plan-it

Turn a fuzzy idea into a buildable delivery package.

Hand it a brain-dump, a transcription, or a one-liner.
Get back specs, PRDs, epics — and a binding Test Contract per epic.

The planning front-end to /build-it: plan-it plans it, build-it builds it.

Install  ·  Why  ·  How it works  ·  The Test Contract  ·  What's inside  ·  Platforms

[!NOTE] Built for agentic delivery — the disciplined front-half of the lifecycle that ends exactly where an autonomous build agent begins.

Everyone has learned that agents can build. What still fails, quietly and expensively, is the step before: turning "here's roughly what I want" into something an agent can build unattended. Paste a fuzzy idea straight into a build agent and it invents the missing decisions, greenfields code that already exists, builds one component against a schema another component doesn't share, and reports "done" on work nobody defined a test for.

plan-it is that missing step, packaged as one command. It runs a ~10-phase discovery → spec → agile-split pipeline: it pre-grounds itself in your actual codebase (and the live system, not just the repo), fans out parallel research teams that must cite path:line for every claim, authors the design docs in dependency order, pauses at one batched human-decision gate, freezes a shared CONTRACT, then fans out squad teams to write PRDs + epics against it — each epic ending in a binding Test Contract the build must pass 100% before "done."

The bottleneck it kills

You describe a feature in three paragraphs and dispatch an agent overnight. In the morning: it picked a database schema in one file and a different one in another, "rebuilt" a service that was already deployed, made four irreversible architecture calls you never saw, and its report says everything works — verified against mocks it wrote itself.

None of that is a capability problem. It's a planning problem: no frozen contract for parallel work to agree on, no single gate where the human injects the decisions only a human can make, and no pre-registered definition of what "working" even means. plan-it fixes all three structurally — with a frozen CONTRACT.md that squads write to, one numbered decision round with a recommendation attached to every item, and a Test Contract authored at planning time, so the build agent inherits its Definition of Done instead of improvising one.

Installation

plan-it ships as both a Claude Code plugin and a portable SKILL.md (the workflow, on any agent). Pick your tool.

[!TIP] Universal installers understand the SKILL.md standard and drop the skill into the right place for 70+ tools — use these if your agent isn't listed below:

npx skills add DevOtts/plan-it -a <agent>   # e.g. -a cursor, -a codex ; add -g for global
gh skill install DevOtts/plan-it            # GitHub CLI

Peek first with npx skills add DevOtts/plan-it --list.

Claude Code · native

# 1. Register the marketplace
/plugin marketplace add DevOtts/plan-it

# 2. Install the plugin (plugin-name@marketplace-name)
/plugin install plan-it@devotts

Then invoke it with /plan-it <your idea, brain-dump, or transcription>. On Claude Code the skill can also drive the Agent tool for its research and squad fan-outs — the full parallel experience. (Skills-CLI alternative: npx skills add DevOtts/plan-it -a claude-code.)

Cursor

npx skills add DevOtts/plan-it -a cursor      # add -g for a global install

Codex · OpenAI Codex CLI

npx skills add DevOtts/plan-it -a codex
# or:  gh skill install DevOtts/plan-it

VS Code + GitHub Copilot

npx skills add DevOtts/plan-it -a github-copilot

Others · OpenCode · Windsurf · Zed · Gemini CLI · Cline · Amp · Warp …

npx skills add DevOtts/plan-it -a <agent>

Run npx skills add DevOtts/plan-it --list, then target your agent.

[!NOTE] On agents without a subagent/team mechanism, the fan-out phases degrade gracefully to sequential research — same pipeline, same gates, same artifacts, just slower. See docs/installation.md.

How it works

Three autonomous bursts, three human gates, one frozen contract.

  /plan-it  ─────────────►  docs/ + delivery/  ─────────────►  /build-it
  (discovery → spec → plan)   (the buildable package)            (builds it)

