Claude Code Multi-Agent Runtime

A reusable, Claude Code-native software delivery harness. Drop it into any project to get a multi-agent workflow that plans, implements, designs, QAs, and documents — with self-maintaining memory and a vendored design-quality skill (Impeccable).

You author one file (.claude/memory/project.md). Claude maintains the rest.

---

What this is

A .claude/ directory plus a CLAUDE.md at the project root that together define:

• A single Orchestrator (the main session) coordinating specialized worker subagents.
• A set of strict lane boundaries so the backend worker never touches frontend, frontend never invents API shapes, QA only recommends (never completes), and only the Orchestrator transitions tasks or writes to memory.
• A self-updating memory system that captures product context, architecture, decisions, conventions, and progress as the project evolves.
• Living contracts for API, database, frontend, UI direction, and integrations — kept in sync with code by the workers that own them.
• A kanban-style task workflow with phases queued / active / blocked / review / completed.
• A vendored design-quality skill (Impeccable) for premium UI polish, anti-AI-slop critique, and accessibility-aware audits.

It is stack-agnostic. The runtime governs how Claude works, not what it builds.

---

File map

CLAUDE.md             ← root orchestrator persona (always loaded)
PRODUCT.md            ← Impeccable bridge → .claude/memory/project.md
DESIGN.md             ← Impeccable bridge → .claude/contracts/ui-direction.md
README.md             ← this file

.claude/
├── settings.json     ← permission allowlist
├── agents/           ← 8 worker subagents
│   ├── orchestrator.md
│   ├── planner.md
│   ├── backend.md
│   ├── frontend.md
│   ├── ui-ux.md
│   ├── qa.md
│   ├── docs.md
│   └── devops.md
├── commands/         ← 6 slash commands
│   ├── initialize-project.md
│   ├── plan-feature.md
│   ├── implement-feature.md
│   ├── audit-ui.md
│   ├── run-qa.md
│   └── update-memory.md
├── memory/           ← AI-maintained except project.md (human-initiated)
│   ├── project.md
│   ├── progress.md
│   ├── architecture.md
│   ├── decisions.md
│   └── conventions.md
├── contracts/        ← living specifications
│   ├── api.md
│   ├── database.md
│   ├── frontend.md
│   ├── ui-direction.md
│   └── integrations.md
├── tasks/            ← kanban folders
│   ├── queued/  active/  blocked/  review/  completed/
├── reports/          ← agent outputs
│   ├── qa/  ui/  bugs/  performance/  implementation/
├── runtime/          ← workflow + rules + state
│   ├── workflow.md
│   ├── execution-rules.md
│   └── execution-state.json
└── skills/
    └── impeccable/   ← vendored from pbakaus/impeccable (Apache 2.0)

---

Install into a new project

# from inside the new project root
cp -r /path/to/this/runtime/CLAUDE.md .
cp -r /path/to/this/runtime/PRODUCT.md .
cp -r /path/to/this/runtime/DESIGN.md .
cp -r /path/to/this/runtime/.claude .

That's it. Open Claude Code in the project directory and you're ready.

If your project already has a CLAUDE.md, merge the runtime's content into it rather than overwriting — runtime instructions plus project-specific notes can coexist.

---

Quick start

1. /initialize-project        ← Q&A walkthrough to populate .claude/memory/project.md
2. /plan-feature <name>       ← decompose a feature into atomic tasks
3. /implement-feature <name>  ← run the full pipeline end-to-end

After step 3, inspect .claude/memory/progress.md and .claude/reports/ to see what was built and what was validated.

---

Day-to-day commands

Command	What it does
/initialize-project	Interactive Q&A → writes project.md, scaffolds memory and contract files, resets execution state.
/plan-feature <name>	Reads memory + contracts, applies the project.md split policy, delegates to the planner subagent → atomic task files land in tasks/queued/.
/implement-feature <name>	Full pipeline: plan → UI direction → backend/frontend → QA → Impeccable audit → docs → memory update.
/audit-ui <area>	Standalone Impeccable audit on a UI area → report in reports/ui/.
/run-qa [task or "all"]	QA worker validates tasks in review/ (or current diff) → report in reports/qa/.
/update-memory	Sweep source + tasks + reports → reconcile architecture.md, decisions.md, conventions.md, progress.md. Surfaces drift between contracts and code.

---

The Orchestrator / worker model

The main session is the Orchestrator. It coordinates, delegates, and is the sole authority over:

