@0-nazmi/bauplan

Bauplan

Turn a software idea into a complete, autonomous build kit. Any AI coding agent picks it up and builds the product story-by-story — with no guidance from you.

---

What it is

Bauplan is an open-source methodology and a small toolkit. You bring an idea. Bauplan produces a complete kit — live-verified research, a single source-of-truth (CANON.md), 10–14 spec docs, a numbered story backlog, parallel work lanes, and a native agent config for your chosen coding tool. An AI agent opens the kit and builds the product. You come back when it's done.

idea → research → CANON → docs → backlog → lanes → agent config → kit → agent builds it

The kit runs itself. Bauplan is what you run once. The kit it produces runs forever — or until the product exists.

---

What makes it different

Most planning approaches tell an agent what to do. Bauplan engineers the conditions that make autonomous multi-session builds succeed by default:

1. Research-verified dependencies Every library, framework, and service is checked live before being pinned: last release date, release cadence, governance (foundation-backed or solo-maintainer?), active CVEs, license changes, maintenance-mode flags. Abandoned projects are caught before they're baked into a CANON no one wants to update. Training-data versions are never trusted.

2. A single source of truth that wins every conflict CANON.md holds every version pin, route, data model, and quality gate. All other docs are required to agree with it. The rule — if a doc conflicts with CANON, CANON wins — is enforced in code (hooks, CI, agent instructions) not just convention. An agent working on any story can answer "what version of X?" without reading ten files.

3. Independent verification The agent that implements a story never verifies it. A fresh-context verifier re-runs the story's literal Verify block with no memory of how the code was written — and therefore no incentive to rationalize failures. This single pattern catches more bugs in unattended runs than any linting rule.

4. Context-free resumability A session hook injects the current board state (progress, next story, barrier, last lesson) at session start and after every compaction — in under a second, from a shell script. Any model, any tool, zero memory: every session knows exactly where the build stands. Stopping is always safe; restarting is always free. Claims survive crashes by design (a commit-to-main = claim, not a lock file).

5. File-ownership lanes Each parallel worker owns a set of paths. There is no coordination protocol — workers just don't touch each other's files. Collisions become impossible rather than managed. A cross-lane touch requires explicit Integrator review. This scales from one agent to five without any changes to the workflow.

6. The walking skeleton gate Milestone 1 is always the thinnest possible end-to-end slice — one real user action produces one real visible result. Nothing else merges until this gate is green. It forces proof of architecture before features and surfaces integration failures before they've compounded into a six-week rewrite.

7. Mandatory gap audit After the kit is generated, Bauplan turns fresh eyes on it: week-one failures (auth flows with no mailer, no container registry, no asset upload path, no content moderation), classic engineering gaps (no GC cron, no rate limits, no backup verification), legal and regulatory items. Gaps become an addendum; each is merged, deferred, or rejected by the owner — nothing lands silently.

8. Token discipline is architectural, not advisory The subagent pipeline (doc-scout, story-implementer, verifier, integrator) keeps the orchestrator's context small by design. Heavy reads go to doc-scout which returns a distilled extract. Code goes to story-implementer which returns a brief report. Verification goes to the fresh-context verifier. The main thread coordinates; it does not accumulate. This is not a tip — it is the structure.

---

Installation

Install once. Use everywhere.

# Recommended: one-line install (macOS / Linux)
curl -fsSL https://raw.githubusercontent.com/LIVELUCKY/bauplan/main/install.sh | bash

# Or via npm (works on all platforms including Windows with WSL)
npm install -g @0-nazmi/bauplan

# Or clone and install manually
git clone https://github.com/LIVELUCKY/bauplan.git ~/.bauplan
bash ~/.bauplan/scripts/setup-bauplan.sh

bauplan install:

