docks-kit 0.23.0 → 0.24.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 +19 -20
- package/README.md +12 -22
- package/cli/docs/command-guards.md +5 -3
- package/cli/docs/flags.md +11 -29
- package/cli/docs/install.md +1 -1
- package/cli/docs/omp-context.md +79 -7
- package/cli/docs/omp-models.md +18 -12
- package/cli/docs/overview.md +5 -8
- package/cli/docs/sync-layers.md +12 -11
- package/cli/docs/toolchain.md +4 -4
- package/cli/src/argv.ts +0 -4
- package/cli/src/argvValidate.ts +2 -9
- package/cli/src/commands/docs.ts +2 -2
- package/cli/src/commands/omp.ts +1 -1
- package/cli/src/commands/scratch.ts +1 -1
- package/cli/src/commands/sync.ts +3 -24
- package/cli/src/commands/tidy.ts +1 -1
- package/cli/src/engine-native/DESIGN.md +21 -31
- package/cli/src/engine-native/deps.ts +2 -7
- package/cli/src/engine-native/engineCtx.ts +3 -28
- package/cli/src/engine-native/index.ts +2 -2
- package/cli/src/engine-native/kitDb.ts +21 -37
- package/cli/src/engine-native/ompFastMode.ts +1 -1
- package/cli/src/engine-native/ompOverlay.ts +1 -1
- package/cli/src/engine-native/ompRemovals.ts +24 -3
- package/cli/src/engine-native/ompSession.ts +67 -0
- package/cli/src/engine-native/ompSync.ts +1 -1
- package/cli/src/engine-native/os/posix.ts +0 -1
- package/cli/src/engine-native/os/types.ts +0 -4
- package/cli/src/engine-native/os/windows.ts +0 -1
- package/cli/src/engine-native/parseArgs.ts +1 -61
- package/cli/src/engine-native/parseHelp.ts +1 -6
- package/cli/src/engine-native/scratch.ts +1 -1
- package/cli/src/engine-native/sharedTypes.d.ts +1 -1
- package/cli/src/engine-native/syncConcurrency.ts +3 -3
- package/cli/src/engine-native/syncDispatch.ts +26 -92
- package/cli/src/engine-native/toolchain.ts +1 -5
- package/cli/src/generated/sotPayload.ts +6 -8
- package/cli/src/main.ts +3 -7
- package/package.json +2 -2
- package/cli/src/checklistPrompt.ts +0 -464
- package/cli/src/commands/harnesses.ts +0 -77
- package/cli/src/commands/skills.ts +0 -40
- package/cli/src/engine-native/harnesses.ts +0 -138
- package/cli/src/engine-native/skillsInstall.ts +0 -135
- package/cli/src/engine-native/skillsLinks.ts +0 -216
- package/cli/src/engine-native/skillsManifest.ts +0 -36
- package/cli/src/engine-native/skillsPrune.ts +0 -117
- package/cli/src/engine-native/skillsRecords.ts +0 -138
- package/cli/src/engine-native/skillsSync.ts +0 -57
- package/cli/src/manifests.ts +0 -53
- package/cli/src/terminalCells.ts +0 -191
package/AGENTS.md
CHANGED
|
@@ -9,13 +9,16 @@ trust the stated purpose and re-locate it (grep the symbol) before acting.
|
|
|
9
9
|
|
|
10
10
|
Portable configuration kit for AI coding agents. The kit manages one coding
|
|
11
11
|
harness, Oh My Pi (`omp`). Its Single Source of Truth (SoT) directory deploys
|
|
12
|
-
to omp's user-config location through
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
12
|
+
to omp's user-config location through `./docks-kit sync`. Sync writes no
|
|
13
|
+
`.agents` or `.claude` folder of its own; omp's folders follow
|
|
14
|
+
`PI_CONFIG_DIR`, `PI_CODING_AGENT_DIR`, and `XDG_DATA_HOME`, so an override
|
|
15
|
+
that points into one of those folders makes omp's files go there. Sync also
|
|
16
|
+
writes the kit plugin to `~/.docks-kit/omp-plugin`. Clone once to get a
|
|
17
|
+
consistent AI-assisted environment on supported Linux, macOS, and Windows
|
|
18
|
+
hosts. The kit focuses on **token efficiency without sacrificing quality**.
|
|
19
|
+
Every setting and hook minimizes token use while preserving rigorous output.
|
|
20
|
+
When you add or edit anything, ask: *does this change reduce tokens without
|
|
21
|
+
weakening correctness?*
|
|
19
22
|
|
|
20
23
|
omp uses this `AGENTS.md` file plus the omp SoT under `SoT/.omp/`.
|
|
21
24
|
|
|
@@ -50,7 +53,6 @@ AGENTS.md files on disk.
|
|
|
50
53
|
| `.github/workflows/release-cli.yml` | `cli-v*` release: four binaries (Linux x64 and arm64, macOS arm64, Windows x64), plus `SHA256SUMS` and npm publish |
|
|
51
54
|
| `README.md` | Front door |
|
|
52
55
|
| `package.json` / `bun.lock` | npm package: `bin` = `cli/src/main.ts`; bundles `cli/` with the generated in-memory SoT payload |
|
|
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. |
|
|
54
56
|
| `docs/PLAN.md` | Plan record standard. The plan record is a GitHub issue; no plan markdown is tracked. `docs/AGENTS.md` routes to it. |
|
|
55
57
|
| `AGENTS.md` | This file — tool-agnostic instructions |
|
|
56
58
|
|
|
@@ -66,15 +68,15 @@ omp SoT notes:
|
|
|
66
68
|
- `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
69
|
- `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.
|
|
68
70
|
- `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.
|
|
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
|
|
71
|
+
- `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 the cap of the former kit value `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. Since 0.24.0 the kit sets no `task.maxEffort`, so that cap is omp's default `max`. 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.
|
|
70
72
|
- 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.
|
|
71
73
|
- `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.
|
|
72
74
|
- `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.
|
|
73
75
|
- `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
|
|
74
76
|
- `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.
|
|
75
77
|
- `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.
|
|
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
|
|
77
|
-
- `
|
|
78
|
+
- 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 tests the measured input families for linear time: 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. A condition can still backtrack on a run that no generator holds, so a new condition needs a new family when its shape is new. 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.
|
|
79
|
+
- By owner decision (0.24.0), `astGrep.enabled` and `checkpoint.enabled` are `true`, so omp offers the `ast_grep` tool and the `checkpoint` and `rewind` tools. `rewind` restores only the conversation, and a rule line in `SoT/.omp/AGENTS.md` says so. The memory backend, `autolearn.enabled`, and `prewalk.enabled` stay off. Every other omp 19.0.0 feature keeps its omp default. The owner also returned 18 kit overrides to the omp defaults, for example `task.agentIdleTtlMs` (omp parks an idle subagent after 7 minutes) and `browser.idleCloseSec`. `OMP_RETIRED_VALUES` prunes each deployed key while it still holds the value that the kit shipped. `cli/docs/omp-context.md` lists the 18 keys, the kept overrides, and why `issue://` and `pr://` still work with `github.enabled` at its default `false`.
|
|
78
80
|
- 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.
|
|
79
81
|
- 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.
|
|
80
82
|
- omp plugin upgrade flow, the `pi-intercom` install, and the `docks-kit omp` free-model launcher: `cli/AGENTS.md`.
|
|
@@ -83,14 +85,13 @@ For the omp SoT layout (`SoT/.omp/`), see that directory.
|
|
|
83
85
|
|
|
84
86
|
## Engineering rules
|
|
85
87
|
|
|
86
|
-
- **EngineNative and CLI rules** (idempotency, failure ledger, removed bash engine, Effect stack and skill routing,
|
|
87
|
-
- **
|
|
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.
|
|
88
|
+
- **EngineNative and CLI rules** (idempotency, failure ledger, removed bash engine, Effect stack and skill routing, kit store, module boundaries): `cli/AGENTS.md`.
|
|
89
|
+
- **One sync.** `./docks-kit sync` deploys the omp SoT and takes no positional target. Combine it with `--dry-run`, `--skip-plugin-refresh` (install missing omp plugins without refreshing existing ones), and `--verbose`.
|
|
90
|
+
- **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). Sync has no removal flag.
|
|
90
91
|
- **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.
|
|
91
92
|
- **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.
|
|
92
93
|
- **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
|
|
94
|
+
- **Dry-run before a real sync.** Preview a change to the omp SoT with `./docks-kit sync --dry-run` before you run `./docks-kit sync`.
|
|
94
95
|
- **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
96
|
- **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.
|
|
96
97
|
|
|
@@ -123,7 +124,7 @@ Never rewrite published `main` history to correct a routing mistake. Use a follo
|
|
|
123
124
|
|
|
124
125
|
Project-skill authoring rules (scope, canonical layout, vendored `unslop`, citation constraint): `.agents/skills/AGENTS.md`.
|
|
125
126
|
|
|
126
|
-
**
|
|
127
|
+
**Vendored `unslop`.** The kit never runs the skills CLI. Only a maintainer refreshes the vendored `.agents/skills/unslop/` copy, with `npx skills@1.7.0 add cursor/plugins -s unslop -y -a universal`. The skills CLI 1.7.0 installs the `universal` agent into the project path `.agents/skills/`, which omp reads.
|
|
127
128
|
|
|
128
129
|
## Plans
|
|
129
130
|
|
|
@@ -217,10 +218,8 @@ Per the agents.md open standard, place an `AGENTS.md` inside any subdirectory th
|
|
|
217
218
|
# Clone and sync the kit
|
|
218
219
|
git clone <this-repo> ~/projects/public
|
|
219
220
|
cd ~/projects/public
|
|
220
|
-
./docks-kit harnesses # view or change this machine's flag-less sync selection
|
|
221
|
-
./docks-kit sync # sync this machine's harness selection (additive)
|
|
222
221
|
./docks-kit sync --dry-run # preview before applying
|
|
223
|
-
./docks-kit sync
|
|
222
|
+
./docks-kit sync # deploy the omp SoT (additive)
|
|
224
223
|
./docks-kit toolchain check # verify installed tools against SoT/toolchain.json floors
|
|
225
224
|
```
|
|
226
225
|
|
package/README.md
CHANGED
|
@@ -1,21 +1,20 @@
|
|
|
1
1
|
# docks-kit
|
|
2
2
|
|
|
3
|
-
Portable configuration kit for AI coding agents.
|
|
4
|
-
Truth (SoT)**
|
|
5
|
-
once to get a consistent AI-assisted environment on supported Linux,
|
|
6
|
-
and Windows machines. Tuned for **token efficiency without sacrificing
|
|
3
|
+
Portable configuration kit for AI coding agents. The **Single Source of
|
|
4
|
+
Truth (SoT)** directory `SoT/.omp/` deploys to the omp user-config location.
|
|
5
|
+
Clone once to get a consistent AI-assisted environment on supported Linux,
|
|
6
|
+
macOS, and Windows machines. Tuned for **token efficiency without sacrificing
|
|
7
|
+
quality**.
|
|
7
8
|
|
|
8
9
|
Supported harness: **Oh My Pi (`omp`)**.
|
|
9
|
-
The kit also deploys [agentskills.io](https://agentskills.io) universal skills.
|
|
10
10
|
|
|
11
11
|
## Quick start
|
|
12
12
|
|
|
13
13
|
```bash
|
|
14
14
|
git clone https://github.com/DocksDocks/public.git ~/projects/public
|
|
15
15
|
cd ~/projects/public
|
|
16
|
-
./docks-kit
|
|
17
|
-
./docks-kit sync
|
|
18
|
-
./docks-kit sync omp # deploy omp explicitly
|
|
16
|
+
./docks-kit sync # deploy the omp SoT
|
|
17
|
+
./docks-kit sync --dry-run # preview the sync without a write
|
|
19
18
|
./docks-kit toolchain # doctor view: verified-version floors for external tools
|
|
20
19
|
```
|
|
21
20
|
|
|
@@ -35,7 +34,7 @@ Download the platform release binary from GitHub Releases and run it directly.
|
|
|
35
34
|
The executable carries the generated sync payload; no checkout or adjacent
|
|
36
35
|
`SoT/` directory is required.
|
|
37
36
|
|
|
38
|
-
Source and global installs require Bun. npm-global
|
|
37
|
+
Source and global installs require Bun. An npm-global install needs npm.
|
|
39
38
|
`jq` is optional doctor/test tooling. `curl` is needed only to download Bun's
|
|
40
39
|
upstream installer when Bun is absent: by the POSIX launcher and installer, and
|
|
41
40
|
by sync's Bun bootstrap, which a release binary can also run. The Windows
|
|
@@ -44,13 +43,11 @@ launcher and installer use Invoke-WebRequest.
|
|
|
44
43
|
## CLI
|
|
45
44
|
|
|
46
45
|
```text
|
|
47
|
-
docks-kit sync [
|
|
48
|
-
docks-kit harnesses view or change this machine's selection
|
|
46
|
+
docks-kit sync [--dry-run] deploy the omp SoT to this machine
|
|
49
47
|
docks-kit update [--no-sync] self-update the kit (autodetects checkout vs global install), then sync
|
|
50
48
|
docks-kit omp [--model <m>|--pick] [args...] one omp session on a free model, nothing deployed changes
|
|
51
49
|
docks-kit omp --fast toggle omp fast mode for OpenAI/Codex models, then exit
|
|
52
50
|
docks-kit toolchain [check|ensure <tool>|outdated] verified-version floors for external tools
|
|
53
|
-
docks-kit skills list [--json] universal skills vs manifest
|
|
54
51
|
docks-kit scratch new|remove agent temporary files and directories
|
|
55
52
|
docks-kit tidy [--apply] [--report] remove safe agent leftovers
|
|
56
53
|
docks-kit docs [topic] self-documentation (9 topics)
|
|
@@ -75,21 +72,15 @@ here.
|
|
|
75
72
|
| Flag | Effect |
|
|
76
73
|
|------|--------|
|
|
77
74
|
| `--dry-run` | Preview without applying |
|
|
78
|
-
| `--prune` | Remove kit-managed universal skills not in `SoT/.agents/skills.txt` |
|
|
79
75
|
| `--skip-plugin-refresh` | Install missing omp plugins but skip refresh-only updates |
|
|
80
76
|
| `--verbose` | Also print no-op confirmations |
|
|
81
77
|
|
|
82
|
-
Full reference: `docks-kit docs flags
|
|
83
|
-
the pre-CLI `sync.sh` flags).
|
|
78
|
+
Full reference: `docks-kit docs flags`.
|
|
84
79
|
|
|
85
80
|
## How syncing works
|
|
86
81
|
|
|
87
|
-
- **Additive by default** — user-only settings keys
|
|
88
|
-
|
|
89
|
-
SoT is explicit (`--prune`).
|
|
90
|
-
- **Per-machine selection** — `~/.docks-kit/kit.db` drives a flag-less sync.
|
|
91
|
-
A missing selection selects universal skills and omp. Use
|
|
92
|
-
`docks-kit harnesses` to view or change the selection.
|
|
82
|
+
- **Additive by default** — user-only settings keys and plugins survive a
|
|
83
|
+
plain sync.
|
|
93
84
|
- **Idempotent** — every step is safe to re-run; no-change syncs are no-ops.
|
|
94
85
|
- **Toolchain floors** — `SoT/toolchain.json` records the kit-verified version
|
|
95
86
|
floors for external tools (bun, omp, …). `docks-kit toolchain check` prints
|
|
@@ -116,7 +107,6 @@ the pre-CLI `sync.sh` flags).
|
|
|
116
107
|
| Path | Purpose |
|
|
117
108
|
|------|---------|
|
|
118
109
|
| `SoT/.omp/` | omp SoT (AGENTS.md, config.yml, models.yml, mcp.json, intercom.json, and the `plugin/` source of `docks-kit-omp`) |
|
|
119
|
-
| `SoT/.agents/` | Universal-skill manifest |
|
|
120
110
|
| `SoT/toolchain.json` | Verified-version floors |
|
|
121
111
|
| `cli/src/engine-native/` | EngineNative sync/toolchain implementation |
|
|
122
112
|
| `cli/src/generated/sotPayload.ts` | Generated in-memory payload used by standalone and npm installs |
|
|
@@ -313,9 +313,11 @@ Its shape guard checks only what a static check can prove. Each condition
|
|
|
313
313
|
must start with the forward key prefix, and this rejects the leading
|
|
314
314
|
lookbehind that froze omp. No `|` can stand outside every group, because the
|
|
315
315
|
alternative after it needs no key prefix. The shape guard cannot prove
|
|
316
|
-
linear time. The backstop
|
|
317
|
-
`cli/test/lib/ompTriggerBackstop.ts` under Bun, because
|
|
318
|
-
V8, which does not show the JavaScriptCore cost.
|
|
316
|
+
linear time. The backstop tests the measured input families for linear
|
|
317
|
+
time: the test runs `cli/test/lib/ompTriggerBackstop.ts` under Bun, because
|
|
318
|
+
the unit tests run on V8, which does not show the JavaScriptCore cost. A
|
|
319
|
+
condition can still backtrack on a run that no generator holds, so a new
|
|
320
|
+
condition needs a new family when its shape is new. The backstop has these
|
|
319
321
|
checks:
|
|
320
322
|
|
|
321
323
|
- Time budget, with the regex JIT on: one pass of all conditions over a
|
package/cli/docs/flags.md
CHANGED
|
@@ -3,29 +3,22 @@
|
|
|
3
3
|
Convention: global flags are unprefixed; a flag that touches one tool's
|
|
4
4
|
deployed config is `--<tool>-<setting>`.
|
|
5
5
|
|
|
6
|
-
##
|
|
6
|
+
## Sync
|
|
7
7
|
|
|
8
8
|
```
|
|
9
|
-
docks-kit sync #
|
|
10
|
-
docks-kit sync
|
|
11
|
-
docks-kit sync agents omp # two
|
|
9
|
+
docks-kit sync # deploy the omp SoT
|
|
10
|
+
docks-kit sync --dry-run # preview it
|
|
12
11
|
```
|
|
13
12
|
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
selection with `docks-kit harnesses`. With no stored selection, its picker
|
|
18
|
-
pre-ticks both harnesses; a flag-less `sync` does not change until the picker
|
|
19
|
-
saves a selection. In the picker, Enter or Space ticks or unticks the harness
|
|
20
|
-
under the cursor, Enter on the Save row stores the selection, and Escape
|
|
21
|
-
leaves it unchanged.
|
|
13
|
+
`sync` deploys the omp SoT and takes no positional argument. A word after
|
|
14
|
+
`sync`, such as `omp`, stops it with `Unexpected positional argument` and
|
|
15
|
+
exit 1.
|
|
22
16
|
|
|
23
17
|
## Global flags
|
|
24
18
|
|
|
25
19
|
| Flag | Effect |
|
|
26
20
|
|------|--------|
|
|
27
21
|
| `--dry-run` | Preview without applying; takes no sync lock and no folder lock |
|
|
28
|
-
| `--prune` | Remove the kit-managed universal skills that `~/.agents/.kit-owned-skills` names and SoT no longer lists |
|
|
29
22
|
| `--skip-plugin-refresh` | Install missing omp plugins but skip refresh-only updates |
|
|
30
23
|
| `--verbose` / `-v` | Also print no-op confirmations (already in sync, up to date, left as-is); accepted on `sync` and `toolchain` |
|
|
31
24
|
|
|
@@ -33,7 +26,6 @@ leaves it unchanged.
|
|
|
33
26
|
|
|
34
27
|
| Variable | Effect |
|
|
35
28
|
|----------|--------|
|
|
36
|
-
| `DOCKS_KIT_SYNC_CONCURRENCY=1\|2\|3` | Maximum selected sync pipelines running at once. Default `3`; use `1` for serial golden/debug execution. Invalid values fail `sync` with exit 2 but do not affect `toolchain`. |
|
|
37
29
|
| `DOCKS_KIT_SYNC_LOCK_WAIT_MS=<ms>` | Time that `sync` and `omp --fast` wait for another sync to release a sync lock. A non-negative safe integer in milliseconds (at most `9007199254740991`); unset or empty means `120000` (120 s). Any other value prints `DOCKS_KIT_SYNC_LOCK_WAIT_MS must be a non-negative safe integer` and exits 2. |
|
|
38
30
|
|
|
39
31
|
## Sync lock
|
|
@@ -45,12 +37,11 @@ runs never write the same files at once.
|
|
|
45
37
|
(`DOCKS_KIT_SYNC_LOCK_WAIT_MS` changes the wait). It then prints
|
|
46
38
|
`another docks-kit sync holds <path>; run sync again after it ends` and
|
|
47
39
|
exits 1 with no change.
|
|
48
|
-
- Two homes can share an
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
then names that lock file.
|
|
40
|
+
- Two homes can share an omp folder (`PI_CODING_AGENT_DIR`, `PI_CONFIG_DIR`,
|
|
41
|
+
`XDG_DATA_HOME`, or a symlink). So a writing sync also holds
|
|
42
|
+
`.docks-kit-sync-lock.db` inside each such folder that it writes: the omp
|
|
43
|
+
agent folder, the intercom folder, and the omp data root. The held line then
|
|
44
|
+
names that lock file.
|
|
54
45
|
- A writing sync creates a missing folder of this set just before it takes the
|
|
55
46
|
lock of that folder, after the locks of its ancestors in the set. Each folder
|
|
56
47
|
that it creates gets mode 0700. The lock step does not change the mode of an
|
|
@@ -132,12 +123,3 @@ forwarded `--model` stops the launcher with exit 2, also behind `--`.
|
|
|
132
123
|
| `tidy --apply` | Take the lock `~/.cache/docks-kit/tidy-lock.db`, then plan, perform those actions, and append the outcomes to `~/.cache/docks-kit/tidy.log`; exit 1 when an action fails. When another run holds the lock, print only `another docks-kit tidy run holds <path>`, with no plan and no report, and exit 0. A dry run (`tidy` without `--apply`) and the `--report` sections take no lock |
|
|
133
124
|
| `tidy --repo <path>` | Take the worktree candidates only from that repository, at any location |
|
|
134
125
|
| `tidy --report` | After the plan, print read-only sections on memory, temporary directories, processes, Docker, caches, Trash, git, agent histories, scheduled jobs, and global installs |
|
|
135
|
-
|
|
136
|
-
## Renamed legacy flags (pre-CLI sync.sh)
|
|
137
|
-
|
|
138
|
-
Old flags exit with a rename hint — there is no compat behavior.
|
|
139
|
-
|
|
140
|
-
| Old | New |
|
|
141
|
-
|-----|-----|
|
|
142
|
-
| `--agents` / `--omp` | positional `agents` / `omp` |
|
|
143
|
-
| `--remove-plugins` | `--prune` |
|
package/cli/docs/install.md
CHANGED
|
@@ -159,7 +159,7 @@ sync/config reads.
|
|
|
159
159
|
## Prerequisites
|
|
160
160
|
|
|
161
161
|
- Bun for source/global installs; release binaries embed the runtime
|
|
162
|
-
-
|
|
162
|
+
- npm for an npm-installed kit
|
|
163
163
|
- jq is optional doctor/test tooling; sync has no jq runtime dependency
|
|
164
164
|
- curl is needed only to download Bun's upstream installer when Bun is absent:
|
|
165
165
|
by the POSIX `docks-kit` launcher, by the POSIX `install.sh`, and by sync's
|
package/cli/docs/omp-context.md
CHANGED
|
@@ -1,7 +1,9 @@
|
|
|
1
1
|
# omp context and compaction
|
|
2
2
|
|
|
3
3
|
This topic records why `SoT/.omp/config.yml` ships no compaction threshold,
|
|
4
|
-
and what omp's reserve-based default computes on each model lane.
|
|
4
|
+
and what omp's reserve-based default computes on each model lane. It also
|
|
5
|
+
records the omp 19.0.0 tools that the kit turns on and the kit overrides that
|
|
6
|
+
0.24.0 returned to the omp defaults.
|
|
5
7
|
|
|
6
8
|
## How omp resolves the trigger
|
|
7
9
|
|
|
@@ -100,13 +102,13 @@ No current role model has a window below 272,000, so the hazard was latent
|
|
|
100
102
|
rather than live. Not pinning removes it entirely, including for any future
|
|
101
103
|
model with a smaller window.
|
|
102
104
|
|
|
103
|
-
## Idle compaction is
|
|
105
|
+
## Idle compaction is off
|
|
104
106
|
|
|
105
|
-
`SoT/.omp/config.yml`
|
|
106
|
-
`false`
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
107
|
+
Up to 0.23.0, `SoT/.omp/config.yml` set `compaction.idleEnabled: true`. In
|
|
108
|
+
0.24.0 the owner returned the key to the omp default `false` (omp 18.4.4
|
|
109
|
+
through 19.0.0). Sync prunes a deployed `true` that the kit shipped, so idle
|
|
110
|
+
compaction is off. With the default threshold settings, only the
|
|
111
|
+
reserve-based trigger starts a compaction.
|
|
110
112
|
|
|
111
113
|
## Related settings left at their omp defaults
|
|
112
114
|
|
|
@@ -119,3 +121,73 @@ key turns idle compaction off on fresh installs.
|
|
|
119
121
|
|
|
120
122
|
Every row records a decision to leave the omp default in place. None of these
|
|
121
123
|
keys carries a kit value that differs from the default omp already applies.
|
|
124
|
+
|
|
125
|
+
## omp 19.0.0 tools and returned overrides
|
|
126
|
+
|
|
127
|
+
The owner made these decisions on 2026-11-19 (#184). They apply from 0.24.0.
|
|
128
|
+
|
|
129
|
+
### Tools that the kit turns on
|
|
130
|
+
|
|
131
|
+
- `astGrep.enabled: true` gives the `ast_grep` tool. It searches code by its
|
|
132
|
+
syntax tree (AST), on the local disk only.
|
|
133
|
+
- `checkpoint.enabled: true` gives the `checkpoint` and `rewind` tools.
|
|
134
|
+
`checkpoint` marks the start of an investigation. `rewind` replaces the
|
|
135
|
+
transcript after that mark with a short report. It restores no file, git
|
|
136
|
+
state, artifact, or process, and a rule line in `SoT/.omp/AGENTS.md` says
|
|
137
|
+
so. A subagent gets the two tools only when its tool list asks for one of
|
|
138
|
+
them.
|
|
139
|
+
|
|
140
|
+
The memory backend (`memory.backend: off`), `autolearn.enabled`, and
|
|
141
|
+
`prewalk.enabled` stay off. All three are off by default, so the SoT has no
|
|
142
|
+
key for them. Every other omp 19.0.0 feature keeps its omp default, for
|
|
143
|
+
example context notes, `security_scan`, `task.crossInstance`,
|
|
144
|
+
`mcp.evalNamespaces`, and cache warming. The advisor stays removed (0.22.22).
|
|
145
|
+
|
|
146
|
+
### Overrides returned to the omp defaults
|
|
147
|
+
|
|
148
|
+
The SoT no longer ships these 18 keys. `ompRemovals.ts OMP_RETIRED_VALUES`
|
|
149
|
+
records each key with its old kit value. Sync prunes a deployed key only
|
|
150
|
+
while it holds that value, so a value that you changed stays.
|
|
151
|
+
|
|
152
|
+
| Key | Old kit value | omp 19.0.0 default |
|
|
153
|
+
|---|---|---|
|
|
154
|
+
| `task.maxConcurrency` | `16` | `32` |
|
|
155
|
+
| `task.maxEffort` | `xhigh` | `max` |
|
|
156
|
+
| `task.maxRuntimeMs` | `3600000` | `0` |
|
|
157
|
+
| `task.agentIdleTtlMs` | `120000` | `420000` |
|
|
158
|
+
| `task.enableLsp` | `true` | `false` |
|
|
159
|
+
| `task.eager` | `always` | `default` |
|
|
160
|
+
| `task.showResolvedModelBadge` | `true` | `false` |
|
|
161
|
+
| `find.enabled` | `true` | `auto` |
|
|
162
|
+
| `providers.webSearchTimeoutSeconds` | `30` | `60` |
|
|
163
|
+
| `browser.idleCloseSec` | `600` | `1800` |
|
|
164
|
+
| `steeringMode` | `all` | `one-at-a-time` |
|
|
165
|
+
| `doubleEscapeAction` | `tree` | `rewind` |
|
|
166
|
+
| `features.unexpectedStopDetection` | `smart` | `mechanical` |
|
|
167
|
+
| `compaction.idleEnabled` | `true` | `false` |
|
|
168
|
+
| `compaction.handoffSaveToDisk` | `true` | `false` |
|
|
169
|
+
| `commands.enableOpencodeProject` | `false` | `true` |
|
|
170
|
+
| `statusLine.compactThinkingLevel` | `false` | `true` |
|
|
171
|
+
| `github.enabled` | `true` | `false` |
|
|
172
|
+
|
|
173
|
+
Sync cannot tell the old kit value from the same value that you set again.
|
|
174
|
+
It prunes both on every sync. To keep an old kit value, set it in a project
|
|
175
|
+
configuration or in a `PI_CONFIG_FILES` file, which sync does not write.
|
|
176
|
+
|
|
177
|
+
The `github` tool is off by default. Its `pr_push` operation runs git
|
|
178
|
+
directly, so the `bash.patterns` guards do not see it. The `issue://` and
|
|
179
|
+
`pr://` read schemes do not need the tool. omp reads them through its GitHub
|
|
180
|
+
cache and `gh` (`omp://tools/read.md`, `omp://tools/github.md`), so they still
|
|
181
|
+
work with `github.enabled: false`. The plan-lifecycle work reads issues with
|
|
182
|
+
`gh` in bash, so the change does not affect it.
|
|
183
|
+
|
|
184
|
+
### Overrides that stay
|
|
185
|
+
|
|
186
|
+
- `branchSummary.enabled: true`.
|
|
187
|
+
- `dev.autoqa: false` with `dev.autoqaConsent: denied`.
|
|
188
|
+
- `codexResets.autoRedeem5h: "no"` and `codexResets.autoRedeemWeekly: "no"`.
|
|
189
|
+
- `startup.quiet: true`.
|
|
190
|
+
- `display.showTokenUsage: true`.
|
|
191
|
+
- The model roles, `cycleOrder`, `retry.fallbackChains`, `modelTags`, the
|
|
192
|
+
reviewer overrides in `task.agentModelOverrides` and
|
|
193
|
+
`task.agentServiceTierOverrides`, and the `bash.patterns` guards.
|
package/cli/docs/omp-models.md
CHANGED
|
@@ -656,13 +656,15 @@ keeps a block that the user edited.
|
|
|
656
656
|
not onto level names: `lo` selects the lowest level, `med` the lower middle,
|
|
657
657
|
and `hi` the highest (`resolveTaskEffortLevel` in omp's
|
|
658
658
|
`packages/tui/src/thinking.ts`, omp 18.8.5). Then omp caps the result at
|
|
659
|
-
`task.maxEffort`.
|
|
660
|
-
`
|
|
661
|
-
despite the `:high` role suffix. On
|
|
662
|
-
18.16.0 with the field off had no
|
|
663
|
-
|
|
664
|
-
|
|
665
|
-
|
|
659
|
+
`task.maxEffort`. Up to 0.23.0 the kit set that cap to `xhigh`. On the
|
|
660
|
+
`low, medium, high, xhigh, max` ladder, `hi` then gave `xhigh`, so many
|
|
661
|
+
`task` spawns ran Opus 5.5 xhigh despite the `:high` role suffix. On
|
|
662
|
+
2026-11-05, a fresh `omp -p` run on omp 18.16.0 with the field off had no
|
|
663
|
+
`effort` field, and its `task` child recorded
|
|
664
|
+
`resolvedModel: anthropic/claude-opus-5-5:high`.
|
|
665
|
+
- Since 0.24.0 the kit sets no `task.maxEffort`, so the cap is omp's default
|
|
666
|
+
`max`. With `task.enableEffort` off, the cap applies only to a per-call
|
|
667
|
+
`model` with a `:level` suffix.
|
|
666
668
|
- In the deployed config, `scout` and `sonic` run GPT-6 Luna `medium`. The
|
|
667
669
|
four reviewer agents resolve `@reviewer` and run GPT-6.1 Terra `high` on the
|
|
668
670
|
live tier of the main session. A `docks-kit omp` free session replaces
|
|
@@ -702,9 +704,10 @@ web-search provider order therefore applies, and that order includes the paid
|
|
|
702
704
|
deployed retry chain, such as a `plan`, `slow`, or `designer` chain, therefore
|
|
703
705
|
stays in the merged config. A retry of the free model does not reach such a
|
|
704
706
|
chain, because omp uses the empty chain keyed by the free model first.
|
|
705
|
-
The overlay also sets `defaultThinkingLevel` and `task.maxEffort
|
|
706
|
-
a model that publishes no thinking ladder,
|
|
707
|
-
deployed or
|
|
707
|
+
The overlay also sets `defaultThinkingLevel` and `task.maxEffort` to the
|
|
708
|
+
session level. For a model that publishes no thinking ladder, the overlay
|
|
709
|
+
omits both keys. A value in the deployed config then applies, or else the omp
|
|
710
|
+
default, which is `max` for `task.maxEffort`.
|
|
708
711
|
|
|
709
712
|
The launcher renders a run overlay to
|
|
710
713
|
`~/.cache/docks-kit/omp-free-<model>-<digest>.yml` at mode 0600 and passes it
|
|
@@ -800,7 +803,7 @@ bare selectors with no `:level` suffix, because an invented level makes omp
|
|
|
800
803
|
fail when the session starts.
|
|
801
804
|
|
|
802
805
|
The choice persists per machine in `~/.docks-kit/kit.db` (table
|
|
803
|
-
`omp_session`)
|
|
806
|
+
`omp_session`). It survives across sessions. It is never
|
|
804
807
|
committed. `--model <selector>` records one selector and derives the level
|
|
805
808
|
from the catalog row. `--pick` opens an interactive wizard.
|
|
806
809
|
|
|
@@ -915,4 +918,7 @@ on normal processing, use `docks-kit omp --fast` and a new session, not
|
|
|
915
918
|
- Update the capture date in the same commit as any number.
|
|
916
919
|
- Verify Astra ladder changes in `SoT/.omp/models.yml` through the model
|
|
917
920
|
switcher and in-session thinking control.
|
|
918
|
-
-
|
|
921
|
+
- The kit leaves `task.maxEffort` and `task.enableEffort` at omp's defaults,
|
|
922
|
+
`max` and `false`. After an omp update, check both in
|
|
923
|
+
`omp config list --json`. Verify a kit change to either key with a fresh
|
|
924
|
+
`omp -p` spawn per bundled agent.
|
package/cli/docs/overview.md
CHANGED
|
@@ -1,15 +1,14 @@
|
|
|
1
1
|
# docks-kit overview
|
|
2
2
|
|
|
3
|
-
docks-kit is a portable configuration kit for AI coding agents.
|
|
4
|
-
|
|
5
|
-
|
|
3
|
+
docks-kit is a portable configuration kit for AI coding agents. Its Single
|
|
4
|
+
Source of Truth (SoT) directory `SoT/.omp/` deploys to the user-config location
|
|
5
|
+
of Oh My Pi (`omp`). Clone once, sync everywhere, and get a consistent
|
|
6
6
|
AI-assisted dev environment on every machine.
|
|
7
7
|
|
|
8
8
|
## Pieces
|
|
9
9
|
|
|
10
10
|
| Piece | Role |
|
|
11
11
|
|-------|------|
|
|
12
|
-
| `SoT/.agents/` | Universal agent skills manifest (agentskills.io standard) |
|
|
13
12
|
| `SoT/.omp/` | omp config deployed to `~/.omp/agent/` (AGENTS.md, config.yml, models.yml, mcp.json) plus `intercom.json` for pi intercom, plus the `plugin/` tree, deployed to `~/.docks-kit/omp-plugin` and linked as the `docks-kit-omp` omp plugin |
|
|
14
13
|
| `SoT/toolchain.json` | Verified-version floors for external tools (see `docks-kit docs toolchain`) |
|
|
15
14
|
| `cli/src/generated/sotPayload.ts` | Deterministic generated payload embedded in standalone/npm execution |
|
|
@@ -23,9 +22,7 @@ AI-assisted dev environment on every machine.
|
|
|
23
22
|
- **Quiet on no-ops**: by default a re-run prints only real changes, warnings
|
|
24
23
|
(with a platform-correct install command when a tool is missing), and the
|
|
25
24
|
summary; `--verbose` / `-v` also prints the no-op confirmations.
|
|
26
|
-
- **Additive by default**: user-only keys
|
|
27
|
-
Removing kit-managed universal skills that left the SoT is explicit:
|
|
28
|
-
`--prune`.
|
|
25
|
+
- **Additive by default**: user-only keys and plugins survive a plain sync.
|
|
29
26
|
- **Engine/CLI split**: the CLI adds UX (typed flags, pickers, docs, JSON);
|
|
30
27
|
EngineNative owns mutation. No-Bun recovery is a platform release binary.
|
|
31
28
|
- **Authoring/runtime split**: changes begin in `SoT/`; build/prepack freshness
|
|
@@ -34,5 +31,5 @@ AI-assisted dev environment on every machine.
|
|
|
34
31
|
## Where to go next
|
|
35
32
|
|
|
36
33
|
- `docks-kit docs sync-layers` — what a sync actually touches
|
|
37
|
-
- `docks-kit docs flags` — full flag reference
|
|
34
|
+
- `docks-kit docs flags` — full flag reference
|
|
38
35
|
- `docks-kit toolchain` — doctor view of this machine's external tools
|
package/cli/docs/sync-layers.md
CHANGED
|
@@ -1,13 +1,12 @@
|
|
|
1
1
|
# Sync layers
|
|
2
2
|
|
|
3
|
-
`docks-kit sync
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
healing, and the kit-owned record that `--prune` removes against.
|
|
3
|
+
`docks-kit sync` deploys the omp SoT. It takes no positional target. Sync
|
|
4
|
+
writes no `.agents` or `.claude` folder of its own; omp's folders follow
|
|
5
|
+
`PI_CONFIG_DIR`, `PI_CODING_AGENT_DIR`, and `XDG_DATA_HOME`, so an override
|
|
6
|
+
that points into one of those folders makes omp's files go there. omp uses
|
|
7
|
+
`XDG_DATA_HOME` only on Linux and macOS, only while `PI_CODING_AGENT_DIR`
|
|
8
|
+
does not move the agent folder, and only after the omp folder under it
|
|
9
|
+
exists. Sync also writes the kit plugin to `~/.docks-kit/omp-plugin`.
|
|
11
10
|
|
|
12
11
|
## omp (→ resolved agent dir, intercom root)
|
|
13
12
|
|
|
@@ -118,7 +117,9 @@ into `<agent directory>/intercom`. Otherwise it goes into
|
|
|
118
117
|
`$PI_CODING_AGENT_DIR/intercom` when that variable is set, else
|
|
119
118
|
`~/.pi/agent/intercom`.
|
|
120
119
|
|
|
121
|
-
##
|
|
120
|
+
## Additive by default
|
|
122
121
|
|
|
123
|
-
|
|
124
|
-
|
|
122
|
+
Sync has no removal flag. A key, plugin, or file that only the user added
|
|
123
|
+
stays. Two passes remove kit content on every sync: the `ompRemovals.ts`
|
|
124
|
+
retired-key inventory above, and the kit plugin pass, which removes stale
|
|
125
|
+
files from the kit-owned `~/.docks-kit/omp-plugin`.
|
package/cli/docs/toolchain.md
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
| Field | Meaning |
|
|
6
6
|
|-------|---------|
|
|
7
|
-
| `kind` | `check` (doctor visibility) / `managed` (kit-managed install) / `pin` (no binary — a version pin for a package that the kit installs through another tool
|
|
7
|
+
| `kind` | `check` (doctor visibility) / `managed` (kit-managed install) / `pin` (no binary — a version pin for a package that the kit installs through another tool, such as `omp install` for `pi-intercom`; the required `via` field names that tool in the doctor table) |
|
|
8
8
|
| `policy` | Installation policy; `present` installs when missing and never upgrades |
|
|
9
9
|
| `floor` | Minimum acceptable version shown in the doctor table |
|
|
10
10
|
| `verified` | Last kit-tested version and the exact pin for kit-driven installs |
|
|
@@ -31,11 +31,11 @@ an installer. An already-present Bun skips that download on every host.
|
|
|
31
31
|
|
|
32
32
|
## Supply-chain stance
|
|
33
33
|
|
|
34
|
-
Every kit-driven package install from npm,
|
|
34
|
+
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
|
-
the
|
|
38
|
-
|
|
37
|
+
the release workflow (actions pinned to commit SHAs, exact bun/npm versions).
|
|
38
|
+
The existing omp
|
|
39
39
|
marketplace plugins have no manifest pin: sync installs and refreshes them at
|
|
40
40
|
the version that their marketplace publishes (see `sync-layers`). Any new
|
|
41
41
|
install surface, a new marketplace or plugin source included, needs a
|