@shadowclone/cli 0.0.17 → 0.0.19

package/skills/research-primary-sources/SKILL.md

@@ -1,33 +1,51 @@
 ---
 name: research-primary-sources
-description: Resolve a technical implementation question against authoritative first-party evidence. Use when behavior depends on a library, platform, protocol, standard, or tool that may have changed.
+description: 'Use when a decision depends on how a library, platform, protocol, or tool behaves, and that behavior can change by version. Also use it when the user says "check the docs", "is this still true?", or "what does the spec say?". Finds the first-party source for the installed version and reads it. Separates what the source guarantees from what you infer. Not for debugging a failure in your own code (use `diagnose-before-editing`).'
 metadata:
   shadowclone-category: research
   shadowclone-section: workflow
-  shadowclone-applies-when: resolving an implementation question that depends on external facts
+  shadowclone-applies-when: when a decision depends on facts outside the repository
 ---
 # Research Primary Sources
 
 ## Use when
 
-An implementation decision depends on external facts or behavior that varies by version.
+A decision depends on outside facts about a library, a platform, a protocol, a standard, or a tool. Those facts change with versions, and memory or a search snippet can be out of date.
+
+## Gates
+
+1. Is the question specific enough to have one answer?
+2. Did you record the installed version, the runtime, and the platform that the answer must match?
+3. Did you read the first-party source itself, such as the specification, the official documents, the source code, or the release notes?
+4. Does each claim say whether the source guarantees it or you infer it?
+5. If no source answers the question, did you say so and keep the choice easy to reverse?
 
 ## Process
 
-1. State the decision as an answerable question. Record the project's relevant version, runtime, platform, and constraints.
-2. Find the specification, official documentation, implementation, release note, or first-party issue that defines the behavior.
-3. Open the exact source and check its version and date. Trace consequential claims back from summaries.
-4. Compare the evidence with the installed version and code path. Explain disagreements caused by different environments or versions.
-5. Give the conclusion with direct supporting links and the implementation constraint it creates.
+1. Write the decision as a question. Record the version, the runtime, the platform, and the limits that apply.
+2. Find the source that defines the behavior. Prefer the specification, the official documents, the source code, a release note, or a first-party issue.
+3. Open the exact page or file. Check that its version and date match yours.
+4. Compare the source with the installed code. Explain each difference that comes from a version or an environment.
+5. Write the answer, the link or `file:line` for each claim, and the limit that it puts on the change.
 
-## Guardrails
+## Example
 
-Search snippets are leads; read the underlying source. Distinguish documented guarantees from inferences and identify the observations supporting an inference.
+**Situation:** A change must know which instruction file a coding agent reads when two files exist in one folder.
+**Easy route:** Answer from memory: "it reads both".
+**Hidden cost:** If memory is wrong, an install can write a file that hides a file of the team, and nobody notices.
+**Best route:** Open the official documents for the installed version, find the section about file order, and quote it.
+**Evidence:** The documents said that the agent reads the override file first, and reads at most one file in each folder. The install now stops before it writes a file that hides another one.
 
-Quote sparingly and keep credentials, private URLs, and captured user data out of research notes. If authoritative evidence is unavailable, state the unknown and contain it behind a reversible implementation choice.
+## Guardrails
 
-## Completion
+- A search result is a lead. Read the source that it points to.
+- Quote only the lines that support the decision.
+- Keep credentials, private links, and user data out of research notes.
+- If the evidence is old, say so, and name the version that it covers.
 
-The question has a supported answer or an explicit unknown, and the resulting constraint is clear enough to implement.
+## Completion
 
-Report the answer or the explicit unknown, each claim with its primary source (a link, or a file path and line), and the constraint it puts on the change. Keep the reply to these facts. When a pull request exists, put full command output in its verification section instead of the reply.
+- The answer, or the exact unknown.
+- Each claim with its source: a link, or a `file:line`.
+- The version that each source covers.
+- The limit that the answer puts on the change.

package/skills/resolve-conflicts-by-intent/SKILL.md

@@ -1,34 +1,53 @@
 ---
 name: resolve-conflicts-by-intent
-description: Resolve an in-progress merge or rebase by tracing each conflicting change to its original intent and validating the combined behavior. Use when Git reports conflicted files.
+description: 'Use when Git reports conflicts during a merge, a rebase, or a cherry-pick. Also use it when the user says "fix the merge conflicts", "rebase onto main", or "the merge broke the build". Traces each side of a conflict to the change that it came from. Keeps both intents when they fit together, and asks when they do not. Then runs the checks on the combined result. Not for choosing what a new behavior should be (use `choose-by-consequence`).'
 metadata:
   shadowclone-category: version-control
   shadowclone-section: workflow
