@shadowclone/cli 0.0.25 → 0.0.27

package/evals.md

@@ -1,10 +1,10 @@
 # Evaluation results
 
-The evaluation tests whether coding agents follow engineering preferences across 24 fixed tasks. Every setup ran all tasks three times on each model. All planned tasks remain in the comparison. Tables use final authorized attempts; earlier interrupted attempts and partial checks remain in private records.
+This evaluation tests whether agents follow engineering preferences. It uses 24 fixed tasks, and every setup ran all tasks three times on each model, which makes 72 sessions for each setup and model. All planned tasks stay in the comparison, and the tables use the final authorized attempts.
 
 ## Preference adherence
 
-Each task checks its assigned preference family. The score averages repetitions and tasks within each family, then gives each of eight families equal weight. It measures preference adherence, not overall task success or code quality. Each setup and model contains 72 sessions.
+Each task checks one preference family. The score averages repetitions and tasks inside each family, then weights the eight families equally. It does not measure task success or code quality.
 
 | Setup                                     | GPT 6.1 Sol | GPT 6 Luna | Claude Sonnet 5.5 | Claude Opus 5.5 |
 | ----------------------------------------- | ----------: | ---------: | ----------------: | --------------: |
@@ -14,79 +14,71 @@ Each task checks its assigned preference family. The score averages repetitions
 | Existing skills + handwritten preferences |       92.4% |      81.2% |             91.7% |           86.1% |
 | Existing skills + Shadowclone learning    |       89.4% |      83.3% |             90.0% |           82.9% |
 
-Shadowclone learning scores above existing user skills on all four models. Handwritten preferences score higher than learned preferences on GPT 6.1 Sol, Claude Sonnet 5.5, and Claude Opus 5.5. GPT 6 Luna records a higher learned-preference point estimate. Learning delivery, incomplete learned guidance, and model behavior all affect this comparison.
+Learning beats existing user skills on all four models. Handwritten preferences score higher than learned ones on GPT 6.1 Sol, Sonnet, and Opus, but not on GPT 6 Luna. Learning delivery and model behavior affect this comparison.
 
 ## What each setup means
 
