opencode-orchestrator-uni 0.3.0 → 0.4.0

package/index.ts

@@ -4,7 +4,7 @@
  * Registers the orchestrator agent kit — the `orchestrator` root agent with the
  * built-in audit loop, the read-only audit subagents (`factcheck`,
  * `empiric`, `invariant`, `arbiter`, `meta`,
- * `redteam`), and the `fix-runner` writer subagent — plus the `audit-kit`
+ * `redteam`, `context-lint`), and the `fix-runner` writer subagent — plus the `audit-kit`
  * document reference and the kit's deterministic `orch_uni_*` tools, straight from
  * this TypeScript entry point.
  *
@@ -24,6 +24,9 @@
  * - The `audit-kit` reference is registered only if that name is free; it points
  *   at this package's `docs/` directory so sessions can read the process
  *   documents directly.
+ * - Slash commands (`/agents-md`, `/spec`) are registered through
+ *   `ctx.command.transform`; their handlers inject a workflow prompt into the
+ *   current session and never write files themselves.
  *
  * Models are configuration, not definition: the agent files carry no `model`,
  * and the plugin applies models from its `plugins` entry options —
@@ -49,6 +52,7 @@ import path from "node:path"
 import { fileURLToPath } from "node:url"
 import type { Agent, Model, Plugin, Reference } from "@opencode/plugin"
 import matter from "gray-matter"
+import { registerKitCommands } from "./lib/commands"
 import { registerAuditTools } from "./lib/tools"
 
 /** Stable plugin id: diagnostics, enable/disable selectors, storage scope. */
@@ -114,10 +118,10 @@ function localeCandidates(): string[] {
 const REFERENCE_DESCRIPTIONS: Record<Locale, string> = {
   ru:
     "Процессные документы комплекта оркестратора (аудиторский цикл): call-mechanics.md, " +
-    "process-ready-loop.md, root-runbook.md, instruction-other-session.md.",
+    "process-ready-loop.md, root-runbook.md, instruction-other-session.md, context-efficiency.md.",
   en:
     "Process documents of the orchestrator agent kit (audit loop): call-mechanics.md, " +
-    "process-ready-loop.md, root-runbook.md, instruction-other-session.md.",
+    "process-ready-loop.md, root-runbook.md, instruction-other-session.md, context-efficiency.md.",
 }
 
 /** Frontmatter keys this loader understands; anything else is reported and ignored. */
@@ -404,9 +408,27 @@ async function setup(ctx: Plugin.Context): Promise<Plugin.Cleanup | undefined> {
   })
 
   // Deterministic, read-only audit tools: `orch_uni_validate_report`,
-  // `orch_uni_snapshot`, `orch_uni_sessions` (see `lib/tools.ts` and README «Tools»).
-  // The returned cleanup only stops the background session-index subscription.
-  return await registerAuditTools(ctx)
+  // `orch_uni_context_lint`, `orch_uni_snapshot`, `orch_uni_sessions` (see
+  // `lib/tools.ts` and README «Tools»). The tools cleanup only stops the
+  // background session-index subscription; the commands cleanup disposes the
+  // command transform registration. A failure after the tools are registered
+  // must abort that subscription too — otherwise a half-registered plugin leaks
+  // an event listener for the lifetime of the server.
+  const toolsCleanup = await registerAuditTools(ctx)
+  let commandsCleanup: Plugin.Cleanup
+  try {
+    commandsCleanup = await registerKitCommands(ctx, locale)
+  } catch (error) {
+    toolsCleanup()
+    throw error
+  }
+  return async () => {
+    try {
+      await commandsCleanup()
+    } finally {
+      toolsCleanup()
+    }
+  }
 }
 
 export default { id: PLUGIN_ID, setup } satisfies Plugin.Plugin

package/lib/commands.ts

@@ -0,0 +1,148 @@
+/**
+ * Slash commands of the kit: `/agents-md` and `/spec`.
+ *
+ * Commands are prompts, not writers: `execute` injects a short workflow prompt
+ * into the current session, and the orchestrator runs it with the usual
+ * evidence/approval rules. The detailed templates and checklists live in
+ * `docs/<locale>/context-efficiency.md`.
+ */
+import type { Plugin } from "@opencode/plugin"
+
+type CommandLocale = "ru" | "en"
+
+/** Arguments typed after the slash command, without a duplicated command token. */
+function commandArgs(text: string): string {
+  return text.replace(/^\s*\/(?:agents-md|spec)\b/i, "").trim()
+}
+
+const DESCRIPTIONS: Record<CommandLocale, { readonly agentsMd: string; readonly spec: string }> = {
+  ru: {
+    agentsMd: "Создать или проверить AGENTS.md по шаблону context-efficiency.md.",
+    spec: "Создать или проверить SPEC.md по шаблону context-efficiency.md.",
+  },
+  en: {
+    agentsMd: "Create or audit AGENTS.md using the context-efficiency.md template.",
+    spec: "Create or audit SPEC.md using the context-efficiency.md template.",
+  },
+}
+
+function agentsMdPrompt(locale: CommandLocale, goal: string): string {
+  if (locale === "ru") {
+    const audit = /(?<![\p{L}\p{N}_])(?:аудит|проверь|проверить)(?![\p{L}\p{N}_])/iu.test(goal)
+    return [
+      "[Команда /agents-md]",
+      `Цель: ${goal}.`,
+      "",
+      "Работай по документу context-efficiency.md из reference audit-kit.",
+      audit
+        ? "1. Это аудит: сначала вызови orch_uni_context_lint (если доступен), затем context-lint; покажи SGR и closing_list."
+        : "1. Это черновик: собери факты (стек, команды, границы, ловушки, never/ask, указатели); задай не более 8 вопросов.",
+      "2. Не выдумывай команды, пути и версии; всё непроверенное помечай.",
+      "3. Заполни шаблон AGENTS.md из context-efficiency.md; бюджет 150–200 строк.",
+      "4. Прогони context-lint, покажи diff и открытые вопросы.",
+      "5. Канонический AGENTS.md не меняй без подтверждения; правки — через fix-runner.",
+    ].join("\n")
+  }
+  const audit = /\b(?:audit|review|check)\b/i.test(goal)
+  return [
+    "[Command /agents-md]",
+    `Goal: ${goal}.`,
+    "",
+    "Follow context-efficiency.md from the audit-kit reference.",
+    audit
+      ? "1. This is an audit: run orch_uni_context_lint first (when available), then context-lint; show the SGR and closing_list."
+      : "1. This is a draft: collect facts (stack, commands, boundaries, traps, never/ask, pointers); ask at most 8 questions.",
+    "2. Do not invent commands, paths or versions; mark everything unverified.",
+    "3. Fill the AGENTS.md template from context-efficiency.md; keep the budget at 150–200 lines.",
+    "4. Run context-lint and show the diff plus open questions.",
+    "5. Do not change the canonical AGENTS.md without approval; apply fixes through fix-runner.",
+  ].join("\n")
+}
+
+function specPrompt(locale: CommandLocale, brief: string): string {
+  if (locale === "ru") {
+    return [
+      "[Команда /spec]",
+      `Фича: ${brief}.`,
+      "",
+      "Работай по документу context-efficiency.md из reference audit-kit.",
+      "1. Задай не более 5 уточняющих вопросов; non-goals, приоритеты и метрики утверждает владелец.",
+      "2. Заполни шаблон SPEC.md: контекст, цель, non-goals 3–7, сценарии, R1..Rn (EARS), AC с тестами, инварианты, контракты ссылками, NFR, SC, открытые вопросы, трассировка, DoD.",
+      "3. Прогони orch_uni_context_lint (если доступен) и context-lint; покажи diff и открытые вопросы.",
+      "4. Канонический SPEC.md не меняй без подтверждения; правки — через fix-runner.",
+    ].join("\n")
+  }
+  return [
+    "[Command /spec]",
+    `Feature: ${brief}.`,
+    "",
+    "Follow context-efficiency.md from the audit-kit reference.",
+    "1. Ask at most 5 clarifying questions; non-goals, priorities and success metrics are owned by the owner.",
+    "2. Fill the SPEC.md template: context, goal, 3–7 non-goals, scenarios, R1..Rn (EARS), AC with tests, invariants, contract links, NFRs, success metrics, open questions, traceability, DoD.",
+    "3. Run orch_uni_context_lint (when available) and context-lint; show the diff and open questions.",
+    "4. Do not change the canonical SPEC.md without approval; apply fixes through fix-runner.",
+  ].join("\n")
+}
+
+/** Register `/agents-md` and `/spec`; the cleanup disposes the transform registration. */
+export async function registerKitCommands(ctx: Plugin.Context, locale: CommandLocale): Promise<Plugin.Cleanup> {
+  // The command API is optional in a host build. A missing `list` was already
+  // tolerated; a missing `transform` used to throw out of `setup` and take every
+  // agent and tool with it, so it degrades to a warning plus a no-op cleanup.
+  const command = (ctx as Partial<Plugin.Context>).command
+  if (command === undefined || typeof command.transform !== "function") {
+    console.warn("orch-uni: this host has no command API; /agents-md and /spec are not registered")
+    return async () => {}
+  }
+  let existing = new Set<string>()
+  try {
+    const listed = await command.list()
+    existing = new Set(listed.data.map((item) => item.name))
+  } catch {
+    // No listing API: register; the host resolves a collision on its side.
+  }
+  const registration = await command.transform((editor) => {
+    if (!existing.has("agents-md")) {
+      editor.add({
+        name: "agents-md",
+        description: DESCRIPTIONS[locale].agentsMd,
+        execute: async (input) => {
+          await ctx.session.prompt({
+            sessionID: input.sessionID,
+            text: agentsMdPrompt(
+              locale,
+              commandArgs(input.prompt.text) || (locale === "ru" ? "текущий репозиторий" : "the current repository"),
+            ),
+            ...(input.prompt.files === undefined ? {} : { files: input.prompt.files }),
+            ...(input.prompt.agents === undefined ? {} : { agents: input.prompt.agents }),
+            ...(input.prompt.skills === undefined ? {} : { skills: input.prompt.skills }),
+            delivery: input.delivery,
+          })
+        },
+      })
+    }
+    if (!existing.has("spec")) {
+      editor.add({
+        name: "spec",
+        description: DESCRIPTIONS[locale].spec,
+        execute: async (input) => {
+          await ctx.session.prompt({
+            sessionID: input.sessionID,
+            text: specPrompt(
+              locale,
+              commandArgs(input.prompt.text) ||
+                (locale === "ru" ? "описание фичи не задано — спроси" : "no feature brief — ask for one"),
+            ),
+            ...(input.prompt.files === undefined ? {} : { files: input.prompt.files }),
+            ...(input.prompt.agents === undefined ? {} : { agents: input.prompt.agents }),
+            ...(input.prompt.skills === undefined ? {} : { skills: input.prompt.skills }),
+            delivery: input.delivery,
+          })
+        },
+      })
+    }
+  })
+  return async () => {
+    await registration.dispose()
+  }
+}