This commit is contained in:
parent
44431c4e66
commit
ab35533289
1 changed files with 8 additions and 129 deletions
137
AGENTS.md
137
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 <branch>` succeeds
|
||||
7. `git status` shows the branch is up to date with `forgejo/<branch>`
|
||||
|
||||
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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue