Skip to content

Latest commit

 

History

History

docs

README.org

Design records and documentation policy

Contents

The specs/ directory retains design decisions and the plans/ directory retains implementation plans. These files explain why a change was made and how it was intended to proceed. They are not shell configuration, agent instructions, or executable skills, and merely being tracked here does not load them into a session.

readme-policy.json is different: it is active policy data consumed by bin/docs-audit. It declares which top-level directories require a README, which ones have an explicit exemption, the root directory-map contract, and the source/generated pairs and skill inventory owned by the audit.

Retention and maintenance

Keep a specification when it records a decision that remains useful for interpreting the repository. Keep a plan as an implementation record even after its checkboxes have been completed; it is evidence, not a live task queue. Current behavior belongs in the README or source file owned by the subsystem, not only in a dated plan.

When adding a tracked top-level directory, update readme-policy.json with either a required README or an explicit exemption, then add exactly one row to the root directory map. Verify the complete documentation graph with:

bin/docs-audit audit

The audit is read-only. bin/docs-audit generate is the separate command that rewrites the tracked skill inventory.