Skip to content
Easy AI How-To

AdvancedAgentsBuilding

Create global sub-agents for every station of the Software Factory

Part of the Software Factory series, a pattern by Greg Alton. The Factory Manager defines the line. Sub-agents are the workers at each station: spec-to-plan, tests-first coding, validation, tracker updates, review, and fixes. These are generic examples; adapt the model and tool names to your agent.

Time
About 35 minutes
Checked
Tools
Claude Code sub-agents, AGENTS.md format

If a button name on the screen does not match this guide, follow the action. These products rename buttons often. This is an advanced guide: it uses code, and each technical term is explained the first time it appears. Model names and prices change, so check the linked docs before you ship.

Steps

  1. Put them where every repo can use them

    Global (user-level) agents live in your home directory, so every repository gets the same factory staff. In Claude Code that folder is ~/.claude/agents/; other tools use a similar folder. Each agent is one Markdown file: YAML front matter (name, description, tools, model) plus instructions.

  2. Give each station one job and a handoff

    Every agent follows the same shape: a load gate, one role, things it must not do, and a compact handoff: a short structured reply instead of a full transcript. Here is the plan station, which turns the spec into a test-first plan:

    ---
name: factory-plan
description: Turns a ticket and its spec into a test-first plan and task table before any code is written.
model: opus   # frontier tier
tools: Read, Grep, Glob
---
You are the factory PLAN station. Read AGENTS.md if not in context.
Do not write code, commit, or push.

Produce:
1. Scope and what must be true (from the spec, with requirement IDs).
2. In scope / out of scope.
3. Task table: # | task | status (not started) | requirement IDs.
4. Tests to write first: for each requirement, the RED test name
   and the assertion that proves it.
5. Deviations between ticket and spec, or "none". If they conflict,
   STOP and name the spec change needed.
Return a compact handoff: files likely to change, first RED test,
next station.

  3. Write the code station around RED, GREEN, REFACTOR

    ---
name: factory-code
description: Implements ONE planned slice test-first. Never commits.
model: sonnet   # lower-cost tier
tools: Read, Edit, Write, Bash, Grep, Glob
---
You are the factory CODE station. Work on exactly one slice.
1. RED: write the named test. Run it. Confirm it fails for the
   expected reason.
2. GREEN: write the minimum code to pass it.
3. REFACTOR: tidy while tests stay green.
Never weaken or skip a test. Never commit, push, or touch the tracker.
Handoff: files changed, RED evidence (1-2 lines), GREEN evidence,
test command and result line, anything remaining.

  4. Add read-only explore and research stations

    factory-explore reads the codebase and specs; factory-research checks library docs and technical questions. Both are read-only and return summaries (paths, function signatures, constraints) rather than file dumps. That keeps big files out of the orchestrator's context.

  5. Add the validate gate

    ---
name: factory-validate
description: Runs focused then full verification for a slice and records exact results.
model: sonnet
tools: Read, Bash, Grep
---
Run the focused tests named in the instruction, then the full suite,
lint, type-check, and secret/security scan. Record each exact
command and its pass/fail line. If something can't run, record the
blocker. Never claim a pass you didn't see.
Handoff: commands + results, requirements covered, gaps,
"Ready for Execution Summary? yes/no and why".

  6. Add the tracker clerk

    Only one agent holds the tracker tools. The orchestrator writes the artifact text; the clerk just reads a ticket or creates/updates one titled comment (Plan, Test Results, Execution Summary, Handoff) and returns its ID. Every other agent has the tracker tools disabled. Part 4 shows the setup.

  7. Add the two review stations

    pr-code-reviewer reads the full published PR diff, runs checks, and posts exactly one comment with ## Code Review and ## Security Review. It never edits code. pr-review-fixer reads that comment, sorts each finding into Fix, Waive, or Defer, prepares one tested fix, and stops for your approval before committing. Part 5 covers both.

  8. Write the orchestrator last

    The orchestrator dispatches stations in the Factory Manager's order and passes each a self-contained slice: goal, spec citations, files in scope, out of scope, expected handoff. It never pastes its own history, never reads source files, and never runs tests. A good warning sign: if it makes more than a handful of tool calls before dispatching anyone, it's doing the work itself.

Tips

  • Use the frontier model where judgment matters (orchestrator, plan, review) and a cheaper model for bounded work (explore, code, validate, tracker). Set it in each agent's front matter.

  • Limit tools per agent. Read-only stations shouldn't have Edit; only the clerk gets tracker tools; only review agents and the orchestrator get Git host tools.

  • Handoffs should fit on one screen. If a sub-agent returns a full log, tighten its instructions.

Common questions

Can I use the built-in planning or explore agents instead?

Yes, but custom files let you pin the model and tools for each station, so the factory's rules travel with the agent.

Why does only one agent talk to Jira?

Tool definitions take up context in every agent that has them. Isolating the tracker in one small clerk keeps the others lean and makes it easy to audit what gets posted.

Do sub-agents share memory?

No. Each starts with a fresh context and only sees the instruction you send. That's why the handoff format matters so much.

More guides

Occasional notes

Hear when a new guide is up

A short note when a guide is added. No account, and no emails until this form is connected to a real list.

Placeholder. This form is not connected to an email service. Nothing you type is saved or sent.