-  shadowclone-applies-when: resolving an in-progress merge or rebase conflict
+  shadowclone-applies-when: while a merge, rebase, or cherry-pick has conflicts
 ---
 # Resolve Conflicts by Intent
 
 ## Use when
 
-A merge or rebase is in progress and Git reports conflicts.
+A merge, a rebase, or a cherry-pick stops with conflicted files. Each side of a conflict carries an intent. A correct resolution keeps each intent that still applies.
+
+## Gates
+
+1. For each conflicted file, can you name the commit and the intent behind each side?
+2. Does the resolution keep both intents when they fit together?
+3. When the intents do not fit together, did you ask the user instead of picking one?
+4. Did you check related names and code outside the conflict markers?
+5. Do the checks pass on the combined result, and did you separate failures that were already on a parent?
+6. Are all conflict markers gone, with no file left unmerged?
 
 ## Process
 
-1. Inspect the operation, conflicting paths, and commits being combined.
-2. Read surrounding code and the commits, design records, tests, or review discussions explaining each side.
-3. Identify both intended behaviors. Preserve compatible requirements; ask about incompatible outcomes when the merge goal does not settle them.
-4. Resolve each hunk in the current architecture. Check related names and assumptions outside Git's conflict markers.
-5. Run focused checks and the repository's merge gate. Separate new failures from failures present on either parent.
-6. Stage resolutions and finish the authorized operation. Review the combined diff against both original intents.
+1. Read the operation in progress, the conflicted paths, and the commits on each side.
+2. For each side, read the commit message, the tests, and the design notes that explain it.
+3. Resolve each conflict in the current design. Keep the compatible parts of both sides.
+4. Search the rest of the code for names and assumptions that either side changed.
+5. Run the focused checks and the required merge check.
+6. Read the combined diff against both intents, then finish the operation that the user asked for.
 
-## Guardrails
+## Example
 
-Use whole-file ours or theirs only when that entire side is intentionally obsolete. Keep schema changes, migrations, generated artifacts, and tests coherent. Rename and delete conflicts can change behavior.
+**Situation:** A rebase conflicts in a lock file. One side adds a package, and the other side updates a different package.
+**Easy route:** Take one whole side of the lock file, because a tool writes it.
+**Hidden cost:** One change is lost. The build passes on a machine that still has the old cache, and it fails for everyone else.
+**Best route:** Take the lock file from the base branch. Apply the package change from the other side again, and run the install so that the tool writes the lock file.
+**Evidence:** The new lock file has both packages. A clean install and the full check passed.
 
-Avoid introducing an unrelated third design. Remove all conflict markers and preserve unrelated user edits. Follow the repository's approval requirements for Git operations.
+## Guardrails
 
-## Completion
+- Take a whole side of a file only when nobody wants that side any more.
+- Keep schema changes, migrations, generated files, and tests consistent with each other.
+- Treat rename and delete conflicts as behavior changes.
+- Do not add a third design that neither side asked for.
+- Keep unrelated edits of the user, and follow the approval rules of the repository for Git operations.
 
-No unmerged paths remain, compatible requirements survive, checks cover the combined behavior, and the authorized operation is finished.
+## Completion
 
-Report each conflicted file with the intent kept from each side, the check that covers the combined behavior with its result, and the operation you finished. Keep the reply to these facts. When a pull request exists, put full command output in its verification section instead of the reply.
+- Each conflicted file, with the intent that you kept from each side.
+- The check that covers the combined behavior, with its result line.
+- The operation that you finished, and the final commit hash.

package/skills/scope-confirmed-changes/SKILL.md

@@ -1,33 +1,63 @@
 ---
 name: scope-confirmed-changes
-description: Keep a bug fix or review correction tied to reachable behavior and the requested outcome. Use when addressing defects, reviewer findings, or a request for a minimal focused change.
+description: 'Use when fixing a bug, a regression, or a confirmed review finding. Also use it when the user says "fix this bug", "it is broken", or "keep the change small". Reproduces the issue before any fix, with a test, a real command, or the real interface. After the fix, the same reproduction must pass. Keeps the change to confirmed, reachable behavior. Not for checking review comments before a fix (use `verify-review-findings`).'
 metadata:
   shadowclone-category: change-control
   shadowclone-section: workflow
