60 lines
2.3 KiB
Markdown
60 lines
2.3 KiB
Markdown
# Documentation workflow
|
|
|
|
Keep live documentation authoritative and short. Use
|
|
[`README.md`](README.md) as the index for current documentation.
|
|
|
|
## Before editing documentation
|
|
|
|
- Read the nearby live document and [`current_roadmap.md`](current_roadmap.md).
|
|
- Search for the concept and any filenames you plan to change.
|
|
- Preserve unrelated user changes in the worktree.
|
|
|
|
## Separate live and historical documents
|
|
|
|
Use these locations consistently:
|
|
|
|
- `superpowers/plans/` contains active executable implementation plans.
|
|
- `superpowers/specs/` contains current design contracts.
|
|
- `historical/` contains completed plans, superseded designs, and narrative
|
|
history. Preserve the original path below `historical/` when practical.
|
|
|
|
When work finishes, check every box in its implementation plan and move the
|
|
plan to `historical/`. Update live links after moving or retiring a document.
|
|
Search at least `README.md`, `current_roadmap.md`, `../skills/`, and nearby
|
|
architecture documents.
|
|
|
|
Update a specification in place while it remains the current contract. Move it
|
|
to `historical/` when it only explains how the code reached its current shape.
|
|
Keep one source of truth for current behavior.
|
|
|
|
## Keep the roadmap live
|
|
|
|
Limit `current_roadmap.md` to the current product shape, active work, next
|
|
priorities, durable constraints, and pointers to historical detail. Move
|
|
completed narratives out of the roadmap. If it exceeds 300 lines, trim it
|
|
before adding another section.
|
|
|
|
## Keep code and documentation consistent
|
|
|
|
Update user-facing documentation and repository skills when behavior changes.
|
|
If a live document describes a partial implementation, add a short comment or
|
|
docstring at the code seam. Future agents usually encounter code first.
|
|
|
|
## Verify Markdown edits
|
|
|
|
Run Markdown lint on the exact files you changed:
|
|
|
|
```powershell
|
|
pnpx markdownlint-cli2 'docs/AGENTS.md' 'docs/current_roadmap.md'
|
|
```
|
|
|
|
Use narrow lint or fix targets. Broad autofixes can rewrite historical files or
|
|
unrelated user changes.
|
|
|
|
Follow CommonMark list indentation. When a Markdown example contains fenced
|
|
code, wrap the outer example in a fence of four or more backticks.
|
|
|
|
Treat excerpt-only Python blocks as prose examples, not formatter input. For
|
|
example, Ruff can reinterpret a lone `arg3=None,` argument fragment as an
|
|
assignment because the surrounding call is absent.
|