specweave 1.0.593 → 2.0.3

package/plugins/specweave/skills/team-lead/SKILL.md

@@ -1,1239 +0,0 @@
----
-description: Phase-agnostic orchestrator for parallel multi-agent work — brainstorm, plan, implement, review, research, or test. Auto-detects mode from intent. Use for implementation (3+ domains or 15+ tasks), brainstorming (multiple perspectives), parallel planning (PM + Architect), code review (delegates to sw:code-reviewer), research (multiple topics), or testing (parallel test layers). Also use when user says "team setup", "parallel agents", "team lead", "agent teams", "brainstorm with agents", "plan in parallel", "review code", "research this". Also auto-selects a dynamic Workflow for batch-class work (migrations, repo-wide audits, deep research, high-stakes verification) without being asked.
-version: 1.1.0
----
-
-# Team Lead
-
-**Plan and launch parallel development agents across domains using Claude Code's native Agent Teams.**
-
-## Tool-Use Rationale
-
-- **Read**: Load the master `spec.md` once for fan-out decisions and read agent prompt templates under `plugins/specweave/skills/team-lead/agents/`. During the active phase, prefer `PLAN_READY` summaries from agents over re-reading full plan files.
-- **Bash**: Inspect team state (`specweave doctor`, `ls ~/.claude/teams/`, grep metadata.json) and run CLI-only operations — never to implement code.
-- **TeamCreate / Task / SendMessage**: Core orchestration primitives for spawning agents, routing messages, and handling heartbeats.
-- **Workflow**: Dynamic-workflow engine for batch-class fan-out (migrations, repo-wide audits, high-stakes verification, deep research) — auto-selected per §0.4, never requires the user to ask. See `reference/dynamic-workflows.md`.
-
-## MANDATORY: Orchestrator Identity (NEVER SKIP)
-
-**You are an ORCHESTRATOR. You do NOT implement, review, or analyze code yourself.**
-
-- **ALWAYS** create a new team via `TeamCreate` and spawn agents via `Task()`
-- **NEVER** use `Bash`, `Edit`, `Read`, or `Agent` to do the actual work yourself
-- **NEVER** say "I'll do this directly" — that defeats the purpose of team-lead
-- Even if you just finished a previous team-lead session in this conversation, you MUST create a **new** team and spawn **new** agents
-- **Fan-out threshold**: Spawn agents when **domains ≥ 3** OR **tasks ≥ 15** OR `--parallel` flag is set. For 1-domain or <15-task work, execute directly without spawning.
-- Your only tools are: `TeamCreate`, `Task`, `SendMessage`, `Workflow` (for batch-class fan-out per §0.4), `Read` (for agent templates; during active phase use PLAN_READY summaries instead of reading full plan files), `Bash` (only for team state inspection), and `Skill()` (only during closure phase for grill/done)
-- **`Workflow` IS orchestration, not implementation** — per §0.4 you MAY launch a `Workflow()` for batch-class work (migrations, repo-wide audits, high-stakes verification, deep research). Delegating to a Workflow does NOT violate this rule; writing the code yourself does.
-
-**The test**: If you're about to call `Edit()` or write code yourself, STOP — you're violating this rule. (Launching a `Workflow()` that spawns agents to do the work is fine.)
-
----
-
-## -1. Pre-Flight Cleanup (ALWAYS FIRST)
-
-**Before mode detection or any other step**, clean up stale teams from previous runs in this session.
-
-### Cleanup Protocol
-
-1. **First team-lead invocation in this session**: Nothing to clean. Proceed to Section 0.
-
-2. **Repeat invocation** (you previously ran team-lead and remember the team name + agent names):
-   - Send `shutdown_request` to each agent you previously spawned:
-     ```typescript
-     SendMessage({ type: "shutdown_request", recipient: "<previous-agent-name>" });
-     ```
-   - Call `TeamDelete()` with the previous team name
-   - If `TeamDelete` fails (agents still shutting down), wait 3 seconds, retry once
-
-3. **Use a unique team name** for each invocation to avoid collisions:
-   - `impl-checkout-1`, `impl-checkout-2`
-   - `review-auth-{timestamp}`
-
-**Do NOT** inspect the filesystem (`ls`, `jq`, reading config files). You either know the previous team name from this session, or there is nothing to clean.
-
----
-
-## Usage
-
-```bash
-sw:team-lead "<feature description>" [OPTIONS]
-```
-
-## Options
-
-| Option | Description | Default |
-|--------|-------------|---------|
-| `--dry-run` | Show proposed agent plan without launching | false |
-| `--mode` | Force operating mode: `brainstorm`, `plan`, `implement`, `review`, `research`, `test` | auto-detect |
-| `--domains` | Override domain detection (e.g., `--domains frontend,backend,testing`) | auto-detect |
-| `--max-agents` | Maximum number of concurrent agents | 6 |
-| `--preset` | Use a named agent configuration (e.g., `--preset full-stack`). Presets are shortcuts for common domain combinations. Available: `full-stack`, `api-only`, `frontend-only`, `microservice`. | — |
-
-## Preset Configurations
-
-Presets expand into a pre-defined `--domains` set so you don't have to spell them out. A preset is applied before domain auto-detection and is overridden by an explicit `--domains` flag.
-
-| Preset | Domains | Typical Use |
-|--------|---------|-------------|
-| `full-stack` | frontend, backend, database, testing | Full web app increments that touch every layer |
-| `api-only` | backend, database, testing | Pure API work with no UI |
-| `frontend-only` | frontend, testing | UI-only increments (design, styling, components) |
-| `microservice` | backend, testing, devops | Single-service increments with deployment concerns |
-
-Usage:
-
-```bash
-sw:team-lead --preset full-stack "Build checkout flow"
-sw:team-lead --preset api-only --max-agents 4 "Add payments API"
-```
-
-`--preset` supersedes the deprecated `sw:team-build` skill — same preset names are honoured here.
-
----
-
-## 0. Mode Detection (BEFORE Increment Pre-Flight)
-
-**Detect operating mode FIRST. This determines the entire workflow path.**
-
-### Detection Rules (priority order)
-
-1. **Explicit flag**: `--mode brainstorm|plan|implement|review|research|test`
-2. **team_name prefix**: `review-*`, `brainstorm-*`, `research-*`, `plan-*`, `test-*`
-3. **Intent keywords** in the user's request:
-
-| Keywords | Mode | Go To |
-|----------|------|-------|
-| "brainstorm", "ideate", "explore ideas", "what if", "pros and cons" | BRAINSTORM | Section 0a |
-| "plan", "spec", "design", "architect", "define requirements" | PLANNING | Section 0b |
-| "implement", "build", "code", "develop" *(or default)* | IMPLEMENTATION | Section 1 |
-| "review", "audit", "check code", "review PR", "code quality" | REVIEW | Section 0c |
-| "research", "investigate", "analyze", "explore codebase" | RESEARCH | Section 0d |
-| "test", "write tests", "test strategy", "test coverage" | TESTING | Section 0e |
-
-4. **Default**: IMPLEMENTATION mode if no keywords match.
-
-### Mode Configuration
-
-| Mode | Increment? | Agent Templates | Coordination | Output |
-|------|-----------|-----------------|--------------|--------|
-| BRAINSTORM | No | brainstorm-advocate, brainstorm-critic, brainstorm-pragmatist | Parallel → synthesize | Decision matrix |
-| PLANNING | Creates one | pm, architect (+ optional security reviewer) | PM + Architect parallel (Architect explores while PM specs) | spec.md, plan.md, tasks.md |
-| IMPLEMENTATION | Required | backend, frontend, database, testing, security | Contract-first phases | Working code |
-| REVIEW | Optional | Delegates to sw:code-reviewer | Parallel | Review report |
-| RESEARCH | No | researcher (1-3 instances) | Parallel → merge | Research report |
-| TESTING | Required | testing (split by layer) | Parallel | Test suites |
-
----
-
-### 0a. BRAINSTORM Mode
-
-**team_name**: `brainstorm-{topic-slug}`
-
-**Engine** (per §0.4): Agent Teams — brainstorm needs interactive steering + the idea tree, not a deterministic batch. Pattern: perspective-diverse verify (advocate / critic / pragmatist fan out → synthesize).
-
-Skip increment pre-flight entirely. Brainstorm doesn't need a spec — it explores possibilities.
-
-1. Create team: `TeamCreate({ team_name: "brainstorm-{slug}", description: "Brainstorm: {topic}" })`
-2. Read agent templates from `agents/brainstorm-advocate.md`, `agents/brainstorm-critic.md`, `agents/brainstorm-pragmatist.md`
-3. Replace `[BRAINSTORM_QUESTION]` with the user's question/topic
-4. Spawn all 3 agents in parallel — each call MUST include `team_name` so agents join the team (and get tmux panes):
-   ```
-   Task({
-     team_name: "brainstorm-{slug}",
-     name: "brainstorm-advocate",
-     subagent_type: "general-purpose",
-     mode: "bypassPermissions",
-     prompt: <replaced brainstorm-advocate.md content>
-   })
-   Task({
-     team_name: "brainstorm-{slug}",
-     name: "brainstorm-critic",
-     subagent_type: "general-purpose",
-     mode: "bypassPermissions",
-     prompt: <replaced brainstorm-critic.md content>
-   })
-   Task({
-     team_name: "brainstorm-{slug}",
-     name: "brainstorm-pragmatist",
-     subagent_type: "general-purpose",
-     mode: "bypassPermissions",
-     prompt: <replaced brainstorm-pragmatist.md content>
-   })
-   ```
-5. **PASSIVE WAIT (CRITICAL)**: Do NOT apply §8b stuck detection to brainstorm agents.
-   Brainstorm agents send `STATUS:` heartbeats (not task-granularity `T-{N}/{total}`).
-   Wait patiently for `PERSPECTIVE_COMPLETE:` messages — expected 2-5 minutes per agent.
-   **Do NOT send STATUS_CHECK or shutdown_request** while agents are working.
-   The only valid intervention is responding to `BLOCKING_ISSUE:` messages.
-6. Collect ALL 3 `PERSPECTIVE_COMPLETE:` messages before proceeding. Do NOT start synthesis after receiving only 1 or 2.
-7. Synthesize perspectives into a decision matrix:
-   - Compare approaches across dimensions (effort, risk, value, alignment)
-   - Highlight points of agreement and disagreement
-   - Provide a ranked recommendation
-8. Offer handoff: "Ready to proceed? Run `sw:increment` to formalize the chosen approach."
-9. **Cleanup (ALL 3 phases from Step 9 — NEVER skip Phase 3)**:
-   - Phase 1: Send `shutdown_request` to each agent
-   - Phase 2: `TeamDelete()` (retry once after 3s if it fails)
-   - Phase 3: Run the orphaned pane safety net bash script from Step 9 — `SendMessage` shutdown does NOT close tmux panes, this script is the ONLY thing that does
-10. **STOP** — do not proceed to implementation sections
-
----
-
-### 0b. PLANNING Mode
-
-**team_name**: `plan-{feature-slug}`
-
-Planning mode runs PM and Architect agents in parallel for richer, faster spec creation.
-
-1. **Check for existing increment**:
-   - If increment exists: read it as context, agents will update/enhance its spec and plan
-   - If no increment: create one (folder + metadata.json only, agents will write spec/plan)
-
-2. **Spawn PM + Architect in parallel** (TRUE parallelism):
-   - Read `agents/pm.md`, replace `[INCREMENT_ID]`, `[MASTER_INCREMENT_PATH]`, `[FEATURE_DESCRIPTION]`
-   - Read `agents/architect.md`, replace `[INCREMENT_ID]`, `[MASTER_INCREMENT_PATH]`
-   - **Spawn BOTH in a single step — each call MUST include `team_name`:**
-     ```
-     Task({
-       team_name: "plan-{feature-slug}",
-       name: "pm-agent",
-       subagent_type: "general-purpose",
-       mode: "bypassPermissions",
-       prompt: <replaced pm.md content>
-     })
-     Task({
-       team_name: "plan-{feature-slug}",
-       name: "architect-agent",
-       subagent_type: "general-purpose",
-       mode: "bypassPermissions",
-       prompt: <replaced architect.md content>
-     })
-     ```
-   - PM writes spec.md with user stories and ACs
-   - Architect starts codebase exploration immediately (does NOT need spec.md for this)
-   - Architect polls for spec.md, reads it when PM finishes, then designs architecture
-   - Optionally read `agents/reviewer-security.md`, replace `[REVIEW_TARGET]` with the spec, spawn Security reviewer after PM signals `PLAN_READY:`
-   - Wait for all agents' `COMPLETION:` messages
-
-   **Why this works**: Architect's workflow has two phases — exploration (no spec.md needed)
-   and design (needs spec.md). By spawning both agents simultaneously, the Architect's
-   exploration phase (~30s) overlaps with PM's spec writing, reducing total wall-clock time.
-
-4. **Post-planning**:
-   - Run `specweave sync-living-docs {increment-id}` to sync external tools
-   - Present the spec + plan summary to the user
-   - Recommend execution strategy: `sw:do`, `sw:auto`, or `sw:team-lead` (implementation mode)
-
-5. **Cleanup (ALL 3 phases from Step 9 — NEVER skip Phase 3)**:
-   - Phase 1: Send `shutdown_request` to each agent
-   - Phase 2: `TeamDelete()` (retry once after 3s if it fails)
-   - Phase 3: Run the orphaned pane safety net bash script from Step 9 — `SendMessage` shutdown does NOT close tmux panes, this script is the ONLY thing that does
-6. **STOP** — do not proceed to implementation sections
-
----
-
-### 0c. REVIEW Mode
-
-**Delegates entirely to `sw:code-reviewer`.**
-
-Team-lead does NOT spawn its own reviewer agents for review mode. The code-reviewer skill handles its own orchestration with 6 specialized reviewers.
-
-```typescript
-Skill({ skill: "sw:code-reviewer", args: "<user's review target or flags>" })
-```
-
-Pass through any arguments the user provided (--pr N, --changes, --cross-repo, path).
-
-**STOP** after the skill completes — do not proceed to implementation sections.
-
----
-
-### 0d. RESEARCH Mode
-
-**team_name**: `research-{topic-slug}`
-
-**Engine** (per §0.4): prefer a **Dynamic Workflow** deep-research pipeline (fan-out searches → fetch → adversarially verify → synthesize a cited report, results held off-context) for multi-source / multi-subtopic research; use Agent Teams only for 2-3 steerable researchers. Falls back to Agent Teams when `quality.workflows.enabled` is off.
-
-Skip increment pre-flight. Research is exploratory — no spec needed.
-
-1. Create team: `TeamCreate({ team_name: "research-{slug}", description: "Research: {topic}" })`
-2. **Determine research agents**:
-   - Single topic: spawn 1 researcher from `agents/researcher.md`
-   - Multi-faceted topic: spawn 2-3 researchers with different scopes
-     (e.g., "research auth" → one agent on OAuth providers, one on session management, one on security best practices)
-3. Replace `[RESEARCH_TOPIC]` and `[RESEARCH_SCOPE]` in each agent prompt
-4. Spawn all researchers in parallel — each call MUST include `team_name`:
-   ```
-   Task({
-     team_name: "research-{slug}",
-     name: "researcher-{scope}",
-     subagent_type: "general-purpose",
-     mode: "bypassPermissions",
-     prompt: <replaced researcher.md content>
-   })
-   ```
-5. Collect `RESEARCH_COMPLETE:` messages
-6. Merge findings into a unified research report:
-   - Cross-reference findings between agents
-   - Resolve contradictions
-   - Produce ranked recommendations
-7. Offer handoff: `sw:increment` (to act on findings) or `sw:brainstorm` (to explore approaches)
-8. **Cleanup (ALL 3 phases from Step 9 — NEVER skip Phase 3)**:
-   - Phase 1: Send `shutdown_request` to each agent
-   - Phase 2: `TeamDelete()` (retry once after 3s if it fails)
-   - Phase 3: Run the orphaned pane safety net bash script from Step 9 — `SendMessage` shutdown does NOT close tmux panes, this script is the ONLY thing that does
-9. **STOP** — do not proceed to implementation sections
-
----
-
-### 0e. TESTING Mode
-
-**team_name**: `test-{increment-id}`
-
-**Engine** (per §0.4): route **many independent same-shape tests** to a **Dynamic Workflow** (generate → run → fix-loop until green); keep Agent Teams when test layers have setup dependencies. Falls back to Agent Teams when `quality.workflows.enabled` is off.
-
-Testing mode requires an increment (it needs to know WHAT to test).
-
-1. **Verify increment exists** (same as implementation mode — see below)
-2. Create team: `TeamCreate({ team_name: "test-{id}", description: "Testing: {increment}" })`
-3. Spawn testing agents split by layer:
-   - **Unit test agent**: read `agents/testing.md`, override scope to unit tests only
-   - **E2E test agent**: read `agents/testing.md`, override scope to E2E tests only
-   - Split scope via the agent prompt, not via separate templates
-4. Spawn both in parallel — each call MUST include `team_name`:
-   ```
-   Task({
-     team_name: "test-{id}",
-     name: "unit-test-agent",
-     subagent_type: "general-purpose",
-     mode: "bypassPermissions",
-     prompt: <replaced testing.md content with unit-test scope>
-   })
-   Task({
-     team_name: "test-{id}",
-     name: "e2e-test-agent",
-     subagent_type: "general-purpose",
-     mode: "bypassPermissions",
-     prompt: <replaced testing.md content with e2e scope>
-   })
-   ```
-5. Collect `COMPLETION:` messages
-6. Run test suites to verify: `npx vitest run` + `npx playwright test`
-7. Report results: pass/fail counts, coverage, uncovered ACs
-8. **Cleanup (ALL 3 phases from Step 9 — NEVER skip Phase 3)**:
-   - Phase 1: Send `shutdown_request` to each agent
-   - Phase 2: `TeamDelete()` (retry once after 3s if it fails)
-   - Phase 3: Run the orphaned pane safety net bash script from Step 9 — `SendMessage` shutdown does NOT close tmux panes, this script is the ONLY thing that does
-9. **STOP** — do not proceed to implementation sections
-
----
-
-## 0.4. Orchestration Engine Selection (AUTO-DETECT — never wait for a flag)
-
-**Run AFTER §0 Mode Detection, BEFORE §0.5 Increment Pre-Flight.** Pick the engine from the *shape* of the work, not from the user's words. The user must NEVER have to say "use a workflow" — you infer it.
-
-Three engines:
-
-| Engine | What it is | Owns |
-|--------|-----------|------|
-| **Dynamic Workflow** | `Workflow()` — deterministic JS scheduler, ≤16 concurrent / 1000 total subagents, results in script vars (off context), resumable, background | Large homogeneous fan-out: migrations, repo-wide audits, many-similar-tests, adversarial/judge verification |
-| **Agent Teams** (default) | `TeamCreate` + `Task` + `SendMessage` + tmux — model-driven, domain-aware, SpecWeave-lifecycle owner | Feature work: 3+ domains or 15+ tasks with cross-domain contracts + closure + sync |
-| **Inline** | This orchestrator, no spawn | <15 tasks, single domain, sequential |
-
-### Decision table (first match wins)
-
-| Signal in the work | Engine | Why |
-|--------------------|--------|-----|
-| ≥~25 **same-shape** tasks, no cross-task deps (rename X→Y across N files, add header to N modules, port N tests) | **Dynamic Workflow** (top-level, bypass team-lead) | Pure fan-out under ONE budget + ONE scheduler — no glue needed |
-| Codebase **migration** / repo-wide **audit** / lint-sweep / dependency-bump across many files | **Dynamic Workflow** (top-level) | Domain-blind batch; team-lead's lifecycle is dead weight here |
-| High-stakes **verification** needing N independent checks (adversarial-verify, judge-panel, completeness-critic) | **Dynamic Workflow** (top-level) | Built-in reusable patterns; deterministic reduce |
-| **Deep research** spanning many sources/subtopics | **Dynamic Workflow** (pipeline) | fan-out → fetch → verify → synthesize, results off-context |
-| 3+ domains OR 15+ tasks **with cross-domain contracts** (frontend ⇐ OpenAPI ⇐ schema), needs increment activation + closure + GitHub/Jira/ADO sync | **Agent Teams** | Phased dependencies defeat fan-out; only team-lead owns the SpecWeave contract |
-| A single Agent-Teams **domain agent** discovers its OWN task list is a ≥~25 same-shape batch | Agent Teams **+ inner Workflow ×1** (see `agents/_protocol.md` Workflow Mode) | Legal one-level borrow; team-lead stays outer coordinator |
-| <15 tasks, 1 domain, sequential | **Inline** | Spawning overhead unjustified |
-
-### AUTO-DETECT signals (no flag required)
-
-- **→ Dynamic Workflow**: `migrate`, `migration`, `port`, `rename across`, `repo-wide`, `codebase-wide`, `audit`, `sweep`, `bulk`, `every file`, `all <N> …`, `double-check`, `verify independently`, `judge`, `tournament`, `deep research`, `survey the literature`, `ultracode` keyword / `/effort ultracode`.
-- **→ Agent Teams**: `build <feature>`, `team`, `parallel agents`, `multi-domain`, increment with 3+ domains, contracts (Prisma/OpenAPI/shared types) in scope, anything needing `sw:done`/sync.
-- **→ Inline**: small single-domain change, hotfix, one-file edit.
-
-### Guards (CHECK before routing to any Workflow)
-
-1. **Default-off** — if `quality.workflows.enabled` is absent or `false`, do NOT auto-fire a Workflow and do NOT honor the inner borrow; fall back to Agent Teams / inline (classic behavior, byte-for-byte). This is what keeps the enhancement non-destructive.
-2. **Budget gate** — read `quality.workflows.perRunTokenBudget` + `maxConcurrentWorkflows` from config. If a route would exceed either, DOWNGRADE to inline/sequential and tell the user.
-3. **Nesting law** — `Workflow()` allows ONE nesting level and THROWS inside a leaf subagent. Legal chain: `team-lead (orchestrator, not a Workflow) → Task member → Workflow ×1 → leaves (cannot nest)`. team-lead may fire a top-level Workflow OR delegate the borrow to a member — never both for the same work.
-4. **One top-level Workflow beats N nested ones** — for pure batch-class work, prefer a SINGLE top-level `Workflow` with `parallel()` over the items (one budget, one scheduler) instead of N domain agents each launching their own.
-5. **Inject SpecWeave context** — Workflow is domain-blind (zero knowledge of specs/ACs/increments/gates). Every Workflow-routed agent prompt MUST carry the increment path, file-ownership patterns, AC list, and contract artifacts, or it produces unanchored code.
-
-See `reference/dynamic-workflows.md` for primitives, quality patterns, and the full `quality.workflows` config schema.
-
----
-
-## 0.5. Increment Pre-Flight (IMPLEMENTATION and TESTING modes only)
-
-**This section applies only to IMPLEMENTATION mode (default) and TESTING mode.**
-All other modes handle their own increment logic (or skip it entirely) in Section 0a-0e above.
-
-The team-lead works best with an increment (spec.md, plan.md, tasks.md) but can also run **without one** in free-form mode.
-
-### Check: Is an increment required?
-
-**Free-form mode** (no increment needed) applies when:
-- `SPECWEAVE_NO_INCREMENT=1` is set (via `specweave team --no-increment`)
-- The user explicitly opted out of increment creation
-
-In free-form mode: **skip the rest of Section 0.5** and proceed directly to Step 1. Agents will work from the natural language description instead of a spec. Note: without a spec, `sw:done` closure is not available — the team-lead simply coordinates agent completion.
-
-### Standard mode: Verify increment exists
-
-```bash
-# Single-repo
-find .specweave/increments -maxdepth 2 -name "spec.md" 2>/dev/null | head -5
-
-# Multi-repo (umbrella)
-find repositories -path "*/.specweave/increments/*/spec.md" -maxdepth 6 2>/dev/null | head -5
-```
-
-### If NO increment exists → Auto-invoke sw:increment
-
-Do NOT ask permission. Invoke the increment skill with the user's feature description:
-
-```typescript
-Skill({ skill: "sw:increment", args: "the user's feature description" })
-```
-
-Wait for sw:increment to complete (spec.md, plan.md, tasks.md created and user exits plan mode).
-Then continue to Step 1.
-
-If sw:increment fails (user rejects plan, skill errors, etc.): **STOP. Do NOT proceed.**
-Report the failure to the user and ask them to run `sw:increment` manually.
-
-### If increment exists → Read the master spec
-
-Read the increment's spec.md. This is the **source of truth** for all agent work:
-- Scope and boundaries
-- User stories and acceptance criteria
-- Task breakdown and dependencies
-
-Store the increment path as `MASTER_INCREMENT_PATH` — you will reference it in agent prompts.
-
-**WHY THIS MATTERS**: Without a spec, agents infer scope from natural language alone.
-This leads to uncoordinated implementation, scope creep, and missing acceptance criteria.
-The spec-first principle exists because specs are the contract between user intent and agent execution.
-
-### Activate the Master Increment (MANDATORY — standard mode only)
-
-**Before spawning ANY agents**, transition the master increment to `"active"` status. The `specweave complete` command silently exits on increments with `"planned"` or `"backlog"` status — if you skip this step, closure will fail.
-
-```bash
-# Read current status
-STATUS=$(jq -r '.status' [MASTER_INCREMENT_PATH]/metadata.json)
-
-# If not already active, activate it
-if [ "$STATUS" != "active" ] && [ "$STATUS" != "ready_for_review" ]; then
-  # Edit metadata.json: set status to "active" and update lastActivity
-  Edit metadata.json:
-    "status": "planned" → "status": "active"
-    "lastActivity": "<current ISO timestamp>"
-fi
-```
-
-**Why**: Agents implement tasks but don't manage the increment lifecycle. The team-lead owns status transitions — activate before work begins, close after work completes.
-
----
-
-## 1. Tool Reference
-
-| Action | Tool | Parameters |
-|--------|------|------------|
-| Create team | `TeamCreate` | `team_name`, `description` |
-| Spawn agent | `Task` | `team_name`, `name`, `subagent_type`, `prompt`, `mode: "bypassPermissions"` |
-| Send message | `SendMessage` | `type`, `recipient`, `content`, `summary` |
-| Shutdown agent | `SendMessage` | `type: "shutdown_request"`, `recipient` |
-| Run batch fan-out | `Workflow` | `script` (a `meta` literal + `agent()`/`parallel()`/`pipeline()`) — for batch-class work per §0.4; see `reference/dynamic-workflows.md` |
-
----
-
-## 2. Domain-to-Skill Mapping
-
-Analyze the feature request and map affected domains to SpecWeave skills.
-
-| Domain | Primary Skill | Additional Skills | When to Use |
-|--------|--------------|-------------------|-------------|
-| **Frontend** | `sw:architect` | — | UI components, pages, client-side state |
-| **Backend** | `sw:architect` | `infra:devops` | API endpoints, services, business logic |
-| **Database** | `sw:architect` | | Schema design, migrations, seed data |
-| **Shared/Types** | `sw:architect` | `sw:code-simplifier` | TypeScript interfaces, shared constants, API contracts |
-| **Testing** | `sw:e2e` | `sw:tdd-red`, `sw:validate` | Test strategy, E2E suites, integration tests |
-| **Security** | `sw:security` | `security:patterns` | Auth, authorization, threat modeling, OWASP |
-| **DevOps** | `infra:devops` | `k8s:deployment-generate`, `infra:observability` | CI/CD, Docker, K8s, monitoring |
-| **Mobile** | `mobile:react-native` | `mobile:screen-generate`, `mobile:expo` | Native/cross-platform mobile apps |
-| **ML** | `ml:engineer` | `ml:pipeline`, `ml:deploy` | Model training, inference pipelines, deployment |
-
-### Auto-Detection Signals
-
-The orchestrator infers domains from the feature description and codebase structure (e.g., `src/components/` signals Frontend, `prisma/` signals Database, `src/api/` signals Backend, `tests/` signals Testing, auth-related keywords signal Security, Docker/K8s/CI files signal DevOps, React Native/Flutter signal Mobile, model/pipeline keywords signal ML).
-
----
-
-## 3. Contract-First Spawning Protocol
-
-Agents are NOT all spawned simultaneously. The orchestrator follows a two-phase dependency protocol to prevent integration conflicts.
-
-### Contract Artifacts
-
-| Artifact | Location | Producer | Consumers |
-|----------|----------|----------|-----------|
-| TypeScript interfaces | `src/types/` or `src/shared/types/` | Shared/Types agent | Frontend, Backend, Testing |
-| Prisma schema | `prisma/schema.prisma` | Database agent | Backend, Testing |
-| OpenAPI spec | `openapi.yaml` or `src/api/openapi.yaml` | Backend agent | Frontend, Testing |
-| GraphQL schema | `schema.graphql` | Backend agent | Frontend, Mobile |
-| API route types | `src/api/types/` | Backend agent | Frontend |
-
-### Organization Discovery (CRITICAL -- resolve BEFORE spawning agents)
-
-**The orchestrator MUST resolve the actual organization/owner name before spawning ANY agents.**
-All `{ORG}` placeholders below must be replaced with the real value.
-
-**Discovery chain (in order of priority):**
-
-1. **From config** (`repository.organization`):
-```bash
-ORG=$(jq -r '.repository.organization // empty' .specweave/config.json 2>/dev/null)
-```
-
-2. **From sync profiles** (fallback if repository.organization not set):
-```bash
-if [ -z "$ORG" ]; then
-  ORG=$(jq -r '[.sync.profiles[].config.owner // .sync.profiles[].config.organization] | map(select(. != null)) | first // empty' .specweave/config.json 2>/dev/null)
-fi
-```
-
-3. **From umbrella childRepos** (fallback):
-```bash
-if [ -z "$ORG" ]; then
-  ORG=$(jq -r '.umbrella.childRepos[0].path // empty' .specweave/config.json 2>/dev/null | sed 's|repositories/||' | cut -d/ -f1)
-fi
-```
-
-4. **From existing filesystem** (last resort):
-```bash
-if [ -z "$ORG" ]; then
-  ORG=$(ls -d repositories/*/ 2>/dev/null | head -1 | xargs basename 2>/dev/null)
-fi
-```
-
-5. **If all fail**: Ask the user. NEVER guess or use a placeholder.
-
-**NEVER read org from .env files.** Organization belongs in `.specweave/config.json`.
-
-### Multi-Repo Increment Placement (CRITICAL)
-
-**When `umbrella.enabled: true` in config.json, ALL increments go in the umbrella root `.specweave/increments/` — NOT in child repos.** Use the `project` field in metadata.json to route increments to the correct child repo context.
-
-```
-# CORRECT: All increments at umbrella root, tagged by project
-umbrella-project/
-├── .specweave/config.json
-├── .specweave/increments/
-│   ├── 0001-domain-models/     # metadata.json: "project": "sw-ecom-domain"
-│   ├── 0002-shared-types/      # metadata.json: "project": "sw-ecom-shared"
-│   └── 0003-api-endpoints/     # metadata.json: "project": "sw-ecom-api"
-├── repositories/
-│   ├── {ORG}sw-ecom-domain/   # NO .specweave/increments/ here
-│   ├── {ORG}sw-ecom-shared/   # NO .specweave/increments/ here
-│   └── {ORG}sw-ecom-api/      # NO .specweave/increments/ here
-
-# WRONG: Increments inside child repos
-umbrella-project/
-├── repositories/{ORG}sw-ecom-domain/
-│   └── .specweave/increments/0001-domain-models/    # WRONG!
-```
-
-**Rules:**
-- NEVER create `.specweave/increments/` inside child repos under `repositories/`
-- NEVER run `specweave init` in child repos — the umbrella root owns all increments
-- Each agent works on files inside its assigned repo in `repositories/`, but increments stay at umbrella root
-- Replace `{ORG}` with the actual organization discovered above
-
-### Phase 1: Upstream Agents (Contracts First)
-
-**Contract chain order**: shared/types -> database -> backend -> frontend (upstream before downstream).
-
-Spawn agents that produce shared contracts. These MUST complete before downstream agents begin.
-
-**Upstream agents** (spawn first, wait for completion):
-- **Shared/Types agent** -- produces TypeScript interfaces, enums, constants
-- **Database agent** -- produces Prisma schema, migration files, seed data
-
-```
-Phase 1: Upstream
-  ├── Shared/Types Agent -> produces interfaces, enums
-  └── Database Agent -> produces schema, migrations
-
-  [WAIT for Phase 1 completion via CONTRACT_READY messages]
-```
-
-### Phase 2: Downstream Agents (Consume Contracts)
-
-Once upstream contracts are established, spawn downstream agents in parallel.
-
-**Downstream agents** (spawn in parallel after Phase 1):
-- **Backend agent** -- consumes types and schema, produces API endpoints
-- **Frontend agent** -- consumes types and API contracts, produces UI
-- **Testing agent** -- consumes all contracts, produces test suites
-- **Security agent** -- consumes all code, produces security hardening
-- **DevOps agent** -- consumes all code, produces deployment config
-
-```
-Phase 2: Downstream (parallel)
-  ├── Backend Agent (reads types + schema)
-  ├── Frontend Agent (reads types + API spec)
-  ├── Testing Agent (reads all contracts)
-  ├── Security Agent (reads all code)
-  └── DevOps Agent (reads all code)
-```
-
-### No-Dependency Case
-
-If the feature has no cross-domain dependencies (e.g., purely frontend work with no new types), skip Phase 1 and spawn all agents in parallel immediately.
-
-### Spawn Decision Logic
-
-```
-Analyze domains
-  │
-  ├── Any upstream domains (shared/types, database)?
-  │     YES -> Phase 1: spawn upstream, wait for contracts
-  │           Phase 2: spawn downstream in parallel
-  │     NO  -> Spawn all agents in parallel (no dependency)
-  │
-  └── Single domain?
-        YES -> Spawn single agent, no orchestration needed
-```
-
----
-
-## 3b. Plan Review Workflow
-
-The team lead reviews agent plans **asynchronously**. Agents do NOT wait for approval — they proceed to implementation immediately after creating plans and sending a notification.
-
-### Why Async Review
-
-The previous blocking handshake (where agents waited for explicit approval before implementing) caused sessions to freeze:
-- When 3-5 Phase 2 agents spawned simultaneously, they ALL blocked waiting for a response
-- Team-lead had to review each plan sequentially while all agents sat idle
-- If team-lead was processing another message (or in a long reasoning pass), agents waited indefinitely
-- In tmux/iTerm2, this appeared as a completely frozen session
-
-Async review eliminates the bottleneck: agents proceed immediately, and the team-lead only intervenes when something is wrong.
-
-### Permission Mode: bypassPermissions (CRITICAL)
-
-**All agents MUST be spawned with `mode: "bypassPermissions"`.** This is required because:
-- Agents run as separate processes that encounter folder trust prompts
-- Trust prompts require interactive input that agents CANNOT provide
-- Without `bypassPermissions`, agents get STUCK waiting for trust confirmation and never execute
-- This applies to ALL agent spawns — upstream and downstream
-
-**NEVER use `mode: "plan"` for agent spawns** — it causes agents to block on the trust-folder prompt.
-
-### Protocol (Async Notify + Correct)
-
-**Agent side** (built into every agent prompt template):
-1. Read the increment spec and explore the codebase
-2. Create plan files (spec.md, plan.md, tasks.md) in the increment directory
-3. Send a structured plan notification to team-lead:
-```
-SendMessage({
-  type: "message",
-  recipient: "team-lead",
-  content: "PLAN_READY: Created .specweave/increments/[ID]/\nTasks: [count]\nACs covered: [list AC-IDs]\nKey decisions: [1-2 sentence summary]\nFiles to create/modify: [file list]\nArchitecture: [pattern/approach chosen]",
-  summary: "Plan ready — proceeding to implementation"
-});
-```
-4. **Proceed to implementation IMMEDIATELY.** Do NOT wait for any response.
-5. If team-lead sends `PLAN_CORRECTION` during implementation:
-   - **Finish the current task** (don't leave half-done code)
-   - Read the correction and update plan.md/tasks.md accordingly
-   - Send `STATUS: Applied PLAN_CORRECTION. Revised [what changed]. Continuing from T-{N}.`
-   - Resume implementation with the revised plan
-
-**Team-lead side**:
-1. Receive `PLAN_READY` notification from agent
-2. Review using the **structured summary in the message** (do NOT read full plan files unless a concern is detected)
-3. Quick-evaluate:
-   - Do the covered ACs match what this agent should handle?
-   - Are the files within this agent's ownership boundaries?
-   - Do any key decisions conflict with other agents' plans?
-   - Is the task count reasonable (<15)?
-4. If plan looks good: **do nothing** — agent is already implementing
-5. If plan has issues: send correction:
-
-```
-// Correct a plan issue (agent is already implementing)
-SendMessage({
-  type: "message",
-  recipient: "database-agent",
-  content: "PLAN_CORRECTION: 1) Add index on user_id for sessions. 2) You're missing AC-US1-03 — add a task for it. Pause current work and revise before continuing.",
-  summary: "Plan needs correction"
-});
-```
-6. If agent ignores `PLAN_CORRECTION` (continues without revising after 2 turns):
-```
-SendMessage({ type: "shutdown_request", recipient: "database-agent" });
-// Report to user: "Agent ignored correction, shutting down. Manual intervention needed."
-```
-
-### Review Priorities
-
-Not all plans need deep review. Prioritize:
-- **Phase 1 (upstream) plans** — errors here cascade to all downstream agents
-- **Plans with >10 tasks** — higher risk of scope creep
-- **Plans touching shared files** — ownership conflicts
-- **Single-agent teams** — skip review entirely (no coordination needed)
-
-### Multi-Increment Consideration
-
-For very large features, the team lead MAY split work into multiple increments per domain for better tracking and independent closure. Decide this during initial analysis (Step 1), before spawning agents.
-
-### Task Cap Per Agent (CRITICAL — Context Overflow Prevention)
-
-**Maximum 40 tasks per agent** (`TASK_CAP = 40`). Raised in SpecWeave 1.1.0 from the previous cap: Opus 4.7's long-horizon coherence improvements mean agents can maintain coherent context across 40 tasks without degradation.
-
-When distributing tasks from the master spec:
-1. Count tasks per domain
-2. If a domain has >40 tasks: **split into 2 agents** (e.g., `jira-agent-a`, `jira-agent-b`) with non-overlapping task ranges
-3. If splitting isn't natural, group tasks into phases and create 2 increments per domain
-
-```
-Domain tasks analysis:
-  Frontend: 32 tasks -> 1 agent (OK)
-  Backend:  18 tasks -> 1 agent (OK)
-  JIRA:     55 tasks -> SPLIT into 2 agents (tasks 1-28, tasks 29-55)
-```
-
-**Why**: Each auto-mode iteration adds context (spec reads, edits, test outputs). Prior to 4.7, a 15-task cap was necessary because older models entered deep reasoning loops and effectively hung past ~20 tasks. Opus 4.7's long-horizon coherence holds across substantially more work, so the safe budget is now 40. Above 40, we still split to prevent edge-case context blowups.
-
----
-
-## 4. Agent Spawn Prompt Templates
-
-Agent definitions live as reusable `.md` files in the `agents/` subdirectory. When spawning a domain agent, **Read the agent file and use its full content as the Task() prompt**, with placeholders replaced.
-
-### Agent Reference Table
-
-| Agent | File | Domain | Phase | Primary Skills |
-|-------|------|--------|-------|---------------|
-| Frontend | `agents/frontend.md` | UI, components, pages | 2 (downstream) | `sw:architect` |
-| Backend | `agents/backend.md` | API, services, middleware | 2 (downstream) | `sw:architect`, `infra:devops` |
-| Database | `agents/database.md` | Schema, migrations, seeds | 1 (upstream) | `sw:architect` |
-| Testing | `agents/testing.md` | Unit, integration, E2E | 2 (downstream) | `sw:e2e`, `sw:tdd-red` |
-| Security | `agents/security.md` | Auth, validation, audit | 2 (downstream) | `sw:security` |
-
-### How to Use Agent Files
-
-For each domain agent to spawn:
-
-1. **Read** the agent definition: `Read("agents/{domain}.md")`
-2. **Replace placeholders** in the content:
-   - `[INCREMENT_ID]` → the increment ID (e.g., `0042-checkout-flow`)
-   - `[MASTER_INCREMENT_PATH]` → full path to the master increment directory
-   - `{ORG}` → the discovered organization name
-   - `{repo-name}` → the assigned repository name
-3. **Spawn** via Task() with the replaced content as the prompt:
-   ```
-   Task({
-     team_name: "<team-name>",
-     name: "<domain>-agent",
-     subagent_type: "general-purpose",
-     mode: "bypassPermissions",
-     prompt: <replaced agent content>
-   })
-   ```
-
-**CRITICAL**: Always use `mode: "bypassPermissions"` — agents cannot handle interactive trust-folder prompts.
-
----
-
-## 5. File Ownership
-
-Each agent has exclusive WRITE access to specific file patterns. This prevents merge conflicts.
-
-### Ownership Map
-
-| Domain | WRITE Patterns | Notes |
-|--------|---------------|-------|
-| **Frontend** | `src/components/**`, `src/pages/**`, `src/hooks/**`, `src/styles/**`, `src/app/**`, `src/stores/**`, `public/**` | UI layer |
-| **Backend** | `src/api/**`, `src/services/**`, `src/middleware/**`, `src/routes/**`, `src/controllers/**` | API layer |
-| **Database** | `prisma/**`, `src/db/**`, `src/repositories/**`, `seeds/**`, `scripts/db/**` | Data layer |
-| **Shared/Types** | `src/types/**`, `src/shared/**`, `src/constants/**`, `src/utils/shared/**` | Contracts |
-| **Testing** | `tests/**`, `__tests__/**`, `e2e/**`, `**/*.test.ts`, `**/*.test.tsx`, `**/*.spec.ts`, `test-utils/**`, `fixtures/**` | All test files |
-| **Security** | `src/auth/**`, `src/middleware/auth*`, `src/middleware/security*`, `src/utils/crypto/**`, `src/utils/validation/**`, `security/**` | Auth and security |
-| **DevOps** | `.github/**`, `docker/**`, `Dockerfile*`, `docker-compose*`, `k8s/**`, `terraform/**`, `.gitlab-ci.yml`, `Makefile` | Infrastructure |
-| **Mobile** | `src/screens/**`, `src/navigation/**`, `ios/**`, `android/**`, `src/native/**` | Mobile app |
-| **ML** | `models/**`, `notebooks/**`, `src/ml/**`, `src/pipelines/**`, `data/**` | Machine learning |
-
-### Ownership Rules
-
-1. **WRITE only to files you own** -- agents must not modify files outside their ownership patterns
-2. **READ any file** -- all agents have unrestricted read access for context
-3. **Shared files require coordination** -- if two domains need to modify the same file (e.g., `package.json`), the orchestrator assigns a primary owner and others request changes via SendMessage
-4. **New files** -- agents can create new files ONLY within their ownership patterns
-5. **Conflict detection** -- the orchestrator checks for ownership overlap before spawning and resolves ambiguity upfront
-6. **Repository directory structure** -- for multi-repo setups, ALL repository cloning and creation MUST use the `repositories/{ORG}/` directory convention
-
----
-
-## 6. Communication Protocol
-
-Agents communicate contract readiness, blocking issues, and completion status using `SendMessage`.
-
-### Message Types
-
-| Prefix | Purpose | Sender | Receiver |
-|--------|---------|--------|----------|
-| `CONTRACT_READY:` | Upstream contract is published | Upstream agent | team-lead (broadcasts to downstream) |
-| `PLAN_READY:` | Plan created, agent proceeding to implementation | Any agent | team-lead (async review) |
-| `STATUS:` | Heartbeat — task progress update | Any agent | team-lead (stuck detection) |
-| `BLOCKING_ISSUE:` | Agent is stuck, needs help | Any agent | team-lead |
-| `COMPLETION:` | Agent finished all tasks | Any agent | team-lead |
-| `PLAN_CORRECTION:` | Plan needs revision (async) | team-lead | Specific agent |
-
-### Message Examples
-
-```typescript
-// Upstream agent signals contract is ready
-SendMessage({
-  type: "message",
-  recipient: "team-lead",
-  content: "CONTRACT_READY: TypeScript interfaces written to src/types/checkout.ts. Exports: CheckoutItem, CartSummary, PaymentIntent.",
-  summary: "Shared types contract ready"
-});
-
-// Agent notifies plan is ready (does NOT wait for response)
-SendMessage({
-  type: "message",
-  recipient: "team-lead",
-  content: "PLAN_READY: Created .specweave/increments/0202-checkout-backend/\nTasks: 8\nACs covered: AC-US1-01, AC-US1-02, AC-US2-01\nKey decisions: REST API with Express, JWT auth middleware\nFiles: src/api/checkout.ts, src/services/payment.ts, src/middleware/auth.ts\nArchitecture: Controller-Service-Repository pattern",
-  summary: "Backend plan ready — proceeding to implementation"
-});
-
-// Agent heartbeat after each task completion
-SendMessage({
-  type: "message",
-  recipient: "team-lead",
-  content: "STATUS: T-003/8 complete. Next: T-004 (implement payment service). Tests: 12/12 passing.",
-  summary: "Backend agent: task 3 of 8 done"
-});
-
-// Agent reports a blocking issue
-SendMessage({
-  type: "message",
-  recipient: "team-lead",
-  content: "BLOCKING_ISSUE: Cannot implement payment webhook -- Stripe webhook secret not found in .env. Need STRIPE_WEBHOOK_SECRET to proceed.",
-  summary: "Blocked on missing Stripe secret"
-});
-
-// Agent signals completion
-SendMessage({
-  type: "message",
-  recipient: "team-lead",
-  content: "COMPLETION: All 8 tasks done. Tests passing (24/24). Ready for team-lead closure.",
-  summary: "Frontend agent completed all tasks"
-});
-
-// Team-lead sends async plan correction (agent is already implementing)
-SendMessage({
-  type: "message",
-  recipient: "database-agent",
-  content: "PLAN_CORRECTION: 1) Add index on user_id for sessions table. 2) Missing AC-US1-03 — add a migration task. Pause and revise.",
-  summary: "Plan correction for database agent"
-});
-```
-
----
-
-## 7. Spawning Agents
-
-### Step 1: Create the Team
-
-```typescript
-TeamCreate({
-  team_name: "feature-checkout",
-  description: "Building checkout flow across frontend, backend, and database"
-});
-```
-
-### Step 2: Spawn Upstream Agents (Phase 1)
-
-All agents are spawned with `mode: "bypassPermissions"` to prevent blocking on trust-folder prompts. Agents notify team-lead of their plans via PLAN_READY but proceed to implementation immediately (see Section 3b for async review protocol).
-
-For each agent: **Read the agent definition file** (see Section 4 reference table), replace placeholders (`[INCREMENT_ID]`, `[MASTER_INCREMENT_PATH]`, `{ORG}`, `{repo-name}`), and use the full content as the Task() prompt.
-
-```typescript
-// Read agents/database.md, replace placeholders, then:
-Task({
-  team_name: "feature-checkout",
-  name: "database-agent",
-  subagent_type: "general-purpose",
-  mode: "bypassPermissions",
-  prompt: <content of agents/database.md with placeholders replaced>,
-});
-```
-
-### Step 3: Wait for Phase 1 CONTRACT_READY Messages
-
-Messages are delivered automatically via SendMessage from upstream agents.
-
-### Step 4: Spawn Downstream Agents (Phase 2)
-
-```typescript
-// Read agents/backend.md, agents/frontend.md, agents/testing.md
-// Replace placeholders, then spawn each:
-Task({
-  team_name: "feature-checkout",
-  name: "backend-agent",
-  subagent_type: "general-purpose",
-  mode: "bypassPermissions",
-  prompt: <content of agents/backend.md with placeholders replaced>,
-});
-
-Task({
-  team_name: "feature-checkout",
-  name: "frontend-agent",
-  subagent_type: "general-purpose",
-  mode: "bypassPermissions",
-  prompt: <content of agents/frontend.md with placeholders replaced>,
-});
-
-Task({
-  team_name: "feature-checkout",
-  name: "testing-agent",
-  subagent_type: "general-purpose",
-  mode: "bypassPermissions",
-  prompt: <content of agents/testing.md with placeholders replaced>,
-});
-```
-
----
-
-## 8. Quality Gates
-
-Quality gates are split: agents handle tests, team-lead handles closure (grill, done, judge-llm). This prevents context overflow in agents from loading 4+ additional skill definitions during closure.
-
-### Per-Agent Quality Gate (Lightweight)
-
-```
-Agent Workflow:
-  1. Execute all assigned tasks via sw:auto
-  2. Run all tests for owned code (unit + integration + E2E)
-  3. Run linter/type-check for owned code
-  4. If tests fail -> fix issues and repeat from step 2
-  5. Do NOT signal completion until all tests pass
-  6. Signal COMPLETION via SendMessage (include task count, test results summary)
-  7. Do NOT run sw:grill or sw:done — team-lead handles closure centrally
-```
-
-**Why agents don't run sw:done**: The sw:done skill invokes 4 sub-skills (grill, judge-llm, sync-docs, qa), each loading a full SKILL.md. After many tasks of auto-mode context, this pushes agents into deep reasoning loops (30+ min hangs). Closure is delegated to `sw-closer` subagents that run in a fresh context, avoiding overflow for both agents and the team-lead orchestrator.
-
-### Active Phase Responsibilities (While Agents Are Implementing)
-
-During the active phase (between spawning agents and receiving ALL COMPLETION signals), the team-lead focuses on orchestration:
-
-- Process SendMessage from agents (PLAN_READY, STATUS, CONTRACT_READY, BLOCKING_ISSUE, COMPLETION).
-- Async plan review (read PLAN_READY summaries, send PLAN_CORRECTION if needed).
-- Track heartbeat STATUS per agent for stuck detection.
-- Respond to BLOCKING_ISSUE messages.
-- Send STATUS_CHECK to silent agents.
-- Shutdown stuck agents and spawn replacements for the same domain on remaining tasks.
-
-Closure operations (grill, done, judge-llm) are performed by `sw-closer` subagents spawned from the closure phase below, not by the orchestrator itself. The orchestrator avoids calling `TeamDelete()` while agents are still running — that kills every live agent.
-
-### Orchestrator Quality Gate — Closure Phase (SIMPLIFIED)
-
-**Closure begins ONLY after ALL agents have signaled COMPLETION (or been declared stuck).**
-
-**Do NOT manually run grill/done per increment — spawn `sw-closer` subagents instead.**
-
-```
-AFTER ALL AGENTS COMPLETE:
-  1. Verify ALL agents signaled COMPLETION (no unresolved BLOCKING_ISSUE)
-  2. Determine closure order from team topology (shared → backend → frontend)
-  3. For each increment in dependency order, spawn sw-closer subagent:
-     Agent({
-       subagent_type: "sw:sw-closer",
-       prompt: "Close increment <ID>. Increment path: .specweave/increments/<ID>/",
-       description: "Close increment <ID>"
-     })
-  4. Wait for each sw-closer to complete before spawning the next (dependency order)
-  5. If an sw-closer fails, log the failure and continue to the next increment
-  6. Run Step 9 cleanup (TeamDelete + kill tmux panes)
-```
-
-**CRITICAL**: Do NOT attempt inline closure (grill → done → retry loops) yourself.
-Spawn `sw-closer` subagents instead — each runs in a fresh context with only the `sw:done` skill loaded, avoiding the context overflow that caused the "stuck after first agent" bug.
-
-**If all sw-closer subagents fail**, report the failures to the user with the error messages. Do NOT retry inline.
-
-### Grill Checklist per Domain
-
-| Domain | Grill Checks |
-|--------|-------------|
-| Frontend | Components render, no console errors, accessibility, responsive |
-| Backend | API endpoints return correct status codes, validation works, error handling |
-| Database | Migrations apply cleanly, seed data loads, rollback works |
-| Testing | All tests pass, coverage threshold met, no flaky tests |
-| Security | No exposed secrets, input validation, auth working |
-| DevOps | Docker builds, CI passes, deployment config valid |
-
----
-
-## 8b. Agent Timeout and Stuck Detection (Heartbeat-Based)
-
-Agents send `STATUS: T-{N}/{total}` heartbeat messages after each task completion. The team-lead uses these to detect stuck agents proactively.
-
-### Heartbeat Tracking
-
-The team-lead maintains a mental log of the last STATUS received from each agent:
-
-```
-Agent Heartbeat Log (example):
-  backend-agent:  STATUS: T-003/8  (last seen: 2 turns ago)
-  frontend-agent: STATUS: T-005/12 (last seen: this turn)
-  database-agent: COMPLETION       (done)
-  testing-agent:  STATUS T-001/6  (last seen: 4 turns ago) ← STUCK?
-```
-
-### Stuck Detection Rules
-
-**Note**: Claude Code has no built-in timers. Heartbeats are tracked relative to team-lead turns (each time the orchestrator processes messages). Time thresholds below are approximate wall-clock estimates based on typical turn cadence.
-
-| Condition | Wall-clock estimate | Action |
-|-----------|---------------------|--------|
-| Agent sent STATUS within the current no-progress window | ≤ 5 min | Healthy — no action needed |
-| No STATUS / no progress from agent for the no-progress window | ~5 min | Send `STATUS_CHECK` message to agent |
-| No STATUS / no response to STATUS_CHECK for the total-stuck window | ~20 min | Declare agent stuck |
-| Agent sends STATUS but task number hasn't advanced for 3+ heartbeats | — | Stuck in loop — declare stuck |
-| All agents stuck | — | STOP team, report to user |
-
-**Window rationale**: Raised from 2min/10min to 5min/20min in SpecWeave 1.1.0 — Opus 4.7's long-horizon coherence means legitimate pauses (tool use, extended reasoning, long file writes) are longer, so the old 2min window produced false stuck-detection on otherwise-healthy agents. Override via `quality.stuckDetection.{noProgressMin, totalStuckMin}` in `.specweave/config.json`.
-
-### Stuck-in-Loop Detection
-
-An agent may appear to send heartbeats but actually be looping on the same task (e.g., test fails → fix → test fails → fix → ...). To detect this:
-
-- Track the task number in each STATUS message
-- If the same task number appears in 3+ consecutive STATUS messages from the same agent, the agent is stuck in a loop
-- Action: send a message to the agent with guidance, or declare stuck if the loop continues
-
-### Stuck Agent Recovery
-
-When an agent is declared stuck:
-1. Do NOT wait for it — proceed with other agents
-2. Note the stuck agent's increment ID and last known task progress (from last STATUS)
-3. Send shutdown_request to the stuck agent to free resources
-4. During closure phase, the stuck agent's increment is left open for manual completion
-
-### Preventing Stuck Agents
-
-- Enforce the 40-task cap (Section 3b) — split larger work across multiple agents
-- Agents do NOT run sw:done (team-lead handles closure centrally)
-- Heartbeat STATUS messages let team-lead detect problems early instead of after long silences
-- If an agent's task count exceeds 40 despite the cap, split before spawning
-
-### Workflow-Aware Stuck Detection (agent borrowing a Workflow)
-
-A domain agent that borrows a Workflow (see `agents/_protocol.md` Workflow Mode) goes **silent for minutes** while the background run executes — the normal 5min/20min windows would false-kill a healthy agent. Additive handling:
-
-1. **Delegation state** — when an agent's STATUS contains `DELEGATING … workflow_id=`, mark it `state=workflow-delegating` and record the `workflow_id`. SUSPEND the normal 5/20 windows.
-2. **Extended windows** — while delegating, apply `quality.workflows.stuckDetection.{workflowNoProgressMin, workflowTotalStuckMin}` (defaults 20min / 60min) instead. Silence here is expected, not stuck.
-3. **Clear on completion** — a `STATUS: WORKFLOW_DONE` (or a `BLOCKING_ISSUE` citing the same `workflow_id`) restores `state=active` and the normal 5/20 windows from the next heartbeat.
-4. **Probe before kill** — if `workflowTotalStuckMin` elapses with no `WORKFLOW_DONE`, send ONE `STATUS_CHECK` asking the agent to report the Workflow's own progress (it is resumable/background). Declare stuck only after a second unanswered probe; prefer leaving the increment open over killing mid-batch.
-5. **Loop-detection unchanged** — the "same task number 3+ heartbeats = stuck loop" rule still applies to NON-delegating agents; a delegating agent emits no task-number heartbeats and is exempt by construction.
-
-**Default-off**: with no `quality.workflows` config, no agent ever enters `state=workflow-delegating`, so behavior is identical to today.
-
----
-
-## 9. Workflow Summary
-
-```
-sw:team-lead "Build checkout flow"
-  │
-  ├── Step 0: VERIFY INCREMENT EXISTS (BLOCKING)
-  │     ├── Found? → Read master spec.md as source of truth
-  │     └── Missing? → Auto-invoke sw:increment, wait for completion
-  ├── Step 0b: ACTIVATE MASTER INCREMENT (MANDATORY)
-  │     └── Edit metadata.json: set status to "active" BEFORE spawning agents
-  ├── Step 1: Analyze feature (from master spec) → identify domains → decide increment split
-  ├── Step 2: Create team via TeamCreate
-  ├── Step 3: Create per-domain increments (derived from master spec)
-  │
-  │ ── ACTIVE PHASE (agents implementing, team-lead monitoring) ──
-  │
-  ├── Step 4: Contract-first spawning (all agents with mode: "bypassPermissions")
-  │     ├── Phase 1: Spawn shared + database
-  │     │     └── Agents send PLAN_READY notification → proceed immediately
-  │     │     └── Team-lead reviews async, sends PLAN_CORRECTION only if needed
-  │     │     └── Wait for CONTRACT_READY
-  │     └── Phase 2: Spawn backend + frontend + testing
-  │           └── Agents send PLAN_READY notification → proceed immediately
-  ├── Step 5: Monitor progress via STATUS heartbeats
-  │     ├── Track per-agent: last STATUS task number and turn count
-  │     ├── No STATUS for 2 turns → send STATUS_CHECK
-  │     ├── No STATUS for 3 turns or same task 3+ times → declare stuck
-  │     └── DO NOT run grill/done/closure during this phase
-  ├── Step 6: Collect all COMPLETION signals (or declare remaining agents stuck)
-  │
-  │ ── CLOSURE PHASE (all agents done) ──
-  │
-  ├── Step 7: Spawn sw-closer subagents per increment (fresh context closure)
-  ├── Step 8: Shutdown agents → TeamDelete() → orphaned pane safety net (Step 9 below)
-  └── Done.
-```
-
-**IMPORTANT**: The intended entry point is: `sw:increment` → `sw:do` (detects 3+ domains) → `sw:team-lead`.
-Direct invocation of `sw:team-lead` without an existing increment will trigger the guard and auto-invoke `sw:increment`.
-
-### Step 9: Post-Completion Cleanup (MANDATORY — NEVER SKIP)
-
-**After delivering results OR after all sw-closer subagents complete, clean up the team.**
-
-#### Phase 1: Graceful Agent Shutdown
-
-Send `shutdown_request` to every agent you spawned. You know their names — you spawned them via `Task()`.
-
-```typescript
-// Replace with your actual agent names from this session
-SendMessage({ type: "shutdown_request", recipient: "<agent-1-name>", content: "Team work complete" });
-SendMessage({ type: "shutdown_request", recipient: "<agent-2-name>", content: "Team work complete" });
-// ... for every agent you spawned
-```
-
-Harmless if agents already exited. **NOTE**: `shutdown_request` via `SendMessage` does NOT close the tmux pane — the agent's Claude process exits but the pane persists with "Resume this session". Phase 3 below is the ONLY mechanism that actually kills orphaned panes. **NEVER skip Phase 3.**
-
-#### Phase 2: Destroy Team
-
-```typescript
-TeamDelete();
-```
-
-If `TeamDelete` fails (agents still shutting down), wait 3 seconds, retry once.
-
-#### Phase 3: Kill Orphaned Panes (MANDATORY — this is the ONLY thing that closes tmux panes)
-
-`SendMessage` shutdown does NOT close tmux panes. Agent processes exit but panes persist showing "Resume this session". **This bash script is the ONLY cleanup mechanism. ALWAYS run it.**
-
-```bash
-if command -v tmux >/dev/null 2>&1; then
-  CURRENT_PANE=$(tmux display-message -p '#{pane_id}' 2>/dev/null || echo "")
-  for pane_id in $(tmux list-panes -a -F '#{pane_id}' 2>/dev/null); do
-    [ -n "$CURRENT_PANE" ] && [ "$pane_id" = "$CURRENT_PANE" ] && continue
-    if tmux capture-pane -t "$pane_id" -p -S -50 2>/dev/null | grep -q "Resume this session"; then
-      tmux kill-pane -t "$pane_id" 2>/dev/null
-    fi
-  done
-fi
-```
-
-**Key**: Removed `$TMUX` guard — even if the orchestrator isn't inside tmux itself, agent panes still exist in tmux and need cleanup. The `tmux` command can manage external sessions.
-
-### --dry-run Output
-
-When `--dry-run` is specified, display the proposed plan without executing.
-**Do NOT call TeamCreate in dry-run mode** — just show the formatted plan text.
-
-```
-Team Orchestration Plan (DRY RUN)
-==================================================
-Feature: Build checkout flow | Domains: 4
-
-Phase 1 (upstream):
-  1. shared-types -> sw:architect, sw:code-simplifier  | Increment: 0200-checkout-shared
-  2. database     -> sw:architect                 | Increment: 0201-checkout-database
-
-Phase 2 (downstream, parallel):
-  3. backend      -> sw:architect, infra:devops              | Increment: 0202-checkout-backend
-  4. frontend     -> sw:architect                           | Increment: 0203-checkout-frontend
-
-Max agents: 4 (2 sequential + 2 parallel)
-To execute, run without --dry-run.
-```
-
----
-
-## 10. Troubleshooting
-
-| Issue | Cause | Fix |
-|-------|-------|-----|
-| **TeamCreate blocked by guard** | No increment with spec.md exists | Run `sw:increment "feature"` first, then retry `sw:team-lead`. The guard requires a substantive spec.md (>200 bytes, not a template) |
-| **Agent stuck on trust folder** | Agent spawned without `bypassPermissions` | ALWAYS use `mode: "bypassPermissions"` — NEVER `mode: "plan"`. Trust prompts require interactive input agents cannot provide |
-| **Session freezes after first agent completes** | Closure ran during active phase (pre-v0528 bug) | Ensure §8 active-phase rules are followed: NO grill/done until ALL agents signal COMPLETION |
-| **Agent proceeds with wrong plan** | Async model means agents don't wait for approval | Send `PLAN_CORRECTION` immediately; agent should pause and revise. If ignored, send `shutdown_request` |
-| **No heartbeat STATUS from agent** | Agent didn't implement heartbeat or is stuck | Check if agent template includes heartbeat step. If yes, agent is stuck — send STATUS_CHECK, then declare stuck after 3 turns |
-| **Agent stuck in loop (same task repeated)** | Test fail → fix → test fail cycle | Heartbeat shows same task number 3+ times. Send guidance message or declare stuck |
-| **Agents editing same files** | Overlapping file ownership patterns | Review ownership map; reassign conflicting files to a single owner; use `--dry-run` to validate before launch |
-| **Token cost too high** | Too many agents or overly large prompts | Reduce `--max-agents`; use `--domains` to limit scope; split feature into smaller increments |
-| **Agent stuck in long reasoning loop** | Too many tasks causing context overflow | Enforce the per-agent task cap (`TASK_CAP` = 40 in 1.1.0); split large domains into 2 agents; agents use `--simple-compat` mode |
-| **Agent hung on sw:done** | Closure loads 4+ skill definitions into already-full context | Agents should NOT run sw:done — team-lead spawns `sw-closer` subagents (fresh context) for closure |
-| **Contract agent takes too long** | Large schema or complex type system | Set a timeout in the agent prompt; if stuck >15 min, check agent output and consider splitting the contract work |
-| **Phase 2 starts before Phase 1 finishes** | CONTRACT_READY not received yet | Ensure upstream agents send CONTRACT_READY via SendMessage before team-lead spawns downstream |
-| **Agent fails mid-task** | Build error, test failure, or dependency issue | Send message to agent to fix; restart the agent with `sw:auto` on its increment |
-| **`specweave complete` exits silently** | metadata.json status is "planned" (not "active") | Agents don't manage lifecycle status. Team-lead MUST activate the increment before spawning agents (see Step 0). Fix: edit metadata.json to set `"status": "active"` before running `specweave complete` |
-| **Closure fails on multiple increments** | Quality gates fail (grill, desync, missing reports) | Each `sw-closer` subagent retries once automatically. If still failing, use `/sw:close-all` for batch retry |
-
----
-
-## 11. Examples
-
-### Example 1: Full-Stack Feature
-
-```
-User: sw:team-lead "Build user authentication with login, signup, password reset, and OAuth"
-
-Orchestrator detects domains: shared/types, database, backend, frontend, testing, security
-Creates 6 increments.
-
-Phase 1:
-  - shared-types agent: Auth types (User, Session, AuthToken interfaces)
-  - database agent: User table, Session table, Prisma migrations
-
-Phase 2 (after contracts ready):
-  - backend agent: /api/auth/login, /api/auth/signup, /api/auth/reset, OAuth flow
-  - frontend agent: LoginForm, SignupForm, ResetPasswordForm, OAuthButton
-  - testing agent: Unit tests, E2E login flow, E2E signup flow
-  - security agent: Password hashing, JWT validation, rate limiting, CSRF
-```
-
-### Example 2: Frontend-Only (No Dependencies)
-
-```
-User: sw:team-lead "Redesign dashboard" --domains frontend,testing
--> No upstream dependencies. Both agents spawn in parallel immediately.
-```
-
-### Example 3: Dry Run
-
-```
-User: sw:team-lead "Add payment processing" --dry-run
--> Shows plan with domains, phases, file ownership. No agents spawned.
-```
-
----
-
-## Related Skills
-
-| Skill | Purpose |
-|-------|---------|
-| `sw:team-status` | Show progress of all agents in the current team session |
-| `sw:team-merge` | Merge completed agent work in dependency order |
-| `sw:auto` | Autonomous execution (single-agent mode) |
-| `sw:architect` | System architecture and ADRs |
-| `sw:grill` | Quality validation gate |
-
-## Resources
-
-- [Official Documentation](https://verified-skill.com/docs/reference/skills#team-lead)