@fro.bot/systematic 2.30.1 → 2.31.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fro.bot/systematic",
-  "version": "2.30.1",
+  "version": "2.31.1",
   "description": "Structured engineering workflows for OpenCode",
   "type": "module",
   "homepage": "https://fro.bot/systematic",
@@ -66,18 +66,18 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.16",
-    "@opencode-ai/plugin": "1.15.13",
-    "@opencode-ai/sdk": "1.15.13",
+    "@opencode-ai/plugin": "1.17.3",
+    "@opencode-ai/sdk": "1.17.3",
     "@semantic-release/exec": "7.1.0",
     "@types/bun": "latest",
     "@types/js-yaml": "4.0.9",
-    "@types/node": "24.13.0",
+    "@types/node": "24.13.2",
     "ajv": "8.20.0",
     "ajv-formats": "3.0.1",
     "conventional-changelog-conventionalcommits": "9.3.1",
     "markdownlint-cli": "0.48.0",
     "rimraf": "6.1.3",
-    "semantic-release": "25.0.3",
+    "semantic-release": "25.0.5",
     "semantic-release-export-data": "1.2.0",
     "typescript": "6.0.3"
   },

package/skills/ce-compound-refresh/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ce:compound-refresh
 description: Refresh stale or drifting learnings and pattern docs in docs/solutions/ by reviewing, updating, consolidating, replacing, or deleting them against the current codebase. Use after refactors, migrations, dependency upgrades, or when a retrieved learning feels outdated or wrong. Also use when reviewing docs/solutions/ for accuracy, when a recently solved problem contradicts an existing learning, when pattern docs no longer reflect current code, or when multiple docs seem to cover the same topic and might benefit from consolidation.
+argument-hint: "[mode:autofix] [optional: category, module, or keyword scope]"
 disable-model-invocation: true
 ---
 

package/skills/orchestrating-subagents/SKILL.md

