lda-wf/docs/AGENTS.md

Documentation workflow

Keep live documentation authoritative and short. Use README.md as the index for current documentation.

Before editing documentation

• Read the nearby live document and 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:

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.