Scaffolds a multi-agent project setup from templates. The pattern is runtime-agnostic
(per ADR-001):
a single runtime-neutral persona.yaml hydrates working personas on whatever AI coding agent
you run — Claude Code, code-puppy, or anything else — at the highest fidelity that runtime
supports. It started as a Claude Code plugin and remains fully compatible with it.
This repo also ships a sister skill, multi-agent-audit, for grading multi-agent projects with evidence — INTERVENTION TAX, dual-lens drift, operational fidelity — instead of vibes. Read-only by construction. See Sister skill.
One front door: every new project (and every joiner) routes through
skills/agent-project-bootstrap/assets/collab-repo/START.md, which routes by directory state —
new/empty directory → ORCHESTRATE.md (set up a project), existing collab repo →
PARTICIPATE.md (join it). No modes to pick.
Migration note: this repo previously carried two generations of scaffolding flows. The pre-v1.0 Claude-Code-only emit modes are deprecated and quarantined in
legacy/(existing v0.x projects only). The full v0→v1 story lives in ADR-001 andCHANGELOG.md.
- You're running multiple agent sessions in parallel on the same long-lived project
- You want a knowledge layer (research findings, decisions, reconciliation log) that lives separate from the codebase
- You're a solo or near-solo developer who coordinates with several specialist agents rather than a human team
- You've used multi-agent setups before and want a repeatable starting point instead of rebuilding config files from scratch each time
- Your collaborators run different runtimes (Claude Code at home, code-puppy at work, ...) and you need one persona spec that works on all of them
- One-shot or throwaway tasks (a single agent session is simpler)
- Projects where you don't need persistent memory across sessions
- Team setups where human engineers handle coordination and you only need one agent at a time
A dedicated collab repo (the coordination substrate, separable from your code repo):
README.md # project overview
CONVENTIONS.md # repo-wide rules (single-account constraint, identity, labels,
# routing, handoff lifecycle, machine-local state)
COORDINATION.md # multi-persona protocol (hot files + lock mechanics, review/merge,
# ADR rules, ticket lifecycle)
manifest.yaml # machine-readable project spec (repos, backlog, roster)
canon/ # the runtime-neutral spec, copied in so joiners can resolve it
adapters/ # per-runtime HYDRATE.md (claude / code-puppy / generic)
agents/
<persona-slug>/
persona.yaml # CANONICAL machine truth: identity, capabilities, scope, ritual
AGENT.md # human-readable manual, derived from the yaml
_handoff/ # cross-persona async messages (append-only)
decisions/ findings/ # project decisions + investigation outputs
wiki/ # synthesised by the Librarian
Persona archetype templates shipped (each persona.yaml + AGENT.md):
- dev — interactive persona, one per human collaborator
- librarian — wiki + indexes + drift checks; always present
- autonomous-event — webhook-triggered (e.g. PR checks, backtest runner)
- autonomous-cron — scheduled (e.g. PM+UAT)
- reviewer / merger (optional, ADR-002) — adversarial SHA-bound PR review + a merge gate that isn't the human owner
Plus the /vc slash-command template (assets/commands/vc.md) for the canonical
<persona>: <op> | <description> commit workflow.
Personas are defined once in a runtime-neutral persona.yaml (identity, abstract
capabilities, scope, session ritual). Each runtime maps those abstract capabilities onto its
real tools via an adapter — the only runtime-specific surface. Adding a runtime means
adding an adapters/<runtime>/ folder and touching nothing else.
A persona always runs at the highest tier its runtime supports (the capability ladder), and degrades gracefully:
| Tier | Runtime | Mechanism | Enforcement |
|---|---|---|---|
| 3 | Claude Code or code-puppy | native sub-agents (Claude .claude/agents/<slug>.md; code-puppy JSON agents) |
capabilities enforced via a tool allow-list — whole-tool denials are real (a read-only persona genuinely cannot write/run shell); sub-tool denials instructed |
| 2 | Claude Code | persistent CLAUDE.md |
persistent session context; capabilities instructed |
| 1 | anything | in-prompt | persona re-read each turn; self-enforced |
The Claude adapter renders either Tier 2 or Tier 3, selected by a runtime-neutral
adapters.claude.tier config (auto | 2 | 3, default auto).
Key files:
START.md/ORCHESTRATE.md/PARTICIPATE.md— neutral entrypoints (front door + the two role recipes; routing is by directory state, not a human choice).adapters/{generic,code-puppy,claude}/HYDRATE.md— per-runtime mappings (genericis the mandatory Tier-1 fallback). Each carries a normalized, machine-readable capability map thattests/bi_runtime_accept.pychecks in CI.references/{capability-vocab.v1,persona.schema,manifest.schema}.md— the canonical spec.assets/collab-repo/manifest.example.yaml— a realistic worked example of the project spec.
See ADR-001 for the full design and ADR-002 for the field-proven July-2026 coordination rules baked into the templates (single-account constraint, everything-material- gets-a-handoff, lock-via-open-PR + CI guard, reviewer/merger personas).
Phase 2 of the roadmap converts the coordination conventions above into mechanisms:
baron (cli/, per ADR-003) is a
small typer CLI — a disciplined reader/writer over collab-repo files; the markdown/git
substrate stays the only database. Milestones M1–M3 are in:
baron validate— persona.yaml / manifest.yaml against the canonical schemas, with the frozen 10-verb vocabulary embedded and drift-guarded against the prose spec.baron status— clone/branch divergence (the three stranding classes from the 2026-07-22 field incident), overdue open handoffs, and ledger/wiki staleness, CI-usable exit codes.baron finding|decision new— race-safe F/D-number allocation via push-retry;baron handoff create|close|list(archive-not-delete lifecycle) andbaron index.
uv tool install ./cli && baron --helpThe other half of the kit: a read-only audit skill that grades multi-agent projects against an evidence-based rubric. Bootstrap builds projects; audit grades them.
| Property | Detail |
|---|---|
| Location | skills/multi-agent-audit/ |
| Headline metric | INTERVENTION TAX = human touches per autonomous task. High autonomy split + high tax = false win. |
| Read-only | Never modifies the audited project. Tool allow-list omits Edit; Write only for the report, outside the audited repos. |
| Framework-neutral | Works on agent-project-bootstrap, CrewAI, LangGraph, AutoGen, Copilot agents, custom loops. |
| Two-layer | Universal WHAT-to-measure + per-layout WHERE-it-lives discovery (Step 0). |
| Outputs | Markdown report + self-contained HTML dashboard (Chart.js + horizontal SVG timeline) + 1 KB short-form executive summary (md or html) + machine-readable snapshot JSON for trend analysis. |
| v1.3 enhancements | Multi-substrate Agents lens (claim labels + handoffs + frontmatter, not just git log); snapshot addenda: field for revising shipped point-in-time records; weighted operational-fidelity option; 5 stdlib Python helpers (trend reader, timeline extractor, Brandes' betweenness centrality, coverage parsers, per-persona PR attribution); HTML renderer + short-form renderer; subagent-isolation smoke test + automated contract checker. |
Invoke via the bundled project-auditor subagent (skills/multi-agent-audit/agents/project-auditor.md) which enforces the read-only rule at the tool layer, or read SKILL.md directly from any runtime.
Full workflow: Discovery → Agent Inventory + DUAL-LENS drift pass → Metrics mining (platform, not just git) → 1–5 axis scoring → Markdown/HTML report → snapshot persistence (trend mode kicks in once ≥2 snapshots exist).
/plugin install https://github.com/vggg/agent-project-bootstrap # from GitHub
/plugin install /path/to/agent-project-bootstrap # from a local clone (e.g. for development)
The
/plugin installcommand syntax may evolve as Claude Code matures. If the above fails, check the Claude Code docs for the current install command format.
On code-puppy? It doesn't auto-discover the Claude skill format — see
USING-WITH-CODE-PUPPY.mdfor the invoke-by-file-path quickstart.
After installation, tell your agent something like:
"Use the agent-project-bootstrap skill to set up a new multi-agent project."
The skill routes through START.md: in a new/empty directory it follows ORCHESTRATE.md
(interviews you for project name, repos, backlog source, persona roster; authors
manifest.yaml; hydrates each persona via your runtime's adapter). In an existing collab
repo it follows PARTICIPATE.md (claim a persona, hydrate yourself, run the session ritual).
The archetype templates use {{PLACEHOLDER}} tokens for names, scopes, and identity — name
your personas whatever fits your working style. The structural patterns (three-tier write
ownership, capability allow/deny per persona, handoff protocol, COORDINATION.md as single
source for cross-agent rules) are what carry the value, not the names.
The reviewer/merger module and the CI lock guard are opt-in — small teams without contested seams may not need them.
This skill codifies a multi-agent coordination pattern developed through real iteration on several software projects. The goal is to make the setup repeatable without requiring each new project to rediscover the same structural decisions.
MIT License · vggg