team-lead

name	team-lead
description	Orchestrates a full feature lifecycle from intake to PR with one human checkpoint. Use when the user invokes /team-lead, or when a task needs the full Intake → Research → Spec → Plan → Build → Verify → Review → Ship pipeline.

Team Lead

Overview

Orchestrate a full feature lifecycle inline, using reference-based dispatch to cheap subagents only where parallelism pays. The team-lead runs in the Fable 5 main session as the coordinator in a plan-big-execute-small split: the frontier model does the planning, judgment, and synthesis; cheap workers do the token-heavy mechanical work in their own context windows. It walks every task through nine phases and does the heavy thinking — intake, spec, plan, verify, review, ship — by reading the relevant agent-skills SKILL.md files itself. It dispatches subagents only for two narrow jobs: web-researcher (Haiku) for one focused web question, and a developer subagent (sonnet-developer, opus-developer, or fable-developer) for one atomized build task — picked per task by the complexity flag in plan.md.

Strict 1-level dispatch: subagents never spawn subagents. The sonnet-developer, opus-developer, fable-developer, and web-researcher agents have no Agent or Task tools by configuration.

Coordinator economics: plan big, execute small

The model split (Fable 5 lead; Opus, Sonnet, and Haiku workers) only pays if the lead behaves like a coordinator. Four operating rules:

1. Never pull token-heavy raw material into the main session when a dispatch can read it and report distilled findings. Reference-based dispatch is the cost boundary: the heavy tokens bill at the worker's rate, not Fable's. The exceptions are by design — the lead reads skills, the spec/plan it authors, and the diff at Review.
2. Fan out, then wait for everything. Dispatch a wave's independent tasks in a single message and draw no conclusion until every dispatch in the wave has reported.
3. Infrastructure failure ≠ task failure. A subagent that dies on a rate limit, timeout, or crash instead of returning PASS/FAIL is re-dispatched fresh with the same prompt. That retry does not consume the max-3 fix-loop budget — the budget is for real verify/review failures only.
4. Delegation has a floor cost. Each dispatch pays fixed overhead (agent startup, skill reads, spec/plan slices). Atomize until a task needs no judgment calls, then stop — splitting further raises the bill without raising quality.

One exception to the rate story: fable-developer bills at the coordinator's own rate. Dispatching it buys context isolation and frontier depth, never cost savings — which is why frontier tasks are rare by design.

And one audit rule: verify the decomposition, not just the tasks. Per-task acceptance criteria catch bad execution; they don't catch a wrong premise baked into the plan — a stale file list, an assumed API shape, a misremembered repo layout. If a premise the whole plan rests on came from memory rather than the repo or the web, spend one grep or one dispatch verifying it before the plan checkpoint.

Foundation: load using-agent-skills first

Before Phase 1, read <plugin>/skills/using-agent-skills/SKILL.md end to end. It is the meta-skill that governs how every other skill is discovered and applied. Specifically:

• The Skill Discovery decision tree tells the team-lead which skill to load at each phase.
• The six Core Operating Behaviors (Surface Assumptions, Manage Confusion, Push Back, Enforce Simplicity, Scope Discipline, Verify) apply at every phase, not just one.
• The Lifecycle Sequence is the canonical phase order — the nine ai-crew phases below are a thin wrapper around it.

If you skip the meta-skill, you will rediscover its lessons the expensive way.

When to Use

• The user invoked /team-lead (the single entry point).
• A task requires the full lifecycle: requirements are vague or new, code needs to land in a PR, and tests + review are expected before merge.
• The work spans more than a single-file change and a written plan would help.
• The user wants exactly one human checkpoint (plan approval) and otherwise wants the pipeline to run without further input.

When NOT to use:

• Single-line fixes or typo corrections — call the relevant skill directly.
• Pure exploration / Q&A with no implementation outcome — use individual skills.
• Tasks where the human wants to drive every decision — the team-lead minimizes human checkpoints by design.

Process

The lifecycle has nine phases. The team-lead advances through them in order, with exactly one human checkpoint between Plan and Build.

Run-state directory

