Repository navigation
docs: trim agent instructions and slim the pr template - #252
Merged
Merged
Conversation
The template asked for a type checklist, a test-plan checklist and a seven-item checklist, which produced long bodies of unticked boxes that restated the diff. It is now the Why / Needs attention / Risk / Verified skeleton as comment hints, with two repo-specific Verified examples. CONTRIBUTING said to squash-merge, but the repo only allows rebase merges; it told contributors to fill the template completely; it hardcoded a Sonnet 4.6 co-author line that agents copied verbatim; and its 72-character header limit disagreed with commitlint's 100. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Assisted-by: Claude Code:claude-opus-5-5
AGENTS.md had grown to 248 lines / 19 KB, most of it derivable from the tree (project list, directory map, CI step list, Angular overview), duplicated in docs/ or the global agent config (commit rules, worktree policy, ticket-ID rule), or reference material only relevant on one machine. It is now 96 lines of repo-specific rules with pointers. Moved, not dropped: the Windows F: drive worktree and node_modules junction procedure and the tooling-traps table go to docs/agent-tooling-traps.md; the release job's resolve-before-tag rationale goes to docs/workflows.md. CLAUDE.md, GEMINI.md and AGENT.md are reduced to one-line shims over AGENTS.md. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Assisted-by: Claude Code:claude-opus-5-5
The rtk, gh, Windows curl and CRLF rows describe the tools, not this repo, and were copied verbatim into every jdwlabs traps doc. They now live once in the dotfiles repo (docs/agent-tooling-traps.md). This doc keeps the Windows-checkout trap (pnpm hard links across drives), which only this repo has. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Assisted-by: Claude Code:claude-opus-5-5
Agents may run commands, including pushing their PR branch; the blanket git push deny contradicted AGENTS.md, which expects agents to push. It is replaced by denies for the destructive forms only: --force, -f and +refspec (--force-with-lease stays allowed for rebases), and any push naming main. The rm -rf deny stays: it is destructive and nothing in AGENTS.md needs it. Verified with the rulesets API on 2026-09-30: the active Baseline ruleset on refs/heads/main carries pull_request, non_fast_forward and deletion, so a direct or force push to main is rejected -- except for the OrganizationAdmin bypass actor (bypass_mode always), and the devbox gh account is an org admin. A push to main made with those credentials is therefore not stopped by GitHub, so explicit denies for push-to-main forms sit alongside the force-push ones. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Assisted-by: Claude Code:claude-opus-5-5
Move the rm -rf, force-push and push-to-main rules from permissions.deny to permissions.ask so Claude Code asks the user rather than refusing. Ask rules still prompt in bypassPermissions mode. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Assisted-by: Claude Code:claude-opus-5-5
Claude Code matches everything before the first * literally, so an ask rule written as `kubectl delete*` misses `kubectl -n ns delete ...`, and `git push*` misses `git -C dir push --force`. Each cluster-mutating rule now has `<prog> * <verb>` and `<prog> * <verb> *` companions, and the git push rules take a `git *push*` prefix. A * in a Bash rule matches any text including spaces, and mid-pattern wildcards only draw a startup warning on allow rules. Checked with a glob run over flag-first invocations: all prompt; plain feature-branch pushes and --force-with-lease still do not. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Assisted-by: Claude Code:claude-opus-5-5
The footer table and examples named real-looking JDWLABS ticket IDs, which agents copy verbatim. KEY-123 shows the format without pointing at an unrelated ticket. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Assisted-by: Claude Code:claude-opus-5-5
jdwillmsen
approved these changes
Sep 30, 2026
jdwillmsen
left a comment
jdwillmsen
left a comment
Member
There was a problem hiding this comment.
Reviewed line by line (independent reviewer + spot-check of the ask-rule fixes): AGENTS.md trims lose nothing load-bearing — every removed line is moved, in a cited doc, stale, or in the global instructions; settings move sensitive ops from deny to flag-tolerant ask rules. Checks green, no threads, no open alerts.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
AGENTS.md was 248 lines / 19 KB, mostly derivable or duplicated, and CONTRIBUTING still said squash-merge and hardcoded a Sonnet 4.6 trailer and real ticket IDs (now
KEY-123) that agents copied. This trims the agent file to repo-specific rules and moves reference material instead of deleting it. Generic tool traps (rtk, gh, Windows curl, CRLF) now live once in the dotfiles box-wide doc (jdwillmsen/dotfiles#96);.claude/settings.jsonstops denying all pushes.Needs attention
docs/agent-tooling-traps.md:10— the F: drive Windows path is unverified; still current?AGENTS.md:95— pointer is an absolute devbox path to a doc in another repo; fine for a Windows clone too?.claude/settings.json:15— force-push (--force,-f,+ref), push-to-main andrm -rfrules now sit inask, notdeny, per your call: ask still prompts in bypass mode;--force-with-leaseisn't matched. Main's ruleset has an org-admin always-bypass. Rules are flag-tolerant (git *push*,<prog> * <verb> *) sogit -C d push --forceprompt too.AGENTS.md— dropped the "one worktree per agent" section as covered globally; Codex and Gemini don't read that. Keep a line?Verified
prettier --checkon every touched file: clean--force-with-leasedon'tjq empty .claude/settings.json: validgh api repos/jdwlabs/apps/rulesets/<id>: Baseline on main hasnon_fast_forward,pull_request; bypassOrganizationAdmin: always