Skip to content

fix: stop template skills stating facts about repository-owned files - #101

Merged
bydradev merged 11 commits into
mainfrom
fix/template-skills-tidy
Oct 17, 2026
Merged

bydradev merged 11 commits into
mainfrom
fix/template-skills-tidy

Conversation

@bydradev

@bydradev bydradev commented Oct 16, 2026 •

Copy link
Copy Markdown
Owner

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, 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

  • 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.
  • Tests and docs are updated for the changed behaviour

Prepared with the assistance of Claude Code (Claude Opus 5.5).


Generated by Claude Code

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
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 16, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-17T10:39:29.251633Z 73b8394 New commits
🔒 Security Review ✅ Completed 2026-10-17T10:40:15.838688Z 73b8394 New commits
ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 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

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 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".

claude and others added 4 commits October 16, 2026 14:50
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]>
@bydradev
bydradev merged commit d1e1000 into main Oct 17, 2026
4 checks passed
@bydradev
bydradev deleted the fix/template-skills-tidy branch October 17, 2026 10:39
bydradev added a commit that referenced this pull request Oct 17, 2026
## 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
bydradev pushed a commit that referenced this pull request Oct 17, 2026
🤖 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>
bydradev added a commit that referenced this pull request Oct 26, 2026
…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]>
bydradev added a commit that referenced this pull request Oct 26, 2026
## 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]>
bydradev pushed a commit that referenced this pull request Oct 26, 2026
🤖 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>
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