Default turn-doc diffs to @pierre/diffs
Summary
Updated repository turn-documentation rules to prefer @pierre/diffs for diff snippets, added a documented fallback path, and included the package/lock updates needed for consistent local usage.
Changes Made
- Edited
AGENTS.mdto add a default diff-format policy for turn docs. - Updated the minor-update template bullet for
Code diffswith explicit@pierre/diffsdefault plus fallback wording. - Updated required section
Relevant Diff Snippetswith the same default-and-fallback wording. - Added
@pierre/diffsto rootpackage.jsondependencies and syncedbun.lock.
Context
The existing guidance required a diff section but did not explicitly standardize on a single rendering tool. This change aligns turn-doc expectations around one default tool while preserving an escape hatch when tooling is unavailable.
Important Implementation Details
- The policy is intentionally a preferred default, not a hard requirement.
- Fallback usage is constrained to real tool/blocking errors and must be labeled with a reason.
- No runtime application behavior was changed; this is workflow/documentation and dependency-surface work.
Relevant Diff Snippets
@pierre/diffs is now the repository default for this section.
--- AGENTS.md
+++ AGENTS.md
@@
+For diff content in turn documentation (including "Code diffs" and "Relevant Diff Snippets"), use `@pierre/diffs` output by default.
@@
-- **Code diffs**
+- **Code diffs** (use `@pierre/diffs` output by default; if unavailable, include a clearly labeled plain diff/code block and note why)
@@
-5. **Relevant Diff Snippets**
+5. **Relevant Diff Snippets** (render with `@pierre/diffs` output by default; if unavailable, include a clearly labeled plain diff/code block and note why)
--- package.json
+++ package.json
@@
+ "dependencies": {
+ "@pierre/diffs": "^1.2.2"
+ }
Expected Impact for End-Users
- Future turn docs should have more consistent and readable diff presentation.
- Contributors have clearer guidance for fallback behavior when the preferred renderer cannot be used.
Validation
- Verified policy text appears in all required AGENTS locations for diff guidance.
- Ran
bun install --frozen-lockfileand confirmed lockfile consistency with no changes. - Confirmed repository is clean and branch is up to date after push.
Issues, Limitations, and Mitigations
- This change standardizes policy but does not retroactively update old turn docs.
- Actual visual rendering still depends on environment/tool availability; fallback instructions mitigate this.
Follow-up Work
- Optionally add a tiny helper script/example to generate
@pierre/diffsHTML snippets directly for turn docs.