arthai-marketplace

Tutorial: Plan and Implement a Feature

In this tutorial you’ll build a feature the toolkit way: /planning writes the PRD, you review it, /implementation-plan debates and locks the scope, and /implement spawns the team that builds it — running /qa and creating the PR via /pr at the end. You’ll also see every user-confirmation checkpoint along the way, so none of them surprises you.

Time: ~45–90 minutes depending on feature size You need: the toolkit installed and ideally calibrated (previous tutorial), and a feature idea you can describe in 2–3 sentences.

Step 1: Write the PRD

/planning dark-mode -- Users want a dark theme that follows system preference and persists per account

Everything after -- is the inline brief. (Leave it off and the skill asks for one interactively — every question includes Cancel.)

What happens: an explore-light agent scans your codebase for related routes, components, models, and tests; a Design Thinker writes a UX brief; the Product Manager writes the PRD (user stories with priorities and acceptance criteria, user journey, edge cases, success criteria); and the Architect writes a tech feasibility note in parallel.

You’ll end with:

• .claude/specs/dark-mode.md — the PRD
• .claude/specs/dark-mode-design.html — the design spec (skip with --no-design)
• A feasibility verdict: GREEN / YELLOW / RED

Then it stops. This is deliberate — /implementation-plan is never auto-invoked, because PRD review is the whole point of the two-phase split.

Step 2: Review the PRD and design spec

Open .claude/specs/dark-mode.md and read it like you’d review a teammate’s PRD: are the user stories right? Are the edge cases real? Edit the file directly if anything’s off. Open the -design.html sibling in a browser for the user journeys and key screens.

If feasibility came back YELLOW or RED, read the printed hard constraints now — revising the PRD at this stage is far cheaper than after the architecture debate.

Step 3: Lock the scope

/implementation-plan dark-mode

Checkpoints you’ll hit:

1. Debate depth prompt — Auto / Fast / Lite / Full. Auto is recommended; it picks from PRD signals. (If the PRD’s feasibility was RED, you’re first asked: continue anyway, cancel, or open the PRD.)
2. Escalation protocol — before any PRD-traced item is deferred or rejected, you see the team’s reasoning and choose: keep it, accept the recommendation, or reduce scope. Your overrides are recorded in the plan.
3. Handoff — after the plan is verified against the PRD, the skill asks before proceeding to /implement.

Between those, the PM and Architect (plus a Devil’s Advocate, unless --fast) run a structured debate — Round 1 on scope, Round 2 on feasibility in Full mode — and the result is a locked-scope plan at .claude/plans/dark-mode.md with must-haves, exclusions, cost estimates, a debate record, and a task breakdown.

Step 4: Build it

/implement dark-mode

Checkpoints you’ll hit:

1. Mode prompt — Auto / Guarded / Fast / Strict (how aggressively the red team challenges the build). Auto picks from plan size and risk keywords — auth, payments, and migrations escalate to Strict.
2. Red-team blocks — unresolved CRITICAL findings stop the flow and ask: fix / override / abort.
3. Phase prompts — multi-phase plans pause between phases and ask whether to proceed.
4. QA level — after the build: commit / full / staging / skip.
5. Manual test sign-off — local servers are restarted and the skill waits for your “ready” before shipping.

The team works in parallel: backend and/or frontend agents per the plan’s layers (backend shares the API contract with frontend before either implements), a QA agent traces every user story and edge case to code, and the red team attacks the diff and checks plan compliance.

Step 5: QA and PR

These run inside /implement’s post-implementation workflow, so you don’t invoke them separately: your chosen /qa level runs, and after your manual sign-off the PR is created via /pr --skip-qa (QA already ran, so /pr does only a quick lint + type sanity check). You get an implementation report, QA results, and a GitHub PR URL — then the skill asks what’s next.

What you learned

• The feature workflow is three phases with review gates between them: PRD → locked plan → build, each producing a file you own (.claude/specs/, .claude/plans/, then code + PR).
• /planning stops after the PRD on purpose — your review is the input to the next phase.
• /implementation-plan won’t silently drop scope: every deferral of a PRD-traced item goes through you.
• /implement chains QA and the PR for you, with checkpoints at mode selection, red-team blocks, QA level, and manual sign-off.
• For work that doesn’t fit this shape — a single fuzzy objective, or a ticket backlog — see Run autonomous work and the workflow comparison.

Next: you’ve finished the tutorials — the how-to guides cover incidents, CI recovery, autonomous work, and more.