arthai-marketplace

/implementation-plan

Spin up an adversarial planning team for a feature whose PRD already exists. Reads .claude/specs/.md, runs the PM + Architect (+ Devil's Advocate) debate, and writes a locked-scope plan to .claude/plans/.md.

Synopsis

/implementation-plan <feature-name> [--design] [--gtm] [--fast] [--lite] [--lite-strict] [--sync]

When to use it

After you’ve reviewed (and edited, if needed) the PRD that /planning produced
You want scope locked and a task breakdown debated before any code is written
Not for: drafting the PRD itself — that’s /planning; or building — that’s /implement

Non-interactive mode (CI/Autopilot)

If the environment has CLAUDE_AUTOPILOT=1 or CI=true set, the skill runs non-interactively and will not prompt you. In that mode:

feature-name is required
One mode flag is required: --fast, --lite, or omit it for Full mode

If a required argument is missing, the skill prints an error and exits non-zero instead of asking. If running this from a script or CI pipeline, pass the mode flag explicitly rather than relying on the interactive debate-depth prompt.

Quickstart

/implementation-plan dark-mode

What you’ll see: a debate-depth prompt (Auto / Fast / Lite / Full), then the PM + Architect (+ Devil’s Advocate) debate runs, and a locked-scope plan lands at .claude/plans/dark-mode.md with must-haves, exclusions, cost estimates, and a task breakdown.

Examples

/implementation-plan dark-mode              # full mode by default — 2 debate rounds
/implementation-plan dark-mode --fast       # PM + Architect only, 1 round — quick iterations
/implementation-plan dark-mode --lite       # adds Devil's Advocate, 1 combined round
/implementation-plan checkout --design      # adds Design Thinker + Design Critic to the debate
/implementation-plan checkout --gtm         # adds GTM Expert for launch positioning
/implementation-plan dark-mode --sync       # append new PRD items to an existing plan

The task breakdown in the plan is automatically phased (organized into ### Phase N sections) when tasks have natural sequential dependencies — Lite and Full mode only. Fast mode always produces a single-phase, flat breakdown for speed.

Arguments & flags

Flag	Values	Default	What it does
`--design`	—	off	Include Design Thinker + Design Critic teammates in the debate
`--gtm`	—	off	Include a GTM Expert teammate
`--fast`	—	off	PM + Architect only, single round, no Devil’s Advocate. Single-phase plan. Fastest.
`--lite`	—	off	PM + Architect + Devil’s Advocate in one combined round. Auto-escalates to Full if the DA flags HIGH-risk items (disable with `--lite-strict`).
`--lite-strict`	—	off	Same as `--lite` but disables auto-escalation. Does NOT auto-upgrade to Full mode even if DA flags HIGH-risk items.
`--sync`	—	off	Reconcile the existing plan against spec items added by `/planning --sync` — appends tasks, no debate re-run

No mode flag = Full mode (two debate rounds: scope, then feasibility).

What it does

Verifies the PRD exists at .claude/specs/<feature-name>.md — errors out otherwise (it never auto-runs /planning). If the PRD’s feasibility is RED, it pauses — user-confirmation checkpoint: continue anyway, cancel, or open the PRD.
Interactive resolution — asks for debate depth (Auto recommended — picks Fast/Lite/Full from PRD signals) and optional experts via AskUserQuestion (user-confirmation checkpoint; every question includes Cancel).
Context gathering — explore-light codebase scan plus topic wikis and the project knowledge graph/base.
Spawns the debate team in parallel — PM, Architect, Devil’s Advocate (unless --fast), plus design/GTM experts if flagged.
Structured debate — Round 1 (scope): PM claims must-haves traced to user stories, Architect counters on feasibility, DA attacks for scope creep and hidden assumptions, then a verdict. Round 2 (feasibility, Full mode): Architect leads with API contract, DB changes, and task estimates; PM and DA challenge. The PRD is authoritative — stories are not relitigated.
Escalation protocol — user-confirmation checkpoint: before any PRD-traced item is deferred or rejected, you’re shown the team’s reasoning and asked to keep it, accept the recommendation, or reduce scope. Your overrides are recorded in the plan and the DA may not re-challenge them.
Scope lock + plan write — locked must-haves are hashed (scope_hash) and the full plan (scope lock, technical approach, cost estimates, debate record, task breakdown, acceptance criteria) is written to .claude/plans/<feature-name>.md.
Completion verification + handoff — a completion-verifier agent checks the plan against the PRD, then in guided mode the skill asks before proceeding to /implement (user-confirmation checkpoint).

Agents spawned

Agent	Model tier	Role
explore-light	haiku	Codebase scan
product-manager	opus	Scope claim, owns the “what” and “why”
architect	opus	Technical approach, owns the “how”
devils-advocate (qa-challenger)	sonnet	Risk attack — skipped in `--fast`
design-thinker + design-critic	sonnet	UX brief and critique (`--design` only)
gtm-expert	sonnet	Launch positioning (`--gtm` only)
completion-verifier	sonnet	Plan-vs-PRD traceability check

Output & artifacts

.claude/plans/<feature-name>.md — the locked-scope plan, with frontmatter (debate_mode, scope_hash, spec_hash, da_confidence, layers)
Escalation log and debate record inside the plan (what was deferred, rejected, or user-overridden)
Architecture decisions written back to .claude/knowledge/shared/ and the knowledge graph

Design spec handling: If the PRD references a design spec (a companion HTML file from /planning) and it has gone stale — meaning the PRD was edited after the design spec was generated — the plan displays a warning: ⚠ Design spec is stale (prd_hash mismatch). Run /planning <feature> --design-spec-only to regenerate. This is a normal built-in check, not an error — the plan itself is still valid, but the design reference may be out of sync with the current PRD.

Cost comparison by mode:

Mode	Approx. cost	Speed	Best for
Fast	~421x	Fastest	Quick iterations, small features, prototyping
Lite	~431x	Balanced	Medium features with some risk concerns
Full	~541x	Most thorough	Complex, high-stakes, or multi-system features

Troubleshooting

Problem	Fix
`no PRD found at .claude/specs/<name>.md`	Run `/planning <feature-name>` first, or `ls .claude/specs/` to check the name
Plan flagged `REQUIRES_HUMAN_DECISION`	Non-interactive runs can’t escalate to you — open the plan and resolve the UNRESOLVED items listed with team recommendations
Lite mode unexpectedly ran a second round	Auto-escalation fired (HIGH-risk DA findings) — pass `--lite-strict` to disable it
Plan warns the design spec is stale	The PRD changed after the design spec was generated — run `/planning <feature> --design-spec-only` to regenerate

/planning — phase 1: produces the PRD this skill consumes
/implement — phase 3: builds from the plan this skill writes
Workflow guide — the full planning → implement → PR flow

Session management after planning

By the time /implementation-plan finishes, the context window is heavy with debate output, the full PRD, and codebase-scan results. Before running /implement:

Best practice: start a fresh session — /clear, then open with a one-line brief: “Implement <feature-name> — plan at .claude/plans/<feature-name>.md”. This gives /implement a clean window and avoids context rot during the build.
Staying in this session? Run /compact focus on <feature-name> plan — planning done, ready to implement first, so the summary preserves what the build needs.
If a debate round produced a bad result, rewind (Esc Esc) to before that round and re-prompt with a correction rather than stacking fixes on a bad output.