@arthai/agents 1.0.0

package/skills/planning/SKILL.md

@@ -0,0 +1,436 @@
+---
+name: planning
+description: "Spin up an adversarial planning team for a feature. Usage: /planning <feature-name> [--design] [--gtm] [--fast] [--lite] [-- <brief>]"
+user-invocable: true
+arguments: "<feature-name> <--design> <--gtm> <--fast> <--lite> <-- brief>"
+---
+
+# Planning Team Skill
+
+Automates the full planning team workflow into a single command, using structured adversarial debate rounds to produce a hardened, scope-locked plan.
+
+## Argument Parsing
+
+Parse from the argument string:
+- `feature-name`: Required. Kebab-case name for the feature (used in team name).
+- `--design`: Optional flag. Include Design Thinker + Design Critic teammates.
+- `--gtm`: Optional flag. Include GTM Expert teammate.
+- `--fast`: Optional flag. Skip Round 3 (risk debate). DA participates in Rounds 1 and 2 only.
+- `--lite`: Optional flag. No devil's advocate. PM + Architect only with checklist-based risk evaluation.
+- `-- <brief>`: Optional inline brief. Everything after `--` (not followed by a flag name) is the feature brief.
+
+If no feature name is provided, use AskUserQuestion to get it.
+
+## Execution Steps
+
+### 1. Gather Context (before spawning anyone)
+
+Check if an inline brief was provided after `--` in the arguments. If yes, use it directly as `FEATURE_BRIEF` and skip asking.
+
+If no inline brief was provided, ask the user with AskUserQuestion:
+- "Describe the feature in 2-3 sentences — what problem does it solve and for whom?"
+
+Store their response as `FEATURE_BRIEF`.
+
+### 2. Mode Selection
+
+If `--lite` or `--fast` was passed as an argument, skip the prompt and use that mode directly.
+
+Otherwise, present this prompt to the user with AskUserQuestion:
+
+```
+Planning mode:
+  [1] Lite    — PM + Architect only, checklist risk review (~421x cost, fastest)
+  [2] Fast    — PM + Architect + Devil's Advocate, skip risk round (~431x cost, balanced)
+  [3] Full    — 3 structured debate rounds with DA (~641x cost, most thorough)
+  [auto]      — decide based on feature scope
+
+Your pick? [auto]
+```
+
+If user picks `[auto]` or presses enter without input, apply auto-detection:
+- `FEATURE_BRIEF` has fewer than 50 words AND none of the words "auth", "payment", "migration", "security", "permission", "billing", "database", "breaking" appear → set mode `lite`
+- `FEATURE_BRIEF` has 50–150 words OR contains one complexity signal keyword → set mode `fast`
+- `FEATURE_BRIEF` has more than 150 words OR contains multiple complexity signal keywords OR user asked for "thorough" or "full" planning → set mode `full`
+
+Map user choices:
+- `[1]` or `lite` → `--lite` mode
+- `[2]` or `fast` → `--fast` mode
+- `[3]` or `full` → default full mode
+
+Store the resolved mode as `DEBATE_MODE` (values: `lite`, `fast`, `full`).
+
+### 3. Codebase Scan
+
+Spawn an `explore-light` subagent (model: haiku) to scan for relevant files:
+
+```
+prompt: "For a feature called '{feature-name}', find: (1) related backend routes/services, (2) related frontend pages/components, (3) related database models, (4) any existing tests. Return a structured summary of file paths and their purpose. Feature brief: {FEATURE_BRIEF}"
+```
+
+Store the result as `CODEBASE_CONTEXT`.
+
+### 4. Create Team + Tasks
+
+Create team: `planning-{feature-name}`
+
+Create these tasks:
+
+| Task | Owner | Subject |
+|------|-------|---------|
+| 1 | product-manager | Define product spec for {feature-name} |
+| 2 | architect | Design technical plan for {feature-name} |
+| 3 (if --design) | design-thinker | Create design brief for {feature-name} |
+| 4 (if not --lite) | devils-advocate | Challenge scope and feasibility for {feature-name} |
+
+### 5. Build Shared Context Block
+
+Compose this block to inject into every teammate's spawn prompt:
+
+```
+## Project Context
+{PROJECT_NAME} - {PROJECT_DESCRIPTION}
+Stack: {TECH_STACK}
+Stage: {DEVELOPMENT_STAGE}
+Auth: {AUTH_APPROACH}
+
+## Feature: {feature-name}
+{FEATURE_BRIEF}
+
+## Relevant Codebase
+{CODEBASE_CONTEXT}
+
+## Your Team
+You are on team "planning-{feature-name}". Use SendMessage to collaborate.
+Other teammates: {list who's on the team based on flags}
+
+## Debate Mode
+This planning session runs in {DEBATE_MODE} mode.
+- Full: 3 structured debate rounds (scope, feasibility, risk).
+- Fast: 2 structured debate rounds (scope, feasibility). Round 3 is skipped.
+- Lite: No devil's advocate. PM + Architect + checklist risk review.
+
+## Rules
+- Every claim must include EVIDENCE (code references, cost estimates, or user data).
+- Verdicts are final for that round — do not re-litigate decided items.
+- If DA recommends KILL and user overrides, record as USER OVERRIDE in the plan.
+```
+
+### 6. Spawn Teammates (ALL IN ONE MESSAGE — parallel)
+
+Spawn all teammates in a **single message** with multiple Task tool calls:
+
+**Always spawn:**
+- **product-manager** (subagent_type="product-manager", model="opus")
+  - Prompt: "{SHARED_CONTEXT}\n\nYou are the PM. Own the 'what' and 'why'.\n\nIn Round 1, you LEAD with your scope claim. Format your must-haves as:\n  [M1] requirement — BECAUSE reason\n  [M2] ...\nMaximum 5 MUST-HAVEs. Also list NICE-TO-HAVEs with CUT-IF conditions, EXPLICIT EXCLUSIONS, and success metrics.\n\nIn Round 2, you COUNTER the architect's approach: does it deliver user value, is it over-engineered, what is the time-to-value?\n\nIn Round 3 (full mode only), you DEFEND against the devil's advocate's risk case. Accept or reject each risk with evidence."
+
+- **architect** (subagent_type="architect", model="opus")
+  - Prompt: "{SHARED_CONTEXT}\n\nYou are the Architect. Own the 'how'.\n\nIn Round 1, you COUNTER the PM's scope from a feasibility lens. Challenge feasibility, flag hidden complexity, identify scope creep vectors, propose a counter-scope.\n\nIn Round 2, you LEAD with your technical approach: API contract, DB changes, architecture decision + WHY, task breakdown with S/M/L/XL estimates, implementation cost, dependencies, risks.\n\nIn Round 3 (full mode only), you DEFEND against the devil's advocate's risk case. Accept or reject each risk with evidence. Keep it simple for early-stage. Push back on scope that doesn't match the development stage."
+
+**Spawn if not --lite:**
+- **devils-advocate** (subagent_type="qa-challenger", model="sonnet")
+  - Prompt: "{SHARED_CONTEXT}\n\nYou are the Devil's Advocate. You own RISK. Your mission: make the plan TIGHTER and more REALISTIC — not to block progress.\n\nYou succeed when the plan is smaller, cheaper, and more likely to ship. You fail when you kill good work with vague concerns.\n\nIn Round 1, you ATTACK the PM's scope claim: rate each item for CREEP RISK (LOW / MEDIUM / HIGH), surface HIDDEN ASSUMPTIONS, identify YAGNI violations, estimate implementation cost per item, recommend a CUT LIST.\n\nIn Round 2, you ATTACK the architect's approach: identify hidden complexity based on the codebase context, integration risks, cost underestimates, and propose a simpler alternative approach if one exists.\n\nIn Round 3 (full mode only), you LEAD with your risk case: (a) pre-mortem — name 3 specific failure modes with evidence, (b) scope creep forecast — which must-haves will expand, (c) cost reality check — where estimates are wrong, (d) THE KILL QUESTION — argue whether we should build this at all, (e) acceptance test gaps. After PM + Architect defend, issue a final verdict: SATISFIED or UNSATISFIED per defense, and rate overall confidence HIGH / MEDIUM / LOW."
+
+**Spawn if --design flag:**
+- **design-thinker** (subagent_type="design-studio:think", model="sonnet")
+  - Prompt: "{SHARED_CONTEXT}\n\nYou are the Design Thinker. Clarify user needs, explore UX goals, and create a design brief BEFORE implementation decisions. Share your brief with PM and Architect. Challenge both on user experience. Your output feeds into Round 3 as additional evidence for the devil's advocate. (In --fast mode where Round 3 is skipped, your outputs feed into Round 2 Phase 3 only.)"
+
+- **design-critic** (subagent_type="design-studio:critique", model="sonnet")
+  - Prompt: "{SHARED_CONTEXT}\n\nYou are the Design Critic. Review design proposals from the team against established design principles. Provide actionable feedback. Wait for the design brief before critiquing. Your critique feeds into Round 3 as additional evidence for the devil's advocate. (In --fast mode where Round 3 is skipped, your outputs feed into Round 2 Phase 3 only.)"
+
+**Spawn if --gtm flag:**
+- **gtm-expert** (subagent_type="gtm-expert", model="sonnet")
+  - Prompt: "{SHARED_CONTEXT}\n\nYou are the GTM Expert. Own distribution and launch strategy. Advise on positioning, viral mechanics, and launch sequencing. Challenge the team on how users will discover and adopt this feature. Your output feeds into Round 3 as additional evidence for the devil's advocate."
+
+### 7. Structured Debate Protocol
+
+Facilitate the following rounds in sequence. Each phase completes before the next begins.
+
+---
+
+#### ROUND 1: SCOPE DEBATE
+
+**Phase 1 — PM CLAIM**
+
+The PM posts their scope claim. Required format:
+- MUST-HAVEs (max 5): `[M1] requirement — BECAUSE reason`
+- NICE-TO-HAVEs: each with a `CUT-IF` condition
+- EXPLICIT EXCLUSIONS: what this feature deliberately does not do
+- SUCCESS METRICS: how we know this shipped successfully
+
+**Phase 2 — ARCHITECT COUNTER**
+
+The Architect responds to the PM's scope claim:
+- Which items are feasible as stated?
+- Which hide unexpected complexity?
+- Which are scope creep vectors?
+- Proposed counter-scope (reworded or reduced must-haves)
+
+**Phase 3 — DA ATTACK** (skip if --lite)
+
+The Devil's Advocate rates each must-have item:
+- CREEP RISK: LOW / MEDIUM / HIGH per item
+- HIDDEN ASSUMPTIONS: unstated prerequisites
+- YAGNI VIOLATIONS: items built for a future that may not come
+- COST ESTIMATE: rough implementation cost per item (S/M/L/XL)
+- CUT LIST: recommended items to defer or kill
+
+**Phase 4 — ROUND 1 VERDICT**
+
+Orchestrator issues a structured verdict:
+- LOCKED MUST-HAVES: confirmed with no objections or resolved objections
+- DEFERRED: moved to a future iteration with reason
+- REJECTED: cut with reason
+- EXCLUSIONS: hardened from PM's list
+- UNRESOLVED: items where PM, Architect, and DA disagree — escalate to user
+
+---
+
+#### ROUND 2: FEASIBILITY DEBATE
+
+**Phase 1 — ARCHITECT CLAIM**
+
+The Architect presents the technical approach:
+- API contract (endpoints, inputs, outputs)
+- DB changes (schema additions, migrations)
+- Architecture decision + WHY (not just what)
+- Task breakdown with S/M/L/XL estimates
+- Implementation cost (total estimate)
+- Dependencies (external services, libraries, teams)
+- Known risks
+
+**Phase 2 — PM COUNTER**
+
+The PM challenges the approach:
+- Does it deliver user value as scoped?
+- Is any part over-engineered for the current stage?
+- What is the time-to-value for the user?
+
+**Phase 3 — DA ATTACK** (skip if --lite)
+
+The Devil's Advocate challenges the approach:
+- Hidden complexity not visible in the proposal (reference `CODEBASE_CONTEXT`)
+- Integration risks with existing systems
+- Where the cost estimate is likely wrong
+- Simpler alternative approach (if one exists)
+
+If --design or --gtm agents are present, their outputs are included here as additional evidence.
+
+**Phase 4 — ROUND 2 VERDICT**
+
+Orchestrator issues verdict:
+- APPROVED APPROACH: technical approach as modified by debate
+- MODIFICATIONS FROM DEBATE: what changed from the architect's original proposal
+- COST ESTIMATE: agreed estimate with confidence range
+- RISKS ACKNOWLEDGED: known risks accepted going forward
+
+---
+
+#### ROUND 3: RISK AND COST DEBATE (skip if --fast or --lite)
+
+**Phase 1 — DA CLAIM**
+
+The Devil's Advocate presents the risk case:
+- PRE-MORTEM: 3 specific failure modes, each with evidence from codebase or domain
+- SCOPE CREEP FORECAST: which locked must-haves are likely to expand during implementation and why
+- COST REALITY CHECK: where the Round 2 estimate is likely to be exceeded
+- THE KILL QUESTION: a structured argument for whether this feature should be built at all (PM and Architect must respond to this)
+- ACCEPTANCE TEST GAPS: which acceptance criteria are untestable or ambiguous
+
+If --design or --gtm agents are present, include their outputs as supporting evidence.
+
+**Phase 2 — PM + ARCHITECT DEFENSE**
+
+PM and Architect respond to each risk point:
+- ACCEPT: risk is real, we accept it and proceed
+- REJECT: risk is not valid — here is the evidence
+- MITIGATE: risk is real, here is the mitigation plan
+
+Each response must include evidence (not just assertion).
+
+**Phase 3 — DA FINAL**
+
+Devil's Advocate issues final verdict:
+- SATISFIED or UNSATISFIED per defense item
+- Overall confidence rating: HIGH / MEDIUM / LOW
+- If KILL QUESTION remains unanswered or defense was weak: flag as ESCALATE
+
+**Phase 4 — ROUND 3 VERDICT**
+
+Orchestrator issues verdict:
+- ACCEPTED RISKS: risks both acknowledged and accepted
+- MITIGATED RISKS: risks with approved mitigation plans
+- KILL CRITERIA: conditions under which implementation should stop
+- CONFIDENCE: rating from all 3 agents
+- PLAN STATUS: one of:
+  - APPROVED — all conditions met, proceed
+  - APPROVED WITH CONDITIONS — proceed, but note conditions explicitly
+  - ESCALATE TO USER — unresolved items require human decision
+
+---
+
+#### LITE MODE: RISK CHECKLIST (replaces Round 3)
+
+After Round 2, the orchestrator runs a checklist:
+- Any must-have with complexity >= L?
+- Any item touching auth, payments, or data migration?
+- More than 5 backend tasks?
+- Any new database table?
+
+Each matched item is flagged as a RISK NOTE in the plan.
+
+---
+
+### 8. Convergence Logic
+
+**Plan is APPROVED when ALL of the following are true after all applicable rounds complete:**
+- Rounds 1 and 2 have zero UNRESOLVED items
+- At least 2 of 3 agents (PM, Architect, DA) rate confidence >= MEDIUM
+- DA rates confidence >= MEDIUM
+- DA does not recommend KILL
+
+**Escalate to user when ANY of the following are true:**
+- Any round has UNRESOLVED items
+- DA confidence is LOW
+- DA recommends KILL and PM + Architect disagree
+
+If user overrides a KILL recommendation, record as `USER OVERRIDE` in the plan.
+
+In lite and fast modes, skip convergence checks for rounds that were not run. Apply only the checks applicable to completed rounds.
+
+### 9. Scope Lock
+
+After convergence, compute a `scope_hash`:
+- Concatenate all locked MUST-HAVE strings from Round 1 in order
+- Compute SHA-256 of that string
+- Write the hash into the plan file frontmatter as `scope_hash`
+
+When `/implement` loads the plan, it can verify the hash against the locked must-haves to detect tampering.
+
+### 10. Write Plan File + Present to User
+
+Synthesize teammate outputs into a structured plan and **write it to `.claude/plans/{feature-name}.md`** using the Write tool. This file is read by `/implement` to auto-configure the implementation team.
+
+**Plan file format:**
+
+```markdown
+---
+feature: {feature-name}
+debate_mode: {DEBATE_MODE}
+scope_hash: {SHA-256 of locked must-haves}
+da_confidence: {HIGH|MEDIUM|LOW|N/A}
+layers:
+  - frontend  # include if ANY frontend tasks exist
+  - backend   # include if ANY backend tasks exist
+---
+
+# Planning Summary: {feature-name}
+
+## Problem & User Segment (from PM)
+...
+
+## Technical Approach (from Architect)
+### API Contract
+...
+### Database Changes
+...
+
+## Design Direction (from Design, if included)
+...
+
+## GTM Notes (from GTM, if included)
+...
+
+## Scope Lock
+
+**Locked Must-Haves:**
+- [M1] requirement — BECAUSE reason
+- [M2] ...
+
+**Hard Boundary (Explicit Exclusions):**
+- ...
+
+**Deferred:**
+- ...
+
+**Rejected:**
+- ...
+
+## Implementation Cost Estimate
+
+| Item | Estimate | Confidence |
+|------|----------|------------|
+| {task} | {S/M/L/XL} | {HIGH/MED/LOW} |
+| **Total** | **{range}** | **{confidence}** |
+
+## Debate Record
+
+### Round 1: Scope Debate
+**Verdict:** {LOCKED / DEFERRED / REJECTED / UNRESOLVED items}
+
+### Round 2: Feasibility Debate
+**Verdict:** {APPROVED APPROACH / MODIFICATIONS / COST ESTIMATE / RISKS ACKNOWLEDGED}
+
+### Round 3: Risk and Cost Debate
+**Verdict:** {ACCEPTED RISKS / MITIGATED RISKS / KILL CRITERIA / CONFIDENCE / PLAN STATUS}
+*(Omitted in fast/lite mode)*
+
+## Task Breakdown
+### Backend Tasks
+1. ...
+### Frontend Tasks
+1. ...
+
+## Acceptance Criteria
+1. ...
+
+## Success Metrics
+...
+```
+
+**Rules for the `layers` field:**
+- Include `frontend` if the plan has ANY frontend tasks (UI changes, component work, frontend API integration)
+- Include `backend` if the plan has ANY backend tasks (routes, services, models, migrations, domain logic changes)
+- Include both if the plan spans both layers
+- This field drives which agents `/implement` spawns — get it right
+
+Present the plan to the user for review.
+
+### 11. Cleanup
+
+After user reviews the plan:
+- Send shutdown_request to all teammates.
+- TeamDelete after all teammates confirm shutdown.
+- Report: "Planning complete. Run `/implement {feature-name}` to start implementation."
+
+## Cost Optimization
+
+| Role | Model | Rationale |
+|------|-------|-----------|
+| explore-light (scan) | haiku | Just file search |
+| product-manager | opus | Strategic reasoning |
+| architect | opus | Technical design decisions |
+| devils-advocate | sonnet | Adversarial pressure, not generation |
+| design-thinker | sonnet | Creative but bounded |
+| design-critic | sonnet | Evaluation, not generation |
+| gtm-expert | sonnet | Strategic but scoped |
+
+**Cost by mode:**
+
+| Mode | Approx. Cost | Speed | Agents | Rounds |
+|------|-------------|-------|--------|--------|
+| Lite | ~421x | Fastest | PM + Architect | 2 rounds + checklist |
+| Fast | ~431x | Balanced | PM + Architect + DA | Rounds 1–2 only |
+| Full | ~641x | Most thorough | PM + Architect + DA | All 3 rounds |
+
+## Continuation (Workflow Chaining)
+
+After the plan is written and presented:
+
+**If autopilot is active** (check `.claude/.workflow-state.json` mode == "autopilot"):
+- Do NOT ask "should I proceed?" — proceed directly to `/implement {feature-name}`
+- Update workflow state: `phase: "implement"`
+
+**If guided mode** (no autopilot or mode != "autopilot"):
+- Present: "Plan ready at `.claude/plans/{feature-name}.md`. Next step: `/implement {feature-name}` to start coding. Should I proceed?"
+- Wait for user confirmation before invoking `/implement`