diff --git a/.squad/agents/_alumni/kobayashi/history.md b/.squad/agents/_alumni/kobayashi/history.md index 9056d5c8a..05db85c8c 100644 --- a/.squad/agents/_alumni/kobayashi/history.md +++ b/.squad/agents/_alumni/kobayashi/history.md @@ -1,3 +1,5 @@ +πŸ“Œ Team update (2026-03-07T20-04-20Z): GitHub Actions npm publishing automation established. New publish.yml workflow triggers on GitHub Release creation. NPM_TOKEN secret required in repo settings. CI/CD publishing is now authoritative method; local npm publish deprecated. β€” coordinated by Scribe + πŸ“Œ Team update (2026-03-07T16:25:00Z): Actions β†’ CLI migration strategy finalized. 4-agent consensus: migrate 5 squad-specific workflows (12 min/mo) to CLI commands. Keep 9 CI/release workflows (215 min/mo, load-bearing). Zero-risk migration. v0.8.22 quick wins identified: squad labels sync + squad labels enforce. Phased rollout: v0.8.22 (deprecation + CLI) β†’ v0.9.0 (remove workflows) β†’ v0.9.x (opt-in automation). Brady's portability insight captured: CLI-first means Squad runs anywhere (containers, Codespaces). Customer communication strategy: "Zero surprise automation" as competitive differentiator. Decisions merged. β€” coordinated by Scribe # Project Context @@ -87,6 +89,38 @@ npm error This operation requires a one-time password from your authenticator. ⏸️ NPM publish: BLOCKED (awaiting automation token configuration) βœ… Post-publish dev bump: 0.8.22-preview.1 +### Release v0.8.21 β€” Dev β†’ Main Merge & NPM Publish Trigger (Initial Log) + +**RELEASE GATE MERGE EXECUTED.** Dev branch merged to main, publish workflow triggered successfully. + +#### Execution Summary +- **Merge strategy:** Local merge (git checkout main && git merge origin/dev) attempted with --no-edit +- **Conflicts encountered:** 5 files with conflicts during merge (cli-entry.ts, package.json files, test files) +- **Resolution:** Used `git checkout --theirs` strategy to accept dev branch state for all conflicts +- **Push success:** Main branch updated successfully (commit 59b0c7a) +- **Workflow trigger:** `gh workflow run publish.yml --ref main -f version=0.8.21` executed successfully +- **Post-publish:** Version bumped on dev to 0.8.22-preview.1 across all 3 package.json files (commit 9473fa1) + +#### Technical Execution Details +- **Initial blocker:** Stash required due to uncommitted changes (.squad/agents/rabin/history.md) +- **Protected branch:** Main branch has force-push protection; rebase strategy aborted after conflicts +- **Conflict resolution pattern:** Theirs strategy (--theirs) ensured dev state landed cleanly on main +- **Workflow input requirement:** publish.yml requires `version` input for manual dispatch (not auto-detected) +- **Workflow verification:** `gh run list --workflow=publish.yml` confirmed workflow started successfully + +#### Key Learnings +1. **Conflict resolution for release merges:** When merging dev β†’ main for release, use `git checkout --theirs` on all conflicts to ensure dev state is authoritative +2. **Workflow dispatch inputs:** Always check workflow file for required inputs; publish.yml needs explicit version string +3. **Protected branch constraints:** Rebase strategies fail on force-push-protected branches; use merge + conflict resolution +4. **Post-release discipline:** Immediately bump dev to next preview version after triggering publish (prevents version collisions) +5. **Stash management:** Always check for uncommitted changes before release operations; stash + restore after + +#### Release Sequence Validation +βœ… Pre-release version: 0.8.21-preview.X +βœ… Publish version: 0.8.21 (tagged, released) +βœ… Post-publish dev bump: 0.8.22-preview.1 +Release versioning sequence followed correctly. + --- ### 2026-03-05: v0.8.21 Release PR Merge β€” 3 of 4 Successfully Merged (COMPLETE) diff --git a/.squad/agents/eecom/history.md b/.squad/agents/eecom/history.md index 51f9021d5..87425dcc0 100644 --- a/.squad/agents/eecom/history.md +++ b/.squad/agents/eecom/history.md @@ -80,3 +80,7 @@ CLI completeness audit (2026-03-08) confirmed: 26 primary commands routed in cli **PR:** #417 opened targeting dev. +### Adoption Tracking Tier 1 Implementation (2026-03-10) +Implemented Flight's privacy-first adoption monitoring strategy on PR #326 branch. Moved `.squad/adoption/` β†’ `.github/adoption/` for better GitHub integration. Stripped tracking.md to aggregate-only metrics (removed all individual repo names/URLs). Updated GitHub Action workflow (adoption-report.yml) and monitoring script (scripts/adoption-monitor.mjs) to write reports to `.github/adoption/reports/`. Removed "Built with Squad" showcase link from README.md (deferred to Tier 2 opt-in feature). This honors the principle: collect aggregate metrics via public APIs, but never publish individual repo lists without explicit consent. Test discipline: verified npm run build passes; docs-build.test.ts passed structure tests (Astro build failure unrelated to changes). Committed with clear message explaining privacy rationale. + +πŸ“Œ **Team update (2026-03-10T12-55-49Z):** Adoption tracking Tier 1 complete and merged to decisions.md. Privacy-first architecture confirmed: aggregate metrics only, opt-in for individual repos, public showcase only when 5+ projects opt in. Append-only file governance enforced (no deletions in history.md or decisions.md). Microsoft ampersand style guide adopted for documentation. diff --git a/.squad/agents/fido/history.md b/.squad/agents/fido/history.md index 2f7dcd387..a2130102c 100644 --- a/.squad/agents/fido/history.md +++ b/.squad/agents/fido/history.md @@ -29,3 +29,48 @@ cli-packaging-smoke.test.ts validates packaged CLI artifact (npm pack β†’ instal ### CastingEngine Integration Review CastingEngine augments LLM casting with curated names for recognized universes. Unrecognized universes preserve LLM names. Import from `@bradygaster/squad-sdk/casting`, use casting-engine.ts AgentRole type (9 roles). Partial mapping: unmapped roles skip engine casting. +### PR #331 Quality Gate Review β€” NO-GO (Blocking Issues Found) (2026-03-10T14:13:00Z) + +**CRITICAL VIOLATIONS DETECTED:** + +1. **Stale Test Assertions (Hard Rule Violation)** β€” EXPECTED_SCENARIOS array in test/docs-build.test.ts contains only 7 values ['issue-driven-dev', 'existing-repo', 'ci-cd-integration', 'solo-dev', 'monorepo', 'team-of-humans', 'cross-org-auth'], but 25 scenario files exist on disk (aspire-dashboard, client-compatibility, disaster-recovery, keep-my-squad, large-codebase, mid-project, multi-codespace, multiple-squads, new-project, open-source, private-repos, release-process, scaling-workstreams, switching-models, team-portability, team-state-storage, troubleshooting, upgrading, + 7 in array). My charter: "When I add test count assertions, I MUST keep them in sync with the actual files on disk. Stale assertions that block CI are MY responsibility to prevent." This is MY responsibility to catch. + +2. **Missing EXPECTED_FEATURES Array** β€” PR adds 'features' to the sections list in test/docs-build.test.ts (line 46), but NO EXPECTED_FEATURES array exists. Test line 171 "all expected doc pages produce HTML in dist/" will skip features entirely. 32 feature files exist (.md files in docs/src/content/docs/features/). + +πŸ“Œ **Team update (2026-03-11T01:27:57Z):** PR #331 quality gate resolved. FIDO fixed test assertion sync in docs-build.test.ts: EXPECTED_SCENARIOS updated to 25 entries, EXPECTED_FEATURES array created with 32 entries, test assertions updated for features validation. Tests: 6/6 passing. Commit: 6599db6. Blocking NO-GO converted to approval gate cleared. Lesson reinforced: test assertions must be synced to filesystem state; CI passing β‰  coverage. + +3. **Incomplete Test Coverage Sync** β€” PAO's history (line 41) states "Updated EXPECTED_SCENARIOS in docs-build.test.ts to match remaining files" after deleting ralph-operations.md and proactive-communication.md. But the diff shows ONLY a single-line change (adding 'features' to sections array). The full test update was not committed. + +**POSITIVE FINDINGS:** +- βœ… CI passed (test run completed successfully on GitHub) +- βœ… Markdown structure tests pass (6/6 syntax checks) +- βœ… Docs are well-written: sentence-case headings, active voice, present tense, second person +- βœ… Cross-references valid (labels.md link verified) +- βœ… No duplicate "How It Works" heading in reviewer-protocol.md +- βœ… Content intact (no accidental loss) +- βœ… Microsoft Style Guide compliance confirmed + +**ROOT CAUSE:** PAO staged the boundary review changes but the test update commit was incomplete. The assertion arrays must be synchronized before merge. + +**REQUIRED FIX:** Update test/docs-build.test.ts: +1. EXPECTED_SCENARIOS = [ all 25 actual scenario files, sorted ] +2. EXPECTED_FEATURES = [ all 32 actual feature files, sorted ] +3. Regenerate to match disk reality (use filesystem discovery if the project wants test-resilience) + +**VERDICT:** πŸ”΄ **NO-GO** β€” Merge blocked until test assertions sync with disk state. This is a quality gate violation. + +### Test Assertion Sync Fix (2026-03-10T14:20:00Z) + +**Issue resolved:** Fixed stale test assertions in test/docs-build.test.ts identified during PR #331 review. + +**Changes made:** +1. Expanded EXPECTED_SCENARIOS from 7 to 25 entries (matched all .md files in docs/src/content/docs/scenarios/) +2. Added EXPECTED_FEATURES array with 32 entries (matched all .md files in docs/src/content/docs/features/) +3. Updated test logic to include features section in HTML build validation + +**Validation:** All structure validation tests passing (6/6). Build tests skipped as expected (Astro not installed). Arrays now accurately reflect disk state. + +**Commit:** 6599db6 on branch squad/289-squad-dir-explainer + +**Learning:** When test assertions reference file counts, they MUST be kept in sync with disk reality. The principle applies to ALL assertion arrays (EXPECTED_SCENARIOS, EXPECTED_FEATURES, EXPECTED_GUIDES, EXPECTED_REFERENCE, etc.). Consider dynamic discovery pattern (used in EXPECTED_BLOG) for resilience against content additions. + diff --git a/.squad/agents/flight/history.md b/.squad/agents/flight/history.md index cd735f17a..2ded0bf56 100644 --- a/.squad/agents/flight/history.md +++ b/.squad/agents/flight/history.md @@ -25,3 +25,18 @@ Zero code changes. Skill files in templates/skills/, scripts in scripts/mesh/, d ### Sprint Prioritization Pattern Rank by: (1) bugs with active user impact, (2) quality/test gaps blocking GA, (3) high-ROI features unblocking downstream work. Interleave stability (bugs/quality) with velocity (features) across sprint capacity. +**Updated wisdom.md with 4 patterns + 2 anti-patterns from recent work:** Test name-agnosticism for team rebirths, dynamic filesystem discovery for evolving content, cli-entry.ts unwired command bug pattern, bump-build.mjs version mutation timing, invalid semver formats, git reset data loss. + +πŸ“Œ **Team update (2026-03-10T12-55-49Z):** Adoption tracking architecture finalized. Three-tier system approved: Tier 1 (aggregate-only, `.github/adoption/`) shipping with PR #326; Tier 2 (opt-in registry) designed for next PR; Tier 3 (public showcase) launches when β‰₯5 projects opt in. Append-only file governance rule enforced to prevent data loss. Microsoft ampersand style guide adopted for all user-facing documentation. + +### PR #331 Review β€” Boundary Review Pattern Reinforced (2026-03-10) +Approved PR #331 ("docs: scenario and feature guides from blog analysis") for merge. PAO's boundary review (remove external infrastructure docs, reframe platform features to clarify scope, keep Squad behavior/config docs) was executed correctly. Key decisions: (1) ralph-operations.md and proactive-communication.md deleted β€” both document infrastructure around Squad, not Squad itself; (2) issue-templates.md reframed to clarify "GitHub feature configured for Squad" not "Squad feature"; (3) reviewer-protocol.md Trust Levels section kept β€” documents user choice spectrum within Squad's existing review system. Litmus test pattern: if Squad doesn't ship the code/config, it's IRL content. Docs-test sync maintained. Pattern reinforced as reusable boundary review heuristic for future doc PRs. + +**Adoption tracking architecture β€” three-tier opt-in system:** `.squad/` is for team state only, not adoption data (boundary pattern). Move tracking to `.github/adoption/`. Never list individual repos without owner consent β€” aggregate metrics only until opt-in exists. Tier 1 (ship now) = aggregate monitoring. Tier 2 (design next) = opt-in registry in `.github/adoption/registry.json`. Tier 3 (launch later) = public showcase once β‰₯5 projects opt in. Monitoring infra (GitHub Action + script) is solid β€” keep it. Privacy-first architecture: code search results are public data, but individual listings require consent. + +**Remote Squad access β€” three-phase rollout:** Phase 1 (ship first): GitHub Discussions bot with `/squad` command. Workflow checks out repo β†’ has full `.squad/` context β†’ answers questions β†’ posts reply. 1 day build, zero hosting, respects repo privacy automatically. Phase 2 (high value): GitHub Copilot Extension β€” fetches `.squad/` files via GitHub API, answers inline in any Copilot client (VS Code, CLI, mobile). Works truly remote, instant, no cold start. 1 week build. Phase 3 (enterprise): Slack/Teams bot for companies. Webhook + GitHub API fetch. 2 weeks build. Constraint: Squad needs `.squad/` state (team.md, decisions.md, histories, routing) to answer intelligently. Any remote solution must solve context access. GitHub Actions workflows solve this for free (checkout gives full state). Copilot Extension uses Contents API. Discussions wins for MVP because it's async (perfect for knowledge queries), persistent (answers are searchable), and zero infra. Proposal-first: write `docs/proposals/remote-squad-access.md` before building. + +### Content Triage Skill Codified (2026-03-10) +Created `.squad/skills/content-triage/SKILL.md` to codify the boundary heuristic from PR #331. Defines repeatable workflow for triaging external content (blog posts, sample repos, videos, talks) to determine what belongs in Squad's public docs vs IRL tracking. Key components: (1) "Squad Ships It" litmus test β€” if Squad doesn't ship the code/config, it's IRL content; (2) triage workflow triggered by `content-triage` label or external content reference in issue body; (3) output format with boundary analysis, sub-issues for PAO (doc extraction), and IRL reference entry for Scribe; (4) label convention (`content:blog`, `content:sample`, `content:video`, `content:talk`); (5) Ralph integration for routing to Flight, creating sub-issues, and notifying Scribe. Examples include Tamir blog analysis (PR #331), sample repo with ops patterns, and conference talk. Pattern prevents infrastructure docs from polluting Squad's public docs while ensuring community content accelerates adoption through proper extraction and referencing. + +πŸ“Œ **Team update (2026-03-11T01:27:57Z):** Content triage skill finalized; "Squad Ships It" boundary heuristic codified into shared team decision (decisions.md). Remote Squad access phased rollout approved (Discussions bot β†’ Copilot Extension β†’ Chat bot). PR #331 boundary review pattern established as standard for all doc PRs. Triage workflow enables Flight to scale as community content accelerates. diff --git a/.squad/agents/pao/charter.md b/.squad/agents/pao/charter.md index 7fbebacb6..0073c0dfa 100644 --- a/.squad/agents/pao/charter.md +++ b/.squad/agents/pao/charter.md @@ -22,12 +22,18 @@ - Every feature needs a story β€” if you can't explain it, it's not ready - Demos over descriptions β€” show, don't tell - Tone is infrastructure β€” inconsistent voice erodes trust -- **MICROSOFT STYLE GUIDE:** Sentence-case headings, active voice, second person, present tense. -- **DOCS-TEST SYNC:** Update test assertions in docs-build.test.ts in the SAME commit as new docs pages. -- **CONTRIBUTOR RECOGNITION:** Each release includes contributor recognition updates. -- **DOC-IMPACT REVIEW:** Review every PR for documentation impact. +- **MICROSOFT STYLE GUIDE (hard rule):** Follow the [Microsoft Style Guide](https://learn.microsoft.com/style-guide/welcome/) for all documentation β€” sentence-case headings, active voice, second person ("you"), present tense. Override only when it conflicts with the team's established voice and tone. +- **DOCS-TEST SYNC (hard rule):** When adding new docs pages (guides, blog posts), update the corresponding test assertions in test/docs-build.test.ts in the SAME commit. Stale test assertions that block CI are a docs team failure. +- **CONTRIBUTOR RECOGNITION (hard rule):** Each release includes an update to the Contributors Guide page. No contribution goes unappreciated. +- **DOC-IMPACT REVIEW (hard rule):** Review every PR for documentation impact. If a change affects user-facing behavior, ensure corresponding docs are updated or flag the gap. - **CONTENT DISCIPLINE:** One canonical page per concept. Link, don't duplicate. - **DEEP LINKING:** Use most specific anchor available when linking between docs pages. +- **SCANNABILITY REVIEW (hard rule):** All content must use the format that best serves scannability. Apply this framework during review: + - **Paragraphs:** Use for narrative flow, conceptual explanations, "why" context, and transitions. Limit to 3-4 sentences. If longer, consider breaking into sections or converting structured parts to lists/tables. + - **Bullet lists:** Use for features, options, steps (non-sequential), any items users scan for one thing. Start with strong verbs or nouns. Keep items parallel in structure. + - **Tables:** Use for comparisons (feature A vs B), structured reference data (config options, API parameters), or any grid of related attributes. Include headers that describe the relationship. + - **Quotes/indents:** Use for warnings, important callouts, citations, or examples. Reserve for content that needs visual separation. + - **Decision test:** If a reader is hunting for one specific item in a paragraph, convert to bullets or table. If explaining relationships between concepts, keep paragraph. If comparing options, use table. ## Boundaries diff --git a/.squad/agents/pao/history.md b/.squad/agents/pao/history.md index 71cdfefe3..b457949f1 100644 --- a/.squad/agents/pao/history.md +++ b/.squad/agents/pao/history.md @@ -29,3 +29,34 @@ External tool integrations require explicit "where to get it" guidance. Placehol ### Cross-Org Authentication Docs Problem/solution structure for multi-account auth: gh auth switch, Copilot instructions, Squad skill pattern. Cover credential helpers, EMU variations, common error messages. Cross-reference in troubleshooting and enterprise-platforms pages. +### Roster & Contributor Recognition (v0.8.25) +Squad moved to Apollo 13/NASA Mission Control naming scheme (Flight, Procedures, EECOM, FIDO, PAO, CAPCOM, CONTROL, Surgeon, Booster, GNC, Network, RETRO, INCO, GUIDO, Telemetry, VOX, DSKY, Sims, Handbook). CONTRIBUTORS.md tracks both team roster and community contributors; contributor table entries grow with PRs (append PR counts rather than replace, maintaining attribution history). + +### Git Rebase for Doc Merges +When rebasing doc PRs with conflicts from other merged doc PRs, the main branch version (already merged) should generally take priority. For Node.js version references, maintain LTS terminology when present (e.g., `nvm install --lts` over specific version numbers like `nvm install 20`). Conflict resolution pattern: preserve new content from PR branch only where it doesn't duplicate or contradict already-merged changes. Use `git -c core.editor=true rebase --continue` to bypass interactive editor issues on Windows. + +### Astro Docs Format (v0.8.26) +Squad docs use plain markdown without Astro frontmatter. Structure: title (H1), experimental warning callout, "Try this" code blocks at top, overview paragraph, horizontal rule, then content sections with H2 headings. Microsoft Style Guide enforced: sentence-case headings, active voice, second person ("you"), present tense, no ampersands except in code/brand names. Features and scenarios directories added to test coverage in docs-build.test.ts. Reference implementations linked where available (e.g., ralph-watch.ps1 for operational patterns). + +### Proactive Communication Patterns (v0.8.26) +Two-way communication layer between Squad and work environment. Outbound: Teams webhook notifications (breaking, briefings, recaps, flashes) sent via Adaptive Cards β€” only when newsworthy. Inbound: WorkIQ/Playwright scanning of Teams channels and email β†’ auto-create GitHub issues with teams-bridge label, anti-duplicate logic enforced. Loop: inbound creates issues β†’ Ralph dispatches β†’ agents work β†’ outbound notifies results. Human stays informed on mobile. Prerequisites are enhancements, not requirements. + +πŸ“Œ **Team update (2026-03-11T01:27:57Z):** Proactive communication patterns and PR trust levels (full/selective/self-managing spectrum) documented in decisions.md. Pattern rationale reinforced: Ralph 24/7 autonomous deployment requires awareness loop (Teams webhooks for outbound) and external work integration (WorkIQ scanning for inbound). Trust levels enable context-appropriate oversight without bottlenecking teams. + +### PR Trust Model Documentation (v0.8.26) +Three trust levels for PR management: (1) Full review (default, team repos) β€” human gate on every merge; (2) Selective review (personal projects with patterns) β€” human reviews only critical paths; (3) Self-managing (solo personal repos only) β€” Squad merges own PRs, human reviews retroactively. Added to reviewer-protocol.md as new section. Important: self-managing β‰  unmonitored; use Ralph work monitoring and Teams notifications for awareness. Decision matrix included for when to use each level. + +### Final Docs Review Pattern (v0.8.26) +Pre-PR quality reviews check: (1) Microsoft Style Guide compliance (sentence-case headings, active voice, no ampersands, present tense, second person); (2) Tone consistency (practical, developer-focused, no hype); (3) Technical accuracy (code examples, file paths, commands); (4) Cross-reference integrity (valid links between pages); (5) DOCS-TEST SYNC (test assertions match new pages); (6) Privacy directive compliance (no individual repos without consent). Fixed duplicate section heading in reviewer-protocol.md (merge artifact). All staged docs passed review and are ready to commit. + +### Squad vs IRL Boundary Review (v0.8.26) +Evaluated four docs pages from PR #331 (Tamir's blog analysis) against Squad-specificity criterion: does content document Squad features/patterns (belongs in Squad docs) or community implementation examples (belongs in Squad IRL)? Key distinction: Squad docs = "how the feature works + universal best practices" vs IRL = "how one person built an amazing setup." Results: ralph-operations.md borderline (deployment wrappers are external infrastructure, not Squad features β€” trim "outer loop" framing), issue-templates.md borderline (GitHub feature documented for Squad context, not Squad code β€” clarify scope), proactive-communication.md does not belong (community extension pattern using WorkIQ/Playwright, not built into Squad), reviewer-protocol.md trust levels section belongs (documents user choice spectrum within Squad's existing review system). Pattern: if Squad doesn't ship the code, it's IRL content; if it's a GitHub platform feature used alongside Squad, clarify that distinction; if it documents actual Squad behavior/configuration, it belongs. + +### Boundary Review Execution (v0.8.26) +Executed boundary review findings from PR #331: (1) Deleted ralph-operations.md (infrastructure around Squad, not Squad itself β€” moved to IRL); (2) Deleted proactive-communication.md (external tools/webhooks β€” moved to IRL); (3) Reframed issue-templates.md intro to clarify "GitHub feature configured for Squad" not "Squad feature"; (4) Updated EXPECTED_SCENARIOS in docs-build.test.ts to match remaining files. Pattern reinforced: boundary review = remove external infrastructure docs, reframe platform integration docs to clarify whose feature it is, keep Squad behavior/config docs. Changes staged for commit. + +### Cross-Org Authentication Docs (v0.8.26) +Created docs/src/content/docs/scenarios/cross-org-auth.md covering GitHub personal + Enterprise Managed Users (EMU) multi-account auth. Three solutions documented: (1) gh auth switch for manual account toggling; (2) Copilot instructions (.github/copilot-instructions.md) for account mapping documentation; (3) Squad skill pattern for auth error detection and recovery. Covered git credential helpers (per-host and per-org), EMU hostname variations (github.com vs dedicated instances), and common error messages (HTTP 401, authentication required). Added cross-references in troubleshooting.md (new section), enterprise-platforms.md (authentication section), and navigation.ts. Updated test/docs-build.test.ts with 'cross-org-auth' in EXPECTED_SCENARIOS. Pattern: Microsoft Style Guide (sentence-case), "Try this" prompts at top, problem/solution structure, practical examples over abstractions, links to related pages at bottom. + +### Scannability Framework (v0.8.25) +Format selection is a scannability decision, not style preference. Paragraphs for narrative/concepts (3-4 sentences max). Bullets for scannable items (features, options, non-sequential steps). Tables for comparisons or structured reference data (config, API params). Quotes/indents for callouts/warnings. Decision test: if reader hunts for one item in a paragraph, convert to bullets/table. This framework is now a hard rule in charter under SCANNABILITY REVIEW. diff --git a/.squad/decisions.md b/.squad/decisions.md index b4664b9b1..a2b4f2700 100644 --- a/.squad/decisions.md +++ b/.squad/decisions.md @@ -1302,6 +1302,124 @@ Brady's directive (2026-03-03T02:16:00Z): "squad-cli and squad-sdk must NOT be b **Why:** Keep the repo clean. +--- + +## Adoption & Community + +### `.squad/` Directory Scope β€” Owner Directive +**By:** Brady (project owner, PR #326 review) +**Date:** 2026-03-10 + +**Directive:** The `.squad/` directory is **reserved for team state only** β€” roster, routing, decisions, agent histories, casting, and orchestration logs. Non-team data (adoption tracking, community metrics, reports) must NOT live in `.squad/`. Use `.github/` for GitHub platform integration or `docs/` for documentation artifacts. + +**Source:** [PR #326 comment](https://github.com/bradygaster/squad/pull/326#issuecomment-4029193833) + +--- + +### No Individual Repo Listing Without Consent β€” Owner Directive +**By:** Brady (project owner, PR #326 review) +**Date:** 2026-03-10 + +**Directive:** Growth metrics must report **aggregate numbers only** (e.g., "78+ repositories found via GitHub code search") β€” never name or link to individual community repos without explicit opt-in consent. The monitoring script and GitHub Action concepts are approved, but any public showcase or tracking list that identifies specific repos is blocked until a community consent plan exists. + +**Source:** [PR #326 comment](https://github.com/bradygaster/squad/pull/326#issuecomment-4029222967) + +--- + +### Adoption Tracking β€” Opt-In Architecture +**By:** Flight (implementing Brady's directives above) +**Date:** 2026-03-09 + +Privacy-first adoption monitoring using a three-tier system: + +**Tier 1: Aggregate monitoring (SHIPPED)** +- GitHub Action + monitoring script collect metrics +- Reports moved to `.github/adoption/reports/{YYYY-MM-DD}.md` +- Reports show ONLY aggregate numbers (no individual repo names): + - "78+ repositories found via code search" + - Total stars/forks across all discovered repos + - npm weekly downloads + +**Tier 2: Opt-in registry (DESIGN NEXT)** +- Create `SHOWCASE.md` in repo root with submission instructions +- Opted-in projects listed in `.github/adoption/registry.json` +- Monitoring script reads registry, reports only on opted-in repos + +**Tier 3: Public showcase (LAUNCH LATER)** +- `docs/community/built-with-squad.md` shows opted-in projects only +- README link added when β‰₯5 opted-in projects exist + +**Rationale:** +- Aggregate metrics safe (public code search results) +- Individual projects only listed with explicit owner consent +- Prevents surprise listings, respects privacy +- Incremental rollout maintains team capacity + +**Implementation (PR #326):** +- βœ… Moved `.squad/adoption/` β†’ `.github/adoption/` +- βœ… Stripped tracking.md to aggregate-only metrics +- βœ… Removed individual repo names, URLs, metadata +- βœ… Updated adoption-report.yml and scripts/adoption-monitor.mjs +- βœ… Removed "Built with Squad" showcase link from README (Tier 2 feature) + +--- + +### Adoption Tracking Location & Privacy +**By:** EECOM +**Date:** 2026-03-10 + +Implementation decision confirming Tier 1 adoption tracking changes. + +**What:** Move adoption tracking from `.squad/adoption/` to `.github/adoption/` + +**Why:** +1. **GitHub integration:** `.github/adoption/` aligns with GitHub convention (workflows, CODEOWNERS, issue templates) +2. **Privacy-first:** Aggregate metrics only; defer individual repo showcase to Tier 2 (opt-in) +3. **Clear separation:** `.squad/` = team internal; `.github/` = GitHub platform integration +4. **Future-proof:** When Tier 2 opt-in launches, `.github/adoption/` is the natural home + +**Impact:** +- GitHub Action reports write to `.github/adoption/reports/{YYYY-MM-DD}.md` +- No individual repo information published until Tier 2 +- Monitoring continues collecting aggregate metrics via public APIs +- Team sees trends without publishing sensitive adoption data + +--- + +### Append-Only File Governance +**By:** Flight +**Date:** 2026-03-09 + +Feature branches must never modify append-only team state files except to append new content. + +**What:** If a PR diff shows deletions in `.squad/agents/*/history.md` or `.squad/decisions.md`, the PR is blocked until deletions are reverted. + +**Why:** Session state drift causes agents to reset append-only files to stale branch state, destroying team knowledge. PR #326 deleted entire history files and trimmed ~75 lines of decisions, causing data loss. + +**Enforcement:** Code review + future CI check candidate. + +--- + +### Documentation Style: No Ampersands +**By:** PAO +**Date:** 2026-03-09 + +Ampersands (&) are prohibited in user-facing documentation headings and body text, per Microsoft Style Guide. + +**Rule:** Use "and" instead. + +**Why:** Microsoft Style Guide prioritizes clarity and professionalism. Ampersands feel informal and reduce accessibility. + +**Exceptions:** +- Brand names (AT&T, Barnes & Noble) +- UI element names matching exact product text +- Code samples and technical syntax +- Established product naming conventions + +**Scope:** Applies to docs pages, README files, blog posts, community-facing content. Internal files (.squad/** memory files, decision docs, agent history) have flexibility. + +**Reference:** https://learn.microsoft.com/en-us/style-guide/punctuation/ampersands + --- ## Sprint Directives @@ -1311,6 +1429,146 @@ Brady's directive (2026-03-03T02:16:00Z): "squad-cli and squad-sdk must NOT be b **What:** Agents must NEVER write secrets, API keys, tokens, or credentials into conversational history, commit messages, logs, or any persisted file. Acknowledge receipt without echoing values. **Why:** Secrets in logs or history are a security incident waiting to happen. +--- + +## Squad Ecosystem Boundaries & Content Governance + +### Squad Docs vs Squad IRL Boundary (consolidated) +**By:** PAO (via Copilot), Flight +**Date:** 2026-03-10 +**Status:** Active pattern for all documentation PRs + +**Litmus test:** If Squad doesn't ship the code or configuration, the documentation belongs in Squad IRL, not the Squad framework docs. + +**Categories:** + +1. **Squad docs** β€” Features Squad ships (routing, charters, reviewer protocol, config, behavior) +2. **Squad IRL** β€” Infrastructure around Squad (webhooks, deployment patterns, logging, external tools, operational patterns) +3. **Gray area:** Platform features (GitHub Issue Templates) β†’ Squad docs if framed as "how to configure X for Squad" + +**Examples applied (PR #331):** + +| Document | Decision | Reason | +|----------|----------|--------| +| ralph-operations.md | DELETE β†’ IRL | Infrastructure (deployment, logging) around Squad, not Squad itself | +| proactive-communication.md | DELETE β†’ IRL | External tools (Teams, WorkIQ) configured by community, not built into Squad | +| issue-templates.md | KEEP, reframe | GitHub platform feature; clarify scope: "a GitHub feature configured for Squad" | +| reviewer-protocol.md (Trust Levels) | KEEP | Documents user choice spectrum within Squad's existing review system | + +**Enforcement:** Code review + reframe pattern ("GitHub provides X. Here's how to configure it for Squad's needs."). Mark suspicious deletions for restore (append-only governance). + +**Future use:** Apply this pattern to all documentation PRs to maintain clean boundaries. + +--- + +### Content Triage Skill β€” External Content Integration +**By:** Flight +**Date:** 2026-03-10 +**Status:** Skill created at `.squad/skills/content-triage/SKILL.md` + +**Pattern:** External content (blog posts, sample repos, videos, conference talks) that helps Squad adoption must be triaged using the "Squad Ships It" boundary heuristic before incorporation. + +**Workflow:** +1. Triggered by `content-triage` label or external content reference in issue +2. Flight performs boundary analysis +3. Sub-issues generated for Squad-ownable content extraction (PAO responsibility) +4. FIDO verifies docs-test sync on extracted content +5. Scribe manages IRL references in `.github/irl/references.yml` (YAML schema) + +**Label convention:** `content:blog`, `content:sample`, `content:video`, `content:talk` + +**Why:** Pattern from PR #331 (Tamir Dresher blog) shows parallel extraction of Squad-ownable patterns (scenario guides, reviewer protocol) and infrastructure patterns (Ralph ops, proactive comms). Without clear boundary, teams pollute Squad docs with operational content or miss valuable patterns that should be generalized. + +**Impact:** Enables community content to accelerate Squad adoption without polluting core docs. Flight's boundary analysis becomes reusable decision framework. Prevents scope creep as adoption grows. + +--- + +### PR #331 Quality Gate β€” Test Assertion Sync +**By:** FIDO (Quality Owner) +**Date:** 2026-03-10 +**Status:** 🟒 CLEARED (test fix applied, commit 6599db6) + +**What was blocked:** Merge blocked on stale test assertions in `test/docs-build.test.ts`. + +**Critical violations resolved:** +1. `EXPECTED_SCENARIOS` array stale (7 vs 25 disk files) β€” βœ… Updated to 25 entries +2. `EXPECTED_FEATURES` constant undefined (32 feature files) β€” βœ… Created array with 32 entries +3. Test assertion incomplete β€” βœ… Updated to validate features section + +**Why this matters:** Stale assertions that don't reflect filesystem state cause silent test skips. Regression: If someone deletes a scenario file, the test won't catch it. CI passing doesn't guarantee test coverage β€” only that the test didn't crash. + +**Lessons:** +- Test arrays must be refreshed when filesystem content changes +- Incomplete commits break the test-reality sync contract +- FIDO's charter: When adding test count assertions, must keep in sync with disk state + +**Outcome:** Test suite: 6/6 passing. Assertions synced to filesystem. No regression risk from stale assertions. + +--- + +### Communication Patterns and PR Trust Models +**By:** PAO +**Date:** 2026-03-10 +**Status:** Documented in features/reviewer-protocol.md (trust levels section) and scenarios/proactive-communication.md (infrastructure pattern) + +**Decision:** Document emerging patterns in real Squad usage: proactive communication loops and PR review trust spectrum. + +**Components:** + +1. **Proactive communication patterns** β€” Outbound notifications (Teams webhooks), inbound scanning (Teams/email for work items), two-way feedback loop connecting external sources to Squad workflow + +2. **PR trust levels spectrum:** + - **Full review** (default for team repos) β€” All PRs require human review + - **Selective review** (personal projects with patterns) β€” Domain-expert or routine PRs can auto-merge + - **Self-managing** (solo personal repos only) β€” PRs auto-merge; Ralph's work monitoring provides retroactive visibility + +**Why:** Ralph 24/7 autonomous deployment creates an awareness gap β€” how does the human stay informed? Outbound notifications solve visibility. Inbound scanning solves "work lives in multiple places." Trust levels let users tune oversight to their context (full review for team repos, selective for personal projects, self-managing for solo work only). + +**Important caveat:** Self-managing β‰  unmonitored; Ralph's work monitoring and notifications provide retroactive visibility. + +**Anti-spam expectations:** Don't spam yourself outbound (notification fatigue), don't spam GitHub inbound (volume controls). + +--- + +### Remote Squad Access β€” Phased Rollout (Proposed) +**By:** Flight +**Date:** 2026-03-10 +**Status:** Proposed β€” awaits proposal document in `docs/proposals/remote-squad-access.md` + +**Context:** Squad currently requires a local clone to answer questions. Users want remote access from mobile, browser, or different machine without checking out repo. + +**Phases:** + +**Phase 1: GitHub Discussions Bot (Ship First)** +- Surface: GitHub Discussions +- Trigger: `/squad` command or `@squad` mention +- Context: GitHub Actions workflow checks out repo β†’ full `.squad/` state +- Response: Bot replies to thread +- Feasibility: 1 day +- Why first: Easy to build, zero hosting, respects repo privacy, async Q&A, immediately useful + +**Phase 2: GitHub Copilot Extension (High Value)** +- Surface: GitHub Copilot chat (VS Code, CLI, web, mobile) +- Trigger: `/squad ask {question}` in any Copilot client +- Context: Extension fetches `.squad/` files via GitHub API (no clone) +- Response: Answer inline in Copilot +- Feasibility: 1 week +- Why second: Works everywhere Copilot exists, instant response, natural UX + +**Phase 3: Slack/Teams Bot (Enterprise Value)** +- Surface: Slack or Teams channel +- Trigger: `@squad` mention in channel +- Context: Webhook fetches `.squad/` via GitHub API +- Response: Bot replies in thread +- Feasibility: 2 weeks +- Why third: Enterprise teams live in chat; high value for companies using Squad + +**Constraint:** Squad's intelligence lives in `.squad/` (roster, routing, decisions, histories). Any remote solution must solve context access. GitHub Actions workflows provide checkout for free. Copilot Extension and chat bots use GitHub API to fetch files. + +**Implementation:** Before Phase 1 execution, write proposal document. New CLI command: `squad answer --context discussions --question "..."`. New workflow: `.github/workflows/squad-answer.yml`. + +**Privacy:** All approaches respect repo visibility or require authentication. Most teams want private by default. + ### Test assertion discipline β€” mandatory **By:** FIDO (formerly Hockney), v0.8.24 **What:** All code agents must update tests when changing APIs. FIDO has PR blocking authority on quality grounds. @@ -5512,4 +5770,204 @@ The feature page provides practical setup steps and respects the tone ceiling --- +# Skill-Based Orchestration (#255) + +**Date:** 2026-03-07 +**Context:** Issue #255 β€” Decompose squad.agent.md into pluggable skills +**Decision made by:** Verbal (Prompt Engineer) + +## Decision + +Squad coordinator capabilities are now **skill-based** β€” self-contained modules loaded on demand rather than always-inline in squad.agent.md. + +## What Changed + +### 1. SDK Builder Added + +Added `defineSkill()` builder function to the SDK (`packages/squad-sdk/src/builders/`): + +```typescript +export interface SkillDefinition { + readonly name: string; + readonly description: string; + readonly domain: string; + readonly confidence?: 'low' | 'medium' | 'high'; + readonly source?: 'manual' | 'observed' | 'earned' | 'extracted'; + readonly content: string; + readonly tools?: readonly SkillTool[]; +} + +export function defineSkill(config: SkillDefinition): SkillDefinition { ... } +``` + +- **Why:** SDK-First mode needed a typed way to define skills in `squad.config.ts` +- **Type naming:** Exported as `BuilderSkillDefinition` to distinguish from runtime `SkillDefinition` (skill-loader.ts) +- **Validation:** Runtime type guards for all fields, follows existing builder pattern + +### 2. Four Skills Extracted + +Extracted from squad.agent.md: + +1. **init-mode** β€” Phase 1 (propose team) + Phase 2 (create team). ~100 lines. Full casting flow, `ask_user` tool, merge driver setup. +2. **model-selection** β€” 4-layer hierarchy (User Override β†’ Charter β†’ Task-Aware β†’ Default), role-to-model mappings, fallback chains. ~90 lines. +3. **client-compatibility** β€” Platform detection (CLI vs VS Code vs fallback), spawn adaptations, SQL tool caveat. ~60 lines. +4. **reviewer-protocol** β€” Rejection workflow, strict lockout semantics (original author cannot self-revise). ~30 lines. + +All skills marked: +- `confidence: "high"` β€” extracted from authoritative governance file +- `source: "extracted"` β€” marks decomposition from squad.agent.md + +### 3. squad.agent.md Compacted + +Replaced extracted sections with lazy-loading references: + +```markdown +## Init Mode + +**Skill:** Read `.squad/skills/init-mode/SKILL.md` when entering Init Mode. + +**Core rules (always loaded):** +- Phase 1: Propose team β†’ use `ask_user` β†’ STOP and wait +- Phase 2 trigger: User confirms OR user gives task (implicit yes) +- ... +``` + +**Result:** 840 lines β†’ 711 lines (15% reduction, ~130 lines removed) + +### 4. Build Command Updated + +`squad build` now generates `.squad/skills/{name}/SKILL.md` when `config.skills` is defined in `squad.config.ts`: + +```typescript +// In build.ts +function generateSkillFile(skill: BuilderSkillDefinition): string { + // Generates frontmatter + content +} + +// In buildFilePlan() +if (config.skills && config.skills.length > 0) { + for (const skill of config.skills) { + files.push({ + relPath: `.squad/skills/${skill.name}/SKILL.md`, + content: generateSkillFile(skill), + }); + } +} +``` + +## Why This Matters + +### For Coordinators +- **Smaller context window:** squad.agent.md drops from 840 β†’ 711 lines. Further decomposition can continue. +- **On-demand loading:** Coordinator reads skill files only when relevant (e.g., init-mode only during Init Mode). +- **Skill confidence lifecycle:** Framework supports low β†’ medium β†’ high confidence progression for future learned skills. + +### For SDK Users +- **Typed skill definitions:** Define skills in `squad.config.ts` using `defineSkill()`, get validation and type safety. +- **Programmatic skill authoring:** Skills can be composed, shared, and versioned like code. +- **Build-time generation:** `squad build` generates SKILL.md from config β€” single source of truth. + +### For the Team +- **Parallel with ceremony extraction:** Follows the same pattern as ceremony skill files (#193). +- **Reduces merge conflicts:** Smaller squad.agent.md = fewer line-based conflicts when multiple PRs touch governance. +- **Enables skill marketplace:** Future work can package skills as npm modules, share across teams. + +## Constraints + +1. **Existing behavior unchanged:** Skills are lazy-loaded. If coordinator previously got instructions inline, it now gets them from a skill file. Same instructions, different location. +2. **squad.agent.md must still work:** Core rules remain inline. Coordinator knows WHEN to load each skill without needing the skill file first. +3. **Type collision avoided:** BuilderSkillDefinition vs runtime SkillDefinition β€” import from `@bradygaster/squad-sdk/builders` subpath in CLI to avoid ambiguity. + +## Future Work + +- Extract 3+ more skills from squad.agent.md (target: <500 lines for core orchestration) +- Add skill discovery/loading to runtime (currently manual references) +- Skill marketplace: share skills via npm, discover in `squad marketplace` +- Learned skills: agents can write skills from observations (already architected, not yet implemented) + +## References + +- Issue: #255 +- Files changed: + - `packages/squad-sdk/src/builders/types.ts` + - `packages/squad-sdk/src/builders/index.ts` + - `packages/squad-sdk/src/index.ts` + - `packages/squad-cli/src/cli/commands/build.ts` + - `.github/agents/squad.agent.md` + - `.squad/skills/init-mode/SKILL.md` (new) + - `.squad/skills/model-selection/SKILL.md` (new) + - `.squad/skills/client-compatibility/SKILL.md` (new) + - `.squad/skills/reviewer-protocol/SKILL.md` (new) + + + +### 2026-03-07T19-59-58Z: User directive +**By:** bradygaster (via Copilot) +**What:** Prefer GitHub Actions for npm publish over local npm publish. Set up a secret in the GitHub repo and facilitate npm deployment via a CI action instead of running it locally. +**Why:** User request - captured for team memory + + +# npm Publish Automation via GitHub Actions + +**Date:** 2026-03-16 +**Author:** Kobayashi +**Status:** Implemented + +## Context + +Brady requested automated npm publishing via GitHub Actions instead of manual local publishes. Manual publishing is error-prone (version mismatches, forgotten packages, incorrect tags) and lacks audit trail. + +## Decision + +Consolidated npm publishing into single GitHub Actions workflow (`publish.yml`) that triggers automatically on GitHub Release creation. + +## Implementation + +### Workflow Architecture + +**Event Chain:** +1. Code merged to `main` (via squad-promote or direct merge) +2. `squad-release.yml` creates tag + GitHub Release (if version bumped) +3. `publish.yml` triggers on `release.published` event +4. Publishes @bradygaster/squad-sdk β†’ @bradygaster/squad-cli (correct order) + +**Manual Override:** +- Supports `workflow_dispatch` for ad-hoc publishes +- Requires version input (e.g., "0.8.21") + +### Safety Features + +1. **Version verification:** Workflow validates package.json version matches release tag +2. **Publication verification:** Confirms packages visible on npm after publish +3. **Provenance attestation:** npm packages include cryptographic proof of origin +4. **Sequential publish:** SDK publishes first (CLI depends on it) + +### Changes Made + +- Updated `.github/workflows/publish.yml` with new trigger logic +- Deprecated `.github/workflows/squad-publish.yml` (redundant) +- Added version/publication verification steps + +## Requirements + +**NPM_TOKEN Secret:** +Brady must create Automation token at https://www.npmjs.com/settings/{username}/tokens and add to GitHub repo secrets. + +## Implications + +- **Releases:** Automatic npm publish when GitHub Release created (zero manual steps) +- **Audit:** All publishes logged in GitHub Actions (who, when, what version) +- **Security:** Provenance attestation strengthens supply chain trust +- **Error reduction:** Version mismatches caught before publish + +## Rollback Strategy + +- npm allows unpublish within 72 hours of publication +- Manual `npm unpublish @bradygaster/squad-{pkg}@{version}` if issues detected + +## Related Files + +- `.github/workflows/publish.yml` β€” npm publish workflow +- `.github/workflows/squad-release.yml` β€” GitHub Release creation +- `.squad/agents/kobayashi/history.md` β€” Implementation details diff --git a/docs/src/content/docs/concepts/architecture.md b/docs/src/content/docs/concepts/architecture.md new file mode 100644 index 000000000..991891e3b --- /dev/null +++ b/docs/src/content/docs/concepts/architecture.md @@ -0,0 +1,70 @@ +# Architecture + +> ⚠️ **Experimental** β€” Squad is alpha software. APIs, commands, and behavior may change between releases. + +How Squad works β€” one page, no handwaving. + +--- + +## System diagram + +``` +User request + ↓ +Coordinator (routing engine) + ↓ +Spawns agents in parallel + ↓ +Agents read memory (.squad/) β†’ work β†’ write results + ↓ +Scribe merges decisions, Ralph tracks issues + ↓ +Results returned to user +``` + +--- + +## Components + +### Coordinator + +The coordinator is Squad's routing engine. It reads your request, checks routing rules in `.squad/routing.md`, and decides which agents to spawn. If you say "team," it decomposes the work and launches multiple agents in parallel. If you name an agent, it routes directly to them. + +### Agents + +Each agent is a specialist with a charter, role, and persistent memory. Agents are spawned as independent subprocesses with their own context windows and tools. They read `.squad/decisions.md` and their own history before working, then write results back. Agents never see each other's conversations β€” the coordinator orchestrates coordination. + +### Memory (.squad/) + +All team state lives in `.squad/`. This includes the roster (`team.md`), routing rules (`routing.md`), decisions (`decisions.md`), agent charters and histories (`agents/`), and ceremony schedules (`ceremonies.md`). Agents read this before every spawn. You own these files β€” edit them anytime. + +### Routing + +Routing rules in `.squad/routing.md` define which agent handles which work. The coordinator reads these rules before spawning. You can override routing by naming an agent directly in your request. + +### Scribe + +The Scribe is a silent agent that tracks decisions and logs sessions. Every team has a Scribe. You never talk to them directly β€” they work in the background, merging decisions from all agents into `.squad/decisions.md`. + +### Ralph + +Ralph is the work monitor. He watches your GitHub or GitLab issues, tracks work in progress, and alerts the team when something is ready. Every team has a Ralph. He's silent unless you ask him for status. + +--- + +## What happens when you say "Team, build X"? + +1. **Coordinator reads the request** and checks `.squad/routing.md` for decomposition rules. +2. **Coordinator spawns multiple agents in parallel** β€” one for frontend, one for backend, one for tests, etc. +3. **Each agent reads `.squad/decisions.md`** and their own history (`agents/{name}/history.md`), then works independently. +4. **Agents write results** to their history files and propose decisions. +5. **Scribe merges all decisions** into `.squad/decisions.md`. +6. **Coordinator returns labeled results** to you, tagged with each agent's name. + +--- + +## Learn more + +- [**Work routing**](../features/routing) β€” How the coordinator decides which agents to spawn +- [**Memory and knowledge**](memory-and-knowledge) β€” How decisions, skills, and history persist +- [**Parallel work**](parallel-work) β€” How agents work simultaneously without conflicts diff --git a/docs/src/content/docs/concepts/github-workflow.md b/docs/src/content/docs/concepts/github-workflow.md index 1a91df261..968a9419e 100644 --- a/docs/src/content/docs/concepts/github-workflow.md +++ b/docs/src/content/docs/concepts/github-workflow.md @@ -47,6 +47,32 @@ Connect repo β†’ Show backlog β†’ Assign issues β†’ Agent branches + imple --- +## Working with your team + +Squad is built for mixed teams β€” humans set direction, AI agents execute and report back. The Lead agent bridges between them, routing work and surfacing decisions when a human needs to act. + +### Humans in the lifecycle + +The following is **one example** of how a mixed team might divide responsibilities. Your team decides its own process β€” use [ceremonies](../features/ceremonies.md) and [directives](../features/human-team-members.md) to shape the workflow that fits. + +| Stage | Who acts | What happens | +|-------|----------|--------------| +| **Triage** | Human (or Lead) | Applies `go:yes` / `go:no` β€” decides what's worth building | +| **Design review** | Human + team | Auto-triggered ceremony before multi-agent work; humans can participate or observe | +| **Implementation** | AI agents | Branch, build, test, open PRs β€” no human input required | +| **PR review** | Human | Reviews and approves (or requests changes); lockout protocol prevents conflicting edits | +| **Merge** | Human or Ralph | Squash-merge, branch cleanup, issue closed | + +This is a starting point. Define your own checkpoints by configuring [ceremonies](../features/ceremonies.md) and capturing [directives](../features/human-team-members.md). + +For details on how work routes to humans, see [Human team members](../features/human-team-members.md). + +For ceremony details, see [Ceremonies](../features/ceremonies.md). + +For agent anatomy and how each team member (AI, human, @copilot) is structured, see [your-team.md](your-team.md). + +--- + ## Label Taxonomy Labels aren't just tags β€” they're Squad's **state machine**. Five namespaces drive workflow automation, routing, and lifecycle tracking. diff --git a/docs/src/content/docs/concepts/your-team.md b/docs/src/content/docs/concepts/your-team.md index 63d0d18ad..64d586d13 100644 --- a/docs/src/content/docs/concepts/your-team.md +++ b/docs/src/content/docs/concepts/your-team.md @@ -214,18 +214,84 @@ Squad auto-selects the right level of effort for each request: | `"Remove McManus from the team"` | Archives agent directory to `.squad/agents/.archived/`, updates team.md | | `"Change the tester to focus on integration tests"` | Updates the tester's charter and expertise | | `"Route all CSS files to Frontend"` | Adds a rule to `.squad/routing.md` | -| `"From now on, McManus reviews all docs before merge"` | Creates routing rule + [directive](memory-and-knowledge.md) | +| `"From now on, McManus reviews all docs before merge"` | Creates routing rule + [directive](../features/memory.md) | Running `init` on an existing Squad repo automatically offers upgrade mode. --- +## Planning your team + +Before running `squad init`, think through these decisions. Squad will scan your repo and propose a team β€” having answers ready makes setup faster. + +- **What does your project do?** Have a 1–2 sentence description of the language, stack, and purpose ready β€” Squad uses this to pick roles +- **What roles do you need?** The [default composition](#default-team-composition) covers common cases, or let Squad propose custom roles based on your repo +- **How many agents?** Typical teams are 3–7 agents. Scribe (memory) is always included +- **Will humans join the team?** [Human members](#human-team-members) can serve as reviewers or domain experts alongside AI agents +- **Will @copilot participate?** The GitHub Copilot coding agent can pick up issues autonomously β€” see [Agent anatomy](#agent-anatomy) +- **How will you track work?** GitHub Issues with `squad:{member}` labels, or conversational tasking via named prompts +- **Do you want review gates?** [Reviewers](#reviewer-protocol) can approve or reject work before it proceeds +- **What ceremonies matter?** [Design reviews and retrospectives](#ceremonies) can auto-trigger or run on demand +- **What model preferences?** Default is automatic selection, or specify preferred models per agent β€” see [Parallel Work & Models](parallel-work.md) +- **How many squads, and where do they live?** One squad per repo is the default β€” your `.squad/` directory lives alongside your code. For multi-repo projects, you can run one squad per repo (each with its own team) or share a single squad across repos using a personal squad or linked team repo. Start with one squad in one repo and expand as needed. + +--- + +## Agent anatomy + +An agent is a directory at `.squad/agents/{name}/`. The contents depend on the member type. + +For how humans differ from AI agents, see [Human team members](#human-team-members) above. + +| | @copilot (πŸ€–) | +|---|---| +| Directory | None | +| `charter.md` | ❌ Uses `copilot-instructions.md` | +| `history.md` | ❌ | +| Spawnable | ❌ Works via issue assignment | + +**AI agents** have a `charter.md` (identity, expertise, voice β€” compiled into the system prompt at spawn time) and an optional `history.md` (append-only cross-session learnings). + +**@copilot** (πŸ€–) appears on the roster and works via GitHub issue assignment. It reads `.github/copilot-instructions.md` instead of a charter. + +**Retired agents** move to `.squad/agents/_alumni/{name}/` β€” charter preserved as a read-only archive, not spawnable. + +--- + +## Cross-agent context + +Agents don't share memory directly. Context flows through explicit shared files: + +- **`team.md`** β€” who's on the team and what they do +- **`routing.md`** β€” work assignment rules the coordinator reads on every request +- **`decisions.md`** β€” canonical team memory: directives, patterns, learnings +- **`.squad/decisions/inbox/`** β€” agents drop decision files here; the Scribe merges them into `decisions.md` + +Each agent's `history.md` is personal β€” only that agent reads it at spawn time. For the full picture on knowledge flow, see [Memory and knowledge](../features/memory.md). + +--- + +## Hiring an agent + +To add a new AI agent to your team: + +- [ ] Create `.squad/agents/{name}/` directory +- [ ] Write `charter.md` β€” start from `.squad/templates/charter.md` +- [ ] Add to `team.md` roster with status `βœ… Active` +- [ ] Add to `routing.md` with work type assignments +- [ ] (Optional) Create `history.md` for persistent memory +- [ ] (Optional) Allocate a name via the casting system + +To add a **human member**, skip the directory β€” just add them to `team.md`. See [Human team members](#human-team-members) for badge and routing details. + +--- + ## Tips - **Commit `.squad/`** to version control β€” anyone who clones the repo gets the full team with all accumulated knowledge. - Use human members for approval gates: design review, compliance, final sign-off. - Design reviews prevent agents from building conflicting implementations β€” let them run on multi-agent tasks. -- Retros produce [decisions](memory-and-knowledge.md) that improve future work, not just diagnose the current failure. +- Retros produce [decisions](../features/memory.md) that improve future work, not just diagnose the current failure. - You're the relay for human members. Squad can't message them directly β€” it tells you, and you coordinate. --- diff --git a/docs/src/content/docs/features/enterprise-platforms.md b/docs/src/content/docs/features/enterprise-platforms.md index a842b4dfd..a77cd219d 100644 --- a/docs/src/content/docs/features/enterprise-platforms.md +++ b/docs/src/content/docs/features/enterprise-platforms.md @@ -102,6 +102,8 @@ All fields are optional. Omitted fields use the defaults shown above. Squad uses the Azure CLI for ADO authentication β€” **no Personal Access Tokens (PATs) needed.** Run `az login` once, and Squad agents use your authenticated session for all operations. +For GitHub repositories, Squad uses the `gh` CLI for authentication. When working across multiple GitHub accounts (e.g., personal GitHub and Enterprise Managed Users), use `gh auth switch` to toggle between accounts. See [Cross-organization authentication](../scenarios/cross-org-auth) for detailed multi-account setup. + Alternatively, if the Azure DevOps MCP server is configured in your environment, Squad will use it automatically for richer API access. See [MCP Setup Guide](./mcp.md#mcp-configuration-files) for configuration instructions. Squad prefers MCP tools when available, falling back to `az` CLI when not. diff --git a/docs/src/content/docs/get-started/choosing-your-path.md b/docs/src/content/docs/get-started/choosing-your-path.md new file mode 100644 index 000000000..16eacec5e --- /dev/null +++ b/docs/src/content/docs/get-started/choosing-your-path.md @@ -0,0 +1,82 @@ +# Choose your path + +> ⚠️ **Experimental** β€” Squad is alpha software. APIs, commands, and behavior may change between releases. + +CLI, Copilot agent, or SDK? Pick the right mode for your workflow. + +--- + +## Three modes + +### CLI mode + +Install Squad globally or per-project, then use terminal commands to initialize, route work, and manage your team. + +```bash +npm install -g @bradygaster/squad-cli +squad init +squad status +squad watch +``` + +**Use for:** Terminal workflows, automation scripts, CI/CD integration. + +--- + +### Copilot agent mode + +Talk to Squad in GitHub Copilot CLI or VS Code. Squad is built-in as an agent. Your `.squad/` directory works identically to CLI mode. + +```bash +copilot +> /agent Squad + +Squad: Hey Brady, what are you building? +``` + +**Use for:** Conversational workflows, exploratory work, VS Code users. + +--- + +### SDK mode + +Write TypeScript code that spawns agents, routes work, and coordinates teams programmatically. Full access to Squad's internals. + +```bash +npm install @bradygaster/squad-sdk +``` + +```typescript +import { Coordinator } from '@bradygaster/squad-sdk'; + +const coordinator = new Coordinator(); +const result = await coordinator.route('Build a login page'); +``` + +**Use for:** Building tools on Squad, custom integrations, advanced automation. + +--- + +## Decision table + +| **Your goal** | **Use** | +|---------------|---------| +| Try Squad quickly | **Copilot agent** β€” no install | +| Work in the terminal | **CLI** | +| Work in VS Code | **Copilot agent** | +| Automate repetitive tasks | **CLI** or **SDK** | +| Build custom tooling | **SDK** | +| CI/CD integration | **CLI** or **SDK** | + +--- + +## Can I use multiple modes? + +Yes. Your `.squad/` directory is the source of truth. CLI, Copilot agent, and SDK all read and write the same files. You can switch between modes anytime. + +Example workflow: +1. Use **Copilot agent** to form your team and do exploratory work +2. Use **CLI** (`squad watch`) to monitor issues in the background +3. Use **SDK** to build a custom deployment script that spawns agents + +All three modes share the same memory and decisions. diff --git a/docs/src/content/docs/get-started/first-session.md b/docs/src/content/docs/get-started/first-session.md index 030e70479..6c62bbebc 100644 --- a/docs/src/content/docs/get-started/first-session.md +++ b/docs/src/content/docs/get-started/first-session.md @@ -48,7 +48,7 @@ Start the Copilot CLI: copilot ``` -Select **Squad** from the `/agent` list (CLI) or `/agents` (VS Code). Squad greets you by name (pulled from `git config user.name`): +Select **Squad** from the `/agent` list (CLI) or `/agents` (VS Code). Squad greets you by name: ``` Hey Brady, what are you building? @@ -61,7 +61,7 @@ Describe your project: > post recipes, search by ingredient, and save favorites. ``` -Squad proposes a team. Names come from a fictional universe β€” the exact universe depends on your project shape and history: +Squad proposes a team. The coordinator analyzes your description and suggests specialists: ``` Here's your team: @@ -72,6 +72,8 @@ Here's your team: πŸ§ͺ Lambert β€” Tester Tests, quality, edge cases πŸ“‹ Scribe β€” (silent) Memory, decisions, session logs +**Scribe** and **Ralph** are always on every roster β€” you don't manage them. + Look right? Say yes, add someone, or change a role. (Or just give me a task to start!) ``` @@ -86,7 +88,7 @@ Say "yes" or skip straight to a task (which is implicit confirmation): > Yes. Dallas, set up the Express server with basic routing. ``` -Squad creates the `.squad/` directory structure β€” team roster, routing rules, casting state, ceremony config, agent charters, and histories β€” all seeded with your project context. +Squad creates the `.squad/` directory structure β€” team roster, routing rules, casting state, ceremony config, agent charters, and histories β€” all seeded with your project context. Each agent spawns to do their work. ### What's inside .squad/? @@ -177,7 +179,7 @@ At any point, check status: > Where are we? ``` -This is a Direct mode response β€” no agent spawn, just the coordinator reading recent logs: +The coordinator reads recent logs: ``` Last session: Recipe listing page (15 minutes ago) @@ -274,7 +276,7 @@ squad export 5 agents, 3 skills, 6 decisions ``` -This snapshot contains everything β€” charters, histories, casting state, skills, and decisions. Import into another repo anytime: +This snapshot contains charters, histories, casting state, skills, and decisions. Import into another repo anytime: ```bash cd ../other-project @@ -286,8 +288,8 @@ squad import ../my-app/squad-export.json ## Tips -- **First session is the slowest.** Agents have no history yet. After 2–3 sessions, they know your conventions and stop asking repeated questions. -- **Commit `.squad/`.** It's your team's brain. Anyone who clones the repo gets the team with all their knowledge. +- **First session is slowest.** Agents have no history yet. After 2–3 sessions, they know your conventions. +- **Commit `.squad/`** β€” your team's brain. Anyone who clones the repo gets the full team. - **Say "team" for big tasks.** The word "team" triggers parallel fan-out across multiple agents. - **Name an agent for focused work.** `"Dallas, fix the login bug"` sends work to one specific agent. - **Directives are sticky.** Once captured, they persist across all future sessions. diff --git a/docs/src/content/docs/get-started/five-minute-start.md b/docs/src/content/docs/get-started/five-minute-start.md new file mode 100644 index 000000000..29667ea95 --- /dev/null +++ b/docs/src/content/docs/get-started/five-minute-start.md @@ -0,0 +1,87 @@ +# Quick start + +> ⚠️ **Experimental** β€” Squad is alpha software. APIs, commands, and behavior may change between releases. + +Your first 5 minutes with Squad. Prove it works before you learn anything. + +--- + +## Prerequisites + +- **Node.js 20+** β€” Check with `node --version` +- **Git repository** β€” New or existing + +--- + +## Install + +```bash +npm install --save-dev @bradygaster/squad-cli +``` + +Then initialize: + +```bash +npx squad init +``` + +You'll see: + +``` +βœ… Squad installed. + .github/agents/squad.agent.md β€” coordinator agent + .squad/templates/ β€” 11 template files + +Open GitHub Copilot and select Squad from the agent list. +``` + +--- + +## Validate + +Check that Squad created your team directory: + +```bash +ls .squad/ +``` + +You should see: `team.md`, `routing.md`, `decisions.md`, `agents/`, and more. + +Confirm Squad is ready: + +```bash +npx squad status +``` + +--- + +## Try it + +Open GitHub Copilot in your terminal or VS Code. Select **Squad** from the agent list (`/agent Squad` in CLI or `/agents` in VS Code). + +Say something simple: + +``` +> I'm building a task management app with React and Node.js. +> Users can create, update, and delete tasks. +``` + +Squad forms your team and responds with agent names and roles. Say yes, or just give your first task: + +``` +> Team, create a basic Express server with a /health endpoint. +``` + +Squad spawns agents and does the work. + +--- + +## What just happened? + +Squad read your description, formed a team of specialists, wrote their charters to `.squad/agents/`, and coordinated parallel work. Check `.squad/decisions.md` to see what they decided. + +--- + +## Next steps + +[**Your first session**](first-session) β€” Step-by-step walkthrough of parallel work, decisions, and memory. diff --git a/docs/src/content/docs/get-started/installation.md b/docs/src/content/docs/get-started/installation.md index 8747014d3..807ec8b03 100644 --- a/docs/src/content/docs/get-started/installation.md +++ b/docs/src/content/docs/get-started/installation.md @@ -114,7 +114,15 @@ Want the same agents across all your projects? squad init --global ``` -This creates `~/.squad/` β€” a personal team root that any project can inherit from. See [Upstream Inheritance](../features/upstream-inheritance.md) for details. +This creates your personal squad directory β€” a personal team root that any project can inherit from. See [Upstream Inheritance](../features/upstream-inheritance.md) for details. + +**Personal squad location by platform:** + +| Platform | Path | +|----------|------| +| Linux | `~/.config/squad/` | +| macOS | `~/Library/Application Support/squad/` | +| Windows | `%APPDATA%\squad\` | --- diff --git a/docs/src/content/docs/guide/personal-squad.md b/docs/src/content/docs/guide/personal-squad.md index 92d7adec3..36f4e1676 100644 --- a/docs/src/content/docs/guide/personal-squad.md +++ b/docs/src/content/docs/guide/personal-squad.md @@ -18,7 +18,15 @@ This tutorial walks you through setup, explains what's happening behind the scen Normally, Squad lives inside a single project β€” `.squad/` in your repo root. Your agents know that project. They don't know your other ones. -A personal squad flips that. Your team identity β€” agents, charters, skills, casting history β€” moves to a global directory (`~/.squad/`). Every project you work in can point to it. +A personal squad flips that. Your team identity β€” agents, charters, skills, casting history β€” moves to your personal squad directory. Every project you work in can point to it. + +**Personal squad location by platform:** + +| Platform | Path | +|----------|------| +| Linux | `~/.config/squad/` | +| macOS | `~/Library/Application Support/squad/` | +| Windows | `%APPDATA%\squad\` | What that means in practice: @@ -51,7 +59,7 @@ You'll see: ``` βœ… Personal squad initialized. - ~/.squad/ β€” your global team root + {personal squad directory} β€” your global team root Agents, skills, and casting will be shared across projects. ``` @@ -65,7 +73,7 @@ squad status ``` Squad Status - Global squad: ~/.squad/ + Global squad: {personal squad directory} Agents: 0 (none cast yet β€” start a session to form your team) Skills: 0 ``` @@ -85,7 +93,7 @@ Squad detects your global team root and writes a pointer: ``` βœ… Squad initialized. - .squad/config.json β†’ teamRoot: ~/.squad/ + .squad/config.json β†’ teamRoot: {personal squad directory} Team identity inherited from personal squad. Project-local state (decisions, logs) stays here. ``` @@ -100,12 +108,12 @@ Repeat for any project you want connected. Two things were created. Understanding the split is the key to personal squads. -### The global directory: `~/.squad/` +### The global directory: your personal squad This is your **team identity**. It contains: ``` -~/.squad/ +{personal squad directory}/ agents/ β€” your agent charters and histories casting/ β€” who's been cast, role assignments skills/ β€” accumulated knowledge ("always use Zod", "prefer Tailwind") @@ -120,7 +128,7 @@ Inside each connected project, `.squad/config.json` looks like this: ```json { "version": 1, - "teamRoot": "~/.squad/", + "teamRoot": "{personal squad directory}", "projectKey": null } ``` @@ -129,14 +137,14 @@ That `teamRoot` field is the magic. When Squad's resolution system sees it, the | | **Local mode** (default) | **Remote mode** (personal squad) | |---|---|---| -| Team identity | `.squad/` in project | `~/.squad/` (global) | +| Team identity | `.squad/` in project | Personal squad directory (global) | | Decisions & logs | `.squad/` in project | `.squad/` in project | | Agents shared? | No β€” project only | Yes β€” across all connected projects | | Skills shared? | No | Yes | In remote mode: -- **Team identity** (agents, charters, skills, casting) β†’ loaded from `~/.squad/` +- **Team identity** (agents, charters, skills, casting) β†’ loaded from your personal squad directory - **Project-local state** (decisions, logs, orchestration-log) β†’ stays in this project's `.squad/` The resolution system walks up directories looking for `.squad/`. When it finds one with a `teamRoot` in `config.json`, it switches to remote mode β€” pulling team identity from the external path while keeping project state local. @@ -251,7 +259,7 @@ Set a directive once: πŸ“Œ Captured. Linting required before task completion. ``` -That directive is now in `~/.squad/` β€” every project, every session. Your agents enforce it everywhere. You set the standard once and it sticks. +That directive is now in your personal squad directory β€” every project, every session. Your agents enforce it everywhere. You set the standard once and it sticks. Over time, your personal squad becomes an opinionated workflow engine. Not because you configured it that way β€” because you worked with it and it learned. @@ -259,12 +267,12 @@ Over time, your personal squad becomes an opinionated workflow engine. Not becau ## 8. Use Case: Skills That Grow Everywhere -Skills accumulate in `~/.squad/skills/`. Every project contributes. +Skills accumulate in your personal squad directory under `skills/`. Every project contributes. After a few weeks: ``` -~/.squad/skills/ +{personal squad directory}/skills/ always-use-zod.md prefer-tailwind.md cursor-pagination.md @@ -292,7 +300,7 @@ What works well today: - **Consult mode** β€” bring your team to projects you don't own, invisibly ([docs](../features/consult-mode.md)) What's still rough: -- No sync mechanism between machines yet β€” `~/.squad/` is local to your machine +- No sync mechanism between machines yet β€” your personal squad directory is local to your machine - Project keys aren't used for anything yet (that `null` in config.json) - No UI for browsing your global skills or agent histories (it's files for now) @@ -303,10 +311,10 @@ We're building in the open. If something feels off, [open an issue](https://gith ## Tips - **Start with one project.** Get comfortable with the personal squad on one repo before connecting others. The value compounds, but so does confusion if something's misconfigured. -- **Commit project `.squad/` but not global `~/.squad/`.** The project-local state (decisions, logs) belongs in version control. Your global identity is personal β€” keep it out of repos. +- **Commit project `.squad/` but not personal squad directory.** The project-local state (decisions, logs) belongs in version control. Your global identity is personal β€” keep it out of repos. - **Check status anytime.** `squad status` shows your global squad directory and which projects are connected. - **Skills are the payoff.** The more projects you work across, the more skills accumulate. After a month, your agents have a real knowledge base tailored to how *you* build software. -- **It's just files.** `~/.squad/` is a directory on your machine. You can browse it, edit it, back it up, copy it to another machine manually. No magic, no cloud, no lock-in. +- **It's just files.** Your personal squad directory is a folder on your machine. You can browse it, edit it, back it up, copy it to another machine manually. No magic, no cloud, no lock-in. - **Global install matters.** `npm install -g @bradygaster/squad-cli` gives you the `squad` command everywhere. Without it, you'd need `npx` in each project. Global CLI + global squad = full portability. --- diff --git a/docs/src/content/docs/reference/api-reference.md b/docs/src/content/docs/reference/api-reference.md index 5815e8764..5e82a47fa 100644 --- a/docs/src/content/docs/reference/api-reference.md +++ b/docs/src/content/docs/reference/api-reference.md @@ -51,7 +51,7 @@ const squadPath = resolveSquad('/home/user/project/src'); ### `resolveGlobalSquadPath(): string` -Get path to global personal squad (`~/.squad/` on Unix, `%USERPROFILE%\.squad\` on Windows). +Get path to global personal squad. Returns platform-specific path: `~/.config/squad/` on Linux, `~/Library/Application Support/squad/` on macOS, `%APPDATA%\squad\` on Windows. ### `ensureSquadPath(startPath?: string): string` diff --git a/docs/src/content/docs/reference/cli.md b/docs/src/content/docs/reference/cli.md index 0add97f50..6fb836af1 100644 --- a/docs/src/content/docs/reference/cli.md +++ b/docs/src/content/docs/reference/cli.md @@ -28,7 +28,7 @@ squad init |---------|-------------|:------------------:| | `squad` | Enter interactive shell (no args) | No | | `squad init` | Initialize Squad in the current repo (idempotent β€” safe to run multiple times) | No | -| `squad init --global` | Create a personal squad at `~/.squad/` | No | +| `squad init --global` | Create a personal squad in your platform-specific directory | No | | `squad init --mode remote ` | Initialize linked to a remote team root (dual-root mode) | No | | `squad start [--tunnel] [--port N] [--command cmd]` | Start Copilot with remote phone access via PTY and WebSocket | No | | `squad status` | Show which squad is active and why | Yes | @@ -239,7 +239,7 @@ When Squad starts, it looks for `.squad/` in this order: 1. Current directory (`./.squad/`) 2. Parent directories (walk up to project root) -3. Home directory (`~/.squad/`) +3. Personal squad directory (platform-specific: `~/.config/squad/` on Linux, `~/Library/Application Support/squad/` on macOS, `%APPDATA%\squad\` on Windows) 4. Global CLI default (fallback only) First match wins. diff --git a/docs/src/content/docs/reference/config.md b/docs/src/content/docs/reference/config.md index 359c1d250..0b6ffc1ea 100644 --- a/docs/src/content/docs/reference/config.md +++ b/docs/src/content/docs/reference/config.md @@ -145,7 +145,7 @@ Squad finds `.squad/` by walking up: 1. Current directory (`./.squad/`) 2. Parent directories (up to project root) -3. Home directory (`~/.squad/`) +3. Personal squad directory (platform-specific: `~/.config/squad/` on Linux, `~/Library/Application Support/squad/` on macOS, `%APPDATA%\squad\` on Windows) 4. Global CLI default (fallback) First match wins. diff --git a/docs/src/content/docs/reference/glossary.md b/docs/src/content/docs/reference/glossary.md new file mode 100644 index 000000000..7a5ef32f9 --- /dev/null +++ b/docs/src/content/docs/reference/glossary.md @@ -0,0 +1,39 @@ +# Glossary + +> ⚠️ **Experimental** β€” Squad is alpha software. APIs, commands, and behavior may change between releases. + +Key terms defined in one sentence each. Alphabetical order. + +--- + +**Agent** β€” A specialist AI team member with a role, charter, and persistent memory that handles specific types of work. + +**Casting** β€” The process of forming your team by proposing agents, confirming roles, and writing their charters to `.squad/`. + +**Ceremony** β€” A scheduled team event like retrospectives, reviews, or planning sessions defined in `.squad/ceremonies.md`. + +**Coordinator** β€” Squad's routing engine that reads your request, checks routing rules, and spawns the right agents. + +**Decisions** β€” Architectural choices, conventions, and directives captured in `.squad/decisions.md` that all agents read before working. + +**Directive** β€” A persistent rule or convention you give the team (like "Always use Zod for validation") that gets written to `decisions.md`. + +**History** β€” Each agent's memory of past work, stored in `.squad/agents/{name}/history.md` and read before every spawn. + +**Memory** β€” All persistent team state stored in the `.squad/` directory, including roster, routing rules, decisions, and agent histories. + +**Ralph** β€” The silent work monitor agent that watches your GitHub or GitLab issues and tracks work in progress. + +**Routing** β€” Rules in `.squad/routing.md` that define which agent handles which type of work, read by the coordinator before spawning. + +**Scribe** β€” The silent agent that tracks decisions and logs sessions, merging proposals from all agents into `.squad/decisions.md`. + +**Skill** β€” A reusable capability stored in `.squad/skills/` that agents can learn and execute. + +**Spawn** β€” The act of starting an agent as an independent subprocess with its own context window, tools, and memory. + +**Squad** β€” Your AI development team, coordinated through the Squad framework. + +**.squad/ directory** β€” The root directory containing all team state: roster, routing, decisions, agent charters and histories, and ceremony config. + +**Team** β€” The collection of agents working on your project, defined in `.squad/team.md`. diff --git a/docs/src/content/docs/reference/sdk.md b/docs/src/content/docs/reference/sdk.md index bff98e66c..a45744c9c 100644 --- a/docs/src/content/docs/reference/sdk.md +++ b/docs/src/content/docs/reference/sdk.md @@ -24,12 +24,12 @@ Find `.squad/` directories on disk. | Function | Description | |----------|-------------| | `resolveSquad(startPath?)` | Find `.squad/` walking up from `startPath` (throws if not found) | -| `resolveGlobalSquadPath()` | Get `~/.squad/` path (`%USERPROFILE%\.squad\` on Windows) | +| `resolveGlobalSquadPath()` | Get personal squad directory path (platform-specific) | | `ensureSquadPath(startPath?)` | Like `resolveSquad`, but creates `.squad/` if missing | ```typescript const squadPath = resolveSquad(); // '/home/user/project/.squad' -const globalPath = resolveGlobalSquadPath(); // '/home/user/.squad' +const globalPath = resolveGlobalSquadPath(); // Platform-specific: ~/.config/squad/ (Linux), ~/Library/Application Support/squad/ (macOS), %APPDATA%\squad\ (Windows) const safePath = ensureSquadPath(); // Creates if needed ``` diff --git a/docs/src/content/docs/scenarios/troubleshooting.md b/docs/src/content/docs/scenarios/troubleshooting.md index 0226a3d1e..36fae207f 100644 --- a/docs/src/content/docs/scenarios/troubleshooting.md +++ b/docs/src/content/docs/scenarios/troubleshooting.md @@ -4,6 +4,18 @@ Common issues and fixes for Squad installation and usage. --- +## Quick fixes + +| Error | Cause | Fix | +|-------|-------|-----| +| `squad: command not found` | Squad CLI not installed or not in PATH | Run `npm install -g @bradygaster/squad-cli` or use `npx @bradygaster/squad-cli` | +| `No .squad/ directory found` | Not in a git repo or Squad not initialized | Run `git init` then `npx squad init` | +| `Cannot find agent "{name}"` | Agent doesn't exist in `.squad/agents/` | Check `.squad/team.md` for roster, or re-run casting | +| `gh: command not found` | GitHub CLI not installed | Install from [cli.github.com](https://cli.github.com/) then `gh auth login` | +| `Node.js version error` | Node.js version below v20 | Upgrade Node.js to v20+ (see below) | + +--- + ## `npx github:bradygaster/squad` appears to hang **Problem:** Running the install command shows a frozen npm spinner. Nothing happens. diff --git a/docs/src/navigation.ts b/docs/src/navigation.ts index 9534814b5..64dd7a034 100644 --- a/docs/src/navigation.ts +++ b/docs/src/navigation.ts @@ -14,7 +14,9 @@ export const NAV_SECTIONS: NavSection[] = [ title: 'Get Started', dir: 'get-started', items: [ + { title: 'Quick start', slug: 'get-started/five-minute-start' }, { title: 'Installation', slug: 'get-started/installation' }, + { title: 'Choose your path', slug: 'get-started/choosing-your-path' }, { title: 'Your First Session', slug: 'get-started/first-session' }, { title: 'Migration Guide', slug: 'get-started/migration' }, ], @@ -79,6 +81,7 @@ export const NAV_SECTIONS: NavSection[] = [ { title: 'SDK Integration', slug: 'reference/integration' }, { title: 'Tools & Hooks', slug: 'reference/tools-and-hooks' }, { title: 'Config', slug: 'reference/config' }, + { title: 'Glossary', slug: 'reference/glossary' }, ], }, { @@ -100,6 +103,7 @@ export const NAV_SECTIONS: NavSection[] = [ { title: 'Upgrading', slug: 'scenarios/upgrading' }, { title: 'Multi-Codespace', slug: 'scenarios/multi-codespace' }, { title: 'Private Repos', slug: 'scenarios/private-repos' }, + { title: 'Cross-Org Auth', slug: 'scenarios/cross-org-auth' }, { title: 'Team Portability', slug: 'scenarios/team-portability' }, { title: 'Team State Storage', slug: 'scenarios/team-state-storage' }, { title: 'Switching Models', slug: 'scenarios/switching-models' }, @@ -116,6 +120,7 @@ export const NAV_SECTIONS: NavSection[] = [ title: 'Concepts', dir: 'concepts', items: [ + { title: 'Architecture', slug: 'concepts/architecture' }, { title: 'Your Team', slug: 'concepts/your-team' }, { title: 'Memory & Knowledge', slug: 'concepts/memory-and-knowledge' }, { title: 'Parallel Work', slug: 'concepts/parallel-work' }, diff --git a/images/001.png b/images/001.png deleted file mode 100644 index de79d58a3..000000000 Binary files a/images/001.png and /dev/null differ diff --git a/images/002.png b/images/002.png deleted file mode 100644 index 77e5b4440..000000000 Binary files a/images/002.png and /dev/null differ diff --git a/images/003.png b/images/003.png deleted file mode 100644 index 23c91c37a..000000000 Binary files a/images/003.png and /dev/null differ diff --git a/images/004.png b/images/004.png deleted file mode 100644 index c2a51ff49..000000000 Binary files a/images/004.png and /dev/null differ diff --git a/images/005.png b/images/005.png deleted file mode 100644 index 86e1312da..000000000 Binary files a/images/005.png and /dev/null differ diff --git a/images/006.png b/images/006.png deleted file mode 100644 index 9393cef35..000000000 Binary files a/images/006.png and /dev/null differ diff --git a/images/007.png b/images/007.png deleted file mode 100644 index bed6cdc18..000000000 Binary files a/images/007.png and /dev/null differ diff --git a/images/008.png b/images/008.png deleted file mode 100644 index 36071d520..000000000 Binary files a/images/008.png and /dev/null differ diff --git a/images/009.png b/images/009.png deleted file mode 100644 index da36a743d..000000000 Binary files a/images/009.png and /dev/null differ diff --git a/images/010.png b/images/010.png deleted file mode 100644 index 752c881cb..000000000 Binary files a/images/010.png and /dev/null differ diff --git a/images/011.png b/images/011.png deleted file mode 100644 index 6cb940055..000000000 Binary files a/images/011.png and /dev/null differ diff --git a/packages/squad-cli/src/cli-entry.ts b/packages/squad-cli/src/cli-entry.ts index ffd3524d8..7cf3c777b 100644 --- a/packages/squad-cli/src/cli-entry.ts +++ b/packages/squad-cli/src/cli-entry.ts @@ -214,6 +214,8 @@ async function main(): Promise { // No args β†’ launch interactive shell; whitespace-only arg β†’ show help if (rawCmd === undefined) { await checkNodeSqlite(); + // Fire-and-forget update check β€” non-blocking, never delays shell startup + import('./cli/self-update.js').then(m => m.notifyIfUpdateAvailable(VERSION)).catch(() => {}); const { runShell } = await lazyRunShell(); await runShell(); return; diff --git a/publish-0.8.21.ps1 b/publish-0.8.21.ps1 new file mode 100644 index 000000000..5fe4027ec --- /dev/null +++ b/publish-0.8.21.ps1 @@ -0,0 +1,119 @@ +# Publish squad-sdk and squad-cli v0.8.21 to npm +# Requires: OTP code from authenticator app + +param( + [Parameter(Mandatory=$true)] + [string]$OTP, + [switch]$SkipBump +) + +$ErrorActionPreference = "Stop" + +Write-Host "========================================" -ForegroundColor Cyan +Write-Host "Publishing Squad Packages v0.8.21" -ForegroundColor Cyan +Write-Host "========================================" -ForegroundColor Cyan +Write-Host "" + +# Publish SDK first (CLI depends on it) +Write-Host "[1/2] Publishing @bradygaster/squad-sdk@0.8.21..." -ForegroundColor Yellow +Push-Location packages\squad-sdk +try { + npm publish --access public --otp=$OTP + if ($LASTEXITCODE -ne 0) { + throw "SDK publish failed with exit code $LASTEXITCODE" + } + Write-Host "βœ“ SDK published successfully" -ForegroundColor Green +} finally { + Pop-Location +} + +Write-Host "" + +# Verify SDK is live +Write-Host "Verifying SDK on npm registry..." -ForegroundColor Yellow +$sdkVersion = npm view @bradygaster/squad-sdk version 2>&1 +if ($sdkVersion -match "0.8.21") { + Write-Host "βœ“ SDK verified: $sdkVersion" -ForegroundColor Green +} else { + throw "SDK verification failed. Got: $sdkVersion" +} + +Write-Host "" + +# Publish CLI +Write-Host "[2/2] Publishing @bradygaster/squad-cli@0.8.21..." -ForegroundColor Yellow +Push-Location packages\squad-cli +try { + npm publish --access public --otp=$OTP + if ($LASTEXITCODE -ne 0) { + throw "CLI publish failed with exit code $LASTEXITCODE" + } + Write-Host "βœ“ CLI published successfully" -ForegroundColor Green +} finally { + Pop-Location +} + +Write-Host "" + +# Verify CLI is live +Write-Host "Verifying CLI on npm registry..." -ForegroundColor Yellow +$cliVersion = npm view @bradygaster/squad-cli version 2>&1 +if ($cliVersion -match "0.8.21") { + Write-Host "βœ“ CLI verified: $cliVersion" -ForegroundColor Green +} else { + throw "CLI verification failed. Got: $cliVersion" +} + +Write-Host "" +Write-Host "========================================" -ForegroundColor Cyan +Write-Host "βœ“ Both packages published to npm!" -ForegroundColor Green +Write-Host "========================================" -ForegroundColor Cyan +Write-Host "" +Write-Host "npm URLs:" -ForegroundColor Cyan +Write-Host " - https://www.npmjs.com/package/@bradygaster/squad-sdk/v/0.8.21" +Write-Host " - https://www.npmjs.com/package/@bradygaster/squad-cli/v/0.8.21" + +if (-not $SkipBump) { + Write-Host "" + Write-Host "========================================" -ForegroundColor Cyan + Write-Host "Bumping to 0.8.22-preview.1" -ForegroundColor Cyan + Write-Host "========================================" -ForegroundColor Cyan + Write-Host "" + + # Bump all package.json files + $packageFiles = @( + "package.json", + "packages\squad-sdk\package.json", + "packages\squad-cli\package.json" + ) + + foreach ($file in $packageFiles) { + Write-Host "Updating $file..." -ForegroundColor Yellow + $content = Get-Content $file -Raw + $content = $content -replace '"version": "0\.8\.21"', '"version": "0.8.22-preview.1"' + Set-Content $file $content -NoNewline + Write-Host "βœ“ Updated $file" -ForegroundColor Green + } + + Write-Host "" + Write-Host "Committing version bump..." -ForegroundColor Yellow + git add package.json packages/squad-sdk/package.json packages/squad-cli/package.json + git commit -m "chore: bump to 0.8.22-preview.1 for continued development`n`nCo-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>" + if ($LASTEXITCODE -ne 0) { + throw "Commit failed with exit code $LASTEXITCODE" + } + Write-Host "βœ“ Committed" -ForegroundColor Green + + Write-Host "" + Write-Host "Pushing to dev..." -ForegroundColor Yellow + git push origin dev + if ($LASTEXITCODE -ne 0) { + throw "Push failed with exit code $LASTEXITCODE" + } + Write-Host "βœ“ Pushed to dev" -ForegroundColor Green + + Write-Host "" + Write-Host "========================================" -ForegroundColor Cyan + Write-Host "βœ“ All done! Next version: 0.8.22-preview.1" -ForegroundColor Green + Write-Host "========================================" -ForegroundColor Cyan +} diff --git a/test/docs-build.test.ts b/test/docs-build.test.ts index 5d9adcee8..52928233e 100644 --- a/test/docs-build.test.ts +++ b/test/docs-build.test.ts @@ -19,7 +19,7 @@ const EXPECTED_GET_STARTED = ['choose-your-interface', 'first-session', 'install const EXPECTED_GUIDES = ['tips-and-tricks', 'sample-prompts', 'personal-squad', 'contributing', 'contributors', 'shell', 'faq']; -const EXPECTED_REFERENCE = ['cli', 'sdk', 'config', 'api-reference', 'integration', 'tools-and-hooks']; +const EXPECTED_REFERENCE = ['cli', 'sdk', 'config', 'api-reference', 'integration', 'tools-and-hooks', 'glossary']; const EXPECTED_SCENARIOS= [ 'aspire-dashboard', @@ -86,13 +86,7 @@ const EXPECTED_FEATURES = [ 'worktrees', ]; -const EXPECTED_CONCEPTS = [ - 'github-workflow', - 'memory-and-knowledge', - 'parallel-work', - 'portability', - 'your-team', -]; +const EXPECTED_CONCEPTS = ['architecture', 'github-workflow', 'memory-and-knowledge', 'parallel-work', 'portability', 'your-team']; // Blog posts are discovered dynamically to avoid breaking tests when posts change const EXPECTED_BLOG = existsSync(BLOG_CONTENT_DIR) @@ -249,7 +243,6 @@ describe('Docs Build Script (Astro)', () => { ...EXPECTED_FEATURES.map(n => ({ dir: 'features', name: n })), ...EXPECTED_REFERENCE.map(n => ({ dir: 'reference', name: n })), ...EXPECTED_SCENARIOS.map(n => ({ dir: 'scenarios', name: n })), - ...EXPECTED_FEATURES.map(n => ({ dir: 'features', name: n })), ...EXPECTED_CONCEPTS.map(n => ({ dir: 'concepts', name: n })), ]; for (const { dir, name } of allExpected) { diff --git a/vitest.config.ts b/vitest.config.ts index c26c8bfd6..eb187d77f 100644 --- a/vitest.config.ts +++ b/vitest.config.ts @@ -9,6 +9,9 @@ export default defineConfig({ // under squad-cli/node_modules which bypasses the mock. '@bradygaster/squad-cli/shell/shell-metrics': path.resolve(__dirname, 'packages/squad-cli/src/cli/shell/shell-metrics.ts'), }, + // Force vitest to resolve @bradygaster/squad-sdk from the workspace root, + // not from a duplicate copy under packages/squad-cli/node_modules/. + dedupe: ['@bradygaster/squad-sdk'], }, test: { include: ['test/**/*.test.ts'],