Repository navigation
fix: stop template skills stating facts about repository-owned files - #101
Conversation
Each local-validation-<type> skill now starts by routing to a repository-owned validation skill named in `## Project specifics`, and describes CI tiers, test configuration, formatter scope and Playwright retries as generated, naming the repository file to check. The Next.js skill says when the `next dev` descriptor limit applies (any command that starts `next dev`, including a dev-mode Playwright webServer). Inline "checked ..." citations in agent-facing skill text move to a Sources list at the end of each skill, keeping source and date. The indexing and crawler rules move out of local-validation-nextjs into a new Next.js-only template skill, public-site-indexing. It has no row in the hub's skills table, to keep the Next.js hub within its budget; local-validation-nextjs points at it, and validate_templates.py accepts that through SKILLS_WITHOUT_HUB_ROW. --adopt writes it and its .claude/skills mirror as missing in an existing Next.js repository. pull-requests defines which Co-Authored-By trailers apply (a commit an AI tool materially wrote or changed; merging a change you did not write, such as a Dependabot PR, adds none), uses a placeholder trailer, states the squash-message rule independently of `gh`, and gives blocked pull requests their own heading as a pointer. fresh-eyes-review escalates to the operator after three review rounds with blocking findings still open. verify-external-claims drops three sentences the hub already carries. baseline-process is a short list with the same content. The OpenCode reviewer agent is read-only by configuration: it denies edits, launching subagents, and every shell command except git diff, git log and git show without --output (last matching rule wins). Sources: https://opencode.ai/docs/permissions/ and https://opencode.ai/docs/agents/, checked 2026-10-16. Claude Code has no subagent setting that limits Bash to read-only commands in every permission mode: a disallowedTools entry with a specifier removes the whole tool, and a subagent's permissionMode is ignored under auto, acceptEdits or bypassPermissions. Its reviewer keeps no write tools and now says to use Bash only for read-only commands. Sources: https://code.claude.com/docs/en/sub-agents and https://code.claude.com/docs/en/permission-modes, checked 2026-10-16. The validator pins both. The bootstrapper's own stamped copies under .agents/skills, .claude/agents and .opencode/agents are re-rendered from the `simple` render. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_01SKkexZrY4mpV3wbUybSnkN
The OpenCode fresh-eyes reviewer allowed "git diff*", "git log*" and "git show*", which also admit `git difftool` and a redirect such as `git log > notes`. Its shell rules are now "*": deny; "git diff *", "git log *" and "git show *": allow; then "*--output*" and "*>*": deny. A trailing " *" matches the bare command or the command followed by a space, so difftool stays denied, and the last matching rule wins. The validator allows only those three commands, alone or followed by " *", requires both deny rules last, and requires the reviewer's body to state its shell rule, with self-tests for a redirect-permitting rule set, a "git diff*" prefix, an allow after the closing denies, and a missing body rule. These rules narrow the shell but do not make it read-only, and the README now says so. OpenCode matches each command of a shell line separately and drops a redirect on the last command of a && list or a pipeline, so `git diff && git log > notes` still runs. And `git diff /dev/null .env` prints an untracked .env, which OpenCode's default read rules deny, because git implies --no-index for a path outside the work tree. The message and README of de52984 wrongly said Claude Code has no subagent setting that limits Bash to read-only commands in every permission mode. A subagent's frontmatter can carry a PreToolUse hook that runs a script before each Bash command. The README and the validator comment now say why the Claude Code reviewer still relies on its instruction: the template would have to ship an executable script, and Claude Code skips a project-level subagent's frontmatter hooks until the folder's workspace trust is accepted, where "a `-p` session doesn't count as trusted", which is how the cross-family review recipe runs Claude Code. Also from the review: the pull-requests skill defers the trailer format to AGENTS.md and names merge_pull_request's merge_method and commit_message; the Python skill says CI installs requirements-dev.txt if present, otherwise requirements.txt; the Swift skill points at the full input that the template-owned release-please.yml passes to test.yml; the Next.js skill gives `ulimit -n 10240 && npx playwright test` as an example; the validator reports a skill without a hub row whose parent has none either, with a self-test; and the adopt test also brings a stale stamped local-validation-nextjs up to date alongside the missing public-site-indexing skill. Sources, checked 2026-10-16: - OpenCode v1.19.3, the npm opencode-ai latest release: packages/core/src/util/wildcard.ts, packages/opencode/src/tool/shell.ts and packages/opencode/src/permission/index.ts; the matching was reproduced with the web-tree-sitter 0.25.10 and tree-sitter-bash 0.25.0 it pins. - OpenCode dev: packages/core/test/shell-scan/redirect.test.ts, where "printf ok && git status > output" yields "printf ok" and "git status". - opencode.ai/docs/permissions: the last matching rule wins, and .env files are denied to read by default. - code.claude.com/docs/en/sub-agents: frontmatter hooks and workspace trust. - git-scm.com/docs/git-diff: --no-index may be omitted when a path points outside the working tree; reproduced with git 2.43.0. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_01SKkexZrY4mpV3wbUybSnkN
The OpenCode fresh-eyes reviewer now sets `bash: deny` alongside `edit: deny` and `task: deny`, so it is read-only by permission. Its body says it has no shell and reviews the diff and validation results the implementer hands it, reading files with the read tools; the fresh-eyes-review recipe now also saves the validation results. This replaces the git allow-list of the two earlier commits on this branch, whose messages claimed more than the rules did. de52984 called the reviewer read-only by configuration, and dd88bb4 said its rules narrowed the shell to git diff, log and show. In OpenCode v1.19.3 the shell check sees only each command node, and shell.ts keeps a redirect only when it sits directly on one command, so `git diff && git log > notes`, `git diff || git log > notes`, `{ git log; } > notes` and `(git log) > notes` all pass; `cd`, `pushd` and `popd` produce no pattern, and a scan with no patterns skips the check; and git is not in the set of commands whose paths are checked against external_directory. With `bash: deny` as the agent's last bash rule, Permission.disabled hides the shell tool instead. validate_templates.py requires `bash: deny`, drops the allow-pattern and body shell-rule checks, and rejects any permission key besides edit, task and bash, since OpenCode matches keys as wildcards and a later key such as "*" could reopen them. Self-tests cover a bash allow rule and a later top-level "*": allow. The Claude Code reviewer text no longer says a hook would need an executable script file. Claude Code skips a project subagent's frontmatter hooks in a folder whose trust dialog was never accepted, and "a `-p` session doesn't count as trusted"; such a hook would also have to parse shell commands, which the OpenCode case shows is hard to do completely. So that reviewer stays read-only by instruction. Sources, checked 2026-10-16: - OpenCode v1.19.3, the npm opencode-ai latest release: packages/opencode/src/tool/shell.ts, packages/opencode/src/tool/shell/id.ts, packages/opencode/src/permission/index.ts (evaluate, disabled) and packages/opencode/src/agent/agent.ts (agent rules merge last). - code.claude.com/docs/en/sub-agents and code.claude.com/docs/en/permissions: frontmatter hooks and workspace trust. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_01SKkexZrY4mpV3wbUybSnkN
The OpenCode reviewer has no built-in edit, subagent or shell tool, but e122063 and the README called it read-only by permission. Every permission it does not set falls through to OpenCode's default "*": allow, and MCP tools ask under their own tool name, so MCP, plugin and custom tools follow the user's OpenCode configuration. The README and the validator comment now say that. The validator now accepts only the OpenCode reviewer frontmatter keys the template uses (description, mode, permission). The deprecated `tools` map is turned into permission keys placed before `permission`'s own, so `tools: {bash: false, "*": true}` would have ended with "*": allow and reopened the shell without a validator error. Self-tests cover that map and an unknown key. The reviewer body says its read tools ask before reading most paths outside the project, such as a diff saved to a scratch directory, as OpenCode pre-allows only its own temporary directory. The README no longer says the cross-family recipe runs `claude -p` as the reviewer subagent; it says Claude Code skips a project subagent's frontmatter hooks in a folder whose trust dialog was never accepted, such as a clone where it has only run as `claude -p`, so whether a hook runs would depend on the folder. Each local-validation skill's routing sentence to a repository-owned validation skill is now pinned, with a self-test per type. The adopt test customises ci.yml, test.yml and `## Project specifics` and checks they are byte-identical after adopt. Sources, checked 2026-10-16: OpenCode v1.19.3, the npm opencode-ai latest release: packages/core/src/v1/config/agent.ts (normalize), packages/opencode/src/agent/agent.ts (defaults), packages/opencode/src/session/tools.ts (MCP tool permission); code.claude.com/docs/en/permissions (workspace trust). Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_01SKkexZrY4mpV3wbUybSnkN
The validator now rejects frontmatter that gives a key twice or has a line starting with --- before its closing line. OpenCode's gray-matter with js-yaml 3 throws on a duplicate key and then loads the agent with no frontmatter, and ends the frontmatter at the first line starting with ---, so either would load the reviewer with its shell open while PyYAML passed it. The README says neither reviewer gets a built-in edit tool. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_01SKkexZrY4mpV3wbUybSnkN
OpenCode reads frontmatter with gray-matter and js-yaml 3, which still differ from PyYAML on merge keys, key types and Unicode line breaks after the duplicate-key and early-delimiter checks, and several of those differences load the reviewer with no frontmatter and its shell open. Rather than model each one, the validator now requires the reviewer's frontmatter to be a plain one-line description followed by exactly its mode and three deny lines. Self tests cover a U+2028 line break and a merge key. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_01SKkexZrY4mpV3wbUybSnkN
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: e37b200c24
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
OpenCode's free-tier models on its own provider reject an agent whose shell is denied with "OpenCode's free tier can only be used from within OpenCode" (anomalyco/opencode#50627, open on 2026-10-16). The fresh-eyes-review skill now tells agents to run the reviewer with another model or use another reviewer rather than loosen its permissions, and the README says why bash: ask or a narrow allow rule is no fix: a command that yields no pattern skips the shell check. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_01SKkexZrY4mpV3wbUybSnkN
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 098f72ed5c
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
public-site-indexing told every Next.js repository to set AI crawler policy in the hosting platform's bot controls, which a self-hosted or static site may not have. It now keeps the policy in one place: the host's bot controls when it has them, otherwise per-bot rules in robots.ts. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_01SKkexZrY4mpV3wbUybSnkN
The pinned frontmatter still let the description carry YAML syntax. A
tag or flow mapping there, such as `!!bool yes` or `{1, "1"}`, passes
PyYAML but makes js-yaml 3 throw. gray-matter caches the failed parse,
OpenCode's sanitized retry hits that cache, and the reviewer loads with
no frontmatter, so with its shell open (gray-matter 4.0.3 index.js,
js-yaml 3.14.2 loader.js, OpenCode v1.19.3 config/markdown.ts, read
2026-10-16).
The description must now start with a letter, so neither parser reads
it as a number, and PyYAML must read it back as exactly its own text,
so no tag, quote, anchor, flow mapping or comment changes it. Each
guard has a self-test fixture that fails without it.
Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
Claude-Session: https://claude.ai/code/session_01SKkexZrY4mpV3wbUybSnkN
The indexing skill told agents to allow all crawlers and then to keep per-bot AI crawler rules in robots.ts, which read as a contradiction. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_01SKkexZrY4mpV3wbUybSnkN
Keep screenshot review conditional while generating public-site-indexing for every Next.js configuration. Preserve the configuration-aware ownership and mirror helpers, and document both features in the skill table. Co-Authored-By: Codex (GPT-6) <[email protected]>
## What changes `validate_templates.py` now checks this repository's own agent files against what `bootstrap.py` would generate for it. A new `check_own_template_copies` covers: - the five general skills and their `.claude/skills` links; - both fresh-eyes reviewer agents; - `CLAUDE.md`; - `AGENTS.md` above `## Project specifics`. It compares them with the repository's `--type simple` render through `bootstrap.compare_repository`, the same comparison `./bootstrap.py --check . --type simple` makes. Any status other than `same` fails: - an edited, stale, missing or unstamped copy; - a wrong, missing or dangling link; - a stamped skill the render no longer has, or one of another repository type; - a name collision; - an edited generated hub section. Edits under `## Project specifics` stay the repository's own and pass, and so does a repository-owned skill not named like a template skill. Each error says how to refresh the copy. A missing, stale or unstamped copy, an edited copy or a link points to `./bootstrap.py --adopt . --type simple`, and a retired copy is to be deleted. When a directory or other non-file sits where a copy belongs, which `compare_repository` reports as missing, the hint says to move it aside first, since the adopt run cannot write over it. That adopt run also stamps `pr-title-check.yml` and refuses this repository's own `release-please.yml`, so the hint and the README say to commit only the agent files it changes. `_frontmatter` now reports frontmatter PyYAML cannot load as a validation error. SafeLoader raises plain Python exceptions, not a `YAMLError`, for many malformed values (`!!bool Use` a `KeyError`, `!!int ""` an `IndexError`, a 180-part base-60 `!!float` an `OverflowError`, deep nesting a `RecursionError`), so it catches any exception from the load and reports it with the `YAMLError` wording, "has invalid YAML frontmatter", followed by the exception type. Before, the validator stopped with a traceback; it failed either way, so nothing unsafe passed. ## Why Only the branch-protection runbook copy was compared with its template. Editing this repository's copy of a template skill, or setting `bash: allow` in its OpenCode reviewer, passed every check (call 10 of the template PR summary, raised in the fourth review of #101). Dra approved this as a follow-up after #101 merged. Every copy matches today, so nothing in the repository changes. ## How it was checked All AGENTS.md "Tooling" checks on this branch, on `main` at `50dcffa`: - `validate_templates.py`: 19 configurations validated, 135 self-test fixtures behaved as expected, no errors (also run on Python 3.11, the CI floor) - pytest: 227 passed, 4 skipped (environmental), 495 subtests passed; `tests/test_validator_wiring.py` also passes on Python 3.11 - `node --test templates/*.test.mjs`: 57 of 57 passed - prettier and eslint on `templates/*.mjs`: clean - markdownlint on the rendered Markdown (278 files) and on the repository Markdown (15 files): 0 issues New self-tests build a copy of the render in a temporary directory. They check that it passes and that an edited Project specifics passes. They check that each of these fails: - an edited, stale, missing, unstamped or retired skill, and another type's template skill; - a directory where `CLAUDE.md` belongs, with the move-aside hint; - an edited Claude reviewer, and the OpenCode reviewer with `bash: allow`; - an edited hub section and an edited `CLAUDE.md`; - a moved, missing or dangling link. A table test in `tests/test_validator_wiring.py` fails for every status other than `same` in every covered path, listed by hand, and checks that files outside the agent files are not reported. Another runs `main()` from a different directory and checks that it compares the validator's own directory. Frontmatter fixtures cover each exception type above and match on the shared wording, so they hold whichever way a PyYAML release raises. Mutation testing turned the run red each time: skipping any one status (`shadowed`, `symlink`, `ignored`, `other-type`, `unreadable`, `dangling`, `orphaned`, `missing`, `differs`, `stale`), dropping `.claude/agents/`, `.claude/skills/` or `AGENTS.md` from the scope, narrowing the `except` back to a list, treating a load error as no problem, removing the unstamped-skill hint, dropping or always giving the move-aside hint, or comparing the working directory instead of the validator's. `tests/test_validator_wiring.py` lists the new check, so dropping its call from `main()` fails too. On this repository, I planted each of these and the validator caught it: `bash: allow`, an edited skill, a template-only edit (stale copy), an edited hub section, a removed link, a wrong link target and a colliding skill name. In a scratch clone, the hinted adopt run refreshed stale and missing copies and the hub, and the check then passed; following the unstamped-skill hint restored the skill byte for byte, and following the move-aside hint for a directory at `CLAUDE.md` restored it, and the check passed. Four independent reviews ran. The first found three nits, fixed in the second commit: a hint that pointed a name collision at the template, the adopt side effects, and two link cases without a self-test. The second, on 2026-10-17, found three more, fixed in the third commit: frontmatter inputs that still crashed the validator, a bare `shadowed` result with no restore hint, and statuses and the `.claude/agents/` folder that no self-test covered. The third reviewed that commit, confirmed the broad `except` cannot turn a failure into a pass, and found one nit, fixed in the fourth: the fixtures named PyYAML's exception classes. The fourth found the missing hint for a directory at a copy's path and an untested validator root, both fixed in the fifth commit. ## Checklist - [x] The title is a Conventional Commit subject, and the pull request makes one change - [ ] Every commit is signed off (`git commit -s`; see CONTRIBUTING.md). The commits carry no AI sign-off, because a sign-off certifies the DCO personally; the maintainer signs off if needed. - [x] Tests and docs are updated for the changed behaviour https://claude.ai/code/session_01SKkexZrY4mpV3wbUybSnkN --- *Prepared with the assistance of Claude Code (Claude Opus 5.5).* Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_01SKkexZrY4mpV3wbUybSnkN
🤖 I have created a release *beep* *boop* --- ## [0.12.0](v0.11.1...v0.12.0) (2026-10-17) ### Features * add a public-site-indexing skill for Next.js repositories ([d1e1000](d1e1000)) * add an autonomy and escalation section to the generated agents.md ([#97](#97)) ([54c394c](54c394c)) * generate docs/current-work.md for dated repository status ([54c394c](54c394c)) * generate the screenshot-review skill only with --screenshots ([#100](#100)) ([311f98b](311f98b)) ### Bug Fixes * count a screenshot file with a damaged stamp as the template's copy ([#103](#103)) ([bd0d116](bd0d116)) * remove the OpenCode reviewer's built-in edit, subagent and shell tools ([d1e1000](d1e1000)) * remove unedited older-template guidance from project specifics on adopt ([54c394c](54c394c)) * rewrite the branch-protection runbook as a short procedure ([#99](#99)) ([50dcffa](50dcffa)) * skip the release with a warning when release please credentials are missing ([#98](#98)) ([f0763b8](f0763b8)) * stop template skills stating facts about repository-owned files ([#101](#101)) ([d1e1000](d1e1000)) --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please). Co-authored-by: bydraio-release-please[bot] <299493734+bydraio-release-please[bot]@users.noreply.github.com>
…101) ## What changes Template skills stop stating facts about files a generated repository owns, and the OpenCode fresh-eyes reviewer loses its built-in edit, subagent and shell tools. - Each `local-validation-<type>` skill first loads a repository-owned validation skill named in `## Project specifics`, which governs where it is narrower. It then describes CI tiers, test configuration and formatter scope as generated and names the repository file to check. Inline source dates move to a Sources list at the end of each skill. The validator pins the routing sentence in each of these skills. - Next.js: the indexing and crawler rules move to a new `public-site-indexing` skill, which `local-validation-nextjs` points at. It has no row in the hub's skills table, so the hub does not grow. `--adopt` writes it and its `.claude/skills` mirror into an existing repository and leaves repository-owned files untouched. `local-validation-nextjs` says when the `next dev` descriptor limit applies, for example `ulimit -n 10240 && npx playwright test`. - Python: CI installs `requirements-dev.txt` if present, otherwise `requirements.txt`. Swift: the tiers also point at the `full` input the template-owned `release-please.yml` passes to `test.yml`. - `pull-requests`: a `Co-Authored-By:` trailer belongs to a commit an AI tool materially wrote or changed and is named as `AGENTS.md` specifies; merging a change you did not write adds none. The squash-message rule covers `gh` and the GitHub MCP server's `merge_pull_request` (`merge_method: squash`, the message as `commit_message`), and blocked pull requests get a pointer section. - `fresh-eyes-review` escalates to the operator after three rounds with blocking findings open, and its cross-family recipe also saves the validation results. `verify-external-claims` drops three sentences the hub already carries. `baseline-process` becomes a short list with the same content. - Reviewer agents: - The OpenCode reviewer sets `edit`, `task` and `bash` to `deny`, so it has no built-in edit, subagent or shell tool. MCP, plugin and custom tools still follow the user's OpenCode configuration, whose default allows them. - It reviews the diff and validation results it is handed, and its read tools ask before reading most paths outside the project. - OpenCode's free-tier models on its own provider currently refuse an agent whose shell is denied ([anomalyco/opencode#50627](anomalyco/opencode#50627), open). So `fresh-eyes-review` and the README say to run that reviewer with another model or use another reviewer, not to loosen its permissions. - The Claude Code reviewer keeps `Read, Grep, Glob, Bash`, and its file now says to use Bash only for read-only commands. - Validator: it requires both reviewers' settings. It pins the OpenCode reviewer's frontmatter line for line: a one-line description that starts with a letter and reads back as its own text, then `mode: subagent` and the three deny lines. For every frontmatter, skills included, it rejects a duplicate key or a line starting with `---` before the closing one. feat: add a public-site-indexing skill for Next.js repositories fix: remove the OpenCode reviewer's built-in edit, subagent and shell tools ## Why The skills stated CI tiers, test configuration and formatter scope as facts, but a generated repository owns those files and changes them, so the skills went stale in exactly the repositories that customised them. The OpenCode reviewer could write through its shell, and no allow-list fixes that. In OpenCode v1.19.3 the shell check sees each command separately and keeps a redirect only when it sits directly on one command. So `git diff && git log > notes`, `{ git log; } > notes` and `(git log) > notes` pass a `git log` allow rule. A `cd` or a bare `> path` produces no pattern and skips the check. git's paths are never checked against `external_directory`. `bash: deny` hides the shell tool instead. The free-tier workarounds in the upstream issue, `bash: ask` or a narrow allow rule, make the shell visible again, so they would reopen those writes. The frontmatter is pinned because OpenCode reads it with gray-matter 4.0.3 and js-yaml 3, not PyYAML. Several differences load the agent with no frontmatter at all, so with mode `all` and the default `"*": allow`: a duplicate key, a line starting with `---`, a merge key, a Unicode line break, keys that are distinct to PyYAML but equal as strings, or a tag js-yaml cannot resolve, such as `!!bool yes`. The deprecated `tools` map also becomes permission keys placed before `permission`'s own. Pinning the exact lines closes all of these rather than modelling each one. Claude Code could filter a subagent's Bash with a `PreToolUse` frontmatter hook, but it skips a project subagent's frontmatter hooks in a folder whose workspace trust dialog was never accepted, such as a clone where it has only run as `claude -p`. Whether such a hook runs would depend on the folder, and it would have to parse shell commands, which the OpenCode case shows is hard to do completely. So that reviewer stays read-only by instruction. The branch's earlier commit messages describe OpenCode rule sets that were not read-only and overstate what `bash: deny` achieves, and de52984 wrongly says Claude Code has no subagent setting that can limit Bash. This description is the accurate one. Sources, checked 2026-10-16: OpenCode v1.19.3, the current npm release (`packages/opencode/src/tool/shell.ts`, `tool/shell/id.ts`, `permission/index.ts`, `agent/agent.ts`, `session/tools.ts`, `packages/core/src/v1/config/agent.ts` and `packages/core/src/config/markdown.ts`); anomalyco/opencode#50627; gray-matter 4.0.3 and js-yaml 3.14.2 from npm; https://code.claude.com/docs/en/sub-agents; https://code.claude.com/docs/en/permissions; the `github/github-mcp-server` README. ## How it was checked - `validate_templates.py`: 11 configurations, 98 self-test fixtures, no errors. Fixtures cover: - an OpenCode bash allow rule, `bash: allow`, and a later top-level `"*": allow`; - a `tools: {bash: false, "*": true}` map and an unknown frontmatter key; - a duplicate key, an early `---` line, a U+2028 line break and a merge key in the frontmatter; - a tagged, non-ASCII, numeric or commented description; - a skill without a hub row whose parent skill does not name it or has no row either; - a Claude Code reviewer without its Bash rule. - Per-type self-tests fail when a local-validation skill drops its routing sentence. - Reverting each new frontmatter check makes its self-test fail. - pytest: 200 passed, 4 skipped (filesystem and root-permission conditions), 326 subtests passed. The adopt test brings a stale stamped `local-validation-nextjs` up to date and writes the missing `public-site-indexing` skill and mirror, while customised `ci.yml`, `test.yml` and `## Project specifics` stay byte-identical. - `node --test templates/*.test.mjs`: 57 passed; prettier and eslint clean. - markdownlint: rendered generated Markdown (155 files) and the repository's own Markdown (14 files), 0 issues. - OpenCode v1.19.3's shell matching reproduced with the web-tree-sitter 0.25.10 and tree-sitter-bash 0.25.0 it pins, confirming the bypasses above. - An independent fresh-eyes review ran three rounds. Each round's blocking findings are fixed: the overstated "read-only" claim, the `tools` map, then the frontmatter parser differences. The commit e37b200 pins the frontmatter after round 3. A fourth round, which the maintainer asked for, found that a tag or flow mapping in the description still got past the pin; 09498cd closes that, and removing any one of its guards makes a self-test fail. ## Checklist - [x] The title is a Conventional Commit subject, and the pull request makes one change. The two extra entries above are changelog lines. - [ ] Every commit is signed off (`git commit -s`; see CONTRIBUTING.md). The commits carry no AI sign-off, because a sign-off certifies the DCO personally; the maintainer signs off if needed. - [x] Tests and docs are updated for the changed behaviour --- *Prepared with the assistance of Claude Code (Claude Opus 5.5).* Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> Co-Authored-By: Codex (GPT-6) <[email protected]>
## What changes `validate_templates.py` now checks this repository's own agent files against what `bootstrap.py` would generate for it. A new `check_own_template_copies` covers: - the five general skills and their `.claude/skills` links; - both fresh-eyes reviewer agents; - `CLAUDE.md`; - `AGENTS.md` above `## Project specifics`. It compares them with the repository's `--type simple` render through `bootstrap.compare_repository`, the same comparison `./bootstrap.py --check . --type simple` makes. Any status other than `same` fails: - an edited, stale, missing or unstamped copy; - a wrong, missing or dangling link; - a stamped skill the render no longer has, or one of another repository type; - a name collision; - an edited generated hub section. Edits under `## Project specifics` stay the repository's own and pass, and so does a repository-owned skill not named like a template skill. Each error says how to refresh the copy. A missing, stale or unstamped copy, an edited copy or a link points to `./bootstrap.py --adopt . --type simple`, and a retired copy is to be deleted. When a directory or other non-file sits where a copy belongs, which `compare_repository` reports as missing, the hint says to move it aside first, since the adopt run cannot write over it. That adopt run also stamps `pr-title-check.yml` and refuses this repository's own `release-please.yml`, so the hint and the README say to commit only the agent files it changes. `_frontmatter` now reports frontmatter PyYAML cannot load as a validation error. SafeLoader raises plain Python exceptions, not a `YAMLError`, for many malformed values (`!!bool Use` a `KeyError`, `!!int ""` an `IndexError`, a 180-part base-60 `!!float` an `OverflowError`, deep nesting a `RecursionError`), so it catches any exception from the load and reports it with the `YAMLError` wording, "has invalid YAML frontmatter", followed by the exception type. Before, the validator stopped with a traceback; it failed either way, so nothing unsafe passed. ## Why Only the branch-protection runbook copy was compared with its template. Editing this repository's copy of a template skill, or setting `bash: allow` in its OpenCode reviewer, passed every check (call 10 of the template PR summary, raised in the fourth review of #101). Dra approved this as a follow-up after #101 merged. Every copy matches today, so nothing in the repository changes. ## How it was checked All AGENTS.md "Tooling" checks on this branch, on `main` at `ced2b21`: - `validate_templates.py`: 19 configurations validated, 135 self-test fixtures behaved as expected, no errors (also run on Python 3.11, the CI floor) - pytest: 227 passed, 4 skipped (environmental), 495 subtests passed; `tests/test_validator_wiring.py` also passes on Python 3.11 - `node --test templates/*.test.mjs`: 57 of 57 passed - prettier and eslint on `templates/*.mjs`: clean - markdownlint on the rendered Markdown (278 files) and on the repository Markdown (15 files): 0 issues New self-tests build a copy of the render in a temporary directory. They check that it passes and that an edited Project specifics passes. They check that each of these fails: - an edited, stale, missing, unstamped or retired skill, and another type's template skill; - a directory where `CLAUDE.md` belongs, with the move-aside hint; - an edited Claude reviewer, and the OpenCode reviewer with `bash: allow`; - an edited hub section and an edited `CLAUDE.md`; - a moved, missing or dangling link. A table test in `tests/test_validator_wiring.py` fails for every status other than `same` in every covered path, listed by hand, and checks that files outside the agent files are not reported. Another runs `main()` from a different directory and checks that it compares the validator's own directory. Frontmatter fixtures cover each exception type above and match on the shared wording, so they hold whichever way a PyYAML release raises. Mutation testing turned the run red each time: skipping any one status (`shadowed`, `symlink`, `ignored`, `other-type`, `unreadable`, `dangling`, `orphaned`, `missing`, `differs`, `stale`), dropping `.claude/agents/`, `.claude/skills/` or `AGENTS.md` from the scope, narrowing the `except` back to a list, treating a load error as no problem, removing the unstamped-skill hint, dropping or always giving the move-aside hint, or comparing the working directory instead of the validator's. `tests/test_validator_wiring.py` lists the new check, so dropping its call from `main()` fails too. On this repository, I planted each of these and the validator caught it: `bash: allow`, an edited skill, a template-only edit (stale copy), an edited hub section, a removed link, a wrong link target and a colliding skill name. In a scratch clone, the hinted adopt run refreshed stale and missing copies and the hub, and the check then passed; following the unstamped-skill hint restored the skill byte for byte, and following the move-aside hint for a directory at `CLAUDE.md` restored it, and the check passed. Four independent reviews ran. The first found three nits, fixed in the second commit: a hint that pointed a name collision at the template, the adopt side effects, and two link cases without a self-test. The second, on 2026-10-17, found three more, fixed in the third commit: frontmatter inputs that still crashed the validator, a bare `shadowed` result with no restore hint, and statuses and the `.claude/agents/` folder that no self-test covered. The third reviewed that commit, confirmed the broad `except` cannot turn a failure into a pass, and found one nit, fixed in the fourth: the fixtures named PyYAML's exception classes. The fourth found the missing hint for a directory at a copy's path and an untested validator root, both fixed in the fifth commit. ## Checklist - [x] The title is a Conventional Commit subject, and the pull request makes one change - [ ] Every commit is signed off (`git commit -s`; see CONTRIBUTING.md). The commits carry no AI sign-off, because a sign-off certifies the DCO personally; the maintainer signs off if needed. - [x] Tests and docs are updated for the changed behaviour --- *Prepared with the assistance of Claude Code (Claude Opus 5.5).* Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
🤖 I have created a release *beep* *boop* --- ## [0.12.0](v0.11.1...v0.12.0) (2026-10-17) ### Features * add a public-site-indexing skill for Next.js repositories ([54994c4](54994c4)) * add an autonomy and escalation section to the generated agents.md ([#97](#97)) ([abae5e2](abae5e2)) * generate docs/current-work.md for dated repository status ([abae5e2](abae5e2)) * generate the screenshot-review skill only with --screenshots ([#100](#100)) ([f7a6d76](f7a6d76)) ### Bug Fixes * count a screenshot file with a damaged stamp as the template's copy ([#103](#103)) ([bef1a90](bef1a90)) * remove the OpenCode reviewer's built-in edit, subagent and shell tools ([54994c4](54994c4)) * remove unedited older-template guidance from project specifics on adopt ([abae5e2](abae5e2)) * rewrite the branch-protection runbook as a short procedure ([#99](#99)) ([ced2b21](ced2b21)) * skip the release with a warning when release please credentials are missing ([#98](#98)) ([d2b7d82](d2b7d82)) * stop template skills stating facts about repository-owned files ([#101](#101)) ([54994c4](54994c4)) --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please). Co-authored-by: bydraio-release-please[bot] <299493734+bydraio-release-please[bot]@users.noreply.github.com>
What changes
Template skills stop stating facts about files a generated repository owns, and the OpenCode fresh-eyes reviewer loses its built-in edit, subagent and shell tools.
local-validation-<type>skill first loads a repository-owned validation skill named in## Project specifics, which governs where it is narrower. It then describes CI tiers, test configuration and formatter scope as generated and names the repository file to check. Inline source dates move to a Sources list at the end of each skill. The validator pins the routing sentence in each of these skills.public-site-indexingskill, whichlocal-validation-nextjspoints at. It has no row in the hub's skills table, so the hub does not grow.--adoptwrites it and its.claude/skillsmirror into an existing repository and leaves repository-owned files untouched.local-validation-nextjssays when thenext devdescriptor limit applies, for exampleulimit -n 10240 && npx playwright test.requirements-dev.txtif present, otherwiserequirements.txt. Swift: the tiers also point at thefullinput the template-ownedrelease-please.ymlpasses totest.yml.pull-requests: aCo-Authored-By:trailer belongs to a commit an AI tool materially wrote or changed and is named asAGENTS.mdspecifies; merging a change you did not write adds none. The squash-message rule coversghand the GitHub MCP server'smerge_pull_request(merge_method: squash, the message ascommit_message), and blocked pull requests get a pointer section.fresh-eyes-reviewescalates to the operator after three rounds with blocking findings open, and its cross-family recipe also saves the validation results.verify-external-claimsdrops three sentences the hub already carries.baseline-processbecomes a short list with the same content.edit,taskandbashtodeny, so it has no built-in edit, subagent or shell tool. MCP, plugin and custom tools still follow the user's OpenCode configuration, whose default allows them.fresh-eyes-reviewand the README say to run that reviewer with another model or use another reviewer, not to loosen its permissions.Read, Grep, Glob, Bash, and its file now says to use Bash only for read-only commands.mode: subagentand the three deny lines. For every frontmatter, skills included, it rejects a duplicate key or a line starting with---before the closing one.feat: add a public-site-indexing skill for Next.js repositories
fix: remove the OpenCode reviewer's built-in edit, subagent and shell tools
Why
The skills stated CI tiers, test configuration and formatter scope as facts, but a generated repository owns those files and changes them, so the skills went stale in exactly the repositories that customised them.
The OpenCode reviewer could write through its shell, and no allow-list fixes that. In OpenCode v1.19.3 the shell check sees each command separately and keeps a redirect only when it sits directly on one command. So
git diff && git log > notes,{ git log; } > notesand(git log) > notespass agit logallow rule. Acdor a bare> pathproduces no pattern and skips the check. git's paths are never checked againstexternal_directory.bash: denyhides the shell tool instead. The free-tier workarounds in the upstream issue,bash: askor a narrow allow rule, make the shell visible again, so they would reopen those writes.The frontmatter is pinned because OpenCode reads it with gray-matter 4.0.3 and js-yaml 3, not PyYAML. Several differences load the agent with no frontmatter at all, so with mode
alland the default"*": allow: a duplicate key, a line starting with---, a merge key, a Unicode line break, keys that are distinct to PyYAML but equal as strings, or a tag js-yaml cannot resolve, such as!!bool yes. The deprecatedtoolsmap also becomes permission keys placed beforepermission's own. Pinning the exact lines closes all of these rather than modelling each one.Claude Code could filter a subagent's Bash with a
PreToolUsefrontmatter hook, but it skips a project subagent's frontmatter hooks in a folder whose workspace trust dialog was never accepted, such as a clone where it has only run asclaude -p. Whether such a hook runs would depend on the folder, and it would have to parse shell commands, which the OpenCode case shows is hard to do completely. So that reviewer stays read-only by instruction.The branch's earlier commit messages describe OpenCode rule sets that were not read-only and overstate what
bash: denyachieves, and de52984 wrongly says Claude Code has no subagent setting that can limit Bash. This description is the accurate one.Sources, checked 2026-10-16: OpenCode v1.19.3, the current npm release (
packages/opencode/src/tool/shell.ts,tool/shell/id.ts,permission/index.ts,agent/agent.ts,session/tools.ts,packages/core/src/v1/config/agent.tsandpackages/core/src/config/markdown.ts); anomalyco/opencode#50627; gray-matter 4.0.3 and js-yaml 3.14.2 from npm; https://code.claude.com/docs/en/sub-agents; https://code.claude.com/docs/en/permissions; thegithub/github-mcp-serverREADME.How it was checked
validate_templates.py: 11 configurations, 98 self-test fixtures, no errors. Fixtures cover:bash: allow, and a later top-level"*": allow;tools: {bash: false, "*": true}map and an unknown frontmatter key;---line, a U+2028 line break and a merge key in the frontmatter;local-validation-nextjsup to date and writes the missingpublic-site-indexingskill and mirror, while customisedci.yml,test.ymland## Project specificsstay byte-identical.node --test templates/*.test.mjs: 57 passed; prettier and eslint clean.toolsmap, then the frontmatter parser differences. The commit e37b200 pins the frontmatter after round 3. A fourth round, which the maintainer asked for, found that a tag or flow mapping in the description still got past the pin; 09498cd closes that, and removing any one of its guards makes a self-test fail.Checklist
git commit -s; see CONTRIBUTING.md). The commits carry no AI sign-off, because a sign-off certifies the DCO personally; the maintainer signs off if needed.Prepared with the assistance of Claude Code (Claude Opus 5.5).
Generated by Claude Code