• Copies the methodology to ~/.bauplan/ (the CLI's data dir — always)
• Asks before installing subagents + commands into ~/.claude/ (global, every Claude Code project). Decline it and use bauplan init per project instead. Flags: --yes (accept, non-interactive) · --skip-global (core only).
• Drops bauplan in /usr/local/bin or ~/bin

Prefer per-project? Skip the global install and run bauplan init — it asks which agents to set up and writes their config into the current project. OpenCode, Codex and Copilot need no global config at all; every kit ships their config in-tree (AGENTS.md, .opencode.json, .github/copilot-instructions.md).

Re-running init merges into existing configs (never overwrites): markdown via BAUPLAN markers, JSON/YAML via deep-merge — so your own keys and edits survive.

bauplan doctor        # verify everything is wired up

---

Quick start

Generate a kit for any project

The CLI scaffolds config; your chosen agent generates the kit. Tell it to run the /new-project flow:

Claude Code     claude  →  /new-project "A self-hosted form analytics tool — no SaaS"
GitHub Copilot  Copilot Chat: "Generate a Bauplan kit for: <idea>"
Codex/OpenCode  codex|opencode "Follow AGENTS.md. Generate a Bauplan kit for: <idea>"

The agent asks ≤3 questions, dispatches research scouts in parallel, writes CANON, generates the full doc suite, runs the gap audit, and hands you a ready kit — typically in 20–40 minutes.

From inside Claude Code (agents installed globally after bauplan install):

/new-project "A self-hosted form analytics tool"

Build the product

cd generated-kits/form-analytics
bash scripts/setup-claude.sh     # one-time per kit
claude                           # then: /next-story

Each story: /next-story → /clear → /next-story

The SessionStart hook re-injects board state after every /clear automatically — zero re-orientation cost.

---

Using with each tool

Claude Code (native — full feature set)

After bauplan install, the methodology is available in every project — no per-project setup:

/new-project "idea"          generate a kit
/review-kit [path]           gap audit on a kit
/bauplan-next-story          implement the next story (in a generated kit)
/bauplan-status              board report
/bauplan-barrier             run the next integration gate

The four subagents (bauplan-doc-scout, bauplan-story-implementer, bauplan-verifier, bauplan-integrator) are wired globally and available in all your projects automatically.

To add Bauplan to an existing project without generating a full kit:

cd my-existing-project
bauplan init

GitHub Copilot

Every generated kit ships with .github/copilot-instructions.md — Copilot Chat in VS Code auto-loads it, so the methodology is pre-loaded for every session in the kit.

To generate a kit via Copilot Chat:

"Generate a Bauplan kit for: <idea>. Follow METHODOLOGY.md."

For Copilot Workspace: create one GitHub Issue per story (template in prompts/copilot.md). See prompts/copilot.md for the complete guide including Copilot CLI usage.

OpenAI Codex

AGENTS.md at the repo root is auto-loaded by Codex. After bauplan install, ~/.bauplan/AGENTS.md is always available as a reference:

codex "Follow ~/.bauplan/AGENTS.md. Generate a Bauplan kit for: <idea>"

For a generated kit: codex "Read LOOP.md and STATUS.md. Implement the next ready story. Stop after Verify passes." — see prompts/codex.md.

OpenCode

OpenCode auto-loads the AGENTS.md + .opencode.json shipped in every kit (and added to any project by bauplan init) — no global setup needed:

opencode "Generate a Bauplan kit for: <idea>"

For a generated kit: one story per session, --no-auto-approve for complex stories. See prompts/opencode.md.

Any other agent / API

prompts/system-prompt.md is the complete methodology in one file. Paste it as the system prompt in any tool:

cat ~/.bauplan/prompts/system-prompt.md | pbcopy    # macOS
cat ~/.bauplan/prompts/system-prompt.md | xclip     # Linux

Then ask that agent to generate a kit. Generation is always the agent's job — the CLI only scaffolds config (bauplan init) and installs the methodology.

---

What a generated kit contains

---

How it works

flowchart LR
    A[Idea] --> B[Clarify ≤3 questions]
    B --> C[Parallel research scouts]
    C --> D[CANON — you write it alone]
    D --> E[Parallel doc writers]
    E --> F[Gap audit + owner approval]
    F --> G[Execution machinery]
    G --> H[Kit zip]
    H --> I[Agent builds the product]

    style D fill:#fef3c7,stroke:#d97706
    style F fill:#fee2e2,stroke:#dc2626

Phase 1 — Clarify. At most three questions. Anything skipped becomes a documented assumption in CANON.

Phase 2 — Research. Parallel scouts verify live: exact version + release date, governance, CVEs, maintenance flags. Rejected alternatives are documented. Nothing is assumed from training data.

Phase 3 — CANON. The orchestrator writes this directly — never delegates it. Consistency requires a single author.

Phase 4 — Docs. Parallel writers, each reading only CANON and their named context sections. Writers are instructed never to invent versions; if something contradicts CANON, CANON wins.

Phase 5 — Gap audit. Four passes: week-one failures, engineering gaps, legal/regulatory, deliberate exclusions. Each finding gets an explicit merge/defer/reject decision from the owner.

Phase 6 — Execution kit. LOOP.md, STATUS.md (seeded from backlog story count), parallel workstream spec, file scaffold, Claude Code agent config (subagents, hooks, commands), and a START-HERE.md.

---

Tool compatibility

---

Repo layout

bauplan/
├── README.md
├── METHODOLOGY.md           ← the full specification (principles, phases, story format, exec machinery)
├── AGENTS.md                ← auto-loaded by Codex, OpenCode, and any AGENTS.md-aware tool
├── LICENSE                  ← MIT
├── .github/
│   ├── workflows/ci.yml          ← validates scripts, JSON, required files on every push
│   └── PULL_REQUEST_TEMPLATE.md
├── prompts/
│   ├── system-prompt.md     ← self-contained, paste into any tool
│   ├── research-scout.md    ← template for dispatching research scouts
│   ├── doc-writer.md        ← template for dispatching doc writers
│   ├── gap-audit.md         ← the mandatory post-generation audit
│   ├── codex.md             ← OpenAI Codex integration guide
│   ├── copilot.md           ← GitHub Copilot integration guide
│   ├── gemini.md            ← Gemini CLI / AI Studio guide
│   ├── cursor.md            ← Cursor integration guide
│   └── opencode.md          ← OpenCode integration guide
├── templates/               ← copied verbatim into every generated kit
│   ├── CANON.md             ← CANON template with {{PLACEHOLDERS}}
│   ├── LOOP.md              ← per-session algorithm (generic, final — no placeholders)
│   ├── CLAUDE.md            ← orchestrator discipline (generic)
│   ├── STATUS.md.sh         ← seeds STATUS.md from backlog story count
│   ├── claude-config/       ← 4 subagents, 4 commands, 2 hooks, settings.json
│   └── scripts/
│       ├── setup-claude.sh  ← activates .claude config in a generated kit
│       └── stream-fmt.py    ← live agent activity pretty-printer
├── cli-commands/            ← bauplan's own slash commands (installed to ~/.claude)
│   └── commands/            ← /new-project, /review-kit
├── scripts/
│   └── setup-bauplan.sh     ← one-shot setup (idempotent)
└── generated-kits/          ← your kits land here (gitignored)

---

Running a generated kit

After bash scripts/setup-claude.sh:

claude

In Claude Code:

/next-story           ← implements one story end-to-end, stops, reports
/clear                ← fresh context (session hook re-injects board state)
/next-story           ← next story
/status               ← progress report (reads only STATUS.md)
/barrier              ← run next integration gate

For other tools, the equivalent is: read LOOP.md, read STATUS.md, implement one story, stop.

---

Contributing

• New tool integration → prompts/<toolname>.md + row in the tool table above
• Methodology improvement → update METHODOLOGY.md + prompts/system-prompt.md in sync
• New template file → update ci.yml required-files list
• PRs: bash -n scripts/*.sh + python3 -m py_compile templates/scripts/stream-fmt.py must pass

MIT License — see LICENSE.