@fro.bot/systematic 2.27.0 → 2.28.0

package/dist/cli.js

@@ -6,7 +6,7 @@ import {
   findCommandsInDir,
   findSkillsInDir,
   getConfigPaths
-} from "./index-3q3ns1xh.js";
+} from "./index-ybqr13k7.js";
 
 // src/cli.ts
 import fs from "fs";

package/dist/{index-3q3ns1xh.js → index-ybqr13k7.js}

@@ -15839,6 +15839,7 @@ var BUNDLED_SKILL_NAMES = [
   "git-worktree",
   "lfg",
   "onboarding",
+  "orchestrating-subagents",
   "orchestrating-swarms",
   "proof",
   "rclone",

package/dist/index.js

@@ -13,7 +13,7 @@ import {
   loadConfig,
   loadConfigWithSources,
   parseFrontmatter
-} from "./index-3q3ns1xh.js";
+} from "./index-ybqr13k7.js";
 
 // src/index.ts
 import fs5 from "fs";

package/dist/lib/bundled-names.d.ts

@@ -1,5 +1,5 @@
 export declare const BUNDLED_AGENT_NAMES: readonly ["adversarial-document-reviewer", "adversarial-reviewer", "agent-native-reviewer", "ankane-readme-writer", "api-contract-reviewer", "architecture-strategist", "best-practices-researcher", "bug-reproduction-validator", "cli-agent-readiness-reviewer", "cli-readiness-reviewer", "code-simplicity-reviewer", "coherence-reviewer", "correctness-reviewer", "data-integrity-guardian", "data-migration-expert", "data-migrations-reviewer", "deployment-verification-agent", "design-implementation-reviewer", "design-iterator", "design-lens-reviewer", "dhh-rails-reviewer", "feasibility-reviewer", "figma-design-sync", "framework-docs-researcher", "git-history-analyzer", "issue-intelligence-analyst", "julik-frontend-races-reviewer", "kieran-python-reviewer", "kieran-rails-reviewer", "kieran-typescript-reviewer", "learnings-researcher", "lint", "maintainability-reviewer", "pattern-recognition-specialist", "performance-oracle", "performance-reviewer", "pr-comment-resolver", "previous-comments-reviewer", "product-lens-reviewer", "project-standards-reviewer", "reliability-reviewer", "repo-research-analyst", "schema-drift-detector", "scope-guardian-reviewer", "security-lens-reviewer", "security-reviewer", "security-sentinel", "slack-researcher", "spec-flow-analyzer", "systematic-implementer", "testing-reviewer"];
 export declare const BUNDLED_AGENT_QUALIFIED_IDS: readonly ["design/design-implementation-reviewer", "design/design-iterator", "design/figma-design-sync", "docs/ankane-readme-writer", "document-review/adversarial-document-reviewer", "document-review/coherence-reviewer", "document-review/design-lens-reviewer", "document-review/feasibility-reviewer", "document-review/product-lens-reviewer", "document-review/scope-guardian-reviewer", "document-review/security-lens-reviewer", "research/best-practices-researcher", "research/framework-docs-researcher", "research/git-history-analyzer", "research/issue-intelligence-analyst", "research/learnings-researcher", "research/repo-research-analyst", "research/slack-researcher", "review/adversarial-reviewer", "review/agent-native-reviewer", "review/api-contract-reviewer", "review/architecture-strategist", "review/cli-agent-readiness-reviewer", "review/cli-readiness-reviewer", "review/code-simplicity-reviewer", "review/correctness-reviewer", "review/data-integrity-guardian", "review/data-migration-expert", "review/data-migrations-reviewer", "review/deployment-verification-agent", "review/dhh-rails-reviewer", "review/julik-frontend-races-reviewer", "review/kieran-python-reviewer", "review/kieran-rails-reviewer", "review/kieran-typescript-reviewer", "review/maintainability-reviewer", "review/pattern-recognition-specialist", "review/performance-oracle", "review/performance-reviewer", "review/previous-comments-reviewer", "review/project-standards-reviewer", "review/reliability-reviewer", "review/schema-drift-detector", "review/security-reviewer", "review/security-sentinel", "review/testing-reviewer", "workflow/bug-reproduction-validator", "workflow/lint", "workflow/pr-comment-resolver", "workflow/spec-flow-analyzer", "workflow/systematic-implementer"];
-export declare const BUNDLED_SKILL_NAMES: readonly ["agent-browser", "agent-native-architecture", "agent-native-audit", "andrew-kane-gem-writer", "ce:brainstorm", "ce:compound", "ce:compound-refresh", "ce:ideate", "ce:plan", "ce:review", "ce:work", "changelog", "claude-permissions-optimizer", "compound-docs", "deepen-plan", "deploy-docs", "dhh-rails-style", "document-review", "dspy-ruby", "every-style-editor", "feature-video", "frontend-design", "gemini-imagegen", "generate_command", "git-clean-gone-branches", "git-commit", "git-commit-push-pr", "git-worktree", "lfg", "onboarding", "orchestrating-swarms", "proof", "rclone", "report-bug-ce", "reproduce-bug", "resolve-pr-feedback", "setup", "slfg", "test-browser", "test-driven-development", "test-xcode", "todo-create", "todo-resolve", "todo-triage", "using-systematic", "writing-skills", "writing-systematic-skills"];
+export declare const BUNDLED_SKILL_NAMES: readonly ["agent-browser", "agent-native-architecture", "agent-native-audit", "andrew-kane-gem-writer", "ce:brainstorm", "ce:compound", "ce:compound-refresh", "ce:ideate", "ce:plan", "ce:review", "ce:work", "changelog", "claude-permissions-optimizer", "compound-docs", "deepen-plan", "deploy-docs", "dhh-rails-style", "document-review", "dspy-ruby", "every-style-editor", "feature-video", "frontend-design", "gemini-imagegen", "generate_command", "git-clean-gone-branches", "git-commit", "git-commit-push-pr", "git-worktree", "lfg", "onboarding", "orchestrating-subagents", "orchestrating-swarms", "proof", "rclone", "report-bug-ce", "reproduce-bug", "resolve-pr-feedback", "setup", "slfg", "test-browser", "test-driven-development", "test-xcode", "todo-create", "todo-resolve", "todo-triage", "using-systematic", "writing-skills", "writing-systematic-skills"];
 export type BundledAgentName = (typeof BUNDLED_AGENT_NAMES)[number];
 export type BundledSkillName = (typeof BUNDLED_SKILL_NAMES)[number];

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

@@ -1280,6 +1280,7 @@
           "git-worktree",
           "lfg",
           "onboarding",
+          "orchestrating-subagents",
           "orchestrating-swarms",
           "proof",
           "rclone",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fro.bot/systematic",
-  "version": "2.27.0",
+  "version": "2.28.0",
   "description": "Structured engineering workflows for OpenCode",
   "type": "module",
   "homepage": "https://fro.bot/systematic",

