feat(cadre): ship Bonfire cadre as Claude Code subagent definitions

[Antawari]

Why

When the Bonfire cadre dispatches via Claude Code's Agent tool today, every dispatch surfaces as subagent_type: "general-purpose". The substance is Bonfire — the cadre methodology, the role discipline, the TDD law — but the label is generic. The framework is invisible at the most visible API boundary, and there's no discovery surface for users who install bonfire-ai and use Claude Code.

This PR fixes that. After install, dispatches surface as bonfire:scout-innovative, bonfire:knight, bonfire:warrior, etc. — the cadre at the API surface, sister-shape to vercel:*, agent-sdk-dev:*, and the other published Claude Code plugins.

What ships

Two install rails, one ship-train, same bonfire-public repo:

Plugin (canonical · colon-namespaced)

```bash
/plugin install bonfire@
```

Adds:

• `.claude-plugin/plugin.json` — manifest with six agent entries and an author block.
• `agents/.md` — six pre-rendered subagent files (`scout-innovative`, `scout-conservative`, `knight`, `warrior`, `sage`, `wizard`) with YAML frontmatter (`name`, `description`, `tools`, `model`, `cadre_contract`).

After install, the Claude Code subagent picker shows `bonfire:` entries and dispatches surface with that literal label.

Raw-files CLI (fallback · flat-named)

```bash

user scope (~/.claude/agents/bonfire/) is the default

bonfire install-agents

project scope

bonfire install-agents --scope project

inspect

bonfire list-agents

clean removal (manifest-driven)

bonfire uninstall-agents
```

The CLI rail exists for three structural reasons:

1. Plugin-shipped agents silently drop `hooks`, `mcpServers`, and `permissionMode` frontmatter per Claude Code's security policy. v1 cadre roles don't require those fields, but the rail must exist for future roles that might.
2. Raw user-scope agents are priority 4; plugin agents are priority 5. The CLI rail gives operators a "fork and override" lane — drop a customized `bonfire-scout.md` into `~/.claude/agents/` and the plugin copy is shadowed.
3. Plugin path requires Claude Code CLI. Users on Cursor, Codex, raw SDK, or pipx-isolated environments cannot enable plugins. The CLI rail is the universal channel.

The CLI rail also installs the `bonfire-powered` catch-all — a Bonfire-flavored general-purpose agent that sits flat-named in the picker next to `general-purpose` for users who want the cadre's discipline without picking a specific role. The catch-all does NOT ship via the plugin (head-to-head brand contrast requires flat naming).

New modules

• `src/bonfire/prompts/.md` — canonical prompt bodies (seven files: six cadre + catch-all). Wheel-bundled via the existing `[tool.hatch.build.targets.wheel].include` pattern.
• `src/bonfire/agent/role_metadata.py` — per-role metadata (description, tools, model). Sits adjacent to `agent/roles.py`'s `AgentRole` StrEnum.
• `src/bonfire/cadre/init.py` — `CADRE_CONTRACT_VERSION` constant + `resolve_role_prompt(role)` adapter (skeleton; see Out of scope below).
• `src/bonfire/cli/commands/build_agents.py` — generator that emits `agents/.md` from prompts + metadata. CI gates with `bonfire build-agents --check`.
• `src/bonfire/cli/commands/install_agents.py` — install / uninstall / list subcommands.

Versioning

Three orthogonal pins:

Pin	What it tracks
`bonfire_ai.version`	Library releases
Plugin `version` in `plugin.json`	Prompt-text changes
`CADRE_CONTRACT_VERSION` (in `bonfire.cadre`)	Dispatch-boundary breaking changes; stamped into each subagent's `cadre_contract` frontmatter

Inaugural ship: plugin `0.1.0` + `CADRE_CONTRACT_VERSION = "0.1.0"`.

Per-role tool scoping

Role	Tools	Notes
`scout-innovative`	Read, Grep, Glob, WebSearch, WebFetch	Read-only
`scout-conservative`	Read, Grep, Glob, WebSearch, WebFetch	Read-only
`knight`	Read, Grep, Glob, Write, Edit	No Bash — writes RED tests; Warrior runs the cycle
`warrior`	Read, Grep, Glob, Write, Edit, Bash	Runs the RED→GREEN cycle
`sage`	Read, Grep, Glob, Write, Edit	Writes synthesis docs
`wizard`	Read, Grep, Glob	Read-only; composes workflows (Agent tool is unavailable to subagents period)
`bonfire-powered`	Read, Grep, Glob, WebSearch, WebFetch	Safe read-only default

Warrior Bash discipline

Background-dispatched subagents auto-deny Bash calls outside cached permission rules — listing `Bash` in `tools:` is necessary but not sufficient. This PR ships `.claude/settings.local.json.example` with allow-list entries for the canonical Warrior-pattern Bash commands (`pytest`, `ruff`, `mypy`, `git add/commit/status/diff/log`). Documented as opt-in recommendation; never silently auto-installed.

Out of scope (intentional · follow-up tickets)

To keep this PR single-concern:

• Library-side dispatch-path wiring. The `bonfire.cadre.resolve_role_prompt(role)` adapter ships as a SKELETON. The actual dispatch-side enforcement (refusal on `cadre_contract` mismatch with a structured error envelope) is deferred. The contract is pinned here; the enforcement is the next ticket.
• Bracket roles (Architect, Artificer, Inquisitor, Loremaster). Deferred to a v1.1 follow-up pending the knowledge-backend distribution shape settling.
• Cleric, Bard, Steward. Future scope — no on-disk prompts exist for these roles yet.
• Marketplace submission to `claude-plugins-community`. This PR scaffolds the plugin; submission is a separate operational step.

Verification

```bash
.venv/bin/bonfire build-agents --check # OK: generated files match canonical sources
.venv/bin/pytest tests/unit/ -q # 3860 passed (54 new tests added by this PR)
.venv/bin/ruff check src/ tests/ # All checks passed!
.venv/bin/ruff format --check src/ tests/ # 8 files already formatted
claude plugin validate ./.claude-plugin # passes (one pre-existing warning about repo-root CLAUDE.md placement, unrelated to this PR)
```

The `claude plugin validate --strict` warning is about the repo-root `CLAUDE.md` being a contributor-facing doc (not a plugin skill); fixing it is a documentation-restructuring follow-up, not blocking.

Test plan

• CI green (`pytest`, `ruff check`, `ruff format --check`)
• Reviewer: confirm the plugin manifest installs cleanly via `claude --plugin-dir .` and `@agent-bonfire:scout-innovative` dispatches surface as `subagent_type: "bonfire:scout-innovative"` literally
• Reviewer: confirm `bonfire install-agents --scope user --dry-run` lists 7 files + manifest
• Reviewer: confirm `bonfire install-agents --scope user` then `bonfire uninstall-agents` is clean (no orphan files; manifest-driven removal)
• Reviewer: confirm the catch-all `bonfire-powered` appears flat-named in the picker after CLI install (NOT in the plugin install)

Status

DRAFT. Opening for review and to make the surface visible; not for merge until reviewer sign-off and the marketplace submission decision lands separately.