lda.chat/lda-wf
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: trim live roadmap and guidance

Browse Source
This commit is contained in:
lda
2026-09-04 23:43:42 +07:00 Verified
parent 8d714f625c
commit e583b961f3
3 changed files with 151 additions and 1019 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/AGENTS.md
+40 -80
View File
@@ -1,99 +1,59 @@
# docs management
# Documentation workflow
its the age old problem. code changes, but i dont bother fixing docs. its been here before me, before chatgpt, and after chatgpt.
Keep live documentation authoritative and short. Use
[`README.md`](README.md) as the index for current documentation.
## lets improve this
## Before editing documentation
check [README.md](README.md) as pointers. they point to live evolving docs.
- 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.
a good docs pass, searching for kw, changing the documents that have them. cool. dedicated docs pass after a Thing done. great.
## Separate live and historical documents
ACTIVE (planned, running) implementation plans and specs sit in their folders.
`superpowers/plans/` is only for executable handoff plans that are active or in
progress.
Use these locations consistently:
DONE docs go straight to [`historical/`](historical/). Prefer keeping the OG
path shape under `docs/historical/`, for example
`docs/superpowers/plans/foo.md` -> `docs/historical/superpowers/plans/foo.md`.
You can edit the top of the file to state that its historical, but just being
in the folder is enough.
- `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.
superpowers skills say to tick those boxes; do tick those boxes.
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.
stale docs, even at docs/, go to historical/ or git rm.
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.
user facing docs need updates too. User facing docs include [/skills](../skills/)
## Keep the roadmap live
## roadmap plans?
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.
in superpowers plans there are now suddenly some big plans, like roadmaps, with multiple slices that turn into dedicated implementation plans.
## Keep code and documentation consistent
Those need linking, active or done. Since any done plans go to `historical/**`,
live docs must point to `historical/**` when they cite old slice plans.
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.
`current_roadmap.md` is the live roadmap. Roadmap-shaped plan files are
historical context unless they are actively being used to drive this exact next
slice.
## Verify Markdown edits
## superpowers specs? (generalize to docs/)
Run Markdown lint on the exact files you changed:
Any specs files in that folder represent the current state of the code. Ok
anything at docs/ do. Hence, if a Thing replaces another, something has to go to
the historical/.
as i said before. readme points to LIVE, Evolving docs. cant have stale/superseded stuff in here.
Same stuff for skills!
If a spec is still a useful design contract, update it in place. If it is only
"how we got here", move it to `historical/**`. Do not leave two docs claiming
different current behavior.
## Important rules
When moving or retiring docs, search for the old filename and update live links:
`docs/README.md`, `docs/current_roadmap.md`, skills, and nearby architecture
docs are the usual places.
If code has a partial implementation and docs mention the limitation, add a
short comment or docstring at the code seam too. Future agents see code before
they see old plans.
# docs formatting
## (caution: unstable) markdown formatting
use `pnpx markdownlint-cli(2) --fix '(glob the md)'`
<!-- ill need to setup cli2 -->
Note that this will mess things up, if you dont already follow the strict rules of markdownlint
use `git restore docs/historical` afterwards
### pitfall
all about indenting.
````md
1. you have a list, ordered or not?
this line ends the list, because it has no indents.
```bash
## even this code block has to be indented
```powershell
pnpx markdownlint-cli2 'docs/AGENTS.md' 'docs/current_roadmap.md'
```
2. otherwise this will be "fixed" and renumbered to 1.
Use narrow lint or fix targets. Broad autofixes can rewrite historical files or
unrelated user changes.
<!-- in case -->
9. we have come far
- notice the indents
<!-- a blank line here is standard -->
10. after this point
- the indent increases
- since the list marker is longer
````
Follow CommonMark list indentation. When a Markdown example contains fenced
code, wrap the outer example in a fence of four or more backticks.
### why not prettier? it does much more
when prettier supports compact table i'll switch to it
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.