Feature plan format — Agent guide

Plans live in .feature-plans/ (pending/, wip/, done/). See _plan_sample_format.md for the template. For larger features, a PRD should exist before this plan — link it in the PRD: frontmatter field.

Writing style

• Bullet points only — no full sentences or prose paragraphs
• Include file paths + line numbers for every code reference
• Keep research findings to: file, trigger, risk level, and why
• Approach sections: what changes, where, key behavioral difference
• No code blocks unless showing a specific API contract or critical snippet

Format rules

Avoid

• Long sentences and multi-sentence paragraphs
• Prose explanations — use bullets or a table instead
• Buried actions inside paragraphs — extract as Fix: bullets or table
• Code blocks beyond short API contracts or critical snippets

Plan structure

All plans follow this structure (see _plan_sample_format.md):

1. Frontmatter — Issue, Branch, Status, PRD link
2. Problem — 1-3 bullets: what's broken / missing
3. Concept — High-level user-facing behavior
4. Requirements — Numbered table
5. Research — Bullet-point findings with file paths + line numbers
6. Root Cause — Core issue in 1-2 bullets
7. Approach — Architecture, Data Model, Fix bullets (file.ext:line)
8. Files to Modify — Table: | File | Change |
9. Risks / Open Questions — Table: | # | Question | Notes |
10. Implementation Phases — Phased checklist with test verification blocks
11. Files Summary — Table mapping file → phase → change

Implementation phases and test verification

Every phase ends with a "Verify phase N" block. The phase is not done until those tests pass.

Numbering

• Implementation items: N.1, N.2, N.3 …
• Test items: N.T1, N.T2 … (T prefix distinguishes them from implementation steps)

Test item format

- [ ] **1.T1** Unit — `ClassName`: [specific assertion in plain language]
- [ ] **1.T2** Integration — `[flow name]`: [trigger → expected outcome]
- [ ] **1.T3** Regression — `[existing flow]`: [behavior that must still pass]

Each test item must specify:

1. Type — Unit / Integration / Regression
2. Class or flow — the test file/class name, or the flow being verified end-to-end
3. What it verifies — one plain-language assertion (not "test it works")

Unit vs integration

Rules

• Every phase must have at least one test item (unit or integration)
• Test items live at the end of the phase, in a **Verify phase N:** block — not scattered between implementation items
• Test files belong in the Files Summary table alongside source files
• "Write tests" without a class name or assertion is not a valid test item — be specific

Tables

Use tables for structured data:

• File changes: | File | Change |
• Risk matrix: | # | Question | Notes |
• Config / state: | Variant | Current | Target |
• Options: | Option | Pros | Cons |

Keep cell content short; use bullets inside cells only if needed.

ASCII flows

Use for sequences and data/UI flow:

User action → Controller → Service → Store commit
                ↓
           UI state → Render

• One line per step or level
• Indent for nested steps
• Arrow → for "then" or "leads to"

Checklist before committing a plan

• Title and first line make scope clear
• No long paragraphs — bullets and tables only
• Each issue has Problem + Fix + File(s)
• Files summary table present (includes test files)
• ASCII flow used where a sequence matters
• File paths include line numbers where specific
• Every phase has a **Verify phase N:** block with named, specific test items
• Test items distinguish unit from integration/regression