Good AI output depends on a great plan. Big Plan makes reviewing agent plans a first-class experience.
Warning
Pre-alpha. Big Plan has no compatibility contract until an explicit milestone establishes one. Commands, document formats, and rendered output may change together as the product finds its cleanest model.
Big Plan is built around one question: what is the best way to review a plan and reach agreement on it, before an agent acts?
An agent writes its plan as structured MDX, and Big Plan renders it into a rich local review document. The static authoring contract combines Markdown with validated components for decisions, code, reference data, schemas, file trees, and API contracts. The components and review sections describe the capabilities that ship today.
Big Plan focuses exclusively on that upfront moment of agreement - not code review, not project management. Everything runs locally, and the MDX file on your disk is the source of truth.
Give this stable prompt to your coding agent; the linked setup document stays current as the product evolves:
Set up Big Plan for me: read https://bigplan.dev/setup.md and follow it.
Prefer to do it yourself? Run the current release without installing it globally:
npx -y big-plan@latest guidance
npx -y big-plan@latest render plan.mdxSee the Installation guide for the explicit global-install alternative.
Read the plan-writing guidance, print or install the agent skill shell, validate a plan without writing anything, render it as self-contained themed HTML, or compile its validated contents as machine-readable JSON:
npx -y big-plan@latest guidance
npx -y big-plan@latest skill
npx -y big-plan@latest skill write <path/to/SKILL.md>
npx -y big-plan@latest validate <file.mdx>
npx -y big-plan@latest render <file.mdx> [output.html]
npx -y big-plan@latest compile <file.mdx> [output.json]
npx -y big-plan@latest review <file.mdx>
npx -y big-plan@latest service status
npx -y big-plan@latest agent <file.mdx>guidance prints the principles for writing a plan a human loves to review; the guidance reference owns which commands require a current acknowledgment.
skill prints the thin agent skill shell shipped with the package; skill write <path> installs that shell only when you ask (no silent overwrites).
Validation checks that the plan can be compiled and rendered, then applies linting rules to the authored plan without writing an output file.
Rendering applies the same linting rules, so a plan that fails lint never reaches a reviewer.
Rendered output defaults to <file>.html; compiled output defaults to <file>.model.json.
review serves the rendered plan locally so a reviewer can leave comments, and prints the stable address for that plan; the session address is a debugging detail, while a small local service keeps the plan address working across runtime restarts and big-plan service inspects or stops that service.
agent runs the coding-agent side of that live review exchange.
Rendered and compiled output sit next to the input by default, while the MDX file remains the canonical source and JSON is always derived output.
See the two-artifact delivery contract.
MermaidDiagram rendering additionally uses the pinned headless Chromium renderer at compile time; on a clean install, provision it once with bunx playwright@1.61.1 install chromium.
A responsive table of contents links to the document's level-two headings and highlights the section being read, and a Settings dialog holds saved appearance, colour-theme, and approval-message pages. Standalone documents open it from the gear; live reviews open it from More actions, alongside Markdown export.
In a live authoritative review, Approve plan records the current plan, its decision answers, and that message, then sends them to the agent as an approval mailbox request; Approve a plan owns the complete workflow.
Plans are prose plus validated components, like this callout:
<Callout type="warning" title="Deploy ordering">
Enable the worker before stale reads.
</Callout>Big Plan ships a thin skill shell under assets/skill/SKILL.md, embedded into the published package and printed by big-plan skill.
| Layer | Owns | Changes when |
|---|---|---|
Skill shell (big-plan skill) |
When to use Big Plan, how to invoke the CLI, and the mandatory "run guidance first" rule | Rarely - workflow framing only |
CLI guidance (big-plan guidance) |
Plan-writing principles and per-component usage | Often - product quality iterations |
| Package upgrade | Binary + embedded skill + guidance | Every release |
Update story for end users:
- Upgrade Big Plan (
npm i -g big-plan@latest, bump the dependency, or runnpx -y big-plan@latest ...). - New guidance arrives automatically on the next
npx -y big-plan@latest guidance- no skill-file edits. - Re-run
npx -y big-plan@latest skill write <path>only if the thin shell text itself changed (rare). - Prefer
npx -y big-plan@latestfor always-current one-off runs over silent global mutation. The CLI also exposes axi-sdk's built-inupdatefor global installs when you want that path explicitly.
Agents should not re-copy long guidance into chat memory as policy; the installed CLI is authoritative each session. See Use the skill for the agent-facing install path.
The full authoring contract lives in the documentation:
- Use the skill - install the skill shell and keep it fresh via package upgrades.
- Writing plans - what a plan document is, how the guidance gate works, and where each kind of rule lives.
- Linting rules - every authoring rule and its conservative matching boundaries.
- Components - the complete built-in component reference.
- Reference - one page per command, plus error codes, lint rules, configuration, and the files Big Plan writes.
- Review a plan - one page per reviewer job, from starting a review to approving it.
To preview components locally from a source checkout, run bun run build first. Then run node bin/big-plan.mjs guidance once and render the MDX components plan with node bin/big-plan.mjs render examples/mdx-components.mdx. The local executable reads the compiled files in dist/.
To inspect supported fences in both light and dark appearances, render the syntax-highlighting source the same way.
To see every DatabaseTableSchema scenario in one document, render the table-schema showcase.
Generated previews remain ignored by Git.
bun install
bun run build # regenerate embedded modules, then compile TypeScript to dist/
bun run test # Vitest and Node unit tests, including the script contract tests under scripts/ (regenerates embedded modules first)
bun run lint # ESLint, stylesheet-contract, design-system, and Prettier checks
bun run format # format authored files with Prettier
bun run gen # regenerate review-script, CSS, font, branding-asset, guidance, and skill modules
bun run test:e2e # browser tests of the rendered viewer (build first)
node bin/big-plan.mjs render examples/sample.mdxFormatting exclusions and their rationale are documented in .prettierignore.
Use bun run test, not bun test - the latter invokes Bun's own test runner instead of the package script.
See AGENTS.md for architecture, _internal/ENGINEERING_PRACTICES.md for engineering practices, and CONTRIBUTING.md for the contribution workflow.
The documentation site lives in _docs/.
Install its standalone dependencies and start the development server with:
cd _docs
bun install
bun run devFrom _docs/, build the static site with:
bun run buildEvery push to main builds the root package and documentation site, then deploys
_docs/dist to GitHub Pages through the docs workflow.
The one-time custom-domain setup requires repository and DNS-provider access;
the captain must approve the outward-facing launch and run the repository wizard
for the exact records, guided setup, and DNS/TLS verification:
./scripts/docs-domain-wizard.shAfter building the root package, regenerate the docs' light/dark component screenshot pairs from _docs/ with bun run screenshots.
To report a vulnerability, follow the security policy. The full policy and Big Plan's security model are on the security page.
FSL-1.1-MIT. Each release becomes available under MIT two years after it is published.