@orchestrator-claude/definitions 3.30.1 → 3.31.0

package/skills/project-management-enterprise/SKILL.md

@@ -0,0 +1,304 @@
+---
+name: project-management-enterprise
+description: PME workflow runtime playbook. Load when: "PME workflow", "consultoria", "consultoria externa", "consultoria interna", "software handoff", "cirurgico", "variant=consultoria-externa", or when starting/advancing a project_management_enterprise workflow. Provides variant selection guide, gate intensity tuning, persona pairing strategy, adversarial review iteration playbook, and phase lifecycle reference.
+allowed-tools: Read
+---
+
+# Skill: /project-management-enterprise (PME Workflow Runtime Playbook)
+
+> **Scope:** this skill is loaded by the orchestrator when a `project_management_enterprise` workflow is being started, advanced, or evaluated. It covers variant selection, gate intensity, persona pairing, and adversarial review iteration. Orchestrator runtime call signatures live in `/orchestrator`. Universal invariants live in `CLAUDE.md`. The variant mechanic is governed by **ADR-020** and implemented in **RFC-031**; this skill is the operator guide for the PME consumer defined in **RFC-032**.
+
+---
+
+## When to Use This Skill
+
+Load this skill when **any** of the following apply:
+
+- User requests a "PME workflow", "consultoria", "consultoria externa", "consultoria interna", or "engajamento externo"
+- User says "software handoff", "cirurgico", or "intervencao cirurgica"
+- A `startWorkflow` call includes `type: "project_management_enterprise"`
+- The prompt contains `variant=consultoria-externa`, `variant=consultoria-interna`, `variant=software-handoff`, or `variant=cirurgico`
+- The orchestrator is advancing any of the five PME phases: DISCOVERY, RESEARCH, FRAMEWORK, OPERATIONAL, DELIVER
+- The adversarial gate fires on the RESEARCH phase exit and guidance is needed on iteration protocol
+
+**Do NOT load for:**
+
+- `feature_development` workflows — use `/orchestrator` alone
+- `bug_fix`, `refactoring`, or `emergency_debug` workflows
+- Deliverable file generation — use `/artifact-generator` for xlsx/pdf/csv/docx output
+- Markdown spec/plan/task authoring — use `/artifact-production`
+
+---
+
+## Variant Selection Guide
+
+Use this section to choose the correct variant at `startWorkflow` time. The variant is immutable once set; pre-flight validation rejects unknown or empty variant names (RFC-032 §9 error code `VARIANT_NOT_FOUND` / `EMPTY_VARIANT_NAME`).
+
+### Variant Matrix
+
+| Situation | Variant | Why |
+|---|---|---|
+| External client, full consultoria engagement, all phases, adversarial gate mandatory | `consultoria-externa` | Gate cell `REQ` — defends against methodology defects before framework is built; appropriate where methodology errors have reputational or contractual consequences |
+| Internal team, methodology research EXECUTES (AMENDED S183 — research gate decision), adversarial gate optional | `consultoria-interna` | Research phase `EXEC`; gate cell `OPT` (default OFF); lighter path for teams with existing domain knowledge |
+| Existing project handed to a vendor or software team, needs structured handoff package | `software-handoff` | All phases `EXEC`; gate cell `OPT`; `deliver` phase fires a transition rule that seeds a `feature_development` workflow with `framework_doc` and `deliverables_list` as inherited artifacts |
+| Surgical scope fix, upstream framework already established, minimal artifact set | `cirurgico` | Discovery `EXEC`, Framework `SKIP`, Research `SKIP`, Operational `PARTIAL` (scope_brief + patch_summary), Deliver `EXEC`; gate `SKIP`; requires `framework` artifact_ref and `scope` file_ref at pre-flight |
+
+### Decision Tree
+
+Answer these four questions in order:
+
+```
+Q1. Is the primary audience external (client, regulator, board)?
+    YES --> Q2
+    NO  --> consultoria-interna  [lighter gate, research EXEC per S183]
+
+Q2. Is there an existing framework / prior PME run that covers the research layer?
+    YES --> Q3
+    NO  --> consultoria-externa  [full run, gate REQ]
+
+Q3. Will the final deliverable be handed off to a software team as a spec?
+    YES --> software-handoff  [all phases EXEC, transition rule fires after deliver]
+    NO  --> Q4
+
+Q4. Is the scope narrow enough to fit a single targeted patch/intervention?
+    YES --> cirurgico  [PARTIAL discovery + deliver, research SKIP, gate SKIP]
+    NO  --> consultoria-externa  [full run, gate REQ]
+```
+
+### Required Inputs by Variant
+
+| Variant | Required at startWorkflow |
+|---|---|
+| `consultoria-externa` | `client_name` (string), `project_brief` (string) |
+| `consultoria-interna` | `client_name` (string) |
+| `software-handoff` | `client_name` (string), `repo_url` (string) |
+| `cirurgico` | `framework` (artifact_ref), `scope` (file_ref) |
+
+Missing any required input raises `MISSING_REQUIRED_INPUT` at pre-flight before the first phase dispatches (RFC-032 §9).
+
+---
+
+## Gate Intensity Tuning
+
+The adversarial gate on the RESEARCH phase exit converges when `severity:high == 0` on the latest review artifact. This is the v1.0 default per **ADR-021 §3.2**. Adjust intensity by industry context:
+
+### Convergence Thresholds by Industry
+
+| Industry | Convergence Criterion | Notes |
+|---|---|---|
+| Default (all industries) | `severity:high == 0` after <= 3 iterations | Baseline per ADR-021 |
+| Finance / auditing | `severity:high == 0` AND `severity:medium == 0` | Tighter: regulatory standards require zero medium findings too |
+| Healthcare / compliance-heavy | `severity:high == 0` AND `severity:medium == 0` | Same as finance; compliance audit trail must be clean |
+| Marketing / brand | `severity:high <= 2` acceptable | Looser: subjective taste findings classified as high are common; threshold softened to avoid gate churn |
+| Technology / SaaS internal | `severity:high == 0` (default) | Standard threshold applies |
+
+**Architectural reference:** ADR-021 governs the gate-as-gate-not-phase principle. Per-gate configurability is a post-S183 follow-up (ADR-021 §3.2); these tuning rules are operator guidance until that follow-up lands.
+
+### Force-Pass Escape Hatch
+
+If `severity:high > 0` remains after 3 iterations, the workflow escalates to the user:
+
+- `--force-pass` — bypass gate, log the override in the `adversarial-review-log.md` artifact; workflow proceeds to FRAMEWORK
+- `--abort` — cancel the workflow; no further phases dispatch
+
+Force-pass is always logged. Never bypass silently. The 3-iteration HARD CAP is enforced by the gate runner; see Adversarial Review Iteration Playbook section below.
+
+---
+
+## Persona Pairing Strategy
+
+The adversarial-reviewer agent receives a `persona_id` from the persona library (see `.claude/personas/INDEX.md` for the full catalog; current seed: `cfo-conservador`, `diretor-cetico-fmcg`, `designer-perfeccionista`, `auditor-compliance`). Select the persona that matches the primary stakeholder who will scrutinise the phase output.
+
+### Pairing Guide by Phase
+
+**DISCOVERY phase**
+
+Match persona to the client's seniority and domain:
+
+| Client profile | Recommended persona |
+|---|---|
+| CFO / CEO / board-level | `cfo-conservador` or `diretor-cetico-fmcg` |
+| Brand / creative director | `designer-perfeccionista` |
+| Compliance / legal officer | `auditor-compliance` |
+| Engineering / CTO | `engenheiro-cetico-construcao` (if seeded) |
+
+**RESEARCH gate (adversarial-reviewer dispatch)**
+
+- Primary: same persona selected for DISCOVERY (continuity of lens)
+- Secondary (compliance-heavy industries): add `auditor-compliance` as a secondary reviewer in a second iteration pass to cover regulatory blind spots
+
+**DELIVER gate**
+
+Use the persona that matches the **actual stakeholder who signs off** on the deliverable, not the internal sponsor:
+
+- External board / investor sign-off: `cfo-conservador`
+- Brand committee sign-off: `designer-perfeccionista`
+- Regulatory sign-off: `auditor-compliance`
+
+### Persona Override
+
+The user may override persona selection at any phase via `--persona=<id>`. Record the override and rationale in `persona-selection-log.md` (operational phase artifact). Never silently ignore a user-specified persona.
+
+---
+
+## Adversarial Review Iteration Playbook
+
+The adversarial gate fires at the RESEARCH to FRAMEWORK boundary when the variant gate cell is `REQ` or `OPT` (with `--adversarial=true`). The gate runner dispatches the `adversarial-reviewer` agent in a loop with a HARD CAP of 3 iterations per **ADR-021**.
+
+### Iteration Protocol
+
+**Iteration 1 — Full critique**
+
+- Dispatch `adversarial-reviewer` with `persona_id` and the `research-report.md` artifact
+- Expect 5-10 findings across severity levels (`high`, `medium`, `low`)
+- Store iteration artifacts: `methodology-research-v1.md`, `adversarial-review-{persona}-v1.md`
+- If `severity:high == 0` on iteration 1 output, gate passes immediately (early exit)
+
+**Iteration 2 — Revised artifact, focused critique**
+
+- `methodology-researcher` revises research report addressing all `high` and `medium` findings
+- Re-dispatch `adversarial-reviewer` with revised artifact (`methodology-research-v2.md`)
+- Expect 1-3 findings remaining, concentrated on edge cases
+- Store: `methodology-research-v2.md`, `adversarial-review-{persona}-v2.md`
+- If `severity:high == 0`, gate passes (common exit point)
+
+**Iteration 3 — Final critique**
+
+- Second revision from `methodology-researcher` addressing remaining findings
+- Re-dispatch `adversarial-reviewer` for final pass
+- Store: `methodology-research-v3.md`, `adversarial-review-{persona}-v3.md`
+- If `severity:high > 0` after iteration 3: BLOCKED — do not proceed silently
+
+**BLOCKED state**
+
+Present user escalation:
+
+```
+Gate BLOCKED after 3 iterations.
+Remaining high-severity findings:
+  {list findings from adversarial-review-v3.md}
+
+Options:
+  --force-pass  Accept research report as-is; override logged in audit trail
+  --abort       Cancel workflow; no further phases dispatch
+```
+
+Wait for explicit user response. Never auto-select `--force-pass`.
+
+### Artifact Audit Trail
+
+Every iteration artifact is persisted in MinIO via `mcp__orchestrator-extended__artifactStore` before the next iteration begins:
+
+| Artifact | artifact_kind | When stored |
+|---|---|---|
+| `methodology-research-v{n}.md` | `phase-artifact` | After each revision |
+| `adversarial-review-{persona}-v{n}.md` | `adversarial_review` | After each reviewer dispatch |
+| `adversarial-review-log.md` | `gate-log` | At gate resolution (pass or force-pass) |
+
+The `adversarial-review-log.md` records all iterations, each finding's resolution, and the convergence outcome. It is omitted from the artifact set when the gate cell is `SKIP`.
+
+---
+
+## Workflow Lifecycle Reference
+
+PME executes five phases in strict order. No phase may be skipped outside a declared variant cell of `SKIP` or `PARTIAL`. Checkpoints are written at every phase exit to support multi-session resumption (RFC-032 §3.5).
+
+### Phase Sequence
+
+```
+DISCOVERY --> RESEARCH [+adversarial gate] --> FRAMEWORK --> OPERATIONAL --> DELIVER
+```
+
+### Per-Variant Phase Matrix (RFC-032 §5)
+
+| Phase / Gate | consultoria-externa | consultoria-interna | software-handoff | cirurgico |
+|---|---|---|---|---|
+| DISCOVERY | EXEC | EXEC | EXEC | EXEC |
+| RESEARCH | EXEC | EXEC <!-- AMENDED 2026-05-12 (S183) --> | EXEC | SKIP |
+| Gate: adversarial | REQ | OPT | OPT | SKIP |
+| FRAMEWORK | EXEC | EXEC | EXEC | SKIP |
+| OPERATIONAL | EXEC | EXEC | EXEC | PARTIAL (scope_brief + patch_summary) |
+| DELIVER | EXEC | EXEC | EXEC | EXEC |
+
+`REQ` = gate always runs; `OPT` = opt-in via `--adversarial=true` (default OFF); `SKIP` = gate bypassed.
+Source: RFC-032 §5 matrix. Variant mechanic: ADR-020 + RFC-031.
+
+### Canonical Artifacts by Phase (RFC-032 §8)
+
+| Phase | Primary artifacts |
+|---|---|
+| DISCOVERY | `discovery-brief.md`, `stakeholder-map.md`, `discovery-inputs.json` |
+| RESEARCH | `methodology-research.md`, `evidence-pack.md`, `sources.bib`, `adversarial-review-log.md` (when gate not SKIP) |
+| FRAMEWORK | `framework-doc.md`, `playbook.md`, `framework-summary.md`, `framework-exhibits/` |
+| OPERATIONAL | `operational-runbook.md`, `kpi-set.md`, `risk-register.md`, `implementation-checklist.md`, `persona-selection-log.md` |
+| DELIVER | `deliverables-list.md`, `final-deck.pdf`, `closure-report.md`, `handoff-brief.md` (software-handoff only) |
+
+All artifacts travel through `mcp__orchestrator-extended__artifactStore` / `artifactRetrieve`. Direct access to `.orchestrator/artifacts/*` is forbidden per Universal Charter §4.
+
+### Multi-Session Resumption
+
+PME workflows are long-lived by design. On session resume:
+
+1. Call `getStatus({ workflowId })` to read current phase, variant, and stored artifacts
+2. Retrieve previous phase artifacts via `artifactRetrieve` — do not require user to re-specify
+3. Continue from the current phase; the variant is immutable (do not re-run pre-flight)
+
+---
+
+## Common Pitfalls
+
+| Pitfall | Symptom | Fix |
+|---|---|---|
+| Choosing `consultoria-externa` for internal teams | Adversarial gate `REQ` creates unnecessary friction for teams with existing domain knowledge | Use `consultoria-interna`; gate is `OPT` and defaults OFF |
+| Skipping persona consultation | Research critique is generic, not stakeholder-lens-calibrated; findings lack specificity | Select persona from `.claude/personas/INDEX.md` before dispatching `adversarial-reviewer`; log selection in `persona-selection-log.md` |
+| Treating iteration 3 BLOCKED as failure | Operator abandons gate or bypasses silently | BLOCKED is a feature: it surfaces high-signal escalation points. Present user options (`--force-pass` or `--abort`), log the outcome, never auto-bypass |
+| Forgetting `cirurgico` PARTIAL artifact declarations | `PreFlightValidator` raises `PARTIAL_MISSING_ARTIFACTS` (RFC-032 §9); workflow does not start | `cirurgico` discovery produces only `scope_brief.md`; deliver produces only `patch_summary.md` — ensure variant definition lists these slugs in the `artifacts` cell |
+| Advancing FRAMEWORK before gate resolves | Research defects propagate into framework; methodology errors compound | Gate runner must receive explicit pass (convergence or `--force-pass`) before `advancePhase` is called on RESEARCH |
+| Re-running pre-flight on session resume | Fails because `framework` artifact_ref required by `cirurgico` was resolved in prior session | On resume, read current phase from `getStatus` and skip pre-flight; variant and inputs are stored in PostgreSQL |
+
+---
+
+## Audit Trail Requirements
+
+Every PME phase and gate interaction MUST be persisted. Missing MinIO records are not recoverable at container restart and break the workflow audit graph.
+
+### Required artifact_kind values
+
+| Event | artifact_kind | artifactStore call |
+|---|---|---|
+| Phase output (any phase) | `phase-artifact` | After phase agent completes, before `advancePhase` |
+| Adversarial reviewer dispatch | `adversarial_review` | After each reviewer iteration |
+| Gate resolution (pass or force-pass) | `gate-log` | At gate exit |
+| Final deliverable pack | `deliverable` | At DELIVER phase completion |
+
+### Call pattern (deferred-load, TD-098)
+
+```
+# Step 1: load schema if not yet available
+ToolSearch("select:mcp__orchestrator-extended__artifactStore")
+
+# Step 2: store artifact
+mcp__orchestrator-extended__artifactStore({
+  workflowId: "<workflow-id>",
+  phase: "<pme-phase-name>",   # discovery | research | framework | operational | deliver
+  type: "<artifact_kind>",
+  content: "<artifact content>",
+  metadata: {
+    artifact_kind: "<phase-artifact|adversarial_review|gate-log|deliverable>",
+    variant: "<active-variant>",
+    persona_id: "<persona if applicable>",
+    iteration: <iteration-number if applicable>
+  }
+})
+```
+
+---
+
+## Architectural References
+
+This skill operationalises three architectural decisions. When in doubt, consult the source:
+
+- **ADR-020** (`project-guidelines/adrs/ADR-020-WORKFLOW-MODE-PARAMETER-AS-UNIVERSAL-PATTERN.md`) — establishes `variant` as a first-class, universal workflow parameter; defines `EXEC / SKIP / PARTIAL / REQ / OPT` vocabulary
+- **ADR-021** (`project-guidelines/adrs/ADR-021-ADVERSARIAL-REVIEW-AS-GATE-NOT-PHASE.md`) — mandates adversarial review as a gate row (not a phase), defines the 3-iteration cap and `REQ / OPT / SKIP` gate cell semantics, and reserves the `--force-pass` escape hatch
+- **RFC-032** (`project-guidelines/rfcs/RFC-032-PROJECT-MANAGEMENT-ENTERPRISE-WORKFLOW.md`) — full PME workflow definition: 5 phases, 4 variants, variant matrix (§5), adversarial gate protocol (§6), agent stubs (§7), artifact lifecycle (§8), error codes (§9), and testing strategy (§10)
+- **RFC-031** (`project-guidelines/rfcs/RFC-031-WORKFLOW-MODE-PARAMETER-CONDITIONAL-PHASE-EXECUTION.md`) — framework-wide variant mechanic implementation (JSON Schema, runtime resolution, pre-flight validation, phase-skip enforcement) that PME consumes as a first-class consumer