1. Intake & DoD lock (Phases 0–1). Accept the demand in any form — brain-dump, transcription, one-liner, pointers to sessions and repos. Restructure it into a numbered, individually verifiable Definition of Done for the planning job itself.
2. Scope governor (Phase 2, ⏸ G1). Pick size (S/M/L) and shape (from 5+ packaging shapes: multi-doc program, single-file PRD, research→locked-architecture, numbered PRD platform, refactor catalog…). A feature doesn't get a 4-squad org; a brownfield refactor doesn't get a greenfield vision doc. Confirm before burning effort.
3. Pre-ground + discovery (Phases 3–5). Locate exact paths first, then fan out parallel research teams — one non-overlapping slice each, every claim cited to path:line, findings staged to disk immediately. For plans touching a running system, ground against the live system, not the repo: hit configs, dump live registries, verify credentials actually work. Contradictions get adjudicated, not averaged.
4. Spec authoring (Phase 6). Design docs in dependency order — findings → vision & architecture → data contract → components → roadmap. Never greenfield when code exists; every doc maps what's already built and how to promote it.
5. The decision round (Phase 7, ⏸ G2). Every judgment call a human must make — repo topology, hosting, naming, build-vs-buy — batched into one numbered round, each with a recommendation attached. Answers get locked into the docs with owner + date.
6. Freeze & fan out (Phases 8–9, ⏸ G3). Freeze delivery/CONTRACT.md v1.0 — canonical entities, schema, interface, enums, repo map, the definition of "shipped." Then one squad team per repo lane writes PRDs + epics against it. Cross-cutting discoveries fold back as dated amendments (v1.0 → v1.1), so squads can't drift.
7. Verify + handoff (Phase 10). A consistency lint (counts add up, every goal has a test, IDs coherent across files), then the package: KICKOFF.md plus the exact copy-paste launch prompt for the build agent.

Five rules are enforced, not suggested: freeze the CONTRACT before parallel work · batch human decisions into ONE gate · idle ≠ delivered — verify every agent's output on disk · ground on the live system before the freeze · run the machine, not the prose. Full methodology in docs/methodology.md.

The deterministic core (v2)

v1's control flow lived entirely in prose — the exact "prose control flow" failure mode David Khourshid names in Beyond the Prompt: Goodbye Slop, Welcome Determinism: step-by-step instructions in markdown that you hope the agent follows, and sometimes it won't. v2 applies his "deterministic core, agentic shell" pattern to the pipeline itself:

The fuzzy phases — discovery, synthesis, authoring, judgment — stay LLM-at-the-node. Non-determinism at the edges, determinism at the core. And the same discipline flows into what plan-it plans: every confusing workflow found in discovery must get an explicit model in the CONTRACT ("Core-logic models"), so the build agent inherits structure instead of prose. On agents that can't run Node, everything degrades to plain JSON files and manual checks — the script is an accelerator, not a dependency.

v2.1 goes one step further on Claude Code plugin installs: a PreToolUse hook (scripts/hooks/planit-guard.mjs) hard-blocks writes to PRD/epic deliverables while the run's CONTRACT is unfrozen — the rule stops being an instruction the model follows and becomes something the harness refuses, with the deny reason (and the fix) returned to the model. Fail-open by design: it never interferes with non-plan-it work.

The Test Contract

The single thing that most raises delivered code quality: every epic ends by generating its own test contract — up to ~20 concrete, type-selected use-cases/scenarios with expected outputs registered at planning time — and the feature is not "done" until 100% of them pass.

This is Specification by Example (Gojko Adzic) + ATDD/BDD for code, and Eval-Driven Development for LLM features — authored at planning time so the cases are a binding contract, not an afterthought. And it's the bridge to the build: /build-it's Definition of Done is this contract. No partial ship, no VERIFIED-on-a-mock — a case whose real target is unreachable is reported IMPLEMENTED-NOT-VERIFIED, never a fake green.

What's inside

The output of a run is a package your build agent consumes:

docs/                          delivery/
  01-current-state-and-findings  CONTRACT.md      ← frozen v1.0, the law
  02-vision-and-architecture     00-program-plan.md
  03-data-model-and-contract     STATUS.md        ← the live board
  0N-…                           prds/prd-N-*.md
                                 epics/epics-N-*.md  ← each ends in a Test Contract
                                 KICKOFF.md + launch prompt

plan-it × build-it

They're two halves of one lifecycle, designed to compose:

Each also works standalone: plan-it's package is plain markdown any agent (or human team) can execute; build-it accepts any well-formed goal + DoD.

The third leg — review-it: plan-it plans, build-it builds, review-it verifies. The Test Contract plan-it authors per epic is exactly what review-it's contract-qa mode runs against the finished build — independent verification with an 11-rule gate catalog (no self-graded green), closing the plan → build → review triangle.

Status

3.0.1 — packaging patch: the plugin now installs from the shared DevOtts marketplace (/plugin install plan-it@devotts, alongside build-it) and the version is bumped to 3.0.1 for parity. No pipeline or enforcement changes.

3.0.0 — the field-hardened core line and the public debut of v3. Where v2 made the pipeline deterministic (2.0.0 explicit statechart with persisted run state + executable gate guards; 2.1.0 hard gate enforcement via a PreToolUse hook on Claude Code plugin installs — see The deterministic core), v3 makes the delivery package hard to fake: every mechanism below ships as a machine-checked invariant with a binding Test Contract case, and all v3 verbs/states are strictly additive over v2 (verified by gate-check machine-diff against the v2 baseline). Three layers land together in this debut:

• Enforcement floor — the founder mandates (FD-1 test-convention discovery + registration; FD-2 pre-freeze case review) and six write-time invariants: W1 contract hygiene, W2 environment preflight (ENV-FACTS probe manifest), W3 model-tier enforcement (no hardcoded model IDs), W4 status vocabulary, W5 computed-never-typed tallies, W6 kickoff pinning + packaging parity — plus mirror integrity across the root↔plugin tree.
• Enforcement reach — running v3 against a real external project (not plan-it's own dogfood) surfaced two silent freeze-guard bypasses; both are closed fail-closed (E1 freeze checks key off a discoverable run root, not an invocation flag or the dogfood path; E2 the inline-code stripper handles line-wrapped spans), with the protected v2 core still byte-identical.
• Adversarial depth (D4) — the crown-jewel dimension. A new adversary verb, wired as a hard gate (adversaryGate between verify and handoff), makes Test-Contract failure-mode depth an exit code, not prose: it demands modeled failure states (D-A1), recovery transitions (D-A2), failure states asserted as cases (D-B1), test-hooked governance rules (D-B2), and five cascade classes each covered-or-waived (D-B3). A genuinely linear/CRUD contract declares no state machine and the gate is N/A — no over-reach; silent absence fails closed. In a blind head-to-head against a v2-authored package (same fuzzy brief, same model, labels swapped across two judges + an adversarial checker), v3 wins D4, 5 vs 3 — breaking the prior tie on the exact dimension this line targets.

The underlying pipeline, gates, packaging shapes, and Test Contract discipline are unchanged from 1.0.0 and were reverse-engineered from real multi-squad planning runs — including the live-grounding rules, which trace one-for-one to failures where a repo-derived assumption contradicted the deployed system.

Validate locally before relying on it:

claude plugin validate .                    # the marketplace
claude plugin validate ./plugins/plan-it    # the plugin

Security considerations

• No secrets to install or run. The skill reads your repo and writes markdown.
• Live-grounding checks credentials work — it never stores them. Findings reference where a credential lives, not its value.
• Everything it produces is plain markdown in your repo, reviewable and diffable before any build agent touches it.

Platform compatibility

The pipeline is a SKILL.md, so it installs anywhere the open Agent Skills standard reaches.

Legend — ✅ Native: full parallel experience with subagent fan-outs. ✅ Supported: same pipeline, gates and artifacts; research runs sequentially where the host has no subagent mechanism.

License

MIT — see LICENSE and plugin.json. Use it, fork it, ship with it.

Built by DevOtts.