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
- 参考文档context/apply-recipes.md9.3 KB
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 itsMechanicsfield names, with this run's quote-check result and label (below). - A decline is recorded, not argued. Write
declinedinto 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.
declinedinto the findings artifact. Unchanged, and still the record this branch's run reads.- 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, thereasonin 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
declinedin 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.mdpersonal override: a personal-layer entry the team layer does not carry is reportedpersonal-only, not appliedand 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
driftresult: the record id, its section URL, the stored wording and the fetched one. A finding whoseMechanicsfield 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
Mechanicsfield names, from the record'squotecolumn, with this run's result beside it. - Label what was not read. A finding that relies on an
unverifiedor a drifted record is presented labeled "unverified as of <date>": the date theunverifiedline printed, or for a drifted record itsas_ofin the list. For anunverifiedrecord the operator still decides. - A finding with no
Mechanicsfield 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:
- 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.
- 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. - 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
acceptedand whose source changed is not applied: the acceptance was for text that is gone, so it returns topendingand is presented again. - Version drift. The artifact's
claude_code_versionagainst 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:
-
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.
-
Perform the move: create the destination, then excise the source. In that order, so an interruption leaves content duplicated rather than deleted.
-
Regenerate the index:
"${CLAUDE_PLUGIN_ROOT}/scripts/render-index.sh" write --file <index-file> -
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.
-
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
InstructionsLoadedhook 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 UNKNOWNmeans the probe could not run: that is never a pass, and never grounds for marking the finding applied. -
Record
appliedin 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. ACLAUDE.mdon the file's own path, the repository root's included, is read instead of theAGENTS.mdbeside it, so in a repository that has one, a nestedAGENTS.mdwritten without itsCLAUDE.mdshim silently reaches nothing. That is measured, not inferred. Write the shim whereverrender-index.sh wiringwould report the fileUNWIRED; where it reportsNATIVE, nothing blocks the file and the shim is not what makes it load there, though it stays the cover for sessions that cannot readAGENTS.mdat 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.mdwithout theCLAUDE.mdshim, in a repository whose root carries aCLAUDE.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 theCLAUDE.mdabove 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
declinedstatus 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.blockedthere means "executed elsewhere", and recording it as applied hides work that still needs doing.
04 同仓库更多 Skills
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.
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.
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.
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.
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.
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').