multi-agent-template

Cookiecutter template + bootstrap CLI for new multi-agent Claude Code projects.

Generates a fresh multi-agent project pre-wired with the governance-core package — safety hooks, proposal workflow, wrap-up discipline, constitution iteration, cross-clone sync.

One-line bootstrap

# One-time setup (per machine)
pip install cookiecutter
pip install governance-core
pip install multi-agent-bootstrap

# Bootstrap a new project
multi-agent-bootstrap new my-project \
    --agents core,data \
    --ritual-phrase "Acknowledged"

# Open in Claude Code
cd ~/workshop-claude/my-project/agent-core
claude

Output:

~/workshop-claude/my-project/
├── agent-core/                 (master branch; governance role)
│   ├── .claude/                (50+ hooks/skills/commands/agents)
│   ├── .governance/            (config.json + 17 clauses + keywords)
│   ├── CLAUDE.md               (project constitution — business clauses
│                                inherit governance clauses)
│   ├── constitution/           (total.md + per-agent agent.md)
│   ├── contracts/              (proposal/knowledge schemas)
│   ├── knowledge/              (governance docs + your project docs)
│   ├── tools/                  (31 generic governance tools)
│   └── agent_rules/            (scope allow/deny)
├── agent-data/                 (feature/data branch)
├── shared_state/               (per-project; outside all clones)
│   └── proposals/              (cross-clone shared runtime state)
└── ...

See docs/getting-started.md for the complete walkthrough.

Adopt an existing project (expand)

Already have a single-repo project with governance-core installed, and want to add the multi-agent N-clone layer without losing its content? Use expand (P-0068) — it overlays the multi-agent layout onto an existing GC-installed project, complementing the greenfield new:

multi-agent-bootstrap expand ~/workshop-claude/auto-tax --agents core,filing

It works on either input:

• An existing git repo — git history is preserved; a clean working tree is required.
• A pure folder (just governance-core install-ed, not yet git init-ed) — a fresh master-branch repo is created during the sink.

What happens:

1. The whole project is backed up to a sibling …​.expand-backup-<ts>/.
2. Phase 1 — existing content (and git history, if any) is sunk into <project>/agent-<core>/; shared_state/ is initialized alongside.
3. Phase 2 — one git clone per business agent → agent-<role>/ on feature/<role>.
4. Phase 3 — governance-core install is re-run per clone (reusing the existing project's authorization — same consumer, no new code), migrating the topology single → multi agent.

If any step fails the project is rolled back from the backup to its pre-expand state. The backup is retained on success — delete it once verified.

CLI reference

multi-agent-bootstrap new <project_name> [options]

Options:
    --agents=NAMES            Comma-separated agent list (default: core,data)
    --ritual-phrase=PHRASE    First-line session ritual (default: Acknowledged)
    --install-root=DIR        Output parent dir (default: ~/workshop-claude)
    --core-agent-name=NAME    Governance agent name (default: core)
    --no-bootstrap            Skip bootstrap script + governance-core install
    --force                   Overwrite if project_name already exists

multi-agent-bootstrap expand <project-path> --agents core,<role> [options]

Options:
    --agents=NAMES            Comma-separated agent list (core auto-included)
    --project-name=NAME       Project name (default: project directory name)
    --core-agent-name=NAME    Governance agent name (default: from config)
    --no-backup               Skip the pre-expand backup copy (not recommended)
    --no-reinstall            Restructure + fan-out only; skip Phase 3

How it works

1. cookiecutter render: The {{cookiecutter.project_name}}/ directory contains a skeleton with {{ cookiecutter.* }} placeholders. mab/cli.py calls cookiecutter's Python API to substitute your inputs.
2. bootstrap script: After rendering, mab/cli.py runs git init in the new project + calls governance-core install (directly via Python subprocess; avoids historical PowerShell JSON quoting issues).
3. governance-core install: Renders 17 constitution clauses with your ritual phrase substituted, copies 14 hooks + 7 commands + 22 skills + 2 agents to .claude/, writes 31 tools, sets up .gitattributes merge=ours for per-branch constitution/agent.md isolation.
4. Initial commit: mab/cli.py does git add -A + commits.

Result: a complete multi-agent governance scaffold in ~5 seconds.

Customization

After bootstrap, your project's .governance/config.json controls:

• project_name, install_root, shared_state_root, claude_dir
• core_agent_name, core_branches, ritual_phrase
• agents[] with name/branch/clone_dir per agent
• upstream_branch, constitution_layout

To add a new business agent later, edit agents[] + run governance-core upgrade --project-root . to refresh.

Project status

v0.3.0 (2026-05). API may break between minor versions.

License

MIT — see LICENSE.

Related

• governance-core — the governance package this template installs