-  shadowclone-applies-when: fixing a defect or addressing review feedback
+  shadowclone-applies-when: when fixing a bug, a regression, or a confirmed review finding
+  shadowclone-voice: "true"
 ---
 # Scope Confirmed Changes
 
 ## Use when
 
-Fixing a defect or review finding, or making a change whose scope should stay narrow.
+You fix a bug, a regression, or a review finding that you confirmed. Only a reproduction proves that a bug is real. Only the same reproduction after the fix proves that the fix works.
+
+## Gates
+
+1. Did you reproduce the issue before you changed code, with a test, a real command, or the real interface?
+2. After the fix, does the same reproduction show the expected result?
+3. If you could not reproduce the issue, did you label the cause as inferred, with the data and code that support it?
+4. Does each changed line serve the fix, or a test or check that the fix needs?
+5. Do all checks that passed before your change still pass?
+6. If an approach caused a new regression, did you remove it instead of adding a second fix on top?
 
 ## Process
 
-1. State the reachable input and incorrect behavior, or the requested outcome.
-2. Trace the current path and verify the finding against the working branch.
-3. Keep edits that correct the outcome, plus supporting changes required for correctness or verification.
-4. Leave unrelated cleanup and speculative guards outside the diff.
-5. Verify the behavior through a stable public interface and map each final hunk back to the request.
+Write in the user's voice. Before you write, read `~/.agents/voice.md`. If it does not exist, build it once from the user's merged pull requests, review comments, and commit messages. Use only text that the user wrote, and name those sources in your handoff. Never overwrite an existing or linked `voice.md`.
 
-## Guardrails
+1. Write the issue as a concrete input, the wrong result, and the expected result.
+2. Reproduce it in the cheapest way that shows the real symptom:
+   - a failing unit or integration test,
+   - the real command in a temporary home, or
+   - the real interface, such as browser or desktop automation when the host has it.
+3. Keep the reproduction and its wrong output, because you run it again after the fix.
+4. Find the cause in the code that the reproduction runs. Fix it at the boundary that owns it.
+5. Run the same reproduction. It must now show the expected result.
+6. Run the focused tests and the required check of the repository.
+7. Read the diff. Remove each line that does not serve the fix or its proof.
+8. If reproduction is impossible, say why. Reason from logs, data, and code, and label the conclusion as inferred.
 
-Preserve unrelated user edits and existing style. Do not widen a public contract to accommodate an internal shortcut. Refactor only when the requested fix or its verification needs it.
+## Example
 
-If an approach causes another regression, remove that approach and reconsider the cause. Avoid layering compensating changes onto a wrong fix. Keep later review rounds in separate commits when authorized; never rewrite pushed history.
+**Situation:** A user reports that `sync` lost an edit to an installed skill. All unit tests pass.
+**Easy route:** Read the code, guess that the copy check is wrong, and change it.
+**Hidden cost:** A guess can be wrong, and nothing proves the fix. The edit can still disappear in the case that the user hit.
+**Best route:** Reproduce the report. Install the skill, edit one copy, apply the build again, and run `sync`. The edit disappears. Fix the cause, and run the same steps again.
+**Evidence:** Before the fix, the reproduction printed "Updated design-deep-modules to the bundled version (3 copies)." and the edit was gone. After the fix, it printed "Kept your edited copy of design-deep-modules at ..." and the edit stayed.
 
-## Completion
+## Guardrails
+
+- Keep the unrelated edits of the user in the worktree.
+- Do not widen a public contract to fit an internal shortcut.
+- Refactor only when the fix or its proof needs it.
+- Do not add a guard for a case that cannot happen. Fix the cause of a case that can.
+- Put each later review round in its own commit. Never rewrite pushed history.
 
-The requested outcome works, focused verification passes, and every hunk has a reason within scope.
+## Completion
 
-Report the outcome in one sentence, the verification command with its result, and each changed file with the reason it is in scope. Keep the reply to these facts. When a pull request exists, put full command output in its verification section instead of the reply.
+- The reproduction command or test, with the wrong output before the fix.
+- The same reproduction after the fix, with the expected output.
+- The focused test command and the required check, with their result lines.
+- Each changed file, with the reason that it is in scope.
+- For an issue that you could not reproduce: the reason, and the evidence for the inferred cause.

package/skills/shadowclone-work/SKILL.md

@@ -1,10 +1,11 @@
 ---
 name: shadowclone-work
