AGENT SKILL

realign

Apply an instruction-placement audit's findings behind an explicit per-item human gate. Consumes the audit artifact; never re-judges. Each accepted finding is the whole move. Hard-denied safety content has no path here. Use when: 'apply the placement findings', 'do the migration', 'move those conventions to rules', 'execute finding IP-004', 'realign our instruction layer', 'the audit says move it, do it'. No blanket-approve. Audit proposes; this applies.

License 许可
MIT
最近更新
2026-11-15
Stars
★ 30
Forks
7

01 前言 Front Matter

shell
bash
metadata
{ "summary": "Apply accepted placement findings behind a per-item human gate", "workflow-stage": "implement" }
description
Apply an instruction-placement audit's findings behind an explicit per-item human gate. Consumes the audit artifact; never re-judges. Each accepted finding is the whole move. Hard-denied safety content has no path here. Use when: 'apply the placement findings', 'do the migration', 'move those conventions to rules', 'execute finding IP-004', 'realign our instruction layer', 'the audit says move it, do it'. No blanket-approve. Audit proposes; this applies.
allowed-tools
[ "Bash(${CLAUDE_PLUGIN_ROOT}/scripts/quote-check.sh)", "Bash(${CLAUDE_PLUGIN_ROOT}/scripts/precompute.sh:*)", "Bash(${CLAUDE_PLUGIN_ROOT}/scripts/glob-tools.sh:*)", "Bash(${CLAUDE_PLUGIN_ROOT}/scripts/render-index.sh:*)", "Bash(${CLAUDE_PLUGIN_ROOT}/scripts/verify-load.sh:*)", "Read", "Edit", "Write", "Grep", "Glob" ]
argument-hint
[finding-id ...]
user-invocable
true
disable-model-invocation
false

02 资源文件 1

03 SKILL.md 正文

Arguments. [finding-id ...]. Default: every finding awaiting a decision, in ranked order

Pre-computed context

!"${CLAUDE_PLUGIN_ROOT}/scripts/precompute.sh" realign 2>/dev/null || echo "- Orientation unavailable"

Purpose

