Claude Code Multi-Agent Localhost Loop Setup

This repository is configured for the Claude Code multi-agent critic workflow — a way of using Claude Code as a Lead Agent that coordinates specialist critics to develop and end-to-end test a local web app on localhost, instead of letting it work as a single coding agent that just edits files.

The workflow starts with critique, not coding — and ends with proof, not confidence.

Adopting this in your own project? See the Adoption Guide — what to copy, how to wire the verification commands, and how to adapt the memory wiki and story map (covers both a fresh start and dropping the workflow into an existing codebase).

How it works at a glance

1. The task cycle — from intent to proof, looping until there are zero blockers.

2. The multi-agent workflows — each node is a subagent with its own context.

3. The components — four layers of files, and the evidence-based story statuses.

4. /loop and adoption — trust levels, the denylist, one loop iteration, and the six adoption steps.

What's in this setup

CLAUDE.md                         Project rules + multi-agent workflow + doc-scanner workflow
.claude/
  loop.md                         Recurring watchdog loop, hardened: trust levels + denylist + stop rules
  loop-checklist.md               Readiness rubric to raise a loop's trust level (L0→L3)
  skills-index.md                 Grouped "when to use which command" catalog (kept in sync by /dream)
  memory/                         Knowledge wiki (Karpathy LLM-wiki pattern), maintained by /dream
    index.md                      Small catalog imported by CLAUDE.md (always loaded)
    log.md                        Append-only history of wiki operations
    loop-plan.md                  The loop's durable plan/DAG (every L2/L3 action traces to a ready node)
    loop-run-log.md               Append-only /loop run history (the loop's durable state)
    quarantine.md                 Candidate facts the /dream admission gate deferred (not part of the wiki)
    trace/records.jsonl           TRACE-lite record store: one typed verdict per adjudicated claim (append-only)
    topics/                       One page per subject, read on demand (trace.md = the TRACE-lite policy)
  trace/
    schema-v1.json                TRACE-lite record schema (versioned)
    bench/                        TRACE-Bench-lite: seeded-defect fixtures + scored runs
  settings.local.json             Allowed commands for the workflow
  workflows/                      Deterministic multi-agent orchestration scripts (Workflow tool)
    critic-panel.js               Fan-out critics → adversarial verify → severity matrix
    scan-docs.js                  Per-story parallel evidence-gathering → status verifier
    gap-analysis.js               Per-dimension gap analysis → synthesized next-order
    e2e-design.js                 Per-category E2E test-case enumeration → dedup
    loop-iteration.js             Maker/checker: worktree implementer → separate verifier (typed verdict)
    improve-skills.js             Meta-critic over the project's own prompts → proposed edits
    trace-bench.js                Measure our own checkers on seeded-defect fixtures
  commands/                       Each command has a description used for routing
    write-goal.md                 Write a production-grade /goal (or /loop) prompt for a task
    multi-agent-dev.md            Full critic-led development pass
    critic-round.md               Review-only multi-agent critic round
    multi-agent-e2e.md            Critic-driven E2E test design + run
    qa-pass.md                    Pre-ship QA checklist
    fix-localhost.md              Drive localhost back to a working state
    memory-audit.md               Audit project memory vs CLAUDE.md
    dream.md                      Self-learning pass: ingest learnings, lint, propose skills
    scan-project-docs.md          Build the user-story / status / coverage map from docs
    sync-story-status.md          Re-sync story statuses with code and tests
    story-gap-analysis.md         Gap analysis: docs vs code vs E2E
    improve-skills.md             Self-improvement pass over the prompts/workflows (confirmation-gated)
    bench-checkers.md             TRACE-Bench-lite: measure the checkers, report falsification flags
scripts/trace/                    `pnpm trace …` — record writer, linter, re-audit, metrics, bench scoring
docs/
  adoption-guide.md               How to adopt this template in a real project
  loop-integration-guide.md       How to add hardened recurring /loop automations to a project
  prd.md                          Product requirements (source of record for stories)
  product-docs-index.md           Source documents scanned
  user-stories.md                 Story index (one row per story → its file)
  stories/                        One file per user story (US-<id>-<slug>.md) + _TEMPLATE.md
  implementation-status.md        Evidence dashboard: story → impl/test/verification status
  e2e-coverage-map.md             Story → Playwright/browser coverage
  story-verification-log.md       Evidence log of checks actually run
  gaps-and-risks.md               Missing/untested/contradictory areas
.github/
  workflows/
    verify.yml                    CI: runs typecheck/lint/test/build (matrix) + e2e on push & PR

Which command when? Each command above carries a one-line description; the full grouped "when to use which" catalog (with a pick-by-intent guide) is .claude/skills-index.md.

Quickstart: add to an existing project

The full walkthrough (with snippets, the existing-wiki bridge, and a checklist) is in docs/adoption-guide.md — the short version:

1. Copy the portable workflow — CLAUDE.md (merge into yours, don't overwrite), .claude/commands/, .claude/loop.md, .claude/memory/, .claude/skills-index.md, .claude/settings.local.json, docs/*.md, and .github/workflows/verify.yml. Do not copy the starter app (src/, e2e/, package.json, pnpm-lock.yaml, and the build configs) — that's only a demo.
2. Wire the verification commands — point CLAUDE.md's Main commands at your real scripts and trim verify to the steps you actually have (it's a hard && chain — a missing script breaks the gate). Adjust the package manager, localhost port, and (in monorepos) the src//e2e/ paths.
3. Clear the seeded memory facts FIRST — .claude/memory/topics/* ship this template's Next/React stack facts and load as authoritative memory; delete the ones that don't fit, then run /dream to seed your own.
4. Start the story map empty — delete the example story files in docs/stories/ (keep _TEMPLATE.md) and clear the example rows in docs/*.md (keep the formats), then run /scan-project-docs against your real docs/PRD.
5. Mind the integration gotchas — already have a docs/ wiki? Namespace the story map and bridge (don't run two memories). Already have slash commands? Check name collisions, give each a description, and set disable-model-invocation: true on heavy ones. Put shared permissions in a committed .claude/settings.json (create it — the template ships only settings.local.json); the git add/git commit auto-allow is opt-in. In CI, install the browser normally (no PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD).
6. First session — pnpm verify (green once) → /scan-project-docs → /write-goal <your first task> (review, then run it) → /qa-pass → /dream.

Critic roster

Pre-implementation and post-implementation critic rounds use:

1. First-Time User Critic
2. UX Flow Critic
3. Designer Critic
4. Artistic Direction Critic
5. Frontend Architecture Critic
6. QA / E2E Critic
7. Accessibility Critic
8. Performance Critic
9. Security Critic
10. Regression Critic

The documentation-scanner workflow adds: Product Requirements, User Story, Acceptance Criteria, Code Evidence, Unit Test Evidence, E2E Test Evidence, and Documentation Consistency critics.

These run as real multi-agent orchestration, not one agent simulating critics. The critic-bearing commands invoke deterministic Workflow-tool scripts under .claude/workflows/ — parallel subagents (own context each) with adversarial / maker-checker verification:

Workflow	Backs	What it does
critic-panel.js	/critic-round, /multi-agent-dev, /qa-pass, /loop	fan-out critics → adversarial verify → severity matrix
scan-docs.js	/scan-project-docs	per-story parallel evidence → separate status verifier
gap-analysis.js	/story-gap-analysis	per-dimension gap analysis → synthesized next-order
e2e-design.js	/multi-agent-e2e	per-category E2E case enumeration → dedup
loop-iteration.js	/loop (L2/L3)	worktree implementer → separate verifier per item

It's heavier by design — independent review beats a single context role-playing the panel. Commands that don't fan out (/fix-localhost, /write-goal, /dream, /memory-audit) stay single-agent on purpose.

Everyday workflow

Let Claude write the /goal for you — it knows the project's gates better than a hand-written prompt. CLAUDE.md also tells Claude to offer this whenever you describe a non-trivial task.

# Start a task — pick ONE entry point:
/write-goal add password reset        # Claude writes a production-grade /goal → review, then run IT
/multi-agent-dev implement [FEATURE]  # — or — drive the critic loop directly, no /goal
/goal [FEATURE] is complete using the multi-agent critic workflow, verified on
      localhost, covered by E2E tests, with no post-implementation critic blockers.
      Stop after 25 turns if not achieved.   # — or — hand-write the /goal yourself

# Then, before committing:
/qa-pass final pre-commit check

These three are alternatives, not a sequence — if you used /write-goal, run the /goal it produced (don't skip to /multi-agent-dev).

Every /goal should carry six things: a one-line task statement, 3–5 measurable success criteria, constraints, checkpoint rules, a self-verify instruction, and a max-budget guard. /write-goal produces all six, grounded in this repo.

Long-running watchdog:

/loop 10m

Product delivery audit:

/scan-project-docs full project
/sync-story-status current branch
/story-gap-analysis MVP readiness

Self-learning (/dream) — an LLM wiki

The project "self-learns" by consolidating durable knowledge into a small knowledge wiki, so future sessions start smarter without bloating context. This follows Andrej Karpathy's LLM wiki pattern and uses Claude Code's real memory system (@import + /memory):

.claude/memory/
  index.md        small catalog: each topic = one-line summary + link (always loaded)
  log.md          append-only history of ingest / lint operations
  topics/         one page per subject — read ON DEMAND, not all at once
    tooling.md  build-and-verify.md  testing.md  client-react.md
    code-organization.md  remote-env.md  workflow.md

• Why a wiki, not one file: CLAUDE.md imports only index.md, so per-session context stays flat as knowledge grows. Claude opens just the topic page(s) relevant to the task (the query operation) instead of loading everything.
• /dream (a custom command — see .claude/commands/dream.md) is the wiki maintainer: ingest files new durable learnings into the right topic page and appends to log.md; lint health-checks for contradictions, stale claims, and orphan pages. Run it at the end of a non-trivial task.
• The built-in /memory command lets you view and edit loaded memory files.

/dream            # ingest what was learned this task into the wiki
/dream lint       # health-check the wiki (contradictions, stale, orphans)
/dream query how do we test localStorage?   # answer from the wiki, with citations
/memory-audit     # periodically prune stale or duplicated memory

Note: /dream is not an official Claude Code command. It is implemented here as a custom slash command on top of the memory system. Hard rules: only durable, verifiable facts; never secrets; never temporary/branch-specific bugs; prefer appending; confirm before removing entries.

Typed verdicts & records (TRACE-lite)

Adapted from TRACE: An Operational Reasoning Schema for Auditable Agentic Commitments (Chang & Chang, arXiv:2607.12480): the unit of value is the record, not any one checker. Every claim a checker adjudicates — a critic finding, a loop fix, a story status, a fact headed for the wiki — gets a typed verdict and an append-only record:

• Typed verdicts instead of true/false: accept · qualify (holds, but weaker) · revise (carries a repair) · defer (names what is missing) · reject. A checker that returns nothing defers — it is neither a confirmation nor a refutation.
• Evidence gate: each claim is typed (factual, measured, causal, predictive, normative, practical) and an accept is capped deterministically when its evidence is weaker than its type demands (a perf claim needs a measurement, a "users will be confused" claim needs a browser observation). No claim stronger than its evidence.
• No durable state change without a record: a loop node becomes done, a fact enters the wiki, a story changes status — only with a licensing record and a consumer action (CLEAR, COMMIT, …), enforced fail-closed by pnpm trace and checked in CI.
• Consensus is not evidence: critics share a model, so agreement doesn't upgrade a finding — only different evidence corroborates.
• Measured, not assumed: /bench-checkers runs the production checkers on seeded defects and reports pre-registered falsification flags (e.g. "a single reviewer is as good as the panel").

pnpm trace query --latest          # what has been adjudicated, and what is still deferred
pnpm trace show TR-…               # one record + its consumer actions + revision chain
pnpm trace lint                    # replay the store against the contract (also in pnpm test)
pnpm trace reaudit                 # wiki facts whose evidence changed since they were committed
pnpm trace metrics                 # consumer coverage, defer quality, repeated-error rate

Policy, verdict semantics and what was deliberately not adopted: .claude/memory/topics/trace.md.

Severity model

Severity	Meaning	Action
Blocker	The feature should not be considered complete	Must fix
Important	Meaningfully affects quality, UX, maintainability, or reliability	Fix if in scope
Nice-to-have	Improvement, polish, or future enhancement	Record only unless approved

Starter app

A minimal Next.js 16 (App Router) + TypeScript app is included so every command in CLAUDE.md runs end-to-end out of the box:

src/
  app/
    layout.tsx            Root layout + global styles
    page.tsx              Home page (hero + greeting form)
    globals.css           Dark, cohesive theme
    api/health/route.ts   Liveness endpoint (used by smoke test)
  components/
    GreetingForm.tsx      Client form: greeting, persistence, Clear control
  lib/
    greeting.ts           Pure validation/greeting rule (unit-tested)
    greeting.test.ts      Vitest unit tests
    rememberedName.ts     Safe localStorage wrapper + change subscription
    rememberedName.test.ts Vitest unit tests (incl. storage-unavailable path)
e2e/
  smoke.spec.ts           Home renders + /api/health responds
  critical-flows.spec.ts  Greeting happy path, validation, boundaries, recovery
  remember-me.spec.ts     Reload persistence, clear, no-persist-on-failure, no-network

Two features are tracked through the audit docs in docs/ as worked examples: US-001 (greet a visitor by name) and US-002 (remember me on return).

Setup

pnpm install        # Chromium is pre-provisioned in this environment
pnpm verify         # typecheck + lint + unit + build + E2E
pnpm dev            # http://localhost:3000

Toolchain: Next 16, React 19, TypeScript 6, ESLint 9 (flat config via eslint-config-next), Vitest 4, Playwright 1.56.

package.json scripts

{
  "scripts": {
    "dev": "next dev",
    "build": "next build && node scripts/check-bundle-size.mjs",
    "start": "next start",
    "typecheck": "tsc --noEmit",
    "lint": "eslint .",
    "test": "vitest run",
    "test:e2e": "playwright test",
    "check:bundle": "node scripts/check-bundle-size.mjs",
    "verify": "pnpm typecheck && pnpm lint && pnpm test && pnpm build && pnpm test:e2e"
  }
}

Next 16 removed next lint, so pnpm lint runs ESLint directly against the flat config in eslint.config.mjs.

Swap this starter for your real stack as the project grows — the rule that matters is: Claude must know the exact verification commands and must not guess. Keep CLAUDE.md and package.json in sync.