-description: Take a feature request, an issue, or an existing pull request to a pull request that is ready to merge, then keep it there. Use when the user asks to implement something and open a PR, get a PR ready to merge, fix a red PR, address review comments, resolve conflicts, or restack a stack of PRs. Covers CI failures and flakes, bot and human review threads, conflicts with a moving base, and gh stack restacks.
+description: 'Use when the user asks to implement a change and open a pull request, or to get a pull request ready to merge. Also use it when the user says "fix the red PR", "address the review comments", or "restack my PRs". Covers CI failures and flakes, bot and human review threads, conflicts with a moving base, and stack restacks. Takes the work to a pull request that is ready for review, and keeps it there without merging. Not for checking review comments before you act on them (use `verify-review-findings`).'
 metadata:
   shadowclone-category: workflow
   shadowclone-section: workflow
-  shadowclone-applies-when: taking a change or a pull request to ready for review
+  shadowclone-applies-when: when taking a change or a pull request to ready for review
+  shadowclone-voice: "true"
 ---
 # Take Work to a Ready Pull Request
 
@@ -14,6 +15,8 @@ The user wants a change delivered as a pull request that is ready to merge, or w
 
 ## Process
 
+Write in the user's voice. Before you write, read `~/.agents/voice.md`. If it does not exist, build it once from the user's merged pull requests, review comments, and commit messages. Use only text that the user wrote, and name those sources in your handoff. Never overwrite an existing or linked `voice.md`.
+
 1. **Find the target.** For a request or an issue, branch from an up-to-date default branch. For an existing pull request, check out its branch and run `git fetch`. Run `gh stack view` to learn whether the branch is part of a stack, and note each pull request's base.
 2. **Read the repository's rules.** Read `README.md`, `CONTRIBUTING.md`, `AGENTS.md`, and the pull request template when they exist. Follow their title format (for example conventional commits for squash-merged repositories), template sections, and check commands.
 3. **Build the change.** Make the smallest complete change, add tests through public interfaces, and run the repository's checks locally before pushing.

package/skills/tests-that-catch-bugs/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: tests-that-catch-bugs
+description: 'Use when adding, changing, or reviewing tests. Also use it when the user says "add a regression test", "write the test first", or "make sure this cannot break again". Writes a few tests that each name a bug and check the result where the user sees it. Expected values come from an independent source, and each test fails without the change. Test first is an ordering choice inside this skill. Not for checking finished work against the real command output (use `verify-and-review`).'
+metadata:
+  shadowclone-category: testing
+  shadowclone-section: workflow
+  shadowclone-applies-when: when adding, changing, or proving a test
+---
+# Tests That Catch Bugs
+
+## Use when
+
+You add or change a test, you fix a bug, or the user asks for test first work. A test has value only if it fails when the behavior it guards breaks. Three tests that catch real bugs are better than ten tests that pass whatever the code does.
+
+## Gates
+
+1. Can you name the bug that the test catches, as a wrong output for a given input? If not, do not write the test.
+2. Does the test check the result where the user sees it, such as the command output, the exit code, or a written file? If the symptom is at the command, a helper test alone does not count.
+3. Does the expected value come from a source other than the code under test? Use the bug report, the specification, a value you calculated by hand, or a recorded real output.
+4. Did you see the test fail without the change, for the reason you named, and then pass with the change?
+5. Would the test fail if the code under test returned nothing, an empty list, or a constant? If not, make the test specific or delete it.
+6. Is the final diff free of each temporary mutation and debug line?
+
+## Process
+
+### Choose the order
+
+- Test first: write the failing test before the change. Use this order when the user or a saved preference asks for it. Also use it when the behavior is new and you know its interface. Run the test and see it fail because the behavior is missing.
+- Fix first, then prove: use this order when the fix for a confirmed bug already exists. Write the test, then undo the smallest part of the fix and see the test fail.
+- Both orders end with the same proof.
+
+### Choose what to test
+
+1. List the behaviors that the change can break. Rank them by their consequence for the user. Data loss, wrong output, a wrong count or status, a security boundary, and a crash come first.
+2. Read the nearby tests. Use their fixtures and the public interface that they call.
+3. For each material risk, write one test at the layer where the user sees the failure.
+4. Use the smallest fixture that reaches the real boundary, such as a temporary home folder or a real file on disk.
+5. Do not test private branches, log wording, or styling, unless they are a documented contract.
+
+### Prove each test
+
+1. Find the smallest production change that makes the test pass.
+2. Invert or remove that change, and keep the code compilable.
+3. Show the mutated lines with their file and line number.
+4. Run only that test. Make sure that the intended assertion fails with the wrong value that you named.
+5. Restore the change. Run the same test again and make sure that it passes.
+6. If the test passes under the mutation, or fails for a different reason, it is not proof. Fix the test and do the proof again.
+
+## Example
+
+**Situation:** A setup command skips one agent because the instruction file of that agent is a symbolic link. The fix also changes the summary line.
+**Easy route:** Add a unit test for the helper that decides to skip. It passes, and the work looks done.
+**Hidden cost:** The helper was already correct. The command still printed "Installed for 2 agents" after it skipped one agent, so the user trusted a false count.
+**Best route:** Run the real command in a temporary home that contains the symbolic link. Assert the summary line, the final line that names the skipped agent, and the exit code.
+**Evidence:** With the old counting code, the test failed: expected "Installed for 1 agent", received "Installed for 2 agents". With the fix, the same test passed.
+
+## Guardrails
+
+- Mutate production code, never the assertion. A setup error, a compile error, a timeout, or an unrelated failure does not prove a test.
+- Do not weaken an assertion to make the code pass. Fix the code, or get the expected value again from its independent source.
+- Use the real collaborators inside the module. Replace a dependency only at an external boundary, such as the network, the clock, a paid model call, or another process.
+- Assert the lines that carry meaning, such as a count, a status, or a path. A full snapshot breaks on each wording change and hides the line that matters.
+- Do not depend on clock timing, test order, or machine load. A flaky test teaches people to ignore failures.
+- Name each test for the behavior that it protects, so that a failure explains itself.
+- Keep each mutation local and reversible, and restore it before other work. Keep unrelated changes in the worktree.
+
+## Completion
+
+- The test command and its result line, for example `4 pass, 0 fail`.
+- For each new test, its `file:line` and the bug that it catches, in one sentence.
+- For each proof, the mutated `file:line` and the assertion line that failed under the mutation.
+- The passing run of the same test after the restore.
+- The `git diff` after the restore, with no mutated line left.

