@fro.bot/systematic 3.4.1 → 3.5.0

package/dist/schemas/systematic-config.schema.json

@@ -26,8 +26,11 @@
     "workflow_guard": {
       "$ref": "#/definitions/__schema57"
     },
-    "skills_as_commands": {
+    "pi_subagents": {
       "$ref": "#/definitions/__schema61"
+    },
+    "skills_as_commands": {
+      "$ref": "#/definitions/__schema72"
     }
   },
   "additionalProperties": false,
@@ -1368,16 +1371,178 @@
       "type": "boolean"
     },
     "__schema61": {
+      "default": {
+        "categories": {},
+        "agents": {}
+      },
+      "description": "Pi-native pi-subagents export field overlays (thinking, max_turns, tools, skills). Category values apply first; per-agent values override. No model field — model stays in the categories/agents overlay.",
+      "examples": [
+        {
+          "categories": {
+            "research": {
+              "thinking": "high"
+            }
+          },
+          "agents": {
+            "repo-research-analyst": {
+              "max_turns": 10
+            }
+          }
+        }
+      ],
+      "allOf": [
+        {
+          "$ref": "#/definitions/__schema62"
+        }
+      ]
+    },
+    "__schema62": {
+      "type": "object",
+      "properties": {
+        "categories": {
+          "default": {},
+          "description": "Per-category pi-subagents export overlays keyed by category name",
+          "examples": [
+            {
+              "research": {
+                "thinking": "high"
+              }
+            },
+            {}
+          ],
+          "allOf": [
+            {
+              "$ref": "#/definitions/__schema63"
+            }
+          ]
+        },
+        "agents": {
+          "default": {},
+          "description": "Per-agent pi-subagents export overlays keyed by bundled agent name",
+          "examples": [
+            {
+              "repo-research-analyst": {
+                "max_turns": 10
+              }
+            },
+            {}
+          ],
+          "allOf": [
+            {
+              "$ref": "#/definitions/__schema71"
+            }
+          ]
+        }
+      },
+      "additionalProperties": false
+    },
+    "__schema63": {
+      "type": "object",
+      "propertyNames": {
+        "type": "string"
+      },
+      "additionalProperties": {
+        "description": "Per-category pi-subagents export overlay (Pi-native fields only; no model)",
+        "examples": [
+          {
+            "thinking": "medium"
+          }
+        ],
+        "allOf": [
+          {
+            "$ref": "#/definitions/__schema70"
+          }
+        ]
+      }
+    },
+    "__schema64": {
+      "type": "string",
+      "enum": ["off", "minimal", "low", "medium", "high", "xhigh", "max"],
+      "description": "pi-subagents reasoning effort level for exported persona frontmatter",
+      "examples": ["off", "medium", "high"],
+      "trust": "project-or-higher"
+    },
+    "__schema65": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991,
+      "description": "pi-subagents maximum turns for a delegated persona (0 = unlimited)",
+      "examples": [0, 10, 25],
+      "trust": "any"
+    },
+    "__schema66": {
+      "type": "string",
+      "minLength": 1,
+      "description": "pi-subagents comma-selector tool string (built-ins, */all/none, or extension selectors)",
+      "examples": ["*", "read,grep,glob", "none"],
+      "trust": "project-or-higher"
+    },
+    "__schema67": {
+      "anyOf": [
+        {
+          "$ref": "#/definitions/__schema68"
+        },
+        {
+          "$ref": "#/definitions/__schema69"
+        }
+      ],
+      "description": "pi-subagents skills selector: true (all) or a comma-separated list of skill names",
+      "examples": [true, "ce:plan,ce:review"],
+      "trust": "project-or-higher"
+    },
+    "__schema68": {
+      "type": "boolean",
+      "const": true
+    },
+    "__schema69": {
+      "type": "string",
+      "minLength": 1
+    },
+    "__schema70": {
+      "type": "object",
+      "properties": {
+        "thinking": {
+          "$ref": "#/definitions/__schema64"
+        },
+        "max_turns": {
+          "$ref": "#/definitions/__schema65"
+        },
+        "tools": {
+          "$ref": "#/definitions/__schema66"
+        },
+        "skills": {
+          "$ref": "#/definitions/__schema67"
+        }
+      },
+      "additionalProperties": false,
+      "description": "Per-agent pi-subagents export overlay (Pi-native fields only; no model)",
+      "examples": [
+        {
+          "thinking": "high",
+          "max_turns": 10
+        }
+      ]
+    },
+    "__schema71": {
+      "type": "object",
+      "propertyNames": {
+        "type": "string"
+      },
+      "additionalProperties": {
+        "$ref": "#/definitions/__schema70"
+      }
+    },
+    "__schema72": {
       "default": true,
       "description": "Register skills discovered from user/project skill directories (OpenCode config and other agent-harness-standard locations) as slash commands. Default true.",
       "examples": [true, false],
       "allOf": [
         {
-          "$ref": "#/definitions/__schema62"
+          "$ref": "#/definitions/__schema73"
         }
       ]
     },
