Repository navigation
docs(agents): restructure agent instructions for OpenCode V2 and current Claude Code - #1844
Merged
Merged
Conversation
…ent Claude Code
Both tools loaded ~27,000 words at every session start: AGENTS.md plus
eight unscoped files under .claude/rules/, the latter via an
`instructions` glob in opencode.jsonc. Vendor guidance for both tools is
a short always-loaded core (commands, non-derivable conventions,
routing), procedures in skills and docs loaded on demand, and
deterministic enforcement for zero-exception rules. The always-loaded
core is now ~1,700 words.
- AGENTS.md rewritten at ~200 lines: commands, the checks outside
`make pre-commit` and their triggers, conventions the code cannot
say, working rules (worktrees, publication, delegation, shell, tool
output, history rewrites, temp files, evidence, issues, tools), a
task-to-document routing table, the verbatim bca metric-feedback
policy block.
- CLAUDE.md and .claude/CLAUDE.md removed. Measured with Claude Code
2.1.317 in fresh `claude -p` sessions: a one-line `@AGENTS.md` shim
expands at the repository root but a session started in a
subdirectory receives only the shim; with no CLAUDE.md the native
AGENTS.md reader loads the full file from either directory. A
personal CLAUDE.local.md starting with `@AGENTS.md` loads both from
the root; .gitignore and AGENTS.md's opening paragraph say so.
- .claude/rules/ removed. Mechanisms condensed into
docs/development/{testing,grammar_dispatch,formatting}.md, with
headings matching every citation in the tree; the shell,
tool-output, history-rewrite and temp-file rules reduced to bullets
in AGENTS.md. Incident narratives dropped.
- docs/development/agent_isolation.md: the worktree / branch /
shared-read-only protocol the fan-out skills follow instead of
Claude-specific `.claude/worktrees/` path detection and mandatory
`isolation: "worktree"` / Serena / model prescriptions. Child prompts
carry the allocation (mode, root, branch, base) and verify against
it; orchestrators list worktrees left behind for the user to remove;
read-only skills report rather than restore a modified file.
- Permission guardrails: `ask` on `git push` / `gh pr create`, `deny`
on `git worktree remove|prune`, in opencode.jsonc and
.claude/settings.json, documented as guardrails against command
spellings rather than enforcement.
- Obsolete surface retired: the bca-check.sh compat wrapper and its
Makefile lint lines and test, the MultiEdit matcher, the book's
OpenCode V1 section and the assertion pinning its GUIDANCE literal.
- CONTRIBUTING.md is now the authoritative gate description; the
AGENTS.md-only gate material (baseline refresh in both directions,
the -merge and rebase --exec recipe, stubtest, bulk-snapshot traps,
role-coverage-observe, lint and grammar-pin rules) moved there.
- Threshold table removed from AGENTS.md and from
DOCS_REPEATING_THE_TABLE; the book copy stays pinned.
- ~170 citations of the deleted rule files and the removed AGENTS.md
sections retargeted across utils/, Rust comments, baselines, skills,
lessons_learned.md, tests/README.md and the book.
Reviewed by astra-review at design, mid-point and final checkpoints,
then by fable-review, astra-review and sol-review over the whole
branch; every finding is incorporated. `make pre-commit` passes.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #1844 +/- ##
==========================================
- Coverage 98.40% 98.39% -0.01%
==========================================
Files 397 397
Lines 121726 121287 -439
Branches 121291 120852 -439
==========================================
- Hits 119781 119342 -439
Misses 1223 1223
Partials 722 722
Flags with carried forward coverage won't be shown. Click here to find out more.
🚀 New features to boost your workflow:
|
dekobon
added a commit
that referenced
this pull request
Nov 9, 2026
PR #1843 (3e1c7e1, 6b15a74, ac7cff4) landed on main at 23:33 on 2026-11-07. PR #1844 (docs/agent-instructions) was cut from b85a3cb, before #1843, never rebased, and squash-merged at 23:50 as ca56098. A squash writes the PR's final tree over main as one commit, so ca56098's diff against its own parent silently reverted every file #1843 touched -- the role rows, checker, getter and metric changes, their tests, the #1828 CHANGELOG and book entries, lesson 117, the role baselines, and the big-code-analysis-output gitlink (5fbe03bf back to d411e605) -- under a title that names only documentation. On main at 784045c, `record R(int A, int B);` and `data class D(val a: Int, ...)` again report nargs 0 with no function space, the bug #1828 was closed for. Re-apply `git diff b85a3cb ac7cff4` onto main. Every code, test and snapshot hunk applied cleanly; CHANGELOG.md and lessons_learned.md conflicted with the entries #1856 added since and were resolved by keeping both (the #1828 lesson is 118, after #1818's 117). The grammar-dispatch hunk is ported to its new home, docs/development/grammar_dispatch.md section 7. .bca-baseline.toml is regenerated with `make self-scan-write-baseline-headroom`; the gitlink returns to 5fbe03bf, which is already on the submodule's origin/main. Verified: `bca check --threshold nargs=5` flags `D::D: nargs = 6`; `Total(params int[] values)` reads 1; `make pre-commit` passes. Fixes #1828
dekobon
added a commit
that referenced
this pull request
Nov 10, 2026
…ads its budget Lessons 119 to 121, each drafted from PR #1862 and the incident before it and checked against the code and the GitHub record: - 119: a grammar whose `extras` holds a named non-comment node (tree-sitter-python's `line_continuation`) passes every `is_named() && kind != Comment` selector; five such sites, one predicate (#1830). - 120: a role-row gate that reads bytes but is declared `gated_by` leaves `TEXT_GATED` false, so the byte-less forwards' compile-time asserts trust the declaration and hand it `&[]`; the chain axis has a behavioural backstop, the byte axis none (#1842, #1863). - 121: a commit whose parent is the current tip can carry the old contents of files the tip changed as its own edit; ancestry says nothing, the PR's own diff does (PR #1844 over PR #1843, #1828). `docs/development/testing.md` gains two subsections under "Fixture shapes that cannot fail": a fixture that intercepts output prints it when the test fails, and two correct outcomes separated by a clock are one flake. The second describes the Claude hook's probe-budget test, which this commit redesigns to match: the fixture's preload wraps `setTimeout` and records the budget `run()` arms after each spawn, so the test asserts a `--version` probe arms 3000 and the analyzer run the override, instead of reading a reason string that a slow digest start flips and a leaked override could hide behind. A leaked override, a leaked override under a 1.2 s digest delay, and a check that stops arming the override each fail it; it passes unmutated in about 80 ms with no stalled probe. Reviewed twice by astra-review; the first draft's claim that a squash merge wrote a stale tree did not survive the record and is retracted in the entry.
dekobon
added a commit
that referenced
this pull request
Nov 10, 2026
…ads its budget Lessons 119 to 121, each drafted from PR #1862 and the incident before it and checked against the code and the GitHub record: - 119: a grammar whose `extras` holds a named non-comment node (tree-sitter-python's `line_continuation`) passes every `is_named() && kind != Comment` selector; five such sites, one predicate (#1830). - 120: a role-row gate that reads bytes but is declared `gated_by` leaves `TEXT_GATED` false, so the byte-less forwards' compile-time asserts trust the declaration and hand it `&[]`; the chain axis has a behavioural backstop, the byte axis none (#1842, #1863). - 121: a commit whose parent is the current tip can carry the old contents of files the tip changed as its own edit; ancestry says nothing, the PR's own diff does (PR #1844 over PR #1843, #1828). `docs/development/testing.md` gains two subsections under "Fixture shapes that cannot fail": a fixture that intercepts output prints it when the test fails, and two correct outcomes separated by a clock are one flake. The second describes the Claude hook's probe-budget test, which this commit redesigns to match: the fixture's preload wraps `setTimeout` and records the budget `run()` arms after each spawn, so the test asserts a `--version` probe arms 3000 and the analyzer run the override, instead of reading a reason string that a slow digest start flips and a leaked override could hide behind. A leaked override, a leaked override under a 1.2 s digest delay, and a check that stops arming the override each fail it; it passes unmutated in about 80 ms with no stalled probe. Reviewed twice by astra-review; the first draft's claim that a squash merge wrote a stale tree did not survive the record and is retracted in the entry.
This branch was previously deployed
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
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.
Summary
Restructures the coding-agent instructions for OpenCode V2 and current Claude Code. Both tools loaded ~27,000 words at every session start (
AGENTS.mdplus eight unscoped files under.claude/rules/); the always-loaded core is now ~1,700 words, with procedures routed to on-demand documents.AGENTS.mdrewritten (~200 lines): commands, the checks outsidemake pre-commitand their triggers, conventions the code cannot say, working rules, a task → document routing table, the verbatimbcametric-feedback policy.CLAUDE.mdremoved. Measured with Claude Code 2.1.317: a one-line@AGENTS.mdshim expands at the repo root but a session started in a subdirectory receives only the shim; with noCLAUDE.mdthe native reader loads the fullAGENTS.mdfrom either directory. TheCLAUDE.local.mdcaveat is documented in.gitignoreandAGENTS.md..claude/rules/removed. Mechanisms condensed intodocs/development/{testing,grammar_dispatch,formatting}.mdwith headings matching every citation in the tree; incident narratives dropped.docs/development/agent_isolation.mdadded: the worktree / branch / shared-read-only protocol the seven fan-out skills now follow instead of Claude-specific.claude/worktrees/detection and mandatoryisolation: "worktree"/ Serena / model prescriptions.opencode.jsoncand.claude/settings.json:askongit push/gh pr create,denyongit worktree remove|prune.bca-check.shcompat wrapper, theMultiEditmatcher, the book's OpenCode V1 section and their tests (CHANGELOG entry included).CONTRIBUTING.mdis now the authoritative gate description.Verification
make pre-commit→BCA_GATE: passon the final commit (rebased onac7cff45), no skipped stages.big-code-analysis-ast/src, report receiving onlyAGENTS.mdand answer gate / routing / push questions correctly; a docs-only control routes to prose conventions with no grammar text inlined.astra-reviewat design, mid-point and final checkpoints, then byfable-review,astra-reviewandsol-reviewover the whole branch; every finding is incorporated.Deferred
Splitting
add-lang,batch-fixandscan-project(900–1,500 lines each) intoSKILL.md+references/per the Agent Skills spec.