package/skills/typescript-type-safety/SKILL.md

@@ -1,36 +1,52 @@
 ---
 name: typescript-type-safety
-description: Represent valid state and relationships in TypeScript so invalid combinations fail at compile time. Use when designing types, parsing unknown input, or removing unsafe assertions.
+description: 'Use when changing TypeScript types, parsing input that enters typed code, or removing unsafe casts. Also use it when the user says "fix the types", "remove the as casts", or "make invalid states impossible". Models each valid state with types, so that invalid combinations fail to compile. Checks outside input with a type guard or a schema instead of an assertion. Not for designing module boundaries (use `design-deep-modules`).'
 metadata:
   shadowclone-category: typescript
   shadowclone-section: engineering
-  shadowclone-applies-when: language=typescript and changing typed state or boundaries
+  shadowclone-applies-when: when changing TypeScript types or input that enters typed code
 ---
 # Represent State in TypeScript Types
 
 ## Use when
 
-Values change together, optional fields hide distinct states, external input enters typed code, or an assertion is needed to satisfy the compiler.
+Values change together, optional fields hide different states, outside input enters typed code, or the compiler asks for an assertion. Each of these signals a missing type or a missing check.
+
+## Gates
+
+1. Does each valid state have its own type, such as a member of a discriminated union?
+2. Does outside input enter as `unknown`, and pass a type guard or a schema before use?
+3. Is the code free of `any`, non-null assertions, and casts, except `as const`?
+4. Does each switch over a union handle each member, so that a new member fails to compile?
+5. Does a failure that callers must handle appear in the return type?
 
 ## Process
 
-1. Name valid states and transitions. Use discriminated unions when only certain field combinations are valid.
-2. Preserve key-value relationships with generics, mapped types, or a typed setter.
-3. Accept external input as `unknown` and validate it at the boundary.
-4. Narrow through control flow, predicates, schemas, or destructuring. Make valid absence explicit.
-5. Return types that require callers to handle meaningful failures.
-6. Run type checks and tests for runtime validation.
+1. Name the valid states and the moves between them. Use a discriminated union when only some field combinations are valid.
+2. Keep the relation between keys and values with generics, mapped types, or a typed setter.
+3. Accept outside input as `unknown`. Check it at the boundary with a schema or a type guard.
+4. Narrow values with control flow, type guards, or destructuring. Make a valid absence explicit.
+5. Return a type that makes callers handle each meaningful failure.
+6. Run the type check, and run the tests for the boundary checks.
 
-## Guardrails
+## Example
 
