docks-kit 0.25.0 → 0.27.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 +12 -10
- package/README.md +40 -30
- package/cli/dist/docks-kit.js +24701 -0
- package/cli/docs/command-guards.md +8 -5
- package/cli/docs/install.md +41 -32
- package/cli/docs/omp-context.md +1 -1
- package/cli/docs/omp-models.md +1 -1
- package/cli/docs/overview.md +3 -3
- package/cli/docs/platforms.md +8 -8
- 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 -66
- package/cli/src/engine-native/DESIGN.md +10 -9
- package/cli/src/engine-native/os/targets.ts +6 -19
- package/cli/src/engine.ts +0 -6
- package/cli/src/generated/sotPayload.ts +51 -79
- package/cli/src/kitHome.ts +7 -10
- package/cli/src/main.ts +12 -4
- package/cli/src/plan/bytes.ts +110 -0
- package/cli/src/plan/checkout.ts +379 -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/docks-kit +9 -40
- package/docks-kit.ps1 +10 -61
- package/package.json +10 -8
package/AGENTS.md
CHANGED
|
@@ -10,7 +10,7 @@ Portable configuration kit for AI coding agents. The kit manages one coding harn
|
|
|
10
10
|
|
|
11
11
|
omp uses this `AGENTS.md` file plus the omp SoT under `SoT/.omp/`.
|
|
12
12
|
|
|
13
|
-
docks-kit
|
|
13
|
+
docks-kit host support covers Linux x64/arm64, macOS arm64, and Windows x64. Hosts outside this matrix fail before either launcher runs the Bun source.
|
|
14
14
|
|
|
15
15
|
## Context tree
|
|
16
16
|
|
|
@@ -26,19 +26,19 @@ Per-folder conventions live in nested `AGENTS.md` nodes. An agent can load only
|
|
|
26
26
|
|
|
27
27
|
| Path | Purpose |
|
|
28
28
|
|------|---------|
|
|
29
|
-
| `docks-kit` / `docks-kit.ps1` | POSIX and Windows CLI launchers.
|
|
29
|
+
| `docks-kit` / `docks-kit.ps1` | POSIX and Windows CLI launchers. Each rejects a host outside the support matrix, then runs the checkout source with Bun and auto-installs Bun plus `node_modules` when they are missing. A launcher never runs a file in `cli/dist/`. |
|
|
30
30
|
| `.oxlintrc.json` / `bunfig.toml` | Mechanical lint (correctness, suspicious, eqeqeq, no-var, prefer-const, no-unused) and the `bun fmt` code format settings (`[fmt]`) |
|
|
31
31
|
| `cli/` | Effect 4 CLI + bundled docs topics |
|
|
32
32
|
| `SoT/toolchain.json` | Toolchain floors manifest (verified pins consumed by EngineNative; optional `upstream` source read by `docks-kit toolchain outdated`) |
|
|
33
33
|
| `SoT/.omp/` | Kit-owned omp SoT: `AGENTS.md`, `config.yml`, `models.yml`, `mcp.json`, `intercom.json`, and the kit plugin source `plugin/` |
|
|
34
34
|
| `install.sh` / `install.ps1` | POSIX and Windows global installers. Each installer stops on a host outside the support matrix before it downloads anything. |
|
|
35
|
-
| `.github/workflows/release-cli.yml` | `cli-v*` release:
|
|
35
|
+
| `.github/workflows/release-cli.yml` | `cli-v*` release: attaches the bundle's source map `docks-kit.js.map` to the GitHub release and publishes the npm package with provenance |
|
|
36
36
|
| `README.md` | Front door |
|
|
37
|
-
| `package.json` / `bun.lock` | npm package: `bin` = `cli/
|
|
37
|
+
| `package.json` / `bun.lock` | npm package: `bin` = `cli/dist/docks-kit.js`, a minified bundle of the CLI and the generated in-memory SoT payload that `prepack` builds (`bun run build:bundle`); `cli/src` ships too, for the checkout launchers |
|
|
38
38
|
| `docs/PLAN.md` | Plan pointer and project plan rules. The plan record is a GitHub issue; no plan markdown is tracked. `docs/AGENTS.md` routes to it. |
|
|
39
39
|
| `AGENTS.md` | This file — tool-agnostic instructions |
|
|
40
40
|
|
|
41
|
-
Module map for `cli/` (engine axes, commands, kit store, test fixtures, and the
|
|
41
|
+
Module map for `cli/` (engine axes, commands, kit store, test fixtures, and the build scripts): `cli/AGENTS.md`.
|
|
42
42
|
|
|
43
43
|
SoT notes (the shared prompt authorization, the omp deploy targets, the config and model merges, the retired inventories, the role map, the kit plugin sync, and the cleanup scope): `cli/AGENTS.md` (`### SoT notes`).
|
|
44
44
|
|
|
@@ -67,12 +67,14 @@ SoT notes (the shared prompt authorization, the omp deploy targets, the config a
|
|
|
67
67
|
- **Exemption: the kit's own package.** `install.sh` and `install.ps1` end with `bun add -g docks-kit@latest`, because a global installer that pinned itself would install a fixed old kit forever, and pinning it to `package.json` would request an unpublished version between the release-prep commit and the npm publish. The `@latest` exemption covers `docks-kit` alone. Both installers still pin the Bun installer they download to the manifest's verified version. `cli/test/unit/hostTargets.test.ts` asserts that pin in all four launcher and installer scripts, and `cli/test/unit/install.test.ts` proves `install.sh` passes it to the Bun installer. Any new install surface, a new marketplace or plugin source included, needs a manifest pin first.
|
|
68
68
|
## Testing
|
|
69
69
|
|
|
70
|
-
Run `bun run check` before and after each change: oxlint, `lint:effect` (Effect rules through `effect-tsgo diagnostics --strict`), `bun fmt --check`, `bun check`, the generated-payload check (`check:generated`), unit tests, and both golden suites. Scripts: `lint`, `lint:effect`, `format:check`, `typecheck`, `check:generated`, `test:unit`, `test:integration` (goldens), `test`, `format`; CI runs `check` on pushes to `main` and on pull requests with Bun 1.4.
|
|
70
|
+
Run `bun run check` before and after each change: oxlint, `lint:effect` (Effect rules through `effect-tsgo diagnostics --strict`), `bun fmt --check`, `bun check`, the generated-payload check (`check:generated`), unit tests, and both golden suites. Scripts: `lint`, `lint:effect`, `format:check`, `typecheck`, `check:generated`, `test:unit`, `test:integration` (goldens), `test`, `format`; CI runs `check` on pushes to `main` and on pull requests with Bun 1.4.5. Prove-red modes must exit non-zero after detecting planted mismatches. The golden writer emits two-space JSON that `bun fmt` re-serializes, so run `bun run format` after `--update-goldens` or `format:check` fails. For Effect diagnostics in the editor, set the TypeScript language server command to `node_modules/.bin/effect-tsgo tsc --lsp --stdio`. Keep the `@effect/language-service` plugin entry in `cli/tsconfig.json`: without it, `lint:effect` checks no file and passes. Also verify user-facing changes via `./docks-kit sync --dry-run` and `bun run smoke:package`.
|
|
71
71
|
|
|
72
72
|
Use direct acceptance and focused regressions while iterating, then run the full unit/golden gate once at the pre-commit or release boundary. Reuse still-matching evidence; a later relevant edit invalidates only the affected rung and final gate, not every prior check.
|
|
73
73
|
|
|
74
74
|
Spawning-suite bundle and `DOCKS_KIT_TEST_CLI_ENTRY`: `cli/AGENTS.md`.
|
|
75
75
|
|
|
76
|
+
`test:unit` also runs the vitest project `review-benchmark` on Linux only, because its `keys.mjs` needs GNU tar and one test needs the util-linux `script` command. It needs `git`, `gpg`, GNU tar, and full history with `origin/main`; run `git fetch --unshallow` in a shallow clone. Its fixtures are real omp transcripts: after a raise of the omp `verified` pin in `SoT/toolchain.json`, capture new fixtures as `.agents/skills/review-benchmark/SKILL.md` says. `test:unit:portable` runs the `unit` and `backstop` projects only; the `portable` CI job and the release gate `test:ci` use it, because their checkouts are shallow and the `check` job already runs the suite.
|
|
77
|
+
|
|
76
78
|
## Landing changes
|
|
77
79
|
|
|
78
80
|
Open a pull request when the change can alter what CI proves: `cli/`, `SoT/`, `.github/`, the launchers, the installers, `package.json`, `bun.lock`. Wait for every reported check to finish, then ask before merge. A failed or cancelled check blocks the merge. Push direct to `main` only for prose: root Markdown and code comments.
|
|
@@ -87,8 +89,8 @@ Project-skill authoring rules (scope, canonical layout, vendored `unslop`, citat
|
|
|
87
89
|
|
|
88
90
|
## Kit plugin content
|
|
89
91
|
|
|
90
|
-
`SoT/.omp/plugin/` holds skills at `skills/<name>/SKILL.md`, task agents at `agents/<name>.md`, and the extensions that `package.json` `omp.extensions` names. It ships the 32 docks and plan-lifecycle skills, the `workspace-hygiene` skill, the `code-reviewer` and `plan-reviewer` agents, the `hygiene`, `verify-gate`, and `context-tree-nudge` extensions, the trigger rules in `rules/`, and the `/cleanup` command. A skill reports a problem in DocksDocks/
|
|
91
|
-
After a skill edit, run `bun cli/scripts/skill-content-hash.ts --write` to refresh its `metadata.content_hash` and `metadata.updated`; `--check` names each stale skill. The
|
|
92
|
+
`SoT/.omp/plugin/` holds skills at `skills/<name>/SKILL.md`, task agents at `agents/<name>.md`, and the extensions that `package.json` `omp.extensions` names. It ships the 32 docks and plan-lifecycle skills, the `workspace-hygiene` skill, the `code-reviewer` and `plan-reviewer` agents, the `hygiene`, `verify-gate`, and `context-tree-nudge` extensions, the trigger rules in `rules/`, and the `/cleanup` command. A skill reports a problem in DocksDocks/docks-kit. `bun run check` checks this content with four tests in `cli/test/unit/plugin/`: `skills.test.ts` (layout and name, frontmatter, report section, shared copies, references, durable anchors, transform guard, trigger collisions, score floor), `contentHash.test.ts`, `agents.test.ts` (agent rules, score floor), and `extensions.test.ts` (each entry imports and has a default function export).
|
|
93
|
+
After a skill edit, run `bun cli/scripts/skill-content-hash.ts --write` to refresh its `metadata.content_hash` and `metadata.updated`; `--check` names each stale skill. The skill checks, the 16-point rubric, and the check data in `config.json` (floors, report section, shared-copy groups, transform list) are in `cli/src/skills/`, which `docks-kit skill guard` and `docks-kit skill score` also use; the agent, reference, trigger, extension, and content-hash checks are in `cli/scripts/pluginContent/`.
|
|
92
94
|
|
|
93
95
|
## Plans
|
|
94
96
|
|
|
@@ -102,8 +104,8 @@ Per the agents.md open standard, place an `AGENTS.md` inside any subdirectory th
|
|
|
102
104
|
|
|
103
105
|
```bash
|
|
104
106
|
# Clone and sync the kit
|
|
105
|
-
git clone <this-repo> ~/projects/
|
|
106
|
-
cd ~/projects/
|
|
107
|
+
git clone <this-repo> ~/projects/docks-kit
|
|
108
|
+
cd ~/projects/docks-kit
|
|
107
109
|
./docks-kit sync --dry-run # preview before applying
|
|
108
110
|
./docks-kit sync # deploy the omp SoT (additive)
|
|
109
111
|
./docks-kit toolchain check # verify installed tools against SoT/toolchain.json floors
|
package/README.md
CHANGED
|
@@ -11,34 +11,44 @@ Supported harness: **Oh My Pi (`omp`)**.
|
|
|
11
11
|
## Quick start
|
|
12
12
|
|
|
13
13
|
```bash
|
|
14
|
-
git clone https://github.com/DocksDocks/
|
|
15
|
-
cd ~/projects/
|
|
14
|
+
git clone https://github.com/DocksDocks/docks-kit.git ~/projects/docks-kit
|
|
15
|
+
cd ~/projects/docks-kit
|
|
16
16
|
./docks-kit sync # deploy the omp SoT
|
|
17
17
|
./docks-kit sync --dry-run # preview the sync without a write
|
|
18
18
|
./docks-kit toolchain # doctor view: verified-version floors for external tools
|
|
19
19
|
```
|
|
20
20
|
|
|
21
21
|
POSIX hosts use the `./docks-kit` launcher on Linux x64 and arm64 and on macOS
|
|
22
|
-
arm64. Windows uses `.\docks-kit.ps1` on x64. Each launcher
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
Hosts outside this matrix fail immediately and never fall back to Bun source.
|
|
26
|
-
Stale ignored build artifacts cannot mask newer checkout code.
|
|
22
|
+
arm64. Windows uses `.\docks-kit.ps1` on x64. Each launcher runs the checkout
|
|
23
|
+
source with Bun and auto-installs Bun plus dependencies when needed. Hosts
|
|
24
|
+
outside this matrix fail immediately and never reach the Bun source.
|
|
27
25
|
|
|
28
26
|
Other install paths include global `bun add -g docks-kit`, the POSIX curl
|
|
29
27
|
installer, and the Windows PowerShell installer. See `./docks-kit docs install`.
|
|
30
28
|
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
Download the platform release binary from GitHub Releases and run it directly.
|
|
34
|
-
The executable carries the generated sync payload; no checkout or adjacent
|
|
35
|
-
`SoT/` directory is required.
|
|
36
|
-
|
|
37
|
-
Source and global installs require Bun. An npm-global install needs npm.
|
|
29
|
+
Every install requires Bun. An npm-global install needs npm.
|
|
38
30
|
`jq` is optional doctor/test tooling. `curl` is needed only to download Bun's
|
|
39
31
|
upstream installer when Bun is absent: by the POSIX launcher and installer, and
|
|
40
|
-
by sync's Bun bootstrap
|
|
41
|
-
|
|
32
|
+
by sync's Bun bootstrap. The Windows launcher and installer use
|
|
33
|
+
Invoke-WebRequest.
|
|
34
|
+
|
|
35
|
+
### Move a checkout of DocksDocks/public
|
|
36
|
+
|
|
37
|
+
The kit moved from DocksDocks/public to DocksDocks/docks-kit. To move a
|
|
38
|
+
checkout of DocksDocks/public, run these commands from the checkout's root:
|
|
39
|
+
|
|
40
|
+
```
|
|
41
|
+
git remote set-url origin https://github.com/DocksDocks/docks-kit.git
|
|
42
|
+
./docks-kit update # Linux and macOS
|
|
43
|
+
.\docks-kit.ps1 update # Windows
|
|
44
|
+
./docks-kit sync # Linux and macOS
|
|
45
|
+
.\docks-kit.ps1 sync # Windows
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
The update pulls from DocksDocks/docks-kit and chains a sync that deploys the
|
|
49
|
+
skills with their new report target. The explicit sync covers an older
|
|
50
|
+
checkout whose launcher still runs a binary from `cli/dist/`, because that
|
|
51
|
+
binary does not chain the sync. A global npm install needs nothing.
|
|
42
52
|
|
|
43
53
|
## CLI
|
|
44
54
|
|
|
@@ -125,7 +135,7 @@ marketplace when no uninstall failed and it can read the marketplace registry.
|
|
|
125
135
|
It only warns about a project-scope install, with the manual command. When a
|
|
126
136
|
read fails, sync warns and skips that step, and a later sync tries again.
|
|
127
137
|
Report a problem with a skill, an agent, or the kit in
|
|
128
|
-
[DocksDocks/
|
|
138
|
+
[DocksDocks/docks-kit](https://github.com/DocksDocks/docks-kit/issues).
|
|
129
139
|
|
|
130
140
|
## Repository map
|
|
131
141
|
|
|
@@ -134,17 +144,17 @@ Report a problem with a skill, an agent, or the kit in
|
|
|
134
144
|
| `SoT/.omp/` | omp SoT (AGENTS.md, config.yml, models.yml, mcp.json, intercom.json, and the `plugin/` source of `docks-kit-omp`) |
|
|
135
145
|
| `SoT/toolchain.json` | Verified-version floors |
|
|
136
146
|
| `cli/src/engine-native/` | EngineNative sync/toolchain implementation |
|
|
137
|
-
| `cli/src/generated/sotPayload.ts` | Generated in-memory payload used by
|
|
147
|
+
| `cli/src/generated/sotPayload.ts` | Generated in-memory payload used by npm installs |
|
|
138
148
|
| `cli/` | docks-kit CLI (Effect 4 on Bun) + bundled docs topics |
|
|
139
|
-
| `docks-kit` / `docks-kit.ps1` | POSIX and Windows launchers (
|
|
149
|
+
| `docks-kit` / `docks-kit.ps1` | POSIX and Windows launchers (Bun-from-source) |
|
|
140
150
|
| `install.sh` / `install.ps1` | POSIX and Windows global installers |
|
|
141
151
|
| `docs/PLAN.md` | Plan pointer and project plan rules; plans are GitHub issues |
|
|
142
152
|
| `AGENTS.md` | Agent-facing engineering rules |
|
|
143
153
|
|
|
144
154
|
## Platform support
|
|
145
155
|
|
|
146
|
-
| Platform | Architecture | docks-kit
|
|
147
|
-
|
|
156
|
+
| Platform | Architecture | docks-kit CLI | Sync engine |
|
|
157
|
+
|----------|--------------|---------------|-------------|
|
|
148
158
|
| Linux | x64 | ✅ | ✅ native |
|
|
149
159
|
| Linux | arm64 | ✅ | ✅ native |
|
|
150
160
|
| macOS | arm64 | ✅ | ✅ native |
|
|
@@ -154,15 +164,15 @@ Details: `docks-kit docs platforms`.
|
|
|
154
164
|
|
|
155
165
|
## Releases
|
|
156
166
|
|
|
157
|
-
Tagging `cli-v*`
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
167
|
+
Tagging `cli-v*` attaches the bundle's source map `docks-kit.js.map` to the
|
|
168
|
+
GitHub release. npm publishes the exact package tarball through trusted
|
|
169
|
+
publishing with OIDC provenance. Source maps and release notes are available on
|
|
170
|
+
[GitHub Releases](https://github.com/DocksDocks/docks-kit/releases).
|
|
171
|
+
Each `docks-kit` npm release runs one minified JavaScript bundle of the CLI and
|
|
172
|
+
its generated payload (`cli/dist/docks-kit.js`), so releases are versioned config
|
|
173
|
+
snapshots without shipping the authoring `SoT/` tree. The package does not ship
|
|
174
|
+
the source map; the bundle's last line `//# debugId=<hex>` matches the map of
|
|
175
|
+
the same release.
|
|
166
176
|
|
|
167
177
|
## Deeper docs
|
|
168
178
|
|