Skip to content
Easy AI How-To

AdvancedAgentsBuilding

Write an AGENTS.md Factory Manager that defines your whole SDLC

Part of the Software Factory series, a pattern by Greg Alton. In this pattern, AGENTS.md isn't a list of coding tips. It's the Factory Manager: the single file that defines your production line from spec to merge. Below is a generic, copyable example built station by station.

Time
About 30 minutes
Checked
Tool
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. Add a load gate

    Start the file by making the agent confirm it has the rules before doing anything. Nested repositories can have their own AGENTS.md that adds rules but can't weaken these.

    # AGENTS.md — Software Factory Manager

## 0. Load gate
This file is the Factory Manager. Every session must have it in
context before starting work. Before editing a nested repository,
also read that repository's AGENTS.md. Nested files may tighten
these rules; they may not weaken them.

  2. Make the spec the source of truth

    The first station is the spec. Point the agent at where specs live and forbid building anything the spec doesn't say.

    ## 1. Spec first
- Specs live in `specs/<feature>/` as requirements.md, design.md, tasks.md.
- Read the relevant spec before changing behavior. Requirement IDs
  and task dependencies are binding.
- Never implement behavior that is missing, ambiguous, or
  contradictory in the spec. Stop and fix the spec first.
- Keep spec, tests, code, and task checklist in sync.

  3. Derive tests from the spec, before code

    The second station turns spec requirements into failing tests. This is the heart of the factory.

    ## 2. Tests before code (RED → GREEN → REFACTOR)
1. RED: write the smallest test for one specified behavior. Run it.
   Record the expected failure. Tag it with the requirement ID.
2. GREEN: write the minimum code that makes it pass.
3. REFACTOR: clean up only while tests stay green.
- No production change without a failing test first.
- Never weaken, skip, or delete a test to get green.

  4. Define validation gates and branch rules

    ## 3. Validate
- Run focused tests, then the repo's full suite, lint, type-check,
  and security scan. Record exact commands and results.
- If a command can't run, record the command and blocker.
  Never claim a pass you didn't see.

## 4. Branches and publication
- Check `git status` first; stop if unrelated changes exist.
- Branch fresh from the base branch. Never work on main.
- Do not commit, push, or open a PR until the developer approves.
- Never commit secrets or .env files.

  5. Require durable artifacts

    Every station leaves evidence in the tracker, not just in chat. Name the artifacts exactly so they're easy to find and update.

    ## 5. Tracker artifacts (living comments on the ticket)
- "Plan — {KEY}": scope, traceability, task table, test-first plan.
- "Test Results — {KEY}": test table (pending/failing/passed),
  RED→GREEN evidence, exact commands, QA steps.
- "Execution Summary — {KEY}": what changed, files, verification.
- "Handoff — {KEY}": PR link, review comment, disposition report.
Update the same comment as work moves; don't scatter notes.
No commit or PR until Plan, Test Results, and Execution Summary exist.

  6. Define review and the merge gate

    ## 6. Review (after the PR is published)
1. pr-code-reviewer posts ONE comment with "## Code Review" and
   "## Security Review" sections.
2. pr-review-fixer triages every finding (Fix / Waive / Defer),
   prepares one verified fix at a time, and waits for approval
   before each commit.
3. When no Fix items remain, post a Review Disposition Report on
   the PR accounting for every finding with evidence.
Agents never merge. Merging is the developer's decision.

  7. Define the stations and the dispatch order

    Finish with a staff table and the canonical sequence. Pin models in each agent file, not in prompts.

    ## 7. Stations
| Agent | Model tier | Role |
| --- | --- | --- |
| orchestrator | frontier | Sequencing, gates, artifact content |
| plan | frontier | Spec → task table and test plan |
| explore / research | low-cost | Read-only fact gathering |
| code | low-cost | One RED→GREEN→REFACTOR slice |
| validate | low-cost | Suites and evidence |
| tracker | low-cost | Reads tickets, posts artifacts |
| pr-code-reviewer / pr-review-fixer | frontier | Review and fixes |

Sequence: load gate → read ticket → explore → plan → post Plan →
code slices → post Test Results → validate → post Execution
Summary → developer approves publication → review → fix →
post Handoff.
The orchestrator dispatches; it does not read files or run tests.

Tips

  • Write rules as testable statements ("never", "before", "only"). Vague advice gets ignored.

  • Keep secrets out of the file. Tell agents never to read or print .env values, and to stop if a tool is unauthorized rather than falling back to raw tokens.

  • Add a 'Definition of done' checklist at the end that repeats every gate. Agents use it as a final self-check.

Common questions

How long should AGENTS.md be?

As long as the process needs, but every line should be a rule an agent can follow or check. A few hundred lines is normal for a full factory.

What if a ticket has no spec?

Then the first job is writing one. The plan agent should flag the gap and stop, rather than guessing behavior in code.

Does this work for docs-only changes?

Yes. Mark documentation or configuration-only tasks as exempt from the RED test rule, but keep validation and review.

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.