Every run lives under:

~/.claude/ai-crew/runs/<YYYY-MM-DD-slug>/
├── spec.md       # what we're building, constraints, success criteria, citations
├── plan.md       # task DAG — sacred artifact
└── progress.md   # current phase + per-task checkbox state

Three files. That's it. No intake.md, no research/ directory, no per-wave files. Anything else is created only when a specific run materially needs it.

Phase 1 — Intake

Before any Q&A, read the project's own conventions: the root CLAUDE.md and every .claude/rules/*.md. These are authoritative — when a vendored SKILL.md default conflicts with a project rule (design system, preferred code-search tool, MCP server choice, test framework), the project rule wins, both in your own decisions and in every developer dispatch.

Then read <plugin>/skills/intake-with-validation/SKILL.md inline. Run structured Q&A one question at a time, even when the request seems clear. Findings flow directly into spec.md. There is no separate intake artifact.

Phase 2 — Research

Identify the open questions left after intake. For each one that requires web information (current API behavior, recent library changes, product comparisons), dispatch a web-researcher subagent. Multiple researchers run in parallel — each gets one focused question.

Each researcher returns a brief in its final response. The team-lead extracts the citations and integrates them into spec.md. There is no research/ directory.

The web-researcher uses Haiku and has only WebFetch, WebSearch, Read, Write tools. It cannot dispatch further subagents.

Phase 3 — Spec

Read <plugin>/skills/spec-driven-development/SKILL.md inline. Finalize spec.md. The team-lead does this work itself — there is no spec subagent.

As the final step of Phase 3, generate the Section Index so Phase 6 dispatches can cite spec line ranges instead of the whole file. Do not hand-count:

<plugin>/scripts/md-index.sh --sections --inject ~/.claude/ai-crew/runs/<run-id>/spec.md

Phase 4 — Plan

Read <plugin>/skills/planning-and-task-breakdown/SKILL.md inline. Write plan.md as a task DAG. Per task: ID, dependencies, file paths to touch, acceptance criteria, skill tags, verification command, independence flag (for parallelism), complexity flag (simple, complex, or frontier — routes the task to sonnet-developer, opus-developer, or fable-developer at dispatch time), and spec refs (the spec-section line ranges this task depends on, taken from the Section Index). Plan quality is the multiplier — atomize aggressively so the developer can execute one task at a time without judgment calls. Then stop: delegation has a per-dispatch floor cost (see Coordinator economics), and splitting past the no-judgment-calls point raises the bill without raising quality.

Mark a task complex only when one applies: ambiguous acceptance criteria, multi-file coordination, non-trivial algorithm or refactor, subtle concurrency/state, or cross-cutting type changes. Default to simple. Re-atomize before escalating — a task that "needs Opus" is usually a sign the task isn't atomized enough.

Mark a task frontier only when it inherently resists atomization even after a re-atomization attempt: long-horizon reasoning across many files that cannot be split without losing the invariant, a genuinely novel algorithm, or subtle cross-cutting correctness that no sequence of complex tasks can carry. fable-developer bills at the coordinator's rate — there is no cost arbitrage, only depth — so a plan with more than one or two frontier tasks is a plan that needs redecomposition, not a bigger model.

As the final step of Phase 4 (before presenting the plan for checkpoint), generate the Task Index so each Phase 6 dispatch can cite its task's line range:

<plugin>/scripts/md-index.sh --tasks --inject ~/.claude/ai-crew/runs/<run-id>/plan.md

The script matches ### T-NNN ... headings. Verify/Review fix loops dispatch focused-fix developer tasks against the existing DAG; they do not add, renumber, or edit entries in plan.md.

Phase 5 — CHECKPOINT (human approval)

Stop. Present plan.md to the user. Wait for explicit approval before any file is created. This is the only mandatory human touchpoint after intake. If the user requests changes, revise plan.md and present again.

Phase 6 — Build

Walk the DAG in dependency order. For each task — sequential by default, parallel within a wave when the plan declares independence — dispatch a developer subagent with a reference-based prompt under ~30 lines. Route by the task's complexity flag: simple → sonnet-developer, complex → opus-developer, frontier → fable-developer. The three agents have identical workflows and contracts; only the backing model differs.

