docks-kit 0.22.28 → 0.23.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 +31 -77
- package/README.md +31 -58
- package/cli/docs/command-guards.md +231 -197
- package/cli/docs/flags.md +25 -55
- package/cli/docs/install.md +2 -3
- package/cli/docs/omp-models.md +9 -0
- package/cli/docs/overview.md +4 -12
- package/cli/docs/platforms.md +2 -2
- package/cli/docs/sync-layers.md +10 -57
- package/cli/docs/toolchain.md +9 -78
- package/cli/src/argv.ts +0 -8
- package/cli/src/argvValidate.ts +2 -46
- package/cli/src/commands/docs.ts +2 -14
- package/cli/src/commands/harnesses.ts +6 -9
- package/cli/src/commands/sync.ts +5 -99
- package/cli/src/commands/toolchain.ts +4 -12
- package/cli/src/engine-native/DESIGN.md +67 -88
- package/cli/src/engine-native/deps.ts +6 -86
- package/cli/src/engine-native/engineCtx.ts +7 -76
- package/cli/src/engine-native/exec.ts +1 -18
- package/cli/src/engine-native/harnesses.ts +6 -6
- package/cli/src/engine-native/index.ts +4 -6
- package/cli/src/engine-native/jq.ts +4 -37
- package/cli/src/engine-native/modes.ts +3 -132
- package/cli/src/engine-native/os/darwin.ts +0 -4
- package/cli/src/engine-native/os/index.ts +1 -2
- package/cli/src/engine-native/os/linux.ts +0 -3
- package/cli/src/engine-native/os/posix.ts +2 -46
- package/cli/src/engine-native/os/types.ts +1 -32
- package/cli/src/engine-native/os/windows.ts +0 -49
- package/cli/src/engine-native/parseArgs.ts +11 -124
- package/cli/src/engine-native/parseHelp.ts +5 -40
- package/cli/src/engine-native/scratch.ts +1 -1
- package/cli/src/engine-native/services.ts +1 -2
- package/cli/src/engine-native/sharedTypes.d.ts +0 -40
- package/cli/src/engine-native/skillsSync.ts +1 -1
- package/cli/src/engine-native/syncConcurrency.ts +3 -15
- package/cli/src/engine-native/syncDispatch.ts +10 -57
- package/cli/src/engine-native/toolchain.ts +5 -40
- package/cli/src/engine.ts +0 -75
- package/cli/src/generated/sotPayload.ts +12 -39
- package/cli/src/main.ts +7 -19
- package/cli/src/manifests.ts +1 -93
- package/cli/src/payload.ts +2 -8
- package/cli/tsconfig.json +1 -3
- package/package.json +3 -5
- package/cli/docs/models.md +0 -58
- package/cli/docs/modifiers.md +0 -52
- package/cli/docs/plugins.md +0 -70
- package/cli/src/commands/model.ts +0 -68
- package/cli/src/commands/models.ts +0 -75
- package/cli/src/commands/plugins.ts +0 -35
- package/cli/src/commands/status.ts +0 -206
- package/cli/src/efforts.ts +0 -89
- package/cli/src/engine-native/claudeLsp.ts +0 -301
- package/cli/src/engine-native/claudeOptionalPlugins.ts +0 -126
- package/cli/src/engine-native/claudePluginPasses.ts +0 -426
- package/cli/src/engine-native/claudeRemovals.ts +0 -383
- package/cli/src/engine-native/claudeRetired.ts +0 -165
- package/cli/src/engine-native/claudeRuntime.ts +0 -157
- package/cli/src/engine-native/claudeSettings.ts +0 -201
- package/cli/src/engine-native/claudeSettingsModifiers.ts +0 -115
- package/cli/src/engine-native/claudeSync.ts +0 -312
- package/cli/src/engine-native/codexConfig.ts +0 -214
- package/cli/src/engine-native/codexHooks.ts +0 -91
- package/cli/src/engine-native/codexPaths.ts +0 -14
- package/cli/src/engine-native/codexPlugins.ts +0 -315
- package/cli/src/engine-native/codexStatus.ts +0 -25
- package/cli/src/engine-native/codexSync.ts +0 -314
- package/cli/src/engine-native/codexToml.ts +0 -303
- package/cli/src/engine-native/liveModels.ts +0 -264
- package/cli/src/engine-native/models.ts +0 -101
- package/cli/src/engine-native/parseModifiers.ts +0 -225
- package/cli/src/engine-native/settings.ts +0 -42
- package/cli/src/engine-native/tomlLines.ts +0 -92
package/AGENTS.md
CHANGED
|
@@ -1,15 +1,15 @@
|
|
|
1
1
|
# AGENTS.md
|
|
2
2
|
|
|
3
|
-
Canonical instructions for coding agents working on this project. Compatible with
|
|
3
|
+
Canonical instructions for coding agents working on this project. Compatible with Oh My Pi (`omp`), OpenCode, VS Code Copilot, and any other [agents.md](https://agents.md/)-aware tool.
|
|
4
4
|
|
|
5
5
|
Pointers here name concepts, not coordinates — if a path or symbol moved,
|
|
6
6
|
trust the stated purpose and re-locate it (grep the symbol) before acting.
|
|
7
7
|
|
|
8
8
|
## Repository purpose
|
|
9
9
|
|
|
10
|
-
Portable configuration kit for AI coding agents. The kit manages
|
|
11
|
-
|
|
12
|
-
|
|
10
|
+
Portable configuration kit for AI coding agents. The kit manages one coding
|
|
11
|
+
harness, Oh My Pi (`omp`). Its Single Source of Truth (SoT) directory deploys
|
|
12
|
+
to omp's user-config location through
|
|
13
13
|
`./docks-kit sync`. The kit also deploys shared [agentskills.io](https://agentskills.io)
|
|
14
14
|
skills. Clone once to get a consistent AI-assisted environment on supported
|
|
15
15
|
Linux, macOS, and Windows hosts. The kit focuses on **token efficiency without
|
|
@@ -17,11 +17,7 @@ sacrificing quality**. Every setting and hook minimizes token use while
|
|
|
17
17
|
preserving rigorous output. When you add or edit anything, ask: *does this
|
|
18
18
|
change reduce tokens without weakening correctness?*
|
|
19
19
|
|
|
20
|
-
|
|
21
|
-
- **`.claude/rules/claude-code.md`** — Claude Code SoT (`SoT/.claude/`), env vars, hooks, plugins, status line, session management, permission mode, open concerns. Its `paths:` frontmatter scopes it: Claude Code loads it when it reads or edits a matching file, and any agent can open it by path.
|
|
22
|
-
- Codex uses this `AGENTS.md` file plus the Codex SoT under `SoT/.codex/`; no separate root `CODEX.md` is needed.
|
|
23
|
-
- omp uses this `AGENTS.md` file plus the omp SoT under `SoT/.omp/`.
|
|
24
|
-
|
|
20
|
+
omp uses this `AGENTS.md` file plus the omp SoT under `SoT/.omp/`.
|
|
25
21
|
|
|
26
22
|
docks-kit runtime and standalone binary support covers Linux x64/arm64, macOS
|
|
27
23
|
arm64, and Windows x64. Hosts outside this matrix fail before either
|
|
@@ -29,19 +25,17 @@ launcher can fall back to Bun source.
|
|
|
29
25
|
|
|
30
26
|
## Context tree
|
|
31
27
|
|
|
32
|
-
Per-folder conventions live in nested `AGENTS.md` nodes.
|
|
33
|
-
|
|
34
|
-
the
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
not this list, when a folder's rules change. `context-tree audit` checks this
|
|
38
|
-
table against the AGENTS.md files on disk.
|
|
28
|
+
Per-folder conventions live in nested `AGENTS.md` nodes. An agent can load
|
|
29
|
+
only the nodes from the root down to its working directory, so open the node
|
|
30
|
+
for the folder you edit from this table. Edit the node, not this list, when a
|
|
31
|
+
folder's rules change. `context-tree audit` checks this table against the
|
|
32
|
+
AGENTS.md files on disk.
|
|
39
33
|
|
|
40
34
|
| Node | Governs |
|
|
41
35
|
|---|---|
|
|
42
36
|
| `docs/AGENTS.md` | Plan-record routing to `docs/PLAN.md` |
|
|
43
37
|
| `cli/AGENTS.md` | Effect CLI, EngineNative sync engine, bundled docs topics, build scripts, unit and golden suites |
|
|
44
|
-
| `.agents/skills/AGENTS.md` | Project skills
|
|
38
|
+
| `.agents/skills/AGENTS.md` | Project skills; omp reads `.agents/skills/` directly |
|
|
45
39
|
|
|
46
40
|
## Repository layout (cross-cutting)
|
|
47
41
|
|
|
@@ -50,88 +44,70 @@ table against the AGENTS.md files on disk.
|
|
|
50
44
|
| `docks-kit` / `docks-kit.ps1` | POSIX and Windows CLI launchers. On supported hosts, each runs the matching binary in `cli/dist/` only when its `--version` matches `package.json` and no file under `cli/src/` or `cli/docs/` is newer than the binary. Otherwise it runs Bun-from-source and auto-installs Bun plus `node_modules`, and the mismatch or newer-source warning names the rebuild remedy. A launcher never deletes a binary: on a host without Bun it is the only remaining recovery path. Hosts outside the support matrix fail before source fallback. The standalone platform release binary provides no-Bun recovery. |
|
|
51
45
|
| `.oxlintrc.json` / `bunfig.toml` | Mechanical lint (correctness, suspicious, eqeqeq, no-var, prefer-const, no-unused) and the `bun fmt` code format settings (`[fmt]`) |
|
|
52
46
|
| `cli/` | Effect 4 CLI + bundled docs topics |
|
|
53
|
-
| `SoT/models.json` | Curated Claude and Codex model overlay: aliases and notes always apply; id rows are the fallback when a harness live list is unavailable |
|
|
54
47
|
| `SoT/toolchain.json` | Toolchain floors manifest (verified pins consumed by EngineNative; optional `upstream` source read by `docks-kit toolchain outdated`) |
|
|
55
|
-
| `SoT/.claude/bin/` | Dependency-free Bun runtime programs for Claude's statusline, SessionStart, and Notification |
|
|
56
48
|
| `SoT/.omp/` | Kit-owned omp SoT: `AGENTS.md`, `config.yml`, `models.yml`, `mcp.json`, `intercom.json`, and the kit plugin source `plugin/` |
|
|
57
49
|
| `install.sh` / `install.ps1` | POSIX and Windows global installers. Each installer stops on a host outside the support matrix before it downloads anything. |
|
|
58
50
|
| `.github/workflows/release-cli.yml` | `cli-v*` release: four binaries (Linux x64 and arm64, macOS arm64, Windows x64), plus `SHA256SUMS` and npm publish |
|
|
59
51
|
| `README.md` | Front door |
|
|
60
52
|
| `package.json` / `bun.lock` | npm package: `bin` = `cli/src/main.ts`; bundles `cli/` with the generated in-memory SoT payload |
|
|
61
|
-
| `SoT/.agents/skills.txt` | Universal-skill manifest, intentionally empty by default. Adding an [agentskills.io](https://agentskills.io/specification) slug opts it into EngineNative's shared `~/.agents/skills/` bootstrap
|
|
62
|
-
| `notification.mp3` | Audio asset for Notification hooks (consumed by Claude Code today; tool-agnostic file) |
|
|
53
|
+
| `SoT/.agents/skills.txt` | Universal-skill manifest, intentionally empty by default. Adding an [agentskills.io](https://agentskills.io/specification) slug opts it into EngineNative's shared `~/.agents/skills/` bootstrap. |
|
|
63
54
|
| `docs/PLAN.md` | Plan record standard. The plan record is a GitHub issue; no plan markdown is tracked. `docs/AGENTS.md` routes to it. |
|
|
64
|
-
| `.claude/rules/claude-code.md` | Claude Code-only instructions; path-scoped by its `paths:` frontmatter |
|
|
65
|
-
| `.claude/settings.json` | Project Claude Code settings. It holds only `claudeMdExcludes`, so Claude Code does not load the SoT prompt payloads or the test fixtures as project instructions; sync never reads or writes it |
|
|
66
55
|
| `AGENTS.md` | This file — tool-agnostic instructions |
|
|
67
56
|
|
|
68
57
|
Module map for `cli/` (engine axes, commands, kit store, test fixtures, and the release-binary build `bun run build:binaries`): `cli/AGENTS.md`.
|
|
69
58
|
|
|
70
|
-
|
|
71
|
-
- `SoT/.codex/AGENTS.md` deploys to `~/.codex/AGENTS.md` as global Codex instructions.
|
|
72
|
-
- `SoT/.codex/config.toml` pins Codex to `model = "gpt-6.2-sol"`, sets normal and plan reasoning to `high` with concise summaries, and sets `model_verbosity = "low"`, live top-level `web_search`, workspace-write sandboxing with sandboxed command network access, cross-session `memories` (+ dedicated note tools), `[agents]` subagent limits (`max_threads = 12`, `max_depth = 2` — intentionally above Codex defaults for broad parallel kit work; deeper recursion increases cost and predictability risk), a 128 KiB `project_doc_max_bytes` budget for the repo-side AGENTS.md chain (the global `~/.codex/AGENTS.md` is uncapped and not counted), and enables the two Docks plugins `docks@docks` and `plan-lifecycle@docks` (the shared plan lifecycle). The two project Codex reviewer agents in `.codex/agents/` use the same model.
|
|
73
|
-
- `SoT/.codex/config.toml` does not set `personality`. Codex 0.159.0 deprecated the key, and `friendly` and `pragmatic` no longer select a style. `codexConfig.ts removeRetiredTopLevelSettings, retired top-level key prune` removes the retired `personality = "pragmatic"` line from a deployed `config.toml` on every sync. A different user-set value survives.
|
|
74
|
-
- `SoT/.codex/rules/*.rules` deploys to `~/.codex/rules/` as kit-managed Codex command policy. This is Codex's equivalent of permission allow/prompt/block rules; user-learned approvals in `~/.codex/rules/default.rules` are preserved. Codex applies the strictest matching rule across all files, so a user allow rule cannot loosen a kit `forbidden` or `prompt` rule. Because the strictest rule wins, a narrow allow cannot carve an exception out of a broader prompt prefix, and a prefix rule cannot see an option after an operand. The guards therefore fail closed: every `rm`, `git rm`, `git worktree remove`, and `gio trash` prompts, and only macOS `trash` is allowed (owner decision). A `prompt` goes to `approvals_reviewer = "auto_review"`, a reviewer subagent, not always to a person. `docks.rules` carries the destructive-command guards (`docks-kit docs command-guards`); `cli/test/unit/codexSyncRules.test.ts` parses every one-line `prefix_rule`, alternatives lists and `justification` included, and asserts each guard's decision. Keep each rule on one line so that parser sees it.
|
|
75
|
-
- `codexSync.ts syncRules, kit rules manifest` records the sha256 of the kit bytes of each rules file that the kit deploys in `~/.codex/.kit-managed-rules`, in `<sha256> <file name>` lines. The manifest sits outside `rules/`, so Codex never reads it as a rule file. Sync writes each rules file through `atomicWrite.ts replaceFile`, so an interrupted write keeps the previous file. Codex loads only `*.rules` files, so it never loads the `*.tmp` sibling. Before the deploy, sync writes the manifest ahead. It keeps the recorded set of hashes of each name and adds the new kit hash of each shipped name. So a name whose kit bytes change has two lines. A sync that stops after a deploy thus leaves a record of the bytes that it wrote. A stale kit rules file keeps its old rules active. When the SoT drops a rules file, every sync therefore removes the deployed copy while its hash is in the recorded set of its name. A dropped file that the user edited stays, keeps its set, and gets a warning on each sync. Every recorded hash is a hash of kit bytes, so no record lets cleanup remove bytes that the user wrote. Cleanup reads and removes only recorded names that the SoT no longer ships. It never reads or removes a file that the SoT does not ship and no sync recorded, such as `default.rules`. Sync still deploys each name that the SoT ships over an existing file, recorded or not. It backs up a file that differs to `<name>.bak` and replaces it. After the deploy and the cleanup, the final manifest holds one line per shipped name, plus the set of each kept dropped name. Sync replaces the manifest through a temporary file and a rename, so an interrupted sync keeps the previous complete manifest. `--dry-run` prints `[dry-run] remove <file>` and writes nothing.
|
|
76
|
-
- `SoT/.codex/plugins/marketplace.json` deploys to Codex's personal marketplace path at `~/.agents/plugins/marketplace.json`; when the `codex` CLI is available, sync reruns `codex plugin add <plugin@marketplace>` for enabled SoT plugins so stale cached installs are refreshed.
|
|
77
|
-
- Codex `/import` hook cleanup (`codexHooks.ts`): `cli/AGENTS.md`.
|
|
78
|
-
- Codex limits the initial skill list to 2% of the model context and shortens descriptions first; it still reads a selected skill's full `SKILL.md`. Additive sync preserves user-added plugins, so their skill count and malformed cached `SKILL.md` files remain plugin-owned. Sync never patches a plugin cache in place.
|
|
59
|
+
Shared SoT notes:
|
|
79
60
|
- The global prompt SoTs carry the owner's standing authorization for Docks cross-company plan review, which never overrides host or platform denial.
|
|
80
|
-
- The `codex` CLI binary is upstream-owned, not kit-owned. The official standalone installer keeps package metadata under `$CODEX_HOME/packages/standalone` and places the `codex` symlink in `~/.local/bin` by default; sync only warns with a download-then-run installer command when the CLI is missing. Existing installs can self-update with `codex update`; npm and Homebrew remain upstream alternatives.
|
|
81
|
-
|
|
82
|
-
- Claude runtime settings are an authoring template with sentinels. `claudeRuntime.ts` materializes absolute Bun/script paths only after the shared `bun.ts` bootstrap is ready; `claudeSync.ts` writes all runtime assets before atomically committing settings, then prunes the legacy shell scripts and Stop hook. Native `rate_limits` is the sole quota source, so jq/curl/OAuth caches are not runtime dependencies. A missing Bun defers only this cutover and preserves legacy pointers/files.
|
|
83
|
-
- Claude's deployed SoT defaults are `model: opus` and `effortLevel: high`; `advisorModel` is deliberately absent/off. `--claude-advisor=on` is the per-machine opt-in and writes `advisorModel: opus` after the settings merge. `opus` is the alias, not a pinned id: the `minimumVersion` floor of 2.1.280 makes Claude Code resolve it to Opus 5.5, the default Opus from that release, instead of capping at Opus 5 under the former 2.1.219 floor. Keeping the alias tracks the next Opus release without a kit change and stays portable across providers. The floor also subsumes Fable 5.1's 2.1.257 requirement.
|
|
84
|
-
- Claude permission rules are pruned, not host-scoped. The kit deploys its `PowerShell(...)` deny and ask rules on every host, because Claude Code leaves the PowerShell tool opt-in off Windows rather than unavailable, and a host that enables it must already carry the guards. `claudeRetired.ts RETIRED_PERMISSION_RULES, exact retired-rule inventory` lists the rules the kit no longer ships. `claudeRemovals.ts syncRemovals, retired-permission pass` force-prunes those exact strings from the kit-managed `~/.claude/settings.json` on every sync, because `settings.ts mergeSettings, permission-array union` would otherwise keep a dropped rule forever. A different user-authored rule survives. To restore an exact retired rule for one checkout, put it in that checkout's `.claude/settings.local.json`. Claude Code resolves that file against the working directory and merges it over user settings. Sync never reads or writes the checkout-local file. Claude Code has no user-scope local settings file. For a machine-wide restoration, add the rule to `SoT/.claude/settings.json`. At the same time, remove the exact string from `claudeRetired.ts RETIRED_PERMISSION_RULES, exact retired-rule inventory`. `permissions.allow` holds four read-only entries, `Read`, `Glob`, `Grep`, and `WebSearch`, the working-directory edit rule `Edit(./)`, and two narrow trash allows, `Bash(gio trash -- *)` and `Bash(trash *)`. Broad shell allow rules are not restored, because an allow rule resolves before Claude Code's read-only command analyzer and the auto-mode classifier. `autoMemoryEnabled` and `autoDreamEnabled` are both `false`.
|
|
85
61
|
|
|
86
62
|
omp SoT notes:
|
|
87
63
|
- `SoT/.omp/AGENTS.md`, `config.yml`, `models.yml`, and `mcp.json` deploy to `~/.omp/agent/`. omp loads `~/.omp/agent/AGENTS.md` only into main sessions and advisors, never into task subagents (`omp://context-files.md`). So `SoT/.omp/AGENTS.md` holds only main-session rules, and a command rule that subagents need goes into a kit plugin trigger rule.
|
|
88
64
|
- `SoT/.omp/intercom.json` deploys to `$PI_CODING_AGENT_DIR/intercom/config.json`. The default root is `~/.pi/agent`. Under a named omp profile (`OMP_PROFILE` or `PI_PROFILE`), it deploys to `<profile agentDir>/intercom/config.json`, because omp exports `PI_CODING_AGENT_DIR` as the profile agent directory.
|
|
89
65
|
- `ompFileDeploy.ts syncMergedYaml` deep-merges `config.yml` through `ompYaml.ts mergeOmpConfig` and `models.yml` through `mergeOmpModels`. Both wrap one generic mapping merge; only the config wrapper prunes stale `retry.fallbackChains` wildcards and merges `bash.patterns`.
|
|
90
|
-
- `SoT/.omp/config.yml` `bash.patterns` holds the destructive-command guards. omp
|
|
91
|
-
- `ompSync.ts` runs `ompRemovals.ts syncOmpRemovals, retired-key inventory` right after the config merge, and that pass force-prunes retired kit-owned keys from `~/.omp/agent/config.yml` on every sync,
|
|
66
|
+
- `SoT/.omp/config.yml` `bash.patterns` holds the destructive-command guards. omp 19.0.0 checks a deny rule, then a prompt rule, then its `CRITICAL_BASH_PATTERNS`, then an allow rule (`BashTool.approval` in the v19.0.0 source; `omp://approval-mode.md` still describes the 18.17.0 order, in which the critical check came before a prompt rule). A critical command that no deny or prompt rule matches gets a bare safety override, which replaces a matching allow, and omp's default `tools.approvalMode: yolo` ignores a bare override, so the command runs, in subagents too. A prompt rule asks a person, also on a critical command, but a subagent rejects every prompt. Every `rm` shape that the critical check can flag is therefore a deny: recursive `rm`, `sudo` anywhere before `rm` (also by path), any `rm` with an `r` or `f` option before an absolute path, and `--no-preserve-root`. By owner decision (0.20.9), the recursive-`rm` deny also covers any prefix (a `* rm ` copy of each bare cluster rule, so `env X=1 rm -rf b`, `xargs rm -rf`, `find . -exec rm -rf {} +`, and `git rm -r dir` are denied) and the `-ri`, `-ir`, `-Ri`, and `-iR` clusters for bare `rm`, `*/rm`, and `* rm`. By owner decision (0.21.0), 17 more denies cover bulk removal that can empty the home directory: `find -delete` (bare, `*/find`, `* find`), `-exec`, `-execdir`, `-ok`, and `-okdir` with `rm` or `*/rm`, and `xargs rm` in six shapes. No glob can express "inside the temporary directory", so `docks-kit scratch remove` checks that path in code. A `$` or a backtick anywhere after `git push` in the same command is a deny, not a prompt (0.22.5, #120). A variable can expand to a `+` refspec or `--force`, and the matcher reads the text before the shell expands it. The agent reads the refusal and writes the ref literally, so no person is asked. The two rules are `*git push *$*` and ``*git push *`*``. Their leading `*` keeps a shell keyword such as `do`, a wrapper such as `env`, or a path before `git` from hiding the push. By owner decision (0.22.8, #126), the kit ships no omp prompt rule: `bash.patterns` holds only the denies plus the `trash *` allow, so every command that no deny matches runs without a question, in subagents too. Since 0.20.9 this run-without-question behavior covers a non-denied `rm`, `git rm`, `git worktree remove`, and `gio trash`. Since 0.21.0 it also covers `docks-kit scratch remove`. Since 0.22.8 it also covers `git clean`, `git reset --hard`, a hook skip, and every `git push` that no deny matches. The force-push denies match only `git push --force` or `-f` directly before `origin main` or `origin master`, so another spelling, such as `git push origin main --force`, runs. A prompt rule that the user adds survives sync and still asks. The kit plugin trigger rules in `SoT/.omp/plugin/rules/` carry the agent rules for these commands. `git-safety.md` tells the agent to write each `git push` ref literally and to push the current branch with `git push -u origin HEAD`. The list order is deny, then `trash *`. For a command without shell control, omp takes the first matching rule. For a command with shell control, such as `;` or `|`, each segment takes its first matching deny or prompt rule, a deny chosen for one segment wins over a prompt chosen for another segment, and an allow never matches. A segment also matches without its leading `NAME=value` words. `ompYaml.ts mergeBashPatterns, grouped rule merge` keeps user rules and groups all rules as kit deny, user deny, user prompt, kit prompt, other user rules, kit allow, so a user deny or prompt precedes every kit allow. It treats a deployed rule equal to a kit rule (approval case-folded, `match` whitespace collapsed) as the kit copy, so a re-sync is a no-op. A rule the kit stops shipping stays as a user rule, so retire one through `ompRemovals.ts OMP_RETIRED_BASH_RULES`. `cli/test/lib/ompBashPatterns.ts` ports omp 19.0.0's matcher, critical patterns, and yolo resolution; `cli/test/unit/ompBashPatterns.test.ts` asserts each command's final outcome and the merge. omp subagents reject every `prompt`, and the `eval` tool stays unrestricted by owner decision.
|
|
67
|
+
- `ompSync.ts` runs `ompRemovals.ts syncOmpRemovals, retired-key inventory` right after the config merge, and that pass force-prunes retired kit-owned keys from `~/.omp/agent/config.yml` on every sync, with no flag. The pass is required because `mergeOmpConfig` is additive, so removing a key from the SoT alone never removes it from a deployed file. A key retired with a recorded value is pruned only while the deployed value still matches that value, so a user edit survives; a key retired outright, such as `providers.webSearchOrder`, is pruned at any value. The same pass removes each `bash.patterns` rule listed in `OMP_RETIRED_BASH_RULES`: the 39 file-removal rules retired in 0.20.9, the four `git push` prompts for a `$` or backtick word that 0.22.5 replaced with denies, and the 492 prompt rules retired in 0.22.8 (`RETIRED_PROMPT_MATCHES`). It compares with the merge's kit-rule normalization (approval case-folded, `match` whitespace collapsed), so a user rule with a different `match` or `approval` survives.
|
|
92
68
|
- `cycleOrder` ends with `astra` as its fifth stop. `modelRoles.astra` is `openai-codex/gpt-6.2-astra:xhigh`, and `modelTags.astra` (`GPT-6.2 Astra`) is visible. Astra and Fable fall back to each other through concrete selectors: `retry.fallbackChains.astra` holds `anthropic/claude-fable-5-2:medium`, and `retry.fallbackChains.fable` holds `openai-codex/gpt-6.2-astra:xhigh`. `modelRoles.fable` is `anthropic/claude-fable-5-2:medium`, with visible `modelTags.fable`. The hidden `switch_fable` role uses the same Fable selector and keeps an empty fallback chain.
|
|
93
|
-
- `modelRoles.task` is `anthropic/claude-opus-5-5:high`, and `retry.fallbackChains.task` falls back to `openai-codex/gpt-6.2-sol:high`. The kit relies on omp's default `task.enableEffort: false`: a caller `effort` outranks the role's level suffix, and `hi` maps to the top of the model ladder, so with the field on, `hi` spawns ran at `task.maxEffort` (`xhigh`) instead of the role level. With the field off, every spawn runs its role level, and `task.maxEffort` bounds only a per-call `model` with a `:level` suffix. By owner decision (0.22.22), the omp advisor is removed: the SoT has no `advisor` block, `advisor` role, or `advisor` fallback chain. The plan-lifecycle verification loop replaces a second model on every turn. A session that runs `/advisor on` takes its advisor model from the `slow` role. `smol`, `commit`, and `tiny` use `openai-codex/gpt-6-luna`. The kit-defined hidden `reviewer` role is `openai-codex/gpt-6.1-terra:high`. Its retry fallback is `anthropic/claude-opus-5-5:high`. All four reviewer entries in `task.agentModelOverrides` point to `@reviewer`. `task.agentServiceTierOverrides` sets the same four agents to `inherit`, so they take the live tier of the main session for each provider. The user set the effort `high` and chose to follow the fast toggle (#134); the review benchmark of #130 chose the model. `ompOverlay.ts ROLE_ORDER, FALLBACK_ORDER` list `reviewer`, so a free session also replaces it. omp bundles the `reviewer` and `security-reviewer` agents, and the `plan-lifecycle` plugin ships `code-reviewer` and `plan-reviewer`. The `SoT/toolchain.json` omp floor
|
|
69
|
+
- `modelRoles.task` is `anthropic/claude-opus-5-5:high`, and `retry.fallbackChains.task` falls back to `openai-codex/gpt-6.2-sol:high`. The kit relies on omp's default `task.enableEffort: false`: a caller `effort` outranks the role's level suffix, and `hi` maps to the top of the model ladder, so with the field on, `hi` spawns ran at `task.maxEffort` (`xhigh`) instead of the role level. With the field off, every spawn runs its role level, and `task.maxEffort` bounds only a per-call `model` with a `:level` suffix. By owner decision (0.22.22), the omp advisor is removed: the SoT has no `advisor` block, `advisor` role, or `advisor` fallback chain. The plan-lifecycle verification loop replaces a second model on every turn. A session that runs `/advisor on` takes its advisor model from the `slow` role. `smol`, `commit`, and `tiny` use `openai-codex/gpt-6-luna`. The kit-defined hidden `reviewer` role is `openai-codex/gpt-6.1-terra:high`. Its retry fallback is `anthropic/claude-opus-5-5:high`. All four reviewer entries in `task.agentModelOverrides` point to `@reviewer`. `task.agentServiceTierOverrides` sets the same four agents to `inherit`, so they take the live tier of the main session for each provider. The user set the effort `high` and chose to follow the fast toggle (#134); the review benchmark of #130 chose the model. `ompOverlay.ts ROLE_ORDER, FALLBACK_ORDER` list `reviewer`, so a free session also replaces it. omp bundles the `reviewer` and `security-reviewer` agents, and the `plan-lifecycle` plugin ships `code-reviewer` and `plan-reviewer`. The `SoT/toolchain.json` omp floor and verified pin are 19.0.0, the release the kit tested on 2026-11-19: its `omp models --json` catalog lists each model selector of `modelRoles` and `retry.fallbackChains` exactly, every `SoT/.omp/config.yml` key is a key of `omp config list --json`, and `cli/test/lib/ompBashPatterns.ts` ports its approval source. The floor is doctor visibility only. Sync does not check the omp catalog, so an older omp can fuzzy-match a missing id to another model. `cli/docs/omp-models.md` records the checks.
|
|
94
70
|
- The six Opus 5.5 roles (`default`, `slow`, `plan`, `designer`, `vision`, `task`) and the `smol`, `tiny`, `commit`, and `reviewer` retry chains use `anthropic/claude-opus-5-5` at the levels the role map records. `cli/docs/omp-models.md` carries the Artificial Analysis capture behind the role map, read 2026-09-29 at Intelligence Index v4.3.2 and Coding Agent Index v1.5 from the AA comparison-page metric tables. The `astra`, `reviewer`, `fable`, and `switch_fable` rows are the exceptions: they come from v5.0.1 captures read 2026-11-18 (GPT-6.2 Astra), 2026-11-05 (GPT-6.1 Terra), and 2026-11-12 (Fable 5.2), and they compare only with other v5.0.1 figures. Opus 5.5 max has the highest v4.3.2 index in that topic, at 58. AA has measured speed and latency for every Opus 5.5 level and every GPT-6.2 Sol and GPT-6.2 Astra row in that topic. GPT-6 Luna medium is the only unmeasured speed and latency row.
|
|
95
71
|
- `modelRoles.web` is `web/firecrawl` and `retry.fallbackChains.web` carries the explicit 20-entry provider order. The kit declares both keys because the legacy `providers.webSearchOrder` key is retired: omp expands it in memory into these two keys and then drops it, and never writes that expansion back to disk. An explicit chain replaces omp's built-in web order wholesale, so every entry left out is a provider omp never tries. The owner removed the seven entries that named older models (Gemini 2.5 Flash, Claude Haiku 4.5, GPT-5.6, GPT-5.5, and Grok 4.5); keep every other provider.
|
|
96
72
|
- `SoT/.omp/models.yml` declares Astra's full `low, medium, high, xhigh, max` ladder with `defaultLevel: xhigh` as the worked provider ladder-override example. The override is keyed `gpt-6.2-astra`, the model id of the `astra` role. `ompRemovals.ts syncOmpModelRemovals` prunes the old `gpt-6-astra` block from `~/.omp/agent/models.yml` while it equals the shipped block. The temporary `anthropic.modelOverrides.claude-opus-5-5` block is gone, because the shared catalog now publishes the same limits, ladder, and prices. The removal switches omp from the block's `thinking.mode: effort` (a `budget_tokens` value per level from `ANTHROPIC_THINKING`, no effort value) to the catalog's `anthropic-adaptive` (adaptive thinking with the role's effort level); every kit Opus selector names its level, so the block's bare-selector `defaultLevel: high` is not needed. `ompRemovals.ts syncOmpModelRemovals, retired-block inventory` prunes it from `~/.omp/agent/models.yml` after the models merge, but only while the deployed block still equals the shipped one. `ompYaml.ts mergeOmpModels` preserves deployed-only keys in `~/.omp/agent/models.yml`, because a user file may carry provider credentials. Whole-file replacement is wrong.
|
|
97
73
|
- `SoT/.omp/AGENTS.md` carries the rule `Please remove all mannered prose.` Anthropic's Fable 5.1 prompting guide documents mannered prose as a Fable 5.1 behavior and gives that sentence as its short-version fix: https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-1
|
|
98
74
|
- `cli/docs/omp-models.md` (topic `omp-models`) records the role map rationale and the Artificial Analysis snapshot behind it. Model choices change with published benchmarks, so update that topic in the same commit as a role change. For each model that an omp role or retry chain uses, the topic keeps AA rows at `high` and `xhigh` at least, with the index version and the capture date.
|
|
99
75
|
- `SoT/.omp/config.yml` carries only keys whose value differs from the omp default. When a kit value equals the omp default, remove the key from the SoT. Add it with its shipped value to `ompRemovals.ts OMP_RETIRED_VALUES`, because `ompYaml.ts mergeOmpConfig` is additive and only that pass prunes the deployed copy. For example, the kit ships no `compaction.thresholdTokens`, and sync prunes a deployed `-1` and the former `231200` pin. `cli/docs/omp-context.md` (topic `omp-context`) carries the reserve-based derivation and the measured evidence, so update that topic in the same commit as any compaction-setting change.
|
|
100
|
-
- Sync materializes the kit omp plugin `docks-kit-omp` from `SoT/.omp/plugin/` to `~/.docks-kit/omp-plugin` (`ompKitPlugin.ts syncKitPlugin`). It sets directories to 0700, files to 0600, and the `package.json` `version` to the kit version, and it removes stale files. It keeps no backups, because the directory is kit-owned. `ompPlugins.ts syncPlugins, kit plugin link` then runs `omp plugin link <dir>`. It skips the link when the `omp plugin list --json` npm row `docks-kit-omp` already has a `path` that resolves to that directory. `--skip-plugin-refresh` does not skip the link. The `hygiene.ts` extension registers `scratch_new`, `scratch_remove`, and `tidy_report`. It adds a reminder after each bash command that created a resource, and it checks at session stop that those resources are gone. At a main-session start, it claims `~/.cache/docks-kit/tidy.stamp.claim` and runs `docks-kit tidy --apply` in the background at most once per 12 hours. Every extension subprocess runs without a shell. The `pluginUpgrades.ts` extension reads the omp plugin upgrade log. In a tool result of each main session, it adds one reminder for the logged upgrades that the session did not get before. It names only the upgrades that finished after its omp process started. The reminder tells the agent to ask the user to run `/reload-plugins`. It then tells the agent to read each plugin skill again through `skill://` before it runs a skill script. It asks for a restart instead when an upgraded plugin ships hooks, extension modules, or non-MCP tools. omp imports extensions only at startup. An omp process that started before a sync deployed `pluginUpgrades.ts` did not load it, so its sessions get no reminder. The plugin also ships the `workspace-hygiene` skill, the `/cleanup` command, and six omp Time Traveling Stream Rules (TTSR, trigger rules) in `rules/`: `file-removal.md`, `git-safety.md`, `temp-and-background.md`, `worktree-location.md`, `literal-paths.md`, and `remote-cleanup.md`. omp's `omp-plugins` provider loads `rules/*.md` from the linked plugin root (`omp://plugin-manager-installer-plumbing.md`). Each rule has a regex `condition` scoped to `tool:bash, tool:eval` that aims at the wrong form; eval is in scope because eval code can run a shell command through `sh()`. A condition reads text, not a parsed command, so it has known false positives: a quoted command word (`echo "rm x"`, or a commit message that starts with `rm`) and eval code after the closing quote of a `sh()` string. `worktree-location.md` fires on each `git worktree add`, also at the correct path, because a condition cannot read `$XDG_DATA_HOME` or the home directory. omp aborts the matching tool call before it runs, injects the rule, and retries (`omp://ttsr-injection-lifecycle.md`). Each rule has `repeatMode: always`: it fires at each later wrong form, but not on the retry that its own reminder starts. The rules reach subagents and cost no prompt tokens until they fire. They teach the correct form; the `bash.patterns` denies still enforce. omp tests each condition on the partial argument buffer after each streamed delta, so a condition must not match a prefix of a correct command: it needs a delimiter after each token it checks, never the end anchor `$`. The buffer is the argument JSON text, the intent field `i` can come before or after `command`, and a provider can put JSON white space around the colon (`{"command": "ls"}`). So each condition starts its match inside the `command` or `code` string
|
|
76
|
+
- Sync materializes the kit omp plugin `docks-kit-omp` from `SoT/.omp/plugin/` to `~/.docks-kit/omp-plugin` (`ompKitPlugin.ts syncKitPlugin`). It sets directories to 0700, files to 0600, and the `package.json` `version` to the kit version, and it removes stale files. It keeps no backups, because the directory is kit-owned. `ompPlugins.ts syncPlugins, kit plugin link` then runs `omp plugin link <dir>`. It skips the link when the `omp plugin list --json` npm row `docks-kit-omp` already has a `path` that resolves to that directory. `--skip-plugin-refresh` does not skip the link. The `hygiene.ts` extension registers `scratch_new`, `scratch_remove`, and `tidy_report`. It adds a reminder after each bash command that created a resource, and it checks at session stop that those resources are gone. At a main-session start, it claims `~/.cache/docks-kit/tidy.stamp.claim` and runs `docks-kit tidy --apply` in the background at most once per 12 hours. Every extension subprocess runs without a shell. The `pluginUpgrades.ts` extension reads the omp plugin upgrade log. In a tool result of each main session, it adds one reminder for the logged upgrades that the session did not get before. It names only the upgrades that finished after its omp process started. The reminder tells the agent to ask the user to run `/reload-plugins`. It then tells the agent to read each plugin skill again through `skill://` before it runs a skill script. It asks for a restart instead when an upgraded plugin ships hooks, extension modules, or non-MCP tools. omp imports extensions only at startup. An omp process that started before a sync deployed `pluginUpgrades.ts` did not load it, so its sessions get no reminder. The plugin also ships the `workspace-hygiene` skill, the `/cleanup` command, and six omp Time Traveling Stream Rules (TTSR, trigger rules) in `rules/`: `file-removal.md`, `git-safety.md`, `temp-and-background.md`, `worktree-location.md`, `literal-paths.md`, and `remote-cleanup.md`. omp's `omp-plugins` provider loads `rules/*.md` from the linked plugin root (`omp://plugin-manager-installer-plumbing.md`). Each rule has a regex `condition` scoped to `tool:bash, tool:eval` that aims at the wrong form; eval is in scope because eval code can run a shell command through `sh()`. A condition reads text, not a parsed command, so it has known false positives: a quoted command word (`echo "rm x"`, or a commit message that starts with `rm`) and eval code after the closing quote of a `sh()` string. `worktree-location.md` fires on each `git worktree add`, also at the correct path, because a condition cannot read `$XDG_DATA_HOME` or the home directory. omp aborts the matching tool call before it runs, injects the rule, and retries (`omp://ttsr-injection-lifecycle.md`). Each rule has `repeatMode: always`: it fires at each later wrong form, but not on the retry that its own reminder starts. The rules reach subagents and cost no prompt tokens until they fire. They teach the correct form; the `bash.patterns` denies still enforce. omp tests each condition on the partial argument buffer after each streamed delta, so a condition must not match a prefix of a correct command: it needs a delimiter after each token it checks, never the end anchor `$`. The buffer is the argument JSON text, the intent field `i` can come before or after `command`, and a provider can put JSON white space around the colon (`{"command": "ls"}`). So each condition starts its match with the forward key prefix `"(?:command|code)"\s*:\s*"[^"\\]*?` and an escape loop that takes up to 8 escape pairs per step; `cli/docs/command-guards.md` shows the full prefix. Only the key prefix is sure to stay inside the `command` or `code` string. The rest of a condition can cross the closing quote: the `Bun.file` condition of `file-removal.md` matches `{"code":"Bun.file(","i":").delete("}`. omp's `Matched:` excerpt is a bounded window around the match start: up to 60 characters before it, and a long match is cut at 180 characters from its start, so in a long call the trigger can be outside the excerpt. A scan stops at an unescaped `"` and at a newline (`\n`), a tab (`\t` in the buffer) counts as shell white space, and a scan that looks for an option stops at a ` -- ` word. omp runs each test on its main thread, in JavaScriptCore. Up to 0.22.29, each condition started with an unbounded lookbehind, which walked back over the buffer from every position. A 20 KB call then froze the session for seconds, and past the JavaScriptCore match limit the rule did not fire. So never start a condition with an unbounded lookbehind. Make each scan after a command start one lazy walk that stops at its first event: `(?=(?<w>[\s\S]*?)(?=EVENT)BOUNDARY)\k<w>`. The events are the flag of the condition, a terminator, the end of the run, and the next command start, each at a real token boundary. The lookahead does not backtrack after it matches, so the walk stays frozen. The stop at the next command start keeps a line that repeats a command start linear. Never put a group loop inside a lookaround over text of unbounded length, because JavaScriptCore then keeps each loop step until the match attempt ends and drops out of the JIT. omp tests open buffers that stop before the closing quote, so a scan must not rely on that quote to stop. `cli/test/unit/ompTriggerRules.test.ts` pins every condition through bash and through Python and JavaScript eval `sh()` calls, in the compact and the spaced JSON layouts, with some rows in the pretty layout and trigger words in the intent before and after the command. It checks that each condition has a wrong row that fires it and that each rule has `repeatMode: always`. Its shape guard checks only the key prefix and that no `|` stands outside every group. Its backstop runs `cli/test/lib/ompTriggerBackstop.ts` under Bun and proves linear time by measurement: a time budget, a fire check, scaling with the JIT off, and dense and head-and-run lines with the JIT on, in bash, open bash, and Python. Run `bunx vitest run cli/test/unit/ompTriggerRules.test.ts` after each condition change; it runs both guards. When you rewrite a condition, run the old and the new condition on each buffer of the test table and compare the results. `cli/docs/command-guards.md` (topic `command-guards`) lists the rules, the false positives, and the input families that a forward key prefix alone does not make linear. The plugin, the deployed rules, and the sweep call `docks-kit scratch` and `docks-kit tidy`. So a checkout sync must not run before the global `docks-kit` carries those commands.
|
|
101
77
|
- `task.agentIdleTtlMs` is `120000`, so omp parks an idle subagent after 2 minutes instead of 7. `browser.idleCloseSec` is `600`.
|
|
102
78
|
- By owner decision (0.21.0), resources on the workstation are always development, so `docks-kit tidy` sweeps them without a question. The omp `remote-cleanup.md` trigger rule, the `workspace-hygiene` skill, `/cleanup`, and the extension reminders limit the cleanup of a remote resource (reached through SSH, a database client, or a provider CLI such as `wrangler`, `vercel`, `kubectl`, `aws`, or a remote Docker host) to targets named local, development, dev, test, homolog, homologation, staging, or preview, the plan-lifecycle non-production definition. A production cleanup needs an `ask` immediately before it, must be rare, and a `yolo` invocation does not answer that ask. Prompt rules cannot force an agent to ask, so this rule has no `bash.patterns` guard.
|
|
103
79
|
- The omp CLI is upstream-owned. It updates through `omp update`, or through the external manager that owns the install, such as Tern or Nix. `omp update` refuses to run on an install that an external manager owns. Sync never installs or upgrades the CLI.
|
|
104
80
|
- omp plugin upgrade flow, the `pi-intercom` install, and the `docks-kit omp` free-model launcher: `cli/AGENTS.md`.
|
|
105
81
|
|
|
106
|
-
For
|
|
82
|
+
For the omp SoT layout (`SoT/.omp/`), see that directory.
|
|
107
83
|
|
|
108
84
|
## Engineering rules
|
|
109
85
|
|
|
110
86
|
- **EngineNative and CLI rules** (idempotency, failure ledger, removed bash engine, Effect stack and skill routing, harness-selection store, module boundaries): `cli/AGENTS.md`.
|
|
111
|
-
- **Targeted syncs.** `./docks-kit sync` accepts positional targets: `
|
|
112
|
-
- **Additive by default.** Keys present in deployed config but absent from SoT are preserved on default sync. This protects user-only additions, but means drift accumulates
|
|
113
|
-
- **`--
|
|
87
|
+
- **Targeted syncs.** `./docks-kit sync` accepts positional targets: `agents` and `omp`. Use the narrowest target that matches the SoT change (for example, `./docks-kit sync omp` for omp-only config edits); targets can be combined with `--dry-run`, `--skip-plugin-refresh` (install missing omp plugins without refreshing existing ones), `--prune`, and `--verbose`.
|
|
88
|
+
- **Additive by default.** Keys present in deployed config but absent from SoT are preserved on default sync. This protects user-only additions, but means drift accumulates. The exceptions are the omp retired inventories: `ompRemovals.ts` force-prunes retired kit-owned keys, `bash.patterns` rules, and model blocks on every sync (see the omp SoT notes above).
|
|
89
|
+
- **`--prune` is the one kit-owned removal flag.** It removes the `~/.agents/skills/*` entries named in `~/.agents/.kit-owned-skills` that SoT no longer lists. A slug enters that record only when an install of the kit created its directory, so a directory that existed before is never recorded. `--prune` removes it only while the directory keeps the `<dev>:<ino>` that the record names; else it prints `keep <slug>: the directory is not the one that the kit installed`. The legacy `~/.agents/.kit-managed-skills` of an older kit is read only and never authorizes a removal. `--prune` prints a `keep <slug>` line for each of its dropped slugs whose directory exists. Manually installed skills are always preserved.
|
|
114
90
|
- **Small, reviewable changes.** Bundled multi-concern PRs are harder to review and revert. Split an engine/CLI change and a per-tool config change unless the change requires atomicity.
|
|
115
91
|
- **Version bumps.** Bump `package.json` on user-visible behavior change; bump a `SoT/toolchain.json` `verified` pin only after testing that release. Refactors, splits, and doc edits bump nothing.
|
|
116
|
-
- **Regenerate the payload.** After `SoT
|
|
117
|
-
- **Dry-run before destructive flags.** Always preview with `./docks-kit sync --dry-run
|
|
118
|
-
- **SoT prompt files are rules, not explanation.** `SoT/.
|
|
119
|
-
- **Cache-invariance for kit-authored prompt surfaces.** Never put timestamps, counters, or mutable state into SoT prompt files,
|
|
92
|
+
- **Regenerate the payload.** After `SoT/` or `package.json` changes, run `bun cli/scripts/generate-sot-payload.ts`; `bun run check:generated` verifies it. After file moves, clamp cited `metadata.source_files[].lines` ranges so `skillMetadata.test.ts` passes.
|
|
93
|
+
- **Dry-run before destructive flags.** Always preview with `./docks-kit sync --prune --dry-run`, with the same targets as the intended run, before invoking `--prune`. Only that preview lists the kit-recorded skills that SoT no longer lists, which `--prune` removes.
|
|
94
|
+
- **SoT prompt files are rules, not explanation.** `SoT/.omp/AGENTS.md` is loaded into agent sessions' prompt context — every line costs prompt tokens on every turn for every user. Restrict its content to rules, heuristics, and `<constraint>` blocks the agent must *act on* during a turn. Do NOT add inline source citations (`Source: …`, attributed quotes), "why this rule exists" preface text, version-watermarking trivia (e.g. "Distilled from X v2.0, captured 2025-11-07"), per-bug workarounds, or installation instructions. Provenance, motivation, and historical context belong in `AGENTS.md` (humans read once) or in commit messages — never in the SoT. For every line, apply the official test: …
|
|
95
|
+
- **Cache-invariance for kit-authored prompt surfaces.** Never put timestamps, counters, or mutable state into SoT prompt files, extension output that lands in the cached prefix, or tool definitions — cache breaks force cold-start writes. Dynamic context belongs in runtime-injected messages, such as the reminders that the kit omp plugin adds to tool results.
|
|
120
96
|
|
|
121
97
|
## Code style
|
|
122
98
|
|
|
123
|
-
- Bash: for launchers
|
|
124
|
-
- JSON and YAML config: edit the SoT (`SoT/<tool>/`) and run `./docks-kit sync`. Never edit deployed config under `~/.
|
|
99
|
+
- Bash: for launchers and installers, use `set -euo pipefail`, quoted variables, `[[ ]]` over `[ ]`, and function-scoped `local`.
|
|
100
|
+
- JSON and YAML config: edit the SoT (`SoT/<tool>/`) and run `./docks-kit sync`. Never edit deployed config under `~/.omp/agent/` directly.
|
|
125
101
|
|
|
126
102
|
## Security
|
|
127
103
|
|
|
128
104
|
- No secrets in SoT. The kit's SoT directories are committed; treat them as declarative config only.
|
|
129
105
|
- Treat external plugin marketplaces and installer downloads as untrusted input. Prefer download-then-run over `curl … | bash` so a truncated stream cannot execute a partial script.
|
|
130
106
|
- **Pin, never float.** Every kit-driven install of third-party software is pinned to a `SoT/toolchain.json` `verified` version, except the exemptions in the next item — no `@latest` npm/bun installs (Shai-Hulud-class worm surface), no mutable action tags in workflows (commit SHAs only), installer scripts fetched from version tags where upstream supports it. New third-party install surface ⇒ manifest pin first. The rule also covers a transitive dependency whose declared range is a caret or tilde over a prerelease: `^4.0.0-rc.109` admits every later prerelease of the same version tuple, and a published install resolves that range fresh because `bun.lock` is not packaged, so a runtime pinned in `package.json` meets a newer sibling and the process fails at startup. The fix is an exact root pin plus both guards: the offline `cli/test/unit/dependencyPins.test.ts` and the clean-room `bun run smoke:package`. Moving the Effect release is therefore one lockstep commit: set `effect`, `@effect/platform-bun`, and `@effect/platform-node-shared` to the same version together, then run `bun run smoke:package`. The offline guard fails when a lag breaks a declared range. Its peer-range check fails when the installed `effect` is outside a non-optional peer range of the runtime closure. Its nested-copy check fails when `@effect/platform-node-shared` lags. A lagging `@effect/platform-bun` can keep every declared range satisfied (4.1.1 accepts `@effect/platform-node-shared` `^4.1.1`), so only the lockstep commit keeps it in step. Details: the `toolchain-context` skill and `cli/docs/toolchain.md`.
|
|
131
|
-
- **Exemptions: the kit's own package
|
|
107
|
+
- **Exemptions: the kit's own package and the existing marketplace plugins.** `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. The existing omp marketplace plugin installs have no manifest pin: sync installs and refreshes those plugins at the version that their marketplace publishes. Any new install surface, a new marketplace or plugin source included, still needs a manifest pin first.
|
|
132
108
|
## Testing
|
|
133
109
|
|
|
134
|
-
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.4. 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
|
|
110
|
+
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.4. 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:native`.
|
|
135
111
|
|
|
136
112
|
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.
|
|
137
113
|
|
|
@@ -145,7 +121,7 @@ Never rewrite published `main` history to correct a routing mistake. Use a follo
|
|
|
145
121
|
|
|
146
122
|
## Skills
|
|
147
123
|
|
|
148
|
-
Project-skill
|
|
124
|
+
Project-skill authoring rules (scope, canonical layout, vendored `unslop`, citation constraint): `.agents/skills/AGENTS.md`.
|
|
149
125
|
|
|
150
126
|
**Universal-skill bootstrap.** `SoT/.agents/skills.txt` is intentionally empty, so the default sync exposes no universal skills. The generic opt-in contract remains: each [agentskills.io](https://agentskills.io/specification) slug is installed by `skillsInstall.ts syncUniversal` with `npx --yes skills@<verified> add <slug> -g -y -a claude-code codex`, where `<verified>` is the `skills-cli` pin in `SoT/toolchain.json`. The slug comes first because `-a/--agent` is variadic; naming both supported agents preserves the canonical `~/.agents/skills/<name>/SKILL.md` plus Claude's `~/.claude/skills/<name>` symlink. Existing canonical directories are reused idempotently and are never recorded as kit-owned. When no record names a reused directory, sync warns that `--prune` keeps it. Before an install, sync records the slug in `~/.agents/.kit-pending-skills`, and only when the canonical directory does not exist. After the install, the slug moves to `~/.agents/.kit-owned-skills` when its directory exists. `--prune` removes only entries in `~/.agents/.kit-owned-skills`; the legacy `~/.agents/.kit-managed-skills` is read only and never authorizes a removal (`skillsRecords.ts`).
|
|
151
127
|
|
|
@@ -228,10 +204,6 @@ No plan markdown is tracked. The pre-GitHub records under
|
|
|
228
204
|
them as history, and no lifecycle command restores them. The complete contract
|
|
229
205
|
lives in `docs/PLAN.md`; `docs/AGENTS.md` routes to it.
|
|
230
206
|
|
|
231
|
-
Distinct from the **Open Concerns** section of `.claude/rules/claude-code.md`
|
|
232
|
-
(wait-on-upstream blockers tied to a vendor shipping a fix): plans are
|
|
233
|
-
kit-internal work we control; Open Concerns is conditions-for-resolution.
|
|
234
|
-
|
|
235
207
|
Plugin-internal work (skills, commands, agents) belongs in each plugin's
|
|
236
208
|
own repo, not here.
|
|
237
209
|
|
|
@@ -248,27 +220,9 @@ cd ~/projects/public
|
|
|
248
220
|
./docks-kit harnesses # view or change this machine's flag-less sync selection
|
|
249
221
|
./docks-kit sync # sync this machine's harness selection (additive)
|
|
250
222
|
./docks-kit sync --dry-run # preview before applying
|
|
251
|
-
./docks-kit sync --
|
|
252
|
-
./docks-kit sync --reconcile # reconcile settings toward SoT: SoT keys and arrays win, user-only keys kept (settings layer only)
|
|
253
|
-
./docks-kit sync --prune # uninstall plugins/marketplaces not in SoT (plugin layer only)
|
|
254
|
-
./docks-kit sync --reconcile --prune # full reset to SoT (both layers)
|
|
255
|
-
./docks-kit sync claude --claude-compact-window=680k # deploy-time: raise autocompact window (any token count: 680k or 680000) for disposable sessions (model unchanged)
|
|
256
|
-
./docks-kit sync claude --claude-permissive # deploy-time: empty permissions.ask/deny — unattended commits/pushes in sandboxes
|
|
257
|
-
./docks-kit sync --claude-plugin=supabase # opt in the supabase plugin (install + enable in deployed settings)
|
|
258
|
-
./docks-kit sync --claude-plugin=n8n # opt in the n8n-mcp-skills plugin (add marketplace + install + enable); repeatable/comma-separated
|
|
259
|
-
./docks-kit model claude opus # deploy-time: set Opus explicitly (matches the SoT; standalone form of --claude-model=)
|
|
260
|
-
./docks-kit status # show deployed vs SoT state
|
|
223
|
+
./docks-kit sync --prune # remove kit-recorded universal skills that SoT no longer lists
|
|
261
224
|
./docks-kit toolchain check # verify installed tools against SoT/toolchain.json floors
|
|
262
225
|
```
|
|
263
226
|
|
|
264
227
|
On Windows, replace `./docks-kit` with `.\docks-kit.ps1` in these checkout
|
|
265
228
|
commands.
|
|
266
|
-
|
|
267
|
-
For Codex plugins, after deploying `SoT/.codex/config.toml` and the personal marketplace file, sync runs `codex plugin add <plugin@marketplace>` for each enabled SoT plugin. Re-running sync therefore refreshes stale Codex plugin caches instead of only updating marketplace metadata. Sync also removes the older kit-created configured Docks marketplace source so Codex uses the personal marketplace file as the single source.
|
|
268
|
-
|
|
269
|
-
### Deploy-time modifiers
|
|
270
|
-
|
|
271
|
-
Unlike `--reconcile`/`--prune` (which reconcile toward SoT), modifiers change the **deployed** config for a specific machine profile. The SoT is never touched, and a later flag-less sync reasserts it: Claude returns to Opus/high/advisor-off and Codex returns to its model/high effort. Modifiers run after the base merge/removal passes, are idempotent, honor `--dry-run`, and warn when their tool target is not selected. `docks-kit model <tool> <value>` is the standalone form of the model modifiers.
|
|
272
|
-
|
|
273
|
-
Codex mirrors the model/effort contract with `--codex-model=<m>` and
|
|
274
|
-
`--codex-effort=<level>`; Codex `default` effort restores `high`.
|
package/README.md
CHANGED
|
@@ -5,7 +5,7 @@ Truth (SoT)** directories deploy to each tool's user-config location. Clone
|
|
|
5
5
|
once to get a consistent AI-assisted environment on supported Linux, macOS,
|
|
6
6
|
and Windows machines. Tuned for **token efficiency without sacrificing quality**.
|
|
7
7
|
|
|
8
|
-
Supported
|
|
8
|
+
Supported harness: **Oh My Pi (`omp`)**.
|
|
9
9
|
The kit also deploys [agentskills.io](https://agentskills.io) universal skills.
|
|
10
10
|
|
|
11
11
|
## Quick start
|
|
@@ -16,7 +16,7 @@ cd ~/projects/public
|
|
|
16
16
|
./docks-kit harnesses # choose this machine's flag-less sync harnesses
|
|
17
17
|
./docks-kit sync # deploy this machine's harness selection
|
|
18
18
|
./docks-kit sync omp # deploy omp explicitly
|
|
19
|
-
./docks-kit
|
|
19
|
+
./docks-kit toolchain # doctor view: verified-version floors for external tools
|
|
20
20
|
```
|
|
21
21
|
|
|
22
22
|
POSIX hosts use the `./docks-kit` launcher on Linux x64 and arm64 and on macOS
|
|
@@ -44,18 +44,16 @@ launcher and installer use Invoke-WebRequest.
|
|
|
44
44
|
## CLI
|
|
45
45
|
|
|
46
46
|
```text
|
|
47
|
-
docks-kit sync [
|
|
47
|
+
docks-kit sync [agents] [omp] deploy explicit targets or the machine selection
|
|
48
48
|
docks-kit harnesses view or change this machine's selection
|
|
49
49
|
docks-kit update [--no-sync] self-update the kit (autodetects checkout vs global install), then sync
|
|
50
|
-
docks-kit model <claude|codex> [value] get/set the DEPLOYED model (TTY picker)
|
|
51
|
-
docks-kit models [claude|codex|omp] [--refresh] live catalogs for enabled harnesses (`--json`)
|
|
52
50
|
docks-kit omp [--model <m>|--pick] [args...] one omp session on a free model, nothing deployed changes
|
|
53
51
|
docks-kit omp --fast toggle omp fast mode for OpenAI/Codex models, then exit
|
|
54
|
-
docks-kit toolchain [check|ensure <tool>|outdated
|
|
55
|
-
docks-kit status [--json] deployed-vs-SoT drift + toolchain + counts
|
|
56
|
-
docks-kit plugins list [--json] enabledPlugins tri-state vs installed
|
|
52
|
+
docks-kit toolchain [check|ensure <tool>|outdated] verified-version floors for external tools
|
|
57
53
|
docks-kit skills list [--json] universal skills vs manifest
|
|
58
|
-
docks-kit
|
|
54
|
+
docks-kit scratch new|remove agent temporary files and directories
|
|
55
|
+
docks-kit tidy [--apply] [--report] remove safe agent leftovers
|
|
56
|
+
docks-kit docs [topic] self-documentation (9 topics)
|
|
59
57
|
--help --version --wizard --completions built-in
|
|
60
58
|
```
|
|
61
59
|
|
|
@@ -77,54 +75,34 @@ here.
|
|
|
77
75
|
| Flag | Effect |
|
|
78
76
|
|------|--------|
|
|
79
77
|
| `--dry-run` | Preview without applying |
|
|
80
|
-
| `--
|
|
81
|
-
| `--
|
|
82
|
-
| `--
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
| `--codex-model=<m>` | Deploy-time modifier: deployed Codex model |
|
|
87
|
-
| `--skip-bubblewrap` | Skip optional bubblewrap bootstrap (Codex Linux sandbox) |
|
|
88
|
-
| `--skip-plugin-refresh` | Install missing plugins but skip refresh-only updates |
|
|
89
|
-
|
|
90
|
-
**Deploy-time modifiers** change deployed config only — the SoT is untouched
|
|
91
|
-
and a later flag-less sync reverts them. Full reference: `docks-kit docs flags`
|
|
92
|
-
(includes the old→new rename table for the pre-CLI `sync.sh` flags).
|
|
78
|
+
| `--prune` | Remove kit-managed universal skills not in `SoT/.agents/skills.txt` |
|
|
79
|
+
| `--skip-plugin-refresh` | Install missing omp plugins but skip refresh-only updates |
|
|
80
|
+
| `--verbose` | Also print no-op confirmations |
|
|
81
|
+
|
|
82
|
+
Full reference: `docks-kit docs flags` (includes the old→new rename table for
|
|
83
|
+
the pre-CLI `sync.sh` flags).
|
|
93
84
|
|
|
94
85
|
## How syncing works
|
|
95
86
|
|
|
96
87
|
- **Additive by default** — user-only settings keys, plugins, and skills
|
|
97
|
-
survive a plain sync.
|
|
98
|
-
|
|
88
|
+
survive a plain sync. Removing kit-managed universal skills that left the
|
|
89
|
+
SoT is explicit (`--prune`).
|
|
99
90
|
- **Per-machine selection** — `~/.docks-kit/kit.db` drives a flag-less sync.
|
|
100
|
-
A missing selection selects
|
|
101
|
-
|
|
102
|
-
stored selection, its picker pre-ticks every harness, omp included.
|
|
91
|
+
A missing selection selects universal skills and omp. Use
|
|
92
|
+
`docks-kit harnesses` to view or change the selection.
|
|
103
93
|
- **Idempotent** — every step is safe to re-run; no-change syncs are no-ops.
|
|
104
94
|
- **Toolchain floors** — `SoT/toolchain.json` records the kit-verified version
|
|
105
|
-
floors for external tools (bun,
|
|
95
|
+
floors for external tools (bun, omp, …). `docks-kit toolchain check` prints
|
|
106
96
|
the full doctor table. Bun is the one managed install and is pinned to its
|
|
107
97
|
verified version.
|
|
108
|
-
- **
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
- **Command guards** — omp, Claude Code, and Codex share one policy for
|
|
117
|
-
destructive shell commands; to remove, agents use the trash
|
|
118
|
-
(`gio trash -- <path>`, or `trash <path>` on macOS); omp agents remove a
|
|
119
|
-
temporary file or directory with `docks-kit scratch remove`. `rm` of the
|
|
120
|
-
home directory or `/` and `HOME` reassignment are denied. omp also denies
|
|
121
|
-
every recursive `rm`, `find -delete`, `find -exec rm`, and `xargs rm`. The
|
|
122
|
-
kit ships no omp prompt rule, so omp runs every command that no deny
|
|
123
|
-
matches without a question, in subagents too. Claude Code and Codex ask
|
|
124
|
-
before a recursive `rm`, `find -delete`, every `git rm`, `git clean`,
|
|
125
|
-
`git reset --hard`, and any `git push` that could force; a Codex ask can go
|
|
126
|
-
to its `auto_review` reviewer. Details, per-tool differences, and gaps:
|
|
127
|
-
`docks-kit docs command-guards`.
|
|
98
|
+
- **Command guards** — omp's policy for destructive shell commands: to
|
|
99
|
+
remove, agents use the trash (`gio trash -- <path>`, or `trash <path>` on
|
|
100
|
+
macOS) or remove a temporary file or directory with
|
|
101
|
+
`docks-kit scratch remove`. omp denies `rm` of the home directory or `/`,
|
|
102
|
+
`HOME` reassignment, every recursive `rm`, `find -delete`, `find -exec rm`,
|
|
103
|
+
and `xargs rm`. The kit ships no omp prompt rule, so omp runs every command
|
|
104
|
+
that no deny matches without a question, in subagents too. Details and
|
|
105
|
+
gaps: `docks-kit docs command-guards`.
|
|
128
106
|
- **Agent cleanup (omp)** — `docks-kit scratch` creates agent temporary
|
|
129
107
|
directories and removes agent temporary files and directories with checked
|
|
130
108
|
paths. `docks-kit tidy` lists merged idle worktrees, their containers,
|
|
@@ -137,19 +115,16 @@ and a later flag-less sync reverts them. Full reference: `docks-kit docs flags`
|
|
|
137
115
|
|
|
138
116
|
| Path | Purpose |
|
|
139
117
|
|------|---------|
|
|
140
|
-
| `SoT/.claude/` | Claude Code SoT (settings template, Bun runtime programs, CLAUDE.md) |
|
|
141
|
-
| `SoT/.codex/` | Codex SoT (config.toml, rules, AGENTS.md, marketplace) |
|
|
142
118
|
| `SoT/.omp/` | omp SoT (AGENTS.md, config.yml, models.yml, mcp.json, intercom.json, and the `plugin/` source of `docks-kit-omp`) |
|
|
143
119
|
| `SoT/.agents/` | Universal-skill manifest |
|
|
144
|
-
| `SoT/models.json` | Curated aliases, notes, and offline Claude/Codex fallback |
|
|
145
120
|
| `SoT/toolchain.json` | Verified-version floors |
|
|
146
|
-
| `cli/src/engine-native/` | EngineNative sync/
|
|
121
|
+
| `cli/src/engine-native/` | EngineNative sync/toolchain implementation |
|
|
147
122
|
| `cli/src/generated/sotPayload.ts` | Generated in-memory payload used by standalone and npm installs |
|
|
148
123
|
| `cli/` | docks-kit CLI (Effect 4 on Bun) + bundled docs topics |
|
|
149
124
|
| `docks-kit` / `docks-kit.ps1` | POSIX and Windows launchers (binary → Bun-from-source) |
|
|
150
125
|
| `install.sh` / `install.ps1` | POSIX and Windows global installers |
|
|
151
126
|
| `docs/PLAN.md` | Plan record standard; plans are GitHub issues |
|
|
152
|
-
| `AGENTS.md`
|
|
127
|
+
| `AGENTS.md` | Agent-facing engineering rules |
|
|
153
128
|
|
|
154
129
|
## Platform support
|
|
155
130
|
|
|
@@ -176,9 +151,7 @@ are versioned config snapshots without shipping the authoring `SoT/` tree.
|
|
|
176
151
|
|
|
177
152
|
## Deeper docs
|
|
178
153
|
|
|
179
|
-
- `docks-kit docs <topic>` - overview, sync-layers, flags,
|
|
180
|
-
omp-models, omp-context, command-guards
|
|
181
|
-
|
|
154
|
+
- `docks-kit docs <topic>` - overview, sync-layers, flags, toolchain, install,
|
|
155
|
+
platforms, omp-models, omp-context, command-guards (works offline, bundled
|
|
156
|
+
with the CLI)
|
|
182
157
|
- [`AGENTS.md`](AGENTS.md) — engineering rules for agents working on the kit
|
|
183
|
-
- [`.claude/rules/claude-code.md`](.claude/rules/claude-code.md) — Claude Code specifics: env vars, session
|
|
184
|
-
management, permission mode, open concerns
|