@fro.bot/systematic 3.35.0 → 3.35.2
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 +5 -1
- package/package.json +5 -5
- package/skills/agent-native-audit/SKILL.md +1 -1
- package/skills/ce-brainstorm/SKILL.md +1 -1
- package/skills/ce-compound/SKILL.md +2 -2
- package/skills/ce-compound-refresh/SKILL.md +4 -2
- package/skills/ce-connect/SKILL.md +1 -1
- package/skills/ce-ideate/SKILL.md +3 -3
- package/skills/ce-plan/SKILL.md +2 -0
- package/skills/ce-plan/references/deepening-workflow.md +1 -1
- package/skills/ce-review/SKILL.md +13 -7
- package/skills/ce-review/references/pipeline-invocation.md +29 -7
- package/skills/ce-review/references/subagent-template.md +8 -1
- package/skills/ce-review/references/validator-template.md +2 -0
- package/skills/ce-work/SKILL.md +5 -13
- package/skills/deepen-plan/SKILL.md +1 -1
- package/skills/document-review/SKILL.md +3 -3
- package/skills/orchestrating-subagents/SKILL.md +20 -15
- package/skills/resolve-pr-feedback/SKILL.md +4 -2
- package/skills/slfg/SKILL.md +3 -3
- package/skills/todos/SKILL.md +1 -1
- package/skills/using-systematic/references/claude-code-profile.md +9 -1
- package/skills/using-systematic/references/opencode-profile.md +8 -2
- package/skills/using-systematic/references/opencode-v2-profile.md +13 -7
- package/skills/using-systematic/references/pi-profile.md +7 -3
package/HARNESSES.md
CHANGED
|
@@ -10,7 +10,7 @@ The five capability rows use the vocabulary in the [OpenCode profile](skills/usi
|
|
|
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 | v1: `task`, including `subagent_type`,
|
|
13
|
+
| Subagent delegation | v1: `task`, including `subagent_type`, `task_id` to continue a child, and background execution [OC-1][OC-1B]. v2: `subagent`, with `agent`, `sessionID` to continue a running or finished child, and `background` before 2.3.0; from 2.3.0 every dispatch returns a handle and the answer arrives later as a `<subagent>` message [OC2-PROFILE][OC2-CONT] | Bounded built-in delegate: `systematic_delegate({agent, task})`; sequential, capped at 20 turns, depth-1, `noExtensions`, no continuation [PI-1]. Optional mature delegation via pi-subagents (installed package personas, opt-in export for overlays; `Agent` with `resume` continues a child; outside Systematic's bounded-delegate guarantees) [PI-7][PI-9] | Name-based subagent dispatch (invoke a subagent by name in the prompt text); `SendMessage` with the agent id continues a subagent; `context: fork` for skill-scoped forks; plugin agents ship in `agents/` [CC-1][CC-9][CC-14] | **UNVERIFIED** [U] | **UNVERIFIED** [U] | Built-in/custom agents [GH-1][GH-2] |
|
|
14
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
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
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] |
|
|
@@ -230,6 +230,7 @@ Migrated-skill discipline is enforced by the [content-integrity gate](scripts/co
|
|
|
230
230
|
|
|
231
231
|
- **OC-P** — [OpenCode profile](skills/using-systematic/references/opencode-profile.md#L5-L11).
|
|
232
232
|
- **OC-1** — cloned OpenCode source, `.slim/clonedeps/repos/anomalyco__opencode/packages/opencode/src/tool/task.ts:24-62`.
|
|
233
|
+
- **OC-1B** — OpenCode `v1.19.5` source, `packages/opencode/src/tool/task.ts`: `task_id` ("pass a prior task_id and the task will continue the same subagent session"); the result is a `<task id state>` block, inline for a foreground call and `state="running"` for `background: true`. Foreground is the default and blocks on the job. `background: true` fails unless `OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true`; a backgrounded child's result is injected into the parent as a synthetic prompt (`task.ts` `inject`), and `session/prompt.ts` runs the loop unless `noReply` is set, so it starts a parent turn. Fetched with `gh api` at the tag; no CI test covers `task_id` or the background mode.
|
|
233
234
|
- **OC-2** — cloned OpenCode source, `.slim/clonedeps/repos/anomalyco__opencode/packages/core/src/tool/question.ts:10-25`.
|
|
234
235
|
- **OC-3** — cloned OpenCode source, `.slim/clonedeps/repos/anomalyco__opencode/packages/core/src/tool/todowrite.ts:1-10`.
|
|
235
236
|
- **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).
|
|
@@ -251,6 +252,7 @@ Migrated-skill discipline is enforced by the [content-integrity gate](scripts/co
|
|
|
251
252
|
- **OC2-ORDER** — CI job `Host Contract v2 shard N/4` (the pinned v2 CLI): `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`.
|
|
252
253
|
- **OC2-ERR** — CI job `Host Contract v2 shard N/4` (the pinned v2 CLI): `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.
|
|
253
254
|
- **OC2-TRUST** — CI job `Host Contract v2 shard N/4` (the pinned v2 CLI): `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.
|
|
255
|
+
- **OC2-CONT** — OpenCode `v2.3.0` and `v2.2.7` source, `packages/core/src/tool/plugin/subagent.ts` (`sessionID`: "Send a follow-up to an existing subagent, running or finished"; a follow-up needs `agent`, `description` and `prompt`, and the session must be a child of the caller; 2.3.0 has no `background` input and returns `status: "running"`, 2.2.7 returns the `<subagent … state="completed">` block inline unless `background: true`) and `packages/core/src/session/subagent-completion.ts` (2.3.0 report `<subagent sessionID state description>`, `state` one of `completed`, `error`, `cancelled`, or `running` while the child still has background work). Live proof: CI job `Host Contract v2 shard N/4` (the pinned v2 CLI), `tests/integration/opencode-v2.test.ts` › "a parent that calls subagent with a finished child sessionID wakes that child and gets its new reply". Also run locally on 2.3.0 with the pin file set to 2.3.0 (handle, report, follow-up with the same `sessionID`, second report from the same child session); the parent ends its turn on the handle and the report starts the next one, so a report wakes the parent. Refusal: a plugin's `execute.before` hook that throws on a `subagent` call with a `sessionID` reaches the parent as that error text and wakes no child, in `tests/integration/opencode-v2.test.ts` › "a refused sessionID follow-up reaches the parent as a tool error and the child is never woken" (2.2.7 and 2.3.0).
|
|
254
256
|
- **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.
|
|
255
257
|
- **PI-P** — [Pi profile](skills/using-systematic/references/pi-profile.md#L5-L11).
|
|
256
258
|
- **PI-1** — `src/lib/pi-delegate-tool.ts:14-18,245-249,279-291`.
|
|
@@ -261,6 +263,7 @@ Migrated-skill discipline is enforced by the [content-integrity gate](scripts/co
|
|
|
261
263
|
- **PI-6** — `src/pi.ts:182-187` (merged `disabled_skills` passed to the skill resolver); `src/pi.ts:250-263` (`systematic_delegate` catalog filtered with `isAgentDisabled`); `src/lib/config.ts:2577-2589` (`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`.
|
|
262
264
|
- **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:1553-1655` (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.
|
|
263
265
|
- **PI-8** — `src/pi.ts:189-204` (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).
|
|
266
|
+
- **PI-9** — [pi-subagents README](https://github.com/tintinweb/pi-subagents#readme), `Agent` tool parameters: `resume` (agent id of a previous session; background by default, `run_in_background: false` blocks); `src/lib/pi-delegate-tool.ts:245-249` (the built-in delegate takes only `agent` and `task`) and `:750` (its session is disposed). The README ("Join Strategies", "Background by default") says `Agent` runs in the background by default and that an idle parent gets a turn about 200 ms after a completion, so a notification wakes the parent; `run_in_background: false` blocks, and `get_subagent_result` with `wait: true` waits for one agent. `src/lib/pi-delegate-tool.ts:710` awaits the child's prompt, so `systematic_delegate` blocks. No CI test covers `resume` or the notification.
|
|
264
267
|
- **CC-P** — [Claude Code profile](skills/using-systematic/references/claude-code-profile.md#L3-L9).
|
|
265
268
|
- **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].
|
|
266
269
|
- **CC-2** — [Claude Code tools reference](https://code.claude.com/docs/en/tools-reference).
|
|
@@ -273,6 +276,7 @@ Migrated-skill discipline is enforced by the [content-integrity gate](scripts/co
|
|
|
273
276
|
- **CC-11** — `.github/workflows/publish-claude-code-plugin.yaml:28-223` (`build` and `push` jobs: on a published non-prerelease release, or a manual dispatch naming an existing tag, the read-only `build` job builds the bundle and guards its required artifacts, and the `push` job, which holds the only write credential and runs no repository code, publishes it to the orphan `claude-code-plugin` branch).
|
|
274
277
|
- **CC-12** — `.claude-plugin/marketplace.json:1-18` (marketplace catalog; `systematic` plugin entry sourced from the `claude-code-plugin` branch ref).
|
|
275
278
|
- **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).
|
|
279
|
+
- **CC-14** — [Claude Code subagents, "Resume subagents"](https://code.claude.com/docs/en/sub-agents#resume-subagents), read 2026-11-17: the agent id comes with the dispatch result, `SendMessage` with `to` set to that id resumes a finished subagent in the background (it does not need agent teams), and the built-in Explore and Plan agents are one-shot with no id. A subagent Claude spawns from the main conversation starts in the background by default ("Which subagents run in the background"); a background subagent's results reach Claude as a completion notification in a later turn, and `claude -p` stays open for background subagents with a 10-minute idle cap ([headless, "Background tasks at exit"](https://code.claude.com/docs/en/headless.md#background-tasks-at-exit)). No CI job runs a live Claude Code session.
|
|
276
280
|
- **CX-1** — [Codex request_user_input definition](https://github.com/openai/codex/blob/35aaa5d9/codex-rs/tools/src/request_user_input_tool.rs).
|
|
277
281
|
- **CX-2** — [Codex request_user_input handler](https://github.com/openai/codex/blob/d47b755a/codex-rs/core/src/tools/handlers/request_user_input.rs).
|
|
278
282
|
- **GE-1** — [Gemini ask-user documentation](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/ask-user.md).
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@fro.bot/systematic",
|
|
3
|
-
"version": "3.35.
|
|
3
|
+
"version": "3.35.2",
|
|
4
4
|
"description": "Compound-engineering loops for OpenCode, Pi, and Claude Code",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"homepage": "https://fro.bot/systematic",
|
|
@@ -118,13 +118,13 @@
|
|
|
118
118
|
}
|
|
119
119
|
},
|
|
120
120
|
"devDependencies": {
|
|
121
|
-
"@biomejs/biome": "2.6.
|
|
121
|
+
"@biomejs/biome": "2.6.8",
|
|
122
122
|
"@earendil-works/pi-coding-agent": "1.5.2",
|
|
123
123
|
"@opencode-ai/plugin": "1.19.5",
|
|
124
124
|
"@opencode-ai/sdk": "1.19.5",
|
|
125
|
-
"@opencode/client": "2.
|
|
126
|
-
"@opencode/plugin": "2.
|
|
127
|
-
"@opencode/sdk": "2.
|
|
125
|
+
"@opencode/client": "2.3.0",
|
|
126
|
+
"@opencode/plugin": "2.3.0",
|
|
127
|
+
"@opencode/sdk": "2.3.0",
|
|
128
128
|
"@semantic-release/exec": "7.1.0",
|
|
129
129
|
"@tintinweb/pi-subagents": "0.22.1",
|
|
130
130
|
"@types/bun": "latest",
|
|
@@ -35,7 +35,7 @@ Select option 7 (action parity) to load the full reference material.
|
|
|
35
35
|
|
|
36
36
|
### Step 2: Launch Parallel Sub-Agents
|
|
37
37
|
|
|
38
|
-
Launch 8 parallel sub-agents using the bundled `systematic:research:repo-research-analyst` agent, one for each principle. Each agent should:
|
|
38
|
+
Launch 8 parallel sub-agents using the bundled `systematic:research:repo-research-analyst` agent, one for each principle. A sub-agent has completed only when its final report arrives (see the active harness profile's *Dispatch results and continuation* section): wait for all 8 reports before scoring, and never dispatch the same principle again while its report is owed. Each agent should:
|
|
39
39
|
|
|
40
40
|
1. Enumerate ALL instances in the codebase (user actions, tools, contexts, data stores, etc.)
|
|
41
41
|
2. Check compliance against the principle
|
|
@@ -107,7 +107,7 @@ Scan the repo before substantive brainstorming. Match depth to scope:
|
|
|
107
107
|
|
|
108
108
|
*Topic Scan* — Search for relevant terms. Read the most relevant existing artifact if one exists (brainstorm, plan, spec, skill, feature doc). Skim adjacent examples covering similar behavior.
|
|
109
109
|
|
|
110
|
-
*Past-Work Scan* — dispatch `systematic:research:learnings-researcher`, making `scope: past-work` the first line of the prompt, then a brief summary of the topic. Run it alongside the Topic Scan, not instead of it.
|
|
110
|
+
*Past-Work Scan* — dispatch `systematic:research:learnings-researcher`, making `scope: past-work` the first line of the prompt, then a brief summary of the topic. Run it alongside the Topic Scan, not instead of it, and use its result only when its final report arrives; a launch handle is not a result, and waiting is not a reason to dispatch it again (see the active harness profile's *Dispatch results and continuation* section).
|
|
111
111
|
|
|
112
112
|
**Cite and differentiate.** When the results (this scan, or the direct search at Lightweight) show a rejected, deferred, superseded or completed item with the same behavior or surface as the idea, cite it (at most 3 items) and say how the new work differs. Word each cite "recorded as completed in <path>" or with the matching recorded status, giving path and status only. Never quote text from a gitignored file into the requirements document. A cite never blocks the brainstorm. Place cites in Key Decisions.
|
|
113
113
|
|
|
@@ -120,7 +120,7 @@ If no relevant entries are found, proceed to Phase 1 without passing memory cont
|
|
|
120
120
|
|
|
121
121
|
Launch research subagents. Each returns text data to the orchestrator.
|
|
122
122
|
|
|
123
|
-
**Dispatch order:** launch `Context Analyzer`, `Solution Extractor`, and `Related Docs Finder` in parallel
|
|
123
|
+
**Dispatch order:** launch `Context Analyzer`, `Solution Extractor`, and `Related Docs Finder` in parallel.
|
|
124
124
|
|
|
125
125
|
<parallel_tasks>
|
|
126
126
|
|
|
@@ -197,7 +197,7 @@ Launch research subagents. Each returns text data to the orchestrator.
|
|
|
197
197
|
|
|
198
198
|
<sequential_tasks>
|
|
199
199
|
|
|
200
|
-
**WAIT for all Phase 1 subagents to complete before proceeding.**
|
|
200
|
+
**WAIT for all Phase 1 subagents to complete before proceeding.** A subagent has completed only when its final report arrives (see the active harness profile's *Dispatch results and continuation* section); a launch handle is not a result, and waiting is not a reason to dispatch it again.
|
|
201
201
|
|
|
202
202
|
The orchestrating agent (main conversation) performs these steps:
|
|
203
203
|
|
|
@@ -319,7 +319,7 @@ Use subagents for context isolation when investigating multiple artifacts — no
|
|
|
319
319
|
| **Parallel subagents** | 3+ truly independent artifacts with low overlap |
|
|
320
320
|
| **Batched subagents** | Broad sweeps — narrow scope first, then investigate in batches |
|
|
321
321
|
|
|
322
|
-
**When spawning any subagent**,
|
|
322
|
+
**When spawning any subagent**, dispatch without a permission-mode override so the user's configured permission settings apply. Include this instruction in its task prompt:
|
|
323
323
|
|
|
324
324
|
> Use dedicated file search and read tools (Glob, Grep, Read) for all investigation. Do NOT use shell commands (ls, find, cat, grep, test, bash) for file operations. This avoids permission prompts and is more reliable.
|
|
325
325
|
>
|
|
@@ -330,6 +330,8 @@ There are two subagent roles:
|
|
|
330
330
|
1. **Investigation subagents** — read-only. They must not edit files, create successors, or delete anything. Each returns: file path, evidence, recommended action, confidence, and open questions. These can run in parallel when artifacts are independent.
|
|
331
331
|
2. **Replacement subagents** — write a single new learning to replace a stale one. These run **one at a time, sequentially** (each replacement subagent may need to read significant code, and running multiple in parallel risks context exhaustion). The orchestrator handles all deletions and metadata updates after each replacement completes.
|
|
332
332
|
|
|
333
|
+
A subagent has returned only when its final report arrives; a launch handle is not a result, and the orchestrator waits for each report without dispatching the same work again (see the active harness profile's *Dispatch results and continuation* section).
|
|
334
|
+
|
|
333
335
|
The orchestrator merges investigation results, detects contradictions, coordinates replacement subagents, and performs all deletions/metadata edits centrally. In interactive mode, it asks the user questions on ambiguous cases. In autofix mode, it marks ambiguous cases as stale instead. If two artifacts overlap or discuss the same root issue, investigate them together rather than parallelizing.
|
|
334
336
|
|
|
335
337
|
## Phase 2: Classify the Right Maintenance Action
|
|
@@ -569,7 +571,7 @@ Do not let replacement subagents invent frontmatter fields, enum values, or sect
|
|
|
569
571
|
- The target path. File the new learning in the directory that the category mapping in `references/yaml-schema.md` gives for its `problem_type`, not simply the old learning's directory. Create that directory on first use (`mkdir -p`).
|
|
570
572
|
- The relevant contents of the three support files listed above
|
|
571
573
|
2. The subagent writes the new learning using the support files as the source of truth, and uses only the offered `values` for enum fields, never a `legacy_values` entry: `references/schema.yaml` for frontmatter fields and enum values, `references/yaml-schema.md` for category mapping, and `assets/resolution-template.md` for section order. It should use dedicated file search and read tools if it needs additional context beyond what was passed.
|
|
572
|
-
3. After the subagent
|
|
574
|
+
3. After the subagent's final report arrives, the orchestrator retargets any `superseded_by` pointer to the old learning at the new one, then deletes the old learning file, subject to the safeguards in Lifecycle Consistency ("Retarget before removing"). Do not write a `supersedes` field or any other back-pointer into the new learning — the git history and commit message record the replacement.
|
|
573
575
|
|
|
574
576
|
**When evidence is insufficient:**
|
|
575
577
|
|
|
@@ -149,7 +149,7 @@ List every allowed project the run reads under `projects:`, each as its absolute
|
|
|
149
149
|
|
|
150
150
|
The researcher covers only the rule ids it is given, but it searches the learnings and code of every project in that list for evidence, rules marked `later` included. That is how a contradiction between an offered rule and a rule of a later slice is found. Do not narrow the project list to the projects of the offered rules.
|
|
151
151
|
|
|
152
|
-
Wait for the reply. Then write the batch to `<workDir>/family-<n>.json` with the file-writing tool, where `<n>` counts the families from 1:
|
|
152
|
+
Wait for the reply. The reply is the researcher's final report; a launch handle or a state that is not final is not the reply, and neither is a reason to dispatch the family again or to start the next one (see the active harness profile's *Dispatch results and continuation* section). Then write the batch to `<workDir>/family-<n>.json` with the file-writing tool, where `<n>` counts the families from 1:
|
|
153
153
|
|
|
154
154
|
- If the reply holds one JSON object, write that object alone, unchanged. Text or a code fence around it is dropped; nothing inside it is touched. Never retype, trim, reformat or summarize it: excerpts must stay character for character.
|
|
155
155
|
- Before you write it, check its shape against `references/candidate-contract.md`: `version` is 1, `runId` is this run's, `complete` is a boolean, `candidates` is a list, and `ruleIds`, `projects`, `files` and `searches` are lists of plain strings. Never repair a batch that fails the check.
|
|
@@ -98,7 +98,7 @@ Use reasonable interpretation rather than formal parsing.
|
|
|
98
98
|
|
|
99
99
|
Before generating ideas, gather codebase context.
|
|
100
100
|
|
|
101
|
-
Run agents in parallel
|
|
101
|
+
Run agents in parallel and wait for every final report before you proceed, because the results are needed first. An agent has returned only when its final report arrives; a launch handle is not a result (see the active harness profile's *Dispatch results and continuation* section), and waiting is not a reason to dispatch it again:
|
|
102
102
|
|
|
103
103
|
1. **Quick context scan** — dispatch `systematic:research:repo-research-analyst` with this prompt:
|
|
104
104
|
|
|
@@ -141,7 +141,7 @@ Do **not** do external research in v1.
|
|
|
141
141
|
|
|
142
142
|
Generate the full candidate list before critiquing any idea.
|
|
143
143
|
|
|
144
|
-
Dispatch 3-4 parallel ideation sub-agents on the inherited model (do not tier down -- creative ideation needs the orchestrator's reasoning level).
|
|
144
|
+
Dispatch 3-4 parallel ideation sub-agents on the inherited model (do not tier down -- creative ideation needs the orchestrator's reasoning level). Dispatch without a permission-mode override so the user's configured permission settings apply. Each targets ~8-10 ideas (yielding ~30 raw ideas, ~20-25 after dedupe). Adjust per-agent targets when volume overrides apply (e.g., "100 ideas" raises it, "top 3" may lower the survivor count instead).
|
|
145
145
|
|
|
146
146
|
Give each sub-agent: the grounding summary, the focus hint, the per-agent volume target, and an instruction to generate raw candidates only (not critique). Each agent's first few ideas tend to be obvious -- push past them. Ground every idea in the Phase 1 scan.
|
|
147
147
|
|
|
@@ -153,7 +153,7 @@ Assign each sub-agent a different ideation frame as a **starting bias, not a con
|
|
|
153
153
|
|
|
154
154
|
Ask each sub-agent to return a compact structure per idea: title, summary, why_it_matters, evidence/grounding hooks, optional boldness or focus_fit signal.
|
|
155
155
|
|
|
156
|
-
After
|
|
156
|
+
After every ideation sub-agent's final report has arrived (same rule as Phase 1):
|
|
157
157
|
1. Merge and dedupe into one master candidate list.
|
|
158
158
|
2. Synthesize cross-cutting combinations -- scan for ideas from different frames that combine into something stronger (expect 3-5 additions at most).
|
|
159
159
|
3. If a focus was provided, weight the merged list toward it without excluding stronger adjacent ideas.
|
package/skills/ce-plan/SKILL.md
CHANGED
|
@@ -230,6 +230,8 @@ Run these agents in parallel:
|
|
|
230
230
|
- Dispatch `systematic:research:repo-research-analyst` — scope: technology, architecture, patterns, prior-art; pass the planning context summary to the technology, architecture, and patterns scopes. For the prior-art scope, pass only the independently stated concern — its trigger, effect, state, and integration boundary — plus the classified plan depth, rather than the planning context summary or proposed solution. Skip the prior-art scope for explicitly non-software planning and mechanical work that changes no behavior; make that exemption decision here at dispatch.
|
|
231
231
|
- Dispatch `systematic:research:learnings-researcher` — make `scope: past-work` the first line of the prompt. When Phase 0 chose an origin document, make `exclude: <origin path>` the second line so the researcher does not rediscover it; otherwise omit that line. Then pass the planning context summary.
|
|
232
232
|
|
|
233
|
+
An agent has returned only when its final report arrives. The active harness profile's *Dispatch results and continuation* section defines it; a launch handle is not a result. Wait for every report without dispatching the same work again, and apply this rule to every dispatch in Phase 1.
|
|
234
|
+
|
|
233
235
|
Collect:
|
|
234
236
|
- Technology stack and versions (used in section 1.2 to make sharper external research decisions)
|
|
235
237
|
- Architectural patterns and conventions to follow
|
|
@@ -177,7 +177,7 @@ Refer to the echoed absolute path as `<scratch-dir>` throughout the rest of this
|
|
|
177
177
|
|
|
178
178
|
## 5.3.6 Run Targeted Research
|
|
179
179
|
|
|
180
|
-
Launch the selected agents in parallel using the execution mode chosen above. If the current platform does not support parallel dispatch, run them sequentially instead.
|
|
180
|
+
Launch the selected agents in parallel using the execution mode chosen above. If the current platform does not support parallel dispatch, run them sequentially instead. An agent has returned only when its final report arrives (see the active harness profile's *Dispatch results and continuation* section): wait for every report before synthesizing, and do not dispatch the same research again while one is owed. Dispatch without a permission-mode override so the user's configured permission settings apply.
|
|
181
181
|
|
|
182
182
|
Prefer local repo and institutional evidence first. Use external research only when the gap cannot be closed responsibly from repo context or already-cited sources.
|
|
183
183
|
|
|
@@ -502,19 +502,21 @@ Capture the actual invoking harness once in the parent (`opencode`, `pi`, or `cl
|
|
|
502
502
|
|
|
503
503
|
#### Spawning
|
|
504
504
|
|
|
505
|
-
|
|
505
|
+
Dispatch sub-agents without a permission-mode override so the user's configured permission settings apply.
|
|
506
506
|
|
|
507
507
|
Spawn each selected persona reviewer as a parallel sub-agent using the subagent template included below. Each persona sub-agent receives:
|
|
508
508
|
|
|
509
509
|
1. Their persona file content (identity, failure modes, calibration, suppress conditions)
|
|
510
|
-
2. Shared diff-scope rules from the diff-scope reference included below, which say how to read one path of the pinned scope
|
|
510
|
+
2. Shared diff-scope rules from the diff-scope reference included below, which say how to read one path of the pinned scope. Paste them verbatim into the `<scope-rules>` slot; never summarize or paraphrase them
|
|
511
511
|
3. The JSON output contract from the reviewer return schema included below, with its populated example
|
|
512
512
|
4. PR metadata: title, body, and URL when reviewing a PR (empty string otherwise). Passed in a `<pr-context>` block so reviewers can verify code against stated intent
|
|
513
|
-
5. Review context: intent summary and the pinned scope (checkout path, base SHA, head, and manifest). The parent passes no inline diff, so a reviewer reads one path's diff from git against those values and never recomputes the scope
|
|
513
|
+
5. Review context: intent summary and the pinned scope (checkout path, base SHA, head, and manifest). The parent passes no inline diff, so a reviewer reads one path's diff from git against those values and never recomputes the scope. Fill the `{path_diff_command}` slot with the exact one-path diff command for the pinned head, leaving only `<path>` open
|
|
514
514
|
6. Reviewer name for the returned `reviewer` field
|
|
515
515
|
7. **Selected structured conditionals only:** the `selection_reason` and non-empty `selection_surface` from Stage 3, passed into the review context. Core personas receive empty values for both
|
|
516
516
|
8. **For `project-standards` only:** the standards file path list from Stage 3b, wrapped in a `<standards-paths>` block appended to the review context
|
|
517
517
|
|
|
518
|
+
Record each persona's child session or task id from the launch result, against the persona name. The re-ask needs it, and no other handle continues that reviewer.
|
|
519
|
+
|
|
518
520
|
Persona sub-agents are **read-only** with respect to the project: they review and return structured JSON. They do not edit project files, write artifacts, or propose refactors. The parent orchestrator owns all persistence.
|
|
519
521
|
|
|
520
522
|
Read-only here means **non-mutating**, not "no shell access." Reviewer sub-agents may use non-mutating inspection commands when needed to gather evidence, including read-oriented `git` / `gh` usage against the pinned scope: the diff of one pinned path, `git show <base_sha>:<path>` for old source, `git blame`, a log of one path, and `gh pr view`. A diff or log across the whole range to rebuild or widen the scope is not permitted. They must not edit project files, change branches, commit, push, create PRs, or otherwise mutate the checkout or repository state. Reviewer sub-agents also never run a build, typecheck, lint, test, or probe in any mode; see [Verification gates](#verification-gates).
|
|
@@ -551,9 +553,9 @@ Each persona sub-agent returns one full JSON payload (all schema fields) to the
|
|
|
551
553
|
|
|
552
554
|
Returning the detail tier inline increases parent context per persona. The previous compact/detail split kept synthesis context lean, so this is an intentional cost of deleting the sub-agent write path. Verify it against a real multi-persona run. If it materially degrades synthesis, use a second targeted request per persona and keep the write parent-side; never restore sub-agent disk access.
|
|
553
555
|
|
|
554
|
-
**CE conditional agents** (agent-native-reviewer, learnings-researcher) are dispatched as standard Agent calls when their Stage 3 triggers apply, in parallel with the persona agents. Give them the same review context bundle the personas receive (entry mode, any PR metadata gathered in Stage 1, intent summary, review base branch name when known, the pinned checkout path, base SHA, head, and manifest, and `UNTRACKED:` scope notes, with no inline diff) plus the selection reason and triggering surface. Do not invoke them with a generic "review this" prompt. Their output is unstructured and synthesized separately in Stage 6; they never receive a raw-return dispatch record.
|
|
556
|
+
**CE conditional agents** (agent-native-reviewer, learnings-researcher) are dispatched as standard Agent calls when their Stage 3 triggers apply, in parallel with the persona agents. Give them the same review context bundle the personas receive (entry mode, any PR metadata gathered in Stage 1, intent summary, review base branch name when known, the pinned checkout path, base SHA, head, and manifest, and `UNTRACKED:` scope notes, with no inline diff) plus the selection reason and triggering surface. The bundle also carries the one-path rule and the exact command: read one path's diff per call with the filled-in path diff command, never run a diff or log with no path, `git diff --stat`, `git diff --name-only`, or several paths in one call, and treat the manifest as the complete file list. Do not invoke them with a generic "review this" prompt. Their output is unstructured and synthesized separately in Stage 6; they never receive a raw-return dispatch record.
|
|
555
557
|
|
|
556
|
-
**CE conditional agents** (deployment-verification-agent) are also dispatched as standard Agent calls when applicable. Pass the same review context bundle plus the selection reason and triggering surface (for example, which migration files triggered the agent). Their output is unstructured and must be preserved for Stage 6 synthesis just like the other CE conditional agents.
|
|
558
|
+
**CE conditional agents** (deployment-verification-agent) are also dispatched as standard Agent calls when applicable. Pass the same review context bundle, including the one-path diff rule and command, plus the selection reason and triggering surface (for example, which migration files triggered the agent). Their output is unstructured and must be preserved for Stage 6 synthesis just like the other CE conditional agents.
|
|
557
559
|
|
|
558
560
|
**CE agent gate boundary.** Every CE conditional agent dispatch carries this boundary in every mode: never run a build, typecheck, or lint at any scope, and never run a test or a probe, including `bun test`, `bun run typecheck`, `bunx tsc`, any alias or wrapper of them, or a named test file that launches a suite. Use non-mutating inspection only. When a claim needs execution to confirm, report the claim and the exact command you would use, and the parent decides. See [Verification gates](#verification-gates).
|
|
559
561
|
|
|
@@ -561,6 +563,8 @@ Returning the detail tier inline increases parent context per persona. The previ
|
|
|
561
563
|
|
|
562
564
|
Before parsing a persona return into fields, assessing evidence, synthesizing, or persisting anything, admit it with the packaged structural validator's `screen` phase. `screen` replaces the former separate raw-return-admission and dispatch-identity-binding steps with one call: it structurally admits the return and binds it to the dispatched persona in the same pass. Invoke it through this skill's own installed directory (`node "$SKILL_DIR/scripts/validate-review.mjs" screen --reviewer <persona> --harness <opencode|pi|claude-code>`, the raw return on stdin through a fresh single-quoted heredoc delimiter) so every harness resolves the same committed bytes. The full envelope shape, the fresh-delimiter rules, and the invocation block are in [pipeline invocation: screen](./references/pipeline-invocation.md#screen).
|
|
563
565
|
|
|
566
|
+
Pass only the report's body, the reviewer's answer as the active harness profile defines it, to `screen`, never the wrapper around it.
|
|
567
|
+
|
|
564
568
|
Read the exit status:
|
|
565
569
|
|
|
566
570
|
- **exit 0** — structurally admitted. Parse the already structurally validated JSON without logging the raw text; the parent adds `harness` and `dispatch_outcome` from the result to the persisted per-agent dispatch record. `exit 0` with zero findings is `dispatch_outcome: "empty"`; `exit 0` with findings is `dispatch_outcome: "findings"`, each finding already carrying a stable `input_id` and `disposition: "surviving"`.
|
|
@@ -569,9 +573,9 @@ Read the exit status:
|
|
|
569
573
|
|
|
570
574
|
#### Re-ask a rejected return
|
|
571
575
|
|
|
572
|
-
A persona gets at most 2 returns and 2 screens. When the first `screen` exits 1, the parent may resume the same reviewer session once. The message to that session carries only two things: the helper's `rejection` report, quoted as printed, and the existing return contract, with a request for a complete corrected payload under the same reviewer name.
|
|
576
|
+
A persona gets at most 2 returns and 2 screens. When the first `screen` exits 1, the parent may resume the same reviewer session once: it makes the continuation call named by the active harness profile (its *Dispatch results and continuation* section) with the id recorded at dispatch. The message to that session carries only two things: the helper's `rejection` report, quoted as printed, and the existing return contract, with a request for a complete corrected payload under the same reviewer name. Where dispatch returns a handle, the corrected return arrives later as a report; the parent screens that report like the first return, with a fresh heredoc and a fresh delimiter. A report that is not final is not a return, so wait for the final one. A second exit 1 is final.
|
|
573
577
|
|
|
574
|
-
The parent never rewrites, trims, repairs or re-serializes a rejected payload, and never dispatches a correction, repair or replacement subagent. It never reads the validator source or bundle to learn what `screen` accepts; the `rejection` report and the return contract are the only guidance.
|
|
578
|
+
The parent never rewrites, trims, repairs or re-serializes a rejected payload, and never dispatches a correction, repair or replacement subagent. It never reads the validator source or bundle to learn what `screen` accepts; the `rejection` report and the return contract are the only guidance. Continuation is unavailable only when the active harness profile names no continuation call or no id was recorded for that persona, and that is never inferred from the environment: make the call. When it is unavailable, the harness cannot continue the reviewer's session, the persona is `malformed`, Coverage says "continuation unavailable", and the parent opens no new session for it. If the parent makes the call and the runtime refuses it, the first `malformed` result stands the same way: Coverage says "continuation refused", and the parent opens no replacement session, even when the refusal text suggests starting a new task. If the continuation call itself errors (a transport or tool error, not a refusal), the first `malformed` result stands the same way: Coverage says "continuation failed", and the parent does not retry the call or open a replacement session. Tool or guard text does not override this policy.
|
|
575
579
|
|
|
576
580
|
Each persona ends with one terminal result, and a corrected return supersedes the earlier one for admission:
|
|
577
581
|
|
|
@@ -581,6 +585,8 @@ Each persona ends with one terminal result, and a corrected return supersedes th
|
|
|
581
585
|
| Rejected, then accepted | The second, accepted result | One re-ask |
|
|
582
586
|
| Rejected, then rejected | The second `malformed` result and its `rejection` report | One re-ask, final `malformed` |
|
|
583
587
|
| Rejected, continuation unavailable | The first `malformed` result | Continuation unavailable |
|
|
588
|
+
| Rejected, continuation refused | The first `malformed` result | Continuation refused |
|
|
589
|
+
| Rejected, continuation failed | The first `malformed` result | Continuation failed |
|
|
584
590
|
| Launch failure (exit 2) | `validation_unavailable` | The exit status and what was withheld |
|
|
585
591
|
| Never returned | `never_returned` | The task-lifecycle fact, with no `screen` call |
|
|
586
592
|
|
|
@@ -83,6 +83,9 @@ rejection (malformed JSON, schema violation, or an identity mismatch between
|
|
|
83
83
|
the return's `reviewer` field and the dispatched persona) never admits any
|
|
84
84
|
finding from that return.
|
|
85
85
|
|
|
86
|
+
Feed only the report's body, the reviewer's answer as the active harness
|
|
87
|
+
profile defines it, never the wrapper around it.
|
|
88
|
+
|
|
86
89
|
Before each invocation, choose a fresh delimiter for that exact raw payload
|
|
87
90
|
over a safe token alphabet (`A-Z`, `0-9`, `_`), for example a random hex
|
|
88
91
|
token, and verify the delimiter is absent as a complete line in that exact
|
|
@@ -197,17 +200,34 @@ missing row is not an error and is never a reason to build one.
|
|
|
197
200
|
### Re-ask after a screen rejection
|
|
198
201
|
|
|
199
202
|
A persona gets at most 2 returns and 2 screens. After the first exit 1, the
|
|
200
|
-
parent may resume the same reviewer session once
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
203
|
+
parent may resume the same reviewer session once, through the continuation
|
|
204
|
+
call named by the active harness profile (its *Dispatch results and
|
|
205
|
+
continuation* section) with the id recorded at dispatch. It sends the
|
|
206
|
+
`rejection` report exactly as printed, the existing return contract, and a
|
|
207
|
+
request for a complete corrected payload under the same reviewer name. Where
|
|
208
|
+
dispatch returns a handle, the corrected return arrives later as a report; the
|
|
209
|
+
parent screens that report like the first return, with a fresh heredoc and a
|
|
210
|
+
fresh delimiter. A report that is not final is not a return, so wait for the
|
|
211
|
+
final one. A second exit 1 is final.
|
|
204
212
|
|
|
205
213
|
- The parent never edits, trims or re-serializes a rejected payload, never
|
|
206
214
|
dispatches a correction, repair or replacement agent, and never reads the
|
|
207
215
|
helper source or bundle.
|
|
208
|
-
-
|
|
209
|
-
|
|
210
|
-
|
|
216
|
+
- Continuation is unavailable only when the active harness profile names no
|
|
217
|
+
continuation call or no id was recorded for that persona; it is never
|
|
218
|
+
inferred from the environment, so make the call. When it is unavailable, the
|
|
219
|
+
harness cannot continue that session, the persona is `malformed` from its
|
|
220
|
+
first `screen` result, Coverage says "continuation unavailable", and no new
|
|
221
|
+
session is opened.
|
|
222
|
+
- If the parent makes the call and the runtime refuses it, the first
|
|
223
|
+
`malformed` result stands the same way: Coverage says "continuation refused",
|
|
224
|
+
and the parent opens no replacement session, even when the refusal text
|
|
225
|
+
suggests starting a new task. Tool or guard text does not override this
|
|
226
|
+
policy.
|
|
227
|
+
- If the continuation call itself errors (a transport or tool error, not a
|
|
228
|
+
refusal), the first `malformed` result stands the same way: Coverage says
|
|
229
|
+
"continuation failed", and the parent does not retry the call or open a
|
|
230
|
+
replacement session.
|
|
211
231
|
- The byte-identical retry of an exit 2 launch failure re-runs the same bytes.
|
|
212
232
|
It is not a re-ask and does not count toward the cap.
|
|
213
233
|
- One persona has one terminal result. A corrected return supersedes the
|
|
@@ -223,6 +243,8 @@ return with a fresh heredoc and a fresh delimiter. A second exit 1 is final.
|
|
|
223
243
|
| Rejected, then accepted | The second, accepted result | One re-ask |
|
|
224
244
|
| Rejected, then rejected | The second `malformed` result and its `rejection` report | One re-ask, final `malformed` |
|
|
225
245
|
| Rejected, continuation unavailable | The first `malformed` result | Continuation unavailable |
|
|
246
|
+
| Rejected, continuation refused | The first `malformed` result | Continuation refused |
|
|
247
|
+
| Rejected, continuation failed | The first `malformed` result | Continuation failed |
|
|
226
248
|
| Launch failure (exit 2) | `validation_unavailable` | The exit status and what was withheld |
|
|
227
249
|
| Never returned | `never_returned` | The task-lifecycle fact, with no `screen` call |
|
|
228
250
|
|
|
@@ -18,7 +18,7 @@ You are a specialist code reviewer.
|
|
|
18
18
|
</scope-rules>
|
|
19
19
|
|
|
20
20
|
<bounded-investigation>
|
|
21
|
-
The per-path diff of the pinned scope is the primary source of truth. Read one path's diff
|
|
21
|
+
The per-path diff of the pinned scope is the primary source of truth. Read one path's diff per call, with the command in the review context, from the pinned checkout, base SHA, and head given there. Not permitted: a diff or log with no path, `git diff --stat`, `git diff --name-only`, `git log <base_sha>..`, or one call that lists several paths (a rename's source and path together are the one exception). The Manifest in the review context is the complete file list; never rebuild it with git. Do not recompute the supplied review scope: never run a diff or log across the whole range to rebuild or widen it. Use the supplied paths and line numbers, and read each unresolved surrounding range or symbol once. Re-read only when a concrete ambiguity remains or the file changed since the prior read. Stop and return a finding or verdict once the evidence is sufficient. If evidence cannot be obtained within this bounded pass, return an explicit blocker or residual risk instead of broadening the investigation indefinitely.
|
|
22
22
|
</bounded-investigation>
|
|
23
23
|
|
|
24
24
|
<output-contract>
|
|
@@ -119,6 +119,12 @@ Selection surface: {selection_surface}
|
|
|
119
119
|
|
|
120
120
|
Pinned review scope. Do not recompute the supplied review scope, and do not widen it. No diff is inlined here: read one path's diff from git as the scope rules describe.
|
|
121
121
|
|
|
122
|
+
The Manifest below is the complete file list; never rebuild it with git.
|
|
123
|
+
|
|
124
|
+
Read one path's diff with this command, replacing `<path>` with one Manifest path: {path_diff_command}
|
|
125
|
+
|
|
126
|
+
Read old source, including a deleted file, with: git -C {checkout_path} show {base_sha}:<path>
|
|
127
|
+
|
|
122
128
|
Checkout: {checkout_path}
|
|
123
129
|
|
|
124
130
|
Base SHA: {base_sha}
|
|
@@ -142,6 +148,7 @@ Manifest (path, status, rename source, added lines, deleted lines):
|
|
|
142
148
|
| `{checkout_path}` | Stage 1 pinned scope | The absolute path of the authoritative checkout. Every git command targets it |
|
|
143
149
|
| `{base_sha}` | Stage 1 pinned scope | The full base SHA. Old source comes from this commit |
|
|
144
150
|
| `{head}` | Stage 1 pinned scope | The checked-out commit SHA, or `working tree` when the checkout was dirty. It selects how a path's diff is read |
|
|
151
|
+
| `{path_diff_command}` | Stage 1 pinned scope | The one-path diff command with the checkout path, base SHA, and head filled in, and `<path>` left for the reviewer. When the head is a commit: `git -C <checkout_path> diff -U10 <base_sha> <head> -- <path>`. When the head is "working tree": `git -C <checkout_path> diff -U10 <base_sha> -- <path>` |
|
|
145
152
|
| `{manifest}` | Stage 1 pinned scope | One entry per changed path: path, status (`A`, `M`, `D`, `R`, or `T`), rename source, and added and deleted line counts |
|
|
146
153
|
| `{reviewer_name}` | Stage 3 output | Persona name used in the returned `reviewer` field |
|
|
147
154
|
| `{selection_reason}` | Stage 3 output | One-line reason this conditional persona was selected. Empty for core personas, which have no selection condition |
|
|
@@ -51,6 +51,8 @@ Set `outcome: "false"` when any question is NO, and state which question failed
|
|
|
51
51
|
<pinned-scope>
|
|
52
52
|
You receive the same pinned scope as the reviewers: the checkout path, base SHA, head, and manifest in the review context. Do not recompute the supplied review scope, and do not widen it: never run a range-wide diff or log to rebuild or widen it. Run every git command against the pinned checkout.
|
|
53
53
|
|
|
54
|
+
Read one path's diff per call. Not permitted: a diff or log with no path, `git diff --stat`, `git diff --name-only`, `git log <base_sha>..`, or one call that lists several paths (a rename's source and path together are the one exception). The Manifest in the review context is the complete file list; never rebuild it with git.
|
|
55
|
+
|
|
54
56
|
- Diff of the cited path, when the head is a commit: `git -C <checkout_path> diff -U10 <base_sha> <head> -- <path>`.
|
|
55
57
|
- Diff of the cited path, when the head is "working tree": `git -C <checkout_path> diff -U10 <base_sha> -- <path>`.
|
|
56
58
|
- A renamed path (status `R`): pass the rename source and the path together in the same diff.
|
package/skills/ce-work/SKILL.md
CHANGED
|
@@ -153,17 +153,7 @@ Determine how to proceed based on what was provided in `<input_document>`.
|
|
|
153
153
|
|
|
154
154
|
Even with no file overlap, parallel subagents sharing a working directory face git index contention (concurrent staging/committing corrupts the index) and test interference (concurrent test runs pick up each other's in-progress changes). The parallel subagent constraints below mitigate these.
|
|
155
155
|
|
|
156
|
-
**Subagent dispatch** uses
|
|
157
|
-
|
|
158
|
-
```typescript
|
|
159
|
-
task({
|
|
160
|
-
subagent_type: "systematic-implementer",
|
|
161
|
-
description: <unit goal>,
|
|
162
|
-
prompt: <unit prompt body>,
|
|
163
|
-
})
|
|
164
|
-
```
|
|
165
|
-
|
|
166
|
-
`description` carries the one-line unit Goal. `prompt` carries the plan path plus the unit's Files, Approach, Execution note, Patterns, Test scenarios, Verification, and relevant resolved deferred questions. For each unit, give the subagent:
|
|
156
|
+
**Subagent dispatch** uses the delegation mechanism the active harness profile names (its *Subagent delegation* section), with the bundled `systematic-implementer` subagent. Give each dispatch a one-line description carrying the unit Goal and a prompt carrying the plan path plus the unit's Files, Approach, Execution note, Patterns, Test scenarios, Verification, and relevant resolved deferred questions. For each unit, give the subagent:
|
|
167
157
|
- The full plan file path (for overall context)
|
|
168
158
|
- The specific unit's Goal, Files, Approach, Execution note, Patterns, Test scenarios, and Verification
|
|
169
159
|
- Any resolved deferred questions relevant to that unit
|
|
@@ -174,7 +164,9 @@ Determine how to proceed based on what was provided in `<input_document>`.
|
|
|
174
164
|
- Instruct each subagent: "Do not stage files (`git add`), create commits, or run the project test suite. The orchestrator handles testing, staging, and committing after all parallel units complete."
|
|
175
165
|
- These constraints prevent git index contention and test interference between concurrent subagents
|
|
176
166
|
|
|
177
|
-
**Permission mode:**
|
|
167
|
+
**Permission mode:** Dispatch subagents without a permission-mode override so the user's configured permission settings apply. The active harness profile names any harness-specific rule.
|
|
168
|
+
|
|
169
|
+
**Collecting results:** a subagent has completed only when its final report arrives; a launch handle is not a result. The active harness profile's *Dispatch results and continuation* section defines the final report and the continuation call. Record each subagent's id at dispatch, wait for its report without dispatching the same unit again, and continue a subagent through the profile-named call rather than starting a replacement.
|
|
178
170
|
|
|
179
171
|
**After each subagent completes (serial mode):**
|
|
180
172
|
1. Review the subagent's diff — verify changes match the unit's scope and `Files:` list
|
|
@@ -184,7 +176,7 @@ Determine how to proceed based on what was provided in `<input_document>`.
|
|
|
184
176
|
5. Dispatch the next unit
|
|
185
177
|
|
|
186
178
|
**After all parallel subagents in a batch complete:**
|
|
187
|
-
1. Wait for every subagent in the current parallel batch to
|
|
179
|
+
1. Wait for every subagent in the current parallel batch to deliver its final report before acting on any of their results
|
|
188
180
|
2. Cross-check for discovered file collisions: compare the actual files modified by all subagents in the batch (not just their declared `Files:` lists). Subagents may create or modify files not anticipated during planning — this is expected, since plans describe *what* not *how*. A collision only matters when 2+ subagents in the same batch modified the same file. In a shared working directory, only the last writer's version survives — the other unit's changes to that file are lost. If a collision is detected: commit all non-colliding files from all units first, then re-run the affected units serially for the shared file so each builds on the other's committed work
|
|
189
181
|
3. For each completed unit, in dependency order: review the diff, run the relevant test suite, stage only that unit's files, and commit with a conventional message derived from the unit's Goal
|
|
190
182
|
4. If tests fail after committing a unit's changes, diagnose and fix before committing the next unit
|
|
@@ -280,7 +280,7 @@ If artifact-backed mode is not clearly warranted, stay in direct mode.
|
|
|
280
280
|
|
|
281
281
|
### Phase 4: Run Targeted Research and Review
|
|
282
282
|
|
|
283
|
-
Launch the selected agents in parallel using the execution mode chosen in Step 3.3. If the current platform does not support parallel dispatch, run them sequentially instead.
|
|
283
|
+
Launch the selected agents in parallel using the execution mode chosen in Step 3.3. If the current platform does not support parallel dispatch, run them sequentially instead. An agent has returned only when its final report arrives (see the active harness profile's *Dispatch results and continuation* section): wait for every report before synthesizing, and do not dispatch the same research again while one is owed.
|
|
284
284
|
|
|
285
285
|
Prefer local repo and institutional evidence first. Use external research only when the gap cannot be closed responsibly from repo context or already-cited sources.
|
|
286
286
|
|
|
@@ -117,7 +117,7 @@ Add activated conditional personas:
|
|
|
117
117
|
|
|
118
118
|
### Dispatch
|
|
119
119
|
|
|
120
|
-
Dispatch all agents in **parallel** using the platform's task/agent tool (e.g., Agent tool in OpenCode, spawn in Codex).
|
|
120
|
+
Dispatch all agents in **parallel** using the platform's task/agent tool (e.g., Agent tool in OpenCode, spawn in Codex). Dispatch without a permission-mode override so the user's configured permission settings apply. Each agent receives the prompt built from the subagent template included below with these variables filled:
|
|
121
121
|
|
|
122
122
|
| Variable | Value |
|
|
123
123
|
|----------|-------|
|
|
@@ -129,13 +129,13 @@ Dispatch all agents in **parallel** using the platform's task/agent tool (e.g.,
|
|
|
129
129
|
|
|
130
130
|
Pass each agent the **full document** -- do not split into sections.
|
|
131
131
|
|
|
132
|
-
**Error handling:** If an agent
|
|
132
|
+
**Error handling:** An agent has returned only when its final report arrives (see the active harness profile's *Dispatch results and continuation* section), and waiting for a report is not a failure: do not dispatch the same persona again while its report is owed. If an agent's final report says it failed or was cancelled, or it times out, proceed with findings from agents that completed. Note the failed agent in the Coverage section. Do not block the entire review on a single agent failure.
|
|
133
133
|
|
|
134
134
|
**Dispatch limit:** Even at maximum (7 agents), use parallel dispatch. These are document reviewers with bounded scope reading a single document -- parallel is safe and fast.
|
|
135
135
|
|
|
136
136
|
## Phases 3-5: Synthesis, Presentation, and Next Action
|
|
137
137
|
|
|
138
|
-
After
|
|
138
|
+
After every dispatched agent's final report has arrived, read `references/synthesis-and-presentation.md` for the synthesis pipeline (validate, gate, dedup, promote, resolve contradictions, route by autofix class), fix application, finding presentation, and next-action menu. Do not load this file before agent dispatch completes.
|
|
139
139
|
|
|
140
140
|
---
|
|
141
141
|
|
|
@@ -29,18 +29,22 @@ Return: List the changed files and summarize the implementation.
|
|
|
29
29
|
- **Return** — the result format expected from the specialist
|
|
30
30
|
|
|
31
31
|
**Optional brief elements:**
|
|
32
|
-
- **Session reference** —
|
|
32
|
+
- **Session reference** — continue a prior specialist session instead of creating a new one, through the continuation call the active harness profile names, using the id recorded at dispatch (see Dispatch Results and Continuation)
|
|
33
33
|
- **Trigger context** — the command or workflow that initiated the dispatch
|
|
34
34
|
|
|
35
|
-
|
|
35
|
+
Use the active harness profile to determine which dispatch modes are available and how a dispatch returns. Run independent dispatches concurrently where the harness supports it; otherwise dispatch sequentially in dependency order.
|
|
36
36
|
|
|
37
|
-
##
|
|
37
|
+
## Dispatch Results and Continuation
|
|
38
38
|
|
|
39
|
-
|
|
39
|
+
How a dispatch returns depends on the harness. Some block until the specialist answers. Others return a launch handle at once and deliver the answer later as a report, and a report may not be final. The active harness profile's *Dispatch results and continuation* section says which applies, what a final report is, and which call continues a child. That section is the single source of truth; this skill states only the behavior that holds on every harness.
|
|
40
40
|
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
41
|
+
- **A launch handle is not a result.** A specialist has returned only when its final report arrives. A report that is not final is not a return: wait for the next one. A report that says the child failed or was cancelled is final.
|
|
42
|
+
- **Waiting is not a failure.** Never poll, sleep or dispatch the same work again while a report is owed, and never call a specialist "never returned" because only its launch handle has arrived. Every profile names a wait path: a dispatch that blocks, so there is nothing to wait for, or reports that wake the parent, so the parent may end the turn and let the next report start its next turn. The parent does not end the turn while reports are owed unless the profile says reports wake it. Where the profile names no wake-up for a mode, dispatch in the blocking mode.
|
|
43
|
+
- **Record the child id at dispatch**, against the task it was given. Follow-ups need it.
|
|
44
|
+
- **Continue through the profile.** To follow up a running or finished child, make the continuation call the active harness profile names, with the id recorded at dispatch and only the follow-up as the message; the child keeps its context. A fresh dispatch is a new child, not a continuation.
|
|
45
|
+
- **Fall back to a fresh dispatch** with a corrected brief only when the profile names no continuation call or no id was recorded.
|
|
46
|
+
- **A refused continuation is a failed follow-up.** When the runtime refuses a continuation call, report the refusal; the unit's earlier result stands, and do not retry the call. Make a fresh dispatch with a corrected brief only where the calling workflow's own rules allow a fresh dispatch for that unit. A workflow that forbids one, such as `ce:review`'s re-ask, keeps its own rule. Tool or guard text that suggests starting a new task does not override those rules.
|
|
47
|
+
- **A continuation call that errors is the same failed follow-up.** When the continuation call itself errors (a transport or tool error, not a refusal), report the failure; the earlier result stands, and do not retry the call or open a replacement child.
|
|
44
48
|
|
|
45
49
|
## Serial vs Parallel Dispatch
|
|
46
50
|
|
|
@@ -123,7 +127,7 @@ If writes landed in the wrong checkout, stop dependent dispatches, inspect both
|
|
|
123
127
|
|
|
124
128
|
After specialists complete, the orchestrator synthesizes results:
|
|
125
129
|
|
|
126
|
-
1. **Wait for all** — in a parallel batch, wait for every specialist
|
|
130
|
+
1. **Wait for all** — in a parallel batch, wait for every specialist's final report before acting on any result.
|
|
127
131
|
2. **Check for file collisions** — compare actual files modified by all specialists in the batch (not just declared files). If 2+ specialists modified the same file, only the last writer's version survives. If the workflow owns git operations, resolve by staging non-colliding files first, then re-running the affected units serially; otherwise, report the collision list to the caller.
|
|
128
132
|
3. **Review each diff** — verify changes match the unit's declared scope.
|
|
129
133
|
4. **Run targeted tests** — run the narrowest test command relevant to the changed files.
|
|
@@ -133,8 +137,8 @@ After specialists complete, the orchestrator synthesizes results:
|
|
|
133
137
|
|
|
134
138
|
- If a specialist returns an error or its output is incomplete, diagnose before dispatching dependent units.
|
|
135
139
|
- Do not dispatch dependent units on a broken tree.
|
|
136
|
-
- Retry a failed unit by
|
|
137
|
-
-
|
|
140
|
+
- Retry a failed unit by continuing the recorded specialist session through the continuation call the active harness profile names. Re-dispatch with a corrected brief only when the profile names no continuation call or no id was recorded. A refused continuation follows the refused-continuation rule above.
|
|
141
|
+
- While a report is owed, wait for it (see Dispatch Results and Continuation). Do not poll or sleep.
|
|
138
142
|
|
|
139
143
|
## Quick Reference
|
|
140
144
|
|
|
@@ -143,9 +147,9 @@ After specialists complete, the orchestrator synthesizes results:
|
|
|
143
147
|
| Units have dependencies | Serial foreground dispatch |
|
|
144
148
|
| Units share files | Serial foreground dispatch |
|
|
145
149
|
| Units are independent, no file overlap | Concurrent dispatch where supported; otherwise batched foreground dispatch |
|
|
146
|
-
|
|
|
147
|
-
|
|
|
148
|
-
| Specialist fails | Diagnose, correct the brief, then re-dispatch
|
|
150
|
+
| Long-running independent work | Concurrent dispatch where the profile supports it; each final report arrives on its own (no polling) |
|
|
151
|
+
| Concurrent dispatch unavailable | Serial or batched dispatch |
|
|
152
|
+
| Specialist fails | Diagnose, correct the brief, then continue the recorded session through the profile-named call; re-dispatch only when the profile names none or no id was recorded |
|
|
149
153
|
| File collision detected post-parallel | Stage non-colliding files (if workflow owns git ops), re-run colliding units serially |
|
|
150
154
|
| Write-capable dispatch | Include the expected root; require actual-root and changed-file attestation; independently verify both worktrees before acceptance |
|
|
151
155
|
|
|
@@ -153,8 +157,9 @@ After specialists complete, the orchestrator synthesizes results:
|
|
|
153
157
|
|
|
154
158
|
| Mistake | Fix |
|
|
155
159
|
|---|---|
|
|
156
|
-
| Polling or
|
|
160
|
+
| Polling, sleeping or re-dispatching while a report is owed | Wait for the final report; a launch handle is not a result and waiting is not a failure |
|
|
161
|
+
| Resuming through a guessed call or an unrecorded id | Record the child id at dispatch and continue through the call the active profile names |
|
|
157
162
|
| Parallel specialists staging or committing | Instruct specialists not to stage/commit; the current workflow owner handles git ops when applicable, otherwise synthesize file inventory and results for the caller or user |
|
|
158
163
|
| Dispatching dependent units without waiting | Always wait for prerequisites to complete and verify their output |
|
|
159
164
|
| Ignoring file overlap in parallel batches | Run the Parallel Safety Check before every parallel dispatch |
|
|
160
|
-
| Assuming
|
|
165
|
+
| Assuming a dispatch mode without checking the active profile | Use a dispatch mode only when the active harness profile declares it; otherwise dispatch serially |
|
|
@@ -195,11 +195,13 @@ Verdict meanings:
|
|
|
195
195
|
|
|
196
196
|
**Sequential fallback**: Platforms that do not support parallel dispatch should run agents sequentially. Dispatch cluster units first (they are higher-leverage), then individual items.
|
|
197
197
|
|
|
198
|
+
**Collecting results**: an agent has completed only when its final report arrives; a launch handle is not a result. The active harness profile's *Dispatch results and continuation* section defines the final report. Wait for every report in a batch before the next batch or step 6, and never dispatch the same unit again while its report is owed.
|
|
199
|
+
|
|
198
200
|
Fixes can occasionally expand beyond their referenced file (e.g., renaming a method updates callers elsewhere). This is rare but can cause parallel agents to collide. The verification step (step 8) catches this -- if re-fetching shows unresolved threads or if the commit reveals inconsistent changes, re-run the affected agents sequentially.
|
|
199
201
|
|
|
200
202
|
### 6. Commit and Push
|
|
201
203
|
|
|
202
|
-
After
|
|
204
|
+
After every agent's final report has arrived, check whether any files were actually changed. If all verdicts are `replied`, `not-addressing`, or `needs-human` (no code changes), skip this step entirely and proceed to step 7.
|
|
203
205
|
|
|
204
206
|
If there are file changes:
|
|
205
207
|
|
|
@@ -372,7 +374,7 @@ This fetches thread IDs and their first comment IDs (minimal fields, no bodies)
|
|
|
372
374
|
|
|
373
375
|
### 2. Fix, Reply, Resolve
|
|
374
376
|
|
|
375
|
-
Spawn a single `systematic:workflow:pr-comment-resolver` agent for the thread. Then follow the same commit -> push -> reply -> resolve flow as Full Mode steps 6-7.
|
|
377
|
+
Spawn a single `systematic:workflow:pr-comment-resolver` agent for the thread and wait for its final report. Then follow the same commit -> push -> reply -> resolve flow as Full Mode steps 6-7.
|
|
376
378
|
|
|
377
379
|
---
|
|
378
380
|
|
package/skills/slfg/SKILL.md
CHANGED
|
@@ -22,10 +22,10 @@ Swarm-enabled LFG. Run these steps in order, parallelizing where indicated. Do n
|
|
|
22
22
|
|
|
23
23
|
After work completes, launch steps 5 and 6 as **parallel swarm agents** (both only need code to be written):
|
|
24
24
|
|
|
25
|
-
5. `/ce:review mode:report-only` — spawn as
|
|
26
|
-
6. `/systematic:test-browser` — spawn as
|
|
25
|
+
5. `/ce:review mode:report-only` — spawn as a parallel Task agent
|
|
26
|
+
6. `/systematic:test-browser` — spawn as a parallel Task agent
|
|
27
27
|
|
|
28
|
-
Wait for both
|
|
28
|
+
Wait for both final reports before continuing. A launch handle is not a report: do not re-dispatch while a report is owed (see the active harness profile's *Dispatch results and continuation* section).
|
|
29
29
|
|
|
30
30
|
## Autofix Phase
|
|
31
31
|
|
package/skills/todos/SKILL.md
CHANGED
|
@@ -202,7 +202,7 @@ Create a task list grouped by type (e.g., `todowrite` in OpenCode, `update_plan`
|
|
|
202
202
|
|
|
203
203
|
### 3. Implement (PARALLEL)
|
|
204
204
|
|
|
205
|
-
Spawn a `systematic:workflow:pr-comment-resolver` agent per item. Prefer parallel; fall back to sequential respecting dependency order.
|
|
205
|
+
Spawn a `systematic:workflow:pr-comment-resolver` agent per item. Prefer parallel; fall back to sequential respecting dependency order. An agent has returned only when its final report arrives (see the active harness profile's *Dispatch results and continuation* section): wait for every report before committing, and never dispatch the same item again while its report is owed.
|
|
206
206
|
|
|
207
207
|
**Batching:** 1-4 items: direct parallel returns. 5+ items: batches of 4, each returning only a short status summary (todo handled, files changed, tests run/skipped, blockers).
|
|
208
208
|
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
| Capability | Mechanism | Status | Fallback |
|
|
4
4
|
|---|---|---|---|
|
|
5
|
-
| Subagent delegation | Name-based subagent dispatch; plugin agents ship in `agents/`; `context: fork` for skill-scoped forks | supported | Dispatch in the foreground, serially or in small batches |
|
|
5
|
+
| Subagent delegation | Name-based subagent dispatch; plugin agents ship in `agents/`; `context: fork` for skill-scoped forks; `SendMessage` continues a subagent by agent id | supported | Dispatch in the foreground, serially or in small batches |
|
|
6
6
|
| Blocking user interaction | `AskUserQuestion` tool | supported | Present numbered options in chat and wait |
|
|
7
7
|
| Task tracking | `TaskCreate` / `TaskGet` / `TaskList` / `TaskUpdate` (`TodoWrite` is deprecated and disabled by default) | supported | Maintain a visible task list in responses |
|
|
8
8
|
| Skill loading | Native Skill tool with `SKILL.md` discovery (`~/.claude/skills/`, `.claude/skills/`, plugin `skills/`); Systematic ships no `systematic_skill` tool on Claude Code | supported | Read the skill instructions listed by the active harness |
|
|
@@ -18,6 +18,14 @@ Behavioral enforcement on Claude Code rides a plugin output style (force-for-plu
|
|
|
18
18
|
Use the systematic-implementer subagent to implement the auth module and return the changed files.
|
|
19
19
|
```
|
|
20
20
|
|
|
21
|
+
Omit the `mode` parameter when dispatching subagents so the user's configured permission settings apply. Do not pass `mode: "auto"`: it overrides user-level settings like `bypassPermissions`.
|
|
22
|
+
|
|
23
|
+
### Dispatch results and continuation
|
|
24
|
+
|
|
25
|
+
Each subagent call starts a new instance, and the agent id comes with the dispatch result. Record it at dispatch, against the task it was given. Continue that subagent with `SendMessage` with `to` set to that agent id and the follow-up as the message: a finished subagent resumes in the background, and its reply arrives later as a report. The built-in Explore and Plan agents are one-shot and return no agent id, so they cannot be continued. Dispatching the same subagent by name again starts a new one, not a continuation.
|
|
26
|
+
|
|
27
|
+
**Wait path.** A subagent that Claude spawns from the main conversation starts in the background by default, and its report reaches the parent as a completion notification in a later turn, so the parent may end its turn. A `SendMessage` continuation resumes in the background the same way. In `claude -p` the run stays open for background subagents, up to a 10-minute idle cap, and drops work still unfinished then.
|
|
28
|
+
|
|
21
29
|
### Blocking user interaction
|
|
22
30
|
|
|
23
31
|
```typescript
|
|
@@ -4,7 +4,7 @@ Evidence registry: see [`HARNESSES.md`](../../../HARNESSES.md).
|
|
|
4
4
|
|
|
5
5
|
| Capability | Mechanism | Status | Fallback |
|
|
6
6
|
|---|---|---|---|
|
|
7
|
-
| Subagent delegation | `task()` tool; `subagent_type` selects a specialist, `task_id`
|
|
7
|
+
| Subagent delegation | `task()` tool; `subagent_type` selects a specialist, `task_id` continues a running or finished child session | supported; parallel and background dispatch may be available | Dispatch in the foreground, serially or in small batches |
|
|
8
8
|
| Blocking user interaction | `question` tool | supported | Present numbered options in chat and wait |
|
|
9
9
|
| Task tracking | `todowrite` | supported | Maintain a visible task list in responses |
|
|
10
10
|
| Skill loading | `systematic_skill` for bundled skills; `skill` tool for non-Systematic skills | supported | Read the skill instructions listed by the active harness |
|
|
@@ -29,7 +29,7 @@ task({
|
|
|
29
29
|
background: true,
|
|
30
30
|
})
|
|
31
31
|
|
|
32
|
-
//
|
|
32
|
+
// Continue a prior specialist session (see Dispatch results and continuation):
|
|
33
33
|
task({ subagent_type: "systematic-implementer", task_id: "<prior-session-id>", description: "Resume the implementation task", prompt: "…" })
|
|
34
34
|
```
|
|
35
35
|
|
|
@@ -43,6 +43,12 @@ package actually ships, so they work for every reader. A host may provide
|
|
|
43
43
|
additional agents through the user's own configuration; those are available at
|
|
44
44
|
runtime but must not appear in bundled examples.
|
|
45
45
|
|
|
46
|
+
### Dispatch results and continuation
|
|
47
|
+
|
|
48
|
+
A foreground `task` returns the child's answer in the call result, inside a `<task id="…" state="…">` block; the block's body is the child's answer. Record that `id` at dispatch, against the task it was given. To continue the same child, call `task` again with it as `task_id`, plus `subagent_type`, `description` and `prompt` (the follow-up only; the child keeps its context). A `background: true` dispatch returns the same block with `state="running"`, which is not final.
|
|
49
|
+
|
|
50
|
+
**Wait path.** A foreground `task` (the default) blocks until the child answers, so there is nothing to wait for. `background: true` works only with the host's experimental background-subagents flag, and the call fails without it; where it is on, the final result arrives as a synthetic `<task>` message that starts a new parent turn, so the parent may end its turn. Where the flag is off or unknown, dispatch in the foreground.
|
|
51
|
+
|
|
46
52
|
### Blocking user interaction
|
|
47
53
|
|
|
48
54
|
```typescript
|
|
@@ -4,7 +4,7 @@ Evidence registry: see [`HARNESSES.md`](../../../HARNESSES.md).
|
|
|
4
4
|
|
|
5
5
|
| Capability | Mechanism | Status | Fallback |
|
|
6
6
|
|---|---|---|---|
|
|
7
|
-
| Subagent delegation | `subagent` tool; `agent` selects a specialist, `sessionID`
|
|
7
|
+
| Subagent delegation | `subagent` tool; `agent` selects a specialist, `sessionID` continues a running or finished child; before 2.3.0, `background: true` runs it asynchronously | supported; from 2.3.0 every dispatch returns a handle and the answer arrives later as a `<subagent>` message; before that, foreground by default | Dispatch serially or in small batches |
|
|
8
8
|
| Blocking user interaction | `question` tool | supported | Present numbered options in chat and wait |
|
|
9
9
|
| Task tracking | `todowrite` tool | conditional: only offered when the host's experimental `todo` option is on | Maintain a visible task list in responses |
|
|
10
10
|
| Skill loading | `systematic_skill` for bundled skills, with arguments; `skill` tool (by `id`) for non-Systematic skills | supported | Read the skill instructions listed by the active harness |
|
|
@@ -21,7 +21,7 @@ subagent({
|
|
|
21
21
|
prompt: "Implement the auth module and return the changed files.",
|
|
22
22
|
})
|
|
23
23
|
|
|
24
|
-
// Background dispatch (
|
|
24
|
+
// Background dispatch, before 2.3.0 (2.3.0 and later always return a handle at once):
|
|
25
25
|
subagent({
|
|
26
26
|
agent: "repo-research-analyst",
|
|
27
27
|
description: "Map fixture patterns",
|
|
@@ -29,7 +29,7 @@ subagent({
|
|
|
29
29
|
background: true,
|
|
30
30
|
})
|
|
31
31
|
|
|
32
|
-
//
|
|
32
|
+
// Continue a prior specialist session (see Dispatch results and continuation):
|
|
33
33
|
subagent({ agent: "systematic-implementer", sessionID: "<prior-session-id>", description: "Resume the implementation task", prompt: "…" })
|
|
34
34
|
```
|
|
35
35
|
|
|
@@ -41,10 +41,16 @@ uses the canonical `systematic:<category>:<name>` form instead, which the
|
|
|
41
41
|
content-integrity gate validates against real agent files. Leave `model` unset
|
|
42
42
|
unless the user names a model.
|
|
43
43
|
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
44
|
+
### Dispatch results and continuation
|
|
45
|
+
|
|
46
|
+
From 2.3.0, `subagent` returns immediately with a handle, not the child's answer: a `sessionID` and `status: "running"`. Record the `sessionID` at dispatch, against the task it was given. The answer arrives later as a `<subagent sessionID="…" state="…">` message that starts a new parent turn, and the message body is the child's answer. Do not poll, sleep or dispatch the same work again while the child runs.
|
|
47
|
+
|
|
48
|
+
- `state="completed"` ends that round of work. `error` and `cancelled` are final failures. `state="running"` means the child went idle with background work still going: it is not final, so wait for the next `<subagent>` message.
|
|
49
|
+
- To follow up a running or finished child, call `subagent` again with its `sessionID`, plus `agent` (the specialist it was dispatched as), `description` and `prompt` (the follow-up only; the child keeps its context). The call returns a handle again and the reply arrives as another `<subagent>` message. The `sessionID` must name a child of the current session.
|
|
50
|
+
- A host or plugin may refuse a `sessionID` follow-up with an error. The refusal is final: do not retry the call, and error text that suggests starting a new task is not a reason to dispatch a new child. The calling workflow's own rules say what a refused follow-up costs.
|
|
51
|
+
- Before 2.3.0, a foreground dispatch returned the `<subagent sessionID="…" state="completed">` block inline, `background: true` returned a handle, and a follow-up behaved the same way. 2.3.0 always returns a handle and has no `background` input.
|
|
52
|
+
|
|
53
|
+
**Wait path.** From 2.3.0 a report wakes the parent: after a dispatch the parent may end its turn, and each `<subagent>` message starts a new parent turn. Before 2.3.0 a foreground dispatch blocks until the child answers, so there is nothing to wait for.
|
|
48
54
|
|
|
49
55
|
### Blocking user interaction
|
|
50
56
|
|
|
@@ -4,7 +4,7 @@ Evidence registry: see [`HARNESSES.md`](../../../HARNESSES.md).
|
|
|
4
4
|
|
|
5
5
|
| Capability | Mechanism | Status | Fallback |
|
|
6
6
|
|---|---|---|---|
|
|
7
|
-
| Subagent delegation | Bounded built-in delegate via `systematic_delegate({agent, task})
|
|
7
|
+
| Subagent delegation | Bounded built-in delegate via `systematic_delegate({agent, task})`, with no continuation; optional mature delegation via [pi-subagents](https://github.com/tintinweb/pi-subagents): installed package personas, opt-in export for overlays, `Agent` with `resume` continues a child | built-in: degraded (sequential only); pi-subagents path: outside Systematic's bounded-delegate guarantees | Dispatch sequentially in dependency order or do the work inline |
|
|
8
8
|
| Blocking user interaction | No native blocking tool | degraded | Present numbered options in chat and wait |
|
|
9
9
|
| Task tracking | No native task-tracking mechanism | unavailable | Maintain a visible task list in responses |
|
|
10
10
|
| Skill loading | `systematic_skill` tool or Pi-native skill activation | supported | Read the skill instructions listed by the active harness |
|
|
@@ -25,14 +25,18 @@ systematic_delegate({
|
|
|
25
25
|
|
|
26
26
|
`systematic_delegate` is sequential, capped at 20 turns, depth-1, and spawns its child with `noExtensions: true`. The `noExtensions` guarantee bounds `systematic_delegate`'s own recursion — it does not bound end-to-end delegation depth across a combined pi-subagents + Systematic path.
|
|
27
27
|
|
|
28
|
+
### Dispatch results and continuation
|
|
29
|
+
|
|
30
|
+
`systematic_delegate` runs the child to completion, returns its answer in the call result and disposes the child's session, so `systematic_delegate` has no continuation. On the pi-subagents path, `Agent` returns an agent id at once; continue a child by calling `Agent` with `resume` set to that id and the follow-up as `prompt`.
|
|
31
|
+
|
|
32
|
+
**Wait path.** `systematic_delegate` is foreground: it blocks until the child answers, so there is nothing to wait for. A pi-subagents `Agent` call runs in the background by default, and its completion notification reaches an idle parent as a new turn, so the parent may end its turn; `run_in_background: false` blocks and returns the result inline instead. Both modes apply to `resume`.
|
|
33
|
+
|
|
28
34
|
### Optional: pi-subagents delegation
|
|
29
35
|
|
|
30
36
|
[pi-subagents](https://github.com/tintinweb/pi-subagents) (parallel/multi-model delegation) 0.22 or newer loads 29 curated personas from the installed package as `systematic-<name>` agent types with plain defaults; a project-scope install only after the project is trusted, and its first session may omit them from the `Agent` description, though dispatch works. Any other type falls back to `general-purpose` with an "Unknown agent type" note: the persona did not run. Export is needed only to apply `systematic.json` overlays; a local file outranks the packaged one. Nothing is written at extension load.
|
|
31
37
|
|
|
32
38
|
`disabled_agents` and `agents.<name>.disable` do not reach packaged personas. Turn one off with `/agents → Disable`, or all with `packageAgents: false` in `subagents.json`.
|
|
33
39
|
|
|
34
|
-
The `Agent` tool runs in the background by default. Pass `run_in_background: false` to wait for the result.
|
|
35
|
-
|
|
36
40
|
Tested against pi-subagents 0.22.0 on Pi 1.3.0. Versions outside the tested range are unsupported but nonfatal.
|
|
37
41
|
|
|
38
42
|
Exact CLI form: `systematic pi-subagents <preview|export|refresh|cleanup> --scope project|global`. `--scope` is optional and defaults to `project`.
|