package/skills/receiving-code-review/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: receiving-code-review
+description: "Use when receiving code review feedback, before implementing suggestions — requires technical rigor and verification, not performative agreement or blind implementation."
+triggers:
+  - "When a PR reviewer leaves comments"
+  - "When the user asks you to address review feedback"
+  - "When external review feedback arrives"
+  - "Before implementing any review suggestion"
+---
+
+# Code Review Reception
+
+## Overview
+
+Code review requires technical evaluation, not emotional performance.
+
+**Core principle:** Verify before implementing. Ask before assuming. Technical correctness over social comfort.
+
+## The Response Pattern
+
+```
+WHEN receiving code review feedback:
+
+1. READ: Complete feedback without reacting
+2. UNDERSTAND: Restate requirement in own words (or ask)
+3. VERIFY: Check against codebase reality
+4. EVALUATE: Technically sound for THIS codebase?
+5. RESPOND: Technical acknowledgment or reasoned pushback
+6. IMPLEMENT: One item at a time, test each
+```
+
+## Forbidden Responses
+
+**NEVER:**
+- "You're absolutely right!" (explicit CLAUDE.md violation)
+- "Great point!" / "Excellent feedback!" (performative)
+- "Let me implement that now" (before verification)
+
+**INSTEAD:**
+- Restate the technical requirement
+- Ask clarifying questions
+- Push back with technical reasoning if wrong
+- Just start working (actions > words)
+
+## Handling Unclear Feedback
+
+```
+IF any item is unclear:
+  STOP - do not implement anything yet
+  ASK for clarification on unclear items
+
+WHY: Items may be related. Partial understanding = wrong implementation.
+```
+
+**Example:**
+```
+User: "Fix 1-6"
+You understand 1,2,3,6. Unclear on 4,5.
+
+WRONG: Implement 1,2,3,6 now, ask about 4,5 later
+RIGHT: "I understand items 1,2,3,6. Need clarification on 4 and 5 before proceeding."
+```
+
+## Source-Specific Handling
+
+### From the User (trusted)
+- **Trusted** — implement after understanding
+- **Still ask** if scope unclear
+- **No performative agreement**
+- **Skip to action** or technical acknowledgment
+
+### From External Reviewers
+```
+BEFORE implementing:
+  1. Check: Technically correct for THIS codebase?
+  2. Check: Breaks existing functionality?
+  3. Check: Reason for current implementation?
+  4. Check: Works on all platforms/versions?
+  5. Check: Does reviewer understand full context?
+
+IF suggestion seems wrong:
+  Push back with technical reasoning
+
+IF can't easily verify:
+  Say so: "I can't verify this without [X]. Should I [investigate/ask/proceed]?"
+
+IF conflicts with the user's prior architectural decisions:
+  Stop and discuss with the user first
+```
+
+**Rule:** "External feedback — be skeptical, but check carefully"
+
+## YAGNI Check for "Professional" Features
+
+```
+IF reviewer suggests "implementing properly":
+  grep codebase for actual usage
+
+  IF unused: "This endpoint isn't called. Remove it (YAGNI)?"
+  IF used: Then implement properly
+```
+
+**Rule:** "You and reviewer both report to me. If we don't need this feature, don't add it."
+
+## Implementation Order
+
+```
+FOR multi-item feedback:
+  1. Clarify anything unclear FIRST
+  2. Then implement in this order:
+     - Blocking issues (breaks, security)
+     - Simple fixes (typos, imports)
+     - Complex fixes (refactoring, logic)
+  3. Test each fix individually
+  4. Verify no regressions
+```
+
+## When To Push Back
+
+Push back when:
+- Suggestion breaks existing functionality
+- Reviewer lacks full context
+- Violates YAGNI (unused feature)
+- Technically incorrect for this stack
+- Legacy/compatibility reasons exist
+- Conflicts with the user's architectural decisions
+
+**How to push back:**
+- Use technical reasoning, not defensiveness
+- Ask specific questions
+- Reference working tests/code
+- Involve the user if architectural
+
+## Acknowledging Correct Feedback
+
+When feedback IS correct:
+```
+"Fixed. [Brief description of what changed]"
+"Good catch — [specific issue]. Fixed in [location]."
+[Just fix it and show in the code]
+
+NOT: "You're absolutely right!"
+NOT: "Great point!"
+NOT: "Thanks for catching that!"
+NOT: ANY gratitude expression
+```
+
+**Why no thanks:** Actions speak. Just fix it. The code itself shows you heard the feedback.
+
+## Gracefully Correcting Your Pushback
+
+If you pushed back and were wrong:
+```
+"You were right — I checked [X] and it does [Y]. Implementing now."
+"Verified this and you're correct. My initial understanding was wrong because [reason]. Fixing."
+
+NOT: Long apology
+NOT: Defending why you pushed back
+NOT: Over-explaining
+```
+
+State the correction factually and move on.
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Performative agreement | State requirement or just act |
+| Blind implementation | Verify against codebase first |
+| Batch without testing | One at a time, test each |
+| Assuming reviewer is right | Check if breaks things |
+| Avoiding pushback | Technical correctness > comfort |
+| Partial implementation | Clarify all items first |
+| Can't verify, proceed anyway | State limitation, ask for direction |
+
+## GitHub Thread Replies
+
+When replying to inline review comments on GitHub, reply in the comment thread (`gh api repos/{owner}/{repo}/pulls/{pr}/comments/{id}/replies`), not as a top-level PR comment.
+
+## The Bottom Line
+
+**External feedback = suggestions to evaluate, not orders to follow.**
+
+Verify. Question. Then implement.
+
+No performative agreement. Technical rigor always.

