docks-kit 0.24.0 → 0.26.0
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.
- package/AGENTS.md +21 -136
- package/README.md +54 -9
- package/cli/dist/docks-kit.js +24688 -0
- package/cli/docs/command-guards.md +1 -1
- package/cli/docs/install.md +30 -9
- package/cli/docs/omp-context.md +1 -1
- package/cli/docs/omp-models.md +5 -4
- package/cli/docs/sync-layers.md +46 -75
- package/cli/docs/toolchain.md +4 -5
- package/cli/src/agentDocs/agentFirstCheck.ts +786 -0
- package/cli/src/agentDocs/bridgeCheck.ts +226 -0
- package/cli/src/agentDocs/commands.ts +63 -0
- package/cli/src/agentDocs/prTemplate.ts +211 -0
- package/cli/src/agentDocs/services.ts +202 -0
- package/cli/src/agentDocs/shared.ts +730 -0
- package/cli/src/agentDocs/verifySkill.ts +136 -0
- package/cli/src/argv.ts +25 -1
- package/cli/src/commands/agentDocs.ts +29 -0
- package/cli/src/commands/plan.ts +29 -0
- package/cli/src/commands/skill.ts +29 -0
- package/cli/src/commands/update.ts +90 -31
- package/cli/src/engine-native/DESIGN.md +5 -6
- package/cli/src/engine-native/engineCtx.ts +0 -3
- package/cli/src/engine-native/failures.ts +2 -2
- package/cli/src/engine-native/ompChild.ts +1 -1
- package/cli/src/engine-native/ompKitPlugin.ts +7 -16
- package/cli/src/engine-native/ompPlugins.ts +205 -221
- package/cli/src/engine-native/ompSync.ts +5 -14
- package/cli/src/generated/sotPayload.ts +308 -12
- package/cli/src/main.ts +12 -3
- package/cli/src/plan/bytes.ts +110 -0
- package/cli/src/plan/checkout.ts +341 -0
- package/cli/src/plan/commands.ts +1192 -0
- package/cli/src/plan/github.ts +816 -0
- package/cli/src/plan/records.ts +623 -0
- package/cli/src/plan/repository.ts +53 -0
- package/cli/src/plan/reviews.ts +292 -0
- package/cli/src/plan/services.ts +256 -0
- package/cli/src/plan/types.ts +164 -0
- package/cli/src/skills/commands.ts +142 -0
- package/cli/src/skills/config.json +30 -0
- package/cli/src/skills/files.ts +74 -0
- package/cli/src/skills/frontmatter.ts +148 -0
- package/cli/src/skills/guard.ts +366 -0
- package/cli/src/skills/kitGate.ts +406 -0
- package/cli/src/skills/rubric.ts +143 -0
- package/cli/tsconfig.json +1 -0
- package/package.json +7 -4
- package/cli/src/engine-native/ompMarketplace.ts +0 -140
|
@@ -10,7 +10,7 @@ The policy keeps only deny rules. Where omp's critical-command check acts,
|
|
|
10
10
|
the form is denied. omp also denies a `$` or a backtick after `git push`,
|
|
11
11
|
because the agent can always write the ref literally.
|
|
12
12
|
|
|
13
|
-
By owner decision (0.22.8, #126), the kit ships no omp
|
|
13
|
+
By owner decision (0.22.8, DocksDocks/public#126), the kit ships no omp
|
|
14
14
|
prompt rule. The kit's `bash.patterns` holds only deny rules and the `trash *`
|
|
15
15
|
allow. Under omp's default `tools.approvalMode: yolo`, omp runs every
|
|
16
16
|
command that no deny matches without a question, in the main session and in
|
package/cli/docs/install.md
CHANGED
|
@@ -6,8 +6,8 @@ Hosts outside this matrix fail before a launcher can fall back to Bun source.
|
|
|
6
6
|
## 1. Repo checkout (development / current users)
|
|
7
7
|
|
|
8
8
|
```
|
|
9
|
-
git clone https://github.com/DocksDocks/
|
|
10
|
-
cd ~/projects/
|
|
9
|
+
git clone https://github.com/DocksDocks/docks-kit.git ~/projects/docks-kit
|
|
10
|
+
cd ~/projects/docks-kit
|
|
11
11
|
./docks-kit sync
|
|
12
12
|
```
|
|
13
13
|
|
|
@@ -17,6 +17,23 @@ version matches `package.json`. It then falls back to Bun-from-source and
|
|
|
17
17
|
auto-installs Bun plus `node_modules` when needed. Each launcher reports and
|
|
18
18
|
bypasses an ignored stale build.
|
|
19
19
|
|
|
20
|
+
### Move a checkout of DocksDocks/public
|
|
21
|
+
|
|
22
|
+
The kit moved from DocksDocks/public to DocksDocks/docks-kit. To move a
|
|
23
|
+
checkout of DocksDocks/public, run these commands from the checkout's root:
|
|
24
|
+
|
|
25
|
+
```
|
|
26
|
+
git remote set-url origin https://github.com/DocksDocks/docks-kit.git
|
|
27
|
+
./docks-kit update # Linux and macOS
|
|
28
|
+
.\docks-kit.ps1 update # Windows
|
|
29
|
+
./docks-kit sync # Linux and macOS
|
|
30
|
+
.\docks-kit.ps1 sync # Windows
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
The update pulls from DocksDocks/docks-kit. The sync then deploys the skills
|
|
34
|
+
with their new report target: a launcher that runs a fresh compiled binary
|
|
35
|
+
skips the sync that the update chains. A global npm install needs nothing.
|
|
36
|
+
|
|
20
37
|
## 2. Global via Bun
|
|
21
38
|
|
|
22
39
|
```
|
|
@@ -26,8 +43,11 @@ docks-kit sync
|
|
|
26
43
|
bunx docks-kit toolchain check
|
|
27
44
|
```
|
|
28
45
|
|
|
29
|
-
The npm package
|
|
30
|
-
|
|
46
|
+
The npm package runs one minified JavaScript bundle of the CLI and its generated
|
|
47
|
+
in-memory payload (`cli/dist/docks-kit.js`) — releases are versioned config
|
|
48
|
+
snapshots without publishing the authoring `SoT/` tree. Identifiers stay
|
|
49
|
+
unminified, so a stack trace keeps its names; the source map is a GitHub
|
|
50
|
+
release asset (`docks-kit.js.map`), matched by the bundle's `//# debugId=` line.
|
|
31
51
|
Kit-home resolution remains available for checkout/package update behavior and
|
|
32
52
|
display paths, but sync reads do not depend on it.
|
|
33
53
|
|
|
@@ -49,7 +69,7 @@ a copy that lags behind the pinned release.
|
|
|
49
69
|
## 3. curl installer (POSIX)
|
|
50
70
|
|
|
51
71
|
```
|
|
52
|
-
tmp="$(mktemp)" && curl -fsSL https://raw.githubusercontent.com/DocksDocks/
|
|
72
|
+
tmp="$(mktemp)" && curl -fsSL https://raw.githubusercontent.com/DocksDocks/docks-kit/main/install.sh -o "$tmp" && bash "$tmp"; rc=$?; rm -f "$tmp"; (exit "$rc")
|
|
53
73
|
```
|
|
54
74
|
|
|
55
75
|
Download-then-run, never `curl | bash` — stream truncation has bitten this
|
|
@@ -61,7 +81,7 @@ installer below.
|
|
|
61
81
|
## 4. PowerShell installer (Windows)
|
|
62
82
|
|
|
63
83
|
```powershell
|
|
64
|
-
Invoke-WebRequest https://raw.githubusercontent.com/DocksDocks/
|
|
84
|
+
Invoke-WebRequest https://raw.githubusercontent.com/DocksDocks/docks-kit/main/install.ps1 -OutFile "$env:TEMP\docks-kit-install.ps1"
|
|
65
85
|
powershell.exe -NoProfile -ExecutionPolicy Bypass -File "$env:TEMP\docks-kit-install.ps1"
|
|
66
86
|
Remove-Item "$env:TEMP\docks-kit-install.ps1"
|
|
67
87
|
```
|
|
@@ -108,9 +128,10 @@ worktree and an upstream; `git pull --ff-only`, then re-runs
|
|
|
108
128
|
`bun install --frozen-lockfile` when the pull changed `bun.lock` or
|
|
109
129
|
`package.json`); a kit home under `node_modules` is a global package
|
|
110
130
|
(`bun add -g` / `npm install -g docks-kit@latest`). The chained sync is a
|
|
111
|
-
plain flag-less `docks-kit sync`. It refreshes
|
|
112
|
-
|
|
113
|
-
run `docks-kit sync --skip-plugin-refresh` to
|
|
131
|
+
plain flag-less `docks-kit sync`. It also refreshes plugins, even when the kit
|
|
132
|
+
is already current: it moves `pi-intercom` to its pinned version. Pass
|
|
133
|
+
`--no-sync`, then run `docks-kit sync --skip-plugin-refresh` to keep a present
|
|
134
|
+
`pi-intercom` at its installed version.
|
|
114
135
|
A compiled binary inside a checkout updates the checkout; on the next invocation
|
|
115
136
|
the launcher bypasses that now-stale binary and uses updated source until rebuilt.
|
|
116
137
|
Every `docks-kit sync` except `--dry-run` also does a best-effort behind-upstream
|
package/cli/docs/omp-context.md
CHANGED
|
@@ -124,7 +124,7 @@ keys carries a kit value that differs from the default omp already applies.
|
|
|
124
124
|
|
|
125
125
|
## omp 19.0.0 tools and returned overrides
|
|
126
126
|
|
|
127
|
-
The owner made these decisions on 2026-11-19 (#184). They apply from 0.24.0.
|
|
127
|
+
The owner made these decisions on 2026-11-19 (DocksDocks/public#184). They apply from 0.24.0.
|
|
128
128
|
|
|
129
129
|
### Tools that the kit turns on
|
|
130
130
|
|
package/cli/docs/omp-models.md
CHANGED
|
@@ -128,14 +128,15 @@ What omp's settings catalog establishes about these roles:
|
|
|
128
128
|
model for every reviewer. `task.agentServiceTierOverrides` sets the same four
|
|
129
129
|
agents to `inherit`, so they take the live tier of the main session for each
|
|
130
130
|
provider. "OpenAI fast mode" below describes how that tier changes. The bundled
|
|
131
|
-
`reviewer` and `security-reviewer` agents ship with omp, and the
|
|
132
|
-
`
|
|
131
|
+
`reviewer` and `security-reviewer` agents ship with omp, and the kit plugin
|
|
132
|
+
`docks-kit-omp` ships `code-reviewer` and `plan-reviewer`.
|
|
133
133
|
`retry.fallbackChains.reviewer` holds `anthropic/claude-opus-5-5:high`, and
|
|
134
134
|
`retry.fallbackChains.task` holds `openai-codex/gpt-6.2-sol:high`; both are
|
|
135
135
|
cross-vendor fallbacks.
|
|
136
136
|
|
|
137
137
|
The review benchmark of DocksDocks/public#130 ran on 2026-11-05. It used 24
|
|
138
|
-
held-out cases of the
|
|
138
|
+
held-out cases of the `review-benchmark` skill, 2 runs each. The cases came
|
|
139
|
+
from DocksDocks/docks, the source repository of that skill at the time.
|
|
139
140
|
It compared `gpt-6.1-sol` and `gpt-6.1-terra` at `high`, each on the `default`
|
|
140
141
|
and `priority` tiers. The user set the effort `high`; the benchmark chose the
|
|
141
142
|
model. `gpt-6.1-terra` on `default` let the fewest known defects escape (34.90
|
|
@@ -522,7 +523,7 @@ At `high`, Sol produces about 19% more tokens per second than Terra. At
|
|
|
522
523
|
`xhigh`, the gain is about 24%. Sol also has the lower TTFT and end-to-end
|
|
523
524
|
time at both levels.
|
|
524
525
|
|
|
525
|
-
The `reviewer` role stays on GPT-6.1 Terra `high`. The #130 benchmark chose
|
|
526
|
+
The `reviewer` role stays on GPT-6.1 Terra `high`. The DocksDocks/public#130 benchmark chose
|
|
526
527
|
Terra by escaped defects, not by speed. omp 18.22.2 lists no GPT-6.2 Terra. A
|
|
527
528
|
move of the reviewer to GPT-6.2 Sol needs a new benchmark.
|
|
528
529
|
|
package/cli/docs/sync-layers.md
CHANGED
|
@@ -25,83 +25,53 @@ retired in 0.22.8), config.yml keys whose deployed value still equals the value
|
|
|
25
25
|
ship, `providers.webSearchOrder` at any value, and the retired
|
|
26
26
|
`providers.anthropic.modelOverrides.claude-opus-5-5` block in models.yml while
|
|
27
27
|
it still matches the shipped block.
|
|
28
|
-
Directories are mode 0700 and files mode 0600. Then the
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
`SoT/toolchain.json` pin
|
|
32
|
-
marketplace row counts as installed only when its `scope` is `user`, so a repeat
|
|
33
|
-
run is a no-op and a project-only row still installs. When just the legacy
|
|
34
|
-
config-root registry lists `docks`, omp copies it forward itself: the sync runs
|
|
35
|
-
`marketplace update`, or the read-only `marketplace list` under
|
|
36
|
-
`--skip-plugin-refresh`, which keeps installs but fetches nothing. After a
|
|
37
|
-
plugin operation, the sync reads the inventory again and prints one line that
|
|
38
|
-
names each plugin with its version change, for example
|
|
39
|
-
`omp plugins synced: docks@docks 0.21.1 -> 0.22.0, pi-intercom 0.14.0 (new), docks-kit-omp linked`.
|
|
28
|
+
Directories are mode 0700 and files mode 0600. Then the plugin pass reads the
|
|
29
|
+
inventory from `omp plugin list --json`, tries to retire the former marketplace
|
|
30
|
+
plugins (user-scope installs only; see below), installs `pi-intercom` at its
|
|
31
|
+
`SoT/toolchain.json` pin, and links the kit plugin `docks-kit-omp`.
|
|
40
32
|
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
`omp plugin docks@docks 0.21.1 -> 0.22.0: running omp sessions lose its plugin agents until they run /reload-plugins and read its skills again through skill:// (restart omp instead when the plugin ships hooks, extension modules, or non-MCP tools).`
|
|
48
|
-
The next step then says
|
|
49
|
-
`Run /reload-plugins in each running omp session, then read each plugin skill again through skill://. Restart omp instead when an upgraded plugin ships hooks, extension modules, or non-MCP tools.`
|
|
50
|
-
A version-changing upgrade does not set the restart trigger. Each other plugin
|
|
51
|
-
operation sets it: an install, a reinstall at the same version, an npm install,
|
|
52
|
-
or a link. A changed kit plugin file or omp config file also sets it. The
|
|
53
|
-
restart next step `Restart omp to load any refreshed plugins, skills, or tools.`
|
|
54
|
-
then prints next to the upgrade rule.
|
|
33
|
+
The kit plugin now ships the docks and plan-lifecycle skills, the
|
|
34
|
+
`code-reviewer` and `plan-reviewer` agents, and the `verify-gate` and
|
|
35
|
+
`context-tree-nudge` extensions. So sync installs no plugin from the `docks`
|
|
36
|
+
marketplace. Each real sync tries to retire the former marketplace plugins.
|
|
37
|
+
When the inventory cannot be read, it warns and skips this step; a later sync
|
|
38
|
+
tries again. Otherwise:
|
|
55
39
|
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
`
|
|
61
|
-
|
|
62
|
-
|
|
40
|
+
- For each of `docks@docks` and `plan-lifecycle@docks` with a `scope: "user"`
|
|
41
|
+
inventory row, it runs `omp plugin uninstall --scope user <id>`.
|
|
42
|
+
- For each `scope: "project"` row of these ids, it changes nothing in that
|
|
43
|
+
project and warns
|
|
44
|
+
`omp plugin <id> is installed at project scope and docks-kit no longer ships it; run from that project: omp plugin uninstall --scope project <id>`.
|
|
45
|
+
- When no user uninstall failed, it runs `omp plugin marketplace remove docks`
|
|
46
|
+
if the active registry (`<data root>/marketplaces.json`) lists `docks`, or
|
|
47
|
+
if no active registry exists and the legacy config-root registry lists it.
|
|
48
|
+
omp copies the legacy registry forward only when no active registry exists,
|
|
49
|
+
so a legacy entry beside an active registry is stale and starts no command.
|
|
50
|
+
- A failed uninstall or removal goes to the failure ledger with the manual
|
|
51
|
+
command, for example
|
|
52
|
+
`omp plugin operation failed for docks@docks: <detail>; run manually: omp plugin uninstall --scope user docks@docks`.
|
|
53
|
+
- When the inventory cannot be read, the sync warns
|
|
54
|
+
`omp plugin inventory unavailable — retirement of the docks marketplace plugins skipped until the next sync; pi-intercom and the kit plugin take the full refresh path`.
|
|
55
|
+
- The sync removes the folder `~/.cache/docks-kit/omp-plugin-upgrades/` of the
|
|
56
|
+
retired plugin upgrade log when it exists.
|
|
63
57
|
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
Each upgrade of a present marketplace plugin then counts as a change. It gets
|
|
68
|
-
the warning and an event with the after version `unknown`, for example
|
|
69
|
-
`docks@docks 0.21.1 -> unknown`.
|
|
58
|
+
`--skip-plugin-refresh` does not skip the retirement or the kit plugin link. It
|
|
59
|
+
only keeps a present `pi-intercom` at its installed version. A repeat run after
|
|
60
|
+
a successful retirement runs no uninstall and no removal.
|
|
70
61
|
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
`omp
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
62
|
+
After a plugin operation, the sync prints one line that names each operation,
|
|
63
|
+
for example
|
|
64
|
+
`omp plugins synced: docks@docks uninstalled, plan-lifecycle@docks uninstalled, docks marketplace removed, pi-intercom 0.14.0 (new), docks-kit-omp linked`.
|
|
65
|
+
Each uninstall sets the restart next step
|
|
66
|
+
`Restart omp to load any refreshed plugins, skills, or tools.`, because the
|
|
67
|
+
retired plugins ship extensions, and omp loads extensions only at startup. An
|
|
68
|
+
npm install, a link, and a changed kit plugin file or omp config file also set
|
|
69
|
+
it.
|
|
77
70
|
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
says that the plugin agents of the session may fail. It tells the agent to ask
|
|
83
|
-
the user to run `/reload-plugins`. It then tells the agent to read each plugin
|
|
84
|
-
skill again through `skill://` before it runs a skill script. It asks for a
|
|
85
|
-
restart instead when an upgraded plugin ships hooks, extension modules, or
|
|
86
|
-
non-MCP tools. A folder or file that the extension cannot read gives no
|
|
87
|
-
reminder for that tool result. The next tool result reads it again.
|
|
88
|
-
These limits apply:
|
|
89
|
-
|
|
90
|
-
- omp imports extension modules only at startup. An omp process that started
|
|
91
|
-
before a sync deployed `pluginUpgrades.ts` did not load it. Its sessions get
|
|
92
|
-
no reminder, also for the upgrades of that sync.
|
|
93
|
-
- An upgrade that `docks-kit sync` did not run gives no reminder, for example
|
|
94
|
-
`omp plugin upgrade` by hand.
|
|
95
|
-
- The warning, the next step, and the reminder assume that the session loaded
|
|
96
|
-
the user-scope install. omp keeps an old cache folder that a known project
|
|
97
|
-
registry still uses. So a session on a project-scope install keeps its
|
|
98
|
-
folder. For this reason, the reminder says "may".
|
|
99
|
-
- An omp process that started during the upgrade can get a reminder that it
|
|
100
|
-
does not need. A reload or a restart is harmless.
|
|
101
|
-
- The log keeps the newest 100 events. A session that stays idle through more
|
|
102
|
-
than 100 later upgrades loses the oldest ones.
|
|
103
|
-
|
|
104
|
-
A dry run invokes no omp subcommand and writes no upgrade event.
|
|
71
|
+
A dry run invokes no omp subcommand. It prints
|
|
72
|
+
`[dry-run] omp plugin uninstall --scope user docks@docks` and the same line
|
|
73
|
+
for `plan-lifecycle@docks`, and
|
|
74
|
+
`[dry-run] omp plugin marketplace remove docks` when a registry lists `docks`.
|
|
105
75
|
|
|
106
76
|
Paths mirror upstream `dirs.ts` `DirResolver`, resolved from the environment
|
|
107
77
|
plus directory probes, so a dry run still runs no omp subcommand. The agent
|
|
@@ -120,6 +90,7 @@ into `<agent directory>/intercom`. Otherwise it goes into
|
|
|
120
90
|
## Additive by default
|
|
121
91
|
|
|
122
92
|
Sync has no removal flag. A key, plugin, or file that only the user added
|
|
123
|
-
stays.
|
|
124
|
-
retired-key inventory above,
|
|
125
|
-
|
|
93
|
+
stays. Three passes remove kit content on every sync: the `ompRemovals.ts`
|
|
94
|
+
retired-key inventory above, the kit plugin pass, which removes stale files
|
|
95
|
+
from the kit-owned `~/.docks-kit/omp-plugin`, and the retirement of the former
|
|
96
|
+
marketplace plugins above, which earlier kit versions installed.
|
package/cli/docs/toolchain.md
CHANGED
|
@@ -35,11 +35,10 @@ Every kit-driven package install from npm, GitHub releases, or
|
|
|
35
35
|
`omp install` is pinned to a `SoT/toolchain.json` `verified` version — never
|
|
36
36
|
floating `@latest` (the npm-worm / Shai-Hulud attack surface). That includes
|
|
37
37
|
the release workflow (actions pinned to commit SHAs, exact bun/npm versions).
|
|
38
|
-
The
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
manifest pin first.
|
|
38
|
+
The kit installs no omp marketplace plugin: the kit plugin ships from this
|
|
39
|
+
repository, and sync tries to retire the user-scope installs of the former `docks` marketplace plugins (see
|
|
40
|
+
`sync-layers`). Any new install surface, a new marketplace or plugin source
|
|
41
|
+
included, needs a manifest pin first.
|
|
43
42
|
|
|
44
43
|
The kit's own package is the single exemption from the `@latest` ban. `install.sh` and `install.ps1`
|
|
45
44
|
end with `bun add -g docks-kit@latest` because a global installer that pinned
|