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.