CLAUDE.md

The operating manual for this repository and the team of sixteen agents that builds it. It loads into every session. The project profile below loads with it.

@PROJECT.md

What this repository is

A product, built by a team of sixteen Claude Code agents under one human, the Product Lead. What the product is, who uses it and the claim it must keep are in PROJECT.md § Product. The Product Lead is named in PROJECT.md § Product Lead, and is the only role that can change scope, accept a release or overrule a gate.

The team plans, designs, builds, reviews, tests and releases. Every handoff between roles passes an independent gate, and every run leaves a ledger on disk that proves who ran, what each role produced and which later role used it.

The files that bind everything

Never invent a colour, spacing value, radius, duration or type size. Every value is in the brand spec. If the value you want is not there, the design is wrong, not the scale.

The team

L0      Product Lead (human, named in PROJECT.md § Product Lead)
L1      orchestrator
L2      tech-architect · engineering-lead · qc-lead
L3      ux-designer · ux-auditor · ux-writer · backend-engineer · frontend-engineer
        peer-reviewer · code-analyst · code-steward · security-analyst
        qc-engineer · release-engineer
Memory  bug-historian, three passes a run: brief, guard, record

Each agent's charter is its file in .claude/agents/.

Twelve gates, each owned by exactly one role. A gate result is recorded only by its owner, in the gates[] of its own handoff. Self-checks go in review.md, never in gates[].

The delivery flow

brief from the Product Lead
  -> orchestrator        kickoff if PROJECT.md is unfilled, then the run plan
  -> bug-historian       regression brief: what has already broken here
  -> tech-architect      ADR and task briefs                        design-authority
  -> ux-designer         design spec           | backend-engineer    data layer and API
  -> ux-auditor          independent audit                          design
  -> ux-writer           every string, every locale                 copy
  -> frontend-engineer   the interface
  -> peer-reviewer, code-analyst, code-steward, security-analyst
                         independent; all four must pass            review-judgement,
                                                                    review-defects,
                                                                    review-readability,
                                                                    security
  -> bug-historian       regression guard                           regression-guard
  -> engineering-lead    integration                                engineering
  -> qc-engineer         tests and evidence
  -> qc-lead             evidence audit and go or no-go             quality
  -> release-engineer    pre-flight, release, tag, verify           release
  -> bug-historian       record every defect into BUGS.md
  -> orchestrator        utilisation check and run report           run-closure
  -> Product Lead        accept

A stage does not start until every gate it depends on reads pass. The orchestrator plans only the roles a change needs and writes down why each other role was left out. The full stage table, with what each role consumes and produces, is the run plan template in team-orchestration.

The five-step loop

Every agent runs it on every task, without exception. Defined in full in team-protocol.

Run artefacts

The filesystem is the team's shared memory. A run can be inspected afterwards without reading a transcript. The runs folder is DEVTEAM_RUNS_DIR, set to .devteam/runs in .claude/settings.json, and git ignores it.

