irdb/files

Milestone Instructions

Each MXX-*.md file in this directory is a self-contained prompt for a fresh Claude Code session running Sonnet 4.6. One agent process executes one milestone end-to-end, then stops.

Why fresh agents per milestone

• Long agent runs accumulate context drift. By M8 a long-running agent would be making decisions based on a fuzzy memory of M2.
• A fresh agent reading a focused prompt makes sharper decisions.
• Hand-offs become explicit and reviewable: each milestone produces a commit and a PROGRESS.md entry the next agent reads.
• If a milestone goes wrong, you re-run only that milestone. Nothing earlier is contaminated.

Setup (do this once, before M01)

1. Place the master spec at the repo root as SPEC.md. Every milestone file references it by section number.
2. Initialize git, create an empty PROGRESS.md at the repo root with a single header # Build Progress.
3. Confirm the agent has access to: filesystem, shell, Docker, composer, npm, php.

Running a milestone

For each MXX-*.md file in order:

1. Open a new Claude Code session.
2. Paste (or attach) the milestone file as the initial user message.
3. Let the agent work. It will read SPEC.md, run verification commands, do the work, run acceptance commands, commit, and stop.
4. Review the commit and the PROGRESS.md entry.
5. If acceptance passes, move to the next file. If not, see "When a milestone fails."

Structure of each milestone file

# MXX — Title
## Mission                 (what this milestone accomplishes, in 2-3 sentences)
## Before you start        (prerequisites, verification commands)
## Required reading        (specific SPEC.md sections)
## Tasks                   (concrete checklist, in order)
## Implementation notes    (patterns, gotchas, code shapes)
## Out of scope            (DO NOT — explicit guardrails against scope creep)
## Acceptance              (exact commands; all must pass before commit)
## Handoff                 (commit message format, PROGRESS.md template)

When a milestone fails

If acceptance criteria don't pass:

1. Do not start the next milestone. Out-of-order work is harder to fix than a stuck milestone.
2. Read the agent's notes in chat and any partial PROGRESS.md updates.
3. Either: (a) start a new fresh agent with the same milestone file plus a brief note about what went wrong, or (b) hand-fix and commit, then update PROGRESS.md manually.
4. Only proceed when the current milestone's acceptance commands all pass.

Order

#	File	Builds on
M01	M01-monorepo-skeleton.md	—
M02	M02-database-migrations.md	M01
M03	M03-api-auth-foundations.md	M02
M04	M04-token-system-and-ingest.md	M03
M05	M05-reputation-engine-and-jobs.md	M04
M06	M06-manual-blocks-allowlist.md	M05
M07	M07-policies-and-distribution.md	M06
M08	M08-ui-scaffold-and-auth.md	M07
M09	M09-ui-ips-history-dashboard.md	M08
M10	M10-ui-admin-crud-pages.md	M09
M11	M11-enrichment.md	M07
M12	M12-audit-and-settings.md	M10, M11
M13	M13-polish-openapi-docs.md	M12
M14	M14-hardening.md	M13

M11 (enrichment) only structurally depends on M07; it can be run in parallel with M08–M10 if you have multiple agents available, but the simpler thing is sequential execution.

Common rules — every milestone obeys these

These are repeated in each file but worth stating once here:

• Read SPEC.md before doing anything. It is the source of truth. The milestone file is a focused execution plan, not a full design document.
• Stay in scope. Each milestone has explicit "out of scope" items. If you encounter something that feels like it should be done now but isn't listed in tasks, it belongs to a later milestone or is intentionally deferred.
• Stop and ask if a requirement is ambiguous, contradicts SPEC.md, or appears wrong once you're in the code. Do not paper over it. Stopping mid-milestone is correct behavior in that case.
• No new dependencies without justifying them in PROGRESS.md. The SPEC.md tech stack is non-negotiable.
• Tests must pass before commit. Linters too. PHPStan level 8 on src/ and php-cs-fixer.
• One commit per milestone, conventional-commit style. Include the milestone number.
• Update PROGRESS.md at the end with: what was built, what was deferred, anything the next milestone should know.