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. Phase 0: Spec Generation (before debate)

Before any debate rounds, the PM generates a spec doc that becomes the foundation for all subsequent work. This ensures user stories and edge cases are defined BEFORE architecture decisions.

Create the specs directory:

mkdir -p .claude/specs

Spawn PM agent (subagent_type="product-manager", model="sonnet") for spec generation only:

Prompt:

You are a Product Manager generating a spec doc for the feature "{feature-name}".

Feature brief: {FEATURE_BRIEF}

Generate a spec doc with these sections:

## User Stories
Write 3-7 user stories covering the happy path and key error states.
Format: "As a [user type], I want [action], so that [outcome]"
Each story must have:
- **Story ID**: US-1, US-2, etc.
- **Priority**: P0 (must-have for launch) or P1 (important but deferrable)
- **Acceptance**: specific testable condition that proves this story is done

Example:
  US-1 [P0]: As a new developer, I want to install the toolkit with one command,
  so that I can start using it without manual configuration.
  Acceptance: `npx @arthai/agents install forge .` succeeds and skills are available.

## User Journey
Step-by-step flow from the user's first interaction to completion.
Include:
- **Happy path**: numbered steps (1. User does X → 2. System responds Y → ...)
- **Decision points**: where the user makes a choice (mark with ◆)
- **Error branches**: where things can go wrong (mark with ✗ and show recovery path)

Format as a text flowchart:

1. User discovers feature
2. User does [action] ◆ Decision: [choice A] or [choice B] → Choice A: proceed to step 3 → Choice B: proceed to step 5
3. System responds with [result] ✗ Error: [what went wrong] → Recovery: [how to fix]
4. ...

## Edge Cases
Structured list of what can go wrong. For each:
- **ID**: EC-1, EC-2, etc.
- **Scenario**: what triggers this edge case
- **Expected behavior**: what should happen (not crash, not hang)
- **Severity**: Critical (blocks user) / High (degrades experience) / Medium (inconvenience)
- **Linked story**: which user story this edge case relates to

## Success Criteria
Measurable outcomes tied to user stories. These become the acceptance criteria
that /implement and /qa use to validate the implementation.
- Each criterion references a story ID
- Each criterion is binary: pass or fail, no subjective judgment

Write the output to .claude/specs/{feature-name}.md with this frontmatter:

---
feature: {feature-name}
generated: {ISO date}
stories: {count}
edge_cases: {count}
---

Store the spec content as FEATURE_SPEC — this is injected into the shared context block for all debate participants.

4. 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.

4b. Wiki Discovery (context-loading.md Tier 1→2)

Check for topic wikis relevant to this feature:

# Find all topic wiki indexes
ls -d .claude/wikis/*/wiki/index.md 2>/dev/null

If wikis exist:

1. Read each wiki/index.md (Tier 1 — small catalog)
2. Grep each index for keywords from FEATURE_BRIEF and feature-name
3. If matching pages found, read them (Tier 2 — selective, max 5 pages total)
4. If any wiki has > 20 pages, use explore-light (haiku) to search instead

Store relevant wiki excerpts as WIKI_CONTEXT. If no wikis or no matches, set to "No topic wikis found. Consider /wiki-knowledge-base init {topic} for domain research.".

5. Create Team + Tasks

Create team: planning-{feature-name}

Create these tasks:

Task	Owner	Subject
0	product-manager	Generate spec doc for {feature-name} (Phase 0 — already done above)
1	product-manager	Define product scope for {feature-name} (uses spec as input)
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}

6. 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}

## Spec Doc (from Phase 0)
{FEATURE_SPEC}

(Full spec at: .claude/specs/{feature-name}.md)

## 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.

## Knowledge Base (MANDATORY — follow context-loading.md protocol)
After the plan is finalized, write back:
- Architecture decisions → `.claude/knowledge/shared/decisions.md`
- New patterns established → `.claude/knowledge/shared/patterns.md`
- Domain rules discovered → `.claude/knowledge/shared/domain.md`

## Topic Wiki Context
{WIKI_CONTEXT}

7. 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'. You generated the spec doc in Phase 0 — your user stories and edge cases are in the shared context above. Use them as the foundation for your scope claim.\n\nIn Round 1, you LEAD with your scope claim. Each must-have should trace to one or more user stories (reference by ID, e.g., 'US-1, US-3'). Format your must-haves as:\n [M1] requirement — BECAUSE reason (traces to US-X)\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 the user journey as specified? Is it over-engineered? What is the time-to-value? Reference edge cases the approach doesn't handle.\n\nIn Round 3 (full mode only), you DEFEND against the devil's advocate's risk case. Accept or reject each risk with evidence. Reference user stories to justify why a must-have cannot be cut."

• 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."

8. 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.

---

9. 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.

10. 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.

11. 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:

---
feature: {feature-name}
debate_mode: {DEBATE_MODE}
scope_hash: {SHA-256 of locked must-haves}
da_confidence: {HIGH|MEDIUM|LOW|N/A}
spec: specs/{feature-name}.md
layers:
  - frontend  # include if ANY frontend tasks exist
  - backend   # include if ANY backend tasks exist
---

# Planning Summary: {feature-name}

## Spec Reference
See `.claude/specs/{feature-name}.md` for user stories, user journey, edge cases, and success criteria.

## 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.

12. 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