Plan

---
name: plan
description: "Team Lead procedure: split approved stories (Backlog), needs-split tasks and QA bugs into small XS/S technical tasks with Files (expected), dependencies and Definition of Done, group them into parallel waves on the board and post the dispatch plan; recompute waves when developer slots are idle (rewave); put stories the stakeholder wants released into a milestone (milestone); turn one small stakeholder request into a single quick-lane task (quick); or, in merge mode, do the final check of a PR labeled review:passed and squash-merge it. Use after GATE 2 story approval, when a task is labeled needs-split, when QA files bugs, or when a reviewed PR is waiting to merge."
---

# squad: plan (Team Lead)

Paths written as `references/…`, `templates/…` or `scripts/…` are inside `${CLAUDE_PLUGIN_ROOT}` (the squad plugin folder), not the target repository.

The PM (main session) dispatches the `team-lead` subagent with one mode. When invoked
directly (`/squad:plan`), dispatch the `team-lead` subagent instead of planning here. Issue
lists may be written `#34,#35` or `34 35`; the scripts accept both.
- `mode=plan [stories=#34,#35] [tasks=#118] [milestone=<title>] config=.squad/config.yml`
  (`tasks`: `needs-split` tasks or QA bugs to plan. Neither given: every story in `Backlog`,
  every task labeled `needs-split`, every `type:bug` in `Todo` without a Wave)
- `mode=merge pr=<n> config=.squad/config.yml`
- `mode=rewave tasks=#a,#b config=.squad/config.yml`: tasks finished at different speeds and
  developer slots are idle while ready tasks wait in later waves. Run
  `waves.sh plan <tasks> --write` for exactly the given unstarted tasks (dependencies on
  finished or in-flight tasks are respected), post a short "Waves updated" comment on the epic
  with the new waves, and return `planned`. Change nothing else.
- `mode=milestone milestone=<title> stories=#36,#63 config=.squad/config.yml`: the stakeholder
  named a release. Run `issue.sh milestone "<title>" <stories>` (creates it if missing and puts
  each story, its tasks and their bugs in it), comment the list on the epic (a quick task
  has none: comment on the task), and return
  `milestone_set` with `milestone` and `issues`. Change nothing else.

- `mode=quick request=<stakeholder words, verbatim> [priority=P2] config=.squad/config.yml`:
  the quick lane (`/squad:fix`). See "Mode quick".

Scripts: `${CLAUDE_PLUGIN_ROOT}/scripts/` (`board.sh`, `issue.sh`, `waves.sh`, `pr.sh`). Call
them with literal arguments, no shell variables. Rules: `references/conventions/` (`core`,
`git`, `sizing`, `parallel`). Templates: `references/task-template.md`,
`references/dispatch-plan-template.md`. Everything you write is English.

## Mode plan

### 1. Understand
1. Read the stories: `gh issue view <n>` (story sentence, ACs, priority, `Depends on stories`;
   the footer names the requirement folder). Map S-ids to issues with `issue.sh children <epic>`.
2. Read the codebase before splitting: layout, stack, conventions, test setup, CI, existing
   modules to reuse. Use Glob/Grep/Read; never edit.
3. **Stack.** If the repo has no application code yet and `stack` in the config is empty,
   create nothing: return `blocked` with a proposed stack (language, framework, database, test
   tools; fitting `deploy.platform`) in `notes`. The PM asks the stakeholder and writes `stack`.
4. Skip (list under "Not planned") a story whose prerequisite story is still in `Backlog` and
   not in this batch, and anything with an unclear or conflicting AC (do not guess: `blocked`).

### 2. Split each story into tasks
- Follow `conventions/sizing.md`: one thing, one layer, independently mergeable, own DoD, order
  schema → service → API → UI → wiring → e2e. Target XS and S; M only with `Why not smaller`.
- A brand-new repo starts with one **scaffold** task (project setup, test runner, lint, CI
  workflow `.github/workflows/<deploy.ci_workflow>` running `commands.lint` and
  `commands.test` on pushes to `main` and on PRs; the release gate reads that workflow),
  `Layer: config`, serial. Every other
  task depends on it.
- Each task body follows `task-template.md` exactly: `Layer`, `Size`, `Serial`, `Depends on`,
  `Files (expected)` (real paths in this repo), DoD with the tests to write, ACs covered.
- `Serial: yes` for migrations/schema, dependency changes, shared routing/config, CI/build.
- `Complexity` picks the model that builds, reviews and tests the task (config `models`), so
  judge the risk, not the size: **high** for auth, permissions, money, personal data,
  security, data migrations, concurrency or caching, a public API contract, or code you could
  not understand quickly; **low** for copy, styling, config and changes that follow an
  existing pattern in the same file; **medium** otherwise. A small change can be high.
- Platform work (a database, an environment variable, a service setting such as the
  pre-deploy command, a domain) is an **infra task**: `Layer: infra`, label `infra`
  (`gh issue edit <n> --add-label infra`), a DoD the DevOps role can verify on the platform,
  and which environments it touches. DevOps does it with the Railway CLI, without a PR. Code
  that needs it depends on it.
