Claude Code Task-Driven Harness — Template

A reusable Claude Code harness for building software with a PRD → tasks → implementation workflow. Drop a filled-in PRD into ai-docs/PRD.md, run /create-tasks to generate a sequenced task list, then run /dev to implement tasks one branch at a time — each with an automatic design-system audit and quality-checklist verification.

This repo is a template: clone it, fill in a few placeholders, and start building.

---

How it works

This harness turns a single document — your PRD — into a stream of small, precisely-scoped tasks, each implemented and audited on its own branch.

1. The PRD becomes a task graph. /create-tasks runs the task-master-generator agent: it reads ai-docs/PRD.md, fans out parallel sub-agents to inspect your existing code (auth, database, routes, components, APIs), and writes ai-docs/todos/task-master.md — a numbered task list. Every task carries a priority, a complexity score, a phase, and explicit dependencies, so a task only unlocks once everything it needs is done. Features that already exist in the codebase generate no task.

2. Each task gets its own researched brief — with its own tools. /dev runs the task-sequencer agent for the next pending task. It researches the codebase for relevant examples, then consults ai-docs/tools.yaml — the catalog of every Skill, MCP server, command, agent, script, and CLI the project ships. It scores every tool against that specific task (keyword overlap plus hard rules — e.g. a UI task always pulls in the design-system agents) and injects the top matches into an ## Available Tools block right inside the task file. The implementer never has to rediscover which tool to reach for — the task already tells it.

3. Implementation is isolated and audited. Each task runs on its own task/<NN>-<slug> branch. When it touches frontend files, the design-system-checker audits it against DESIGN.md and the quality-checklist-verifier runs concrete code checks — a failed audit blocks the task from being marked done. Then /dev offers to open a PR.

A note on token cost. This precision is not free. Spawning research sub-agents, writing a detailed brief for every task, and running audit agents on each one means the harness uses noticeably more tokens than asking Claude to "just build the whole app". That is the deliberate trade-off: you spend tokens to get small, well-scoped, individually-verified tasks instead of one large, hard-to-review change. When a task is trivial, /dev --quick skips the specialist research and the design audit to save the cost.

---

What's inside

README.md                   # this file
CLAUDE.md                    # project instructions the agents always read
.gitignore                   # sensible defaults for a fresh repo

ai-docs/
├── PRD.md                   # ← YOU fill this in (skeleton with {{placeholders}})
├── lessons.md               # running log of lessons (grown by /learning)
├── tools.yaml               # catalog of tools the agents may use
├── todos/                   # task-master.md lands here after /create-tasks
│   └── .gitkeep
└── actual-todo/             # the task currently in flight lives here
    └── .gitkeep

.claude/
├── agents/                  # 6 subagents that power the workflow
├── commands/                # 5 slash commands (/create-tasks, /dev, …)
├── hooks/                   # block-npm-npx.sh (PreToolUse — optional, pnpm)
├── skills/                  # bundled Skills (stack-specific — trim to taste)
└── settings.json            # agent-teams env var + hook wiring

---

Quick start

1. Clone the repo.

   git clone <repo-url> my-project && cd my-project

2. Curate the skills & MCP servers. Decide what your project actually needs: delete the .claude/skills/ folders you won't use, add any Skills your stack requires, and register your MCP servers in .mcp.json. Then ask Claude to refresh the tools catalog — "Update ai-docs/tools.yaml to match the skills in .claude/skills/ and the MCP servers in .mcp.json." That catalog is the single source of truth task-sequencer reads when picking a tool for each task.

3. Write the PRD. Use the template in ai-docs/PRD.md as the structure and fill in every {{placeholder}} — /create-tasks refuses to run while any placeholder remains.

4. Drop the PRD in. Replace the contents of ai-docs/PRD.md with your finished PRD.

5. Run the workflow.

   /create-tasks   # PRD → ai-docs/todos/task-master.md
   /dev            # implement the next pending task
   

   Then keep running /dev:

   /dev --task 5                 # a specific task
   /dev "fix the login button"   # an off-roadmap ad-hoc task
   

   Each /dev run claims a task/<NN>-<slug> branch, prepares a detailed task file, implements it, runs the design + quality audits, and offers to open a PR.