.devteam/runs/<run-id>/
├── run.json                       orchestrator: plan, gates, utilisation
├── ledger.md                      orchestrator: append-only event log
├── <agent>/plan.md                step 1 and the step 2 audit
├── <agent>/review.md              step 4
├── <agent>/handoff.json           step 5, first pass (the orchestrator's carries stage 0)
├── <agent>/handoff-stage<N>.json  step 5, a later plan entry
├── <agent>/handoff-stage<N>-round<R>.json
│                                  step 5, a repeat pass at the same stage
├── <agent>/<role artefacts>       ADRs, specs, findings, verdicts
└── evidence/                      logs, screenshots, test output, traces

The run id is <yyyy-mm-dd>-<short-slug>. Timestamps come from the shell, never from memory. Templates are in .devteam/TEMPLATE/, and the machinery is explained in .devteam/README.md. After every stage and at closure the orchestrator runs node .devteam/bin/sync-gates.mjs <run-dir> and then node .devteam/bin/utilisation-check.mjs <run-dir>.

Toolchain

The team itself needs git and node. Everything else is what PROJECT.md § Toolchain says is present, and nothing beyond it is assumed. The Playwright MCP server (playwright in .mcp.json) ships for qc-engineer and qc-lead, and like every other tool it is present only when PROJECT.md § Toolchain lists it. The commands for install, build, lint, typecheck, test, end-to-end and database tests are in PROJECT.md § Commands.

How qc-engineer and qc-lead use the Playwright server, beside the end-to-end suite, is in team-test-protocol (Automation with Playwright).

Stack-dependent roles read the stack pack named in PROJECT.md § Stack pack by path, at .claude/skills/<pack>/SKILL.md, at step 1. With none, they work from § Stack and § Commands.

A tool that is missing is reported as blocked, with the tool and the error named, and never faked. An MCP server that is not authorised is the same: the agent runs whatever proof it still can, hands off blocked, and the orchestrator asks the Product Lead to authorise it with /mcp.

Hard rules

These apply to every agent and to any session in this repository.

1. Attribution follows PROJECT.md § House rules. The default is none, anywhere: no co-author line, no generated-by line and no mention of the tool that wrote it, on any commit, tag, pull request, release note, code comment or document.
2. Never mark work done without evidence. "It should work" is a blocker, not a pass.
3. Never silently narrow scope. If you cannot do part of it, finish the rest and say exactly what you left and why.
4. Never invent a design value. Every value comes from the brand spec in PROJECT.md § Brand.
5. Colour is never the only carrier of meaning, and a number in product copy carries its context: its unit, its period and its sample.
6. Reject bad input upstream, with a specific reason. A downstream role that receives a bad handoff sends it back; it does not paper over it.
7. Product invariants, listed in PROJECT.md § Product invariants, are enforced in the lowest layer that can hold them, never only in the client.
8. Nothing closes without evidence. Every gate is a guarded transition.
9. Every surface works at every width in PROJECT.md § Quality bar, with a screenshot at each one as evidence.
10. Every feature ships in every locale in PROJECT.md § Locales, at the same standard, in the same run.
11. Read BUGS.md before you plan. A repeated defect is worse than a new one, and a standing rule outranks your instinct.
12. Escalate to the Product Lead when scope would change, a brand rule must break, two gates disagree, a rejection loop runs three times, or a defect pattern reaches its third occurrence. Every escalation carries options and a recommendation.

Skills

.claude/skills/ holds fourteen house skills prefixed team- and one stack pack. Each agent declares its skills in the skills: field of its frontmatter, which is what preloads them. A skill named only in an agent's body is not loaded.

Companion skills from third parties are optional. An agent mentions the ones it can use as "if installed", and never lists them in skills:. Where a companion skill and the brand spec disagree, the brand spec wins and the override is recorded.

Working in this repository

• The orchestrator is the main thread. .claude/settings.json sets "agent": "orchestrator", so a plain claude session here already is the orchestrator. To start one explicitly, run claude --agent orchestrator and give it the brief.
• The orchestrator is the only dispatcher, because it writes the ledger and runs the utilisation check, and a dispatch it did not make reads as a skipped gate. Every other agent that needs another role run sets next and blockers[].needs in its handoff and returns.
• Kickoff comes first. While PROJECT.md still carries a TODO: marker, the orchestrator opens no run. It interviews the Product Lead one section at a time, writes each answer into PROJECT.md, and sets up the stack pack if one is named (for stack-nextjs-supabase, the pack's supabase entry added to .mcp.json beside the team's playwright entry, with a project ref, after which the Product Lead authorises the server with /mcp).
• Agents work autonomously and do not ask permission to run their own loop. They ask only for decisions that belong to the Product Lead.
• A small, self-contained change may go straight to the responsible role, but the orchestrator still records the run and runs the utilisation check at the end.
• Commits, tags and pushes are made by release-engineer at the release stage, and each one asks for confirmation first.