planwright

planwright is an opinionated Claude Code framework for spec-driven development: you specify a feature precisely, sign it off, and the framework builds it — advancing tasks, opening draft pull requests, and converging review on its own — while you keep the two controls that matter: sign-off and merge.

Think autopilot, not a replacement crew. How well it flies is bounded by how good your spec is, so planwright's whole investment is getting the spec right before any code is written. Under the hood it is loop engineering with guardrails: the agent runs in autonomous review-and-execute loops (bounded by iteration caps, convergence criteria, and no-progress detection), and every irreversible action stops at a human checkpoint.

Status: v1, self-hosting. The founding spec (specs/bootstrap/) that defines planwright v1 is complete, and planwright now develops itself through the same pipeline it ships. It is young software — expect rough edges, and please report what you find.

New here? The getting-started guide takes you from a clean machine to running the pipeline end to end.

• Specs before code. Every feature is four files — requirements, design, tasks, tests — reviewed and signed off before a line is written. The spec is the contract the agent executes against, not an afterthought.
• You keep the controls. Two actions are human-reserved, permanently: sign-off (no spec runs until you have walked it and signed the brief) and merge (every PR is a draft; planwright never auto-merges). Everything in between is one revert from undone.
• Guardrailed autonomy. Review and execution run in bounded loops — iteration caps, convergence criteria, no-progress detection — with hard pauses at security-sensitive or irreversible steps.
• Adapts to your project. Supply your own linters, test commands, and review rigor through layered overlays, without editing planwright's core.
• Claude Code only. Built entirely on Claude Code primitives (skills, hooks, subagents, file-based state) — there is no second agent framework to install.

• Claude Code — a recent version with the plugin and skill system.
• git, and a GitHub repository with the gh CLI authenticated — planwright opens draft PRs through gh. Without GitHub/gh the pipeline degrades gracefully, but the pull-request flow is unavailable; see the GitHub requirement.

planwright installs through Claude Code's standard marketplace flow:

/plugin marketplace add inkatze/planwright
/plugin install planwright@planwright

For environments without plugin support there is a no-plugin ~/.claude/ writer (scripts/install.sh, portable shell only). Both modes, and the upgrade path, are covered in Install.

Once installed, you drive five steps; planwright does the work between your two controls:

   /spec-draft  →  /spec-kickoff  →  /orchestrate  →  /execute-task  →  review & merge
                        ▲                                                      ▲
                    sign-off                                                 merge
                  (gate 1: no spec                                    (gate 2: planwright
                   runs unsigned)                                      never auto-merges)

   └──── you author ────┘   └──── planwright runs the middle ────┘   └─── you decide ───┘

1. /spec-draft <feature> — interactively elicit the four-file spec bundle (Status Draft).
2. /spec-kickoff <spec-path> — walk the spec section by section to mutual understanding and sign the kickoff brief. Sign-off flips the spec to Active. (your first control)
3. /orchestrate <spec-path> — pick the next ready task, create its worktree, and dispatch execution. Stateless: one step per call, so you can run it in several sessions for parallelism.
4. /execute-task <ids> — test-first implementation, full CI with adaptive retry, convergence via /polish, then a draft PR.
5. Review and merge. (your second control)

The getting-started guide walks each step in depth.

planwright is an autopilot, not a replacement crew. Two controls are human-reserved, permanently:

• Sign-off — a spec executes only after you walk it at kickoff and sign the resulting brief. There is no bypass flag.
• Merge — every PR the framework creates is a draft; your draft→ready flip is the universal review gate, and merge is always your action.

Between them, the intervention contract has three phases: sign-off before execution, rare hard pauses during it (security-sensitive zones, destructive operations, irreducible judgment forks), and review plus merge after. Invariants the framework holds everywhere: never auto-merge; never act on a spec that is not Ready or Active; never force-push, amend, squash, or rebase (new commits only).

Every feature lives in specs/<feature>/ as four files:

• requirements.md — what must be true (REQ-IDs), with a Status: that moves Draft → Ready → Active → Done.
• design.md — the decisions and the alternatives weighed (D-IDs).
• tasks.md — the work as stable-ID tasks with Done when: / Dependencies:; it doubles as the orchestration ledger.
• test-spec.md — each requirement pinned to how it is verified.

The format is specified in full in the spec-format doctrine.

planwright ships eleven skills; each is a slash command in Claude Code.

planwright adapts to your project through overlays — layered config, doctrine, and catalog files that override the core defaults without editing planwright itself. Supply your own linters, test commands, and review rigor in a gitignored machine-local layer or a repo-tracked layer, and the framework merges them over its core. Defaults live in config/defaults.yml and every option is documented in the options reference (an undocumented option fails CI). See Customizing with overlays for the full model.

• Getting started — install, the GitHub requirement, operating the pipeline, and supplying your own tooling.
• Customizing with overlays — the four-layer model and per-kind merge rules.
• Conventions — branch, worktree, and repo conventions.
• Orchestration state — the derived-projection model: how progress is derived from git/GitHub evidence, the single-writer reconcile, and the no-remote flow. Version-keyed off each bundle's Format-version:: a format-version 2 bundle drops the committed snapshot entirely and reads status through the on-demand render.
• Fleet operation — the approachable path: the one entry command, the decision queue, the persona-to-seams mapping, and the execution-backend seam (autodetect, the degradation ladder, plugging in your own backend) — no multiplexer knowledge required.
• Options reference — every configuration option.
• Doctrine — the framework's rule docs: validation and discovery rigor, finding categorization, engineering decisions, security posture, and more.
• Contributing · Release checklist

.claude-plugin/   plugin + marketplace manifests (the install path)
skills/           the eleven planwright skills (one directory each)
doctrine/         the framework rule docs
scripts/          portable-shell entry points (installer, resolver, checks)
config/           tracked default config
docs/             guides (getting-started, overlays, conventions, options)
specs/            planwright's own specs (bootstrap = the founding spec)
tests/            shell tests for the scripts

planwright pins its toolchain with mise: run mise install once and scripts/wire-githooks.sh once per clone (the tracked git-hook backstop; the gate fails loudly on an unwired clone), then mise run check runs the full gate — shell tests, shellcheck, shfmt, markdownlint, yamllint, conventional-commit lint, manifest + link + options-reference checks, the ledger structural-corruption + duplicate-Status guard, the spec validator, the hook-wiring check, and a gitleaks scan. It is the same gate CI runs on every pull request. This is dev tooling only; planwright's runtime scripts stay plain portable bash. See Contributing for the workflow.

MIT.