Usage Manual

Launches a standing design authority in the current session. The architect loads a design document once, announces itself on the campfire, and blocks waiting for escalation questions from workers. It consumes zero tokens when idle.

What it does

1. Finds or creates a swarm campfire (reads .campfire/root if present).
2. Loads design context — from a file path, an inline description, or a design campfire ID.
3. Announces: Architect online. Monitoring for escalations.
4. Blocks on cf read --follow --tag escalation — dormant until a question arrives.
5. When an escalation comes in: checks prior rulings, reads any referenced source, makes a ruling, posts --fulfills.
6. Returns to blocking. Repeat.

When to use

• Multi-session work — any time two or more agent sessions are running on the same repo.
• Parallel agents — when worker agents should not each load the full design context.
• Shared design authority — when you want rulings to be consistent across all workers in a session.

Configuration

Pass arguments to the skill when invoking it:

Ruling standards

• Decide, don't defer. Workers are blocked. A fast good-enough ruling beats a slow perfect one.
• Cite the design. Every ruling references the relevant section or prior decision.
• Be consistent. Before ruling, check prior decisions: cf read "$campfire" --tag decision --all.
• Escalate to human when needed. Novel trade-offs or major consequences get tagged gate-human.

Example session

Posts a design question to the campfire and blocks until the architect (or a human) answers. The worker's context is fully preserved while waiting — no polling, no tab switching, no context loss when the answer arrives.

What it does

1. Finds the swarm campfire (reads .campfire/root, or discovers via cf ls).
2. Posts the question with --tag escalation --future — marking it as a promise awaiting fulfillment.
3. Blocks on cf await <campfire> <msg-id> --timeout 15m.
4. When fulfilled: parses the decision, reports it, continues work using the ruling.
5. On timeout: posts a --tag blocker message and reports that no ruling was received.

When to use

• Design decisions — locking strategy, API shape, error handling approach.
• Scope ambiguity — unclear whether something is in or out of scope for the current task.
• Interface changes — before changing a shared interface that other sessions depend on.
• Novel trade-offs — anything the implementer shouldn't decide unilaterally.

Category tags

The skill applies --tag escalation automatically. You can signal the category in your question text — the architect reads the full message regardless of tags. Common categories:

Writing good escalations

Include: the specific question, relevant file paths and line numbers, the trade-offs you see, and any constraints you're already working within. The more context in the escalation, the faster and better the ruling.

Example: worker asks about locking strategy

Announces work, reads other sessions' status and schema changes, and routes human-needed decisions to a single monitoring point. Use this when two or more Claude Code sessions are running concurrently on the same repo.

What it does

The skill has four subcommands, each a targeted campfire operation:

start — join or create the project campfire

Reads .campfire/root. Creates a swarm campfire if none exists. Announces this session. Reads what other sessions have posted (status, schema changes). Reports active sessions and recent changes.

status — see what's happening

Reads all status messages, schema changes, and pending human decisions from the project campfire. Run this before starting a new file or touching a shared interface.

schema-change — notify others of interface changes

Posts a --tag schema-change message visible to all sessions. Other sessions should check this before continuing work that touches the same interface, and pull before proceeding.

needs-human — route a decision to the human

Posts a --tag gate-human message to the project campfire. The human monitors one command to see all decisions that need them, across all sessions.

Root campfire setup

Run once per project to set up named views for the human monitoring experience:

Example: two sessions coordinating

Two agent specs ship with the recipes: architect.md and implementer.md. Drop them into your project's .claude/agents/ directory. Claude Code reads them automatically when spawning subagents.

How to install

architect.md

Defines the standing architect role. The spec covers:

• Loading design context once at start (file or design campfire)
• Blocking on cf read --follow --tag escalation
• Checking prior rulings before making new ones
• Escalating novel trade-offs to the human via gate-human
• Constraints: read-only on code, no implementation work

The architect uses Sonnet tier by default (set in the frontmatter: model: sonnet). Upgrade to Opus for novel architectural decisions or complex multi-factor trade-offs.

implementer.md

Defines the implementer/worker role. The spec covers:

• Campfire integration — when and how to escalate, signal completion, and announce schema changes
• Process: baseline tests → feature branch → implement → verify → PR
• Flaky test handling — never retry and move on; diagnose the root cause
• Merge protocol — push a branch, create a PR, signal readiness on campfire; do not merge to main

The implementer also uses Sonnet tier. For purely mechanical tasks (template updates, config files, copy-paste refactors), you can dispatch on Haiku.

Customizing for your project

Both specs are starting points. Edit them to add:

• Project-specific conventions (language, framework, test runner)
• Repo layout and where shared interfaces live
• Escalation thresholds (what decisions require the architect vs. worker autonomy)
• PR review requirements and merge criteria

Model tier recommendations

Campfires nest. Tags propagate up through the hierarchy based on each campfire's --require configuration. This lets humans monitor one campfire and see everything that needs them from any depth below.

Root → swarm → engagement hierarchy

Tag propagation

When a campfire is created with --require <tag>, any message posted with that tag on a child campfire propagates to the parent automatically. The human never has to join the child campfire.

When to create sub-campfires

Use cf create for a sub-campfire when:

• A focused channel is needed for a specific area of work (e.g., a security audit, a sweep pass)
• Three or more findings cluster around one topic
• Two sessions need back-and-forth that would clutter the swarm campfire

Disband sub-campfires when done. The swarm campfire is permanent for the duration of the session; the root campfire persists across sessions.

Escalation cascade example

A worker's question reaches the human without manual forwarding:

cf not found on PATH

The Campfire CLI must be installed and on your PATH before any skill will work.

Skills not discovered by Claude Code

Skills must be in the correct directory with the correct filename.

New Claude Code sessions pick up skills automatically. Existing sessions pick them up on next invocation — no restart needed.

No campfire found — "Start one with cf swarm start"

The skills look for .campfire/root in the working directory. If it doesn't exist, they fall back to cf ls to discover campfires. If neither works:

Identity collision — two agents with the same identity

If two sessions share the same cf identity, messages from one look like they came from the other. This is a tool configuration issue, not a protocol issue.

Escalation timed out — no architect responded

The cf await timeout is 15 minutes by default. If no architect is running, escalations time out.

Debug commands