feat(han-experimental): add the han-experimental plugin and review-skill-or-agent#119
Draft
taminomara wants to merge 2 commits into
Draft
feat(han-experimental): add the han-experimental plugin and review-skill-or-agent#119taminomara wants to merge 2 commits into
taminomara wants to merge 2 commits into
Conversation
…ill-or-agent Introduce the opt-in han-experimental plugin carrying review-skill-or-agent: a skill that reviews a finished Claude Code skill or agent against the plugin-authoring guidance and quality dimensions (bloat and restatement first) and produces a severity-ranked, code-review-shaped report. It resolves the target's type, grounds against the type-appropriate guidance (halting when it is absent or incomplete), and dispatches a signal-scaled roster of fresh-context reviewers handed the artifact as untrusted data, then validates the findings with adversarial-validator. Wiring: - register han-experimental in .claude-plugin/marketplace.json (v0.1.0) - describe it in CLAUDE.md (plugin family, repo layout, shipping/deps, index rule) - add its section and skill entry to docs/skills/README.md - add the long-form doc docs/skills/han-experimental/review-skill-or-agent.md Depends on han-core (the reviewer agents it dispatches) and han-plugin-builder (the authoring guidance it grounds against). Opt-in: not bundled by the han meta-plugin. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01L76cznjxv6sCjxk6AYTQNY
Rework Step 3 so the same artifact yields the same reviewer roster and small skills stop drawing specialists they do not need: - Replace the five free-form triage signals with a pinned rubric (references/triage-rubric.md): each signal has a floor that excludes the trivial baseline, plus a fixed per-signal yes/no output format. - Recalibrate the roster gates toward exclusion (information-architect at reference-count >= 2, security default-out, a "fewer is better" tie-break) and resolve the line-84/93 and line-97 contradictions. - Drop the hard-coded haiku model override at the triage dispatch so it inherits the session model (skills pass no model override). - Correct the skill/tool-seam checks to the current context-injection loader model: load-blockers are the refused constructs, unallowlisted pipe/chain stages, and missing non-zero-exit guards, not output size; "| head" is a truncation nit, not a guard. - Fix a self-load hazard: the literal bang-backtick pattern in SKILL.md prose is executed by the loader, so reword it to "bang-backtick". Add a seam checklist item for bang-backtick invocation safety, and keep the long-form doc in sync. Runtime-validated: triage signals stable 5/5 across two targets; lean rosters confirmed; the always-on conformance backstop caught both planted seam defects with the seam reviewer deselected. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MxVNiTYhXQtAoBDy4GRJQw
Collaborator
|
🤔 i need to think about the structure and dependencies a bit... this might be pointing to a more foundational layer than han-core, with a bit more restructure |
mxriverlynn
added a commit
that referenced
this pull request
Jul 14, 2026
## Summary Adds an npm-managed lint and test toolchain, CI, and Dependabot for the han repo. One `npm install` pins every tool locally (no global installs, no cross-project version drift) and installs the git hook via the `prepare` script. - **prek** (`@j178/prek`) runs the pre-commit hooks (drop-in for `pre-commit`). - **Prettier** formats Markdown, JSON, YAML, and JS: 120-column prose wrap, ordered-list numbering preserved, `.github` PR/issue templates unwrapped (GitHub renders newlines as `<br>`), and `docs/plans`, `docs/research`, and the vendored assets excluded. - **ShellCheck** (via `shellcheck-py`, no Docker) lints shell scripts. - The `pre-commit-hooks` hygiene checks cover the rest; their whitespace/EOL fixers exclude md/json/yaml/js so Prettier owns those with no overlap, and `check-yaml`/`check-json` are dropped because Prettier already validates those types. - **Bats** runs `test/*.bats` in CI (not on commit); a sanity test proves the harness. - **CI**: a `lint` job (`npm run lint`) and a `test` job (`npm test`), both on the pinned lockfile. - **Dependabot**: one monthly PR bundling npm + GitHub Actions + pre-commit updates via a multi-ecosystem group, with a 30-day cooldown on new releases to reduce supply-chain risk (security updates are exempt from the cooldown). Mitigates #113 for this repo. Should be merged before #119. ## Note on the `lint` CI job This PR adds the tooling only. Running `npm run lint` reflows the existing Markdown across the repo; that mechanical reflow is intentionally **not** included here, so the `lint` job will report changes until it is applied in a separate pass. The `test` job is green. ## Follow-ups for a maintainer - Run `npm run lint` and commit the repo-wide Prettier reflow (and re-run so the `lint` job goes green). - Resolve two ShellCheck findings, or add `# shellcheck disable` directives: `init-guidance.sh:55` (SC2016) and `upload-screenshots.sh:136` (SC2034). Both look benign. - Fix the broken symlink `.claude/rules/plugin-entity-taxonomy.md` that `check-symlinks` flags. - Enable *Settings → Code security → Dependabot security updates* so security patches bypass the 30-day cooldown. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01KFKuiUmQ9QinkSt9LbE7hc
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a new opt-in plugin,
han-experimental, and its first skill,/review-skill-or-agent. The skill reviews a finished Claude Code skill or agent against thehan-plugin-builderauthoring guidance and a set of quality dimensions, then produces a severity-ranked,code-review-shaped report. Bloat and restatement are first-class corrective findings.The orchestrator never reads the artifact itself. It resolves the target's type and guidance with a deterministic detector script, runs a short
haikutriage, then dispatches a signal-scaled panel of fresh-context reviewers that each read the artifact as untrusted data. It consolidates and de-duplicates the findings, validates them with an adversarial pass, and renders the report from a template. It can halt (returning a "Review Halted" block instead of a report) when the guidance or the target is not reviewable.han-experimentalis opt-in: it depends onhan-core(the reviewer agents it dispatches) andhan-plugin-builder(the guidance it grounds against), and thehanmeta-plugin does not bundle it.Key file changes
han-experimental/.claude-plugin/plugin.json: new plugin manifest (v0.1.0; depends on han-core and han-plugin-builder).han-experimental/skills/review-skill-or-agent/SKILL.md: the skill itself, a seven-step review protocol with roster selection, three reviewer prompt blocks, and a halt procedure.han-experimental/skills/review-skill-or-agent/references/:finding-classification.md(the consequence-class severity spine),bloat-classification.md(bloat tiers and the two-pass process),review-checklist.md(the per-lens checklist), andtemplate.md(the report template).han-experimental/skills/review-skill-or-agent/scripts/:detect-guidance-and-type-context.sh(type and guidance resolution) plus its test suite..claude-plugin/marketplace.json,CLAUDE.md,docs/skills/README.md, and the long-form docdocs/skills/han-experimental/review-skill-or-agent.md.Test Plan
detect-guidance-and-type-context.test.shpasses (48/48)./review-skill-or-agentagainst itself and applied the surviving findings.han-plugin-builderand reportsguidance-complete: true.Results so far:
The skill performs better than a simple invocation of guidance skill with an instruction to review something. It spawns a panel of reviewers, similar to
code-review. Additionally, it has instructions on finding bloat and duplication, which addresses common issues left after building/refactoring skills using LLMs.This skill is work in progress:
Question for @mxriverlynn and other maintainers:
I've put this skill into new
han-experimentalplugin because I didn't want to addhan-coreas dependency ofhan-plugin-builder. Plugin builder can be vendored into other repos; vendoringreview-skill-or-agentwould require vendoring agents fromhan-core. Are we ok with this? If not, are we ok with addinghan-coretohan-plugin-builder's dependencies without vendoring it?Until this is resolved, the skill is fragile: it uses
claude plugin list --jsonto find installation path ofhan-plugin-builderand read guidance, and it depends on output format of--jsonflag, which is not formally specified.🤖 Generated with Claude Code
https://claude.ai/code/session_01L76cznjxv6sCjxk6AYTQNY