Execute what the audit found, one finding at a time, with the operator deciding each one. This is the mutating surface for audit findings (/instruction-placement:migrate is the other mutating skill, and it owns a repository's move to AGENTS.md), and the per-item gate below is the entire reason it is safe to point at a repository nobody has reviewed.

What makes these edits unusual is their target: every file this skill touches is a file that steers the agent's own behavior. A bad code edit fails a test. A bad instruction edit quietly changes what the agent does in every future session, and nothing goes red.

Read these before executing anything

Not restated here. A paraphrase inside a proposal is a drift seed.

Read For
../../context/findings-artifact.md The artifact's location, fields, status vocabulary, merge rules, and the finding-id constituents a suppression entry is keyed by
../../reference/consumer-config.md The suppression surface a decline is recorded on: its layers, its per-key merge, and the offered-never-taken rule
../../context/routing-rubric.md The hard-deny classes and what each destination means
../../context/verified-mechanics.md When the shim is what makes a nested AGENTS.md load, and why the index exists
context/apply-recipes.md The exact edit sequence per destination, and the verification each one owes

The per-item gate

Nothing mutates without an explicit acceptance of that finding, from the operator, at the moment it is presented. Say so in the run's opening line, then hold it literally.

  • One finding, one acceptance. Accepting IP-003 authorizes IP-003 and nothing else, not its neighbors, not the rest of its file, not the obvious next one.
  • Blanket approval is not the gate. "Approve everything", "do whatever the audit says", and a standing authorization from earlier in the session are all declined, out loud, with an offer to walk the findings one at a time. This is not pedantry: the whole value of the gate is that a human looked at each destination, and a blanket yes means nobody did.
  • Present before asking. The source and its line range, the destination, the exact paths: glob with its validated match count, what leaves the always-loaded budget, and the cost: that the content is not inherited by a subagent and announces itself nowhere, and post-compaction behavior for that destination. Then the deciding sentence of each record its Mechanics field names, with this run's quote-check result and label (below).
  • A decline is recorded, not argued. Write declined into the artifact and move on. A declined finding is not re-proposed by a later audit.

Recording a decline so it survives the checkout

The artifact is memory tier: branch-keyed, invisible from every other worktree, and gone with the memory root. A decline written only there is a judgment the next checkout never sees, and the operator is asked again. So a decline has two writes, and the second is what makes it durable.

  1. declined into the findings artifact. Unchanged, and still the record this branch's run reads.
  2. An entry on the tracked suppression surface, ${CLAUDE_PROJECT_DIR}/.claude/instruction-placement.md. Git carries that file to every checkout whose branch holds the commit, which is the only mechanism that crosses checkouts at all.

The entry's five required keys, its finding_id, and the layer rules are owned by the two documents in the table above. Do not invent a format here. Four rules bind the write:

  • Offered, never taken. Show the composed entry in full (check, claim, sites, the reason in the operator's own words, date), and write it only on an explicit yes. Declining a finding and agreeing to never be asked again are two decisions, and the second silences a future report.
  • A reason is required, and it is theirs, not yours. An entry with no stated reason cannot be reviewed or retired later. If the operator gives none, ask once; if they still give none, record declined in the artifact only and say the decline will not survive this checkout.
  • Team layer only. Write ${CLAUDE_PROJECT_DIR}/.claude/instruction-placement.md, never ~/.claude/** and never the .local.md personal override: a personal-layer entry the team layer does not carry is reported personal-only, not applied and suppresses nothing, so writing one would look like recording a decision while recording none.
  • Say that it needs committing. The file is tracked, and an uncommitted entry has reached no other worktree yet. Name that rather than implying the decision is already everywhere.

Check the mechanics quotes first

The audit priced each finding on the docs records its Mechanics field names, and a page can change between that audit and this run. So the first command of a run, before the artifact is read, is:

"${CLAUDE_PLUGIN_ROOT}/scripts/quote-check.sh"

It takes no arguments and fetches only the pages ${CLAUDE_PLUGIN_ROOT}/context/mechanics-sources.tsv lists. It prints one line per record: verified <id>; drift <id> <url>, with the stored and fetched sentences on the next two lines; or unverified <id> as of <date> when the page could not be read fresh. It exits 0 whatever the results, so a run with no network still completes. Its grant names the script with no * (how such a rule matches: https://code.claude.com/docs/en/permissions#wildcard-patterns).

  • Drift goes first. Before the gate opens, list each drift result: the record id, its section URL, the stored wording and the fetched one. A finding whose Mechanics field names a drifted record is not applied on either wording: present it with both wordings and the unverified label below, say that it looks wrong until re-audited, and offer the re-audit.
  • Quote the deciding sentence of each record the finding's Mechanics field names, from the record's quote column, with this run's result beside it.
  • Label what was not read. A finding that relies on an unverified or a drifted record is presented labeled "unverified as of <date>": the date the unverified line printed, or for a drifted record its as_of in the list. For an unverified record the operator still decides.
  • A finding with no Mechanics field came from an audit that predates the check. Say so when it is presented and offer a re-audit. Leave its records unnamed: naming them here would re-judge it.

Prerequisites

Read the artifact from the home findings-artifact.md "Where it lives" defines.

If it is absent, say no audit has been run for this branch and offer to run one. Do not fall back to another path or another branch's artifact: findings cite line ranges, and a range derived elsewhere points at different text here. Name such a file a leftover and run a fresh audit instead.

Then, before the first finding is presented, resolve .claude/instruction-placement.md across its three layers and drop every finding the merged surface covers, reporting each as suppressed with its reason, date, and contributing layer. Match on the finding_id the artifact's Suppression key already carries; do not derive one here. This skill has no detector stream, and a second derivation is a second heading parse whose disagreement produces a decline nothing ever matches.

The ordering is the point, and the case it protects is ordinary. This checkout's artifact is memory tier: whatever the last local audit left behind, knowing nothing about a decline another checkout recorded and committed since, which arrives here when that commit does. Present first and consult the surface later, and the operator is asked to re-judge what their team already settled, which is the rubber-stamping this gate exists to prevent. A suppressed finding is never presented, never accepted, never applied.

Then four checks before the first edit, because acting on a stale artifact edits the wrong lines:

  1. Suppression sweep. The step above has run and its suppressed set is reported. A finding that reaches the gate unswept is a question the team already answered.
  2. Branch match. The artifact's branch: frontmatter against the current branch. On a mismatch, stop and re-audit. The directory a file sits in never proves which branch it describes.
  3. Source drift. For each finding, that the cited content still exists at the cited location. Content that moved is re-audited, not guessed at. A finding whose status is accepted and whose source changed is not applied: the acceptance was for text that is gone, so it returns to pending and is presented again.
  4. Version drift. The artifact's claude_code_version against the running one. On a material difference, re-verify the mechanics before trusting destination choices that depend on them.

Execution

Per accepted finding, in ranked order, following the recipe for its destination:

  1. Re-validate the glob immediately before writing it. The repository may have changed since the audit, and a glob that now matches nothing must not be committed.

  2. Perform the move: create the destination, then excise the source. In that order, so an interruption leaves content duplicated rather than deleted.

  3. Regenerate the index:

    "${CLAUDE_PLUGIN_ROOT}/scripts/render-index.sh" write --file <index-file>
    
  4. Verify statically: the destination file's frontmatter parses, its glob resolves, the index is in sync and its target is reachable, and the source no longer carries the moved content.

  5. Verify empirically when the operator wants proof, or when the destination is one you are unsure of:

    "${CLAUDE_PLUGIN_ROOT}/scripts/verify-load.sh" \
      --trigger <a file the new surface covers> --expect <the new surface>
    

    This drives the real CLI with an InstructionsLoaded hook and reports what actually loaded, the only check in this plugin that observes Claude Code rather than reasoning about it, and the one that catches a surface passing every static gate while never entering context. It costs a model call, so it earns its place on the first move of a migration and on anything unusual, not on every finding. VERDICT UNKNOWN means the probe could not run: that is never a pass, and never grounds for marking the finding applied.

  6. Record applied in the artifact, with the destination path.

One finding is one reviewable unit of work. Do not batch several findings into one edit sweep even when they share a destination file. A reviewer needs to see which change came from which accepted proposal.

Hard rules

  • No blanket approval, ever. Not on request, not for a batch, not for "the trivial ones". That covers suppression entries too: a standing "and never ask me about any of these again" is declined the same way, with an offer to compose one entry at a time.
  • Hard-denied content is not applicable. The held-back section carries no destination and there is no code path that gives it one. If the operator asks for one, explain the class and offer compression in place. This is the one place where the operator's instruction does not carry.
  • Never re-judge the surface. This skill executes classifications the audit made; it does not reclassify, discover new candidates, or improve a destination it thinks the audit got wrong. If a finding looks wrong, say so and stop. The fix is a re-audit, not an improvised alternative.
  • Never rewrite content while moving it. The move is a relocation. Tightening prose during a relocation makes the diff unreviewable and smuggles an unapproved edit past the gate.
  • The shim is what carries a blocked AGENTS.md. A CLAUDE.md on the file's own path, the repository root's included, is read instead of the AGENTS.md beside it, so in a repository that has one, a nested AGENTS.md written without its CLAUDE.md shim silently reaches nothing. That is measured, not inferred. Write the shim wherever render-index.sh wiring would report the file UNWIRED; where it reports NATIVE, nothing blocks the file and the shim is not what makes it load there, though it stays the cover for sessions that cannot read AGENTS.md at all.
  • Never leave the index stale. Regenerating it is part of the move, not a follow-up. An un-indexed demotion is exactly the subagent gap this plugin exists to close.
  • Stop on a failed verification. Report what failed and leave the finding blocked. Do not proceed to the next finding on a broken tree.

Spoke paths

The context/ files write the plugin's root directory as <plugin-root>, which is ${CLAUDE_PLUGIN_ROOT}. Put that path in place of the placeholder before running a command or writing it into a brief. Those files arrive through the Read tool as plain bytes, so a ${…} token in them would reach the Bash tool unsubstituted, and the Bash tool's environment has no CLAUDE_PLUGIN_ROOT to expand it from. Basis: the plugins reference, https://code.claude.com/docs/en/plugins/manifest-reference#where-each-variable-resolves.

Gotchas

Observed failure modes. Every one leaves a repository that looks migrated and is not.

  • Writing the nested AGENTS.md without the CLAUDE.md shim, in a repository whose root carries a CLAUDE.md. The most likely mistake in this whole plugin, because the result reviews as correct: a well-written conventions file, in the right directory, that Claude Code never loads, because the CLAUDE.md above it is read instead. Measured, not inferred.
  • Forgetting the index regeneration. The move succeeds, the rule fires when Claude works with a file its glob covers (which tool calls count, by version: ../../context/verified-mechanics.md), and nothing tells any agent the rule exists until then. In a delegation-heavy repo a worker briefed to create or change files under that glob can act before the rule arrives. The index is part of the move, not a follow-up task.
  • Excising before creating. An interruption between the two then deletes the only copy. The ordering is not stylistic; it is the difference between a recoverable and an unrecoverable failure.
  • Tightening prose "while you're in there". It makes the diff unreviewable and slips an edit past the gate the operator thought they were approving. Relocate verbatim.
  • Treating a run-level "yes, all good" as acceptance. An operator who has skimmed the findings has not gated each destination. The gate is per item because the value is per item.
  • Acting on line numbers from an artifact written before the file changed. Excising a stale line range removes the wrong content, and the audit's own record then describes something that never happened. The staleness checks run before the first edit for this reason.
  • Re-proposing a declined finding. A declined status is a decision, not a gap to be filled on the next run. Resurrecting it trains the operator to stop reading carefully, which is how a per-item gate degrades into a rubber stamp.
  • Marking a report-only rung applied. A linter or skill routing has no destination this skill builds. blocked there means "executed elsewhere", and recording it as applied hides work that still needs doing.

04 同仓库更多 Skills

melodic-software
melodic-software/claude-code-plugins

track

Backlog reads through the bound tracker: search open and closed items, view one item with its comments and state history. Use when another skill searches or reads tracker items.

★ 30
melodic-software
melodic-software/claude-code-plugins

reviewer-media

Reviewer media for one pull request: decides whether it needs a narrated walkthrough, builds the storyboard from /review:explain-change's digest, has /explainer-video:produce render it and hands the manifest to /source-control:pull-request media. Use when asked for 'reviewer media', 'a walkthrough video for this PR', 'a produced video of this change', or when pull-request ready or monitor hands a PR over.

★ 30
melodic-software
melodic-software/claude-code-plugins

route

Model and effort per agent role (orchestrator, worker, verifier, retrieval) for a multi-agent run, resolved through the bundled defaults and the user, team and personal override config layers into fenced JSON with single-agent and fan-out variants and the layer behind each value. Use when asked 'which model for the subagents', 'route the roles' or 'model routing', or before a skill passes a role's model on a spawn.

★ 30
melodic-software
melodic-software/claude-code-plugins

route

Model and effort per agent role (orchestrator, worker, verifier, retrieval) for a multi-agent run, resolved through the bundled defaults and the user, team and personal override config layers into fenced JSON with single-agent and fan-out variants and the layer behind each value. Use when asked 'which model for the subagents', 'route the roles' or 'model routing', or before a skill passes a role's model on a spawn.

★ 30
melodic-software
melodic-software/claude-code-plugins

principles

Module-design vocabulary for architecture findings, and the checks built on it. Use when: 'what is a deep module', 'what is a seam', 'deep vs shallow module', 'what is the deletion test', 'leverage and locality', 'module design vocabulary', 'which word do we use for X in architecture findings'. Scanning a codebase for friction is /architecture:improve.

★ 30
melodic-software
melodic-software/claude-code-plugins

write

Structured five-field bug report (title, steps to reproduce, expected vs actual, justified severity, suggested fix location) from an informal description, read-only. Use when the user names a defect they observed, or asks for one written up ('report a bug', 'file a bug', 'write this up as a bug').

★ 30