package/skills/orchestrating-subagents/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: orchestrating-subagents
+description: Use when dispatching parallel or serial subagents in OpenCode, coordinating multi-unit plan execution, synthesizing results from independent subagent runs, or handling subagent failure and retry. Triggers on requests to run tasks in parallel, divide work across subagents, orchestrate a pipeline of dependent steps, or coordinate multiple agents without shared-file conflicts.
+---
+
+# Orchestrating Subagents
+
+Dispatch, coordinate, and synthesize results from OpenCode subagents using the `task()` primitive.
+
+## The Portable Primitive
+
+Every subagent dispatch goes through `task()`:
+
+```typescript
+task({
+  subagent_type: "systematic-implementer",
+  description: "Implement auth module",
+  prompt: "...",
+})
+```
+
+**Required parameters:**
+- `subagent_type` — the registered agent name (e.g., `systematic-implementer`, `best-practices-researcher`)
+- `description` — 3–5 word label shown in the UI
+- `prompt` — full instructions for the subagent
+
+**Optional:**
+- `task_id` — resume a prior subagent session instead of creating a new one
+- `command` — the slash command that triggered this task
+
+Foreground dispatch (no `background` parameter) blocks until the subagent returns its result. **This is the default and works on all OpenCode versions.**
+
+## Background Dispatch (Experimental)
+
+Background dispatch is gated by a runtime flag. It is **not available by default**.
+
+```typescript
+// Only use when the runtime exposes background support
+task({
+  subagent_type: "systematic-implementer",
+  description: "Implement auth module",
+  prompt: "...",
+  background: true,   // experimental — see below
+})
+```
+
+**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 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.
+
+**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.
+
+## Serial vs Parallel Dispatch
+
+### Serial (default, always safe)
+
+Dispatch one subagent, wait for its result, then dispatch the next. Use when:
+- Units have dependencies (unit B needs unit A's output)
+- Units touch overlapping files
+- You need to verify each result before proceeding
+
+```typescript
+const researchResult = task({
+  subagent_type: "best-practices-researcher",
+  description: "Research caching patterns",
+  prompt: "Research Redis caching best practices for Rails APIs...",
+})
+
+// Use research output to guide implementation
+task({
+  subagent_type: "systematic-implementer",
+  description: "Implement caching",
+  prompt: `Implement caching based on this research:\n\n${researchResult}`,
+})
+```
+
+### Parallel (foreground batches)
+
+Dispatch multiple foreground subagents in the same turn. OpenCode runs them concurrently when dispatched together. Use when:
+- Units are fully independent (no shared files, no dependency on each other's output)
+- You have passed the Parallel Safety Check (see below)
+
+```typescript
+// Dispatch independent review subagents together
+task({ subagent_type: "security-sentinel", description: "Security review", prompt: "..." })
+task({ subagent_type: "performance-oracle", description: "Performance review", prompt: "..." })
+task({ subagent_type: "correctness-reviewer", description: "Correctness review", prompt: "..." })
+// All three run; orchestrator synthesizes results after all complete
+```
+
+## Parallel Safety Check
+
+Before dispatching units in parallel, verify:
+
+1. **No file overlap** — build a file-to-unit map from each unit's declared files. Any file appearing in 2+ units means overlap → use serial dispatch instead.
+2. **No git index contention** — parallel subagents must not stage files (`git add`), create commits, or run the full test suite. If the current workflow owns git operations, the orchestrator handles staging and committing after all parallel units complete; otherwise, synthesize results and file lists and leave staging/committing to the caller or user.
+3. **No test interference** — concurrent test runs pick up each other's in-progress changes. Instruct parallel subagents not to run the project test suite.
+
+If any check fails, downgrade to serial dispatch. Log the reason (e.g., "Units 2 and 4 share `config/routes.rb` — using serial dispatch").
+
+## Subagent Constraints for Parallel Work
+
+When dispatching units in parallel, include these instructions in each subagent's prompt:
+
+> Do not stage files (`git add`), create commits, or run the project test suite. Leave staging and committing to the orchestrator or caller.
+
+## Result Synthesis
+
+After subagents complete, the orchestrator synthesizes results:
+
+1. **Wait for all** — in a parallel batch, wait for every subagent to finish before acting on any result.
+2. **Check for file collisions** — compare actual files modified by all subagents in the batch (not just declared files). If 2+ subagents 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.
+3. **Review each diff** — verify changes match the unit's declared scope.
+4. **Run targeted tests** — run the narrowest test command relevant to the changed files.
+5. **Stage and commit per unit (if the workflow owns git operations)** — in dependency order, stage only that unit's files and commit with a conventional message. If git operations belong to the caller or user, synthesize the result list and file inventory instead.
+
+## Failure and Retry
+
+- 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.
+
+## Quick Reference
+
+| Scenario | Approach |
+|---|---|
+| 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 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 |
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---|---|
+| Assuming `task_status` is always available | Check tool list first; fall back to foreground if absent |
+| 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 |