spec-best-practices

Naming

Always SPEC.md. No exceptions for the primary spec file. Not feature.spec.md, not SPEC-feature.md.

Supporting documents linked from a SPEC.md TOC may use descriptive names (e.g., commands.spec.md), but only when a root SPEC.md exists and links to them.

Placement

Specs are colocated with the code they describe: root SPEC.md for project scope, apps/foo/SPEC.md for app scope, packages/bar/SPEC.md for package scope.

• Avoid spec/, docs/specs/, and docs/plans/ directories. Prefer colocated SPEC.md files.
• Plan documents are ephemeral. Absorb durable decisions into the relevant SPEC.md and delete the plan doc.
• When a spec gets long, add a TOC linking to adjacent supporting files (./commands.spec.md, etc.). Supporting files live alongside the SPEC.md, not in a subdirectory.

Content

Specs are freeform markdown. No rigid template, no YAML frontmatter, no required section ordering. These elements must be present:

Problem and solution -- narrative context for why this system/feature exists. Lead with the problem.