-Keep one source of truth for each discriminator and handle every union member where behavior must be exhaustive. Preserve literals instead of widening them prematurely.
+**Situation:** A function reads a config file and casts the parsed JSON to `Config`.
+**Easy route:** Keep the cast, because the file usually has the right shape.
+**Hidden cost:** A config file with one wrong field passes the cast. The program fails later, far from the cause.
+**Best route:** Parse the JSON with a schema at the boundary. Return a clear error that names the field.
+**Evidence:** A test with a wrong field type now fails at the boundary with "sources.git-metadata: expected boolean". The type check passed with no cast left.
 
-Treat `any`, non-null assertions, and broad casts as signs of a missing relationship or boundary. A narrow assertion is appropriate only when an externally established runtime invariant cannot be expressed through validation or control flow. Follow stricter repository rules where they apply.
+## Guardrails
 
-Contain imprecise library types in one adapter returning a precise project type. Avoid generic abstractions that obscure a simple relationship.
+- Keep one source of truth for each discriminator.
+- Keep literal types until a wider type is necessary.
+- Put an imprecise library type in one adapter that returns a precise project type.
+- Use a narrow assertion only for a fact that a runtime check cannot express, and write down why.
+- Follow the stricter rules of the repository where they apply.
 
 ## Completion
 
-Valid states are constructible, invalid combinations are rejected, relationships survive the call path, and type and boundary checks pass.
-
-Report the type that now rejects the invalid state, one example the compiler rejects, and the typecheck and boundary test commands with their results. Keep the reply to these facts. When a pull request exists, put full command output in its verification section instead of the reply.
+- The type that now rejects the invalid state.
+- One example that the compiler now rejects, with its error line.
+- The type check command and the boundary test command, with their result lines.

package/skills/verify-and-review/SKILL.md

@@ -1,34 +1,58 @@
 ---
 name: verify-and-review
-description: Verify changed behavior and inspect the final diff before presenting completed work. Use when an implementation, fix, refactor, or documentation change is ready for handoff.
+description: 'Use before you say that work is done, fixed, or ready for review. Also use it when the user says "make sure it works", "verify this", or "is it ready?". Runs the command or page that the user will use, and reads every count, status line, and exit code. Reviews the whole diff, and labels each claim as measured, inferred, or not verified. This catches a wrong count or a buried warning before handoff. Not for writing or proving tests (use `tests-that-catch-bugs`).'
 metadata:
   shadowclone-category: review
   shadowclone-section: workflow
-  shadowclone-applies-when: preparing completed work for review or handoff
+  shadowclone-applies-when: before you say that work is done or ready for review
 ---
-# Verify and Review Before Finishing
+# Verify the Real Outcome
 
 ## Use when
 
-Code or documentation changes are ready for handoff. Answers to questions do not need this workflow; answer them directly.
+You are about to say that a change is done, fixed, or ready for review. A question does not need this skill. Answer it directly.
+
+## Gates
+
+1. Did you run what the user runs: the command, the page, or the request, on the surface that they use? A passing unit test does not show that the command works.
+2. Did you read every line of the real output, including counts, totals, the final lines, and the exit code? Does each one match what happened?
+3. If the command writes files, did it run in a temporary home or a copy? Did you read the files that it wrote?
+4. Does each claim in your report have a label: measured, inferred, or not verified?
+5. Did you read the whole diff, including new files, and remove debug output, temporary mutations, and unrelated edits?
+6. Does the report list each behavior choice, such as a skip or a fallback, with its output line?
 
 ## Process
 
-1. Identify changed behavior, data paths, interfaces, and public claims. Read the repository's required checks.
-2. Run focused verification, then the required gate. Repeat broad checks only when later changes or failures justify it.
-3. Review the full diff with surrounding context, including untracked files. Check for generated output, diagnostics, secrets, and unrelated edits.
-4. For changed data paths, trace logs, errors, writes, and network requests to their source and required redaction boundary.
-5. Compare affected docs and diagrams with the implementation. Exercise changed interfaces and inspect their rendered state.
-6. Report checks and results, separating pre-existing failures and unverified behavior from regressions.
+1. List what changed for the user: commands, output lines, exit codes, written files, pages, and documents.
+2. Run the focused tests, then the required check of the repository. Run a broad check again only when a later change needs it.
+3. Run the real command, or open the real page. Use a temporary home folder for a command that writes files. For a page, take a screenshot and look at it.
+4. Read the output line by line. Compare each count, status, and path with what you know happened. A wrong count is a bug, even when all tests pass.
+5. Do one failure path as well, such as a missing file or a bad value. Check the message and the exit code.
+6. Read the full diff with its context. Look for secrets, generated files, debug lines, and edits outside the request.
+7. Compare the changed documents with the behavior that you saw.
+8. Write the report, and give each claim its label.
 
