Project Spec
What to build, how it fits together, how to keep going.
Process
- Explore: Check context—files, docs, commits, patterns.
- Ask: Ask many questions (multiple choice when possible) until you can fill every section.
- Approaches: If multiple valid paths exist, present 2-3 options. Lead with your recommendation.
- Derive: Map conversation to spec sections:
- Mission: what, who, why
- Architecture: technical decisions
- Components: what exists
- Constraints: non-negotiables
- Priorities: current focus
- Standards: quality bar
- Write: Output
PLAN.md with spec and progress in one file.
Spec Structure (under 100 lines)
Instructions:
- Read Progress section to know what's done, check git log for context
- Build the next item from Priorities—do not ask what to work on
- Make decisions from existing code patterns
- Commit at natural breakpoints (test passing, working feature, integration complete)
- Update Progress section after each commit, continue to next item
- When priorities clear, surface new work
- PLAN.md is a living document—update as work evolves
- No clarifying questions—ship working features
Mission: 1-3 lines. What, who, why.
Architecture: Technical decisions stated, not debated.
Components: What exists. One line each—name and essence.
Constraints: Non-negotiables only.
Priorities: Current focus. Replenishes.
Standards: Quality bar. Improve over time.
Progress: What's done, what's current, what's next. Update after each commit.
Writing Principles
Concrete, not vague
- "CLI tool for rotating AWS credentials" not "developer utility"
- "Postgres, Redis, S3" not "appropriate storage solutions"
No filler
- Cut: "Prefer working software over perfection", "Start simple", "Future integrations"
1---2name: project-spec3description: Create a project spec for AI agents to work from autonomously.4---56# Project Spec78What to build, how it fits together, how to keep going.910## Process11121. **Explore**: Check context—files, docs, commits, patterns.132. **Ask**: Ask many questions (multiple choice when possible) until you can fill every section.143. **Approaches**: If multiple valid paths exist, present 2-3 options. Lead with your recommendation.154. **Derive**: Map conversation to spec sections:16 - Mission: what, who, why17 - Architecture: technical decisions18 - Components: what exists19 - Constraints: non-negotiables20 - Priorities: current focus21 - Standards: quality bar225. **Write**: Output `PLAN.md` with spec and progress in one file.2324## Spec Structure (under 100 lines)2526**Instructions**:27- Read Progress section to know what's done, check git log for context28- Build the next item from Priorities—do not ask what to work on29- Make decisions from existing code patterns30- Commit at natural breakpoints (test passing, working feature, integration complete)31- Update Progress section after each commit, continue to next item32- When priorities clear, surface new work33- PLAN.md is a living document—update as work evolves34- No clarifying questions—ship working features3536**Mission**: 1-3 lines. What, who, why.3738**Architecture**: Technical decisions stated, not debated.3940**Components**: What exists. One line each—name and essence.4142**Constraints**: Non-negotiables only.4344**Priorities**: Current focus. Replenishes.4546**Standards**: Quality bar. Improve over time.4748**Progress**: What's done, what's current, what's next. Update after each commit.4950## Writing Principles5152**Concrete, not vague**53- "CLI tool for rotating AWS credentials" not "developer utility"54- "Postgres, Redis, S3" not "appropriate storage solutions"5556**No filler**57- Cut: "Prefer working software over perfection", "Start simple", "Future integrations"
diegosouzapw