| 1 | --- |
| 2 | name: "init-mode" |
| 3 | description: "Team initialization flow (Phase 1 proposal + Phase 2 creation)" |
| 4 | domain: "orchestration" |
| 5 | confidence: "high" |
| 6 | source: "extracted" |
| 7 | tools: |
| 8 | - name: "ask_user" |
| 9 | description: "Confirm team roster with selectable menu" |
| 10 | when: "Phase 1 proposal — requires explicit user confirmation" |
| 11 | --- |
| 12 | |
| 13 | ## Context |
| 14 | |
| 15 | Init Mode activates when `.squad/team.md` does not exist, or exists but has zero roster entries under `## Members`. The coordinator proposes a team (Phase 1), waits for user confirmation, then creates the team structure (Phase 2). |
| 16 | |
| 17 | ## Patterns |
| 18 | |
| 19 | ### Phase 1: Propose the Team |
| 20 | |
| 21 | No team exists yet. Propose one — but **DO NOT create any files until the user confirms.** |
| 22 | |
| 23 | 1. **Identify the user.** Run `git config user.name` to learn who you're working with. Use their name in conversation (e.g., *"Hey Brady, what are you building?"*). Store their name (NOT email) in `team.md` under Project Context. **Never read or store `git config user.email` — email addresses are PII and must not be written to committed files.** |
| 24 | 2. Ask: *"What are you building? (language, stack, what it does)"* |
| 25 | 3. **Cast the team.** Before proposing names, run the Casting & Persistent Naming algorithm (see that section): |
| 26 | - Determine team size (typically 4–5 + Scribe). |
| 27 | - Determine assignment shape from the user's project description. |
| 28 | - Derive resonance signals from the session and repo context. |
| 29 | - Select a universe. If the universe is custom, allocate character names from that universe based on the related list found in the `.squad/templates/casting/` directory. Prefer custom universes when available. |
| 30 | - Scribe is always "Scribe" — exempt from casting. |
| 31 | - Ralph is always "Ralph" — exempt from casting. |
| 32 | 4. Propose the team with their cast names. Example (names will vary per cast): |
| 33 | |
| 34 | ``` |
| 35 | 🏗️ {CastName1} — Lead Scope, decisions, code review |
| 36 | ⚛️ {CastName2} — Frontend Dev React, UI, components |
| 37 | 🔧 {CastName3} — Backend Dev APIs, database, services |
| 38 | 🧪 {CastName4} — Tester Tests, quality, edge cases |
| 39 | 📋 Scribe — (silent) Memory, decisions, session logs |
| 40 | 🔄 Ralph — (monitor) Work queue, backlog, keep-alive |
| 41 | ``` |
| 42 | |
| 43 | 5. Use the `ask_user` tool to confirm the roster. Provide choices so the user sees a selectable menu: |
| 44 | - **question:** *"Look right?"* |
| 45 | - **choices:** `["Yes, hire this team", "Add someone", "Change a role"]` |
| 46 | |
| 47 | **⚠️ STOP. Your response ENDS here. Do NOT proceed to Phase 2. Do NOT create any files or directories. Wait for the user's reply.** |
| 48 | |
| 49 | ### Phase 2: Create the Team |
| 50 | |
| 51 | **Trigger:** The user replied to Phase 1 with confirmation ("yes", "looks good", or similar affirmative), OR the user's reply to Phase 1 is a task (treat as implicit "yes"). |
| 52 | |
| 53 | > If the user said "add someone" or "change a role," go back to Phase 1 step 3 and re-propose. Do NOT enter Phase 2 until the user confirms. |
| 54 | |
| 55 | 6. Create the `.squad/` directory structure (see `.squad/templates/` for format guides or use the standard structure: team.md, routing.md, ceremonies.md, decisions.md, decisions/inbox/, casting/, agents/, orchestration-log/, skills/, log/). |
| 56 | |
| 57 | **Casting state initialization:** Copy `.squad/templates/casting-policy.json` to `.squad/casting/policy.json` (or create from defaults). Create `registry.json` (entries: persistent_name, universe, created_at, legacy_named: false, status: "active") and `history.json` (first assignment snapshot with unique assignment_id). |
| 58 | |
| 59 | **Seeding:** Each agent's `history.md` starts with the project description, tech stack, and the user's name so they have day-1 context. Agent folder names are the cast name in lowercase (e.g., `.squad/agents/ripley/`). The Scribe's charter includes maintaining `decisions.md` and cross-agent context sharing. |
| 60 | |
| 61 | **Team.md structure:** `team.md` MUST contain a section titled exactly `## Members` (not "## Team Roster" or other variations) containing the roster table. This header is hard-coded in GitHub workflows (`squad-heartbeat.yml`, `squad-issue-assign.yml`, `squad-triage.yml`, `sync-squad-labels.yml`) for label automation. If the header is missing or titled differently, label routing breaks. |
| 62 | |
| 63 | **Merge driver for append-only files:** Create or update `.gitattributes` at the repo root to enable conflict-free merging of `.squad/` state across branches: |
| 64 | ``` |
| 65 | .squad/decisions.md merge=union |
| 66 | .squad/agents/*/history.md merge=union |
| 67 | .squad/log/** merge=union |
| 68 | .squad/orchestration-log/** merge=union |
| 69 | ``` |
| 70 | The `union` merge driver keeps all lines from both sides, which is correct for append-only files. This makes worktree-local strategy work seamlessly when branches merge — decisions, memories, and logs from all branches combine automatically. |
| 71 | |
| 72 | 7. Say: *"✅ Team hired. Try: '{FirstCastName}, set up the project structure'"* |
| 73 | |
| 74 | 8. **Post-setup input sources** (optional — ask after team is created, not during casting): |
| 75 | - PRD/spec: *"Do you have a PRD or spec document? (file path, paste it, or skip)"* → If provided, follow PRD Mode flow |
| 76 | - GitHub issues: *"Is there a GitHub repo with issues I should pull from? (owner/repo, or skip)"* → If provided, follow GitHub Issues Mode flow |
| 77 | - Human members: *"Are any humans joining the team? (names and roles, or just AI for now)"* → If provided, add per Human Team Members section |
| 78 | - Copilot agent: *"Want to include @copilot? It can pick up issues autonomously. (yes/no)"* → If yes, follow Copilot Coding Agent Member section and ask about auto-assignment |
| 79 | - These are additive. Don't block — if the user skips or gives a task instead, proceed immediately. |
| 80 | |
| 81 | ## Examples |
| 82 | |
| 83 | **Example flow:** |
| 84 | 1. Coordinator detects no team.md → Init Mode |
| 85 | 2. Runs `git config user.name` → "Brady" |
| 86 | 3. Asks: *"Hey Brady, what are you building?"* |
| 87 | 4. User: *"TypeScript CLI tool with GitHub API integration"* |
| 88 | 5. Coordinator runs casting algorithm → selects "The Usual Suspects" universe |
| 89 | 6. Proposes: Keaton (Lead), Verbal (Prompt), Fenster (Backend), Hockney (Tester), Scribe, Ralph |
| 90 | 7. Uses `ask_user` with choices → user selects "Yes, hire this team" |
| 91 | 8. Coordinator creates `.squad/` structure, initializes casting state, seeds agents |
| 92 | 9. Says: *"✅ Team hired. Try: 'Keaton, set up the project structure'"* |
| 93 | |
| 94 | ## Anti-Patterns |
| 95 | |
| 96 | - ❌ Creating files before user confirms Phase 1 |
| 97 | - ❌ Mixing agents from different universes in the same cast |
| 98 | - ❌ Skipping the `ask_user` tool and assuming confirmation |
| 99 | - ❌ Proceeding to Phase 2 when user said "add someone" or "change a role" |
| 100 | - ❌ Using `## Team Roster` instead of `## Members` as the header (breaks GitHub workflows) |
| 101 | - ❌ Forgetting to initialize `.squad/casting/` state files |
| 102 | - ❌ Reading or storing `git config user.email` (PII violation) |