-## Guardrails
+## Example
 
-Match claims to checks or direct observations. A successful build does not prove an unexercised runtime path works. Keep captured user content out of reports unless it has crossed the required redaction boundary.
+**Situation:** A change adds a `--json` flag to a status command. The unit tests for the formatter pass.
+**Easy route:** Report "Done, all tests pass."
+**Hidden cost:** The real command printed a warning line before the JSON. Each script that read the output failed to parse it.
+**Best route:** Run the command with `--json`, send its output to a JSON parser, and check the exit code.
+**Evidence:** The first run failed to parse at line 1, which was "Warning: the config file is old". After the fix, the parser read the output, and the command exited with code 0.
 
-Preserve unrelated work. An existing dirty worktree is not a reason to delete another contributor's changes or claim that the whole tree is clean.
+## Guardrails
 
-## Completion
+- Match each claim to a check that you ran or a thing that you saw. A successful build does not prove that an unused path works.
+- Never verify a command that writes files against the real home or data of the user. Use a copy.
+- Report each failure that existed before your change apart from new failures, with the evidence that it existed before.
+- Keep captured user content and secrets out of the report.
+- Keep unrelated work in the worktree. A worktree with other changes is not a reason to delete them.
+- When a pull request exists, put the full command output in its verification section, not in the chat reply.
 
-The final diff has been reviewed, required checks have run, and the handoff states the evidence and material limitations.
+## Completion
 
-Report each check you ran with its result, what you exercised by hand and what you saw, and each unverified path or pre-existing failure apart from regressions. Keep the reply to these facts. When a pull request exists, put full command output in its verification section instead of the reply.
+- Each command that you ran, with its exit code.
+- The output lines that show the result, quoted exactly.
+- Each claim with its label: measured, inferred, or not verified.
+- The `file:line` of each behavior choice, with the output line that shows it.
+- Each failure that existed before the change, and each path that you did not verify.

package/skills/verify-review-findings/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: verify-review-findings
+description: 'Use when a pull request has review comments or bot findings to check. Also use it when the user says "are these comments right?", "triage the review", or "check what the bot found". Checks each finding against the code at the head of the pull request, and confirms the file, the line, and the claim. Asks what each suggested fix would break, reports a verdict for each finding, and waits. Not for writing the fix (use `scope-confirmed-changes`).'
+metadata:
+  shadowclone-category: review
+  shadowclone-section: workflow
+  shadowclone-applies-when: when a pull request has review comments or bot findings
+  shadowclone-voice: "true"
+---
+# Verify Review Findings
+
+## Use when
+
+A pull request has review comments, bot findings, or a list of issues from another agent. A finding is a claim, not a fact. Check each one before you change code or reply.
+
+## Gates
+
+1. Did you read each finding at the head commit of the pull request? A finding about an older commit can be stale.
+2. For each finding, do the file and the line exist, and does the code there do what the finding says?
+3. Can you show the claim with a test, a command, or the code itself? If not, label it as not verified.
+4. Did you ask what each suggested fix would break, such as a caller, a test, or a documented behavior?
+5. Does each finding have a verdict: confirmed, partly right, wrong, stale, or not verified?
+6. Did you wait for the user before you changed code or replied to a reviewer?
+
+## Process
+
+Write in the user's voice. Before you write, read `~/.agents/voice.md`. If it does not exist, build it once from the user's merged pull requests, review comments, and commit messages. Use only text that the user wrote, and name those sources in your handoff. Never overwrite an existing or linked `voice.md`.
+
+1. Fetch the pull request, and check out its head commit. Write down the commit hash.
+2. List each finding in one table, with its source, its `file:line`, and its claim.
+3. For each finding, read the code at that location and its callers. Compare the claim with the real behavior.
+4. When the claim is about behavior, run a focused test or a command that shows it.
+5. For each suggested fix, list what it changes for callers, tests, and users. A fix that is right in one place can break another place.
+6. Give each finding a verdict, with the evidence that supports it.
+7. Put the confirmed findings first, with the highest risk at the top.
+8. Report the table, and wait. Change code or reply only after the user decides.
+
+## Example
+
+**Situation:** A review bot says that a function can return null and crash its caller. It suggests a null check.
+**Easy route:** Add the null check, and reply "Fixed".
+**Hidden cost:** The function never returns null, because a type guard on the line above handles that case. The extra check hides the real contract, and the reply tells the reviewer something false.
+**Best route:** Read the function at the head commit, and run its test with an empty input. Report the finding as wrong, with the line that handles the case.
+**Evidence:** The test with the empty input passed at the head commit. The report quoted the guard at its `file:line` and gave the verdict "wrong".
+
+## Guardrails
+
+- Never change code or post a reply before the user decides.
+- Do not accept a finding because a bot or a senior reviewer wrote it. Do not reject it for that reason either.
+- Quote the code that proves each verdict. Do not paraphrase it.
+- Keep each finding separate. Do not merge two findings into one verdict.
+- A finding that you cannot check stays "not verified" in the report.
+
+## Completion
+
+- The head commit hash that you checked.
+- A table row for each finding: the source, the `file:line`, the claim, the verdict, and the evidence.
+- Each command or test that you ran, with its result line.
+- For each confirmed finding, what its fix changes for callers and tests.