• task state transitions between queued / active / blocked / review / completed,
• writes to .claude/memory/*,
• final completion of any task (based on QA and UI/UX recommendations).

Workers are subagents invoked via the Task tool. Each operates in a strict lane:

Worker	Lane
planner	writes task files to tasks/queued/ only
backend	server-side source + api.md, database.md, integrations.md
frontend	client-side source only (no contracts, no API invention)
ui-ux	contracts/ui-direction.md, DESIGN.md, reports/ui/
qa	reports/qa/, reports/bugs/ (recommends only — cannot move tasks)
docs	README, changelog, public API docs
devops	CI, env, deploy, infra

Workers that need to cross a lane must surface to the Orchestrator. Crossing silently is not allowed.

---

Memory & contracts

Memory (.claude/memory/)

File	Who maintains	Notes
project.md	Human-initiated, AI-maintained	You write or bootstrap it (via /initialize-project). Orchestrator updates it under a split policy: small/aligned additions auto-append; major direction shifts, large scope changes, or conflicts pause and ask you first.
progress.md	Orchestrator	Append-only feature log.
architecture.md	Orchestrator	Living high-level view; updated when modules/services/data flows change.
decisions.md	Orchestrator	ADR-style log of non-obvious choices.
conventions.md	Orchestrator	Coding/design rules that emerged from actual work.

Contracts (.claude/contracts/)

Specifications that workers update in lock-step with code. Drift between contract and code is a QA failure.

File	Owner	Updated when
api.md	backend	endpoints added/changed
database.md	backend	schema/migration changes
frontend.md	frontend	routes/components/state slices added
ui-direction.md	ui-ux	tokens, patterns, voice, motion rules
integrations.md	backend / devops	third-party services, webhooks

---

Impeccable integration

The Impeccable design skill is vendored at .claude/skills/impeccable/ (Apache 2.0, attribution preserved). It auto-activates on frontend/design work and provides:

• 27 deterministic anti-pattern rules (npx impeccable detect).
• 12-rule LLM critique pass across typography, color, spacing, motion, interaction, responsive, UX writing.
• 23 commands (/impeccable audit, /impeccable polish, /impeccable critique, etc.).

The runtime hooks Impeccable in three places:

1. The ui-ux worker uses it during /audit-ui and post-implementation polish.
2. The frontend worker runs npx impeccable detect against changed files before declaring work done.
3. The QA worker runs the deterministic CLI pass as part of validation.

Bridge files: Impeccable requires PRODUCT.md and DESIGN.md at the project root for its context gate. Both ship as thin bridges pointing to the canonical sources in .claude/. The Orchestrator keeps PRODUCT.md synced with .claude/memory/project.md; the UI/UX worker keeps DESIGN.md synced with .claude/contracts/ui-direction.md.

To update Impeccable later:

rm -rf .claude/skills/impeccable
git clone --depth 1 --filter=blob:none --sparse https://github.com/pbakaus/impeccable.git /tmp/impeccable
cd /tmp/impeccable && git sparse-checkout set ".claude/skills/impeccable"
cp -r /tmp/impeccable/.claude/skills/impeccable <project>/.claude/skills/
rm -rf /tmp/impeccable

---

Customization

• .claude/settings.json — pre-approves safe operations. Add project-specific allowlists (test commands, build scripts, linters) so they don't prompt for permission every run.
• CLAUDE.md — add project-specific notes below the runtime instructions. Stack conventions, deployment quirks, client preferences.
• CLAUDE.local.md — (gitignored) for personal overrides that should not be shared with the team.
• Agents and commands — edit the markdown files directly. Subagent frontmatter follows Claude Code's standard format.

---

Strict rules (summary)

The full rule set lives in .claude/runtime/execution-rules.md. Top-level:

• Always read CLAUDE.md, memory/project.md, and memory/progress.md before starting work.
• Workers stay in their lane. Cross-lane needs surface to the Orchestrator.
• Frontend must not invent API contracts — it waits for contracts/api.md.
• UI/UX produces design direction before major frontend work.
• QA runs after implementation and produces a recommendation only. Only the Orchestrator transitions tasks.
• A task is not complete until QA passes and the Orchestrator moves it.
• Memory writes are Orchestrator-only.
• The project.md split policy is non-negotiable: auto-append small additions, pause and ask for major shifts.

---

Credits

• The vendored design skill at .claude/skills/impeccable/ is Impeccable by Paul Bakaus, released under Apache 2.0. See its SKILL.md and any included NOTICE.md for full attribution.
• Runtime structure: Claude Code subagents, slash commands, and skills, per Anthropic's Claude Code conventions.