# Create global sub-agents for every station of the Software Factory > Write reusable sub-agents for planning, exploring, research, coding, validation, tracker updates, code review, and PR fixes, each with one job and a compact handoff. Level: Advanced Tool: Agents Category: Building Time: About 35 minutes Checked: 2026-10-15 Tools: [Claude Code sub-agents](https://docs.claude.com/en/docs/claude-code/sub-agents), [AGENTS.md format](https://agents.md) HTML page: https://easyaihowtos.com/guides/software-factory-global-sub-agents **Part of the Software Factory series, a pattern by [Greg Alton](https://www.linkedin.com/in/greg-alton-ios).** 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. ## What you need - The Factory Manager AGENTS.md from part 2 - A coding agent that supports custom sub-agents defined as Markdown files with YAML front matter ## 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: ```markdown --- 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 ```markdown --- 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 ```markdown --- 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. ## FAQ ### 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. --- This guide is from Easy AI How-To (https://easyaihowtos.com). It is independent of the tools named above. Screens and free-plan limits change, so check the date before you rely on a button name.