@shadowclone/cli 0.0.11 → 0.0.12

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +40 -167
  2. package/dist/shadowclone.js +423 -410
  3. package/evals.md +231 -53
  4. package/package.json +1 -1
  5. package/skills/verify-and-review/SKILL.md +1 -1
package/README.md CHANGED
@@ -2,203 +2,76 @@
2
2
 
3
3
  # Shadowclone
4
4
 
5
- Your agents should share your engineering preferences, even across large repositories. Shadowclone maintains the skills, instructions, and checks that help **Claude Code, Codex, Cursor, and Antigravity** work within your guardrails.
6
-
7
- Keep working in your usual agent. Equip workflows, add your own, and let useful corrections improve future sessions. Shadowclone learns from the sessions and memory you enable. You control what it reads, which guidance applies, and what it may change. [Why I built it](docs/motivation.md).
8
-
9
- [Get started](#get-started) · [Agent builds](#agent-builds) · [Learning](#learn-from-your-work) · [Skills](#maintain-your-skills) · [How it works](#how-it-works) · [Privacy](#privacy-comes-first) · [Evaluations](#evaluations)
5
+ Shadowclone maintains the skills, instructions, and checks that help **Claude Code, Codex, Cursor, and Antigravity** follow your engineering preferences. It works with the coding agents you already use and keeps you in control of what it reads and changes.
10
6
 
11
7
  ## Get started
12
8
 
13
- ```bash
14
- npm install -g @shadowclone/cli
15
- shadowclone init
16
- ```
17
-
18
- For model-assisted learning, you need an installed and authenticated `claude`, `codex`, or `cursor-agent` CLI. Shadowclone uses that account and its quota, with no separate API key or Shadowclone account. Antigravity supports capture and native guidance; learning needs one of the other CLIs.
19
-
20
- Setup shows the sources it found and asks what it may read, whether it may maintain your skills, and whether to learn in the background. You can decline any of these. Use `shadowclone init --advanced` to choose sources individually.
21
-
22
- With background learning enabled, setup makes a bounded first pass through recent sessions. Open a new coding-agent session to use the installed guidance. Run `shadowclone doctor` to check the installation and `shadowclone context --explain` from your repository to see which guidance applies.
23
-
24
- ## Agent builds
25
-
26
- Choose and equip skills like putting together a character’s kit in an RPG. Open the browser wizard:
27
-
28
- ```bash
29
- shadowclone wizard
30
- ```
31
-
32
- ![Agent builds showing equipped skills across Craft, Verification, and Autonomy, with a build summary and skill details](docs/assets/agent-builds.jpg)
33
-
34
- Select a skill to read its instructions and decide whether to equip it. Keep a personal build across agents, tailor a private build to a repository, or choose shared repository standards. **Review your build** shows the files that will change before you apply it. You can return and adjust your build at any time.
35
-
36
- **Add your own skills.** Choose **Create a skill**, give it a name, explain when it applies, and write what the agent should do. **Use AI** can help draft the instructions: review the text, provider, and limits before sending, then edit the result before adding it to your build. Applying the build is a separate step.
37
-
38
- <p align="center"><img src="docs/assets/create-skill.jpg" alt="Creating an accessible-interfaces skill with a trigger and editable instructions" width="720"></p>
39
-
40
- Prefer the terminal? Use `shadowclone wizard --cli`. Add `--repo` to open a private repository build or `--no-open` to print the browser URL. Keep the terminal running while using the editor; Ctrl+C stops it. Opening the editor makes no model request. Its optional **Describe my agent with my model** action has its own preview.
41
-
42
- ## Learn from your work
43
-
44
- Run a model-assisted learning pass over your enabled session history:
45
-
46
- ```bash
47
- shadowclone learn --deep
48
- ```
49
-
50
- Shadowclone finds reusable instructions and corrections, compares them with existing guidance, and proposes changes for your review. Accepted learning can update skills within your edit permissions. Each run is bounded; run it again if it reports more history remains.
51
-
52
- Add **`--apply`** to accept proposed learning without the confirmation prompt. Use **`--dry-run`** to preview without applying it; this still calls the model. Deep learning requires your consent and an authenticated agent CLI. Plain `shadowclone learn` indexes and reports locally after setup. A first-time interactive run offers initialization, which can include an authorized first learning pass.
53
-
54
- **Keep learning as you work.** Background learning has its own consent. When enabled, sessions containing reusable guidance can improve future sessions. A temporary exception or an interruption alone does not become a standing preference. Use `shadowclone learning status` to inspect it and `shadowclone learning enable` or `disable` to control it.
55
-
56
- **Record a preference directly** with `shadowclone remember --repo "Use complete variable names."`. Use `--global` for guidance intended for every repository. Recording a preference and publishing it into skills are separate steps; `shadowclone skills pending` and `shadowclone context --explain` show what is active.
57
-
58
- ## Maintain your skills
59
-
60
- Skills are ordinary files you can inspect and edit. Shadowclone reviews the consented library, updates a relevant workflow, or creates a skill when one is missing. Supporting files, unrelated instructions, and invocation settings are preserved.
9
+ Install the CLI:
61
10
 
62
11
  ```bash
63
- shadowclone skills list
64
- shadowclone skills update
65
- shadowclone skills pending
12
+ npm install -g @shadowclone/cli
66
13
  ```
67
14
 
68
- Reading a library and allowing automatic edits are separate choices. Supported changes to authorized user skills can apply automatically. Third-party packages stay unchanged and receive local companion skills. Conflicts and uncertain changes remain pending for review.
69
-
70
- Personal skills use `~/.agents/skills` as their canonical directory. Claude and Antigravity receive copies; Codex and Cursor discover that directory. Repository skills live under `.agents/skills` and `.claude/skills`. `shadowclone sync` propagates a changed maintained copy and preserves conflicting edits for review.
71
-
72
- Every publication has a revision covering its skills, resources, native instructions, and learning decisions. Inspect or undo it with `shadowclone history`, `shadowclone history <revision>`, and `shadowclone undo <revision>`. Undo refuses to overwrite later edits. Existing profile-based installations first need [skills migration](docs/migration.md).
15
+ | Step | Command | What happens | Time |
16
+ | --- | --- | --- | ---: |
17
+ | 1 | `shadowclone init` | Answer three questions about learning and skill maintenance | About 1 minute |
18
+ | 2 | `shadowclone learn --deep` | Learn from enabled past sessions; repeat if more history remains | Up to 5 minutes per run |
19
+ | 3 | `shadowclone wizard` | Choose skills in the browser and review the files before applying them | About 1 minute |
73
20
 
74
- | Command | What it does |
75
- | --- | --- |
76
- | `shadowclone skills` | List bundled preferences and starter skills |
77
- | `shadowclone skills configure --global` / `--repo` | Configure personal or repository skill roots |
78
- | `shadowclone skills automatic on` / `off` | Allow or stop automatic edits without deleting published files |
79
- | `shadowclone skills disable` | Stop library access |
80
- | `shadowclone skills retry <learning-key>` | Queue a record again after resolving its conflict |
81
- | `shadowclone skills exclude <learning-key> "This was a temporary exception."` | Record why guidance should stay unpublished |
82
-
83
- Configuration accepts `--root <directory>` for a custom root and `--third-party` for a package you do not own. Model-assisted updates also require deep-learning consent. After retrying a record, run `shadowclone skills update`. Updates share a default budget of 20 model calls and five minutes, with a cumulative $2 ceiling on engines that support it. Later runs can continue unfinished work.
84
-
85
- ## Set up a repository
86
-
87
- ```bash
88
- shadowclone init --repo
89
- ```
21
+ Setup takes about two to three minutes, excluding learning. Deep learning needs an installed and authenticated `claude`, `codex`, or `cursor-agent` CLI.
90
22
 
91
- Setup asks to read project manifests, detects checks, and previews shared instructions and workflow skills. It asks separately before including personal preferences in files your teammates may see. Review and commit the files you want to share.
23
+ **Skip learning.** Run `shadowclone wizard` by itself if you do not want Shadowclone to read sessions or call a model. It starts from an empty active environment and lets you choose a build locally.
92
24
 
93
- | File | Purpose |
94
- | --- | --- |
95
- | `AGENTS.md` | Shared instructions, selected skills, and verification commands |
96
- | `CLAUDE.md` | Import of the shared instructions |
97
- | `.agents/skills/` and `.claude/skills/` | Repository workflows and selected personal skills |
98
- | `.shadowclone/harness.json` | Configured checks, conventions, and file fingerprints |
25
+ **For coding agents.** Install the CLI, run `shadowclone wizard --no-open`, and give the user the printed local URL. Keep the command running while they edit their build. `shadowclone init` asks consent questions and needs the user.
99
26
 
100
- Run `shadowclone check --changed` to check uncommitted work, or `shadowclone check` for the repository. A local Claude Stop hook runs these checks before the agent finishes. Other agents receive the checks through repository instructions. `shadowclone sync` refreshes the setup while preserving conflicting edits.
27
+ ## Evaluations
101
28
 
102
- Use `--personal` or `--no-personal` to include or exclude applicable personal guidance. Repeat `--skill <name>` to copy selected personal skills with their resources. Use `--no-enforce` to skip the Claude Stop hook. Text outside managed sections stays yours, and edited managed sections are preserved for review. Private builds cannot weaken shared repository requirements. A skill omitted from Shadowclone’s routing may still be discovered through the host agent’s global configuration.
29
+ The preference study tested ordinary coding tasks on GPT-6 Sol, GPT-6 Luna, Sonnet 5.5, and Opus 5.5. Each agent ran with no personal help, with existing skills, with Shadowclone skills, and with Shadowclone skills plus deep learning.
103
30
 
104
- ## How it works
31
+ | Share of preferences followed | GPT-6 Sol | GPT-6 Luna | Sonnet 5.5 | Opus 5.5 |
32
+ | --- | ---: | ---: | ---: | ---: |
33
+ | Agent alone | 72% | 73% | 55% | 57% |
34
+ | With Shadowclone skills | 84% | 83% | 68% | 68% |
35
+ | With Shadowclone skills and deep learning | 97% | 88% | 76% | 82% |
36
+ | Improvement with skills and deep learning | **+25** | **+15** | **+22** | **+25** |
105
37
 
106
- ```text
107
- enabled sessions and memory -> redacted learning -> local evidence records
108
- -> maintain or create skills
109
- skills + small native instructions -> coding agents -> new feedback
110
- ```
38
+ Here is what changed in practice. Each cell compares the agent alone with Shadowclone skills and deep learning.
111
39
 
112
- 1. **Read what you enable.** Shadowclone indexes references to session events without making another transcript archive. It selects user instructions and corrections, with supporting context, and redacts eligible text before learning.
113
- 2. **Decide what is durable.** Explicit reusable guidance can qualify from one session. Inferred patterns need three independent sessions. Existing instructions, manual edits, rejected proposals, and scope constrain what can change.
114
- 3. **Improve the right workflow.** Learning updates a matching skill or creates a missing one. Supported edits follow your write permissions; conflicts and uncertain changes stay pending. Evidence survives even when publication cannot finish.
115
- 4. **Use it in the next session.** A small baseline skill carries shared preferences. Task skills hold detailed procedures, and native agent instructions explain which skills to read. Hooks, MCP, optional subagents, and delegated runs use the same delivery path.
40
+ | Preference | GPT-6 Sol | GPT-6 Luna | Sonnet 5.5 | Opus 5.5 |
41
+ | --- | ---: | ---: | ---: | ---: |
42
+ | Review reply preferences | 2 of 6 → 6 of 6 | 2 of 6 → 6 of 6 | 0 of 6 → 6 of 6 | 0 of 6 → 6 of 6 |
43
+ | Failing test first | 0 of 3 → 3 of 3 | 0 of 3 → 2 of 3 | 0 of 3 → 0 of 3 | 0 of 3 → 2 of 3 |
44
+ | Pull request checklist | 0 of 3 → 3 of 3 | 3 of 3 → 3 of 3 | 0 of 3 → 1 of 3 | 2 of 3 → 3 of 3 |
116
45
 
117
- This changes the guidance an existing model receives, not its weights. It does not guarantee compliance. The baseline and native instruction sections each have a 4 KiB limit, while detailed workflows load when selected. Your evidence and history stay available even when guidance exceeds a delivery limit.
46
+ Skills with deep learning beat the agent alone on all four agents by 15 to 25 points. The gain is statistically clear on GPT-6 Sol and Opus 5.5, and directional on the other two. The participant's existing skills scored in the same range and slightly higher on GPT-6 Luna. [Read the tasks, intervals, and limitations](evals.md).
118
47
 
119
48
  ## Privacy comes first
120
49
 
121
- **There is no Shadowclone collection service or telemetry.** Learning records, revisions, and original-library snapshots stay on your machine. Model work goes through your authenticated agent CLI to its provider, so it is subject to that provider’s account and retention terms. Local storage does not make learning offline.
122
-
123
- **You choose what it reads.** Each source has its own setting and defaults off. Setup shows detected sources before asking for access; advanced setup lets you choose them individually. Reading sessions does not silently enable memory, repository metadata, or skill editing. Before consent, discovery only checks whether a configured source root exists and contains data.
124
-
125
- | Source | What access can include |
126
- | --- | --- |
127
- | Agent sessions | Claude Code sessions and prompt history, Codex sessions, Cursor chats, and Antigravity logs and workspace attribution |
128
- | Memory | Read-only Claude memory for registered repositories; selected native memory can also be frozen for evaluation |
129
- | Instructions and skills | Native agent instructions, repository rules, and consented personal, repository, custom, or third-party skills |
130
- | Shell history | Separately enabled `.zsh_history` and `.bash_history` |
131
- | Git metadata | Remote names used to keep guidance scoped to its repository and owner |
132
- | Repository setup | Known manifests, scripts, dependency names, Makefile targets, workflow files, and top-level entry names |
133
-
134
- The [source inventory](docs/data-handling.md#sources) lists exact paths and settings. Tool-result payloads, tool-returned file contents, thinking blocks, and data-access results are excluded from learning. Enabled transcript parsers can still encounter their bytes while reading the source file.
50
+ **There is no Shadowclone collection service or telemetry.** Learning records, revisions, and original-library snapshots stay on your machine. Model work goes through the authenticated agent CLI you select and is subject to that provider's terms.
135
51
 
136
- **What leaves your machine:**
52
+ **You choose what it reads.** Every capture source is off by default and has its own consent setting. Reading sessions does not silently enable memory, repository metadata, or skill editing.
137
53
 
138
54
  | Operation | What the selected provider can receive |
139
55
  | --- | --- |
140
56
  | Learning and skill maintenance | Selected redacted instructions, steering, and supporting context |
141
- | Browser editor | Nothing merely from opening it; optional AI drafting sends reviewed form fields, and build descriptions have a separate reviewed request |
57
+ | Browser editor | Nothing merely from opening it; optional AI drafting sends reviewed form fields |
142
58
  | Delegated `run` | The authorized task worktree and guidance |
143
- | Evaluation | The chosen repository snapshot and frozen context; judges receive generated code without redaction |
144
-
145
- Redaction catches known secret, host, path, and entropy patterns. It can miss sensitive prose or unusual secrets. Use sources and repositories you are authorized to send to the chosen provider. Native memory stays read-only, third-party packages stay unchanged, and automatic skill edits need separate permission.
146
-
147
- ### Controls for teams and enterprises
148
-
149
- Project guidance stays with its registered repository and verified identity. Organization scope follows the remote owner; global guidance requires an explicit global instruction or decision. Unknown origins stay isolated. A remote-owner identity is a technical boundary and does not prove a legal employer boundary.
59
+ | Evaluation | Synthetic prompts, the tested setup's guidance, and generated code |
150
60
 
151
- Administrators can install a root-owned managed policy to restrict sources, providers, repository origins, hosted learning, and action tiers, or disable Shadowclone. User settings cannot widen those limits. `shadowclone doctor` reports the effective policy. Policies live at `/Library/Application Support/shadowclone/managed.json` on macOS or `/etc/shadowclone/managed.json` on Linux. See the [policy example](docs/architecture/07-enterprise.md#managed-policy).
61
+ **Redaction is a boundary, not an anonymity guarantee.** Tool results, tool-returned file contents, thinking blocks, and data-access results are excluded from learning. Use only sources and repositories you are authorized to send to the selected provider.
152
62
 
153
- The browser editor binds only to loopback, serves local assets, checks request origins, and authenticates its API with an ephemeral token. Learning requests have no tools and use shared call, time, and supported spending limits. Delegated work uses an isolated worktree; local verification has no network or provider credentials. Required isolation must be available before the affected workflow runs.
63
+ **Removal stays in your control.** Disable background learning with `shadowclone learning disable`, stop automatic skill edits with `shadowclone skills automatic off`, or remove recorded state with `shadowclone forget --all`. See [data handling](docs/data-handling.md) and [enterprise controls](docs/architecture/07-enterprise.md) for sources, storage, managed policy, and removal details.
154
64
 
155
- `shadowclone run <task>` authorizes one local worktree, branch, and commit. Remote actions also need a repository policy ceiling and approval for that run. Shared repository instructions require review before personal guidance is included. [Execution controls](docs/architecture/04-acting.md) describe the boundaries in detail.
65
+ ## Guides
156
66
 
157
- **Storage and removal.** State lives under `~/.shadowclone/`, with published skills and instructions in the selected agent or repository directories. Whole transcripts are not copied, but derived records and evaluation evidence can contain sensitive content. Local state is not encrypted; processes with equivalent access and backups may read it. Managed policy governs Shadowclone, not other programs under the account. There is no automatic expiry policy or local model runner.
158
-
159
- Disable background learning with `shadowclone learning disable`, stop automatic skill edits with `shadowclone skills automatic off`, or remove recorded state with `shadowclone forget --all`. Preserve unfinished worktrees first. Conflicting managed edits can block removal. Original transcripts, native memory, provider-retained requests, backups, and remote Git history remain. Repository setup files remain too; use `undo` before deleting revision history or remove them through version control. [Data handling](docs/data-handling.md) and [security reporting](SECURITY.md) cover the full details.
160
-
161
- ## Evaluations
162
-
163
- We measure whether guidance changes an agent’s behavior on the same tasks, keeping preference adherence, correctness, and safety separate. The results below come from the earlier profile-based system. Current skills evaluations compare **Bare**, **original Skills**, **original Skills + Memory**, and **maintained Skills + native routing**, preserving the original library as a baseline.
164
-
165
- **Early preference comparison.** GPT-5.6 Sol at medium reasoning effort completed four TypeScript tasks, once per setup. Each implementation was judged against the same 17 preference checks, with three model votes per check. Bare received repository guidance; Skills added existing personal skills and context; Clone added the Shadowclone profile.
166
-
167
- | Task | Bare | Skills | Clone |
168
- | --- | ---: | ---: | ---: |
169
- | Byte quantities | 11/17 | 14/17 | 15/17 |
170
- | Integer ranges | 15/17 | 14/17 | 16/17 |
171
- | Ordered query parameters | 15/17 | 16/17 | 16/17 |
172
- | Bounded undo/redo | 14/17 | 15/17 | 15/17 |
173
- | Total | 55/68 (80.9%) | 59/68 (86.8%) | 62/68 (91.2%) |
174
-
175
- Clone exceeded Skills on two tasks and tied on two, an aggregate difference of 4.4 percentage points. These are guideline checks, not correctness or productivity scores. Candidate tests were not executed. The sample was small, the personal skills were not optimized for the comparison, and judges made documented mistakes around assertions and test setup. The recorded scores have not been silently corrected.
176
-
177
- Later guidance-and-memory comparisons were mixed. After one explicitly directed reference correction, Shadowclone scored 9/10 on preferences and 8/8 on shared-memory checks; native memory scored 10/10 and 6/8. Shadowclone still used a prohibited cast and changed files outside the task. The conditions had different reference content, and runtime correctness remained unverified. These results do not establish autonomous repair or general superiority. [Later comparison details](docs/design/021-guidance-evaluation.md#recorded-comparisons).
178
-
179
- **Repository setup pilot.** Claude Code ran the same task with and without repository setup on two synthetic projects. Both arms passed held-out acceptance checks and the project gate, and neither committed. On the Python project, the baseline skipped a test while the configured agent added one. This was one run per arm per project, so it demonstrates a working practice in that sample, not a general improvement.
180
-
181
- Read [the full methods, task specifications, scores, and known judging issues](evals.md). The [evaluation guide](docs/architecture/09-evaluation.md) explains running your own comparison, isolation, explicit spending limits, and recovery. Successful migration or skill publication alone is not evidence of improved behavior.
182
-
183
- ## Built with agents
184
-
185
- I built Shadowclone without writing code by hand. Agents wrote the implementation; I set the requirements, engineering preferences, and guardrails. To me, that is still engineering. This repository has more than 800 source and test files. Ask your agent to review its architecture, code quality, and tests, then judge the result for yourself. [Why I built it and what it solves](docs/motivation.md).
186
-
187
- <details><summary>More commands</summary>
188
-
189
- | Command | Purpose |
67
+ | Guide | Use it to |
190
68
  | --- | --- |
191
- | `shadowclone import` | Refresh consented repository guidance as evidence |
192
- | `shadowclone recall <query>` | Search available scoped references |
193
- | `shadowclone install --agent all --global` | Install native guidance manually |
194
- | `shadowclone install --agent <agent> --local` | Install guidance for this repository without shared setup |
195
- | `shadowclone uninstall --global` / `--local` | Remove owned integrations in the selected scope |
196
- | `shadowclone migrate skills` | Preview migration from an older profile installation |
197
- | `shadowclone mcp` | Serve context and maintenance tools to a connected agent |
198
-
199
- Supported agent identifiers are `claude-code`, `codex`, `cursor`, and `antigravity`. Optional local Claude subagents use `--subagent`; automatic delegation is a separate `--auto-delegate` choice. Run `shadowclone --help` for the command reference.
200
-
201
- </details>
69
+ | [Agent builds](docs/guides/agent-builds.md) | Choose, create, and equip skills |
70
+ | [Learning](docs/guides/learning.md) | Run deep learning, background learning, or record a preference |
71
+ | [Skill maintenance](docs/guides/skills.md) | Review updates, conflicts, history, and undo |
72
+ | [Repository setup](docs/guides/repositories.md) | Share checks and skills with a repository |
73
+ | [How it works](docs/guides/how-it-works.md) | Follow guidance from consented evidence to coding agents |
74
+ | [Command reference](docs/guides/commands.md) | Find everyday and advanced commands |
202
75
 
203
76
  **Further reading:** [Documentation index](docs/README.md) · [Architecture](docs/architecture/README.md) · [Design history](docs/design/README.md) · [Migration](docs/migration.md) · [Contributing](CONTRIBUTING.md) · [Security](SECURITY.md)
204
77