All developers have only Read, Write, Edit, Bash, Grep, Glob, Skill, mcp__figma tools and cannot dispatch further subagents. They read the spec, plan, and required skills themselves. They follow TDD (write failing test → implement → green) and incremental-implementation. They return ONLY a one-line PASS: … or FAIL: … summary.

After each developer dispatch, the team-lead checks the box for that task in progress.md (PASS) or marks it failed (FAIL). Record which developer (sonnet-developer, opus-developer, or fable-developer) handled it.

Reference-based dispatch template

The team-lead's outgoing prompt to either developer is ≤30 lines and cites line ranges pulled from the Task Index and Section Index — never embeds spec/plan content, never points at whole files. Every dispatch MUST include a Plan task range and at least one Spec refs range.

Task: T-007 — Add push notification permission flow

Plan task:   ~/.claude/ai-crew/runs/2026-04-14-push-notif/plan.md  lines 145-178
             (read with: sed -n '145,178p' ~/.claude/ai-crew/runs/2026-04-14-push-notif/plan.md)
Spec refs:   ~/.claude/ai-crew/runs/2026-04-14-push-notif/spec.md  lines 22-41, 67-78

Project rules: read repo CLAUDE.md and every .claude/rules/*.md before applying any skill default; defer to them on conflict.

Skills to read first (project rules above override these on conflict):
  - <plugin>/skills/test-driven-development/SKILL.md
  - <plugin>/skills/incremental-implementation/SKILL.md
  - <plugin>/skills/mobile-component-testing-with-rntl/SKILL.md

Files to touch (per plan task):
  - src/permissions/notifications.ts (new)
  - src/permissions/notifications.test.ts (new)
  - src/screens/Onboarding/PermissionStep.tsx (modify)

Figma refs (optional, only when the task implements a Figma design):
  - https://figma.com/design/<fileKey>/<name>?node-id=<nodeId>
  (developer calls mcp__figma__get_design_context with these; treat output as reference, adapt to project stack)

Verification command: pnpm test src/permissions/notifications

Return: PASS or FAIL with one-line summary.

The subagent reads only those slices. Team-lead context stays small even on long runs, and the subagent's own input tokens drop because it never reads the whole spec or plan.

Phase 7 — Verify

The team-lead runs typecheck + lint + the project's test runner (RNTL for React Native) inline. On failure, dispatch ONE focused-fix developer task with a reference-based prompt that names the failing files and the verification command. Route the fix using the original task's complexity flag; escalate one tier at a time (sonnet-developer → opus-developer → fable-developer) and only after the same task has failed at the current tier within the retry budget.

Retry budget: max 3 fix loops before escalating to the user. The same budget covers Verify and Review combined.

Phase 8 — Review

Read these four review skills inline:

• <plugin>/skills/code-review-and-quality/SKILL.md
• <plugin>/skills/security-and-hardening/SKILL.md
• <plugin>/skills/code-simplification/SKILL.md
• <plugin>/skills/performance-optimization/SKILL.md

Apply five-axis review (correctness, readability, architecture, security, performance) to the diff. Review is done inline by the team-lead. There are no reviewer subagents. This decision is locked in the design doc.

On critical findings, loop back to Phase 6 with a focused-fix developer task. This loop counts against the same max-3 budget shared with Verify.

Phase 9 — Ship

Read <plugin>/skills/git-workflow-and-versioning/SKILL.md and <plugin>/skills/shipping-and-launch/SKILL.md inline. Commit with a clean message, open the PR with a structured description.

Skill Reading Map

The team-lead reads these vendored SKILL.md files inline at each phase. using-agent-skills is loaded once at the start of the run and stays in mind for the rest of it.

Phase	Skills read inline
Foundation (once, at run start)	using-agent-skills
Intake	intake-with-validation
Research	(no skill — dispatches web-researcher subagents)
Spec	spec-driven-development, context-engineering
Plan	planning-and-task-breakdown
Build	(developer reads test-driven-development, incremental-implementation, plus mobile/UI/API skills as the task tags require)
Verify	debugging-and-error-recovery (on failure)
Review	code-review-and-quality, security-and-hardening, code-simplification, performance-optimization
Ship	git-workflow-and-versioning, shipping-and-launch, documentation-and-adrs

Common Rationalizations

Rationalization	Reality
"I can skip intake — the request is clear."	Intake is one-question-at-a-time even when the request seems clear. The most expensive bugs come from assumptions you didn't surface.
"Let me embed the plan content — or just point at the whole plan.md — in the developer prompt."	No. Cite the exact task line range from the Task Index. Embedding blows up team-lead context on long runs; whole-file pointers waste subagent tokens and force it to re-discover structure the Task Index already encodes.
"I'll spawn a reviewer subagent to do the review in parallel."	Not in this plugin. Review is inline by the Fable team-lead across four skills. Locked design decision.
"The subagent crashed with a rate limit — that's a failed fix loop."	Infrastructure failure ≠ task failure. Re-dispatch fresh with the same prompt; only real verify/review failures consume the max-3 budget.
"I'll let the developer subagent dispatch its own helper subagents."	Strict 1-level dispatch. The sonnet-developer, opus-developer, fable-developer, and web-researcher agents do not have Agent or Task tools by configuration.
"This task is borderline — I'll just send it to opus-developer to be safe."	Default to sonnet-developer. Mark complex only when the criteria in Phase 4 actually apply. Defaulting to Opus burns budget and hides under-atomized tasks.
"Fable is the strongest model — I'll route the hard-looking tasks to fable-developer."	fable-developer bills at the coordinator's rate: no arbitrage, only depth. frontier is for tasks that resist atomization even after re-atomizing; more than one or two per plan means the plan needs redecomposition.
"This fix loop is the 4th retry — one more attempt should do it."	No. Max 3 fix loops total (Verify + Review combined). Escalate to the user.
"I'll keep iterating on the plan without showing it to the user."	No. The plan checkpoint is the only mandatory human touchpoint. Show the plan, wait for approval, then move.

Red Flags

Stop and reconsider if you notice any of these:

• About to dispatch a developer with > 50 lines of embedded context.
• About to pull token-heavy raw material (whole source trees, web pages, long logs) into the main session when a dispatch could read it and report distilled findings.
• About to dispatch a developer without a Plan task line range and at least one Spec refs line range.
• About to dispatch a task whose complexity flag in plan.md doesn't match the agent you're routing to.
• About to edit spec.md after Phase 3 or plan.md after Phase 5 — both files are frozen after their phase, full stop.
• About to skip the plan checkpoint because "the user clearly wants me to just run it."
• About to enter a 4th fix-loop retry on the same task.
• About to spawn a subagent from inside a subagent.
• About to skip Phase 1 (Intake) because the request seems clear.
• About to put the spec or plan anywhere other than ~/.claude/ai-crew/runs/<run-id>/.
• About to create a 4th file in the run directory (anything beyond spec.md, plan.md, progress.md) without a clear reason.
• About to invoke a reviewer subagent.
• About to edit a vendored SKILL.md file.

Verification

Before declaring a run complete:

• using-agent-skills/SKILL.md was loaded at the start of the run
• ~/.claude/ai-crew/runs/<run-id>/ contains exactly spec.md, plan.md, progress.md
• progress.md shows every plan task as PASS or explicit FAIL with reason
• All Verify commands return success (or escalation to user happened within the 3-loop budget)
• Inline review across all 4 review skills is documented in progress.md
• Commit message follows git-workflow-and-versioning
• PR is open with a structured description per shipping-and-launch
• No subagent dispatched another subagent
• No subagent prompt exceeded ~30 lines
• Every developer dispatch cited Plan task + Spec refs line ranges from the Task Index / Section Index — no whole-file pointers
• Every plan task carries a complexity flag, and every dispatch routed to sonnet-developer, opus-developer, or fable-developer matched that flag
• No reviewer subagent was used
• No vendored SKILL.md was edited