opencode-orchestrator-uni 0.3.1 → 0.4.0

package/docs/en/context-efficiency.md

@@ -0,0 +1,196 @@
+# Token-efficient AGENTS.md and SPEC.md
+
+An instruction file is a budget of attention, not documentation. Every line is paid for: it participates in every session's context and competes with the task. The goal is the minimum set of testable rules that cannot be inferred from the code and are needed in most sessions.
+
+## Budget
+
+| File | Target | Ceiling |
+|---|---:|---:|
+| Global `AGENTS.md` | 25–40 lines / <500 tokens | 60 lines |
+| Root `AGENTS.md` | 100–200 lines / 1–2k tokens | 200 lines |
+| Nested `AGENTS.md` | 20–60 lines / <700 tokens | 100 lines |
+| `SPEC.md` | 80–150 lines / ≤1.5k words | 2k words |
+| `ADR` | 30–60 lines / <700 tokens | 100 lines |
+
+`orch_uni_context_lint` applies one root budget (`max_lines`, 200 lines by default) and one SPEC word budget (`max_words`, 1500 by default — the target from the table; pass `max_words: 2000` for the ceiling). The per-level figures above are authoring guidance, not separate tool limits. The tool reports what it did not check (links outside the root, directories below depth 3, an unclosed fence) as INFO findings; a `pass` therefore never means "unverified".
+
+Selection rule: if a line is not testable, is inferable from code/linters, or is needed in fewer than half of sessions — delete it or move it to a link.
+
+## AGENTS.md: 12 rules
+
+1. Commands first: install, build, test, one test, lint, run; with flags and a working directory.
+2. Only the non-inferable: flags, traps, layer order, prohibitions, versions.
+3. One instruction per line, imperative, testable.
+4. Style belongs to the linter; do not restate the README or the language standard.
+5. Explicit "Never" and "Ask first": secrets, `dist/`, prod, migrations, dependencies.
+6. Precedence in the text: what overrides what; on a conflict, stop and ask.
+7. One source of truth: `AGENTS.md` plus a symlink/import for `CLAUDE.md`.
+8. Links instead of inline copies; inline only what is needed every time.
+9. Add a rule after a repeated agent mistake, not "for the future".
+10. Delete dead rules: they tax every request.
+11. Stable content on top, dates/branches/tasks at the bottom (prefix cache).
+12. Review the file as code; update it when tooling/CI changes.
+
+## AGENTS.md template
+
+```md
+# AGENTS.md
+
+## Precedence
+1. The user's explicit instruction in the task.
+2. `SPEC.md` of the active feature.
+3. The nearest `AGENTS.md`.
+4. This file.
+5. The global `AGENTS.md`.
+On a conflict, stop and ask.
+
+## Commands
+| Task | Command | Note |
+|---|---|---|
+| Install | `<...>` | `<version>` |
+| Build | `<...>` | `<flag>` |
+| Tests | `<...>` | `<limit>` |
+| One test | `<...>` | `<name>` |
+| Lint/types | `<...>` | |
+| Run | `<...>` | `<port>` |
+
+## Boundaries
+- `<path>/` is generated; do not edit.
+- `<path>/` is vendored; do not edit.
+- New files go to `<path>`.
+
+## Conventions
+- <One testable rule per line.>
+
+## Verification
+`<analyze>` → `<lint>` → `<test>`.
+Done = all commands green + `<DoD>`.
+
+## Never / ask first
+- Never: secrets, `dist/`, prod, applied migrations.
+- Ask first: DB schema, public API, new dependencies, CI.
+
+## Pointers
+- `SPEC.md` — the feature contract.
+- `docs/adr/` — decisions.
+- `docs/pitfalls.md` — traps.
+```
+
+## SPEC.md: 12 rules
+
+1. One feature per file, 1–3 pages; larger — split via a roadmap.
+2. Stable IDs (`R1`, `AC1.1`); never renumber.
+3. One requirement — one observable behavior.
+4. EARS or Given/When/Then — consistently; MUST/SHOULD/MAY — sparingly.
+5. No HOW: stack, files, classes belong in plan/design/ADR.
+6. Contracts as links, not copies.
+7. Non-goals: 3–7 items.
+8. Invariants separate from acceptance criteria.
+9. Tables for AC and traceability; prose for context only.
+10. Frontmatter: `status`, `owner`, `version`, `supersedes`; no changelog in the body.
+11. At most three open questions, each with an owner and a date; `TBD` elsewhere is forbidden.
+12. DoD and metrics are measurable; "faster" without a number does not count.
+
+## SPEC.md template
+
+```md
+---
+id: SPEC-000
+title: <name>
+status: draft
+owner: "@team"
+version: 1.0.0
+supersedes: —
+---
+
+# SPEC-000: <name>
+
+## 1. Context and problem
+<3–5 lines: who suffers, what hurts, why now.>
+
+## 2. Goal and non-goals
+**Goal:** <one sentence>.
+**Non-goals:** <3–7 items we deliberately do not do>.
+<!-- one item per line with `-` at 0–4 spaces; a wrapped paragraph is one item;
+     fenced, `<pre>` and bullets indented 5+ are code, not items. -->
+
+## 3. Scenarios
+| ID | Role | Goal | Value | Independent test |
+|---|---|---|---|---|
+| S1 | <...> | <...> | <...> | <...> |
+
+## 4. Requirements (EARS)
+- **R1** — WHEN <trigger>, THE SYSTEM SHALL <result>.
+- **R2** — IF <condition>, THEN THE SYSTEM SHALL <...>.
+
+## 5. Acceptance criteria
+| AC | R | Given | When | Then | Test |
+|---|---|---|---|---|---|
+| AC1.1 | R1 | <...> | <...> | <...> | `test_...` |
+
+## 6. Invariants and edge cases
+- Invariant: <always true>.
+- Empty/limit/concurrency/error: <...>.
+
+## 7. Contracts
+Links: `<openapi.yaml>`, `<schema.sql>`, `<types.ts>`.
+
+## 8. Non-functional requirements
+| Metric | Target | How we check |
+|---|---|---|
+| Latency p95 | <...> | <...> |
+
+## 9. Success metrics
+- **SC-1** — <number and how to check>.
+
+## 10. Open questions
+- **Q1** — <...>; owner: <...>; due <date>.
+
+## 11. Traceability
+| R | AC | Task | Test |
+|---|---|---|---|
+| R1 | AC1.1 | T1 | `test_...` |
+
+## 12. Definition of Done
+- [ ] AC closed.
+- [ ] Tests green.
+- [ ] Contracts and docs/ADR updated.
+```
+
+## Command /agents-md
+
+1. Decide the mode: audit an existing file or draft from scratch.
+2. For an audit: `orch_uni_context_lint` → `context-lint`; show the SGR and `closing_list`.
+3. For a draft: collect facts and ask at most 8 questions; do not invent commands or paths.
+4. Fill the template; stay within 150–200 lines.
+5. Run the linter; show the diff and open questions.
+6. Change the canonical file only after approval; apply fixes through `fix-runner`.
+
+## Command /spec
+
+1. Capture the brief and ask at most 5 clarifying questions.
+2. Non-goals, priorities and metrics are owned by the owner; do not invent them.
+3. Fill the template: EARS, AC with tests, invariants, traceability, DoD.
+4. Run `orch_uni_context_lint` and `context-lint`; show the diff and questions.
+5. Change the canonical file only after approval.
+
+## Review
+
+- [ ] `AGENTS.md` ≤200 lines, `SPEC.md` ≤1.5k words.
+- [ ] Every line is testable.
+- [ ] No duplicates with README/linter/CI.
+- [ ] Precedence and boundaries are explicit.
+- [ ] Every relative link exists.
+- [ ] Every R has an AC, every AC has a test.
+- [ ] Non-goals and DoD are present.
+- [ ] A baseline on 10–20 tasks exists.
+
+## Anti-patterns
+
+| Anti-pattern | Why it is bad | What to do |
+|---|---|---|
+| Auto-generation "just in case" | −0.5…−2% success, +20–23% cost | Write manually, high-signal only |
+| Restating README/architecture | Duplication, zero effect | Link to docs |
+| Duplicating the linter | Tokens on what is already checked | Linter/CI |
+| Generic phrases ("write clean code") | Not testable | Imperative + example |
+| Conflicts between layers | The model chooses arbitrarily | Explicit precedence |

