Skip to content

fix(hooks,init): exec-form hooks, AGENTS.md target, discovery-stats root fallback, docs-check refresh - #77

Merged
slbug merged 5 commits into
mainfrom
adopt-changelog
Oct 1, 2026
Merged

slbug merged 5 commits into
mainfrom
adopt-changelog

Conversation

@slbug

@slbug slbug commented Oct 1, 2026

Copy link
Copy Markdown
Owner

No description provided.

@slbug slbug self-assigned this Oct 1, 2026
@slbug
slbug requested a balanced review from Copilot October 1, 2026 05:24

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Copilot review overview

🟡 Changes recommended

The new AGENTS.md workflows mishandle symlink updates and mixed migration/repair states.

Review effort: Balanced
Findings: 1 High severity · 1 Medium severity

Open (2)
What changed in this PR

Updates plugin compatibility with current Claude Code behavior and adds AGENTS.md initialization support.

Changes:

  • Converts hooks to exec form and refreshes documentation guidance.
  • Adds AGENTS.md targeting, migration, and version checks.
  • Fixes discovery-stats root detection and adds tests.
File Description
scripts/​fetch-claude-docs.sh Adds current plugin documentation pages.
README.md Updates /rb:init guidance.
plugins/​ruby-grape-rails/​skills/​intro/​SKILL.md Refreshes onboarding recommendations.
plugins/​ruby-grape-rails/​skills/​intro/​references/​tutorial-content.md Documents current commands and AGENTS.md.
plugins/​ruby-grape-rails/​skills/​init/​SKILL.md Adds AGENTS.md target and migration rules.
plugins/​ruby-grape-rails/​hooks/​scripts/​check-plugin-version.sh Checks and migrates AGENTS.md blocks.
plugins/​ruby-grape-rails/​hooks/​hooks.json Converts script hooks to exec form.
plugins/​ruby-grape-rails/​bin/​discovery-stats Adds plugin-root fallback.
plugins/​ruby-grape-rails/​.claude-plugin/​plugin.json Bumps plugin version.
package.json Bumps package version.
package-lock.json Updates lockfile metadata and dependencies.
lab/​eval/​tests/​test_runtime_scripts.py Tests exec hooks and AGENTS.md handling.
lab/​eval/​tests/​test_discovery_stats.py Tests discovery root resolution.
CHANGELOG.md Documents release 1.16.19.
.github/​instructions/​plugin-review.instructions.md Refreshes plugin-agent field guidance.
.github/​instructions/​markdown-review.instructions.md Updates schema and hook guidance.
.github/​instructions/​hooks-review.instructions.md Establishes exec-form review rules.
.claude/​skills/​docs-check/​SKILL.md Updates authoritative documentation mapping.
.claude/​skills/​docs-check/​references/​validation-rules.md Refreshes supported schema rules.
.claude/​skills/​docs-check/​references/​doc-pages.md Updates cached-page inventory.
.claude/​rules/​hook-development.md Documents exec-form hooks.
.claude/​rules/​eval-workflow.md Updates plugin-agent cache guidance.
.claude/​agents/​docs-surface-validator.md Updates documentation sources.
.claude-plugin/​marketplace.json Bumps marketplace version and ref.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

@slbug
slbug requested a balanced review from Copilot October 1, 2026 05:46

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Copilot review overview

🔵 Needs a closer look

Target-selection edge cases and conflicting documentation guidance remain unresolved.

Review effort: Balanced
Findings: None

Resolved since last review (2)
Previously missed (3)

In code that hasn't changed since last review

Medium severity Handle present but unusable CLAUDE.md before fallback

plugins/​ruby-grape-rails/​skills/​init/​SKILL.md:154

The table defines CLAUDE.md as writable only when usable, but a present read-only file, directory, or unrelated symlink misses the first three rows and falls through to CLAUDE.md; with a usable AGENTS.md, the preceding row also offers that invalid target. Add an explicit stop row for a present unusable CLAUDE.md before either fallback.

Low severity Add experimental.cacheTtl to the valid-agent list

.github/​instructions/​markdown-review.instructions.md:46

The refreshed plugin-agent rules now recognize experimental.cacheTtl in plugin-review.instructions.md:29 and the docs-check rules, but this file's exhaustive valid-agent list still omits it. Both instruction files apply to plugins/**/agents/*.md, so reviewers receive contradictory guidance. Add the field here as well.