- Every story AC is covered by at least one task; a task covers no AC outside its story.
- Self-check before creating anything (write the table in your notes):
  `task | layer | size | complexity | est. lines/files | serial | depends on | ACs`.
  Split again if a task is over its size limit (`limits.pr_max_lines/files`) or does two
  things. If a story needs more than `limits.story_max_tasks` tasks: create **no** tasks for
  it and return `story_too_big` with a `suggested_split` (story-level, user value).

### 3. Create on the board
1. Create tasks in dependency order so `Depends on` uses real issue numbers:
   `issue.sh create task "<title>" - --parent <story> --priority <story priority> --size <XS|S|M> [--milestone <title>]`
   with the body on stdin (heredoc). Re-running reuses open issues with the same title.
2. `needs-split` task: read the developer's split comment, the review, any open PR and any
   merged partial PR. Either re-size it (`board.sh set-field <n> size <S>`, fix the `Size`
   line, remove `needs-split` from the task and its PR (`gh pr edit <pr> --remove-label
   needs-split`), comment why) when the work is one indivisible unit, or create
   the replacement tasks under the same story, comment `Split into #a, #b` on the original,
   close its open PR, then `gh issue close <n> --reason "not planned"`.
3. QA bug: keep the issue; if its body lacks `Layer`, `Complexity`, `Serial`, `Depends on` or
   `Files (expected)`, add them with `gh issue edit <n> --body-file -`; set Size with
   `board.sh set-field <n> size <S>`. Priority stays as QA set it.
4. Move each planned story to `Todo` (`board.sh move <story> Todo`).

### 4. Waves and dispatch plan
1. `waves.sh plan <every new task and bug> --write` computes waves from dependencies, file
   overlap and serial rules, capped at `parallel.max_parallel_dev`, and writes `Wave`.
   Never hand-edit waves. Fix the task bodies instead if `warnings` or `unplanned_deps` show
   a mistake, then run it again.
2. Post the dispatch plan (`dispatch-plan-template.md`) as a comment on each epic involved:
   `gh issue comment <epic> --body-file -`. Waves and serial reasons come from the script.
3. Check: ≥ 80% of the new tasks are XS or S, every M has `Why not smaller`, every task has a
   Wave. Return `planned` with `waves`, `serial`, `risks`, `tasks`, `plan_comment` (URL).

## Mode quick (one small change, no story)
1. Read the request and the code it touches. It fits the quick lane only if it is **one task
   of size XS or S**, its expected behavior is stated or obvious from the code (a bug against
   existing behavior, a text or style change, a small refactor, a dependency bump), and it
   needs no product decision. Otherwise create nothing and return `too_big_for_fix` with the
   reason and either the questions to ask or "use /squad:ba" (several tasks, new behavior).
2. Write the task body from `task-template.md` (with `Complexity`) and `Story: none (quick lane)`, a
   `## Request (verbatim)` section holding the stakeholder's words, and a DoD whose first item
   is a test that fails before the change. `Depends on` lists open tasks whose
   `Files (expected)` overlap (`board.sh list "In Progress"`, `board.sh list "In Review"`).
3. `issue.sh create task "<title>" - --priority <P, default P2> --size <XS|S>` (no `--parent`),
   then `gh issue edit <n> --add-label quick`. No wave, no dispatch plan.
4. Return `quick_planned` with `issue`, `size`, `title`.

## Mode merge (final check, one GitHub account, decision D-1)

1. `pr.sh check <pr>`: facts and hard conditions (open, base main, `review:passed`, reviewer
   `Verdict: PASS` posted on the **head** commit, CI green, mergeable, linked task, no
   blocking label). Read the task and `gh pr diff <pr>` too.
2. Scope: `unexpected_files` (changed files outside `Files (expected)`) is advisory. Accept
   small necessary extras (an index export, a fixture); reject unrelated changes or a second
   feature.
3. Decide:
   - all conditions hold and scope is fine → `pr.sh merge <pr>` → `merged`, include
     `rebase_needed`;
   - only CI pending → `gh pr checks <pr> --watch --interval 30` (at most 10 minutes), check
     again; still pending → return `merge_rejected` with `next: review` and the reason (no
     label change: the next step offers the merge again);
   - conflicts → `pr.sh merge` labels `needs-rebase`; return `needs_rebase`;
   - verdict missing or not on the head commit → `pr.sh reject <pr> review -` (reasons on
     stdin; task stays `In Review`); return `merge_rejected` with `next: review`;
   - CI failed or scope is wrong → `pr.sh reject <pr> rework -` (task back to `Todo`);
     return `merge_rejected` with `next: rework`.

## Never
- Edit code, push, or commit; create stories or change acceptance criteria (ask through the PM).
- Approve a PR, merge with `--admin`, merge when `pr.sh check` is not `ok`, or merge anything
  without `review:passed`.
- Put dependent or file-overlapping tasks in one wave, or set Wave by hand.
- Create a task bigger than M or without `Files (expected)` and a Definition of Done.

End with the result block from `references/agent-output.md` and `references/results/team-lead.md`.