Skip to content

docs: trim repository agent guidance - #4246

Merged
max-sixty merged 5 commits into
mainfrom
codex/trim-agent-guidance
Sep 23, 2026
Merged

max-sixty merged 5 commits into
mainfrom
codex/trim-agent-guidance

Conversation

@max-sixty

@max-sixty max-sixty commented Sep 23, 2026 •

Copy link
Copy Markdown
Owner

The repository guidance had grown into long implementation histories, especially in the plugin instructions surfaced by #4241. This trims the nine guidance files from 2,769 lines to 380, keeping active contracts and fragile workflows while moving enduring cache semantics into the owning module docstring and updating trace and feature-spec references.

This follows #4245, which moved the guidance into AGENTS.md. The nine CLAUDE.md forwarding files remain in place.

Verified with the plugin-layout and documentation-sync integration tests, pre-commit, JSON parsing for the updated feature specifications, and git diff --check.

This was written by Codex on behalf of max-sixty

@worktrunk-bot worktrunk-bot left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Network Access trim drops the one carve-out that kept the rule consistent with shipped behavior. wt list statusline does reach the network on every redraw — src/cli/list.rs's after_long_help for it says "A stale CI status cache makes it reach the network for a second or two, so it fits a statusline the host renders in the background" — and the old text named it explicitly as not a synchronous prompt path. What's left is "A shell-prompt hot path never touches the network" in the root file and "A shell prompt must never touch the network" in src/commands/list/AGENTS.md, with the What currently reaches the wire inventory that listed statusline also gone. Read together they say a shipped path is a violation, and this guidance is exactly what gets consulted before someone changes it. Suggestion inline.

Two commands in the trimmed text no longer run as written:

  • docs/AGENTS.md keeps test:site in the site-check list but drops the npm --prefix docs exec playwright install webkit prerequisite the old Development section carried. docs/tests/browser-site.test.mjs opens with import { webkit } from 'playwright', so a first run without that one-time install fails on a missing browser executable with nothing in the file to explain it.
  • benches/AGENTS.md's "or add --chrome" follows a command whose -- separator has already been shown. --chrome is a wt-perf timeline flag, so appending it there passes it to wt list instead; the old file spelled the command out as timeline --chrome -- list --progressive.

<path>, <full-sha> (tests/AGENTS.md) and <name> (docs/demos/AGENTS.md) now sit outside code fences with no backticks, where Markdown parses them as HTML tags and GitHub's sanitizer drops them — the rendered lines read The file_report/?sha= endpoint and --only or ... --only .. Suggestions inline for both.

Four .config/clawpatch/features/*.json entries still cite root-AGENTS.md headings this PR removes: Hook Output Logs (twice in feat_custom_hook_logs.json, in summary and in the contextFiles reason), Time-of-check vs time-of-use in feat_custom_remove.json, and Benchmarks & Traces; Repository Caching in feat_custom_performance.json — the same class of reference the PR already swept in the two benches/AGENTS.md docstrings. Three of the four have a new home to point at (HookLog in src/commands/process.rs, the # Caching docstring in src/git/repository/mod.rs, benches/AGENTS.md). The TOCTOU rule is the one with none: the general statement — be conservative across the gap between the safety check and the operation; don't force-remove during cleanup — is dropped, and what survives is per-site notes in code (src/commands/hook_plan.rs, src/git/remove.rs). That one is worth keeping in Data Safety on its own merits, not just to fix the citation. Happy to push a commit retargeting the four citations if you want it in this PR.

Comment thread AGENTS.md Resolved
Comment thread src/commands/list/AGENTS.md Resolved
Comment thread docs/AGENTS.md Resolved
Comment thread benches/AGENTS.md Resolved
Comment thread tests/AGENTS.md Resolved
Comment thread docs/demos/AGENTS.md Resolved
Base automatically changed from codex/agents-md-migration to main September 23, 2026 10:20
…ance

# Conflicts:
#	.config/clawpatch/features/feat_custom_hook_logs.json
#	.config/clawpatch/features/feat_custom_performance.json
#	.config/clawpatch/features/feat_custom_remove.json
#	.config/clawpatch/features/feat_custom_repo_cache.json
#	.github/AGENTS.md
#	.github/CLAUDE.md
#	AGENTS.md
#	CLAUDE.md
#	benches/AGENTS.md
#	benches/CLAUDE.md
#	docs/AGENTS.md
#	docs/CLAUDE.md
#	docs/demos/AGENTS.md
#	docs/demos/CLAUDE.md
#	plugins/worktrunk/AGENTS.md
#	plugins/worktrunk/CLAUDE.md
#	src/commands/AGENTS.md
#	src/commands/CLAUDE.md
#	src/commands/list/AGENTS.md
#	src/commands/list/CLAUDE.md
#	src/commands/list/collect/mod.rs
#	src/commands/picker/mod.rs
#	tests/AGENTS.md
#	tests/CLAUDE.md
@max-sixty
max-sixty merged commit e8b264c into main Sep 23, 2026
39 of 71 checks passed
@max-sixty
max-sixty deleted the codex/trim-agent-guidance branch September 23, 2026 10:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants