@pi-ohm/subagents 0.3.0-dev.22083116751.1.d12e548

package/README.md

@@ -0,0 +1,20 @@
+# @pi-ohm/subagents
+
+Install only subagent delegation support for Pi.
+
+```bash
+pi install npm:@pi-ohm/subagents
+```
+
+Scaffolded subagents:
+
+- `librarian` — multi-repo code understanding
+- `oracle` — reasoning-heavy advisor/reviewer
+- `finder` — intelligent behavior-based search
+- `task` — isolated parallel execution worker
+- `painter` — explicit-request image generation/editing helper
+
+Commands:
+
+- `/ohm-subagents`
+- `/ohm-subagent <id>`

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@pi-ohm/subagents",
+  "version": "0.3.0-dev.22083116751.1.d12e548",
+  "type": "module",
+  "main": "src/extension.ts",
+  "types": "src/extension.ts",
+  "files": [
+    "src/",
+    "README.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/extension.ts"
+    ]
+  },
+  "dependencies": {
+    "@mariozechner/pi-coding-agent": "^0.52.0",
+    "@pi-ohm/config": "0.3.0-dev.22083116751.1.d12e548"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/src/catalog.ts

@@ -0,0 +1,80 @@
+export type OhmSubagentId = "librarian" | "oracle" | "finder" | "task" | "painter";
+
+export interface OhmSubagentDefinition {
+  id: OhmSubagentId;
+  name: string;
+  summary: string;
+  whenToUse: string[];
+  scaffoldPrompt: string;
+  requiresPackage?: string;
+}
+
+export const OHM_SUBAGENT_CATALOG: readonly OhmSubagentDefinition[] = [
+  {
+    id: "librarian",
+    name: "Librarian",
+    summary: "Multi-repo codebase understanding subagent (GitHub/Bitbucket architecture analysis).",
+    whenToUse: [
+      "Understand architecture across multiple repositories",
+      "Build implementation maps before migration/refactor",
+      "Trace ownership boundaries across services",
+    ],
+    scaffoldPrompt:
+      "Analyze this codebase (and linked repos if provided). Build an architecture map: boundaries, key modules, integration points, and risky coupling.",
+  },
+  {
+    id: "oracle",
+    name: "Oracle",
+    summary:
+      "Reasoning-heavy advisor for code review, architecture feedback, complex debugging, and planning.",
+    whenToUse: [
+      "Get second-opinion architecture critique",
+      "Review risky design decisions before implementation",
+      "Debug ambiguous failures with hypothesis ranking",
+    ],
+    scaffoldPrompt:
+      "Act as a critical reviewer. Challenge assumptions, rank risks, and provide a concrete implementation plan with trade-offs.",
+  },
+  {
+    id: "finder",
+    name: "Finder",
+    summary: "Concept/behavior-based search subagent for multi-step codebase discovery.",
+    whenToUse: [
+      "Find all call sites for a behavior, not just symbol references",
+      "Map data flow across modules",
+      "Locate implicit coupling and duplicated logic",
+    ],
+    scaffoldPrompt:
+      "Search this codebase for all implementations and call paths related to the requested behavior. Return files, rationale, and confidence.",
+  },
+  {
+    id: "task",
+    name: "Task",
+    summary: "Independent execution subagent for parallelizable tasks with isolated tool context.",
+    whenToUse: [
+      "Parallelize work across unrelated app areas",
+      "Delegate focused implementation tasks",
+      "Run isolated experiments without polluting main context",
+    ],
+    scaffoldPrompt:
+      "Execute this focused implementation task independently. Return a concise summary of changes, validation, and follow-up risks.",
+  },
+  {
+    id: "painter",
+    name: "Painter",
+    summary: "Image generation/editing subagent used only on explicit request.",
+    whenToUse: [
+      "Generate concept/mock images",
+      "Edit existing images based on prompt instructions",
+      "Produce visual assets when user explicitly asks for image output",
+    ],
+    scaffoldPrompt:
+      "Generate or edit an image per user request. Confirm intent first, then return prompt + provider/model metadata with result notes.",
+    requiresPackage: "@pi-ohm/painter",
+  },
+] as const;
+
+export function getSubagentById(id: string): OhmSubagentDefinition | undefined {
+  const needle = id.trim().toLowerCase();
+  return OHM_SUBAGENT_CATALOG.find((agent) => agent.id === needle);
+}

package/src/extension.ts

@@ -0,0 +1,128 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { loadOhmRuntimeConfig, registerOhmSettings } from "@pi-ohm/config";
+import { getSubagentById, OHM_SUBAGENT_CATALOG } from "./catalog";
+
+function normalizeCommandArgs(args: unknown): string[] {
+  if (Array.isArray(args)) {
+    return args.filter((value): value is string => typeof value === "string");
+  }
+
+  if (typeof args === "string") {
+    return args
+      .split(/\s+/)
+      .map((part) => part.trim())
+      .filter((part) => part.length > 0);
+  }
+
+  if (args && typeof args === "object") {
+    const asRecord = args as { args?: unknown; raw?: unknown };
+
+    if (Array.isArray(asRecord.args)) {
+      return asRecord.args.filter((value): value is string => typeof value === "string");
+    }
+
+    if (typeof asRecord.raw === "string") {
+      return asRecord.raw
+        .split(/\s+/)
+        .map((part) => part.trim())
+        .filter((part) => part.length > 0);
+    }
+  }
+
+  return [];
+}
+
+export default function registerSubagentsExtension(pi: ExtensionAPI): void {
+  registerOhmSettings(pi);
+
+  pi.on("session_start", async (_event, ctx) => {
+    const { config } = await loadOhmRuntimeConfig(ctx.cwd);
+    if (!ctx.hasUI) return;
+
+    const enabled = config.features.subagents ? "on" : "off";
+    ctx.ui.setStatus("ohm-subagents", `subagents:${enabled} · backend:${config.subagentBackend}`);
+  });
+
+  pi.registerCommand("ohm-subagents", {
+    description: "Show scaffolded subagents and backend status",
+    handler: async (_args, ctx) => {
+      const { config, loadedFrom } = await loadOhmRuntimeConfig(ctx.cwd);
+
+      const lines = OHM_SUBAGENT_CATALOG.map((agent) => {
+        const needsPainterPackage = agent.id === "painter";
+        const available = !needsPainterPackage || config.features.painterImagegen;
+        const availability = available ? "available" : "requires painter feature/package";
+        return `- ${agent.name} (${agent.id}): ${agent.summary} [${availability}]`;
+      });
+
+      const text = [
+        "Pi OHM: subagents",
+        "",
+        `enabled: ${config.features.subagents ? "yes" : "no"}`,
+        `backend: ${config.subagentBackend}`,
+        "",
+        "Scaffolded subagents:",
+        ...lines,
+        "",
+        "Use /ohm-subagent <id> to inspect one profile.",
+        `loadedFrom: ${loadedFrom.length > 0 ? loadedFrom.join(", ") : "defaults + extension settings"}`,
+      ].join("\n");
+
+      if (!ctx.hasUI) {
+        console.log(text);
+        return;
+      }
+
+      await ctx.ui.editor("pi-ohm subagents", text);
+    },
+  });
+
+  pi.registerCommand("ohm-subagent", {
+    description: "Inspect one subagent scaffold (librarian|oracle|finder|task|painter)",
+    handler: async (args, ctx) => {
+      const { config } = await loadOhmRuntimeConfig(ctx.cwd);
+      const [requested = ""] = normalizeCommandArgs(args);
+      const match = getSubagentById(requested);
+
+      if (!match) {
+        const usage = [
+          "Usage: /ohm-subagent <id>",
+          "",
+          `Valid ids: ${OHM_SUBAGENT_CATALOG.map((agent) => agent.id).join(", ")}`,
+        ].join("\n");
+
+        if (!ctx.hasUI) {
+          console.log(usage);
+          return;
+        }
+
+        await ctx.ui.editor("pi-ohm subagent usage", usage);
+        return;
+      }
+
+      const isAvailable = match.id !== "painter" || config.features.painterImagegen;
+
+      const text = [
+        `Subagent: ${match.name}`,
+        `id: ${match.id}`,
+        `available: ${isAvailable ? "yes" : "no"}`,
+        match.requiresPackage
+          ? `requiresPackage: ${match.requiresPackage}`
+          : "requiresPackage: none",
+        "",
+        "When to use:",
+        ...match.whenToUse.map((line) => `- ${line}`),
+        "",
+        "Scaffold prompt:",
+        match.scaffoldPrompt,
+      ].join("\n");
+
+      if (!ctx.hasUI) {
+        console.log(text);
+        return;
+      }
+
+      await ctx.ui.editor(`pi-ohm ${match.id} subagent`, text);
+    },
+  });
+}