diff --git a/AGENTS.md b/AGENTS.md index 2e0d7d1..5cccfba 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -13,6 +13,26 @@ Follow it rather than improvising: propose, merge, apply, archive — each step its own pull request, except documentation-only changes where propose and archive belong in one. +## Read the corpus first + +Before starting work in any repository, read `openspec/specs/` for the +capabilities that bind it. `openspec/specs/repo-standards/` binds every +repository; the rest bind by type, recorded in the classification. + +Requirements are not advice. A repository that does not satisfy one is +non-conformant, and work that leaves it that way is unfinished. + +## When you find something + +Before editing any repository, answer: **which requirement authorizes this?** + +If a requirement covers it, the fix is compliance work — cite the requirement in +the pull request. If none does, propose the change first. Do not fix it and +write the requirement afterwards; that produces a corpus that describes what +already happened rather than what was agreed. + +See @CONTRIBUTING.md under "When you find something". + ## Planning boundary `/opsx:propose` produces planning artifacts and then stops. Do not edit code in diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 49ec1e4..8c8132c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -189,6 +189,35 @@ the spec while implementing, update the change rather than quietly building something else, then `/opsx:sync` so the corpus reflects what was actually built. +## Read the corpus first + +`openspec/specs/` is the standing answer to what is true about osapi-io. Read +the capabilities that bind the repository you are working in before you start — +`repo-standards` binds every repository, and the classification records which +others apply by type. + +This is what makes the next question answerable. + +## When you find something + +Most work starts by noticing a problem rather than by deciding to write a +change. What you do next depends on one question: + +**Does a requirement already cover it?** + +- **Yes** — fixing it is compliance work. Open an ordinary pull request against + the repository, and cite the requirement it satisfies. +- **No** — propose first. The fix is the second step, not the first. + +The temptation is to fix it immediately, because fixing feels like progress and +the change process feels like overhead. That is exactly how the corpus falls +behind reality: the work lands, the requirement is written afterwards to +describe what was already done, and nothing was ever actually agreed. + +If a fix is urgent, do it — then open the change and say in it that the work +preceded the requirement. Skipping the change entirely is what leaves the next +person with a rule that exists only in someone's memory. + ## Running a change `main` is protected, so each step below is its own pull request.