@fro.bot/systematic 3.0.2 → 3.1.0

package/HARNESSES.md

@@ -0,0 +1,97 @@
+# Harnesses
+
+This is the evidence registry for Systematic's harness-portability work. **Every tool or mechanism named here is backed by an in-repo path with line numbers, installed or cloned source, or an authoritative URL.** If the supplied research did not verify a capability, it is explicitly marked **UNVERIFIED**; absence of evidence is not evidence of absence.
+
+**Tiers.** Tier 1 means Systematic ships a controlled adapter: OpenCode and Pi. Tier 2 means the harness is documented for portability but has no Systematic adapter: Claude Code, Codex CLI, Gemini CLI, and GitHub Copilot.
+
+## Capability matrix
+
+The four capability rows use the vocabulary in the [OpenCode profile](skills/using-systematic/references/opencode-profile.md#L3-L8) and [Pi profile](skills/using-systematic/references/pi-profile.md#L3-L8).
+
+| Capability | OpenCode (Tier 1) | Pi (Tier 1) | Claude Code (Tier 2) | Codex CLI (Tier 2) | Gemini CLI (Tier 2) | GitHub Copilot (Tier 2) |
+|---|---|---|---|---|---|---|
+| Subagent delegation | `task`, including `subagent_type`, resume, and background execution [OC-1] | `systematic_delegate({agent, task})`; sequential, capped at 20 turns [PI-1] | `context: fork` for skills; `subagent_type` is **UNVERIFIED** [CC-1] | **UNVERIFIED** [U] | **UNVERIFIED** [U] | Built-in/custom agents [GH-1][GH-2] |
+| Blocking user interaction | `question` [OC-2] | 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] |
+| Task tracking | `todowrite` [OC-3] | 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] |
+| Skill loading | Skills become commands and `systematic_skill` is registered [OC-4][OC-5] | `systematic_skill` adapter and Pi-native activation [PI-3][PI-4] | Skill tool, `SKILL.md`, and `.claude/skills/` [CC-5][CC-6] | **UNVERIFIED** [U] | **UNVERIFIED** [U] | `SKILL.md` skills [GH-6] |
+| Skills-file support | `SKILL.md` is loaded by the Systematic skill path [OC-4] | `pi.skills` ships `./skills`, including `SKILL.md` discovery [PI-4][PI-5] | `SKILL.md` and `.claude/skills/` [CC-5][CC-6] | **UNVERIFIED** [U] | **UNVERIFIED** [U] | `SKILL.md` [GH-6] |
+
+`[U]` means the capability was not checked in the supplied research pack. It is not a claim that the capability does not exist.
+
+## OpenCode — Tier 1 shipped adapter
+
+OpenCode is the primary controlled integration. Its profile defines delegation, blocking interaction, task tracking, and skill loading [OC-P]. The underlying source registers `task` with specialized-agent, resume, and background fields [OC-1], `question` as a user-facing tool [OC-2], and `todowrite` as a built-in tool [OC-3]. Systematic converts bundled skills into commands in `src/lib/config-handler.ts:467-485` and registers the skill tool in `src/lib/skill-tool.ts:41-101` [OC-4][OC-5]. Bundled agent markdown omits a model field by invariant [OC-6]; runtime configuration may still supply source-owned defaults [OC-7].
+
+Compatibility is direct: OpenCode consumes the concrete invocation language in the profile. The adapter is not a generic claim about other harnesses.
+
+## Pi — Tier 1 shipped adapter
+
+Pi's profile records degraded or unavailable native capabilities and explicit fallbacks [PI-P]. The adapter registers `systematic_skill` in `src/pi.ts:85-103` and `systematic_delegate` in `src/pi.ts:106-113` [PI-3]. Delegation is explicitly sequential (`executionMode: 'sequential'`), capped at `MAX_DELEGATE_TURNS = 20`, and guarded against re-entry in `src/lib/pi-delegate-tool.ts:14-18,245-249` [PI-1].
+
+The package manifest exposes the extension and skills at `package.json:17-23`, with tests verifying both manifest entries and their packaged paths `tests/unit/package-exports.test.ts:42-66,241-267` [PI-4]. Pi's RPC/JSONL test fixture isolates its environment (`tests/integration/pi.test.ts:349-388`), and the installed runtime exposes environment-specific agent/session directories `node_modules/@earendil-works/pi-coding-agent/dist/config.js:396-398` [PI-5].
+
+Pi does not consume `disabled_skills` or Systematic's OpenCode configuration, and its skill loading has no OpenCode-style permission gate `docs/src/content/docs/guides/pi-harness.mdx:39-47` [PI-6]. Those are deliberate honesty boundaries, not implied parity.
+
+## Claude Code — Tier 2 documented portability target
+
+Claude Code documents `AskUserQuestion` [CC-2], current task tracking through `TaskCreate`/`TaskGet`/`TaskList`/`TaskUpdate`, and the deprecated `TodoWrite` [CC-3][CC-4]. Its skill model includes the skill tool, `SKILL.md`, `~/.claude/skills/`, and `.claude/skills/` [CC-5][CC-6]. Skills may run with `context: fork`; a public-docs verification of a `subagent_type` parameter was not found, so that name remains **UNVERIFIED** [CC-1]. Systematic ships no Claude Code adapter or profile.
+
+## Codex CLI — Tier 2 documented portability target
+
+The supplied evidence verifies only `request_user_input`: its definition names the tool [CX-1], and its handler blocks while restricting use to the root thread, rejecting subagents [CX-2]. Delegation, task tracking, skill loading, and skills-file support were not checked and remain **UNVERIFIED**. Systematic ships no Codex adapter or profile.
+
+## Gemini CLI — Tier 2 documented portability target
+
+The supplied evidence verifies `ask_user`: the official documentation says it pauses execution until answers arrive [GE-1], and the implementation defines `ASK_USER_TOOL_NAME` [GE-2]. Other capabilities, including delegation, task tracking, and skill-file support, were not checked and remain **UNVERIFIED**. Systematic ships no Gemini adapter or profile.
+
+## GitHub Copilot — Tier 2 documented portability target
+
+Copilot documents built-in agents and custom-agent invocation [GH-1][GH-2]. Its documented blocking behavior is plan-mode clarification, with `--no-ask-user` disabling asks; no dedicated blocking-tool name was verified [GH-3][GH-4]. The cloud-agent tasks/sessions API is documented, but no `TodoWrite` equivalent was verified [GH-5]. `SKILL.md` skills are documented [GH-6], as are instruction files including `AGENTS.md`, `.github/copilot-instructions.md`, and `.github/instructions/**/*.instructions.md` [GH-7][GH-8]. Systematic ships no Copilot adapter or profile.
+
+## Similarities and differences
+
+`SKILL.md` is the clearest cross-harness convergence: it is documented for Claude Code and Copilot, consumed by OpenCode's Systematic skill path, and shipped through Systematic-on-Pi [OC-4][PI-4][CC-5][GH-6]. `AGENTS.md` is also converging as an instruction-file convention: this repository uses it (`AGENTS.md:1-7`), and Copilot documents it [GH-7][GH-8].
+
+Delegation semantics diverge materially: OpenCode supports parallel/background dispatch [OC-1], Pi's adapter is sequential-only [PI-1], Claude's `context: fork` is skill-scoped [CC-1], and the remaining Tier 2 delegation claims are **UNVERIFIED**. Blocking input likewise ranges from native tools (`question`, `request_user_input`, `ask_user`, `AskUserQuestion`) to Pi's numbered-chat fallback and Copilot's plan-mode clarification [OC-2][PI-2][CC-2][CX-1][GE-1][GH-3].
+
+## Maintenance
+
+Update this file evidence-first: verify the implementation path and line range, installed/cloned source, or authoritative URL before adding a tool name. Re-check URLs when their pinned revision or behavior matters. Preserve **UNVERIFIED** when a capability has not been checked; do not fill gaps from intuition. Tier 1 changes require updating the corresponding profile and this registry together.
+
+Migrated-skill discipline is enforced by the [content-integrity gate](scripts/content-integrity.ts); keep exact harness identifiers in the designated profile/evidence surfaces and follow the gate's allowlist policy rather than weakening the gate.
+
+## Evidence registry
+
+- **OC-P** — [OpenCode profile](skills/using-systematic/references/opencode-profile.md#L3-L8).
+- **OC-1** — cloned OpenCode source, `.slim/clonedeps/repos/anomalyco__opencode/packages/opencode/src/tool/task.ts:24-62`.
+- **OC-2** — cloned OpenCode source, `.slim/clonedeps/repos/anomalyco__opencode/packages/core/src/tool/question.ts:10-25`.
+- **OC-3** — cloned OpenCode source, `.slim/clonedeps/repos/anomalyco__opencode/packages/core/src/tool/todowrite.ts:1-10`.
+- **OC-4** — `src/lib/config-handler.ts:467-485`.
+- **OC-5** — `src/lib/skill-tool.ts:41-101`.
+- **OC-6** — `ARCHITECTURE.md:75-85` and `agents/`.
+- **OC-7** — `src/lib/config-handler.ts:276-289`.
+- **PI-P** — [Pi profile](skills/using-systematic/references/pi-profile.md#L3-L8).
+- **PI-1** — `src/lib/pi-delegate-tool.ts:14-18,245-249,279-291`.
+- **PI-2** — [Pi profile](skills/using-systematic/references/pi-profile.md#L5-L8).
+- **PI-3** — `src/pi.ts:85-113`.
+- **PI-4** — `package.json:17-23`; `tests/unit/package-exports.test.ts:42-66,241-267`.
+- **PI-5** — `tests/integration/pi.test.ts:349-388`; installed Pi source `node_modules/@earendil-works/pi-coding-agent/dist/config.js:396-398`.
+- **PI-6** — `docs/src/content/docs/guides/pi-harness.mdx:39-47`.
+- **CC-1** — [Claude Code skills](https://code.claude.com/docs/en/skills) (`context: fork`); public-docs `subagent_type` verification is **UNVERIFIED**.
+- **CC-2** — [Claude Code tools reference](https://code.claude.com/docs/en/tools-reference).
+- **CC-3** — [Claude Code tools reference](https://code.claude.com/docs/en/tools-reference).
+- **CC-4** — [Claude Code todo tracking](https://code.claude.com/docs/en/agent-sdk/todo-tracking.md).
+- **CC-5** — [Claude Code skills](https://code.claude.com/docs/en/skills).
+- **CC-6** — [Claude Code Agent SDK skills](https://code.claude.com/docs/en/agent-sdk/skills.md).
+- **CX-1** — [Codex request_user_input definition](https://github.com/openai/codex/blob/35aaa5d9/codex-rs/tools/src/request_user_input_tool.rs).
+- **CX-2** — [Codex request_user_input handler](https://github.com/openai/codex/blob/d47b755a/codex-rs/core/src/tools/handlers/request_user_input.rs).
+- **GE-1** — [Gemini ask-user documentation](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/ask-user.md).
+- **GE-2** — [Gemini ask-user implementation](https://github.com/google-gemini/gemini-cli/blob/d2cd12a7/packages/core/src/tools/ask-user.ts).
+- **GH-1** — [Copilot CLI built-in agents](https://docs.github.com/en/copilot/concepts/agents/copilot-cli/about-custom-agents).
+- **GH-2** — [Copilot CLI custom agents](https://docs.github.com/en/copilot/how-tos/copilot-cli/use-copilot-cli/invoke-custom-agents).
+- **GH-3** — [Copilot CLI](https://docs.github.com/en/copilot/concepts/agents/about-copilot-cli).
+- **GH-4** — [Copilot CLI automation](https://docs.github.com/en/copilot/how-tos/copilot-cli/automate-copilot-cli/run-cli-programmatically).
+- **GH-5** — [Copilot cloud-agent tasks/sessions API](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/cloud-agent/use-cloud-agent-via-the-api).
+- **GH-6** — [Copilot CLI skills](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-skills).
+- **GH-7** — [Copilot best-practices instructions](https://docs.github.com/en/copilot/get-started/best-practices).
+- **GH-8** — [Copilot `AGENTS.md` support](https://github.blog/changelog/2025-08-28-copilot-coding-agent-now-supports-agents-md-custom-instructions/).

package/dist/cli.js

@@ -9,7 +9,7 @@ import {
   modify,
   parse,
   parseTree
-} from "./index-yskzf7vh.js";
+} from "./index-6yz7bra8.js";
 
 // src/cli.ts
 import fs2 from "fs";

package/dist/{index-yskzf7vh.js → index-6yz7bra8.js}

@@ -16074,6 +16074,9 @@ var REMOVED_BUNDLED_AGENT_NAMES = [
   "security-sentinel",
   "workflow/lint"
 ];
+var REMOVED_BUNDLED_AGENT_CATEGORIES = [
+  "docs"
+];
 
 // src/lib/config-schema.ts
 var permissionSettingSchema = exports_external.enum(["ask", "allow", "deny"]);
@@ -16296,16 +16299,19 @@ var CURRENT_AGENT_NAMES_SET = new Set([
   ...BUNDLED_AGENT_NAMES,
   ...BUNDLED_AGENT_QUALIFIED_IDS
 ]);
+var REMOVED_AGENT_CATEGORIES_SET = new Set(REMOVED_BUNDLED_AGENT_CATEGORIES);
 function computeDroppedNames(names, allowedSet) {
   return names.filter((n) => !allowedSet.has(n));
 }
 var MIGRATION_DOCS_URL = "https://fro.bot/systematic/guides/v3-migration/";
-function warnDroppedNames(dropped, field, warned) {
+function warnDroppedNames(dropped, field, warned, removalVersion) {
   for (const name of dropped) {
     if (warned.has(name))
       continue;
     warned.add(name);
-    console.warn(`[systematic] "${name}" in \`${field}\` is no longer a bundled name and will be ignored. Remove it from your config to silence this warning. See ${MIGRATION_DOCS_URL} for migration guidance.`);
+    const displayName = field === "categories" ? `${field}.${name}` : name;
+    const removalNote = removalVersion ? ` It was removed in ${removalVersion}.` : "";
+    console.warn(`[systematic] "${displayName}" in \`${field}\` is no longer a bundled name and will be ignored.${removalNote} Remove it from your config to silence this warning. See ${MIGRATION_DOCS_URL} for migration guidance.`);
   }
 }
 function resolveConfigPath(dir, basename) {
@@ -16443,7 +16449,15 @@ function loadConfigWithSources(projectDir) {
   const projectSource = loadConfigSource(paths.projectConfig, "project");
   const customSource = paths.customConfig ? loadConfigSource(paths.customConfig, "custom") : null;
   const sources = [userSource, projectSource, customSource].filter((source) => source !== null);
-  const overlays = mergeOverlaySources(sources);
+  const mergedOverlays = mergeOverlaySources(sources);
+  const droppedCategories = Object.keys(mergedOverlays.categories).filter((name) => REMOVED_AGENT_CATEGORIES_SET.has(name));
+  const warned = new Set;
+  warnDroppedNames(droppedCategories, "categories", warned, "v3.0.0");
+  const droppedCategorySet = new Set(droppedCategories);
+  const overlays = droppedCategorySet.size === 0 ? mergedOverlays : {
+    ...mergedOverlays,
+    categories: Object.fromEntries(Object.entries(mergedOverlays.categories).filter(([key]) => !droppedCategorySet.has(key)))
+  };
   const userConfig = userSource?.config;
   const projectConfig = projectSource?.config;
   const customConfig = customSource?.config;
@@ -16461,7 +16475,6 @@ function loadConfigWithSources(projectDir) {
     categories: overlayValues(overlays.categories),
     skills_as_commands: customConfig?.skills_as_commands ?? projectConfig?.skills_as_commands ?? userConfig?.skills_as_commands ?? DEFAULT_CONFIG.skills_as_commands
   };
-  const warned = new Set;
   const droppedSkills = computeDroppedNames(result.disabled_skills, CURRENT_SKILL_NAMES_SET);
   warnDroppedNames(droppedSkills, "disabled_skills", warned);
   const droppedAgents = computeDroppedNames(result.disabled_agents, CURRENT_AGENT_NAMES_SET);

package/dist/index.js

@@ -14,7 +14,7 @@ import {
   loadConfigWithSources,
   parseFrontmatter,
   walkDir
-} from "./index-yskzf7vh.js";
+} from "./index-6yz7bra8.js";
 
 // src/index.ts
 import fs8 from "fs";
@@ -188,6 +188,15 @@ var applyBootstrapContent = (output, content) => {
 
 ${content}` : content;
 };
+function readHarnessProfile(bundledSkillsDir, name) {
+  const profilePath = path2.join(bundledSkillsDir, "using-systematic/references", `${name}-profile.md`);
+  try {
+    return fs2.readFileSync(profilePath, "utf8");
+  } catch (error) {
+    console.error(`Failed to read harness profile ${profilePath}: ${error instanceof Error ? error.message : String(error)}`);
+    return null;
+  }
+}
 function getSkillUsageTemplate() {
   return `**Skills naming:**
 - Systematic bundled skills use the \`systematic:\` prefix (e.g., \`systematic:onboarding\`)
@@ -202,7 +211,7 @@ function getSkillUsageTemplate() {
 Bundled skills ship with the Systematic plugin and are discoverable via \`systematic_skill\`.`;
 }
 function getBootstrapContent(config, deps) {
-  const { bundledSkillsDir, usageTemplate } = deps;
+  const { bundledSkillsDir, usageTemplate, profileBlock } = deps;
   if (!config.bootstrap.enabled)
     return null;
   if (config.bootstrap.file) {
@@ -225,6 +234,9 @@ function getBootstrapContent(config, deps) {
   const catalogSection = catalog.length > 0 ? `
 
 ${catalog}` : "";
+  const profileSection = profileBlock === undefined ? "" : `
+
+${profileBlock}`;
   return `<SYSTEMATIC_WORKFLOWS>
 You have access to structured engineering workflows via the Systematic plugin.
 
@@ -232,7 +244,7 @@ You have access to structured engineering workflows via the Systematic plugin.
 
 ${content}
 
-${skillUsage}${catalogSection}
+${skillUsage}${profileSection}${catalogSection}
 </SYSTEMATIC_WORKFLOWS>`;
 }
 
@@ -1439,7 +1451,10 @@ var getPackageVersion = () => {
 var initializePlugin = async ({ client, directory }) => {
   let hasLoggedInit = false;
   const config = loadConfig(directory);
-  const bootstrapContent = getBootstrapContent(config, { bundledSkillsDir });
+  const bootstrapContent = getBootstrapContent(config, {
+    bundledSkillsDir,
+    profileBlock: readHarnessProfile(bundledSkillsDir, "opencode") ?? undefined
+  });
   const configHandler = createConfigHandler({
     directory,
     bundledSkillsDir,

package/dist/lib/bootstrap.d.ts

@@ -21,7 +21,10 @@ export declare const applyBootstrapContent: (output: {
 export interface BootstrapDeps {
     bundledSkillsDir: string;
     usageTemplate?: string;
+    profileBlock?: string;
 }
+/** Reads a harness capability profile from the packaged using-systematic references. */
+export declare function readHarnessProfile(bundledSkillsDir: string, name: string): string | null;
 type BootstrapContentConfig = Pick<SystematicConfig, 'bootstrap' | 'disabled_skills'>;
 /** Safely computes default bootstrap content, returning null instead of throwing. */
 export declare function computeBootstrapContentSafe(deps: BootstrapDeps, reportError?: (error: unknown) => void): string | null;

package/dist/lib/config.d.ts

@@ -40,7 +40,7 @@ export declare function computeDroppedNames(names: readonly string[], allowedSet
  * single load call -- callers must NOT share it across independent loads.
  * Passing a fresh set per load ensures no cross-load suppression.
  */
-export declare function warnDroppedNames(dropped: string[], field: string, warned: Set<string>): void;
+export declare function warnDroppedNames(dropped: string[], field: string, warned: Set<string>, removalVersion?: string): void;
 export declare function loadConfig(projectDir: string): SystematicConfig;
 export declare function loadConfigWithSources(projectDir: string): SourceAwareConfigResult;
 export declare function getConfigPaths(projectDir: string): {

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

@@ -13,3 +13,4 @@
  */
 export declare const REMOVED_BUNDLED_SKILL_NAMES: readonly string[];
 export declare const REMOVED_BUNDLED_AGENT_NAMES: readonly string[];
+export declare const REMOVED_BUNDLED_AGENT_CATEGORIES: readonly string[];

package/dist/pi.js

@@ -3078,6 +3078,15 @@ ${bullets}`;
 }
 
 // src/lib/bootstrap.ts
+function readHarnessProfile(bundledSkillsDir, name) {
+  const profilePath = path4.join(bundledSkillsDir, "using-systematic/references", `${name}-profile.md`);
+  try {
+    return fs5.readFileSync(profilePath, "utf8");
+  } catch (error) {
+    console.error(`Failed to read harness profile ${profilePath}: ${error instanceof Error ? error.message : String(error)}`);
+    return null;
+  }
+}
 var DEFAULT_BOOTSTRAP_CONFIG = {
   bootstrap: { enabled: true },
   disabled_skills: []
@@ -3120,7 +3129,7 @@ function getSkillUsageTemplate() {
 Bundled skills ship with the Systematic plugin and are discoverable via \`systematic_skill\`.`;
 }
 function getBootstrapContent(config, deps) {
-  const { bundledSkillsDir, usageTemplate } = deps;
+  const { bundledSkillsDir, usageTemplate, profileBlock } = deps;
   if (!config.bootstrap.enabled)
     return null;
   if (config.bootstrap.file) {
@@ -3143,6 +3152,9 @@ function getBootstrapContent(config, deps) {
   const catalogSection = catalog.length > 0 ? `
 
 ${catalog}` : "";
+  const profileSection = profileBlock === undefined ? "" : `
+
+${profileBlock}`;
   return `<SYSTEMATIC_WORKFLOWS>
 You have access to structured engineering workflows via the Systematic plugin.
 
@@ -3150,7 +3162,7 @@ You have access to structured engineering workflows via the Systematic plugin.
 
 ${content}
 
-${skillUsage}${catalogSection}
+${skillUsage}${profileSection}${catalogSection}
 </SYSTEMATIC_WORKFLOWS>`;
 }
 
@@ -3599,7 +3611,8 @@ async function systematicPiExtension(pi, deps = defaultPiExtensionDependencies)
   const resolverOptions = { bundledSkillsDir, disabledSkills };
   const bootstrapContent = computeBootstrapContentSafe({
     bundledSkillsDir,
-    usageTemplate: PI_BOOTSTRAP_USAGE_TEMPLATE
+    usageTemplate: PI_BOOTSTRAP_USAGE_TEMPLATE,
+    profileBlock: readHarnessProfile(bundledSkillsDir, "pi") ?? undefined
   }, reportPiBootstrapFailure);
   pi.on("before_agent_start", (event) => {
     const systemPrompt = composeSystemPromptWithBootstrap(event.systemPrompt, bootstrapContent);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fro.bot/systematic",
-  "version": "3.0.2",
+  "version": "3.1.0",
   "description": "Structured engineering workflows for OpenCode",
   "type": "module",
   "homepage": "https://fro.bot/systematic",
@@ -26,7 +26,8 @@
     "dist",
     "skills",
     "agents",
-    "ATTRIBUTIONS.md"
+    "ATTRIBUTIONS.md",
+    "HARNESSES.md"
   ],
   "workspaces": [
     "docs"
@@ -88,8 +89,8 @@
   "devDependencies": {
     "@biomejs/biome": "2.5.3",
     "@earendil-works/pi-coding-agent": "0.80.6",
-    "@opencode-ai/plugin": "1.17.20",
-    "@opencode-ai/sdk": "1.17.20",
+    "@opencode-ai/plugin": "1.18.0",
+    "@opencode-ai/sdk": "1.18.0",
     "@semantic-release/exec": "7.1.0",
     "@types/bun": "latest",
     "@types/js-yaml": "4.0.9",

package/skills/ce-brainstorm/SKILL.md

@@ -2,6 +2,8 @@
 name: ce:brainstorm
 description: 'Explore requirements and approaches through collaborative dialogue before writing a right-sized requirements document and planning implementation. Use for feature ideas, problem framing, when the user says ''let''s brainstorm'', or when they want to think through options before deciding what to build. Also use when a user describes a vague or ambitious feature request, asks ''what should we build'', ''help me think through X'', presents a problem with multiple valid solutions, or seems unsure about scope or direction — even if they don''t explicitly ask to brainstorm.'
 argument-hint: "[feature idea or problem to explore]"
+metadata:
+  harness-portability: neutral-v1
 ---
 
 # Brainstorm a Feature or Improvement
@@ -30,7 +32,7 @@ This skill does not implement code. It explores, clarifies, and documents decisi
 1. **Ask one question at a time** - Do not batch several unrelated questions into one message.
 2. **Prefer single-select multiple choice** - Use single-select when choosing one direction, one priority, or one next step.
 3. **Use multi-select rarely and intentionally** - Use it only for compatible sets such as goals, constraints, non-goals, or success criteria that can all coexist. If prioritization matters, follow up by asking which selected item is primary.
-4. **Use the platform's question tool when available** - When asking the user a question, prefer the platform's blocking question tool if one exists (`question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini). Otherwise, present numbered options in chat and wait for the user's reply before proceeding.
+4. **Use the platform's question tool when available** - When asking the user a question, prefer the platform's blocking question tool if one exists (`question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini; in Pi, use the blocking-question extension if available, otherwise present numbered options in chat and wait). Otherwise, present numbered options in chat and wait for the user's reply before proceeding.
 
 ## Output Guidance
 

package/skills/ce-compound/SKILL.md

@@ -32,7 +32,7 @@ When spawning subagents, pass the relevant file contents into the task prompt so
 
 ## Execution Strategy
 
-Present the user with two options before proceeding, using the platform's blocking question tool (`question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini). If no question tool is available, present the options and wait for the user's reply.
+Present the user with two options before proceeding, using the platform's blocking question tool (`question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini; in Pi, use the blocking-question extension if available, otherwise present numbered options in chat and wait). If no question tool is available, present the options and wait for the user's reply.
 
 ```
 1. Full (recommended) — the complete compound workflow. Researches,
@@ -263,7 +263,7 @@ After the learning is written and the refresh decision is made, check whether th
 
       `docs/solutions/` — documented solutions to past problems (bugs, best practices, workflow patterns), organized by category with YAML frontmatter (`module`, `tags`, `problem_type`). Relevant when implementing or debugging in documented areas.
       ```
-   c. In full mode, explain to the user why this matters — agents working in this repo (including fresh sessions, other tools, or collaborators without the plugin) won't know to check `docs/solutions/` unless the instruction file surfaces it. Show the proposed change and where it would go, then use the platform's blocking question tool (`question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini) to get consent before making the edit. If no question tool is available, present the proposal and wait for the user's reply. In lightweight mode, output a one-liner note and move on
+   c. In full mode, explain to the user why this matters — agents working in this repo (including fresh sessions, other tools, or collaborators without the plugin) won't know to check `docs/solutions/` unless the instruction file surfaces it. Show the proposed change and where it would go, then use the platform's blocking question tool (`question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini; in Pi, use the blocking-question extension if available, otherwise present numbered options in chat and wait) to get consent before making the edit. If no question tool is available, present the proposal and wait for the user's reply. In lightweight mode, output a one-liner note and move on
 
 ### Phase 3: Optional Enhancement
 
@@ -413,7 +413,7 @@ What's next?
 5. Other
 ```
 
-**After displaying the success output, present the "What's next?" options using the platform's blocking question tool** (`question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini). If no question tool is available, present the numbered options and wait for the user's reply before proceeding. Do not continue the workflow or end the turn without the user's selection.
+**After displaying the success output, present the "What's next?" options using the platform's blocking question tool** (`question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini; in Pi, use the blocking-question extension if available, otherwise present numbered options in chat and wait). If no question tool is available, present the numbered options and wait for the user's reply before proceeding. Do not continue the workflow or end the turn without the user's selection.
 
 **Alternate output (when updating an existing doc due to high overlap):**
 

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

@@ -33,7 +33,7 @@ Check if `$ARGUMENTS` contains `mode:autofix`. If present, strip it from argumen
 
 Follow the same interaction style as `ce:brainstorm`:
 
-- Ask questions **one at a time** — use the platform's blocking question tool when available (`question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini). Otherwise, present numbered options in plain text and wait for the user's reply before continuing
+- Ask questions **one at a time** — use the platform's blocking question tool when available (`question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini; in Pi, use the blocking-question extension if available, otherwise present numbered options in chat and wait). Otherwise, present numbered options in plain text and wait for the user's reply before continuing
 - Prefer **multiple choice** when natural options exist
 - Start with **scope and intent**, then narrow only when needed
 - Do **not** ask the user to make decisions before you have evidence
@@ -395,7 +395,7 @@ Do **not** ask questions about whether code changes were intentional, whether th
 
 #### Question Style
 
-Always present choices using the platform's blocking question tool when available (`question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini). Otherwise, present numbered options in plain text and wait for the user's reply before proceeding.
+Always present choices using the platform's blocking question tool when available (`question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini; in Pi, use the blocking-question extension if available, otherwise present numbered options in chat and wait). Otherwise, present numbered options in plain text and wait for the user's reply before proceeding.
 
 Question rules:
 
@@ -675,6 +675,6 @@ After the refresh report is generated, check whether the project's instruction f
 
       `docs/solutions/` — documented solutions to past problems (bugs, best practices, workflow patterns), organized by category with YAML frontmatter (`module`, `tags`, `problem_type`). Relevant when implementing or debugging in documented areas.
       ```
-   c. In interactive mode, explain to the user why this matters — agents working in this repo (including fresh sessions, other tools, or collaborators without the plugin) won't know to check `docs/solutions/` unless the instruction file surfaces it. Show the proposed change and where it would go, then use the platform's blocking question tool (`question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini) to get consent before making the edit. If no question tool is available, present the proposal and wait for the user's reply. In autofix mode, include it as a "Discoverability recommendation" line in the report — do not attempt to edit instruction files (autofix scope is doc maintenance, not project config).
+   c. In interactive mode, explain to the user why this matters — agents working in this repo (including fresh sessions, other tools, or collaborators without the plugin) won't know to check `docs/solutions/` unless the instruction file surfaces it. Show the proposed change and where it would go, then use the platform's blocking question tool (`question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini; in Pi, use the blocking-question extension if available, otherwise present numbered options in chat and wait) to get consent before making the edit. If no question tool is available, present the proposal and wait for the user's reply. In autofix mode, include it as a "Discoverability recommendation" line in the report — do not attempt to edit instruction files (autofix scope is doc maintenance, not project config).
 
 5. **Amend or create a follow-up commit when the check produces edits.** If step 4 resulted in an edit to an instruction file and Phase 5 already committed the refresh changes, stage the newly edited file and either amend the existing commit (if still on the same branch and no push has occurred) or create a small follow-up commit (e.g., `docs: add docs/solutions/ discoverability to AGENTS.md`). If Phase 5 already pushed the branch to a remote (e.g., the branch+PR path), push the follow-up commit as well so the open PR includes the discoverability change. This keeps the working tree clean and the remote in sync at the end of the run. If the user chose "Don't commit" in Phase 5, leave the instruction-file edit unstaged alongside the other uncommitted refresh changes — no separate commit logic needed.

package/skills/ce-ideate/SKILL.md

@@ -2,6 +2,8 @@
 name: ce:ideate
 description: "Generate and critically evaluate grounded improvement ideas for the current project. Use when asking what to improve, requesting idea generation, exploring surprising improvements, or wanting the AI to proactively suggest strong project directions before brainstorming one in depth. Triggers on phrases like 'what should I improve', 'give me ideas', 'ideate on this project', 'surprise me with improvements', 'what would you change', or any request for AI-generated project improvement suggestions rather than refining the user's own idea."
 argument-hint: "[feature, focus area, or constraint]"
+metadata:
+  harness-portability: neutral-v1
 ---
 
 # Generate Improvement Ideas
@@ -18,7 +20,7 @@ This workflow produces a ranked ideation artifact in `docs/ideation/`. It does *
 
 ## Interaction Method
 
-Use the platform's blocking question tool when available (`question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini). Otherwise, present numbered options in chat and wait for the user's reply before proceeding.
+Use the platform's blocking question tool when available (`question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini; in Pi, use the blocking-question extension if available, otherwise present numbered options in chat and wait). Otherwise, present numbered options in chat and wait for the user's reply before proceeding.
 
 Ask one question at a time. Prefer concise single-select choices when natural options exist.
 

package/skills/ce-plan/SKILL.md

@@ -2,6 +2,8 @@
 name: ce:plan
 description: "Create structured plans for any multi-step task -- software features, research workflows, events, study plans, or any goal that benefits from structured breakdown. Also deepen existing plans with interactive review of sub-agent findings. Use for plan creation when the user says 'plan this', 'create a plan', 'write a tech plan', 'plan the implementation', 'how should we build', 'what's the approach for', 'break this down', 'plan a trip', 'create a study plan', or when a brainstorm/requirements document is ready for planning. Use for plan deepening when the user says 'deepen the plan', 'deepen my plan', 'deepening pass', or uses 'deepen' in reference to a plan."
 argument-hint: "[optional: feature description, requirements doc path, plan path to deepen, or any task to plan]"
+metadata:
+  harness-portability: neutral-v1
 ---
 
 # Create Technical Plan
@@ -16,7 +18,7 @@ This workflow produces a durable implementation plan. It does **not** implement
 
 ## Interaction Method
 
-Use the platform's question tool when available. When asking the user a question, prefer the platform's blocking question tool if one exists (`question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini). Otherwise, present numbered options in chat and wait for the user's reply before proceeding.
+Use the platform's question tool when available. When asking the user a question, prefer the platform's blocking question tool if one exists (`question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini; in Pi, use the blocking-question extension if available, otherwise present numbered options in chat and wait). Otherwise, present numbered options in chat and wait for the user's reply before proceeding.
 
 Ask one question at a time. Prefer a concise single-select choice when natural options exist.
 

package/skills/ce-review/SKILL.md

@@ -2,6 +2,8 @@
 name: ce:review
 description: "Structured code review using tiered persona agents, confidence-gated findings, and a merge/dedup pipeline. Use when reviewing code changes before creating a PR."
 argument-hint: "[blank to review current branch, or provide PR link]"
+metadata:
+  harness-portability: neutral-v1
 ---
 
 # Code Review
@@ -59,7 +61,7 @@ All tokens are optional. Each one present means one less thing to infer. When ab
 
 ### Headless mode rules
 
-- **Skip all user questions.** Never use the platform question tool (`question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini) or other interactive prompts. Infer intent conservatively if the diff metadata is thin.
+- **Skip all user questions.** Never use the platform question tool (`question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini; in Pi, use the blocking-question extension if available, otherwise present numbered options in chat and wait) or other interactive prompts. Infer intent conservatively if the diff metadata is thin.
 - **Require a determinable diff scope.** If headless mode cannot determine a diff scope (no branch, PR, or `base:` ref determinable without user interaction), emit `Review failed (headless mode). Reason: no diff scope detected. Re-invoke with a branch name, PR number, or base:<ref>.` and stop without dispatching agents.
 - **Apply only `safe_auto -> review-fixer` findings in a single pass.** No bounded re-review rounds. Leave `gated_auto`, `manual`, `human`, and `release` work unresolved and return them in the structured output.
 - **Return all non-auto findings as structured text output.** Use the headless output envelope format (see Stage 6 below) preserving severity, autofix_class, owner, requires_verification, confidence, pre_existing, and suggested_fix per finding. Enrich with detail-tier fields (why_it_matters, evidence[]) from the per-agent artifact files on disk (see Detail enrichment in Stage 6).
@@ -311,7 +313,7 @@ Pass this to every reviewer in their spawn prompt. Intent shapes *how hard each
 
 **When intent is ambiguous:**
 
-- **Interactive mode:** Ask one question using the platform's interactive question tool (question in OpenCode, request_user_input in Codex): "What is the primary goal of these changes?" Do not spawn reviewers until intent is established.
+- **Interactive mode:** Ask one question using the platform's interactive question tool (`question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini; in Pi, use the blocking-question extension if available, otherwise present numbered options in chat and wait): "What is the primary goal of these changes?" Do not spawn reviewers until intent is established.
 - **Autofix/report-only/headless modes:** Infer intent conservatively from the branch name, diff, PR metadata, and caller context. Note the uncertainty in Coverage or Verdict reasoning instead of blocking.
 
 ### Stage 2b: Plan discovery (requirements verification)
@@ -634,7 +636,7 @@ After presenting findings and verdict (Stage 6), route the next steps by mode. R
 **Interactive mode**
 
 - Apply `safe_auto -> review-fixer` findings automatically without asking. These are safe by definition.
-- Ask a policy question **using the platform's blocking question tool** (`question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini) only when `gated_auto` or `manual` findings remain after safe fixes. Do not replace with a conversational open-ended question. Adapt the options to match what actually remains:
+- Ask a policy question **using the platform's blocking question tool** (`question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini; in Pi, use the blocking-question extension if available, otherwise present numbered options in chat and wait) only when `gated_auto` or `manual` findings remain after safe fixes. Do not replace with a conversational open-ended question. Adapt the options to match what actually remains:
 
   **When `gated_auto` findings are present** (with or without `manual`):
   ```

package/skills/deepen-plan/SKILL.md

@@ -22,7 +22,7 @@ This skill does **not** turn plans into implementation scripts. It identifies we
 
 ## Interaction Method
 
-Use the platform's question tool when available. When asking the user a question, prefer the platform's blocking question tool if one exists (`question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini). Otherwise, present numbered options in chat and wait for the user's reply before proceeding.
+Use the platform's question tool when available. When asking the user a question, prefer the platform's blocking question tool if one exists (`question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini; in Pi, use the blocking-question extension if available, otherwise present numbered options in chat and wait). Otherwise, present numbered options in chat and wait for the user's reply before proceeding.
 
 Ask one question at a time. Prefer a concise single-select choice when natural options exist.
 

package/skills/frontend-design/SKILL.md

@@ -53,7 +53,7 @@ Based on detected signals, choose a mode:
 
 ### Asking the User
 
-When context is ambiguous, use the platform's blocking question tool (`question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini). If no question tool is available, assume "partial" mode and proceed conservatively.
+When context is ambiguous, use the platform's blocking question tool (`question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini; in Pi, use the blocking-question extension if available, otherwise present numbered options in chat and wait). If no question tool is available, assume "partial" mode and proceed conservatively.
 
 Example question: "I found [detected signals]. Should I follow your existing design patterns or create something distinctive?"
 

package/skills/git-clean-gone-branches/SKILL.md

@@ -37,7 +37,7 @@ These local branches have been deleted from the remote:
 Delete all of them? (y/n)
 ```
 
-Wait for the user's answer using the platform's question tool (e.g., `question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini). If no question tool is available, present the list and wait for the user's reply before proceeding.
+Wait for the user's answer using the platform's question tool (e.g., `question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini; in Pi, use the blocking-question extension if available, otherwise present numbered options in chat and wait). If no question tool is available, present the list and wait for the user's reply before proceeding.
 
 This is a yes-or-no decision on the entire list -- do not offer multi-selection or per-branch choices.
 

package/skills/git-commit/SKILL.md

@@ -56,7 +56,7 @@ If both fail, fall back to `main`.
 
 If the git status from the context above shows a clean working tree (no staged, modified, or untracked files), report that there is nothing to commit and stop.
 
-If the current branch from the context above is empty, the repository is in detached HEAD state. Explain that a branch is required before committing if the user wants this work attached to a branch. Ask whether to create a feature branch now. Use the platform's blocking question tool (`question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini). If no question tool is available, present the options and wait for the user's reply before proceeding.
+If the current branch from the context above is empty, the repository is in detached HEAD state. Explain that a branch is required before committing if the user wants this work attached to a branch. Ask whether to create a feature branch now. Use the platform's blocking question tool (`question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini; in Pi, use the blocking-question extension if available, otherwise present numbered options in chat and wait). If no question tool is available, present the options and wait for the user's reply before proceeding.
 
 - If the user chooses to create a branch, derive the name from the change content, create it with `git checkout -b <branch-name>`, then run `git branch --show-current` again and use that result as the current branch name for the rest of the workflow.
 - If the user declines, continue with the detached HEAD commit.
@@ -80,7 +80,7 @@ Keep this lightweight:
 
 ### Step 4: Stage and commit
 
-If the current branch from the context above is `main`, `master`, or the resolved default branch from Step 1, warn the user and ask whether to continue committing here or create a feature branch first. Use the platform's blocking question tool (`question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini). If no question tool is available, present the options and wait for the user's reply before proceeding. If the user chooses to create a branch, derive the name from the change content, create it with `git checkout -b <branch-name>`, then continue.
+If the current branch from the context above is `main`, `master`, or the resolved default branch from Step 1, warn the user and ask whether to continue committing here or create a feature branch first. Use the platform's blocking question tool (`question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini; in Pi, use the blocking-question extension if available, otherwise present numbered options in chat and wait). If no question tool is available, present the options and wait for the user's reply before proceeding. If the user chooses to create a branch, derive the name from the change content, create it with `git checkout -b <branch-name>`, then continue.
 
 Write the commit message:
 - **Subject line**: Concise, imperative mood, focused on *why* not *what*. Follow the convention determined in Step 2.

package/skills/git-commit-push-pr/SKILL.md

@@ -7,7 +7,7 @@ description: Commit, push, and open a PR with an adaptive, value-first descripti
 
 Go from working changes to an open pull request, or rewrite an existing PR description.
 
-**Asking the user:** When this skill says "ask the user", use the platform's blocking question tool (`question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini). If unavailable, present the question and wait for a reply.
+**Asking the user:** When this skill says "ask the user", use the platform's blocking question tool (`question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini; in Pi, use the blocking-question extension if available, otherwise present numbered options in chat and wait). If unavailable, present the question and wait for a reply.
 
 ## Mode detection
 

package/skills/onboarding/SKILL.md

@@ -385,7 +385,7 @@ Write the file to the repo root as `ONBOARDING.md`.
 
 ### Phase 5: Present Result
 
-After writing, inform the user that `ONBOARDING.md` has been generated. Offer next steps using the platform's blocking question tool when available (`question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini). Otherwise, present numbered options in chat.
+After writing, inform the user that `ONBOARDING.md` has been generated. Offer next steps using the platform's blocking question tool when available (`question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini; in Pi, use the blocking-question extension if available, otherwise present numbered options in chat and wait). Otherwise, present numbered options in chat.
 
 Options:
 1. Open the file for review

package/skills/orchestrating-subagents/SKILL.md

@@ -1,125 +1,131 @@
 ---
 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.
+description: Use when dispatching parallel or serial subagents, 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, orchestrate a pipeline of dependent steps, or coordinate multiple agents without shared-file conflicts.
+metadata:
+  harness-portability: neutral-v1
 ---
 
 # Orchestrating Subagents
 
-Dispatch, coordinate, and synthesize results from OpenCode subagents using the `task()` primitive.
+Dispatch, coordinate, and synthesize results from subagents using the harness's delegation mechanism (see the active harness profile).
 
 ## The Portable Primitive
 
-Every subagent dispatch goes through `task()`:
+Every subagent dispatch should carry the same bounded brief, expressed through the active harness's delegation mechanism:
 
-```typescript
-task({
-  subagent_type: "systematic-implementer",
-  description: "Implement auth module",
-  prompt: "...",
-})
+```text
+Specialist: systematic-implementer
+Objective: Implement the auth module
+Scope: Make only the changes needed for the auth module.
+Return: List the changed files and summarize the implementation.
 ```
 
-**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
+**Required brief elements:**
+- **Specialist** — the registered agent or persona best suited to the work (for example, an implementer or researcher)
+- **Objective** — a concise statement of the outcome
+- **Scope** — full instructions, boundaries, dependencies, and files in scope
+- **Return** — the result format expected from the specialist
 
-**Optional:**
-- `task_id` — resume a prior subagent session instead of creating a new one
-- `command` — the slash command that triggered this task
+**Optional brief elements:**
+- **Session reference** — resume a prior specialist session instead of creating a new one, where the harness supports session reuse
+- **Trigger context** — the command or workflow that initiated the dispatch
 
-Foreground dispatch (no `background` parameter) blocks until the subagent returns its result. **This is the default and works on all OpenCode versions.**
+A foreground dispatch blocks until the specialist returns its result. Use the active harness profile to determine whether foreground, background, or other dispatch modes are available. Run independent dispatches concurrently where the harness supports it; otherwise dispatch sequentially in dependency order.
 
-## Background Dispatch (Experimental)
+## Background Dispatch (When Available)
 
-Background dispatch is gated by a runtime flag. It is **not available by default**.
+Background dispatch may be gated by a runtime capability or feature flag. Check the active harness profile and rely on whether the mechanism accepts background work.
 
-```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_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:** Passing `background: true` returns an error. Fall back to foreground dispatch — dispatch subagents serially or in small foreground batches instead.
+When background dispatch is available, it runs asynchronously and the harness reports the result to the parent session when the specialist completes. Do not poll or sleep.
 
-**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.
+When background dispatch is unavailable, fall back to foreground dispatch—serially or in small foreground batches.
 
 ## Serial vs Parallel Dispatch
 
 ### Serial (default, always safe)
 
-Dispatch one subagent, wait for its result, then dispatch the next. Use when:
+Dispatch one specialist, 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}`,
-})
+```text
+First dispatch:
+  Specialist: best-practices-researcher
+  Objective: Research caching patterns
+  Scope: Research Redis caching best practices for Rails APIs.
+  Return: Summarize recommendations and constraints.
+
+After the first result, dispatch:
+  Specialist: systematic-implementer
+  Objective: Implement caching
+  Scope: Implement caching based on the research result below.
+  Input: Include the first specialist's returned research.
+  Return: List changed files and summarize the implementation.
 ```
 
-### Parallel (foreground batches)
+Use the first specialist's returned research to guide the dependent implementation dispatch.
 
-Dispatch multiple foreground subagents in the same turn. OpenCode runs them concurrently when dispatched together. Use when:
+### Parallel (independent dispatches)
+
+Dispatch multiple independent specialists concurrently where the harness supports it. 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-reviewer", description: "Security review", prompt: "..." })
-task({ subagent_type: "performance-reviewer", description: "Performance review", prompt: "..." })
-task({ subagent_type: "correctness-reviewer", description: "Correctness review", prompt: "..." })
-// All three run; orchestrator synthesizes results after all complete
+```text
+Concurrent dispatch 1:
+  Specialist: security-reviewer
+  Objective: Perform a security review
+  Scope: Review the proposed changes for security issues.
+  Return: Findings with severity and file references.
+
+Concurrent dispatch 2:
+  Specialist: performance-reviewer
+  Objective: Perform a performance review
+  Scope: Review the proposed changes for performance issues.
+  Return: Findings with severity and file references.
+
+Concurrent dispatch 3:
+  Specialist: correctness-reviewer
+  Objective: Perform a correctness review
+  Scope: Review the proposed changes for functional issues.
+  Return: Findings with severity and file references.
 ```
 
+All three review dispatches run independently; the orchestrator synthesizes their 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.
+2. **No git index contention** — parallel specialists 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 specialists 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").
+If any check fails, downgrade to serial dispatch. Log the reason (for example, "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:
+When dispatching units in parallel, include these instructions in each specialist's brief:
 
 > 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:
+After specialists 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.
+1. **Wait for all** — in a parallel batch, wait for every specialist to finish before acting on any result.
+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.
 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.
+- If a specialist 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): 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`.
+- Retry a failed unit by re-dispatching with a corrected brief, or resume the prior specialist session where the harness supports session reuse.
+- For background work (when available): wait for the automatic completion notification (the result is delivered into the parent session). Do not poll or sleep. Retry by re-dispatching with a corrected brief, or resume the prior specialist session where the harness supports session reuse.
 
 ## Quick Reference
 
@@ -127,18 +133,18 @@ 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; results are pushed back to the parent on completion (no polling) |
+| Units are independent, no file overlap | Concurrent dispatch where supported; otherwise batched foreground dispatch |
+| Background available + long-running work | Concurrent 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` |
+| Specialist fails | Diagnose, correct the brief, then re-dispatch or resume the prior session where supported |
 | File collision detected post-parallel | Stage non-colliding files (if workflow owns git ops), re-run colliding units serially |
 
 ## Common Mistakes
 
 | Mistake | Fix |
 |---|---|
-| 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 |
+| Polling or sleeping to wait for background work | Background results are pushed into the parent session automatically; never poll or sleep |
+| 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 |
 | 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 the experimental flag enabled | Only use background when `OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true`; otherwise dispatch foreground |
+| Assuming background support without checking the active profile | Use background dispatch only when the active harness profile declares it available; otherwise dispatch in the foreground |

package/skills/report-bug-ce/SKILL.md

@@ -11,7 +11,7 @@ Report bugs encountered while using the Systematic plugin. This skill gathers st
 
 ## Step 1: Gather Bug Information
 
-Ask the user the following questions (using the platform's blocking question tool — e.g., `question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini — or present numbered options and wait for a reply):
+Ask the user the following questions (using the platform's blocking question tool — e.g., `question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini; in Pi, use the blocking-question extension if available, otherwise present numbered options in chat and wait — or present numbered options and wait for a reply):
 
 **Question 1: Bug Category**
 - What type of issue are you experiencing?

package/skills/reproduce-bug/SKILL.md

@@ -14,7 +14,7 @@ Fetch and analyze the bug report to extract structured information before touchi
 
 ### Fetch the issue
 
-If no issue number or URL was provided as an argument, ask the user for one before proceeding (using the platform's question tool -- e.g., `question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini -- or present a prompt and wait for a reply).
+If no issue number or URL was provided as an argument, ask the user for one before proceeding (using the platform's question tool -- e.g., `question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini; in Pi, use the blocking-question extension if available, otherwise present numbered options in chat and wait -- or present a prompt and wait for a reply).
 
 ```bash
 gh issue view $ARGUMENTS --json title,body,comments,labels,assignees
@@ -111,7 +111,7 @@ When the bug is reproduced:
 For bugs that require specific data conditions, user roles, external service state, or cannot be automated:
 
 1. Document what conditions are needed
-2. Ask the user (using the platform's question tool -- e.g., `question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini -- or present options and wait for a reply) whether they can set up the required conditions
+2. Ask the user (using the platform's question tool -- e.g., `question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini; in Pi, use the blocking-question extension if available, otherwise present numbered options in chat and wait -- or present options and wait for a reply) whether they can set up the required conditions
 3. Guide them through manual reproduction steps if needed
 
 ### If reproduction fails

package/skills/resolve-pr-feedback/SKILL.md

@@ -327,7 +327,7 @@ Still pending from a previous run (count):
 
 If a blocking question tool is available, use it to ask about all pending decisions (both new `needs-human` and previous-run pending) together. If there are only pending decisions and no new work was done, the summary is just the pending items.
 
-If a blocking question tool is available (`question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini), use it to present the decisions and wait for the user's response. After they decide, process the remaining items: fix the code, compose the reply, post it, and resolve the thread.
+If a blocking question tool is available (`question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini; in Pi, use the blocking-question extension if available, otherwise present numbered options in chat and wait), use it to present the decisions and wait for the user's response. After they decide, process the remaining items: fix the code, compose the reply, post it, and resolve the thread.
 
 If no question tool is available, present the decisions in the summary output and wait for the user to respond in conversation. If they don't respond, the items remain open on the PR for later handling.
 

package/skills/test-browser/SKILL.md

@@ -48,7 +48,7 @@ If not installed, inform the user: "`agent-browser` is not installed. Install it
 
 ### 2. Ask Browser Mode
 
-Ask the user whether to run headed or headless (using the platform's question tool — e.g., `question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini — or present options and wait for a reply):
+Ask the user whether to run headed or headless (using the platform's question tool — e.g., `question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini; in Pi, use the blocking-question extension if available, otherwise present numbered options in chat and wait — or present options and wait for a reply):
 
 ```
 Do you want to watch the browser tests run?

package/skills/using-systematic/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: using-systematic
 description: Use when starting any conversation - establishes how to find and use skills, requiring skill tool invocation before ANY response including clarifying questions
+metadata:
+  harness-portability: neutral-v1
 ---
 
 <SUBAGENT-STOP>
@@ -27,8 +29,6 @@ If CLAUDE.md, GEMINI.md, or AGENTS.md says "don't use TDD" and a skill says "alw
 
 ## How to Access Skills
 
-Use the `systematic_skill` tool for Systematic bundled skills. Use the `skill` tool for non-Systematic skills. When you invoke a skill, its content is loaded and presented to you—follow it directly.
-
 # Using Skills
 
 ## The Rule
@@ -106,6 +106,10 @@ The skill itself tells you which.
 
 Instructions say WHAT, not HOW. "Add X" or "Fix Y" doesn't mean skip workflows.
 
-## Skill Resolution
+## Capability Resolution
+
+The four capabilities are subagent delegation, blocking user interaction, task tracking, and skill loading.
+
+The bootstrap inlines the active harness profile naming the exact mechanisms—consult it. See `references/opencode-profile.md` and `references/pi-profile.md`.
 
-Systematic bundled skills are listed in the `systematic_skill` tool description. Use the `skill` tool for skills outside the Systematic plugin.
+When a mechanism is unavailable, present numbered options in chat and wait for questions, maintain a visible list for task tracking, and dispatch delegation sequentially or do the work inline.

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

@@ -0,0 +1,57 @@
+# OpenCode Capability Profile
+
+Evidence registry: see [`HARNESSES.md`](../../../HARNESSES.md).
+
+| Capability | Mechanism | Status | Fallback |
+|---|---|---|---|
+| Subagent delegation | `task()` tool; `subagent_type` selects a specialist, `task_id` resumes a session | supported; parallel and background dispatch may be available | Dispatch in the foreground, serially or in small batches |
+| Blocking user interaction | `question` tool | supported | Present numbered options in chat and wait |
+| Task tracking | `todowrite` | supported | Maintain a visible task list in responses |
+| Skill loading | `systematic_skill` for bundled skills; `skill` tool for non-Systematic skills | supported | Read the skill instructions listed by the active harness |
+
+## Invocation examples
+
+### Subagent delegation
+
+```typescript
+task({
+  subagent_type: "systematic-implementer",
+  description: "Implement auth module",
+  prompt: "Implement the auth module and return the changed files.",
+})
+
+// Background dispatch (run independent work concurrently; reconcile on completion):
+task({
+  subagent_type: "explorer",
+  description: "Map fixture patterns",
+  prompt: "…",
+  background: true,
+})
+
+// Resume a prior specialist session:
+task({ subagent_type: "fixer", task_id: "<prior-session-id>", description: "Resume fixer task", prompt: "…" })
+```
+
+### Blocking user interaction
+
+```typescript
+question({
+  questions: [{ question: "Which deployment target should I use?", header: "Deployment target",
+    options: [{ label: "Staging", description: "Deploy to staging" }] }],
+})
+```
+
+### Task tracking
+
+```typescript
+todowrite({
+  todos: [{ content: "Run validation", status: "pending", priority: "high" }],
+})
+```
+
+### Skill loading
+
+```typescript
+systematic_skill({ name: "systematic:using-systematic" })
+skill({ name: "external-skill" })
+```

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

@@ -0,0 +1,44 @@
+# Pi Capability Profile
+
+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 |
+| 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
+
+```typescript
+systematic_delegate({
+  agent: "systematic-implementer",
+  task: "Implement the auth module and return the changed files.",
+})
+```
+
+### Blocking user interaction
+
+```text
+1. Deploy to staging
+2. Deploy to production
+
+Reply with the number of your choice.
+```
+
+### Task tracking
+
+```text
+Task list:
+- [ ] Implement the auth module
+- [ ] Run validation
+```
+
+### Skill loading
+
+```typescript
+systematic_skill({ name: "systematic:using-systematic" })
+```