Optional: run /design create to generate DESIGN.md before implementing — without it the design audit only warns, never blocks. For one-time stack configuration, see Make it yours below.

---

Commands

Command	What it does
/create-tasks	Reads ai-docs/PRD.md and generates ai-docs/todos/task-master.md.
/dev [description | --task <selector>] [--test] [--worktree] [--no-branch] [--list] [--dry-run] [--quick] [--ship]	Selects, prepares, implements, and audits a task on its own branch.
/design [create|lint|check|export|spec]	Manages DESIGN.md (Google Labs alpha spec).
/learning [description]	Records a lesson in ai-docs/lessons.md.
/manual-verify [request]	Runs a free-form verification you describe and reports what needs human action.

See CLAUDE.md for the full /dev flag reference and the multi-tab / worktree workflow.

Agents

All in .claude/agents/ — invoked automatically by the commands, never by hand:

• task-master-generator — turns the PRD into task-master.md.
• task-sequencer — claims a branch and prepares the next PRD task file.
• ad-hoc-task-creator — same, for free-form off-roadmap tasks.
• design-system-curator — authors/updates DESIGN.md.
• design-system-checker — audits frontend changes against DESIGN.md (auto in /dev).
• quality-checklist-verifier — verifies each task's quality checklist against the diff (auto in /dev).

---

Make it yours

The harness itself (agents, commands, the workflow) is stack-agnostic. A few spots carry the source project's assumptions — review these once when you adopt the template:

File	What to do
ai-docs/PRD.md	Fill in every {{placeholder}} (or replace the file with your own PRD).
CLAUDE.md → "Project-specific notes"	Describe your stack, backend, package manager, and conventions.
.claude/agents/quality-checklist-verifier.md → ## Project configuration	Fill the YAML block so the quality checks match your stack. If left blank, the agent auto-detects conservatively.
ai-docs/tools.yaml	Add rows for your project's scripts / MCP servers / CLIs; trim the bundled skill rows to match what you keep. Fastest way: ask Claude to regenerate it from .claude/skills/ and .mcp.json (see Quick start step 2).
.claude/skills/	The bundled Skills (Convex, Clerk, Stripe, Cloudflare, Hono, Astro, Resend, shadcn, …) came from the source project. Delete the folders you don't need and trim tools.yaml to match.
.claude/hooks/block-npm-npx.sh	This PreToolUse hook assumes pnpm — it rewrites npm/npx calls. If your project uses npm / yarn / bun, delete this file and the hooks block in .claude/settings.json.

---

Requirements

• git — required; the whole /dev workflow is branch-based.
• Node.js — only for /design *, which downloads @google/design.md on demand.
• Playwright MCP — only for /dev --test. Register it in .mcp.json or .claude/settings.json first.
• Agent Teams — .claude/settings.json sets CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 so the planning agents can spawn parallel research sub-agents.

How the branch claim works

/dev always isolates a task on its own task/<NN>-<slug> branch. The branch is the claim: any session that sees an existing task/<NN>-* branch (local or remote) skips that task. That is what makes multiple tabs / worktrees safe to run in parallel. Full details — including --worktree — are in CLAUDE.md under "Multi-tab workflow".

Notes

• The agents match the language of your PRD. Write the PRD in Portuguese and the whole project is generated in Portuguese; English is the default.
• actual-todo/ should be empty (just .gitkeep) between tasks — each /dev archives its own task file into todos/ on the final commit.
• This template standardises on pnpm. The bundled .claude/hooks/block-npm-npx.sh PreToolUse hook blocks any npm / npx command and tells Claude to use the pnpm equivalent instead — that's how the whole project stays on one package manager. If your project doesn't use pnpm, just delete that file and the hooks block in .claude/settings.json; nothing else depends on it.
• lessons.md is a single shared file; grow it with /learning after any avoidable mistake so the project keeps a living guide of what not to repeat.