@@ -44,11 +44,11 @@ task({
 })
 ```
 
-**When background is available:** OpenCode exposes `task_status` in the tool list and the `task()` tool description includes background mode instructions. This requires `OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true` or the umbrella `OPENCODE_EXPERIMENTAL=true` flag.
+**When background is available:** `OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true` (or the umbrella `OPENCODE_EXPERIMENTAL=true`) must be set. When enabled, `background: true` runs the subagent asynchronously. OpenCode automatically injects the result into the parent session as a synthetic message when the subagent completes. You are notified; you do not poll.
 
-**When background is unavailable:** `task_status` is not registered. Passing `background: true` returns an error. Fall back to foreground dispatch — dispatch subagents serially or in small foreground batches instead.
+**When background is unavailable:** Passing `background: true` returns an error. Fall back to foreground dispatch — dispatch subagents serially or in small foreground batches instead.
 
-**Check before assuming:** If you see `task_status` in your available tools, background dispatch is enabled. If you do not see it, use foreground dispatch only.
+**Check before assuming:** Rely on whether `background: true` is accepted (i.e., the env flag is set). If it returns an error, use foreground dispatch only.
 
 ## Serial vs Parallel Dispatch
 
@@ -119,7 +119,7 @@ After subagents complete, the orchestrator synthesizes results:
 - If a subagent returns an error or its output is incomplete, diagnose before dispatching dependent units.
 - Do not dispatch dependent units on a broken tree.
 - Retry a failed unit by dispatching a new `task()` call with a corrected prompt, or resume the prior session with `task_id`.
-- For background tasks (when available): use `task_status` to poll or wait for terminal state before retrying.
+- For background tasks (when available): wait for the automatic completion notification (the result is injected into the parent session). Do not poll or sleep. Retry by dispatching a new `task()` with a corrected prompt, or resume with `task_id`.
 
 ## Quick Reference
 
@@ -128,7 +128,7 @@ After subagents complete, the orchestrator synthesizes results:
 | Units have dependencies | Serial foreground dispatch |
 | Units share files | Serial foreground dispatch |
 | Units are independent, no file overlap | Parallel foreground dispatch |
-| Background available + long-running work | Parallel background dispatch with `task_status` |
+| Background available + long-running work | Parallel background dispatch; results are pushed back to the parent on completion (no polling) |
 | Background unavailable | Foreground only — serial or batched |
 | Subagent fails | Diagnose, fix prompt, retry with new `task()` or resume with `task_id` |
 | File collision detected post-parallel | Stage non-colliding files (if workflow owns git ops), re-run colliding units serially |
@@ -137,8 +137,8 @@ After subagents complete, the orchestrator synthesizes results:
 
 | Mistake | Fix |
 |---|---|
-| Assuming `task_status` is always available | Check tool list first; fall back to foreground if absent |
+| Polling or sleeping to wait for a background subagent | Background results are pushed into the parent session automatically; never poll or sleep |
 | Parallel subagents staging or committing | Instruct subagents not to stage/commit; the current workflow owner handles git ops when applicable, otherwise synthesize file inventory and results for the caller or user |
 | Dispatching dependent units without waiting | Always wait for prerequisites to complete and verify their output |
 | Ignoring file overlap in parallel batches | Run the Parallel Safety Check before every parallel dispatch |
-| Using `background: true` without checking the flag | Only use when `task_status` appears in available tools |
+| Using `background: true` without the experimental flag enabled | Only use background when `OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true`; otherwise dispatch foreground |

package/skills/writing-systematic-skills/references/foundation-conventions.md

@@ -6,21 +6,21 @@ This reference expands the Systematic-specific rules from `SKILL.md`. The mechan
 
 Systematic skill frontmatter mirrors what the runtime loader actually reads. Do not invent fields for documentation structure. If the loader does not consume the field, put the information in the body.
 
-| Field | Required | When To Use | Example |
-|---|---:|---|---|
-| `name` | Yes | Every skill. Use the unprefixed skill identifier unless another namespace is intentional. | `name: writing-systematic-skills` |
-| `description` | Yes | Trigger-oriented discovery text. Third person. Prefer `Use when...`. | `description: Use when fixing bundled skill frontmatter failures...` |
-| `argument-hint` | No | The skill accepts meaningful invocation arguments. | `argument-hint: "[path/to/document.md]"` |
-| `disable-model-invocation` | No | Dispatcher or routing skills that should not be directly model-invoked. | `disable-model-invocation: true` |
-| `allowed-tools` | No | The skill needs an explicit tool allowlist. | `allowed-tools: Bash, Read` |
-| `license` | No | Licensing metadata matters for distribution. | `license: MIT` |
-| `compatibility` | No | A platform or version caveat is real and useful. | `compatibility: OpenCode` |
-| `metadata` | No | String-only metadata map. Keep it boring. | `metadata: { owner: systematic }` |
-| `user-invocable` | No | Direct user invocation should be explicitly advertised or suppressed. | `user-invocable: false` |
-| `agent` | No | A loader-supported companion agent is required. | `agent: general` |
-| `model` | No | A skill-level model choice is justified for *skill execution* (not bundled agents — see below). | `model: anthropic/claude-haiku-4-5` |
-| `context` | No | Forked execution is required. `fork` derives subtask behavior at runtime. | `context: fork` |
-| `subtask` | No | Explicit forked-subtask dispatch marker. | `subtask: true` |
+| Field | Required | When To Use | Enforcement | Example |
+|---|---:|---|---|---|
+| `name` | Yes | Every skill. Use the unprefixed skill identifier unless another namespace is intentional. | Read + enforced (loader rejects missing/null) | `name: writing-systematic-skills` |
+| `description` | Yes | Trigger-oriented discovery text. Third person. Prefer `Use when...`. | Read + enforced (loader rejects missing/null) | `description: Use when fixing bundled skill frontmatter failures...` |
+| `argument-hint` | No | The skill accepts meaningful invocation arguments. | Read + surfaced to callers | `argument-hint: "[path/to/document.md]"` |
+| `disable-model-invocation` | No | Dispatcher or routing skills that should not be directly model-invoked. | Read + enforced (loader acts on it) | `disable-model-invocation: true` |
+| `allowed-tools` | No | The skill needs an explicit tool allowlist. | **Read but not enforced.** `src/lib/skills.ts` parses it into `SkillFrontmatter.allowedTools` and passes it through, but no permission gate in `src/lib` acts on it. OpenCode treats it as metadata, not enforced permissions. Do not rely on this field to restrict tool access. | `allowed-tools: Bash, Read` |
+| `license` | No | Licensing metadata matters for distribution. | Read, passed through as metadata | `license: MIT` |
+| `compatibility` | No | A platform or version caveat is real and useful. | Read, passed through as metadata | `compatibility: OpenCode` |
+| `metadata` | No | String-only metadata map. Keep it boring. | Read, passed through as metadata | `metadata: { owner: systematic }` |
+| `user-invocable` | No | Direct user invocation should be explicitly advertised or suppressed. | Read + surfaced to callers | `user-invocable: false` |
+| `agent` | No | A loader-supported companion agent is required. | Read + enforced (loader acts on it) | `agent: general` |
+| `model` | No | A skill-level model choice is justified for *skill execution* (not bundled agents -- see below). | Read + enforced (loader acts on it; banned in bundled agent markdown) | `model: anthropic/claude-haiku-4-5` |
+| `context` | No | Forked execution is required. `fork` derives subtask behavior at runtime. | Read + enforced (runtime-recognized) | `context: fork` |
+| `subtask` | No | Explicit forked-subtask dispatch marker. | Read + enforced (runtime-recognized) | `subtask: true` |
 
 ### Required Fields