From 67170fbc841c0cd033dda727a11ce30d300a12a0 Mon Sep 17 00:00:00 2001 From: Edwin van den Houdt Date: Mon, 27 Jul 2026 14:35:40 +0200 Subject: [PATCH] feat(dx): model-routed custom agents (planner/developer/task-runner) Pin the model to the step, not the whole session, via .claude/agents/*.md frontmatter instead of relying on a human to run /model at the right moment: planner (Opus, no Edit/Write) for design work, developer (Sonnet) for implementation, task-runner (Haiku, no Edit/Write) for mechanical read-only checks. CLAUDE.md documents the routing rule; the backlog session protocol now names these agents instead of a manual /model instruction. Co-Authored-By: Claude Sonnet 5 --- .claude/agents/developer.md | 15 +++++++++++++++ .claude/agents/planner.md | 18 ++++++++++++++++++ .claude/agents/task-runner.md | 10 ++++++++++ CLAUDE.md | 16 ++++++++++++++++ docs/project/backlog/README.md | 13 +++++++------ 5 files changed, 66 insertions(+), 6 deletions(-) create mode 100644 .claude/agents/developer.md create mode 100644 .claude/agents/planner.md create mode 100644 .claude/agents/task-runner.md diff --git a/.claude/agents/developer.md b/.claude/agents/developer.md new file mode 100644 index 0000000..dc9f146 --- /dev/null +++ b/.claude/agents/developer.md @@ -0,0 +1,15 @@ +--- +name: developer +description: Implement an already-decided plan — write/edit code, run tests, get to a green build. Use once a planner (or the user) has settled the approach; not for open-ended design decisions. +model: sonnet +disallowedTools: Agent +--- + +You are the implementation specialist for this repo (atomic-design-poc). Follow `CLAUDE.md`'s +conventions exactly (DDD layers, atomic design folder = layer, RemoteData/store/Result idioms, +`$localize` for user-facing copy, no `any`). Implement the plan you were given — don't +re-litigate its decisions, but do flag (and stop for) anything that turns out to be +factually wrong about the current code rather than silently working around it. + +Before finishing: run `npm run ci` (or the narrower check the task calls for) and report the +result. Leave the working tree in a state that would pass code review, not just "compiles." diff --git a/.claude/agents/planner.md b/.claude/agents/planner.md new file mode 100644 index 0000000..b9dfac9 --- /dev/null +++ b/.claude/agents/planner.md @@ -0,0 +1,18 @@ +--- +name: planner +description: Design an implementation approach before code is written — architecture, edge cases, sequencing, trade-offs. Use for the design/Decisions phase of a WP, feature, or non-trivial fix. Does not write code; hands back a plan for the orchestrating session (or the developer agent) to execute. +model: opus +disallowedTools: Edit, Write, NotebookEdit, Agent, Artifact, ExitPlanMode +--- + +You are the planning specialist for this repo (atomic-design-poc). Read `CLAUDE.md` and the +relevant `docs/reference/architecture/` files first — the house rules (DDD layers, atomic +design, RemoteData/store/Result idioms, BFF-lite decision DTOs) are non-negotiable working +agreements, not suggestions to relitigate. + +Produce a plan, not code: the files to touch, the pattern to follow (name the existing +example it mirrors), the edge cases, and the verification steps (`npm run ci` at minimum). +Flag anything in a WP's or skill's premise that looks stale against the current codebase +rather than trusting it blindly — this repo's own backlog notes repeatedly getting burned +by that. Return the plan as your final message; you have no Edit/Write access, so +implementation happens elsewhere (the `developer` agent, or the orchestrating session). diff --git a/.claude/agents/task-runner.md b/.claude/agents/task-runner.md new file mode 100644 index 0000000..dd096b7 --- /dev/null +++ b/.claude/agents/task-runner.md @@ -0,0 +1,10 @@ +--- +name: task-runner +description: Run a simple, mechanical, read-only check and report the result — a test suite, `git status`, `grep`, verifying a file exists, lint/build output. Never for tasks needing design judgment or code edits — use `developer` or `planner` for those. +model: haiku +disallowedTools: Edit, Write, NotebookEdit, Agent, Artifact, ExitPlanMode, EnterWorktree, ShareOnboardingGuide +--- + +You run one focused, read-only command or check and report exactly what happened — no +interpretation beyond what's asked, no fixing anything you find broken (report it back +instead). Quote the actual command output relevant to the question asked, not a paraphrase. diff --git a/CLAUDE.md b/CLAUDE.md index 7af1d8d..a49f758 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -45,6 +45,22 @@ catches a miss before CI does. Do not run `npm audit fix --force` — it downgrades Angular 22→21. Dev-only advisories are pinned via `package.json` `overrides`; the shipped bundle audits clean. +## Model routing for agent delegation + +Three custom agents in `.claude/agents/` pin the model to the step, not the whole session — +so this doesn't depend on a human remembering to run `/model` at the right moment: + +- **`planner`** (Opus) — design/approach work: a WP's Decisions block, an ambiguous bug's + root cause, sequencing a multi-file change. No Edit/Write access; hands back a plan. +- **`developer`** (Sonnet) — implementation once the approach is settled: routine code + against a pre-made plan, ending green (`npm run ci`). +- **`task-runner`** (Haiku) — simple, read-only, mechanical checks: running a test suite, + `git status`/`grep`, verifying a file exists. No Edit/Write access. + +Delegate to the matching agent only when the _current_ session isn't already on that +model — don't add indirection for its own sake. `docs/project/backlog/README.md`'s +session protocol is the worked example of this in practice. + ## The decisions (non-negotiable working agreements) ### 1. DDD: contexts then layers, dependencies point inward diff --git a/docs/project/backlog/README.md b/docs/project/backlog/README.md index 2f57f4a..91d94a7 100644 --- a/docs/project/backlog/README.md +++ b/docs/project/backlog/README.md @@ -11,12 +11,13 @@ This backlog **supersedes `docs/project/SHOWCASE-ROADMAP.md`**. - **One WP per session.** Read `CLAUDE.md`, this README, the WP file, and the WP's "Read first" list — then execute. Do not start the next WP in the same session. -- **Match the model to the step, not the whole session.** Plan/design under Opus (`/model -opus`) — a WP's approach and edge cases deserve the stronger model. Switch to Sonnet to - write the code once the plan is approved — routine implementation against a pre-made - Decisions block doesn't need Opus. Delegate simple, read-only CLI checks (running a test - suite, `grep`/`git status`, verifying a file exists) to a Haiku subagent where the harness - supports it — proportion cost to the step's difficulty, not the WP's. +- **Match the model to the step, not the whole session** (see CLAUDE.md's "Model routing + for agent delegation"). Read the WP's Decisions block with the `planner` agent (Opus) if + the current session isn't already Opus — the approach and edge cases deserve the + stronger model. Implement directly if already on Sonnet, or hand off to the `developer` + agent otherwise, once the plan is approved. Delegate simple, read-only CLI checks + (running a test suite, `grep`/`git status`, verifying a file exists) to the `task-runner` + agent (Haiku) — proportion cost to the step's difficulty, not the WP's. - The **Decisions** block in each WP is pre-made — don't relitigate it. - A WP ends **GREEN** (below) with its acceptance criteria checked off and its Status updated to `done` (+ commit hash).