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

> Turn AGENTS.md into the Factory Manager: one file that defines the spec-first, test-first production line, its gates, the artifacts each stage leaves, and what agents may never do.

Level: Advanced
Tool: Agents
Category: Building
Time: About 30 minutes
Checked: 2026-10-15
Tools: [AGENTS.md format](https://agents.md)
HTML page: https://easyaihowtos.com/guides/software-factory-agents-md-factory-manager

**Part of the Software Factory series, a pattern by [Greg Alton](https://www.linkedin.com/in/greg-alton-ios).** 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.

## What you need

- A workspace folder that holds one or more repositories
- A coding agent that loads AGENTS.md (most current ones do)
- Your team's real test, lint, and build commands

## 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.
```markdown
# 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.
```markdown
## 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.
```markdown
## 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

```markdown
## 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.
```markdown
## 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

```markdown
## 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.
```markdown
## 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.

## FAQ

### 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.

---

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.