inkatze/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 a guardrailed **agent
harness**: the model brings the intelligence; planwright brings the
verification loops, bounded iteration, no-progress detection, and hard human
checkpoints that make autonomous coding shippable. Run one spec and it is an
autopilot; run several and it is an
agentic software factory with a human quality
gate at the end of the line.
> **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.
Why planwright
- **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.
Requirements
- **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.
Install
planwright installs through Claude Code's standard marketplace flow:
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.
Quickstart
Once installed, you drive five steps; planwright does the work between your two
controls:
1. **/spec-draft ** — interactively elicit the four-file spec bundle
(Status Draft).
2. **/spec-kickoff ** — 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 ** — 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 ** — 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.
Run it as a software factory
One signed-off spec is autopilot; several at once is a factory floor. Fleet
mode turns planwright into a small **agentic software factory**: standardized