From ab35533289b41d02f325eac28ee7f2b61a1aa343 Mon Sep 17 00:00:00 2001 From: dirtydishes Date: Sun, 31 May 2026 09:29:53 -0400 Subject: [PATCH] trim repo turn doc guidance --- AGENTS.md | 137 ++++-------------------------------------------------- 1 file changed, 8 insertions(+), 129 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 225cfda..72a0e65 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -86,39 +86,15 @@ Agent expectations: ## Required Turn Documentation -At the end of every completed implementation task, before final handoff, create a user-readable HTML document describing the work. +Follow the global turn-documentation rules in `~/.codex/AGENTS.md` for repository implementation tasks, plan documents, and non-repo computer tasks. -This documentation is mandatory whenever code, configuration, tests, or project files were changed. +For this repository, the repo-specific requirements are: -### Precedence and classification - -Use this decision order before creating a turn document: - -1. Check the minor/trivial exemption checklist below first. -2. If the task clearly matches an exemption, do not create a turn document. -3. If the task is a clearly substantive implementation change, create a turn document. -4. If classification is ambiguous or mixed, ask the user before creating a turn document. - -The minor/trivial exemptions override the general mandatory turn-document rule. - -For diff content in turn documentation (including "Code diffs" and "Relevant Diff Snippets"), render the diff as HTML with the `@pierre/diffs/ssr` library by default. Do not try to run `bunx @pierre/diffs`; this package is installed as a library and does not expose a CLI. A plain diff/code block fallback is only acceptable if importing or rendering with `@pierre/diffs/ssr` fails because of a real tool or blocking error, and the document must say why. - -Known-good `@pierre/diffs/ssr` pattern: - -```js -import { preloadPatchDiff } from "@pierre/diffs/ssr"; -import { execSync } from "node:child_process"; - -const patch = execSync("git diff -- path/to/file", { encoding: "utf8" }); -const rendered = ( - await preloadPatchDiff({ - patch, - options: { maxContextLines: 4 } - }) -).prerenderedHTML; -``` - -Embed `rendered` directly into the turn document inside a clearly labeled diff container. +- Save repository implementation turn documents in `docs/turns/`. +- Use the `impeccable` skill to structure and style repository implementation turn documents when available. +- Render "Relevant Diff Snippets" with `@pierre/diffs/ssr`; use https://diffs.com/docs as the SSR reference. +- For minor updates to a previous change, update the existing turn document instead of creating a new one. +- The minor/trivial exemptions below override the general documentation requirement for this repository. ### No turn document for minor/trivial checklist matches @@ -133,69 +109,9 @@ Do not create a turn document when the change is minor/trivial and cleanly match If a change does not cleanly fit either exempt or substantive buckets, ask the user before creating a turn document. -### When making a minor update to a previous change, update the existing documentation instead of creating a new file. Use the following format: - -**"New Changes as of {time and date at which the change was made}"** -- **Summary of changes** -- **Why this change was made** -- **Code diffs** (render with `@pierre/diffs/ssr` by default; if importing or rendering fails, include a clearly labeled plain diff/code block and note why) -- **Related issues or PRs** - -Additionally, add a note to each section explaining why the changes were made. - -### Location - -Save the document in: - -```text -docs/turns/ -``` - -Use a clear timestamped filename: - -```text -docs/turns/YYYY-MM-DD-short-task-name.html -``` - -Example: - -```text -docs/turns/2026-05-14-add-market-replay-controls.html -``` - -### Format - -Use the `impeccable` skill to structure and style the document as clean, readable HTML. - -For this repository, `impeccable` is the styling and layout authority for turn documents when available. Do not apply global non-repo computer-task house styling to repository turn documents. - -If the `impeccable` skill is unavailable or blocked by an actual tool/file error, still create a well-structured standalone HTML file with: - -- A concise summary at the top -- A detailed explanation of what changed -- Relevant context or background -- Specific code snippets or examples when helpful -- Issues, limitations, tradeoffs, or mitigations -- Validation performed, including tests, builds, linters, or manual checks -- Any remaining follow-up work, with corresponding Beads issue IDs when applicable - -### Required Sections - -Each turn document must include these sections: - -1. **Summary** -2. **Changes Made** -3. **Context** -4. **Important Implementation Details** -5. **Relevant Diff Snippets** (render with `@pierre/diffs/ssr` by default; if importing or rendering fails, include a clearly labeled plain diff/code block and note why) -6. **Expected Impact for End-Users** -7. **Validation** -8. **Issues, Limitations, and Mitigations** -9. **Follow-up Work** - ### Completion Rule -A task that requires a turn document is not complete until: +For repository implementation tasks that require turn documentation, the task is not complete until: 1. The Beads workflow is updated 2. The turn document is created in `docs/turns` @@ -204,40 +120,3 @@ A task that requires a turn document is not complete until: 5. `bd dolt push` succeeds 6. `git push forgejo ` succeeds 7. `git status` shows the branch is up to date with `forgejo/` - -For tasks that do require turn documentation, the document may be brief when scope is small, but it must clearly explain what changed and how it was validated. - -## Plan Mode Documentation - -When working in plan mode, do not modify implementation files. - -At the end of plan mode, provide a concise summary of the plan and ask the user whether they want to proceed with implementation. - -If the user asks to save the plan, create a user-readable HTML plan document in: - -```text -docs/plans/ -``` - -Use a clear timestamped filename: - -```text -docs/plans/YYYY-MM-DD-short-plan-name.html -``` - -The plan document should be labeled clearly as a plan and should include: - -1. **Plan Summary** -2. **Goals** -3. **Proposed Changes** -4. **Relevant Context** -5. **Implementation Steps** -6. **Risks, Limitations, and Mitigations** -7. **Open Questions** - -Always do the following when you finish a task, finish the beads workflow and and make a commit: -- Document the changes in a user-readable format -- Use the impeccable skill to structure the document as HTML -- Create a clear, concise summary of the changes at the top, followed by a detailed description of the changes, including any relevant context or background as well as specific code snippets or examples. -- Note any relevant issues or limitations that were addressed or mitigated by the changes. -- The HTML file should be stored in the `docs/turns` directory. It should include the current date and time, as well as a brief explanation of changes. e.g. docs/turns/YYYY-MM-DD-{description}.html