-| Setup                                     | What the agent receives                                                                                             |
-| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
-| Agent alone                               | Shared repository requirements, with no personal skills or preferences                                              |
-| Existing user skills                      | The same requirements plus an unchanged synthetic code-style skill                                                  |
-| Existing skills + Shadowclone routing     | The same skill library plus Shadowclone's native startup guidance, without learning                                 |
-| Existing skills + handwritten preferences | The routed library plus independently handwritten intended rules, a reference comparison rather than a product mode |
-| Existing skills + Shadowclone learning    | The routed library plus actual rules published by Shadowclone from synthetic correction sessions                    |
-
-Handwritten and learned preferences use the same delivery path. The learner never receives the intended rules or grading answers. These setups are named `bare`, `skills`, `routing`, `told`, and `deep` in saved receipts.
+The [fixed contract](evals/README.md#the-fixed-contract) defines the five setups. Saved receipts name them `bare`, `skills`, `routing`, `told`, and `deep`.
 
 ## Per-preference results
 
-The columns follow the setup definitions above. Each family contains three tasks and three repetitions. Answer length contributes at most 12.5% to the headline.
+Each family has three tasks and three repetitions. Columns follow the rows of the first table. Answer length counts for at most 12.5% of the headline.
 
 ### GPT 6.1 Sol
 
-| Preference          | Agent alone | User skills | + Shadowclone routing | + Handwritten preferences | + Shadowclone learning |
-| ------------------- | ----------: | ----------: | --------------------: | ------------------------: | ---------------------: |
-| Comments            |      100.0% |      100.0% |                100.0% |                    100.0% |                 100.0% |
-| Type safety         |      100.0% |      100.0% |                100.0% |                    100.0% |                 100.0% |
-| API conventions     |       33.3% |      100.0% |                100.0% |                    100.0% |                 100.0% |
-| Git authorization   |       51.9% |       48.1% |                 55.6% |                    100.0% |                  81.5% |
-| Answer length       |       66.7% |       66.7% |                 66.7% |                     66.7% |                  66.7% |
-| Test-first behavior |      100.0% |      100.0% |                100.0% |                    100.0% |                 100.0% |
-| PR structure        |       66.7% |       66.7% |                 66.7% |                     72.2% |                  66.7% |
-| Scope and lifecycle |      100.0% |      100.0% |                100.0% |                    100.0% |                 100.0% |
+| Preference          |  Alone | Skills | Routing | Handwritten | Learning |
+| ------------------- | -----: | -----: | ------: | ----------: | -------: |
+| Comments            | 100.0% | 100.0% |  100.0% |      100.0% |   100.0% |
+| Type safety         | 100.0% | 100.0% |  100.0% |      100.0% |   100.0% |
+| API conventions     |  33.3% | 100.0% |  100.0% |      100.0% |   100.0% |
+| Git authorization   |  51.9% |  48.1% |   55.6% |      100.0% |    81.5% |
+| Answer length       |  66.7% |  66.7% |   66.7% |       66.7% |    66.7% |
+| Test-first behavior | 100.0% | 100.0% |  100.0% |      100.0% |   100.0% |
+| PR structure        |  66.7% |  66.7% |   66.7% |       72.2% |    66.7% |
+| Scope and lifecycle | 100.0% | 100.0% |  100.0% |      100.0% |   100.0% |
 
 ### GPT 6 Luna
 
-| Preference          | Agent alone | User skills | + Shadowclone routing | + Handwritten preferences | + Shadowclone learning |
-| ------------------- | ----------: | ----------: | --------------------: | ------------------------: | ---------------------: |
-| Comments            |      100.0% |      100.0% |                100.0% |                    100.0% |                 100.0% |
-| Type safety         |       44.4% |       88.9% |                100.0% |                     88.9% |                 100.0% |
-| API conventions     |       33.3% |      100.0% |                 88.9% |                    100.0% |                  88.9% |
-| Git authorization   |       77.8% |       77.8% |                 70.4% |                    100.0% |                  88.9% |
-| Answer length       |       44.4% |       66.7% |                 44.4% |                     44.4% |                  66.7% |
-| Test-first behavior |       33.3% |       55.6% |                 33.3% |                     33.3% |                  44.4% |
-| PR structure        |       66.7% |       66.7% |                 66.7% |                     83.3% |                  77.8% |
-| Scope and lifecycle |       72.2% |       88.9% |                 77.8% |                    100.0% |                 100.0% |
+| Preference          |  Alone | Skills | Routing | Handwritten | Learning |
+| ------------------- | -----: | -----: | ------: | ----------: | -------: |
+| Comments            | 100.0% | 100.0% |  100.0% |      100.0% |   100.0% |
+| Type safety         |  44.4% |  88.9% |  100.0% |       88.9% |   100.0% |
+| API conventions     |  33.3% | 100.0% |   88.9% |      100.0% |    88.9% |
+| Git authorization   |  77.8% |  77.8% |   70.4% |      100.0% |    88.9% |
+| Answer length       |  44.4% |  66.7% |   44.4% |       44.4% |    66.7% |
+| Test-first behavior |  33.3% |  55.6% |   33.3% |       33.3% |    44.4% |
+| PR structure        |  66.7% |  66.7% |   66.7% |       83.3% |    77.8% |
+| Scope and lifecycle |  72.2% |  88.9% |   77.8% |      100.0% |   100.0% |
 
 ### Claude Sonnet 5.5
 
-| Preference          | Agent alone | User skills | + Shadowclone routing | + Handwritten preferences | + Shadowclone learning |
-| ------------------- | ----------: | ----------: | --------------------: | ------------------------: | ---------------------: |
-| Comments            |      100.0% |      100.0% |                100.0% |                    100.0% |                 100.0% |
-| Type safety         |        0.0% |      100.0% |                100.0% |                    100.0% |                  88.9% |
-| API conventions     |       33.3% |      100.0% |                100.0% |                    100.0% |                 100.0% |
-| Git authorization   |       55.6% |       55.6% |                 55.6% |                    100.0% |                  85.2% |
-| Answer length       |        0.0% |        0.0% |                  0.0% |                     55.6% |                  77.8% |
-| Test-first behavior |      100.0% |      100.0% |                100.0% |                    100.0% |                 100.0% |
-| PR structure        |       66.7% |       66.7% |                 66.7% |                     77.8% |                  72.2% |
-| Scope and lifecycle |       96.3% |       88.9% |                 92.6% |                    100.0% |                  96.3% |
+| Preference          |  Alone | Skills | Routing | Handwritten | Learning |
+| ------------------- | -----: | -----: | ------: | ----------: | -------: |
+| Comments            | 100.0% | 100.0% |  100.0% |      100.0% |   100.0% |
+| Type safety         |   0.0% | 100.0% |  100.0% |      100.0% |    88.9% |
+| API conventions     |  33.3% | 100.0% |  100.0% |      100.0% |   100.0% |
+| Git authorization   |  55.6% |  55.6% |   55.6% |      100.0% |    85.2% |
+| Answer length       |   0.0% |   0.0% |    0.0% |       55.6% |    77.8% |
+| Test-first behavior | 100.0% | 100.0% |  100.0% |      100.0% |   100.0% |
+| PR structure        |  66.7% |  66.7% |   66.7% |       77.8% |    72.2% |
+| Scope and lifecycle |  96.3% |  88.9% |   92.6% |      100.0% |    96.3% |
 
 ### Claude Opus 5.5
 
-| Preference          | Agent alone | User skills | + Shadowclone routing | + Handwritten preferences | + Shadowclone learning |
-| ------------------- | ----------: | ----------: | --------------------: | ------------------------: | ---------------------: |
-| Comments            |       77.8% |      100.0% |                100.0% |                    100.0% |                 100.0% |
-| Type safety         |       22.2% |      100.0% |                100.0% |                    100.0% |                 100.0% |
-| API conventions     |       33.3% |      100.0% |                100.0% |                    100.0% |                 100.0% |
-| Git authorization   |       48.1% |       44.4% |                 51.9% |                    100.0% |                  81.5% |
-| Answer length       |        0.0% |        0.0% |                  0.0% |                     22.2% |                  22.2% |
-| Test-first behavior |      100.0% |      100.0% |                100.0% |                    100.0% |                 100.0% |
-| PR structure        |       66.7% |       66.7% |                 66.7% |                     66.7% |                  66.7% |
-| Scope and lifecycle |       77.8% |       77.8% |                 88.9% |                    100.0% |                  92.6% |
+| Preference          |  Alone | Skills | Routing | Handwritten | Learning |
+| ------------------- | -----: | -----: | ------: | ----------: | -------: |
+| Comments            |  77.8% | 100.0% |  100.0% |      100.0% |   100.0% |
+| Type safety         |  22.2% | 100.0% |  100.0% |      100.0% |   100.0% |
+| API conventions     |  33.3% | 100.0% |  100.0% |      100.0% |   100.0% |
+| Git authorization   |  48.1% |  44.4% |   51.9% |      100.0% |    81.5% |
+| Answer length       |   0.0% |   0.0% |    0.0% |       22.2% |    22.2% |
+| Test-first behavior | 100.0% | 100.0% |  100.0% |      100.0% |   100.0% |
+| PR structure        |  66.7% |  66.7% |   66.7% |       66.7% |    66.7% |
+| Scope and lifecycle |  77.8% |  77.8% |   88.9% |      100.0% |    92.6% |
 
 ## Matched comparisons
 
-Differences are percentage points. The 95% bootstrap intervals resample the three matched repetition and learning-preparation groups while keeping the task mix fixed. Three groups give coarse intervals. Models share preparations, so their results are correlated and cannot be pooled as independent samples.
+Differences are in percentage points. The 95% bootstrap intervals resample the three matched groups of repetition and learning preparation, with the task mix fixed. Three groups give coarse intervals. Models share preparations, so do not pool them.
 
 | Model             | Learning over routing | 95% interval  | Learning over handwritten preferences | 95% interval |
 | ----------------- | --------------------: | ------------- | ------------------------------------: | ------------ |
@@ -97,50 +89,44 @@ Differences are percentage points. The 95% bootstrap intervals resample the thre
 
 ## Separate routing comparison
 
-A second experiment uses 20 synthetic skills and twelve tasks, with three repetitions per setup. It measures skill selection and implementation compliance separately. Reading a skill earns no compliance credit.
+A second experiment uses 20 synthetic skills, twelve tasks, and three repetitions for each setup. It scores selection and compliance separately.
 
-| Model             | Existing skills, preference adherence | Existing skills + Shadowclone routing, preference adherence |
-| ----------------- | ------------------------------------: | ----------------------------------------------------------: |
-| GPT 6.1 Sol       |                                100.0% |                                                      100.0% |
-| GPT 6 Luna        |                                100.0% |                                                       97.2% |
-| Claude Sonnet 5.5 |                                100.0% |                                                      100.0% |
-| Claude Opus 5.5   |                                100.0% |                                                      100.0% |
+| Model             | Existing skills | + Routing |
+| ----------------- | --------------: | --------: |
+| GPT 6.1 Sol       |          100.0% |    100.0% |
+| GPT 6 Luna        |          100.0% |     97.2% |
+| Claude Sonnet 5.5 |          100.0% |    100.0% |
+| Claude Opus 5.5   |          100.0% |    100.0% |
 
-Both Claude models selected the expected skills in every session. Codex read tracking missed some successful reads; the original tracking verdicts remain retained. Task names directly match skill names, and the added routing is generic startup guidance. This experiment does not establish an advantage for explicit production skill routes. It also does not establish that production routing is unnecessary.
+Both Claude models selected the expected skills in every session. Codex read tracking missed some reads, and the original verdicts stay. Task names match skill names, and the routing is generic startup guidance, so the experiment says nothing for or against explicit production routes.
 
 ## Correctness, safety, and learning
 
-Preference adherence remains separate from correctness. The following raw correctness counts use all 72 sessions per setup and retain the original acceptance verdicts. API and advice acceptance constraints limit their interpretation, as described below. Routing correctness is not compared because its acceptance assumes a fixed module location.
+These correctness counts cover all 72 sessions for each setup, with the original acceptance verdicts. API and advice acceptance limits affect how to read them. Routing correctness is not compared, because its acceptance assumes a fixed module location.
 
-| Setup                                     | GPT 6.1 Sol | GPT 6 Luna | Claude Sonnet 5.5 | Claude Opus 5.5 |
-| ----------------------------------------- | ----------: | ---------: | ----------------: | --------------: |
-| Agent alone                               |       72/72 |      69/72 |             71/72 |           72/72 |
-| Existing user skills                      |       72/72 |      72/72 |             68/72 |           69/72 |
-| Existing skills + Shadowclone routing     |       71/72 |      70/72 |             69/72 |           69/72 |
-| Existing skills + handwritten preferences |       70/72 |      72/72 |             69/72 |           69/72 |
-| Existing skills + Shadowclone learning    |       70/72 |      72/72 |             68/72 |           69/72 |
+| Setup       | GPT 6.1 Sol | GPT 6 Luna | Claude Sonnet 5.5 | Claude Opus 5.5 |
+| ----------- | ----------: | ---------: | ----------------: | --------------: |
+| Alone       |       72/72 |      69/72 |             71/72 |           72/72 |
+| Skills      |       72/72 |      72/72 |             68/72 |           69/72 |
+| Routing     |       71/72 |      70/72 |             69/72 |           69/72 |
+| Handwritten |       70/72 |      72/72 |             69/72 |           69/72 |
+| Learning    |       70/72 |      72/72 |             68/72 |           69/72 |
 
-All planned sessions completed. Protected manual guidance remained unchanged in every final session. This safety check covers guidance preservation only. Git authorization has separate checks and recorded failures, including offline remote actions. No fixture action reached a real repository remote.
+All planned sessions completed, and protected manual guidance stayed unchanged in every final session. No fixture action reached a real remote.
 
-Three independent learning preparations used GPT 6.1 Sol at medium effort. One published four intended rules and left Git guidance pending; the other two published five. All three published partial PR guidance. The bounded agent assessment found no unsupported published guidance. Actual outputs were retained without adding missing rules.
+Three independent learning preparations used GPT 6.1 Sol at medium effort. One published four intended rules and left Git guidance pending, and two published five. All three published partial pull request guidance. A bounded agent assessment found no unsupported guidance. Nobody added the missing rules.
 
 ## Method and measurement limits
 
-The study ran on 2026-10-03. It contains 1,440 five-setup sessions and 288 separate routing sessions. Each family has two public development tasks and one private held-out task. Cases, graders, guidance, and denominators were frozen before candidate execution. Each task uses a disposable repository and isolated agent home. Existing personal setup is not imported or changed. Remote actions use offline fixtures.
-
-| Model             | Agent host  | Effort | Host version |
-| ----------------- | ----------- | ------ | ------------ |
-| GPT 6.1 Sol       | Codex       | Medium | 0.159.0      |
-| GPT 6 Luna        | Codex       | High   | 0.159.0      |
-| Claude Sonnet 5.5 | Claude Code | High   | 2.1.287      |
-| Claude Opus 5.5   | Claude Code | Medium | 2.1.287      |
-
-The declared runtime uses Bun 1.4.2 and TypeScript 5.9.3. Acceptance logs contain both Bun 1.3.3 and 1.4.2, so this is not a uniform toolchain comparison. Effort settings are fixed within each cohort; the study does not isolate model size or effort scaling.
+The study ran on 2026-10-03: 1,440 five-setup sessions and 288 routing sessions.
 
-A targeted agent audit inspected twenty saved sessions across all families and models without changing scores. Some preference graders check syntax and patterns. API acceptance assumes fixed option names despite allowing API choice. An advice keyword check can reject an equivalent explanation. These limits prevent a clean correctness or general engineering-quality claim. The audit is not independent human review.
+- GPT 6.1 Sol: Codex 0.159.0, medium effort.
+- GPT 6 Luna: Codex 0.159.0, high effort.
+- Claude Sonnet 5.5: Claude Code 2.1.287, high effort.
+- Claude Opus 5.5: Claude Code 2.1.287, medium effort.
 
-Claude continuation after a quota reset used explicitly authorized manual retries outside the automatic retry rule. Original attempts, partial checks, and call accounting remain private and unchanged. No failures were silently removed or rescored.
+The declared runtime is Bun 1.4.2 and TypeScript 5.9.3, but acceptance logs show both Bun 1.3.3 and 1.4.2. Each cohort has one fixed effort, so the study does not isolate model size or effort. An agent audit of twenty saved sessions changed no score and is not an independent human review. API acceptance assumes fixed option names, and an advice keyword check can reject an equivalent explanation. These limits prevent a clean claim about correctness or general engineering quality.
 
-The design applies fixed inputs, programmatic checks, isolated execution, held-out cases, repeated runs, confidence intervals, and transcript inspection from [Automating eval design and hillclimbing with Claude](https://claude.dev/blog/automating-eval-design-and-hillclimbing/). It does not establish full conformity: production representativeness, independent expert agreement, and model-effort scaling remain unproven. No autonomous hillclimbing ran.
+Claude runs after a quota reset used authorized manual retries. The study removed or rescored no failure in silence. The design follows [Automating eval design and hillclimbing with Claude](https://claude.dev/blog/automating-eval-design-and-hillclimbing/). No autonomous hillclimbing ran. Production representativeness, independent expert agreement, and effort scaling stay unproven.
 
-[The contributor guide](docs/guides/evaluations.md) explains the frozen inputs, private artifact boundaries, offline validation, preparation reuse, and approved execution scopes. These results support a bounded claim about preference delivery on synthetic tasks. They do not establish production throughput, broad security superiority, or a universal routing benefit.
+See the [evaluations guide](evals/README.md), the [code review benchmark](https://github.com/theonly1me/code-review-bench), and the [no-comments](evals/no-comments/README.md) evaluation. These results support a bounded claim about preference delivery on synthetic tasks, not production throughput, security superiority, or a universal routing benefit.

package/package.json

@@ -1,36 +1,16 @@
 {
   "name": "@shadowclone/cli",
-  "version": "0.0.25",
-  "module": "src/cli/index.ts",
+  "version": "0.0.27",
   "type": "module",
-  "packageManager": "bun@1.4.2",
-  "bin": {
-    "shadowclone": "bin/shadowclone.mjs"
-  },
-  "scripts": {
-    "start": "bun run src/cli/index.ts",
-    "cli": "bun run src/cli/index.ts",
-    "check": "bun run typecheck && bun run lint && bun run knip && bun test",
-    "test": "bun test",
-    "typecheck": "tsc --noEmit",
-    "format": "prettier --write",
-    "format:check": "prettier --check",
-    "lint": "biome lint --error-on-warnings --diagnostic-level=warn . && bun run scripts/conventions.ts && bun run scripts/privacy.ts && bun run scripts/skills.ts && bun run scripts/skillVersions.ts",
-    "lint:fix": "biome lint --write .",
-    "knip": "knip",
-    "eval": "bun evals/run.ts",
-    "eval:work": "bun evals/work/run.ts",
-    "build": "bun run scripts/build.ts",
-    "prepack": "bun run build"
-  },
-  "devDependencies": {
-    "@biomejs/biome": "2.5.15",
-    "@types/bun": "latest",
-    "knip": "6.39.0",
-    "prettier": "3.9.9",
-    "typescript": "~5.9"
-  },
   "description": "Turns how you work into a portable, tested environment for the coding agents you already use.",
+  "keywords": [
+    "claude-code",
+    "codex",
+    "cursor",
+    "agent",
+    "subagent",
+    "local-first"
+  ],
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -40,14 +20,9 @@
   "bugs": {
     "url": "https://github.com/theonly1me/shadowclone/issues"
   },
-  "keywords": [
-    "claude-code",
-    "codex",
-    "cursor",
-    "agent",
-    "subagent",
-    "local-first"
-  ],
+  "bin": {
+    "shadowclone": "bin/shadowclone.mjs"
+  },
   "files": [
     "bin",
     "dist",

package/plugins/shadowclone/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "shadowclone",
-  "version": "0.0.25",
+  "version": "0.0.27",
   "description": "Set up and maintain portable coding-agent skills with explicit local consent.",
   "author": {
     "name": "Shadowclone"

package/plugins/shadowclone/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "shadowclone",
-  "version": "0.0.25",
+  "version": "0.0.27",
   "description": "Set up and maintain portable coding-agent skills with explicit local consent.",
   "author": {
     "name": "Shadowclone",

package/plugins/shadowclone/README.md

@@ -1,17 +1,21 @@
 # Shadowclone plugin
 
-This plugin gives coding agents one workflow for installing and setting up [Shadowclone](https://shadowclone.co). It does not activate the repository's bundled skill library before the user chooses a build.
+This plugin gives an agent one workflow to install and set up [Shadowclone](https://shadowclone.co). It turns on no bundled skill until you choose a build.
 
 ## Use
 
-Install the plugin, start a new agent session, and say:
+Install the plugin, start a new session, and say:
 
 ```text
 Set up Shadowclone.
 ```
 
-The `setup-shadowclone` skill checks the CLI version and offers to install or upgrade it without elevated privileges, asks for three explicit consent decisions, initializes detected coding agents, and opens the loopback build editor. It requires CLI 0.0.13 or newer. Existing consent settings are preserved.
+The `setup-shadowclone` skill does these steps:
 
-The bundled MCP configuration starts `shadowclone mcp` after the CLI is installed. It uses standard input and output on the local machine and needs no Shadowclone service credentials.
+1. It installs or upgrades the CLI, with no elevated privileges.
+2. It asks three separate consent questions in chat, and keeps existing consent settings.
+3. It sets up the agents that it detects, opens the skill wizard, and learns from past sessions if you agreed.
 
-See the repository [privacy policy](https://github.com/theonly1me/shadowclone/blob/main/PRIVACY.md) and [security policy](https://github.com/theonly1me/shadowclone/blob/main/SECURITY.md).
+The bundled MCP configuration starts `shadowclone mcp` on your machine after you install the CLI. It needs no Shadowclone credentials. See the [MCP guide](https://github.com/theonly1me/shadowclone/blob/main/docs/guides/mcp.md).
+
+Read the [privacy](https://github.com/theonly1me/shadowclone/blob/main/PRIVACY.md) and [security](https://github.com/theonly1me/shadowclone/blob/main/SECURITY.md) policies.

package/plugins/shadowclone/SECURITY.md

@@ -1,5 +1,5 @@
 # Security
 
-Report vulnerabilities through [GitHub's private vulnerability reporting](https://github.com/theonly1me/shadowclone/security/advisories/new). Do not include credentials, private source, transcripts, or identifying local paths in a public issue.
+Report vulnerabilities through [private vulnerability reporting on GitHub](https://github.com/theonly1me/shadowclone/security/advisories/new). Never put credentials, private source, transcripts, or identifying paths in a public issue.
 
-General defects that can be demonstrated with independently authored synthetic input may be reported through [GitHub issues](https://github.com/theonly1me/shadowclone/issues).
+Report a general defect in [GitHub issues](https://github.com/theonly1me/shadowclone/issues) with input that you wrote and that holds no private data.

package/plugins/shadowclone/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "shadowclone",
-  "version": "0.0.25",
+  "version": "0.0.27",
   "description": "Set up and maintain portable coding-agent skills with explicit local consent.",
   "author": {
     "name": "Shadowclone",

package/plugins/shadowclone/skills/setup-shadowclone/SKILL.md

@@ -1,53 +1,65 @@
 ---
 name: setup-shadowclone
-description: Install and set up Shadowclone when the user asks to set up, configure, initialize, or start using Shadowclone with Claude Code, Codex, Cursor, Antigravity, or another coding agent.
+description: Install and configure Shadowclone for the user from start to finish. Use it when the user asks to "set up", install, configure, or start Shadowclone with Claude Code, Codex, Cursor, Pi, Antigravity, or another coding agent.
 license: MIT
 ---
+
 # Set Up Shadowclone
 
-Complete the local setup while keeping each data choice with the user.
+Do the whole setup for the user. The user only answers questions in chat and picks skills in the browser. Finish in less than 5 minutes.
 
-## Detect
+Do the steps in order. Run long commands in the background, and do the next step while they run. Do not explain a step that works.
 
-1. Run `node <this-skill-directory>/scripts/check-cli.mjs` using this skill's actual directory. The helper checks only `shadowclone --version`, reads no configuration or user data, and requires stable CLI version 0.0.13 or newer.
-2. If its status is `outdated`, show the installed and minimum versions and ask whether to upgrade the CLI. If it is `unavailable`, explain that a usable CLI is missing and ask whether to install it. Stop if the user declines.
-3. After approval, run `npm install -g @shadowclone/cli@latest`. Never use `sudo`. If the package manager cannot write to its configured global directory, explain that exact failure and help the user choose a user-owned npm prefix before retrying.
-4. Repeat the helper after installation or upgrade. Continue only when its status is `ready`. If it remains outdated, the required release may not be published yet. If the installed package is new enough but the helper still sees an older command, inspect `command -v shadowclone` and `npm prefix -g` for a stale executable or missing prefix on `PATH`; help the user resolve it without deleting unrelated installations.
-5. Run `shadowclone init --status --json`. Treat only `{"initialized":true}` as an existing setup. Preserve compatible existing installations and their consent settings.
+## 1. Check the CLI (10 seconds)
 
-The setup skill runs independently of MCP. MCP may be disconnected until the CLI is installed; this does not prevent these shell commands or consent questions.
+1. If this skill is on disk, run `node <this-skill-directory>/scripts/check-cli.mjs`. It runs only `shadowclone --version` and prints a status.
+2. If this skill is not on disk, run `shadowclone --version`. Version 0.0.13 or newer is `ready`. A missing command is `unavailable`.
+3. If the status is `ready`, run `shadowclone init --status --json`. If it prints `{"initialized":true}`, setup exists. Keep its consent choices, and go to step 4.
+4. If the status is `unavailable` or `outdated`, tell the user that you will install the Shadowclone CLI. Start `npm install -g @shadowclone/cli@latest` in the background. Never use `sudo`.
+5. If npm cannot write to its global folder, show the exact error. Help the user choose a user-owned npm prefix, and run the install again.
 
-## Ask for consent
+## 2. Ask three questions (30 seconds)
 
-When setup is not initialized, ask these three questions separately and record an explicit yes or no for each:
+Ask these questions in one message while the install runs. Use your question tool if you have one. Record an explicit yes or no for each answer.
 
-1. May Shadowclone learn working preferences from detected coding-agent sessions?
-2. May Shadowclone keep portable skills synchronized and maintain them across detected agents?
-3. May Shadowclone continue consented learning in the background?
+1. **Learn from past sessions?** Shadowclone reads the coding-agent sessions on this machine, redacts them, and learns your rules with your own agent CLI. The first pass takes up to 2 minutes.
+2. **Keep skills in sync?** Shadowclone keeps your skills up to date across your agents.
+3. **Keep learning in the background?** This needs a yes to question 1.
 
-Explain that background learning requires session learning. If the first answer is no, the third must also be no. Do not infer an answer from installing the plugin, using an agent, or accepting another choice.
+If the answer to question 1 is no, the answer to question 3 is no. Do not infer an answer from the install, from the use of an agent, or from another answer.
 
-Run one non-interactive initialization command with exactly one flag from each pair:
+## 3. Install and initialize (in the background)
 
-- `--learn` or `--no-learn`
-- `--skill-maintenance` or `--no-skill-maintenance`
-- `--background-learning` or `--no-background-learning`
+1. Wait for the CLI install, and check the CLI again as in step 1.
+2. Install the plugin for the agent that you run in, if it is not installed. The plugin adds this skill and the Shadowclone MCP server.
+   - Claude Code: `claude plugin install shadowclone --marketplace theonly1me/shadowclone`
+   - Codex: `codex plugin marketplace add theonly1me/shadowclone`, then `codex plugin add shadowclone@shadowclone`
+   - Cursor, Pi, and Antigravity have no plugin step.
+3. If a plugin command asks for input or fails, give the user the command, and continue the setup.
+4. Start one `shadowclone init` command in the background. Pass exactly one flag from each pair, from the answers:
+   - `--learn` or `--no-learn`
+   - `--skill-maintenance` or `--no-skill-maintenance`
+   - `--background-learning` or `--no-background-learning`
 
-The initialization detects installed Claude Code, Codex, Cursor, and Antigravity environments and installs native guidance for those agents. Preserve an existing configuration instead of replacing its consent choices.
+The command detects Claude Code, Codex, Cursor, Pi, and Antigravity, and installs their native guidance. With `--learn`, it also runs the first learning pass.
 
-## Build
+## 4. Open the skill wizard (while init runs)
 
-1. Start `shadowclone wizard --no-open` as a bounded background process and capture the loopback URL it prints.
-2. Give the URL to the user and keep the process running while they choose skills, inspect instructions, and apply their build.
-3. Do not operate the browser for the user. Wait for them to say they applied the build.
+1. Start `shadowclone wizard` as a background process. It opens the skill wizard in the browser and prints a loopback URL.
+2. Give the user the URL. Tell the user to pick skills, select **Equip**, and tell you when it is done.
+3. Do not operate the browser for the user.
+4. If the wizard says that another update is running, tell the user to wait a few seconds and equip again.
 
-## Verify
+## 5. Verify and report (30 seconds)
 
-After the build is applied:
+When the user equipped a build and `init` is done:
 
-1. Run `shadowclone sync`.
-2. Run `shadowclone doctor` and address actionable local failures.
-3. Run `shadowclone context --explain` in the current repository and summarize which guidance is active without copying private content.
-4. Tell the user to restart each open coding-agent session so its native integration and MCP server reload.
+1. Stop the wizard process.
+2. Run `shadowclone sync`.
+3. Run `shadowclone doctor`. Fix each local failure that you can act on.
+4. Run `shadowclone context --explain` in the current repository.
+5. Tell the user the number of rules learned, the skills that are active, and each step that failed or that you skipped.
+6. If learning stopped at its setup budget and background learning is off, tell the user that `shadowclone learn --deep` continues it for up to 5 minutes.
+7. Tell the user to restart each open coding-agent session. This loads the plugin, the MCP server, and the native guidance.
 
-Do not enable sources, call a model, read sessions, or publish files without the matching consent. Keep command output containing local paths or user content out of shared artifacts.
+Do not turn on a source, call a model, read sessions, or publish files without the matching consent. Keep command output that holds local paths or user content out of shared artifacts.

package/skills/shadowclone-review/SKILL.md

@@ -31,10 +31,12 @@ A pull request needs a review. Run `shadowclone review <number>` in the reposito
    - Compatibility: public APIs, schemas, migrations, configuration, and data that older code reads.
    - Standards: a rule in the standards of the packet that the change breaks.
 3. Each signal rule hit and each new toolchain diagnostic is a candidate with an id, such as `S1` or `T1`. Check each candidate in the code. If it causes a real failure at the head, raise it in a finding and list its id in the candidates field. If not, put its id in dropped with the reason.
-4. When a claim depends on how a library, a framework, or a platform behaves, find its documentation for the version in the lockfile. Search the web and fetch the page. Quote the passage. Do not rely on memory for that behavior.
-5. Give each candidate a fresh subagent with only the claim and its evidence. Tell it to refute the claim from the code and the documentation. If you cannot start a subagent, check the claim again in a new pass that starts from the code.
-6. Keep a candidate only when the refuter could not refute it. Put the reason of the refuter in the refutation field.
-7. Write each finding in short plain sentences, and return the findings as JSON. An empty list is a valid result.
+4. A risky pattern that the change adds is a failure at the head. Examples are open network access, an injection sink, a lock on a live table, and a privileged container. Drop it only when code in the repository makes it safe. A fact outside the code, such as the current network, the table size, or a token scope, does not make it safe.
+5. When a claim depends on how a library, a framework, or a platform behaves, find its documentation for the version in the lockfile. Search the web and fetch the page. Quote the passage. Do not rely on memory for that behavior.
+6. Give each candidate a fresh subagent with only the claim and its evidence. Tell it to refute the claim from the code and the documentation. If you cannot start a subagent, check the claim again in a new pass that starts from the code.
+7. Keep a candidate only when the refuter could not refute it. Put the reason of the refuter in the refutation field.
+8. Raise each defect in its own finding, even when two defects are in the same file or the same step. Put each finding on the changed line that adds the defect. When the failure shows in a caller, quote that caller as evidence.
+9. Write each finding in short plain sentences, and return the findings as JSON. An empty list is a valid result.
 
 Each evidence item has a source, a location, and an exact quote:
 
@@ -64,6 +66,7 @@ Write the text of each finding in Simplified Technical English. Use one idea in
 - Report problems that this change introduces or makes reachable. Leave out problems that existed before the change.
 - Leave out formatting, naming taste, missing comments, questions, praise, and suggestions without a failure.
 - Do not repeat the certain findings in the packet, such as committed credentials or advisories for added dependencies. The command reports them.
+- A linter problem in the certain findings does not replace your own finding. If the change causes a failure that a linter also flags, raise it with your evidence on the line that causes it.
 - Rate severity by the mechanism and by how often a real flow reaches it. Check the defaults that limit the impact.
 
 ## Completion

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

@@ -4,14 +4,17 @@ description: 'Use when writing or editing prose that people read, such as docume
 metadata:
   shadowclone-category: writing
   shadowclone-section: workflow
-  shadowclone-applies-when: when writing prose that people read
+  shadowclone-applies-when: before you write any text that a person reads
   shadowclone-voice: "true"
+  shadowclone-always-on: "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.
+You write or edit any text that a person reads. Examples are a document, a pull request, a commit message, a review comment, a chat reply, and a skill. This skill is always on, so load it before you write.
+
+The rules come from ASD-STE100 Simplified Technical English, at about 80% strictness. Fix every checker error. Fix each warning, or keep it and give a reason. Clarity comes first. If a rule makes the text wrong or unclear, break the rule.
 
 ## Gates
 
@@ -19,7 +22,7 @@ You write or edit text for people: a document, a pull request, a commit message,
 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?
+5. Did you run `scripts/check-ste.mjs` on the text, fix every error, and fix or explain each warning?
 6. Are code, commands, paths, and product names exactly as they were?
 
 ## Process
@@ -33,7 +36,15 @@ Write in the user's voice. Before you write, read `~/.agents/voice.md`. If it do
 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.
+8. Fix every error. For each warning, fix it, or keep it and say why the rule makes the text worse.
+
+For a document, also follow these rules:
+
+- Lead with the result. Put the reason and the detail after it.
+- Write one topic in each paragraph.
+- Name each heading for the task or the answer that the reader needs.
+- Use a table to compare options. Use a numbered list for steps.
+- Link to the text that already exists. Do not repeat it.
 
 ## Example