@fro.bot/systematic 3.26.4 → 3.27.1
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/HARNESSES.md +55 -15
- package/README.md +8 -2
- package/dist/cli.js +2 -2
- package/dist/{index-1dyb2x0z.js → index-608preny.js} +1 -1
- package/dist/index.d.ts +7 -3
- package/dist/index.js +817 -97
- package/dist/lib/asset-plan.d.ts +94 -0
- package/dist/lib/bootstrap.d.ts +17 -0
- package/dist/lib/config-handler.d.ts +39 -9
- package/dist/lib/opencode-v1.d.ts +17 -0
- package/dist/lib/opencode-v2-bootstrap.d.ts +37 -0
- package/dist/lib/opencode-v2-commands.d.ts +36 -0
- package/dist/lib/opencode-v2-permissions.d.ts +32 -0
- package/dist/lib/opencode-v2-skills.d.ts +66 -0
- package/dist/lib/opencode-v2.d.ts +96 -0
- package/dist/lib/skill-tool.d.ts +46 -0
- package/package.json +20 -5
- package/skills/git-commit/SKILL.md +3 -5
- package/skills/git-commit-push-pr/SKILL.md +3 -5
- package/skills/using-systematic/references/opencode-v2-profile.md +75 -0
package/HARNESSES.md
CHANGED
|
@@ -2,18 +2,18 @@
|
|
|
2
2
|
|
|
3
3
|
This is the evidence registry for Systematic's harness-portability work. **Every tool or mechanism named here is backed by an in-repo path with line numbers, installed or cloned source, or an authoritative URL.** If the supplied research did not verify a capability, it is explicitly marked **UNVERIFIED**; absence of evidence is not evidence of absence.
|
|
4
4
|
|
|
5
|
-
**Tiers.** Tier 1 means Systematic ships a controlled adapter: OpenCode, Pi, and Claude Code. Tier 2 means the harness is documented for portability but has no Systematic adapter: Codex CLI, Gemini CLI, and GitHub Copilot.
|
|
5
|
+
**Tiers.** Tier 1 means Systematic ships a controlled adapter: OpenCode (the v1 and v2 lines, one package), Pi, and Claude Code. Tier 2 means the harness is documented for portability but has no Systematic adapter: Codex CLI, Gemini CLI, and GitHub Copilot.
|
|
6
6
|
|
|
7
7
|
## Capability matrix
|
|
8
8
|
|
|
9
|
-
The four capability rows use the vocabulary in the [OpenCode profile](skills/using-systematic/references/opencode-profile.md#L3-L8), [Pi profile](skills/using-systematic/references/pi-profile.md#L3-L8), and [Claude Code profile](skills/using-systematic/references/claude-code-profile.md#L5-L10).
|
|
9
|
+
The four capability rows use the vocabulary in the [OpenCode profile](skills/using-systematic/references/opencode-profile.md#L3-L8), the [OpenCode v2 profile](skills/using-systematic/references/opencode-v2-profile.md#L5-L10), [Pi profile](skills/using-systematic/references/pi-profile.md#L3-L8), and [Claude Code profile](skills/using-systematic/references/claude-code-profile.md#L5-L10).
|
|
10
10
|
|
|
11
11
|
| Capability | OpenCode (Tier 1) | Pi (Tier 1) | Claude Code (Tier 1) | Codex CLI (Tier 2) | Gemini CLI (Tier 2) | GitHub Copilot (Tier 2) |
|
|
12
12
|
|---|---|---|---|---|---|---|
|
|
13
|
-
| Subagent delegation | `task`, including `subagent_type`, resume, and background execution [OC-1] | Bounded built-in delegate: `systematic_delegate({agent, task})`; sequential, capped at 20 turns, depth-1, `noExtensions` [PI-1]. Optional mature delegation via pi-subagents (installed package personas, opt-in export for overlays; outside Systematic's bounded-delegate guarantees) [PI-7] | Name-based subagent dispatch (invoke a subagent by name in the prompt text); `context: fork` for skill-scoped forks; plugin agents ship in `agents/` [CC-1][CC-9] | **UNVERIFIED** [U] | **UNVERIFIED** [U] | Built-in/custom agents [GH-1][GH-2] |
|
|
14
|
-
| Blocking user interaction | `question` [OC-2] | No native blocking tool; numbered-chat fallback [PI-2] | `AskUserQuestion` [CC-2] | `request_user_input`; blocking and root-thread-only [CX-1][CX-2] | `ask_user`; pauses until answers [GE-1][GE-2] | No dedicated tool name verified; plan-mode clarification and `--no-ask-user` are documented [GH-3][GH-4] |
|
|
15
|
-
| Task tracking | `todowrite` [OC-3] | No native mechanism; visible list fallback [PI-2] | `TodoWrite` is deprecated/disabled by default; `TaskCreate`/`TaskGet`/`TaskList`/`TaskUpdate` replace it [CC-3][CC-4] | **UNVERIFIED** [U] | **UNVERIFIED** [U] | No `TodoWrite` equivalent verified; cloud-agent tasks/sessions API is documented [GH-5] |
|
|
16
|
-
| Skill loading | Skills become commands and `systematic_skill` is registered [OC-4][OC-5] | `systematic_skill` adapter and Pi-native activation [PI-3][PI-4] | Native Skill tool with `SKILL.md` discovery (`~/.claude/skills/`, `.claude/skills/`, plugin `skills/`); Systematic ships no `systematic_skill` tool on Claude Code [CC-5][CC-6][CC-9] | **UNVERIFIED** [U] | **UNVERIFIED** [U] | `SKILL.md` skills [GH-6] |
|
|
13
|
+
| Subagent delegation | v1: `task`, including `subagent_type`, resume, and background execution [OC-1]. v2: `subagent`, with `agent`, `sessionID` to resume, and `background` [OC2-PROFILE] | Bounded built-in delegate: `systematic_delegate({agent, task})`; sequential, capped at 20 turns, depth-1, `noExtensions` [PI-1]. Optional mature delegation via pi-subagents (installed package personas, opt-in export for overlays; outside Systematic's bounded-delegate guarantees) [PI-7] | Name-based subagent dispatch (invoke a subagent by name in the prompt text); `context: fork` for skill-scoped forks; plugin agents ship in `agents/` [CC-1][CC-9] | **UNVERIFIED** [U] | **UNVERIFIED** [U] | Built-in/custom agents [GH-1][GH-2] |
|
|
14
|
+
| Blocking user interaction | `question` on v1 [OC-2] and v2 [OC2-PROFILE] | No native blocking tool; numbered-chat fallback [PI-2] | `AskUserQuestion` [CC-2] | `request_user_input`; blocking and root-thread-only [CX-1][CX-2] | `ask_user`; pauses until answers [GE-1][GE-2] | No dedicated tool name verified; plan-mode clarification and `--no-ask-user` are documented [GH-3][GH-4] |
|
|
15
|
+
| Task tracking | `todowrite` on v1 [OC-3]; on v2 only when the experimental `todo` option is on [OC2-TODO] | No native mechanism; visible list fallback [PI-2] | `TodoWrite` is deprecated/disabled by default; `TaskCreate`/`TaskGet`/`TaskList`/`TaskUpdate` replace it [CC-3][CC-4] | **UNVERIFIED** [U] | **UNVERIFIED** [U] | No `TodoWrite` equivalent verified; cloud-agent tasks/sessions API is documented [GH-5] |
|
|
16
|
+
| Skill loading | Skills become commands and `systematic_skill` is registered [OC-4][OC-5]; v2 also registers each skill with the host's own `skill` tool [OC2-SKILL] | `systematic_skill` adapter and Pi-native activation [PI-3][PI-4] | Native Skill tool with `SKILL.md` discovery (`~/.claude/skills/`, `.claude/skills/`, plugin `skills/`); Systematic ships no `systematic_skill` tool on Claude Code [CC-5][CC-6][CC-9] | **UNVERIFIED** [U] | **UNVERIFIED** [U] | `SKILL.md` skills [GH-6] |
|
|
17
17
|
| Skills-file support | `SKILL.md` is loaded by the Systematic skill path [OC-4] | `pi.skills` ships `./skills`, including `SKILL.md` discovery [PI-4][PI-5] | `SKILL.md` and `.claude/skills/`; the plugin bundle is built and identifier-translated in CI from `skills/`, never committed [CC-5][CC-6][CC-9] | **UNVERIFIED** [U] | **UNVERIFIED** [U] | `SKILL.md` [GH-6] |
|
|
18
18
|
|
|
19
19
|
`[U]` means the capability was not checked in the supplied research pack. It is not a claim that the capability does not exist.
|
|
@@ -24,6 +24,31 @@ OpenCode is the primary controlled integration. Its profile defines delegation,
|
|
|
24
24
|
|
|
25
25
|
Compatibility is direct: OpenCode consumes the concrete invocation language in the profile. The adapter is not a generic claim about other harnesses.
|
|
26
26
|
|
|
27
|
+
The citations above (OC-1 to OC-8) describe the v1 adapter. The v2 adapter is the next section.
|
|
28
|
+
|
|
29
|
+
## OpenCode v2 — Tier 1 shipped adapter
|
|
30
|
+
|
|
31
|
+
One package serves both OpenCode lines. v1 (1.18.29 and later) reads the `plugin` key and calls `server`; v2 (2.2.0 and later) reads `plugins` and calls `setup(ctx)`. Versions below those floors are unsupported, with no shim. The floors are a support decision, not a loader limit: the loader probe found that 1.18.28 and v2 2.1.4 load the object default exactly as the floor versions do, and that v2 2.1.4 silently drops a function default while 2.2.0 logs a warning [OC2-LOADER]. v2 2.2.0 is the oldest v2 release the adapter is tested on; whether earlier releases provide every API it uses was not probed.
|
|
32
|
+
|
|
33
|
+
Each v2 mechanism was chosen by a probe against OpenCode 2.2.0 on 2026-10-27. The table records which mechanism won and what covers it. "CI" names the job that runs the test; every v2 test below runs in `Host Contract v2 shard N/4` (the `v2` profile in `scripts/host-contract-guard.ts`) against the pinned v2 CLI in `scripts/opencode-host-pins.json`, and the `Host Contract` check aggregates it. Behaviors that no CI test reaches are labeled "local probe, OpenCode 2.2.0, 2026-10-27": they were observed once on a real host, are not re-checked by CI, and the scratch logs behind them are not published.
|
|
34
|
+
|
|
35
|
+
| Probe | Outcome | Mechanism the adapter uses | Evidence |
|
|
36
|
+
|---|---|---|---|
|
|
37
|
+
| Agent creation | Passed | `ctx.agent.transform` with `editor.update(id, fn)` creates a missing agent from a default skeleton. Unknown fields are stripped, so there is no ownership marker; user config applies after every plugin transform and overlays a same-named agent | [OC2-AGENT] |
|
|
38
|
+
| Instruction entries | Passed, with a different trigger | One keyed entry (`systematic.bootstrap`) per session, put from `ctx.session.hook('prompt')`. `session.created` is not used, because the first session after a service start never sees it | [OC2-INSTR] |
|
|
39
|
+
| Per-kind request hooks | Not needed | The `context` hook is used only to restore truncated skill output; the bootstrap does not use it | [OC2-CTX] |
|
|
40
|
+
| Permissions | Passed | Ordered `{action, resource, effect}` lists, last match wins; `bash` becomes `shell`, `task` becomes `subagent`, `doom_loop` and `lsp` have no v2 action | [OC2-PERM] |
|
|
41
|
+
| Native skill tool | Partial | The host tool loads plugin-added skills and refuses denied ones, but takes only an `{id}`, so `$ARGUMENTS` cannot be passed. `systematic_skill` is ported | [OC2-SKILL] |
|
|
42
|
+
| Plugin tool registration | Passed | `ctx.tool.transform` with a JSON Schema input and `options: {codemode: false}` (the default registration is reachable only through Code Mode) | [OC2-TOOL] |
|
|
43
|
+
| Output truncation | Truncates | The host cuts tool output at 2000 lines or 51200 bytes after the plugin's `execute.after` hook sees the full text. The full text is kept by call id and put back in the `context` hook; nothing depends on the marker text | [OC2-TRUNC] |
|
|
44
|
+
| Commands | Passed, with constraints | `ctx.command.transform`; a plugin command receives only the typed text and does its own expansion; routing is not offered to plugin commands, so a command that declares `agent`, `model` or `subtask` is refused; a name that matches a built-in replaces it | [OC2-CMD] |
|
|
45
|
+
| Apply order | Documented | Plugin transforms run first, then user config and discovered sources; `reload()` replays transforms on a fresh editor and does not re-run `setup` | [OC2-ORDER] |
|
|
46
|
+
| Error handling | Documented | A rejected `setup` leaves the plugin unloaded and the host running; a throwing transform disables the whole plugin; a throwing hook breaks the turn. Every callback is guarded, and invalid config rejects `setup` as it throws on v1 | [OC2-ERR] |
|
|
47
|
+
| Project directory | Documented | `ctx.location.directory` is the project directory (the service's working directory is not); each location gets a fresh module instance and its own `setup` | [OC2-TRUST] |
|
|
48
|
+
| Task tracking tool | Conditional, unobserved | Binary strings name a `todowrite` tool behind the experimental `todo` option; no live request showed it | [OC2-TODO] |
|
|
49
|
+
|
|
50
|
+
OpenCode v2 does not make skills into commands. Systematic registers them itself, under `systematic:<name>` for bundled skills and the bare name for discovered ones.
|
|
51
|
+
|
|
27
52
|
## Pi — Tier 1 shipped adapter
|
|
28
53
|
|
|
29
54
|
Pi's profile records degraded or unavailable native capabilities and explicit fallbacks [PI-P]. The adapter registers `systematic_skill` in `src/pi.ts:217-236` and `systematic_delegate` in `src/pi.ts:238-263` [PI-3]. Delegation is explicitly sequential (`executionMode: 'sequential'`), capped at `MAX_DELEGATE_TURNS = 20`, and guarded against re-entry in `src/lib/pi-delegate-tool.ts:14-18,245-249` [PI-1]. The child is spawned with `noExtensions: true`, bounding `systematic_delegate`'s own recursion; this does not bound end-to-end depth across a combined pi-subagents + Systematic path.
|
|
@@ -66,7 +91,7 @@ Honest capability boundary: output-style enforcement is real and applies automat
|
|
|
66
91
|
|
|
67
92
|
One short rule ships in the shared bootstrap: create a worktree at `.worktrees/<branch>` under the main repository root with the `git-worktree` skill's script, and follow a different location or tool when the user or a project instruction names one. The script (`skills/git-worktree/scripts/worktree-manager.sh`) is small and non-interactive: `create`, `list`, `switch`, `copy-env` and `cleanup`, with exit codes 0 ok, 1 error, 2 usage and 3 refused, and no stdin reads. `create` places the worktree at `.worktrees/<branch>` under the main root, writes `.worktrees/.gitignore` and never edits the root `.gitignore`, and fails closed on a bare, separate-git-dir or submodule layout; `cleanup` reports and removes only named clean worktrees [WT-2]. The rule lives in `skills/using-systematic/references/worktree-placement.md` and holds no harness identifiers [WT-1]. Each adapter composes it differently:
|
|
68
93
|
|
|
69
|
-
- **OpenCode.** `
|
|
94
|
+
- **OpenCode.** Both adapters compose the bootstrap through `composeBootstrapContent`, which always supplies the rule, and `getBootstrapContent` omits it when `git-worktree` is in `disabled_skills`. It sits after the usage template and before the capability profile. `bootstrap.enabled: false` returns no bootstrap, and an existing `bootstrap.file` is returned verbatim with no rule, because the user owns that file [OC-8]. On v2 the composed text is stored as an instruction entry rather than added to the system prompt, and the same three rules are checked on a real v2 host [OC2-INSTR].
|
|
70
95
|
- **Pi.** The extension supplies the rule and passes `disabled_skills`, and nothing else from the config. The rule is therefore present unless `git-worktree` is disabled, including when `bootstrap.file` is set, because Pi never reads that setting [PI-8].
|
|
71
96
|
- **Claude Code.** The output style is static, so it always carries the rule between the using-systematic body and the profile. The build fails when the rule file is missing [CC-13].
|
|
72
97
|
|
|
@@ -78,7 +103,7 @@ The raw-return validator and the four-phase synthesis pipeline (`screen`, `prepa
|
|
|
78
103
|
`finalize`) ship as one self-contained Node bundle,
|
|
79
104
|
`skills/ce-review/scripts/validate-review.mjs`, generated from
|
|
80
105
|
`src/ce-review-validator.ts` by `scripts/generate-ce-review-validator.ts` and
|
|
81
|
-
gated by `bun run ce-review-validator:drift
|
|
106
|
+
gated by `bun run ce-review-validator:drift` (run by `bun run surfaces:drift`). The bundle dispatches six subcommands (`return`,
|
|
82
107
|
`artifact`, `screen`, `prepare`, `merge`, `finalize`) through one shared exit-code vocabulary (0
|
|
83
108
|
ok, 1 rejection/oversized/invalid UTF-8, 2 usage/TTY/read failure) and one exception boundary;
|
|
84
109
|
`merge` and `finalize` run through one shared strict-JSON stdin runner bounded by
|
|
@@ -175,20 +200,35 @@ Migrated-skill discipline is enforced by the [content-integrity gate](scripts/co
|
|
|
175
200
|
- **OC-1** — cloned OpenCode source, `.slim/clonedeps/repos/anomalyco__opencode/packages/opencode/src/tool/task.ts:24-62`.
|
|
176
201
|
- **OC-2** — cloned OpenCode source, `.slim/clonedeps/repos/anomalyco__opencode/packages/core/src/tool/question.ts:10-25`.
|
|
177
202
|
- **OC-3** — cloned OpenCode source, `.slim/clonedeps/repos/anomalyco__opencode/packages/core/src/tool/todowrite.ts:1-10`.
|
|
178
|
-
- **OC-4** — `src/lib/config-handler.ts:
|
|
179
|
-
- **OC-5** — `src/lib/skill-tool.ts:
|
|
180
|
-
- **OC-6** — `ARCHITECTURE.md:
|
|
181
|
-
- **OC-7** — `src/lib/config-handler.ts:
|
|
182
|
-
- **OC-8** — `src/
|
|
203
|
+
- **OC-4** — `src/lib/asset-plan.ts:223-234` (`loadSkillAsCommand`), `:532-551` (bundled skills as `systematic:<name>` commands), `:553-618` (discovered skills as commands); `src/lib/config-handler.ts:367-377` (`registerSkillsPaths`, the v1 skill path); `src/lib/config-handler.ts:188-274` (the v1 config hook that writes the plan into the host config); `src/lib/config-handler.ts:112-170` (`foldPermissionRulesToV1Map`, which writes each managed skill allow under both the bare and the `systematic:` name unless the user wrote a rule for the prefixed name, because v1's native `skill` tool asks with the bare name and `systematic_skill` with the prefixed one); `src/lib/config-handler.ts:276-360` (`denyDisabledSkills`, the top-level `permission.skill` deny in both name forms for each disabled skill, because the registered skills folder is not filtered). Real v1 host, 1.19.4: `tests/integration/opencode-v1.test.ts` (a managed `skills` list loads through `systematic_skill`; the native `skill` tool refuses a disabled skill).
|
|
204
|
+
- **OC-5** — `src/lib/skill-tool.ts:146-230` (`createSkillTool`, the v1 tool with the `context.ask` permission check at `:198-203`).
|
|
205
|
+
- **OC-6** — `ARCHITECTURE.md:217-223` (invariant 2) and `agents/`.
|
|
206
|
+
- **OC-7** — `src/lib/asset-plan.ts:274-380` (a model reaches an agent only through `applyAgentOverlays`, `applyAgentOverlayPass` and `applyRoutingModel`, all driven by user-owned overlays); `tests/unit/config-handler.test.ts:1173-1330` (overlay model emitted, `model: null` restores inheritance, native same-name replacement stays model-free).
|
|
207
|
+
- **OC-8** — `src/lib/opencode-v1.ts:73-79` (v1: the loaded config and `composeBootstrapContent`; the rule is always supplied and the gate lives in `getBootstrapContent`); `src/lib/bootstrap.ts:144-160` (`readWorktreePlacementRule`), `:244-253` (`bootstrap.enabled` and `bootstrap.file` return before the rule is composed), `:265-269` (the rule is omitted when `disabled_skills` contains `git-worktree`), `:279` (placement after the usage template and before the profile), `:291-314` (`composeBootstrapContent`, shared by v1 and v2); `tests/unit/bootstrap.test.ts:1025-1227` (real `loadConfig`: default, `git-worktree` disabled, another skill disabled, qualified name rejected, `bootstrap.enabled: false`, existing and missing `bootstrap.file`); `tests/unit/plugin.test.ts:1473-1610` (real v1 plugin init).
|
|
208
|
+
- **OC2-PROFILE** — [OpenCode v2 profile](skills/using-systematic/references/opencode-v2-profile.md#L5-L10). Tool names and arguments: Local probe, OpenCode 2.2.0, 2026-10-27, from the tool list of a real request (`edit`, `glob`, `grep`, `question`, `read`, `shell`, `skill`, `subagent`, `webfetch`, `websearch`, `write`, `execute`): `subagent` takes `agent`, `description`, `prompt`, `model`, `sessionID` and `background`; `question` takes `questions` with `question`, `header`, `options` and `multiple`. CI covers the `subagent` call: CI job `Host Contract v2 shard N/4` (OpenCode 2.2.0), `tests/integration/opencode-v2.test.ts` › "a subagent request carries the bootstrap once, and so does the parent request that follows it". `question` has no CI test.
|
|
209
|
+
- **OC2-LOADER** — OpenCode v1 1.18.28, 1.18.29, 1.19.4 and v2 2.1.4, 2.2.0, 2026-10-27. The object default `{id, setup, server}` loads on all five. A v1 host calls `server(input)` and then `setup(ctx)` in the same process, with a reduced context of 9 keys and no `location` or `session`; a v2 host never calls `server`. v2 2.1.4 drops a function default with no log line, and 2.2.0 logs a warning. Tarball config forms fail on v1, so installs go through `npm install <tarball>` and load the installed directory. Local probe for the version comparison. CI covers the 2.2.0 load: CI job `Host Contract v2 shard N/4` (OpenCode 2.2.0), `tests/integration/opencode-v2.test.ts` › "the packed plugin loads, setup runs once and stderr carries nothing unexpected"; the v1 loads: CI jobs `Host Contract v1 floor` and `Host Contract v1 current`, `tests/integration/opencode-v1.test.ts` › "packaged plugin loads, warns on a removed disabled_skills name, and exposes a compliant catalog"; the bridge no-op: `tests/unit/opencode-v2.test.ts` › "default export wiring" › "setup does nothing for the reduced context a v1 host passes".
|
|
210
|
+
- **OC2-HOST** — Local probe, OpenCode 2.2.0, 2026-10-27. Isolation takes `HOME`, the four `XDG_*` variables, `OPENCODE_CONFIG_DIR` and `TMPDIR`; a managed config under `/Library` on macOS is read and cannot be isolated. One-shot runs use `run --standalone`; the default `run` starts a detached shared service on port 49374. The remote client is `@opencode/client` (`OpenCode.make`), not `@opencode/sdk`, which has only the embedded `create`. The plugin runs in the service process under a compiled Bun 1.4.4, with the home directory as its working directory. The CLI install needs `npm install --dangerously-allow-all-scripts` on npm 12. CI uses this recipe: the host install step and `tests/integration/fixtures/opencode-host.ts` in CI job `Host Contract v2 shard N/4` (OpenCode 2.2.0).
|
|
211
|
+
- **OC2-AGENT** — CI job `Host Contract v2 shard N/4` (OpenCode 2.2.0): `tests/integration/opencode-v2.test.ts` › "the bundled agents appear in the agent list with their v1 description and prompt" and "a user agent with the same id in config keeps the user system prompt"; `tests/unit/opencode-v2.test.ts` › "agents installer" › "replaying the transform on a fresh editor yields the same single agent set". Local probe, OpenCode 2.2.0, 2026-10-27: an extra property set in a transform is visible to later plugins in the same replay and gone from `agent.list`, so no ownership marker survives; an agent's `model` applies only when the session names no model; a session whose agent is later unregistered fails its next turn with `Session.AgentNotFoundError`.
|
|
212
|
+
- **OC2-INSTR** — CI job `Host Contract v2 shard N/4` (OpenCode 2.2.0): `tests/integration/opencode-v2.test.ts` › "the first request of a new session carries the bootstrap with the v2 profile, once", "the title request does not carry the bootstrap", "a subagent request carries the bootstrap once, and so does the parent request that follows it", "a second turn does not duplicate the bootstrap or announce a change", "git-worktree in disabled_skills leaves the worktree rule out of the bootstrap" and "bootstrap.enabled false puts no entry and nothing reaches the model". Local probe, OpenCode 2.2.0, 2026-10-27: the entry lands in the first system message as `<context key="...">`; compaction and later requests carry it once; entries persist across a host restart, even with the plugin removed; a changed value freezes the system block at the old text and adds a `<system-update>` message; a value is capped at 256 KiB; a `session.created` subscription misses the first session after a service start, so the `prompt` hook is the trigger. The composed bootstrap is about 9.2 KB.
|
|
213
|
+
- **OC2-CTX** — Local probe, OpenCode 2.2.0, 2026-10-27. Per-kind hooks `prompt`, `title`, `context`, `compaction` and `generate`; pushing to `event.system` in a hook reaches the model once per request. Not used for the bootstrap. The `context` hook is used for skill output restoration, which CI job `Host Contract v2 shard N/4` (OpenCode 2.2.0), `tests/integration/opencode-v2.test.ts` › "a skill above the host output limit reaches the model in full on the continuation request and later turns" covers.
|
|
214
|
+
- **OC2-PERM** — CI job `Host Contract v2 shard N/4` (OpenCode 2.2.0): `tests/integration/opencode-v2.test.ts` › "an agent with a managed skills list is refused a skill outside it, and an unmanaged agent is not" and "systematic_skill refuses a skill a managed agent may not load while a sibling agent loads it"; `tests/unit/opencode-v2-permissions.test.ts` (the v1 golden corpus replayed through the translator, including the integer-like skill names that v1 hoists and v2 keeps in order). Local probe, OpenCode 2.2.0, 2026-10-27: last match wins, `*` and `?` match whole values, `deny *` then one allow per skill works, any deny blocks a compound shell command, and the action names are `shell` and `subagent`. The tool asserts the bare skill id, so a rule written for `systematic:<id>` (the v1 spelling) is translated to the bare id; CI: `tests/integration/opencode-v2.test.ts` › "a skill deny written with the systematic: prefix refuses the skill, as it does on v1".
|
|
215
|
+
- **OC2-SKILL** — CI job `Host Contract v2 shard N/4` (OpenCode 2.2.0): `tests/integration/opencode-v2.test.ts` › "the native skill tool sees the registered bundled skills, and not a disabled one" and "an on-disk skill with the same id replaces the registered one in the native tool, with no diagnostic". Local probe, OpenCode 2.2.0, 2026-10-27: the native tool refuses denied skills per agent, including in subagents; `<available_skills>` lists only the skills the agent may load; the permission resource is the skill id; an inline skill's base directory is `dirname(path)`; the tool takes only `{id}`, so `$ARGUMENTS` stays literal.
|
|
216
|
+
- **OC2-TOOL** — CI job `Host Contract v2 shard N/4` (OpenCode 2.2.0): `tests/integration/opencode-v2.test.ts` › "systematic_skill is offered to the model and loads an enabled skill by bare and prefixed name", "arguments are substituted into the skill the model receives" and "a skill in disabled_skills is refused by systematic_skill". Local probe, OpenCode 2.2.0, 2026-10-27: a plugin tool takes a JSON Schema input; the default registration is reachable only through Code Mode, and `options: {codemode: false}` makes it a direct tool (`pinned: true` did not).
|
|
217
|
+
- **OC2-TRUNC** — CI job `Host Contract v2 shard N/4` (OpenCode 2.2.0): `tests/integration/opencode-v2.test.ts` › "a skill above the host output limit reaches the model in full on the continuation request and later turns" and "a discovered project skill above the host output limit reaches the model whole as a command, with its arguments". Local probe, OpenCode 2.2.0, 2026-10-27: tool output over 2000 lines or 51200 bytes is cut after the plugin's `execute.after` hook has seen the full text, with a trailing `[showing lines a-b of N; full output saved to <path>]` part; the bundled `ce-review`, `ce-plan` and `ce-compound-refresh` skills are over the limit. Restoration matches the tool result by call id and does not read the marker. v2 has no runtime prune placeholder: `[Old tool result content cleared]` exists only in the v1-to-v2 migration converter, so v1's compacted-result restore has no v2 counterpart.
|
|
218
|
+
- **OC2-CMD** — CI job `Host Contract v2 shard N/4` (OpenCode 2.2.0): `tests/integration/opencode-v2.test.ts` › "a command with $ARGUMENTS reaches the model expanded, on the invoking session as it is", "a command that declares agent is refused with a message and nothing is prompted" (and the same for `model` and `subtask`), "a !-backtick block in a command stays literal text in the prompt", "the command names and descriptions match the v1 set" and "a discovered skill named like a built-in command is skipped and the built-in stays". Local probe, OpenCode 2.2.0, 2026-10-27: a plugin command receives `{sessionID, prompt: {text, files, agents, skills}, delivery}` with the raw typed text; `prompt` takes no agent or model; `switchAgent` to an unregistered agent succeeds and the next turn fails; a plugin command named like a built-in replaces it; the command editor has only `add`; a throwing `execute` makes `session.command` reject with `CommandExecutionError` and leaves the plugin loaded. A session created with no agent or model reports neither from `session.get`, even after a turn; it runs on the host's default agent (`build` here) and the model `model.default` returns. `switchAgent` and `switchModel` make a session's choice explicit and persistent, and no call clears it; the host also reads a session's agent and model for every model request, so a switch made during a running turn changes that turn's later requests. Because of those three facts a plugin command cannot route without leaving the user's session changed or racing a running turn, so Systematic does not route: a command whose plan declares `agent`, `model` or `subtask` is refused with a message that points to an OpenCode command in Markdown or JSON. Only bundled skills can declare those fields (discovered skills drop them on both hosts), and no bundled skill does.
|
|
219
|
+
- **OC2-ORDER** — CI job `Host Contract v2 shard N/4` (OpenCode 2.2.0): `tests/integration/opencode-v2.test.ts` › "a user agent with the same id in config keeps the user system prompt" and "an on-disk skill with the same id replaces the registered one in the native tool, with no diagnostic" (user config and disk sources win over plugin transforms); `tests/unit/opencode-v2.test.ts` › "agents installer" › "replaying the transform on a fresh editor yields the same single agent set" (replay on a fresh editor). Local probe, OpenCode 2.2.0, 2026-10-27: plugins apply in config order and see earlier plugins' edits; `reload()` replays transforms and does not re-run `setup`.
|
|
220
|
+
- **OC2-ERR** — CI job `Host Contract v2 shard N/4` (OpenCode 2.2.0): `tests/integration/opencode-v2.test.ts` › "invalid systematic.json fails the plugin load, is logged, and the session still answers" and "a command that declares %s is refused with a message and nothing is prompted" (a `systematic:` diagnostic reaches the server's standard error); `tests/unit/opencode-v2.test.ts` › "createSafeGuard". Local probe, OpenCode 2.2.0, 2026-10-27: a rejected `setup` leaves the plugin unloaded with one `WARN failed to load plugin` and the host and other plugins unaffected; a throwing transform disables the whole plugin; a throwing `prompt` hook returns HTTP 500; a throwing `context` hook fails the turn; a throwing `execute.before` or `execute.after` turns the tool result into an error; `console.error` reaches only the server's standard error.
|
|
221
|
+
- **OC2-TRUST** — CI job `Host Contract v2 shard N/4` (OpenCode 2.2.0): `tests/integration/opencode-v2.test.ts` › "the packed plugin loads, setup runs once and stderr carries nothing unexpected" and every test that writes a project `.opencode/systematic.json`, such as "a skill in disabled_skills is refused by systematic_skill". Local probe, OpenCode 2.2.0, 2026-10-27: `ctx.location.directory` is the project directory and `ctx.location.project` has `id`, `directory` and `canonical`; one shared service creates one plugin instance per location, with a fresh module instance and its own `setup`; project config plugins load with no trust prompt.
|
|
222
|
+
- **OC2-TODO** — Binary strings only: no live request showed the tool, and no CI test covers it. Local probe, OpenCode 2.2.0, 2026-10-27, reading strings in the 2.2.0 CLI binary: a `todowrite` tool with input `todos: [{content, status}]` (`status` is `pending`, `in_progress`, `completed` or `cancelled`) and an experimental config option `todo` described as "Enable the experimental todowrite tool. Defaults to false". The tool list of the probe requests had no todo tool, so whether the tool appears with the option on was not observed. The v2 profile therefore marks task tracking conditional.
|
|
183
223
|
- **PI-P** — [Pi profile](skills/using-systematic/references/pi-profile.md#L3-L8).
|
|
184
224
|
- **PI-1** — `src/lib/pi-delegate-tool.ts:14-18,245-249,279-291`.
|
|
185
225
|
- **PI-2** — [Pi profile](skills/using-systematic/references/pi-profile.md#L5-L8).
|
|
186
226
|
- **PI-3** — `src/pi.ts:217-263`.
|
|
187
227
|
- **PI-4** — `package.json:17-23`; `tests/unit/package-exports.test.ts:64-84,268-288`.
|
|
188
228
|
- **PI-5** — `tests/integration/pi.test.ts:349-388`; installed Pi source `node_modules/@earendil-works/pi-coding-agent/dist/config.js:396-398`.
|
|
189
|
-
- **PI-6** — `src/pi.ts:181-186` (merged `disabled_skills` passed to the skill resolver); `src/pi.ts:242-251` (`systematic_delegate` catalog filtered with `isAgentDisabled`); `src/lib/config.ts:2103-2115` (`isAgentDisabled`); `src/lib/pi-subagents-export.ts:857-893` (`generateEntries` applies it to the export); `tests/unit/disable-parity.test.ts` (parity with OpenCode's config handler); OpenCode's contrasting permission gate at `src/lib/skill-tool.ts:
|
|
229
|
+
- **PI-6** — `src/pi.ts:181-186` (merged `disabled_skills` passed to the skill resolver); `src/pi.ts:242-251` (`systematic_delegate` catalog filtered with `isAgentDisabled`); `src/lib/config.ts:2103-2115` (`isAgentDisabled`); `src/lib/pi-subagents-export.ts:857-893` (`generateEntries` applies it to the export); `tests/unit/disable-parity.test.ts` (parity with OpenCode's config handler); OpenCode's contrasting permission gate at `src/lib/skill-tool.ts:198-203`.
|
|
190
230
|
- **PI-7** — `package.json:24-28` (the `pi.subagents.agents` declaration); `scripts/build-pi-package-agents.ts` (writes `dist/pi-subagents/agents/` at build time); `tests/unit/package-exports.test.ts:76-83,289-344` (manifest key, `pi-package` keyword, packed files byte-equal to the fixtures); `tests/integration/pi.test.ts:1550-1652` (real Pi host: dispatch from the package at project and global scope, the `packageAgents: false` fallback to `general-purpose`, and a local file outranking the packaged one); `node_modules/@tintinweb/pi-subagents/dist/package-resources.js:90,327-341,432` (which packages are read, trust), `node_modules/@tintinweb/pi-subagents/dist/custom-agents.js:36-39,59-64` (precedence), `node_modules/@tintinweb/pi-subagents/dist/settings.js:133-135` (`packageAgents` gate), `node_modules/@tintinweb/pi-subagents/dist/index.js:361,1187` (registry setter and background default), `node_modules/@tintinweb/pi-subagents/dist/agent-types.js:65` (`registerAgents`); `src/lib/pi-subagents-export.ts` (export lifecycle, manifest, rollback, stale-file removal and retention); `src/lib/pi-subagents-personas.ts` (curated persona list, compatibility screening); `src/cli.ts:1080-1106` (CLI surface: `pi-subagents preview|export|refresh|cleanup`). Tested interop contract: pi-subagents 0.22.0 on Pi 1.3.0.
|
|
191
|
-
- **PI-8** — `src/pi.ts:188-203` (rule supplied, `piConfig.disabled_skills` the only config passed); `src/lib/bootstrap.ts:
|
|
231
|
+
- **PI-8** — `src/pi.ts:188-203` (rule supplied, `piConfig.disabled_skills` the only config passed); `src/lib/bootstrap.ts:172-198` (`computeBootstrapContentSafe` keeps `bootstrap.enabled` and `bootstrap.file` at their defaults); `tests/unit/pi.test.ts:1317-1447` (real extension init: default, `git-worktree` disabled, `bootstrap.file` set, `bootstrap.enabled: false`, foreign prompt text kept and not doubled).
|
|
192
232
|
- **CC-P** — [Claude Code profile](skills/using-systematic/references/claude-code-profile.md#L5-L10).
|
|
193
233
|
- **CC-1** — [Claude Code skills](https://code.claude.com/docs/en/skills) (`context: fork`); name-based subagent dispatch verified via `claude-code/agents/` and the plugin's invocation convention [CC-9].
|
|
194
234
|
- **CC-2** — [Claude Code tools reference](https://code.claude.com/docs/en/tools-reference).
|
package/README.md
CHANGED
|
@@ -35,13 +35,19 @@ The workflow runs on three harnesses from one source: [OpenCode](https://opencod
|
|
|
35
35
|
|
|
36
36
|
## Quick Install
|
|
37
37
|
|
|
38
|
-
**OpenCode**:
|
|
38
|
+
**OpenCode**: one npm package runs on both OpenCode lines. OpenCode v1 (1.18.29 or later) reads the `plugin` key:
|
|
39
39
|
|
|
40
40
|
```json
|
|
41
41
|
{ "plugin": ["@fro.bot/systematic@latest"] }
|
|
42
42
|
```
|
|
43
43
|
|
|
44
|
-
|
|
44
|
+
OpenCode v2 (2.2.0 or later) reads the `plugins` key:
|
|
45
|
+
|
|
46
|
+
```json
|
|
47
|
+
{ "plugins": ["@fro.bot/systematic@latest"] }
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
Add the one that matches your OpenCode to `~/.config/opencode/opencode.json` and restart OpenCode. Older OpenCode versions are not supported. `systematic setup --harness opencode` and OCX installs write the v1 `plugin` key only.
|
|
45
51
|
|
|
46
52
|
**Pi**:
|
|
47
53
|
|
package/dist/cli.js
CHANGED
|
@@ -35,7 +35,7 @@ import {
|
|
|
35
35
|
findCommandsInDir,
|
|
36
36
|
findSkillsInDir,
|
|
37
37
|
discoverSkills
|
|
38
|
-
} from "./index-
|
|
38
|
+
} from "./index-608preny.js";
|
|
39
39
|
var __defProp = Object.defineProperty;
|
|
40
40
|
var __returnValue = (v) => v;
|
|
41
41
|
function __exportSetter(name, newValue) {
|
|
@@ -3078,7 +3078,7 @@ function setupOpenCode(cwd, ops) {
|
|
|
3078
3078
|
throw createSetupError(`Invalid OpenCode config in ${targetPath}: root must be an object`);
|
|
3079
3079
|
}
|
|
3080
3080
|
if (Object.hasOwn(parsed, "plugins")) {
|
|
3081
|
-
throw createSetupError(`Invalid OpenCode config in ${targetPath}: \`plugins\` (plural) is
|
|
3081
|
+
throw createSetupError(`Invalid OpenCode config in ${targetPath}: \`plugins\` (plural) is the OpenCode v2 key. Setup writes only the OpenCode v1 \`plugin\` key and left this file unchanged. For OpenCode v2 (2.2.0 or later), add "${SYSTEMATIC_PACKAGE_NAME}" to \`plugins\` by hand`);
|
|
3082
3082
|
}
|
|
3083
3083
|
if (!Object.hasOwn(parsed, "plugin")) {
|
|
3084
3084
|
const edits = modify(rawText, ["plugin"], [SYSTEMATIC_PACKAGE_NAME], {});
|
|
@@ -9497,4 +9497,4 @@ function discoverSkills(options) {
|
|
|
9497
9497
|
return Array.from(byName.values());
|
|
9498
9498
|
}
|
|
9499
9499
|
|
|
9500
|
-
export { parseFrontmatter, parse, parseTree, modify, applyEdits, CONFIG_PROTECTED_FIELD_PATHS, _isoDateTime, _isoDate, _isoTime, _isoDuration, string, ZodISODateTime, ZodISODate, ZodISOTime, ZodISODuration, number, boolean, array, object, union, discriminatedUnion, _enum, literal, AgentOverlaySchema, CategoryOverlaySchema, isRecord, extractString, toSourcedPiSubagentsOverlays, resolveRouting, loadConfig, loadConfigWithSources, isAgentDisabled, collectRoutingTargets, getConfigPaths, isDiscoverableMarkdown, findAgentsInDir, extractAgentFrontmatter, findCommandsInDir, extractCommandFrontmatter, findSkillsInDir, discoverSkills };
|
|
9500
|
+
export { parseFrontmatter, parse, parseTree, modify, applyEdits, CONFIG_PROTECTED_FIELD_PATHS, _isoDateTime, _isoDate, _isoTime, _isoDuration, string, ZodISODateTime, ZodISODate, ZodISOTime, ZodISODuration, number, boolean, array, object, union, discriminatedUnion, _enum, literal, AgentOverlaySchema, CategoryOverlaySchema, isRecord, isPermissionSetting, isAgentMode, extractString, toSourcedPiSubagentsOverlays, resolveRouting, loadConfig, loadConfigWithSources, isAgentDisabled, collectRoutingTargets, getConfigPaths, isDiscoverableMarkdown, findAgentsInDir, extractAgentFrontmatter, findCommandsInDir, extractCommandFrontmatter, findSkillsInDir, discoverSkills };
|
package/dist/index.d.ts
CHANGED
|
@@ -1,3 +1,7 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
1
|
+
interface SystematicPluginEntry {
|
|
2
|
+
readonly id: string;
|
|
3
|
+
setup(ctx: unknown): Promise<void>;
|
|
4
|
+
server(input: unknown): Promise<unknown>;
|
|
5
|
+
}
|
|
6
|
+
declare const entry: SystematicPluginEntry;
|
|
7
|
+
export default entry;
|