Skip to content

docs(agents): restructure agent instructions for OpenCode V2 and current Claude Code - #1844

Merged
dekobon merged 1 commit into
mainfrom
docs/agent-instructions
Nov 7, 2026
Merged

dekobon merged 1 commit into
mainfrom
docs/agent-instructions

Conversation

@dekobon

@dekobon dekobon commented Nov 7, 2026

Copy link
Copy Markdown
Owner

Summary

Restructures the coding-agent instructions for OpenCode V2 and current Claude Code. Both tools loaded ~27,000 words at every session start (AGENTS.md plus eight unscoped files under .claude/rules/); the always-loaded core is now ~1,700 words, with procedures routed to on-demand documents.

  • AGENTS.md rewritten (~200 lines): commands, the checks outside make pre-commit and their triggers, conventions the code cannot say, working rules, a task → document routing table, the verbatim bca metric-feedback policy.
  • CLAUDE.md removed. Measured with Claude Code 2.1.317: a one-line @AGENTS.md shim expands at the repo root but a session started in a subdirectory receives only the shim; with no CLAUDE.md the native reader loads the full AGENTS.md from either directory. The CLAUDE.local.md caveat is documented in .gitignore and AGENTS.md.
  • .claude/rules/ removed. Mechanisms condensed into docs/development/{testing,grammar_dispatch,formatting}.md with headings matching every citation in the tree; incident narratives dropped.
  • docs/development/agent_isolation.md added: the worktree / branch / shared-read-only protocol the seven fan-out skills now follow instead of Claude-specific .claude/worktrees/ detection and mandatory isolation: "worktree" / Serena / model prescriptions.
  • Permission guardrails in opencode.jsonc and .claude/settings.json: ask on git push / gh pr create, deny on git worktree remove|prune.
  • Obsolete surface retired: bca-check.sh compat wrapper, the MultiEdit matcher, the book's OpenCode V1 section and their tests (CHANGELOG entry included).
  • CONTRIBUTING.md is now the authoritative gate description.
  • ~170 citations retargeted; zero stale references to deleted files or renamed sections.

Verification

  • make pre-commit → BCA_GATE: pass on the final commit (rebased on ac7cff45), no skipped stages.
  • Fresh OpenCode 2.1.3 and Claude Code 2.1.317 sessions in the worktree, from the root and from big-code-analysis-ast/src, report receiving only AGENTS.md and answer gate / routing / push questions correctly; a docs-only control routes to prose conventions with no grammar text inlined.
  • 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.

Deferred

Splitting add-lang, batch-fix and scan-project (900–1,500 lines each) into SKILL.md + references/ per the Agent Skills spec.

…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

codecov Bot commented Nov 7, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.39%. Comparing base (ac7cff4) to head (ca56098).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

Impacted file tree graph

@@            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              
Flag Coverage Δ
python 100.00% <ø> (ø)
rust 98.39% <100.00%> (-0.01%) ⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines Coverage Δ
big-code-analysis-ast/src/c_declarator.rs 100.00% <ø> (ø)
big-code-analysis-ast/src/cfg_predicate.rs 99.32% <ø> (ø)
big-code-analysis-ast/src/checker.rs 96.79% <ø> (ø)
big-code-analysis-ast/src/checker/csharp.rs 100.00% <100.00%> (ø)
big-code-analysis-ast/src/checker/objc.rs 100.00% <ø> (ø)
big-code-analysis-ast/src/count.rs 89.91% <ø> (ø)
big-code-analysis-ast/src/getter.rs 95.65% <ø> (-0.06%) ⬇️
big-code-analysis-ast/src/getter/csharp.rs 100.00% <ø> (ø)
big-code-analysis-ast/src/getter/kotlin.rs 95.61% <ø> (-0.12%) ⬇️
big-code-analysis-ast/src/lang_helpers/ruby.rs 100.00% <ø> (ø)
... and 41 more
🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@dekobon
dekobon merged commit ca56098 into main Nov 7, 2026
64 checks passed
@dekobon
dekobon deleted the docs/agent-instructions branch November 7, 2026 23:50
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

1 inactive deployment
github-pages — ca56098d Deployed Nov 7, 2026 by dekobon via deploy to GitHub Pages #1005
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.

1 participant