-    "__schema62": {
+    "__schema73": {
       "type": "boolean"
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fro.bot/systematic",
-  "version": "3.4.1",
+  "version": "3.5.0",
   "description": "Compound-engineering loops for OpenCode, Pi, and Claude Code",
   "type": "module",
   "homepage": "https://fro.bot/systematic",
@@ -92,9 +92,10 @@
   "devDependencies": {
     "@biomejs/biome": "2.5.5",
     "@earendil-works/pi-coding-agent": "0.80.10",
-    "@opencode-ai/plugin": "1.18.5",
-    "@opencode-ai/sdk": "1.18.5",
+    "@opencode-ai/plugin": "1.18.6",
+    "@opencode-ai/sdk": "1.18.6",
     "@semantic-release/exec": "7.1.0",
+    "@tintinweb/pi-subagents": "0.14.3",
     "@types/bun": "latest",
     "@types/js-yaml": "4.0.9",
     "@types/node": "24.13.3",

package/skills/using-systematic/references/pi-profile.md

@@ -4,14 +4,14 @@ Evidence registry: see [`HARNESSES.md`](../../../HARNESSES.md).
 
 | Capability | Mechanism | Status | Fallback |
 |---|---|---|---|
-| Subagent delegation | `systematic_delegate({agent, task})` with bundled personas | degraded; execution is sequential only | Dispatch sequentially in dependency order or do the work inline |
+| Subagent delegation | Bounded built-in delegate via `systematic_delegate({agent, task})`; optional mature delegation via [pi-subagents](https://github.com/tintinweb/pi-subagents) through opt-in persona export | built-in: degraded (sequential only); pi-subagents path: outside Systematic's bounded-delegate guarantees | Dispatch sequentially in dependency order or do the work inline |
 | Blocking user interaction | No native blocking tool | degraded | Present numbered options in chat and wait |
 | Task tracking | No native task-tracking mechanism | unavailable | Maintain a visible task list in responses |
 | Skill loading | `systematic_skill` tool or Pi-native skill activation | supported | Read the skill instructions listed by the active harness |
 
 ## Invocation examples
 
-### Subagent delegation
+### Subagent delegation (built-in)
 
 ```typescript
 systematic_delegate({
@@ -20,6 +20,32 @@ systematic_delegate({
 })
 ```
 
+`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.
+
+### Optional: pi-subagents delegation
+
+Export Systematic personas for use with [pi-subagents](https://github.com/tintinweb/pi-subagents) (parallel/multi-model delegation). All writes are opt-in; nothing is exported at extension load.
+
+Tested against pi-subagents v0.14.3 (verified contract as of July 29, 2026). Versions outside the tested range are unsupported but nonfatal.
+
+Exact CLI form: `systematic pi-subagents <preview|export|refresh|cleanup> --scope project|global`. `--scope` is optional and defaults to `project`.
+
+```bash
+systematic pi-subagents preview [--scope project|global]
+systematic pi-subagents export  [--scope project|global]
+systematic pi-subagents refresh [--scope project|global]
+systematic pi-subagents cleanup [--scope project|global]
+```
+
+- `project` (default) targets `<cwd>/.pi/agents/`.
+- `global` targets `$PI_CODING_AGENT_DIR/agents/`, or `~/.pi/agent/agents/` if `$PI_CODING_AGENT_DIR` is unset.
+
+The pi-subagents delegation path is **outside Systematic's bounded-delegate guarantees** and governed by pi-subagents' own configuration. `systematic_delegate` remains the bounded default.
+
+`export`/`refresh`/`cleanup` hold an exclusive per-root mutation lock and fail closed if any path component between the selected scope's anchor and the agents directory is a symlink or not a directory. A manifest (`.systematic-personas.json`) tracks ownership by filename and content hash; cleanup and stale-file removal only delete a file whose on-disk content still matches its recorded hash, refusing otherwise. Manifest hashes are drift evidence, not a cryptographic authenticity guarantee.
+
+Systematic's own config (`systematic.json`/`.jsonc`) is the durable source of truth for exported personas; the generated files and their manifest are a disposable projection that `export`/`refresh`/`cleanup` regenerate or remove, and `refresh` intentionally overwrites manifest-owned generated files that diverge from current config — run `preview` first to see what would change. See the [pi-subagents pairing guide](https://fro.bot/systematic/guides/pi-subagents/) for the config precedence, trust boundaries, and a canonical example.
+
 ### Blocking user interaction
 
 ```text