The AGENTS.md Orchestration File

One file in your project root runs the show. I call it AGENTS.md because more and more coding agents read that name (if yours reads a different file, Module 5 covers the fix). It tells the agent which stages exist, what each one needs, where it has to stop, and what you can say when it does.

Mine started as a list of stages and a lot of capital letters begging the agent to stop. That wasn't enough. The version below leans on files instead of pleading.

What Changed From the Simple Version

•Numbered files. Every stage writes one file into drafts/[slug]/. You can open any of them and see exactly what the agent saw.
•The upstream check. Each stage lists the files it needs. If one is missing, the stage refuses to run. Without this rule an agent will happily write a draft from whatever it remembers of the chat, and that is how invented stories get in.
•Checkpoints versus hard blocks. Checkpoints wait for your approval. Hard blocks don't care about your approval at all.
•A script for the AI-tell scan. A model grading its own prose for AI patterns is the fox auditing the henhouse. Code checks what code can check.

AGENTS.md template

Template

Copy into AGENTS.md in your project root, or whatever file your agent reads. Fill in the bracketed parts. Leave [slug] and [topic] alone, the agent fills those per article.

# [publication name] writing pipeline

This file is the source of truth for how this pipeline runs. Any other instructions file in this folder only points here. Change the rules in this file, nowhere else.

## Voice

Read voice/voice.md before any stage that writes or edits prose.
- Tone: [your tone]
- Audience: [your audience]
- Never: [things you never do]

## Running the pipeline

When I say "run the pipeline on [topic]", pick a short slug for the piece and run the stages below in order. Every stage has its own instructions file in agents/. Read that file before the stage runs and do only what it says.

Each stage writes one numbered file into drafts/[slug]/. Before a stage runs, check that every file on its "Needs" line exists. If one is missing, stop and tell me which one. Never rebuild a missing file from memory or from this chat.

1. Classify. agents/content-classifier.md. Needs: my input. Writes: 01-classified.json
2. Focus questions. agents/focus-questions.md. Needs: 01-classified.json. Writes: 01b-focus-questions.json, then 01b-focus-answers.json with my answers word for word
3. Research. agents/content-researcher.md. Needs: 01-classified.json, 01b-focus-answers.json. Searches the web and [your archive folder]. Writes: 02-research.md
4. Draft. agents/content-writer.md. Needs: 01-classified.json, 02-research.md. Writes: 03-draft.md
4b. Image prompts. agents/image-prompter.md. Needs: 03-draft.md. Writes: 04-image-prompts.md
5. Story check. agents/story-check.md. Needs: 01b-focus-answers.json, 02-research.md, 03-draft.md. Writes: 03c-story-check.md
6. Critique. agents/content-reviewer.md. Needs: 03-draft.md, 03c-story-check.md. Writes: 05-critique.md
7. Hazard check. agents/hazard-check.md. Needs: 03-draft.md, 05-critique.md. Writes: 05b-hazard-check.md
8. Humanize. agents/content-humanizer.md. Needs: 03-draft.md, 05-critique.md, 05b-hazard-check.md. Writes: 06-humanized.md
9. AI-tell scan. A script, not a model: scripts/ai-tell-scan.py. Needs: 06-humanized.md. Writes: 06b-scan-report.txt
10. Attribution check. First step of agents/newsletter-publisher.md. Needs: 06-humanized.md. Writes: 07-attribution-check.md
11. Publish prep. agents/newsletter-publisher.md. Needs: 06-humanized.md, 07-attribution-check.md. Writes: 10-meta.json, 10-copy-paste-assets.md
12. Ingest. After I say "published", copy the final article into [your archive folder] so research can find it next time.

Before any stage overwrites a file, copy the old version to drafts/[slug]/versions/.

Which model runs which stage lives in config/models.yaml. Don't choose a model yourself.

## Checkpoints (stop and wait for me)

Stop at each of these, show me what it lists, and wait for a gate command:
- After focus questions: show the questions. Wait for my answers. Never answer them yourself. My answers are the only source for my own stories.
- After story check: show 03-draft.md and 03c-story-check.md together.
- After critique: run the hazard check first. Show 05-critique.md only once it has passed.
- After the AI-tell scan: show what humanize changed and the scan score.
- After publish prep: show the package. Wait for "published" before ingest.

Silence is not approval. A question from me is not approval either. Only a gate command moves the pipeline forward.

## Hard blocks (I can't wave these through)

These stop the pipeline even if I say "continue":
- Missing upstream file: stop and name the file.
- Story check: any anecdote or number with no source in my answers or the research gets cut or sourced before critique runs.
- Hazard check: if any passage could point at [current employer], my team or my colleagues, show me only the flagged passage and halt. Don't show the draft or the critique until I cut it or confirm in writing that it comes from a past role.
- AI-tell scan: if the script fails, send the draft back to humanize. After three failed passes, stop and show me the findings.

## Gate commands

- "continue" (or "looks good", "proceed"): run the next stage
- "revise [notes]": apply my notes, show the result again, stay at this checkpoint
- "restart from [stage]": rerun that stage and every stage after it
- "skip critique": jump straight to publish prep. The hazard check still runs first.
- "pause": stop here. Every stage is already on disk. Next session, read drafts/[slug]/ to see where we are.

## Folders

drafts/[slug]/            numbered stage files, plus versions/
published/YYYY-MM-DD-[slug]/   final article, metadata, social copy
agents/                   one instructions file per stage
config/models.yaml        model and thinking level per stage
voice/                    voice guide and banned-word list
scripts/ai-tell-scan.py           the AI-tell scanner

Why the hazard check gates the critique: a risky passage shouldn't get another round of polish (or get quoted back in a revision note) before you decide whether it stays. So the pipeline halts first and shows you only the flagged lines.

Agent files: stages point at plain files like agents/content-writer.md. No special syntax, so any agent that can read a file can follow along. Module 6 builds those files.

Check the wiring before the first run

Try it

Paste into any coding agent, in the folder with your AGENTS.md.

There is an AGENTS.md in this folder that defines a writing pipeline. Don't run it yet. Check it.

1. For every stage, confirm its instructions file exists under agents/. List the missing ones and create a stub for each with one job and a "must not do" list.
2. Walk the stages in order. For each "Needs" file, confirm an earlier stage writes it. Flag any stage that needs a file nobody writes.
3. List every checkpoint and every hard block back to me in your own words, so I can see you read them.
4. Tell me the gate commands you will accept at a checkpoint, and what you will do if I reply with anything else.

Stop after step 4 and wait for me.