Low severity Document the symlink exception for usable AGENTS.md

plugins/​ruby-grape-rails/​skills/​intro/​references/​tutorial-content.md:265

This description omits the new symlink exception: the init contract targets a usable AGENTS.md without prompting when CLAUDE.md symlinks to it. As written, the tutorial promises a prompt in that supported state and disagrees with skills/init/SKILL.md:152 and the changelog.

@slbug
slbug requested a balanced review from Copilot October 1, 2026 05:58

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Copilot review overview

🔵 Needs a closer look

The initialization fallback can suppress an existing unusable AGENTS.md, and review guidance and regression tests remain inconsistent.

Review effort: Balanced
Findings: None

Previously missed (4)

In code that hasn't changed since last review

Medium severity Require args for interpreter-only hooks

lab/​eval/​tests/​test_runtime_scripts.py:397

This test allows an interpreter-only hook ("command": "bash" or "ruby" with no args) to pass, even though such a hook would run no registered script. Assert that known interpreters always have an args array before continuing past shell-form commands.

Medium severity Avoid CLAUDE.md fallback when unusable AGENTS.md exists

plugins/​ruby-grape-rails/​skills/​init/​SKILL.md:155

This fallback still creates CLAUDE.md when AGENTS.md exists but is read-only or a symlink. That immediately stops Claude Code from loading the existing AGENTS.md, which is the behavior this change is intended to avoid. Stop when AGENTS.md is present but unusable and no CLAUDE.md already exists.

Low severity Update review rules for newly documented skill frontmatter fields

.claude/​skills/​docs-check/​references/​validation-rules.md:128

This expands the documented skill frontmatter set, but .github/instructions/markdown-review.instructions.md:29-35 still defines the valid set without background, metadata, license, or compatibility. Update that review rule in the same PR (while retaining the explicit repo bans for when_to_use and plugin-scope paths) so reviewers do not report these newly documented fields as invalid.

Low severity Rewrite feature summaries as imperative actions

plugins/​ruby-grape-rails/​skills/​intro/​references/​tutorial-content.md:446

Rewrite this shipped reference as direct actions. These descriptive feature summaries load into agent context and violate the repository's imperative-only convention for plugin Markdown.

@slbug
slbug requested a balanced review from Copilot October 1, 2026 07:01

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Copilot review overview

🔵 Needs a closer look

The initialization matrix can place or retain managed content in AGENTS.md when Claude Code will not load that file.

Review effort: Balanced
Findings: None

Previously missed (3)

In code that hasn't changed since last review

Medium severity Migrate hidden AGENTS.md blocks to CLAUDE.md

plugins/​ruby-grape-rails/​hooks/​scripts/​check-plugin-version.sh:165

This assumes an AGENTS.md block remains valid beside CLAUDE.md, but Claude Code stops loading AGENTS.md once a regular CLAUDE.md appears. Consequently the hook stays silent for a now-hidden managed block, and /rb:init --update leaves it hidden. Detect this state and direct migration to CLAUDE.md or require an explicit @AGENTS.md import.

Medium severity Target CLAUDE.md when Claude memory files exist

plugins/​ruby-grape-rails/​skills/​init/​SKILL.md:155

This row can send the managed block to AGENTS.md even when CLAUDE.md or an unusable-but-present CLAUDE.local.md exists, although the loading rule below says either file prevents Claude Code from reading AGENTS.md. The install then succeeds but its stack notes never load. Offer AGENTS.md only when neither Claude memory file exists; otherwise target CLAUDE.md.

This issue also appears on line 189 of the same file.

Low severity Resolve conflict over prompting during --update migration

plugins/​ruby-grape-rails/​skills/​init/​SKILL.md:188

This prompt conflicts with the section contract at line 175, which says --update migration is “automatic, no prompt.” The agent receives mutually exclusive instructions. Either remove the no-prompt guarantee or define a deterministic file to retain.

@slbug
slbug requested a balanced review from Copilot October 1, 2026 07:15

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Copilot review overview

🟢 Approval recommended

The implementation, tests, documentation, and release metadata are consistent with the updated contracts.

Review effort: Balanced
Findings: None

@slbug
slbug merged commit 7c7cb22 into main Oct 1, 2026
3 checks passed
@slbug
slbug deleted the adopt-changelog branch October 1, 2026 08:08
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