README.md
Birdbrain docs
Author-time documentation for the project. Some folders are tracked (durable design decisions and conventions); plans/ is gitignored (ephemeral working notes).
Canonical layout
| Folder | Purpose | Naming convention | Tracked? |
|---|---|---|---|
reference/ | Long-lived technical documentation. Stable, edited in place as the system evolves. | <topic>.md | yes |
specs/ | Design specs, design briefs, spikes, and assessments. Decisions captured at design time; treat as immutable once approved. | YYYY-MM-DD-<slug>-design.md, -spike.md, -assessment.md, or -brief.md | yes |
adr/ | Architecture Decision Records. | NNNN-<slug>.md | yes |
plans/ | Implementation plans, migration trackers, and operational checklists. Living documents — checked off as work progresses. | YYYY-MM-DD-<slug>.md | no — gitignored |
archive/ | Superseded specs moved out of the active folders. | Original filename preserved | yes |
superpowers/ | Output from the superpowers agent skill — managed by tooling, do not hand-edit. | Tool-managed | yes (frozen) |
plans/ is intentionally gitignored: implementation checklists are author-time artifacts, they get checked off and rot, and bundling them into feature PRs creates noise. Write them, refer to them locally, and let them disappear with the working tree. Tracked durable docs (specs, ADRs, reference) must be committed in their own PR — never bundled with a src/** change.
Conventions
- New design or spec? Drop it in
specs/with today's date as the prefix. - New implementation plan? Drop it in
plans/with today's date as the prefix (will not be tracked). - Superseding an existing doc? Move the old file to
archive/(keep its original name) before adding the replacement. - Permanent technical reference (architecture, pipelines, protocols)? Goes in
reference/without a date prefix.
Tool-specific path overrides
| Tool / skill | Built-in default | Override (use this instead) |
|---|---|---|
superpowers:brainstorming | docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md | docs/specs/YYYY-MM-DD-<topic>-design.md |
superpowers:writing-plans | docs/superpowers/plans/YYYY-MM-DD-<feature>.md | docs/plans/YYYY-MM-DD-<feature>.md |
speckit.* | varies | follow the canonical layout above |
When a skill says "save to docs/superpowers/...", treat that as overridden by this README. Always write to docs/specs/ or docs/plans/.
Legacy superpowers/ directory
docs/superpowers/ is the old default path written by the Superpowers skill before this convention was set. It is frozen:
- Do not write new files there.
- Existing files remain for git history reference. Canonical copies of any duplicated docs live under
reference/andspecs/. - When superseding a
superpowers/doc, move the new version intospecs/orplans/per the convention above.