ai-setup: Command for Claude Code

Draft an implementation plan, grill it with independent adversarial reviewers, and — once the user approves — save the refined plan as a checked-in artifact that rides with the stacked PRs.

Use this for any non-trivial task where a weak plan would compound into a bad implementation.

/plan grills an approach — before any code exists; it attacks the reasoning. To grill a diff you've already written, use /grill instead. (Same adversarial fan-out, different target.)

Steps

1. Derive a slug for the plan file:

   • Grep the current branch name and the last 5 commit subjects for \b[A-Z]{2,}-\d+\b. If a Jira-style key matches (e.g. AUTH-1234), slug = that key.
   • Otherwise, build a 3–5 kebab-case word summary of $ARGUMENTS, prefixed with a verb when one fits — feat-rotate-oauth-keys, fix-auth-race, chore-bump-deps, refactor-payments-module. If no prefix fits, drop it (migrate-to-rsc).
   • If $ARGUMENTS is empty or too thin to summarise, ask the user for a slug before continuing.

2. Draft a plan based on $ARGUMENTS (the task). Structure:

   • Goal — one sentence.
   • Files to touch — concrete paths.
   • Steps — GitHub-checkbox list (- [ ] step); each small enough that progress is observable as work lands.
   • Edge cases — concurrency, retries, partial failure, untrusted inputs.
   • Out of scope — explicit non-goals.
   • Acceptance criteria — how we'll know it's done.

   Keep the plan tight — 10–20 bullet points, not an essay. Don't save it to disk yet.

3. Grill the plan adversarially. A plan reviewed by the same model that wrote it self-anchors — it confirms its own assumptions instead of attacking them. Instead, fan out independent reviewer subagents, each a fresh context with one adversarial lens. Synthesis and the decision to loop back stay with you (the main loop).

   Size the grill to the plan — this is the cost dial; don't throw 8 Opus reviewers at a one-file fix. Announce the setup in one line and let the user retune before launching. Invoking /plan is your opt-in to run the Workflow, so don't ask whether — only let them change the model or lens set:

   • Small (bug fix, refactor, ≤ ~3 files / ≤ ~5 steps) → the core 4 lenses (★) on Sonnet.
   • Large (greenfield, many files, new abstractions) → all 8 lenses on Opus.
   • e.g. "Small plan → core 4 lenses on Sonnet. Say 'opus' or 'all 8' to widen, otherwise I'll launch."
   • Frontend plans (the plan adds/changes UI — .tsx/.jsx/.vue/.svelte/.html or component/page/form files, same signal as /grill) → invoke the test-locators skill first, then add the locators lens below. Skip it for backend-only plans.

   The lenses (core 4 marked ★) — each reviewer gets exactly one:

   • ★ assumptions — Which single assumption, if wrong, breaks the whole plan? What did the author inherit without confirming?
   • ★ failure_modes — What fails silently? Which new codepath has no error handling or a swallowed error?
   • ★ dependencies — Does each step really depend on the prior one, or is the order arbitrary? Is every acceptance criterion concrete and testable, not "works correctly"?
   • ★ alternatives — Was a simpler approach dismissed too fast? Is there a 1-file fix behind a 5-file plan?
   • scope_drift — What snuck in beyond the goal? What belongs in "Out of scope" but isn't there?
   • testing_gaps — What edge case passes the plan's checks but still breaks prod? What does each acceptance criterion actually prove?
   • missing_risks — What risk is suspiciously absent? (rollback path, data migration, observability gap)
   • business_fit — Does the approach serve the actual goal, or has it drifted into a neat solution to the wrong problem?
   • locators (frontend plans only) — Apply the test-locators skill: does the plan ensure new interactive/asserted elements get stable data-testid/data-test (business-meaningful, not position/CSS-based)? If the plan adds UI but never mentions test locators, that's the finding.