@fro.bot/systematic 3.26.1 → 3.26.3

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/ATTRIBUTIONS.md CHANGED
@@ -272,7 +272,7 @@ The following is the full Apache License, Version 2.0 text, reproduced here in c
272
272
  ## vercel-labs/agent-browser — Apache-2.0
273
273
 
274
274
  **Source repository:** [`vercel-labs/agent-browser`](https://github.com/vercel-labs/agent-browser)
275
- **Pinned version:** `v0.39.1` (npm `agent-browser@0.39.1`)
275
+ **Pinned version:** `v0.39.2` (npm `agent-browser@0.39.2`)
276
276
  **License:** Apache-2.0
277
277
  **Copyright:** Copyright 2025 Vercel Inc.
278
278
 
@@ -296,7 +296,7 @@ This is fully automated — no human adaptation pass is required, in contrast to
296
296
 
297
297
  ### Upstream Apache-2.0 license text
298
298
 
299
- The following is the full Apache License, Version 2.0 text from `agent-browser@0.39.1`, reproduced here in compliance with the license's notice requirements:
299
+ The following is the full Apache License, Version 2.0 text from `agent-browser@0.39.2`, reproduced here in compliance with the license's notice requirements:
300
300
 
301
301
  ```
302
302
  Apache License
package/HARNESSES.md CHANGED
@@ -26,14 +26,14 @@ Compatibility is direct: OpenCode consumes the concrete invocation language in t
26
26
 
27
27
  ## Pi — Tier 1 shipped adapter
28
28
 
29
- Pi's profile records degraded or unavailable native capabilities and explicit fallbacks [PI-P]. The adapter registers `systematic_skill` in `src/pi.ts:187-206` and `systematic_delegate` in `src/pi.ts:207-232` [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.
29
+ 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.
30
30
 
31
31
  Optional mature delegation is available via [pi-subagents](https://github.com/tintinweb/pi-subagents). It is outside Systematic's bounded-delegate guarantees and governed by pi-subagents' own configuration. Tested against pi-subagents 0.22.0 on Pi 1.3.0; versions outside the tested range are unsupported but nonfatal. pi-subagents reaches Systematic's personas by two paths:
32
32
 
33
33
  - **Installed package.** The package declares `pi.subagents.agents` at `package.json:24-28`, pointing at `dist/pi-subagents/agents/`. `scripts/build-pi-package-agents.ts` writes that directory at build time from the same render the export uses, so the 29 curated personas it ships are byte-equal to the committed fixtures (`tests/unit/package-exports.test.ts:289-344`) [PI-7]. pi-subagents 0.22 is the first release that reads package-declared agents. It reads them from the packages in Pi's `settings.json` `packages[]`, global and project, and never from `node_modules`, because the only scan is Pi's own configured-package list (`node_modules/@tintinweb/pi-subagents/dist/package-resources.js:327-341`). It sees a project-scope package only after the project is trusted: the trust flag starts `false` (`node_modules/@tintinweb/pi-subagents/dist/package-resources.js:90`), is passed to `SettingsManager.create` when the package list is read (`node_modules/@tintinweb/pi-subagents/dist/package-resources.js:332`), and keys the scan (`node_modules/@tintinweb/pi-subagents/dist/package-resources.js:432`). An installed Systematic therefore exposes `systematic-<name>` types with plain defaults and no export step. `pi -e` does not, because it is not in `packages[]`, and neither does a git install, which has no built `dist/`. `tests/integration/pi.test.ts:1550-1652` pins dispatch from the package at project and global scope, the `packageAgents: false` switch in `subagents.json`, and local precedence [PI-7].
34
34
  - **Export.** `systematic pi-subagents <preview|export|refresh|cleanup> --scope project|global` writes flat files that carry `systematic.json` overlays. Package agents load first, so a local file of the same name outranks the packaged one (`node_modules/@tintinweb/pi-subagents/dist/custom-agents.js:36-39,59-64`). No files are written without an explicit command [PI-7].
35
35
 
36
- Packaged personas are config-blind. The only function that sets pi-subagents' agent registry, `registerAgents` (`node_modules/@tintinweb/pi-subagents/dist/agent-types.js:65`), is called only from its own `dist/index.js:361`, so another extension cannot register or filter agent types. Overlays, `disabled_agents` and `agents.<name>.disable` therefore cannot reach a packaged file. `src/pi.ts:143-155` warns once at startup when either is configured. pi-subagents' own `/agents → Disable` turns off one packaged persona, and `packageAgents: false` in `subagents.json` turns off all of them (`node_modules/@tintinweb/pi-subagents/dist/settings.js:133-135`). A top-level `Agent` call runs in the background unless it passes `run_in_background: false` (`node_modules/@tintinweb/pi-subagents/dist/index.js:1187`).
36
+ Packaged personas are config-blind. The only function that sets pi-subagents' agent registry, `registerAgents` (`node_modules/@tintinweb/pi-subagents/dist/agent-types.js:65`), is called only from its own `dist/index.js:361`, so another extension cannot register or filter agent types. Overlays, `disabled_agents` and `agents.<name>.disable` therefore cannot reach a packaged file. `src/pi.ts:165-179` warns once at startup when either is configured. pi-subagents' own `/agents → Disable` turns off one packaged persona, and `packageAgents: false` in `subagents.json` turns off all of them (`node_modules/@tintinweb/pi-subagents/dist/settings.js:133-135`). A top-level `Agent` call runs in the background unless it passes `run_in_background: false` (`node_modules/@tintinweb/pi-subagents/dist/index.js:1187`).
37
37
 
38
38
  Export writes are governed by a manifest (`.systematic-personas.json`) and an exclusive per-root mutation lock (`.systematic-personas.lock`) held for the duration of `export`/`refresh`/`cleanup`; a pre-existing lock is never auto-deleted — a reported lock requires manual verification that no operation is actually running before removal. The export honors the same disable settings as the rest of Systematic: a persona disabled by `disabled_agents` (bare name or `category/name`) or by an `agents.<name>.disable` overlay is not exported [PI-6].
39
39
 
@@ -43,7 +43,7 @@ Every export/refresh/cleanup operation walks every path component from a scope-a
43
43
 
44
44
  The package manifest exposes the extension and skills at `package.json:17-23` (and the packaged personas at `package.json:24-28`), with tests verifying both manifest entries and their packaged paths `tests/unit/package-exports.test.ts:64-84,268-288` [PI-4]. Pi's RPC/JSONL test fixture isolates its environment (`tests/integration/pi.test.ts:349-388`), and the installed runtime exposes environment-specific agent/session directories `node_modules/@earendil-works/pi-coding-agent/dist/config.js:396-398` [PI-5].
45
45
 
46
- Pi honors Systematic's disable settings. `src/pi.ts` loads the merged config once at extension start and passes `disabled_skills` to the skill resolver, so a disabled skill is absent from the `systematic_skill` description and parameter hint and fails to load as unknown. It filters the `systematic_delegate` catalog with `isAgentDisabled`, so a persona disabled by `disabled_agents` (bare name or `category/name`) or by an `agents.<name>.disable` overlay disappears from the tool's description, hint and lookup. The pi-subagents export applies the same predicate, and `tests/unit/disable-parity.test.ts` pins it to what OpenCode's config handler omits [PI-6]. Settings are read at extension start, so a Pi restart applies a change. Pi's `systematic_skill` takes a single `name` parameter and no arguments (`src/pi.ts:215-219`) [PI-3], so a skill that needs arguments, such as `mode:embed` and image paths for `pr-attachments`, reads them from the invoking instruction text instead; OpenCode and Claude Code can also pass skill arguments. Pi's own skill discovery is a separate path: `pi.skills` ships the whole `./skills` directory and Pi's `/skill:name` commands, so those still list and load disabled skills [PI-4], [PI-5]. Pi's skill loading also has no OpenCode-style permission gate — OpenCode's `skill-tool.ts` calls `context.ask({ permission: 'skill', ... })` before returning skill content, but Pi 0.80.6's extension API has no equivalent hook and Systematic's Pi tool implementation does not call one [PI-6]. Those are deliberate honesty boundaries, not implied parity.
46
+ Pi honors Systematic's disable settings. `src/pi.ts` loads the merged config once at extension start and passes `disabled_skills` to the skill resolver, so a disabled skill is absent from the `systematic_skill` description and parameter hint and fails to load as unknown. The same list reaches Pi's bootstrap, which drops the worktree placement rule when `git-worktree` is disabled; nothing else from the config reaches the bootstrap, so Pi still ignores `bootstrap.enabled` and `bootstrap.file` and carries the rule even when `bootstrap.file` is set [PI-8]. It filters the `systematic_delegate` catalog with `isAgentDisabled`, so a persona disabled by `disabled_agents` (bare name or `category/name`) or by an `agents.<name>.disable` overlay disappears from the tool's description, hint and lookup. The pi-subagents export applies the same predicate, and `tests/unit/disable-parity.test.ts` pins it to what OpenCode's config handler omits [PI-6]. Settings are read at extension start, so a Pi restart applies a change. Pi's `systematic_skill` takes a single `name` parameter and no arguments (`src/pi.ts:222-226`) [PI-3], so a skill that needs arguments, such as `mode:embed` and image paths for `pr-attachments`, reads them from the invoking instruction text instead; OpenCode and Claude Code can also pass skill arguments. Pi's own skill discovery is a separate path: `pi.skills` ships the whole `./skills` directory and Pi's `/skill:name` commands, so those still list and load disabled skills [PI-4], [PI-5]. Pi's skill loading also has no OpenCode-style permission gate — OpenCode's `skill-tool.ts` calls `context.ask({ permission: 'skill', ... })` before returning skill content, but Pi 0.80.6's extension API has no equivalent hook and Systematic's Pi tool implementation does not call one [PI-6]. Those are deliberate honesty boundaries, not implied parity.
47
47
 
48
48
  ## Claude Code — Tier 1 shipped adapter
49
49
 
@@ -60,7 +60,17 @@ Behavioral enforcement rides a plugin output style (`force-for-plugin: true`), w
60
60
  | Workflow | Native skills | Skill content and instructions, discovered natively |
61
61
  | Agents | Native subagents | Persona dispatch by name |
62
62
 
63
- Honest capability boundary: output-style enforcement is real and applies automatically on install, but it operates at the system-prompt level — the same layer as any other instruction the model receives — so it is strong guidance, not a hard gate the model cannot violate. Coverage also differs by surface: plugin-bundled hooks fire app-wide, including in Cowork, while a project-local `.claude/settings.json` hook fires in the Code tab but not in Cowork — state or enforcement reaching Cowork sessions has to come through the plugin, not a project-local hook. Integration coverage lives in `tests/integration/claude-code.test.ts` [CC-10].
63
+ Honest capability boundary: output-style enforcement is real and applies automatically on install, but it operates at the system-prompt level — the same layer as any other instruction the model receives — so it is strong guidance, not a hard gate the model cannot violate. Coverage also differs by surface: plugin-bundled hooks fire app-wide, including in Cowork, while a project-local `.claude/settings.json` hook fires in the Code tab but not in Cowork — state or enforcement reaching Cowork sessions has to come through the plugin, not a project-local hook. The output style is also static and the build reads no user config, so it cannot follow `disabled_skills`: it always carries the worktree placement rule, even when `git-worktree` is disabled [CC-13]. Integration coverage lives in `tests/integration/claude-code.test.ts` [CC-10].
64
+
65
+ ## Worktree placement rule — bootstrap paths
66
+
67
+ 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
+
69
+ - **OpenCode.** `src/index.ts` 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].
70
+ - **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
+ - **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
+
73
+ Tests drive the real OpenCode plugin init and the real Pi extension init under an isolated home and the real config loader, and pin the built Claude Code output style byte for byte. The script's behavior is covered by unit tests against real throwaway git repositories, also run under stock macOS `/bin/bash` 3.2 [WT-2]. Together these are package-level evidence: no live OpenCode, Pi or Claude Code session has created a worktree from a build carrying the rule.
64
74
 
65
75
  ## Review synthesis pipeline validator — packaged paths
66
76
 
@@ -167,16 +177,18 @@ Migrated-skill discipline is enforced by the [content-integrity gate](scripts/co
167
177
  - **OC-3** — cloned OpenCode source, `.slim/clonedeps/repos/anomalyco__opencode/packages/core/src/tool/todowrite.ts:1-10`.
168
178
  - **OC-4** — `src/lib/config-handler.ts:467-485`.
169
179
  - **OC-5** — `src/lib/skill-tool.ts:41-101`.
170
- - **OC-6** — `ARCHITECTURE.md:75-85` and `agents/`.
180
+ - **OC-6** — `ARCHITECTURE.md:158-164` and `agents/`.
171
181
  - **OC-7** — `src/lib/config-handler.ts:276-289`.
182
+ - **OC-8** — `src/index.ts:60-70` (the rule is always supplied to `getBootstrapContent` together with the loaded config); `src/lib/bootstrap.ts:142-157` (`readWorktreePlacementRule`), `:241-250` (`bootstrap.enabled` and `bootstrap.file` return before the rule is composed), `:262-266` (the rule is omitted when `disabled_skills` contains `git-worktree`), `:276` (placement after the usage template and before the profile); `tests/unit/bootstrap.test.ts:979-1178` (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:1400-1499` (real plugin init).
172
183
  - **PI-P** — [Pi profile](skills/using-systematic/references/pi-profile.md#L3-L8).
173
184
  - **PI-1** — `src/lib/pi-delegate-tool.ts:14-18,245-249,279-291`.
174
185
  - **PI-2** — [Pi profile](skills/using-systematic/references/pi-profile.md#L5-L8).
175
- - **PI-3** — `src/pi.ts:187-232`.
186
+ - **PI-3** — `src/pi.ts:217-263`.
176
187
  - **PI-4** — `package.json:17-23`; `tests/unit/package-exports.test.ts:64-84,268-288`.
177
188
  - **PI-5** — `tests/integration/pi.test.ts:349-388`; installed Pi source `node_modules/@earendil-works/pi-coding-agent/dist/config.js:396-398`.
178
- - **PI-6** — `src/pi.ts:157-162` (merged `disabled_skills` passed to the skill resolver); `src/pi.ts:208-221` (`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:191-196`.
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:191-196`.
179
190
  - **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:175-195` (`computeBootstrapContentSafe` keeps `bootstrap.enabled` and `bootstrap.file` at their defaults); `tests/unit/pi.test.ts:1314-1444` (real extension init: default, `git-worktree` disabled, `bootstrap.file` set, `bootstrap.enabled: false`, foreign prompt text kept and not doubled).
180
192
  - **CC-P** — [Claude Code profile](skills/using-systematic/references/claude-code-profile.md#L5-L10).
181
193
  - **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].
182
194
  - **CC-2** — [Claude Code tools reference](https://code.claude.com/docs/en/tools-reference).
@@ -184,10 +196,11 @@ Migrated-skill discipline is enforced by the [content-integrity gate](scripts/co
184
196
  - **CC-4** — [Claude Code todo tracking](https://code.claude.com/docs/en/agent-sdk/todo-tracking.md).
185
197
  - **CC-5** — [Claude Code skills](https://code.claude.com/docs/en/skills).
186
198
  - **CC-6** — [Claude Code Agent SDK skills](https://code.claude.com/docs/en/agent-sdk/skills.md).
187
- - **CC-9** — `scripts/build-claude-code-plugin.ts:5-27,253-291,345-379` (builder, identifier translation, integrity gate); `.gitignore` (`claude-code/` gitignored build staging).
199
+ - **CC-9** — `scripts/build-claude-code-plugin.ts:5-28,256-368,374-418` (builder, identifier translation, integrity gate); `.gitignore` (`claude-code/` gitignored build staging).
188
200
  - **CC-10** — `tests/integration/claude-code.test.ts`.
189
201
  - **CC-11** — `.github/workflows/main.yaml:263-338` (`publish-claude-code-plugin` job: builds, guards required artifacts, publishes to the orphan `claude-code-plugin` branch on push to `main`).
190
202
  - **CC-12** — `.claude-plugin/marketplace.json:1-18` (marketplace catalog; `systematic` plugin entry sourced from the `claude-code-plugin` branch ref).
203
+ - **CC-13** — `scripts/build-claude-code-plugin.ts:129-157` (the rule file is read after the using-systematic and profile checks, fails the build when missing, and sits between the body and the profile); `tests/unit/build-claude-code-plugin.test.ts:491-514` and the byte-exact output-style fixture in the same file; `tests/integration/claude-code.test.ts:140-162` (real build: the rule appears exactly once between the body and the profile).
191
204
  - **CX-1** — [Codex request_user_input definition](https://github.com/openai/codex/blob/35aaa5d9/codex-rs/tools/src/request_user_input_tool.rs).
192
205
  - **CX-2** — [Codex request_user_input handler](https://github.com/openai/codex/blob/d47b755a/codex-rs/core/src/tools/handlers/request_user_input.rs).
193
206
  - **GE-1** — [Gemini ask-user documentation](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/ask-user.md).
@@ -205,3 +218,5 @@ Migrated-skill discipline is enforced by the [content-integrity gate](scripts/co
205
218
  - **PA-1** — `tests/unit/pr-attachments-packaging.test.ts` (real Node execution of `skills/pr-attachments/scripts/pr-attachments.mjs` from the npm-packed archive, the OCX-selected tree and the Claude Code generated bundle; nothing under `docs/evidence/` ships).
206
219
  - **PA-2** — `tests/unit/pr-attachments-contract.test.ts` (`skills/pr-attachments/SKILL.md` contract: modes, argument dispatch, `SKILL_DIR` anchor, publishing order, bans).
207
220
  - **PA-3** — `tests/unit/pr-attachments-dry-run.test.ts` (the skill's fenced blocks run offline against a temporary repository and a local bare remote, with the real helper).
221
+ - **WT-1** — `skills/using-systematic/references/worktree-placement.md` (the rule text); `tests/unit/bootstrap.test.ts:1043-1092` (exact text, at most 350 bytes, names `git-worktree` and `.worktrees/<branch>`, keeps the raw-add ban and the carve-out sentence, no harness identifiers, no `CLAUDE.md` literal).
222
+ - **WT-2** — `skills/git-worktree/scripts/worktree-manager.sh` (the script); `tests/unit/git-worktree-manager.test.ts` and `tests/unit/git-worktree-cleanup.test.ts` (placement from the root, a subdirectory and a linked worktree, refused layouts, ignore policy, base resolution, `--no-track`, `list`, `switch`, `copy-env`, `cleanup`; real git in throwaway repositories with a bare `origin`, `TEST_BASH=/bin/bash` runs them under bash 3.2); `tests/unit/git-worktree-skills-contract.test.ts` (the safety and routing terms in `skills/git-worktree/SKILL.md` and the pointers in `ce-review`, `orchestrating-subagents` and `git-clean-gone-branches`). Package probe: the plugin-init, Pi-init and built-output-style tests cited by WT-1, OC-8, PI-8 and CC-13. No live session has run.
@@ -9,29 +9,27 @@ You are an expert institutional knowledge researcher specializing in efficiently
9
9
 
10
10
  ## Search Strategy (Grep-First Filtering)
11
11
 
12
- The `docs/solutions/` directory contains documented solutions with YAML frontmatter. When there may be hundreds of files, use this efficient strategy that minimizes tool calls:
12
+ The `docs/solutions/` directory holds documented solutions with YAML frontmatter. There may be hundreds of files, so use this strategy, which minimizes tool calls. Never assume a layout: discover what exists first.
13
+
14
+ ### Step 0: Discover What Exists
15
+
16
+ List `docs/solutions/` with a directory listing tool.
17
+
18
+ - If `docs/solutions/` does not exist or holds no `.md` files, stop and return the "No Matches" result, saying the project has no solutions directory yet. This is not an error. Read no other path.
19
+ - The subdirectories you find are the categories. Do not assume any particular category exists.
20
+ - Skip `README.md` files and anything under `_archived/` when collecting candidates. Never treat `critical-patterns.md` as a candidate (Step 3b handles it).
13
21
 
14
22
  ### Step 1: Extract Keywords from Feature Description
15
23
 
16
24
  From the feature/task description, identify:
17
- - **Module names**: e.g., "BriefSystem", "EmailProcessing", "payments"
25
+ - **Module names**: the named modules, services or areas the work touches
18
26
  - **Technical terms**: e.g., "N+1", "caching", "authentication"
19
27
  - **Problem indicators**: e.g., "slow", "error", "timeout", "memory"
20
- - **Component types**: e.g., "model", "controller", "job", "api"
28
+ - **Component types**: e.g., "database", "api", "background job", "cli"
21
29
 
22
30
  ### Step 2: Category-Based Narrowing (Optional but Recommended)
23
31
 
24
- If the feature type is clear, narrow the search to relevant category directories:
25
-
26
- | Feature Type | Search Directory |
27
- |--------------|------------------|
28
- | Performance work | `docs/solutions/performance-issues/` |
29
- | Database changes | `docs/solutions/database-issues/` |
30
- | Bug fix | `docs/solutions/runtime-errors/`, `docs/solutions/logic-errors/` |
31
- | Security | `docs/solutions/security-issues/` |
32
- | UI work | `docs/solutions/ui-bugs/` |
33
- | Integration | `docs/solutions/integration-issues/` |
34
- | General/unclear | `docs/solutions/` (all) |
32
+ If the feature type is clear, narrow the search to the category directories from Step 0 whose names fit it. Match by name. For example, performance work fits a directory with `performance` in its name, and a security change fits one with `security` in its name. Several directories can fit. When the type is unclear, or no directory fits, search `docs/solutions/` as a whole.
35
33
 
36
34
  ### Step 3: Content-Search Pre-Filter (Critical for Efficiency)
37
35
 
@@ -39,42 +37,72 @@ If the feature type is clear, narrow the search to relevant category directories
39
37
 
40
38
  ```
41
39
  # Search for keyword matches in frontmatter fields (run in PARALLEL, case-insensitive)
42
- content-search: pattern="title:.*email" path=docs/solutions/ files_only=true case_insensitive=true
43
- content-search: pattern="tags:.*(email|mail|smtp)" path=docs/solutions/ files_only=true case_insensitive=true
44
- content-search: pattern="module:.*(Brief|Email)" path=docs/solutions/ files_only=true case_insensitive=true
40
+ content-search: pattern="title:.*cache" path=docs/solutions/ files_only=true case_insensitive=true
41
+ content-search: pattern="tags:.*(cache|caching|ttl)" path=docs/solutions/ files_only=true case_insensitive=true
42
+ content-search: pattern="module:.*(Checkout|Orders)" path=docs/solutions/ files_only=true case_insensitive=true
45
43
  content-search: pattern="component:.*background_job" path=docs/solutions/ files_only=true case_insensitive=true
46
44
  ```
47
45
 
48
46
  **Pattern construction tips:**
49
- - Use `|` for synonyms: `tags:.*(payment|billing|stripe|subscription)`
47
+ - Use `|` for synonyms: `tags:.*(auth|login|session|token)`
50
48
  - Include `title:` - often the most descriptive field
51
49
  - Search case-insensitively
52
50
  - Include related terms the user might not have mentioned
51
+ - To learn which `module`, `component` or `tags` values the project actually uses, search for the field name (`^module:`) and read the values the matches show. Do not guess values from memory.
53
52
 
54
53
  **Why this works:** Content search scans file contents without reading into context. Only matching filenames are returned, dramatically reducing the set of files to examine.
55
54
 
56
- **Combine results** from all searches to get candidate files (typically 5-20 files instead of 200).
55
+ **Combine results** from all searches to get candidate files (typically 5-20 files instead of 200). Drop the files Step 0 says to skip.
57
56
 
58
57
  **If search returns >25 candidates:** Re-run with more specific patterns or combine with category narrowing.
59
58
 
60
59
  **If search returns <3 candidates:** Do a broader content search (not just frontmatter fields) as fallback:
61
60
  ```
62
- content-search: pattern="email" path=docs/solutions/ files_only=true case_insensitive=true
61
+ content-search: pattern="cache" path=docs/solutions/ files_only=true case_insensitive=true
63
62
  ```
64
63
 
65
- ### Step 3b: Always Check Critical Patterns
64
+ ### Step 3b: Check Critical Patterns (Only If the File Exists)
66
65
 
67
- **Regardless of Grep results**, always read the critical patterns file:
66
+ If the Step 0 listing shows a `patterns/` directory, list it. If `critical-patterns.md` is there, read it and scan for patterns relevant to the current task. Most projects have neither. If the directory or the file is absent, skip this step without reading a missing path and without reporting an error.
68
67
 
69
- ```bash
70
- Read: docs/solutions/patterns/critical-patterns.md
68
+ ### Step 4: Read Lifecycle Fields and Resolve
69
+
70
+ Run ONE content search across all of `docs/solutions/` to find which files mention the lifecycle fields, returning file paths only:
71
+
72
+ ```
73
+ content-search: pattern="^(status|superseded_by|stale_reason):" path=docs/solutions/ files_only=true case_insensitive=false
71
74
  ```
72
75
 
73
- This file contains must-know patterns that apply across all work - high-severity issues promoted to required reading. Scan for patterns relevant to the current feature/task.
76
+ Use the search only to learn which files to read. Do not take values from the matched lines: a raw line can keep a trailing comment, can be a folded scalar, and can sit in a doc body (for example in a fenced example) instead of the frontmatter. A file that does not match has no lifecycle fields, so it has no status.
74
77
 
75
- ### Step 4: Read Frontmatter of Candidates Only
78
+ Before routing any candidate, and at every successor hop, read that doc's frontmatter (the block between the opening and closing `---`, with limit:30 as in Step 5, reading on if the closing `---` is not in view). Take `status`, `superseded_by` and `stale_reason` from that frontmatter, parsed as YAML. `status: superseded # retired` is `superseded`. Ignore any match outside the frontmatter block.
76
79
 
77
- For each candidate file from Step 3, read the frontmatter:
80
+ Then resolve every candidate before scoring:
81
+
82
+ | Candidate `status` | Result |
83
+ |--------------------|--------|
84
+ | Missing, `active`, or any value you do not recognize | Active. Treat as a normal candidate. |
85
+ | `stale` | Keep it, and give it a `Caution:` line (see Output Format). |
86
+ | `superseded` | Replace it with its successor, if the successor resolves. Otherwise omit it and report the skip. |
87
+
88
+ **Resolving a successor.** Only a repo-root path counts: a value that starts with `docs/solutions/`, ends in `.md`, contains no `..` segment, is not a `README.md`, is not under `_archived/`, and names a file that exists. A bare filename, a relative path, an empty value, a list, a missing file and any other form are all unresolvable. Do not guess.
89
+
90
+ 1. Start with the candidate's `superseded_by` value. Keep a visited set holding the candidate's own path.
91
+ 2. At every hop, before taking the target as the successor, check that it passes the form rule above and that the file exists. Check existence against the Step 0 listing or Glob results you already have, or with a direct existence check. A target that fails either check makes the chain unresolvable. A target that did not match the search is not evidence that it exists, because most active docs have no `status` line.
92
+ 3. If the target is already in the visited set, the chain is a cycle: unresolvable.
93
+ 4. Read the target's frontmatter and take its `status`. If it is `superseded`, follow its `superseded_by` and repeat from step 2.
94
+ 5. One hop is one `superseded_by` link. Follow at most 5 hops. A target still superseded after the fifth hop makes the chain unresolvable.
95
+ 6. The first target that is not `superseded` is the successor. An unrecognized status counts as active. If reading the target's frontmatter fails, the chain is unresolvable.
96
+
97
+ **Then apply the result.**
98
+ - A superseded candidate with a resolvable successor is never returned. Return the successor in its place, labelled with a `Supersedes:` line (see Output Format). The successor does not need to match the keywords itself, because it stands in for a doc that did.
99
+ - If the successor is `stale`, it also gets a `Caution:` line.
100
+ - Several superseded docs that resolve to the same successor return that successor once. Its `Supersedes:` line lists all of them. If the successor is also a candidate in its own right, merge the two into one entry.
101
+ - A superseded candidate with an unresolvable successor is omitted. Add a line `Skipped: superseded, successor unresolved: <path>` for it to the search results.
102
+
103
+ ### Step 5: Read Frontmatter of Candidates Only
104
+
105
+ For each remaining candidate (including successors), read the frontmatter:
78
106
 
79
107
  ```bash
80
108
  # Read frontmatter only (limit to first 30 lines)
@@ -83,14 +111,16 @@ Read: [file_path] with limit:30
83
111
 
84
112
  Extract these fields from the YAML frontmatter:
85
113
  - **module**: Which module/system the solution applies to
86
- - **problem_type**: Category of issue (see schema below)
114
+ - **problem_type**: Category of issue
87
115
  - **component**: Technical component affected
88
116
  - **symptoms**: Array of observable symptoms
89
117
  - **root_cause**: What caused the issue
90
118
  - **tags**: Searchable keywords
91
119
  - **severity**: critical, high, medium, low
92
120
 
93
- ### Step 5: Score and Rank Relevance
121
+ `status`, `superseded_by` and `stale_reason` come from the Step 4 frontmatter read, not from search lines. Values for these fields are whatever the docs use. Do not validate them against a fixed list.
122
+
123
+ ### Step 6: Score and Rank Relevance
94
124
 
95
125
  Match frontmatter fields against the feature/task description:
96
126
 
@@ -101,7 +131,7 @@ Match frontmatter fields against the feature/task description:
101
131
  - `component` matches the technical area being touched
102
132
 
103
133
  **Moderate matches (include):**
104
- - `problem_type` is relevant (e.g., `performance_issue` for optimization work)
134
+ - `problem_type` is relevant (e.g., a performance problem type for optimization work)
105
135
  - `root_cause` suggests a pattern that might apply
106
136
  - Related modules or components mentioned
107
137
 
@@ -109,7 +139,7 @@ Match frontmatter fields against the feature/task description:
109
139
  - No overlapping tags, symptoms, or modules
110
140
  - Unrelated problem types
111
141
 
112
- ### Step 6: Full Read of Relevant Files
142
+ ### Step 7: Full Read of Relevant Files
113
143
 
114
144
  Only for files that pass the filter (strong or moderate matches), read the complete document to extract:
115
145
  - The full problem description
@@ -117,9 +147,9 @@ Only for files that pass the filter (strong or moderate matches), read the compl
117
147
  - Prevention guidance
118
148
  - Code examples
119
149
 
120
- ### Step 7: Return Distilled Summaries
150
+ ### Step 8: Return Distilled Summaries
121
151
 
122
- For each relevant document, return a summary in this format:
152
+ For each relevant document, return a summary in this format. `Supersedes:` and `Caution:` are optional; include each only when it applies. `Supersedes:` lists each retired doc as a repo-root path, comma-separated. `Caution:` says the doc is marked stale and quotes its `stale_reason` from its frontmatter if it has one.
123
153
 
124
154
  ```markdown
125
155
  ### [Title from document]
@@ -129,49 +159,10 @@ For each relevant document, return a summary in this format:
129
159
  - **Relevance**: [Brief explanation of why this is relevant to the current task]
130
160
  - **Key Insight**: [The most important takeaway - the thing that prevents repeating the mistake]
131
161
  - **Severity**: [severity level]
162
+ Supersedes: <path>[, <path>]
163
+ Caution: <text>
132
164
  ```
133
165
 
134
- ## Frontmatter Schema Reference
135
-
136
- Use this on-demand schema reference when you need the full contract:
137
- `../../skills/ce-compound/references/yaml-schema.md`
138
-
139
- Key enum values:
140
-
141
- **problem_type values:**
142
- - build_error, test_failure, runtime_error, performance_issue
143
- - database_issue, security_issue, ui_bug, integration_issue
144
- - logic_error, developer_experience, workflow_issue
145
- - best_practice, documentation_gap
146
-
147
- **component values:**
148
- - rails_model, rails_controller, rails_view, service_object
149
- - background_job, database, frontend_stimulus, hotwire_turbo
150
- - email_processing, brief_system, assistant, authentication
151
- - payments, development_workflow, testing_framework, documentation, tooling
152
-
153
- **root_cause values:**
154
- - missing_association, missing_include, missing_index, wrong_api
155
- - scope_issue, thread_violation, async_timing, memory_leak
156
- - config_error, logic_error, test_isolation, missing_validation
157
- - missing_permission, missing_workflow_step, inadequate_documentation
158
- - missing_tooling, incomplete_setup
159
-
160
- **Category directories (mapped from problem_type):**
161
- - `docs/solutions/build-errors/`
162
- - `docs/solutions/test-failures/`
163
- - `docs/solutions/runtime-errors/`
164
- - `docs/solutions/performance-issues/`
165
- - `docs/solutions/database-issues/`
166
- - `docs/solutions/security-issues/`
167
- - `docs/solutions/ui-bugs/`
168
- - `docs/solutions/integration-issues/`
169
- - `docs/solutions/logic-errors/`
170
- - `docs/solutions/developer-experience/`
171
- - `docs/solutions/workflow-issues/`
172
- - `docs/solutions/best-practices/`
173
- - `docs/solutions/documentation-gaps/`
174
-
175
166
  ## Output Format
176
167
 
177
168
  Structure your findings as:
@@ -184,9 +175,10 @@ Structure your findings as:
184
175
  - **Keywords Used**: [tags, modules, symptoms searched]
185
176
  - **Files Scanned**: [X total files]
186
177
  - **Relevant Matches**: [Y files]
178
+ Skipped: superseded, successor unresolved: <path> <- one line per such doc; omit when none
187
179
 
188
- ### Critical Patterns (Always Check)
189
- [Any matching patterns from critical-patterns.md]
180
+ ### Critical Patterns
181
+ [Matching patterns from critical-patterns.md. Include this section only when that file exists.]
190
182
 
191
183
  ### Relevant Learnings
192
184
 
@@ -195,6 +187,8 @@ Structure your findings as:
195
187
  - **Module**: [module]
196
188
  - **Relevance**: [why this matters for current task]
197
189
  - **Key Insight**: [the gotcha or pattern to apply]
190
+ Supersedes: <path>[, <path>]
191
+ Caution: <text>
198
192
 
199
193
  #### 2. [Title]
200
194
  ...
@@ -205,21 +199,23 @@ Structure your findings as:
205
199
  - [Gotchas to avoid]
206
200
 
207
201
  ### No Matches
208
- [If no relevant learnings found, explicitly state this]
202
+ [If no relevant learnings found, explicitly state this. Say so when docs/solutions/ does not exist.]
209
203
  ```
210
204
 
211
205
  ## Efficiency Guidelines
212
206
 
213
207
  **DO:**
208
+ - List `docs/solutions/` first and work from the directories that exist
214
209
  - Use the native content-search tool to pre-filter files BEFORE reading any content (critical for 100+ files)
215
210
  - Run multiple content searches in PARALLEL for different keywords
216
211
  - Include `title:` in search patterns - often the most descriptive field
217
- - Use OR patterns for synonyms: `tags:.*(payment|billing|stripe)`
212
+ - Use OR patterns for synonyms: `tags:.*(auth|login|session)`
218
213
  - Use `-i=true` for case-insensitive matching
219
214
  - Use category directories to narrow scope when feature type is clear
220
215
  - Do a broader content search as fallback if <3 candidates found
221
216
  - Re-narrow with more specific patterns if >25 candidates found
222
- - Always read the critical patterns file (Step 3b)
217
+ - Use one search to find which files mention the lifecycle fields, read each such doc's frontmatter for the values, and resolve superseded docs before scoring
218
+ - Read the critical patterns file only when it exists
223
219
  - Only read frontmatter of search-matched candidates (not all files)
224
220
  - Filter aggressively - only fully read truly relevant files
225
221
  - Prioritize high-severity and critical patterns
@@ -227,6 +223,7 @@ Structure your findings as:
227
223
  - Note when no relevant learnings exist (this is valuable information too)
228
224
 
229
225
  **DON'T:**
226
+ - Read a path that may not exist (a category directory, `critical-patterns.md`, a successor) without checking that it exists
230
227
  - Read frontmatter of ALL files (use content-search to pre-filter first)
231
228
  - Run searches sequentially when they can be parallel
232
229
  - Use only exact keyword matches (include synonyms)
@@ -234,13 +231,18 @@ Structure your findings as:
234
231
  - Proceed with >25 candidates without narrowing first
235
232
  - Read every file in full (wasteful)
236
233
  - Return raw document contents (distill instead)
234
+ - Return a superseded doc. Return its successor, or skip it.
235
+ - Follow a `superseded_by` that is not a repo-root `docs/solutions/` path, and never follow more than 5 hops
237
236
  - Include tangentially related learnings (focus on relevance)
238
- - Skip the critical patterns file (always check it)
239
237
 
240
238
  ## Integration Points
241
239
 
242
240
  This agent is designed to be invoked by:
243
241
  - `/ce:plan` - To inform planning with institutional knowledge and add depth during confidence checking
242
+ - `/ce:review` - To flag known patterns in the diff under review
243
+ - `/ce:ideate` - To ground ideas in documented past solutions
244
+ - `/ce:compound` - As the Related Docs Finder when a new learning is written
245
+ - `/deepen-plan` - To strengthen plans with documented prior art
244
246
  - Manual invocation before starting work on a feature
245
247
 
246
248
  The goal is to surface relevant learnings in under 30 seconds for a typical solutions directory, enabling fast knowledge retrieval during planning phases.
package/dist/index.js CHANGED
@@ -91,6 +91,15 @@ function readHarnessProfile(bundledSkillsDir, name) {
91
91
  return null;
92
92
  }
93
93
  }
94
+ function readWorktreePlacementRule(bundledSkillsDir) {
95
+ const rulePath = path.join(bundledSkillsDir, "using-systematic/references/worktree-placement.md");
96
+ try {
97
+ return fs.readFileSync(rulePath, "utf8").trim();
98
+ } catch (error) {
99
+ console.error(`Failed to read worktree placement rule ${rulePath}: ${error instanceof Error ? error.message : String(error)}`);
100
+ return null;
101
+ }
102
+ }
94
103
  function getSkillUsageTemplate() {
95
104
  return `**Skills naming:**
96
105
  - Systematic bundled skills use the \`systematic:\` prefix (e.g., \`systematic:onboarding\`)
@@ -105,7 +114,12 @@ function getSkillUsageTemplate() {
105
114
  Bundled skills ship with the Systematic plugin and are discoverable via \`systematic_skill\`.`;
106
115
  }
107
116
  function getBootstrapContent(config, deps) {
108
- const { bundledSkillsDir, usageTemplate, profileBlock } = deps;
117
+ const {
118
+ bundledSkillsDir,
119
+ usageTemplate,
120
+ worktreePlacementRule,
121
+ profileBlock
122
+ } = deps;
109
123
  if (!config.bootstrap.enabled)
110
124
  return null;
111
125
  if (config.bootstrap.file) {
@@ -121,6 +135,9 @@ function getBootstrapContent(config, deps) {
121
135
  const { body } = parseFrontmatter(fullContent);
122
136
  const content = body.trim();
123
137
  const skillUsage = usageTemplate ?? getSkillUsageTemplate();
138
+ const ruleSection = worktreePlacementRule === undefined || config.disabled_skills.includes("git-worktree") ? "" : `
139
+
140
+ ${worktreePlacementRule}`;
124
141
  const profileSection = profileBlock === undefined ? "" : `
125
142
 
126
143
  ${profileBlock}`;
@@ -131,7 +148,7 @@ You have access to structured engineering workflows via the Systematic plugin.
131
148
 
132
149
  ${content}
133
150
 
134
- ${skillUsage}${profileSection}
151
+ ${skillUsage}${ruleSection}${profileSection}
135
152
  </SYSTEMATIC_WORKFLOWS>`;
136
153
  }
137
154
 
@@ -1058,6 +1075,7 @@ var initializePlugin = async ({ client, directory }) => {
1058
1075
  const config = loadConfig(directory);
1059
1076
  const bootstrapContent = getBootstrapContent(config, {
1060
1077
  bundledSkillsDir,
1078
+ worktreePlacementRule: readWorktreePlacementRule(bundledSkillsDir) ?? undefined,
1061
1079
  profileBlock: readHarnessProfile(bundledSkillsDir, "opencode") ?? undefined
1062
1080
  });
1063
1081
  const configHandler = createConfigHandler({
@@ -21,13 +21,28 @@ export declare const applyBootstrapContent: (output: {
21
21
  export interface BootstrapDeps {
22
22
  bundledSkillsDir: string;
23
23
  usageTemplate?: string;
24
+ /**
25
+ * Placement rule text. Callers pass it whenever the packaged file reads; when
26
+ * the read fails (`readWorktreePlacementRule` returns null after a logged
27
+ * error) they pass nothing and the rule is left out, as with
28
+ * `readHarnessProfile`. `getBootstrapContent` also omits it when
29
+ * `git-worktree` is in `disabled_skills`, so OpenCode and Pi cannot drift.
30
+ */
31
+ worktreePlacementRule?: string;
24
32
  profileBlock?: string;
25
33
  }
26
34
  /** Reads a harness capability profile from the packaged using-systematic references. */
27
35
  export declare function readHarnessProfile(bundledSkillsDir: string, name: string): string | null;
36
+ /** Reads the shared worktree placement rule from the packaged using-systematic references. */
37
+ export declare function readWorktreePlacementRule(bundledSkillsDir: string): string | null;
28
38
  type BootstrapContentConfig = Pick<SystematicConfig, 'bootstrap' | 'disabled_skills'>;
29
- /** Safely computes default bootstrap content, returning null instead of throwing. */
30
- export declare function computeBootstrapContentSafe(deps: BootstrapDeps, reportError?: (error: unknown) => void): string | null;
39
+ /**
40
+ * Safely computes default bootstrap content, returning null instead of throwing.
41
+ *
42
+ * Only `disabledSkills` reaches the composition. `bootstrap.enabled` and
43
+ * `bootstrap.file` stay at their defaults, so Pi keeps ignoring both.
44
+ */
45
+ export declare function computeBootstrapContentSafe(deps: BootstrapDeps, reportError?: (error: unknown) => void, disabledSkills?: readonly string[]): string | null;
31
46
  /** Composes an existing system prompt with nullable bootstrap content; returns null when bootstrapContent is null. */
32
47
  export declare function composeSystemPromptWithBootstrap(existingSystemPrompt: string, bootstrapContent: string | null): string | null;
33
48
  export declare function getBootstrapContent(config: BootstrapContentConfig, deps: BootstrapDeps): string | null;
@@ -39,7 +39,7 @@ export interface ManifestEntry {
39
39
  * - agents/review/project-standards-reviewer.md — CRITICAL: requires orchestrator <standards-paths>.
40
40
  * - agents/review/kieran-typescript-reviewer.md — WARNING: excluded by plan recommendation.
41
41
  * - agents/research/slack-researcher.md — CRITICAL: requires Slack MCP environment.
42
- * - agents/research/learnings-researcher.md — CRITICAL: references Systematic skill paths.
42
+ * - agents/research/learnings-researcher.md — not curated: it reads the host project's docs/solutions/ layout, so curating it is a separate decision.
43
43
  * - agents/workflow/pr-comment-resolver.md — WARNING: "Spawned by the resolve-pr-feedback skill".
44
44
  */
45
45
  export interface CuratedPersonaEntry {
package/dist/pi.js CHANGED
@@ -3362,13 +3362,22 @@ function readHarnessProfile(bundledSkillsDir, name) {
3362
3362
  return null;
3363
3363
  }
3364
3364
  }
3365
+ function readWorktreePlacementRule(bundledSkillsDir) {
3366
+ const rulePath = path2.join(bundledSkillsDir, "using-systematic/references/worktree-placement.md");
3367
+ try {
3368
+ return fs3.readFileSync(rulePath, "utf8").trim();
3369
+ } catch (error) {
3370
+ console.error(`Failed to read worktree placement rule ${rulePath}: ${error instanceof Error ? error.message : String(error)}`);
3371
+ return null;
3372
+ }
3373
+ }
3365
3374
  var DEFAULT_BOOTSTRAP_CONFIG = {
3366
3375
  bootstrap: { enabled: true },
3367
3376
  disabled_skills: []
3368
3377
  };
3369
- function computeBootstrapContentSafe(deps, reportError) {
3378
+ function computeBootstrapContentSafe(deps, reportError, disabledSkills = []) {
3370
3379
  try {
3371
- return getBootstrapContent(DEFAULT_BOOTSTRAP_CONFIG, deps);
3380
+ return getBootstrapContent({ ...DEFAULT_BOOTSTRAP_CONFIG, disabled_skills: [...disabledSkills] }, deps);
3372
3381
  } catch (error) {
3373
3382
  if (reportError !== undefined) {
3374
3383
  try {
@@ -3404,7 +3413,12 @@ function getSkillUsageTemplate() {
3404
3413
  Bundled skills ship with the Systematic plugin and are discoverable via \`systematic_skill\`.`;
3405
3414
  }
3406
3415
  function getBootstrapContent(config, deps) {
3407
- const { bundledSkillsDir, usageTemplate, profileBlock } = deps;
3416
+ const {
3417
+ bundledSkillsDir,
3418
+ usageTemplate,
3419
+ worktreePlacementRule,
3420
+ profileBlock
3421
+ } = deps;
3408
3422
  if (!config.bootstrap.enabled)
3409
3423
  return null;
3410
3424
  if (config.bootstrap.file) {
@@ -3420,6 +3434,9 @@ function getBootstrapContent(config, deps) {
3420
3434
  const { body } = parseFrontmatter(fullContent);
3421
3435
  const content = body.trim();
3422
3436
  const skillUsage = usageTemplate ?? getSkillUsageTemplate();
3437
+ const ruleSection = worktreePlacementRule === undefined || config.disabled_skills.includes("git-worktree") ? "" : `
3438
+
3439
+ ${worktreePlacementRule}`;
3423
3440
  const profileSection = profileBlock === undefined ? "" : `
3424
3441
 
3425
3442
  ${profileBlock}`;
@@ -3430,7 +3447,7 @@ You have access to structured engineering workflows via the Systematic plugin.
3430
3447
 
3431
3448
  ${content}
3432
3449
 
3433
- ${skillUsage}${profileSection}
3450
+ ${skillUsage}${ruleSection}${profileSection}
3434
3451
  </SYSTEMATIC_WORKFLOWS>`;
3435
3452
  }
3436
3453
 
@@ -11939,8 +11956,9 @@ async function systematicPiExtension(pi, deps = defaultPiExtensionDependencies)
11939
11956
  const bootstrapContent = computeBootstrapContentSafe({
11940
11957
  bundledSkillsDir,
11941
11958
  usageTemplate: PI_BOOTSTRAP_USAGE_TEMPLATE,
11959
+ worktreePlacementRule: readWorktreePlacementRule(bundledSkillsDir) ?? undefined,
11942
11960
  profileBlock: readHarnessProfile(bundledSkillsDir, "pi") ?? undefined
11943
- }, reportPiBootstrapFailure);
11961
+ }, reportPiBootstrapFailure, piConfig.disabled_skills);
11944
11962
  pi.on("before_agent_start", (event) => {
11945
11963
  const systemPrompt = composeSystemPromptWithBootstrap(event.systemPrompt, bootstrapContent);
11946
11964
  if (systemPrompt === null)