superplan

Superplan

Superplan is a local contract compiler for autonomous software work. It turns vague build requests into hash-pinned plans, measurable /goal contracts, verification requirements, and an optional local mission-control board called Superboard.

Superplan
├── /superplan skill        compile PLAN/ACCEPTANCE/VERIFY/POLISH/LOCK/GOAL
├── superplan-go           run the locked goal through Claude Code
└── Superboard             queue many Superplan jobs and review them safely

What It Is

Superplan owns the build contract. It writes the planning artifacts under .superplan/ for standalone work, or under .superboard/tasks/<task-id>/superplan/ when the board is managing a queue.

Superboard is the board feature inside Superplan. It lets you brain-dump cards, promote them to To Do, run each through Superplan, dispatch execution, inspect logs, and accept finished work only after human review.

Claude/Codex are workers. They execute the locked goal; they do not define done after the fact.

Install

From GitHub:

npm install -g github:robzilla1738/superplan
superplan doctor

From source:

git clone https://github.com/robzilla1738/superplan.git
cd superplan
npm install
npm link
superplan install-skills

The npm install automatically installs both companion skills:

• superplan: the contract compiler skill used as /superplan
• superboard: the board coordination skill used by agents working from the queue

They are linked into ~/.claude/skills/, ~/.codex/skills/, and ~/.agents/skills/. You can re-run superplan install-skills at any time. Use --local to install project-local copies into ./.claude/skills/ and ./.agents/skills/.

The global CLI is superplan. The board is available as the default superplan view or explicitly with superplan board.

Standalone Superplan Flow

Use this when you have one task and want a strong execution contract before an agent starts coding.

/superplan Build team invites with role-based access

The skill creates:

.superplan/
├── PLAN.md
├── ACCEPTANCE.md
├── VERIFY.md
├── POLISH.md
├── RISKS.md
├── STATE.md
├── GOAL.txt
├── LOCK.json
└── plan.html

After lock, superplan-go submits the compiled /goal to Claude Code unless SUPERPLAN_NO_AUTOKICK=1 is set.

Board Flow

Use this when you want a queue of tasks picked up in order.

cd ~/your-project
superplan init
superplan add "Build team invites with role-based access"
superplan add "Polish mobile nav copy" --priority 30
superplan

In the TUI:

• Press a to add a card to Brain Dump.
• Use arrows or hjkl to move around.
• Press m on a card, then T, to move it to To Do.
• Press r on a To Do card to start Planning.
• Run the shown Claude command, then invoke /superplan <task request>.
• When Superplan writes a valid contract, the card moves to Ready.
• Press r again to run the locked goal through superplan-go.
• The card moves to Review when execution exits.
• Press Y to accept into Done, or N to send it back to To Do.

Agents can move work to Review, not Done. Done is a human acceptance state.

Commands

Human commands:

Command	Behavior
superplan	Open the Superboard TUI
superplan init [--provider <p>] [--mode <m>]	Create .superboard/db.sqlite and config
superplan add "<text>"	Add a card
superplan move <id> <col>	Move a card
superplan status [--json]	Show board state
superplan doctor [--json]	Check local readiness
superplan install-skills [--local]	Install Superplan and Superboard skills
superplan accept <id>	Human-only Review -> Done

Agent-safe commands:

Command	Behavior
superplan next --json	Get the next To Do task
superplan claim <id> --agent claude	Claim To Do -> Planning
superplan evidence <id> --kind test ...	Attach evidence
superplan block <id> --reason "<reason>"	Mark blocked
superplan review-ready <id>	Move to Review

Architecture

Superplan skill
  ├── compiles contract files
  ├── pins hashes in LOCK.json
  ├── writes GOAL.txt under the 4000-character /goal limit
  └── requires transcript-visible MANIFEST/STATE/FAILURE_PROBE/SELF_REVIEW

Superboard feature
  ├── SQLite state in .superboard/db.sqlite
  ├── Ink TUI
  ├── scheduler and filesystem watcher
  ├── per-task SUPERPLAN_ROOT directories
  └── Claude adapter using the bundled superplan-go runner

Claude Code is the supported execution path in V1. Codex planning and visibility are present; Codex headless execution is V2.

Development

npm install
npm run build
npm test
npm run dev -- <command>

License

MIT.