package/skills/write-plain-english/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: write-plain-english
+description: 'Use when writing or editing prose that people read, such as documents, pull requests, commit messages, review comments, chat replies, or skills. Also use it when the user says "make this clearer", "simplify the wording", or "this is a wall of text". Rewrites the text in plain technical English, with one idea in each sentence and no dashes. Then runs a checker that reports long sentences and dashes. Not for checking code behavior (use `verify-and-review`).'
+metadata:
+  shadowclone-category: writing
+  shadowclone-section: workflow
+  shadowclone-applies-when: when writing prose that people read
+  shadowclone-voice: "true"
+---
+# Write Plain English
+
+## Use when
+
+You write or edit text for people: a document, a pull request, a commit message, a review comment, a chat reply, or a skill. The rules come from ASD-STE100 Simplified Technical English. Clarity comes first. If a rule makes the text wrong or unclear, break the rule.
+
+## Gates
+
+1. Does each sentence carry one idea, with 20 words or fewer for an instruction and 25 or fewer for a description?
+2. Is each instruction in the active voice, with the condition before the action?
+3. Do you use one term for one thing, every time?
+4. Is the text free of em dashes and en dashes?
+5. Did you run `scripts/check-ste.mjs` on the text, and fix or explain each finding?
+6. Are code, commands, paths, and product names exactly as they were?
+
+## Process
+
+Write in the user's voice. Before you write, read `~/.agents/voice.md`. If it does not exist, build it once from the user's merged pull requests, review comments, and commit messages. Use only text that the user wrote, and name those sources in your handoff. Never overwrite an existing or linked `voice.md`.
+
+1. Put the main point first. Give the reader the result, then the reason.
+2. Use common words that have one meaning. Use a single verb, not a phrasal verb: "start", not "kick off".
+3. Keep the articles "the" and "a". Do not drop words to save space.
+4. Use numbered steps for a procedure, with one action in each step.
+5. Put a condition before its instruction: "If the test fails, read the first error."
+6. Replace each dash with a comma, a period, parentheses, or two sentences. For a range, write "to", as in "2 to 5".
+7. Save the text to a file, and run `node scripts/check-ste.mjs <file>`. If Node is not available, run the script with `bun`. If neither one runs, say that the check did not run.
+8. Fix each error. For each warning, fix it, or keep it and say why the rule makes the text worse.
+
+## Example
+
+**Situation:** A pull request explains a bug in one sentence of 45 words. The sentence joins the symptom, the cause, and the fix with "so" and "which", and it has an em dash.
+**Easy route:** Keep the sentence. It is accurate, and a rewrite takes time.
+**Hidden cost:** Reviewers skim it and miss the cause, so they ask about it in review. The dash also fails the prose check of the repository.
+**Best route:** Split it into three sentences: the symptom, the cause, and the fix. Replace the dash with a period.
+**Evidence:** Before the edit, the checker reported the 45 word sentence and the dash. After the edit, it printed "check-ste: 0 errors, 0 warnings in 1 file".
+
+## Guardrails
+
+- Keep technical terms, identifiers, and quoted text exactly as they are. Do not paraphrase an error message.
+- Do not change the meaning to obey a rule.
+- Do not rewrite text that another person wrote, unless they ask. Suggest the change instead.
+- Do not add filler, praise, or hedging words, such as "robust", "seamless", or "simply".
+- Keep each term the same in the whole document.
+
+## Completion
+
+- The checker command and its summary line, for example `check-ste: 0 errors, 1 warning in 1 file`.
+- Each warning that you kept, with its `file:line` and your reason.
+- The path of the voice file that you read, or the sources that you used to build it.