package/skills/sprint-launch/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: sprint-launch
+description: >
+  Launch parallel Claude sessions in tmux for sprint execution.
+  Use when starting a sprint with independent tasks that benefit from parallel panes.
+  Supports duo, duo-doc, squad, squad-review, platoon, and platoon-full presets
+  covering 2 to 5+ pane configurations.
+argument-hint: <preset> [workflow-id]
+---
+
+# Sprint Launcher — RFC-025 v2
+
+Launch parallel Claude sessions in tmux panes, each isolated in a git worktree, to execute sprint tasks concurrently.
+
+## When to Use
+
+- Starting a sprint with 1-5 independent task tracks
+- You want parallel agent sessions with worktree isolation
+- RFC-021 Sprints, ADR-017 phases, or any feature work with clear task separation
+
+## Prerequisites
+
+Before launching, verify:
+1. **tmux** is installed and on PATH (`tmux -V`)
+2. **claude** CLI is on PATH (`claude --version`)
+3. **git** repo is clean (no uncommitted changes that could conflict with worktrees)
+4. An active workflow exists (or you have a workflowId)
+
+## Presets
+
+| Preset | Panes | Composition | Use When |
+|--------|-------|-------------|----------|
+| `duo` | 1 | 1 implementer | Simple sprint, 1 task track |
+| `duo-doc` | 2 | 1 implementer + 1 doc-sidecar | Documentation-heavy work |
+| `squad` | 3 | 2 implementers + 1 debug-sidecar | 2 parallel tracks with review |
+| `squad-review` | 3 | 1 implementer + 1 debug-sidecar + 1 doc-sidecar | Quality-critical single track |
+| `platoon` | 5 | 3 implementers + 1 reviewer + 1 debug-sidecar | 3 parallel tracks with review |
+| `platoon-full` | 7 | 2 implementers + 2 doc-sidecars + 1 debug-sidecar + 1 test-sidecar + 1 reviewer | Complex sprint with full observability |
+
+## Protocol
+
+**IMPORTANT: Always confirm with the user before launching.**
+
+### Step 1: Gather Parameters
+
+Parse from user input or active workflow context:
+- **preset**: one of the 6 presets above (required)
+- **workflowId**: from active workflow or user input (optional — script generates one if missing)
+
+### Step 2: Confirm via AskUserQuestion
+
+Before executing anything, present the launch plan:
+
+```
+AskUserQuestion({
+  question: "Sprint Launch: {preset} preset\n\nSession: sprint-{wfId:0:8}\nPanes: {pane descriptions}\nWorktrees: ../wt-sprint-{wfId:0:8}-{0,1,...}\n\nProceed?",
+  options: ["Launch", "Change preset", "Cancel"]
+})
+```
+
+### Step 3: Execute
+
+On user approval, run via TypeScript launcher:
+
+```bash
+npx tsx scripts/sprint-launch.ts {preset} {workflowId}
+
+# With task distribution (--task is repeatable, round-robin to implementer panes):
+npx tsx scripts/sprint-launch.ts {preset} {workflowId} --mailbox \
+  --task "TASK-001: Implement auth endpoint" \
+  --task "TASK-002: Write integration tests"
+
+# With tasks fetched from REST API (graceful fallback if API unavailable):
+npx tsx scripts/sprint-launch.ts {preset} {workflowId} --mailbox --fetch-tasks
+```
+
+### Step 4: Auto-attach
+
+The script automatically attaches after launching panes and injecting startup prompts:
+
+- **Inside tmux**: opens a horizontal split pointing at the new session — zero user action required
+- **Outside tmux**: prints the attach command to console, e.g. `tmux attach -t sprint-{prefix}`
+
+Startup prompts are injected into each pane automatically. If a pane fails to receive its prompt, auto-attach still proceeds.
+
+## Task Distribution
+
+When launching with tasks, the launcher distributes them **round-robin to implementer panes only**.
+Sidecar agents (doc-sidecar, debug-sidecar, test-sidecar) react to implementer progress via mailbox
+and do not receive direct task_assignment messages from the launcher.
+
+### --task flag (repeatable)
+
+```bash
+--task "TASK-001: Title"
+```
+
+- Parses `TASK-001` as `taskId` and `Title` as `title`
+- Produces a `task_assignment` mailbox message with `description: ''` and `acceptanceCriteria: []`
+- Tasks are distributed round-robin: task[0] → implementer[0], task[1] → implementer[1], task[2] → implementer[0], etc.
+- The task title is also injected into the pane's CLAUDE.md as a hint (via WorktreeIsolator)
+
+### --fetch-tasks flag
+
+```bash
+--fetch-tasks
+```
+
+- Calls `GET /api/workflows/{workflowId}/tasks` on the configured REST API (`ORCHESTRATOR_API_URL` env var, default `http://localhost:3000`)
+- Appends fetched tasks to any `--task` CLI tasks
+- Graceful fallback: if the API is unreachable or returns an error, prints a warning and continues with CLI tasks only
+
+### Agent Protocol
+
+Agents receive tasks via the sprint-teammate skill. See `.claude/skills/sprint-teammate/sprint-teammate.md`.
+
+## Critical Rules
+
+1. **NEVER use `--bare` for implementer panes** — `--bare` suppresses hooks, skills, and MCP tools. Implementers MUST have access to these. The script uses `claude -p` (without `--bare`).
+2. **Always confirm before launching** — never auto-launch panes.
+3. **Worktrees are cleaned up on exit** — the script traps EXIT/SIGINT/SIGTERM and removes worktrees if interrupted.
+4. **ANTHROPIC_API_KEY warning** — if unset, script warns but continues (Max OAuth mode assumed).
+
+## Monitoring
+
+After launch, check pane health:
+
+```bash
+# Single check
+./scripts/sprint-status.sh sprint-{prefix} --once
+
+# Continuous monitoring (10s interval)
+./scripts/sprint-status.sh sprint-{prefix}
+
+# Custom interval
+POLL_INTERVAL=5 ./scripts/sprint-status.sh sprint-{prefix}
+```
+
+Output shows ALIVE (green) or DEAD (red) per pane.
+
+## Cleanup
+
+Worktrees are auto-cleaned on script exit. If a crash leaves orphans:
+
+```bash
+git worktree prune
+git worktree list  # verify no wt-sprint-* remain
+```
+
+To kill a running sprint session:
+
+```bash
+tmux kill-session -t sprint-{prefix}
+```
+
+## Examples
+
+```bash
+# Simple sprint with 1 implementer (auto-attaches)
+/sprint-launch duo
+
+# Documentation-heavy sprint
+/sprint-launch duo-doc adaaa9a4-ef49-4e26-af14-2b239f62b40c
+
+# 2 parallel tracks
+/sprint-launch squad
+
+# 2 tracks with reviewer sidecar
+/sprint-launch squad-review adaaa9a4-ef49-4e26-af14-2b239f62b40c
+
+# 3 parallel tracks
+/sprint-launch platoon
+
+# 3 tracks with reviewer sidecar
+/sprint-launch platoon-full adaaa9a4-ef49-4e26-af14-2b239f62b40c
+```