specweave AGENTS.md

Essential Rules

1. NEVER pollute project root with .md files
2. Increment IDs unique (0001-9999)
3. ONLY 4 files in increment root: metadata.json, spec.md, plan.md, tasks.md
4. ALL reports/scripts/logs → increment subfolders (NEVER at root!)
5. metadata.json MUST exist BEFORE spec.md can be created
6. tasks.md + spec.md = SOURCE OF TRUTH (update after every task!)
7. EVERY User Story MUST have **Project**: field
8. For 2-level structures: EVERY US also needs **Board**: field

Increment Folder Structure

.specweave/increments/0001-feature/
├── metadata.json                  # REQUIRED - create FIRST
├── spec.md                        # WHAT & WHY
├── plan.md                        # HOW (optional)
├── tasks.md                       # Task checklist
├── reports/                       # ALL other .md files go here!
├── scripts/                       # Helper scripts
└── logs/                          # Execution logs
    └── 2026-01-04/

Workflow Orchestration

1. Plan Before Code

BEFORE implementing ANY non-trivial task (3+ steps):

1. Create increment: spec.md (WHAT/WHY) + plan.md (HOW) + tasks.md (checklist)
2. Get user approval before implementing
3. If something goes sideways → STOP and re-plan

See Task Format and User Story Format sections for templates.

2. Verify Before Done

Never mark a task complete without proving it works:

• Code compiles/builds successfully
• Tests pass
• Acceptance criteria actually satisfied
• Ask: "Would a staff engineer approve this?"

3. Dependencies First

Satisfy dependencies BEFORE dependent operations.

Bad:  node script.js → Error → npm run build
Good: npm run build → node script.js → Success