package/docs/ru/context-efficiency.md

@@ -0,0 +1,196 @@
+# Token-efficient AGENTS.md и SPEC.md
+
+Файл инструкций — это бюджет внимания, а не документация. Оплачивается каждая строка: она участвует в контексте каждой сессии и конкурирует с задачей. Цель — минимум проверяемых правил, которые нельзя вывести из кода и которые нужны в большинстве сессий.
+
+## Бюджет
+
+| Файл | Цель | Потолок |
+|---|---:|---:|
+| Глобальный `AGENTS.md` | 25–40 строк / <500 токенов | 60 строк |
+| Корневой `AGENTS.md` | 100–200 строк / 1–2k токенов | 200 строк |
+| Вложенный `AGENTS.md` | 20–60 строк / <700 токенов | 100 строк |
+| `SPEC.md` | 80–150 строк / ≤1,5k слов | 2k слов |
+| `ADR` | 30–60 строк / <700 токенов | 100 строк |
+
+`orch_uni_context_lint` применяет один бюджет корня (`max_lines`, по умолчанию 200 строк) и бюджет слов SPEC (`max_words`, по умолчанию 1500 — цель из таблицы; потолок 2k включается через `max_words: 2000`). Цифры по уровням выше — ориентир для автора, а не отдельные лимиты инструмента. Инструмент сообщает о том, что не проверял (ссылки вне корня, каталоги глубже глубины 3, незакрытый фенс), INFO-находками, поэтому `pass` никогда не означает «непроверено».
+
+Правило отбора: если строка не проверяема, выводима из кода/линтера или нужна реже половины сессий — удалить либо вынести в ссылку.
+
+## AGENTS.md: 12 правил
+
+1. Команды — в начало: install, build, test, one test, lint, run; с флагами и рабочей директорией.
+2. Только невыводимое: флаги, ловушки, порядок слоёв, запреты, версии.
+3. Одна инструкция — одна строка, императив, проверяемо.
+4. Стиль — линтеру; не пересказывать README и стандарт языка.
+5. Явные «Never» и «Ask first»: секреты, `dist/`, prod, миграции, зависимости.
+6. Приоритеты — в тексте: что переопределяет что; при конфликте — остановись и спроси.
+7. Один источник правды: `AGENTS.md` + симлинк/импорт для `CLAUDE.md`.
+8. Ссылки вместо инлайна; инлайнить только то, что нужно всегда.
+9. Правило добавлять после повторной ошибки агента, а не «на будущее».
+10. Мёртвое правило удалять: это налог на каждый запрос.
+11. Стабильное — вверх, даты/ветки/задачи — вниз (prefix cache).
+12. Ревьюить файл как код; менять при смене тулинга/CI.
+
+## Шаблон AGENTS.md
+
+```md
+# AGENTS.md
+
+## Приоритеты
+1. Явное указание пользователя в задаче.
+2. SPEC.md активной фичи.
+3. Ближайший AGENTS.md.
+4. Этот файл.
+5. Глобальный AGENTS.md.
+При конфликте — остановись и спроси.
+
+## Команды
+| Задача | Команда | Примечание |
+|---|---|---|
+| Установка | `<...>` | `<версия>` |
+| Сборка | `<...>` | `<флаг>` |
+| Тесты | `<...>` | `<лимит>` |
+| Один тест | `<...>` | `<имя>` |
+| Линт/типы | `<...>` | |
+| Запуск | `<...>` | `<порт>` |
+
+## Границы
+- `<path>/` — сгенерировано, не редактировать.
+- `<path>/` — вендорное, не редактировать.
+- Новые файлы — в `<path>`.
+
+## Конвенции
+- <Одно проверяемое правило на строку.>
+
+## Проверка
+`<analyze>` → `<lint>` → `<test>`.
+Готово = все команды зелёные + `<DoD>`.
+
+## Никогда / сначала спроси
+- Никогда: секреты, `dist/`, prod, применённые миграции.
+- Сначала спроси: схема БД, публичный API, новые зависимости, CI.
+
+## Указатели
+- `SPEC.md` — контракт фичи.
+- `docs/adr/` — решения.
+- `docs/pitfalls.md` — ловушки.
+```
+
+## SPEC.md: 12 правил
+
+1. Одна фича — один файл, 1–3 страницы; больше — split через roadmap.
+2. Стабильные ID (`R1`, `AC1.1`), не перенумеровывать.
+3. Одно требование — одно наблюдаемое поведение.
+4. EARS или Given/When/Then — единообразно; MUST/SHOULD/MAY — редко.
+5. Никакого HOW: стек, файлы, классы — в plan/design/ADR.
+6. Контракты — ссылками, не копиями.
+7. Non-goals — 3–7 пунктов.
+8. Инварианты — отдельно от acceptance criteria.
+9. Таблицы — для AC и трассировки; проза — для контекста.
+10. Frontmatter: `status`, `owner`, `version`, `supersedes`; без changelog в теле.
+11. Не более трёх открытых вопросов, у каждого owner и дата; `TBD` в других местах запрещён.
+12. DoD и метрики — измеримые; «быстрее» без числа не считается.
+
+## Шаблон SPEC.md
+
+```md
+---
+id: SPEC-000
+title: <название>
+status: draft
+owner: "@team"
+version: 1.0.0
+supersedes: —
+---
+
+# SPEC-000: <название>
+
+## 1. Контекст и проблема
+<3–5 строк: кто страдает, в чём боль, почему сейчас.>
+
+## 2. Цель и non-goals
+**Цель:** <одно предложение>.
+**Non-goals:** <3–7 пунктов «сознательно не делаем»>.
+<!-- один пункт на строку с `-` и отступом 0–4; перенесённый абзац — один пункт;
+     фенс, `<pre>` и bullet с отступом 5+ — код, не пункт. -->
+
+## 3. Сценарии
+| ID | Роль | Цель | Ценность | Независимый тест |
+|---|---|---|---|---|
+| S1 | <...> | <...> | <...> | <...> |
+
+## 4. Требования (EARS)
+- **R1** — WHEN <триггер>, THE SYSTEM SHALL <результат>.
+- **R2** — IF <условие>, THEN THE SYSTEM SHALL <...>.
+
+## 5. Acceptance criteria
+| AC | R | Given | When | Then | Test |
+|---|---|---|---|---|---|
+| AC1.1 | R1 | <...> | <...> | <...> | `test_...` |
+
+## 6. Инварианты и краевые случаи
+- Инвариант: <всегда истинно>.
+- Пусто/лимит/конкурентность/ошибка: <...>.
+
+## 7. Контракты
+Ссылки: `<openapi.yaml>`, `<schema.sql>`, `<types.ts>`.
+
+## 8. Нефункциональные требования
+| Метрика | Цель | Как проверяем |
+|---|---|---|
+| Latency p95 | <...> | <...> |
+
+## 9. Метрики успеха
+- **SC-1** — <число и способ проверки>.
+
+## 10. Открытые вопросы
+- **Q1** — <...>; owner: <...>; до <дата>.
+
+## 11. Трассировка
+| R | AC | Task | Test |
+|---|---|---|---|
+| R1 | AC1.1 | T1 | `test_...` |
+
+## 12. Definition of Done
+- [ ] AC закрыты.
+- [ ] Тесты зелёные.
+- [ ] Контракты и docs/ADR обновлены.
+```
+
+## Команда /agents-md
+
+1. Определи режим: аудит существующего файла или черновик с нуля.
+2. Для аудита: `orch_uni_context_lint` → `context-lint`; покажи SGR и `closing_list`.
+3. Для черновика: собери факты и задай не более 8 вопросов; не выдумывай команды и пути.
+4. Заполни шаблон; уложись в 150–200 строк.
+5. Прогони линтер, покажи diff и открытые вопросы.
+6. Канонический файл меняй только после подтверждения; правки — через `fix-runner`.
+
+## Команда /spec
+
+1. Зафиксируй бриф и задай не более 5 уточняющих вопросов.
+2. Non-goals, приоритеты и метрики утверждает владелец; не придумывай их.
+3. Заполни шаблон: EARS, AC с тестами, инварианты, трассировка, DoD.
+4. Прогони `orch_uni_context_lint` и `context-lint`; покажи diff и вопросы.
+5. Канонический файл меняй только после подтверждения.
+
+## Ревью
+
+- [ ] `AGENTS.md` ≤200 строк, `SPEC.md` ≤1,5k слов.
+- [ ] Каждая строка проверяема.
+- [ ] Нет дублей с README/линтером/CI.
+- [ ] Приоритеты и границы прописаны.
+- [ ] Все относительные ссылки существуют.
+- [ ] У каждого R есть AC, у каждого AC есть тест.
+- [ ] Non-goals и DoD на месте.
+- [ ] Есть baseline на 10–20 задачах.
+
+## Анти-паттерны
+
+| Анти-паттерн | Почему плохо | Что делать |
+|---|---|---|
+| Автогенерация «на всякий случай» | −0,5…−2% успеха, +20–23% косты | Писать вручную, только высокосигнальное |
+| Пересказ README/архитектуры | Дублирование, нулевой эффект | Ссылка на docs |
+| Дублирование линтера | Токены на то, что и так проверяется | Линтер/CI |
+| Общие фразы («пиши чисто») | Непроверяемо | Императив + пример |
+| Противоречия между уровнями | Модель выбирает произвольно | Явные приоритеты |

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()
+  }
+}