Claude Code project template - agent workspace

A starting kit for a new project that will be built and maintained by an orchestrated fleet of Claude Code agents.

What you get

CLAUDE.md                          project instructions template (checked into the repo)
.claude/
  launch.json                      dev-server definitions for the Claude Code preview
  agents/
    project-architect.md           read-only design-phase planner
    project-reviewer.md            read-only first-pass diff reviewer
    package-implementer.md         delegated implementer - copy once per package
    test-engineer.md               dedicated test writer with the protected-resource rail
    docs-curator.md                keeps docs matching reality after merges
    stack-researcher.md            web-enabled current-truth checker for a bleeding-edge stack
    tracker-clerk.md               issue-tracker bookkeeping without burning orchestrator context
    contract-auditor.md            checklist audit of a cross-package wire contract
    ux-expert.md                   hands-on UI review - launches the app, reports, never fixes
  commands/
    run-phase.md                   /run-phase - the milestone orchestration runbook
  skills/
    _template/SKILL.md             anatomy of a pinned stack skill - copy per stack pillar

The design, in brief

The setup encodes a trust topology, and that topology is the point:

• The orchestrator (your main session) owns every irreversible action. Implementers commit locally on a branch and stop; the orchestrator reviews, pushes, opens the PR, gates on CI, merges, and closes the tracker issue.
• Reviewing agents are read-only by construction. The architect, reviewer, and contract auditor restrict their tools in frontmatter so they cannot edit even by accident. Findings flow back as text; the orchestrator decides.
• One issue, one agent, one branch. Implementers receive a self-contained brief, work in a git worktree under .worktrees/, and hand back raw data (branch, commits, files, verification evidence, open questions) - not a narrative for a human.
• Tracker-first. An implementer's first action is marking its issue In Progress, because the human watches the board while agents work.
• The protected-resource rail. Every agent that can touch a database, account, or external service carries the same non-negotiable rule: never the production resource; disposable, self-created, self-destroyed test resources only. Repeat it in every brief - it is cheap insurance against the worst failure class.
• Model and effort pinning per role. Implementers pin the strongest model at high effort; mechanical roles (clerk, curator, auditor) pin a cheaper model. Costs stay proportional to the difficulty of the role, not the volume of its output.
• Pinned stack skills. One SKILL.md per stack pillar whose current major version postdates most training data, plus one per bespoke integration seam, plus one for the testing topology. Each states what changed and what the project's conventions are, so no session re-derives (or mis-remembers) them.

Instantiating a project

1. Copy this directory's contents into the new repo root (CLAUDE.md, .claude/).

2. Find and replace the placeholders - they are all greppable:

   Placeholder	Meaning	Angus example
   {{PROJECT}}	project name	Angus
   {{OWNER}}	the human the agents answer to	Alex
   {{ORG_REPO}}	GitHub slug	rzem-ai/rzem-ai-angus
   {{TRACKER}}	issue tracker product	Linear
   {{TRACKER_TEAM}}	team / workspace in the tracker	Rzemai
   {{ISSUE_KEY}}	issue id prefix	RZE
   {{PACKAGE}}	a package an implementer owns	shared
   {{CANON_DOCS}}	the design docs agents cite	docs/architecture.md, docs/scope-and-roadmap.md
   {{PROD_RESOURCE}}	the guarded production resource	the angus Postgres database
   {{TEST_RESOURCE_PATTERN}}	naming rule for disposable test resources	angus_test_* databases

3. Duplicate package-implementer.md once per package (shared-implementer.md, client-implementer.md, ...) and fill each copy's Context and Invariants sections. Keep the Process and Return format sections identical across copies - divergence there is drift, not customisation.

4. Duplicate skills/_template/ per stack pillar and write the content. The description frontmatter is load-bearing: it is the trigger, so pack it with the phrases a session would actually contain when the skill should fire, and say why training-data knowledge misleads.

5. Fill in the HTML comments (<!-- ... -->) scattered through the agent files - each marks a spot that needs project-specific content - then delete them.

6. Edit .claude/launch.json to the project's real dev servers and ports.

7. Write CLAUDE.md last, once the invariants are real. Keep it short: what the project is, the load-bearing invariants, house style. It is read by every session; every sentence costs context forever.

8. Delete this README from the project copy (it documents the template, not the project).

House style baked into the template

Australian English, standard hyphens (never em dashes), no emojis, TypeScript throughout, comments only for constraints the code cannot show. Adjust in CLAUDE.md and the agent files if a new project wants different rules - but keep them consistent everywhere, because the reviewer enforces what the implementers were told.