CLAUDE.md

Guidance for Claude Code (claude.ai/code) when working in this repository.

What this repo is

A 14-agent synchronous assembly-line pipeline (plus a weekly tuner agent on cron — 15 total) that turns a plain-English task into a reviewed, tested, security-scanned, documented patch. Round 4 (2026-05-08) added the 14th synchronous agent — chief_architect, an autonomous escalation decider that fires on chief_architect_pending and emits a structured 7-verdict decision.json (round 5b1 added skip_with_warning as the 7th).

Read, copy, adapt — not deployed as-is. The shape is production. The recipes are anonymized.

Described in Claude Code terms because that's what the maintainers run, but the design is LLM-agnostic: the daemon, profiles, and state machine don't depend on Claude Code specifics. The agent prompt format is portable to any subprocess-spawnable runner that emits structured usage.

Spec lives here

pipeline-workflow.md (repo root) is the deep technical spec — Mermaid flow, state machine, retry semantics, three-gate human review, Slack matrix, T1–T19 production-validated tunings (built-in) + T20–T26 round-6 patterns + Tune Lifecycle Discipline section. Read it before changing any agent prompt or daemon constant.

Public surface

Everything in this repo is public. There is no private layer — the entire .claude/ directory ships as-is.

The cookbook = 9 skills + 15 agent definitions + 3 hooks + 4 profiles + daemon (~4.3k LOC, stdlib-only) + 46 tests. Per-user runtime state (.state/, STATUS.md, STATUS-history/, .claude/.env) is gitignored — but the showcase itself isn't split into public vs internal tiers.

When adding new artifacts, default to public. Don't introduce a .claude/-shadow private tree without explicit reason.

Pipeline as live product spec (dogfooding)

If you're using this cookbook to build dev-tools for AI pipelines — orchestration platforms, agent frameworks, prompt registries, observability surfaces — the pipeline you run is your product's live spec. Every operational pain you hit while shipping with the assembly line is a candidate roadmap feature for the product, because your users will hit a structurally similar pain.

When the daemon traps a stuck task at awaiting_user_action and you write a one-off helper to break it free, that helper is a UI affordance your product owes its users. When you find yourself grepping completed.jsonl for retry rates, that's a metrics dashboard. When you escalate a pipeline-stuck case to a senior reviewer, that's a routing-strategy plug-point.

Treat this as a discipline, not a vibe:

• Pipeline-First Test — before you write the spec for a new product feature, ask: "would the pipeline that builds this product use it?" If yes, ship it into the pipeline first, battle-test for a week, then port the matured shape to the product. If no, reconsider whether it's a real feature or a wishlist.
• Pain → spec, not opinion → spec — feature briefs that begin with "I think users would want…" are weaker than briefs that begin with "we hit this in our own pipeline last Tuesday and lost two hours." The latter has a fixed bug as evidence.
• N=1 sample-size honesty — your team is one team. Patterns that show up in your pipeline are signal but not proof; bias surfaces (you-the-solver / you-the-owner / you-the-payer / cargo-culted-from-elsewhere) need an external validation channel — usually the public surface (this cookbook + reader feedback) before a feature graduates from "pipeline pain" to "product roadmap commit."

The reverse direction also matters: when product roadmap items land, ask whether the pipeline already needs them. If it doesn't, that's a smell — the feature might be premature.

Repository layout

• team.sh — reference CLI (start / stop / resume-daemon / pause / resume / status / logs / tokens / backlog). tokens flags: --json / --daily / --wave (group by meta.json.wave) / --cache. backlog manages the .state/backlog.jsonl autopilot queue (add / list / peek / purge-consumed / clear).
• pipeline-workflow.md — deep technical spec (Mermaid + state machine + tunings + Slack matrix)
• .claude/agents/*.md — 15 agent definitions: 14 synchronous (planner, analyst, architect, chief_architect [round 4], developer, reviewer + 3 sub-reviewers, tester, qa, security-reviewer, documenter, retrospective) + 1 weekly tuner
• .claude/scripts/pipeline-daemon.py — the local state daemon (LSD), ~4.3k LOC, stdlib-only
• .claude/scripts/dedup_minhash.py, .claude/scripts/prompt_drift.py — round 5 stdlib-only helpers (duplicate detection + prompt drift telemetry)
• .claude/scripts/weekly-tuner-trigger.sh — cron entry for the tuner agent (round 5a's idle scheduler can also fire it; both paths coexist)
• .claude/skills/*/SKILL.md — 9 user-invocable slash commands: /start, /status, /ask, /verify, /logs, /tokens, /decisions, /lessons, /recovery
• .claude/profiles/*.yaml — per-module build/test/manifest config (4 starters: shared / backend / worker / frontend)
• .claude/learned-lessons/*.md — retrospective writes; tuner reads
• .claude/hooks/{notify-slack.py, after-code-change.sh, check-status-update.sh}
• .claude/.env.example — daemon env var template
• tests/test_pipeline_daemon.py + tests/test_round5_smoke.py + tests/test_c_series_fixes.py — 46 daemon unit tests (21 baseline + 6 round-5 smoke + 19 round-6 c-series)
• verify-cookbook.sh, Makefile — repo health smoke test (CI + maintainer-facing regression guard; not required for readers); make verify or bash verify-cookbook.sh
• docs/use-case-tracker-driven-pipeline.md — production tracker-driven shape (Jira / Linear / GitHub Issues + Slack)
• CHANGELOG.md — Keep-a-Changelog format
• README.md — primary public entry point
• LICENSE — MIT

Test & lint commands

# 46 daemon unit tests (21 baseline + 6 round-5 smoke + 19 round-6 c-series)
uv run --with pytest --with pytest-asyncio pytest tests/

# Lint Python
uv run --with ruff ruff check .claude/scripts/ tests/

# Validate shell scripts
bash -n team.sh
bash -n .claude/scripts/weekly-tuner-trigger.sh
bash -n .claude/hooks/*.sh

Safety & workflow rules

• Never commit .env or .state/. Both are gitignored. Verify nothing is staged before pushing.
• Run the test suite when modifying agent prompts. Changes to .claude/agents/*.md ripple through daemon behaviour. pytest tests/ catches observable differences.
• Idempotency is non-negotiable. Every new agent's first step must be: "is role_done.<me> set? If yes, exit." This is what makes crash-resume work.
• Don't introduce new artifacts outside .claude/ without reason. Agent definitions, skills, hooks, profiles all live in .claude/ for a flat resolver.
• Profile-driven, not hardcoded. All stack-specific commands (build, test, lint) live in .claude/profiles/*.yaml. Agent prompts read profiles; they never name a language or framework directly.

Conventions

• All agent prompts, README, blog posts, and inline comments are English.
• The cookbook is stack-agnostic. Adapt profile YAML; don't edit agents to match your stack.
• Per-user runtime state (.state/, STATUS.md) is gitignored. Don't add it back.

License

MIT. See LICENSE. Use it, fork it, ship it.