@ngockhoale/ukit 2.1.5 → 2.2.1

package/templates/.claude/commands/ukit/handoff-fullstack.md

@@ -1,7 +1,7 @@
 # /ukit:handoff-fullstack — Full Pipeline: Plan → Implement → Review
 
 **Role: ORCHESTRATOR**
-**Tool: any** (Claude Code / Codex / Kilo / OpenCode — your choice)
+**Tool: any** (Claude Code / Codex / omp / Kilo / OpenCode — your choice)
 
 ## Model Split
 
@@ -13,6 +13,8 @@
 
 > Claude Code: spawn `ukit-small-task-maintainer` (haiku) for light steps; spawn `handoff-planner` (opus) for planning; spawn `feature-implementer` (sonnet) agents for implementation; spawn `code-reviewer` (opus) per task for review.
 
+> **omp model tiers:** the tiers above map to `.omp/config.yml`'s `modelRoles`, referenced from agent frontmatter as `@lite` / `@code` / `@smart`.
+
 ---
 
 ## Problem / feature
@@ -86,7 +88,7 @@ Only when `RUN.md` is absent or `Phase: done` does `$ARGUMENTS` start a fresh cy
 
 ### P1 — Read context (lite model)
 
-**Claude Code — MANDATORY, do this before anything else in P1:** call the Agent tool with `subagent_type: "ukit-small-task-maintainer"`. Do NOT read these files yourself in the current session — this step is contracted to the lite tier (haiku/unic-lite), which only the spawned agent's frontmatter model guarantees. Ask it to return a compact summary of:
+**Claude Code — MANDATORY, do this before anything else in P1:** call the Agent tool with `subagent_type: "ukit-small-task-maintainer"` (omp: the `task` tool with `agent: "ukit-small-task-maintainer"`). Do NOT read these files yourself in the current session — this step is contracted to the lite tier (haiku/unic-lite), which only the spawned agent's frontmatter model guarantees. Ask it to return a compact summary of:
 
 1. `docs/AI_HANDOFF/INDEX.md` — current tasks + statuses (or "empty / no tasks")
 2. `docs/AI_HANDOFF/ACTIVE.md` — active cycle info (or "no active cycle")
@@ -99,7 +101,7 @@ Return a compact summary. Do NOT write any files yet.
 
 ### P2 — Write PLAN.md + task files (strong model)
 
-**Claude Code — MANDATORY, do this before anything else in P2:** call the Agent tool with `subagent_type: "handoff-planner"`, passing it the P1 summary and `$ARGUMENTS`. Do NOT write PLAN.md or task files yourself in the current session — this step is contracted to the strong tier (opus/unic-smart), which only the spawned agent's frontmatter model guarantees.
+**Claude Code — MANDATORY, do this before anything else in P2:** call the Agent tool with `subagent_type: "handoff-planner"` (omp: the `task` tool with `agent: "handoff-planner"`), passing it the P1 summary and `$ARGUMENTS`. Do NOT write PLAN.md or task files yourself in the current session — this step is contracted to the strong tier (opus/unic-smart), which only the spawned agent's frontmatter model guarantees.
 
 The planner agent does the following (use P1 summary — do NOT re-read files):
 
@@ -160,7 +162,7 @@ The planner agent does the following (use P1 summary — do NOT re-read files):
 The gate still does its job — two independent opus passes shape the plan before a line of code
 is written. What it no longer does is hand a stalled plan back to a human who isn't there.
 
-**Claude Code — MANDATORY, do this before anything else in P2.5:** call the Agent tool with `subagent_type: "code-reviewer"`, passing `REVIEW_TARGET_TYPE=plan` and the path to `docs/AI_HANDOFF/PLAN.md`. This MUST be a separate agent invocation from P2's `handoff-planner` call (fresh context) — same-session self-review defeats the purpose of an independent gate.
+**Claude Code — MANDATORY, do this before anything else in P2.5:** call the Agent tool with `subagent_type: "code-reviewer"` (omp: the `task` tool with `agent: "code-reviewer"`), passing `REVIEW_TARGET_TYPE=plan` and the path to `docs/AI_HANDOFF/PLAN.md`. This MUST be a separate agent invocation from P2's `handoff-planner` call (fresh context) — same-session self-review defeats the purpose of an independent gate.
 
 1. Reviewer reads `PLAN.md` only (no diff, no task files, no executor report), checks Completeness / Consistency / Clarity / Scope / YAGNI — see `.claude/agents/code-reviewer.md` → Spec/Plan Review — and appends its verdict to PLAN.md's `## Plan Review Log` (new round entry, prior rounds kept).
 2. `Issues Found` → route back to P2: `handoff-planner` revises `PLAN.md` and the affected `TASK-xxx.md` files to address every finding, then re-submit for one more P2.5 review round — subject to the loop cap above.
@@ -170,7 +172,7 @@ is written. What it no longer does is hand a stalled plan back to a human who is
 
 ### P3 — Commit the plan (lite model)
 
-**Claude Code — MANDATORY:** call the Agent tool with `subagent_type: "ukit-small-task-maintainer"` for this commit step (lite tier — haiku/unic-lite). Run:
+**Claude Code — MANDATORY:** call the Agent tool with `subagent_type: "ukit-small-task-maintainer"` (omp: the `task` tool with `agent: "ukit-small-task-maintainer"`) for this commit step (lite tier — haiku/unic-lite). Run:
 ```bash
 git add docs/AI_HANDOFF/ && git commit -m "handoff: plan — <goal>"
 ```
@@ -185,7 +187,7 @@ Replace `<goal>` with the one-sentence goal from ACTIVE.md. This locks the plan
 
 ### I1 — Setup + verify (lite model)
 
-**Claude Code — MANDATORY:** call the Agent tool with `subagent_type: "ukit-small-task-maintainer"` for I1. Ask it to read:
+**Claude Code — MANDATORY:** call the Agent tool with `subagent_type: "ukit-small-task-maintainer"` (omp: the `task` tool with `agent: "ukit-small-task-maintainer"`) for I1. Ask it to read:
 - `docs/AI_HANDOFF/ACTIVE.md` → get `Base: <BASE>`
 - `docs/AI_HANDOFF/INDEX.md` → collect all `ready` tasks
 
@@ -234,7 +236,7 @@ leaves worktrees behind. Batching only ever narrows a wave, never reorders acros
 
 ### I3 — Execute wave by wave (code model agents)
 
-**Claude Code — MANDATORY, do this before anything else in I3:** for each wave, call the Agent tool once per task **in the current batch** (in parallel, at most `handoff.maxParallelAgents`), each with `subagent_type: "feature-implementer"`. Do NOT implement the tasks yourself in the current session — this step is contracted to the code tier (sonnet/unic-code), which only the spawned agent's frontmatter model guarantees.
+**Claude Code — MANDATORY, do this before anything else in I3:** for each wave, call the Agent tool once per task **in the current batch** (in parallel, at most `handoff.maxParallelAgents`), each with `subagent_type: "feature-implementer"` (omp: the `task` tool with `agent: "feature-implementer"`, likewise invoked once per task in the batch, not once per wave). Do NOT implement the tasks yourself in the current session — this step is contracted to the code tier (sonnet/unic-code), which only the spawned agent's frontmatter model guarantees.
 
 For each wave:
 
@@ -356,7 +358,7 @@ logs used to cost. That difference is what makes a multi-wave cycle finish in on
 
 ### I4 — Consolidate + update INDEX (lite model)
 
-**Claude Code — MANDATORY:** call the Agent tool with `subagent_type: "ukit-small-task-maintainer"` for I4. After all waves complete, ask it to:
+**Claude Code — MANDATORY:** call the Agent tool with `subagent_type: "ukit-small-task-maintainer"` (omp: the `task` tool with `agent: "ukit-small-task-maintainer"`) for I4. After all waves complete, ask it to:
 
 1. Update `docs/AI_HANDOFF/INDEX.md`:
    - PASS tasks → `pending_review`
@@ -376,7 +378,7 @@ logs used to cost. That difference is what makes a multi-wave cycle finish in on
 
 ### R1 — Setup (lite model)
 
-**Claude Code — MANDATORY:** call the Agent tool with `subagent_type: "ukit-small-task-maintainer"` for the R1 reads. Ask it to read:
+**Claude Code — MANDATORY:** call the Agent tool with `subagent_type: "ukit-small-task-maintainer"` (omp: the `task` tool with `agent: "ukit-small-task-maintainer"`) for the R1 reads. Ask it to read:
 - `docs/AI_HANDOFF/ACTIVE.md` → get `Base: <BASE>`
 - `docs/AI_HANDOFF/INDEX.md` → collect `pending_review` tasks
 
@@ -400,7 +402,7 @@ If that diff is empty → implement was not completed. Do not stop: re-enter Pha
 
 **Batch the review set — mandatory.** Read `handoff.maxParallelAgents` from `.ukit/storage/config.json`. If more `pending_review` tasks exist than that, split into consecutive batches of at most that many; finish one batch's verdicts (R2–R4, appended to each task file) before starting the next.
 
-**Claude Code — MANDATORY, do this before anything else in R2–R4:** for each batch, call the Agent tool once per `pending_review` task **in parallel** (at most `handoff.maxParallelAgents`), each with `subagent_type: "code-reviewer"`. Reviewer agents only read the diff and append a verdict to their own task file — no worktree, no shared write target — so running them in parallel carries none of Phase 3's file-conflict risk. Do NOT review the diff yourself in the current session — this step is contracted to the strong tier (opus/unic-smart) and MUST differ from the executor's model, which only the spawned agent's frontmatter model guarantees.
+**Claude Code — MANDATORY, do this before anything else in R2–R4:** for each batch, call the Agent tool once per `pending_review` task **in parallel** (at most `handoff.maxParallelAgents`), each with `subagent_type: "code-reviewer"` (omp: the `task` tool with `agent: "code-reviewer"`, likewise invoked once per task in the batch, not once per wave). Reviewer agents only read the diff and append a verdict to their own task file — no worktree, no shared write target — so running them in parallel carries none of Phase 3's file-conflict risk. Do NOT review the diff yourself in the current session — this step is contracted to the strong tier (opus/unic-smart) and MUST differ from the executor's model, which only the spawned agent's frontmatter model guarantees.
 
 The spawned reviewer agent reads `EXECUTOR_MODEL` from each task file `## Executor Report`:
 

package/templates/.claude/commands/ukit/handoff-implement.md

@@ -1,9 +1,11 @@
 # /ukit:handoff-implement — Phase 3: Execute
 
 **Role: EXECUTOR (orchestrated)**
-**Tool: any** (Claude Code / Codex / Antigravity / Kilo / OpenCode — your choice)
+**Tool: any** (Claude Code / Codex / omp / Kilo / OpenCode — your choice)
 **Model: code model** (Sonnet · unic-code · cheap-smart)
 
+> **omp model tiers:** the tiers above map to `.omp/config.yml`'s `modelRoles`, referenced from agent frontmatter as `@lite` / `@code` / `@smart`.
+
 ## Target (optional)
 $ARGUMENTS
 _Empty = all `ready` tasks. Or: "TASK-001" for a specific task._
@@ -117,7 +119,7 @@ git worktree add -b handoff/task-xxx .worktrees/task-xxx $BASE
 
 ### 3b — Run tasks in parallel (one agent/session per task)
 
-**Claude Code — MANDATORY, do this before anything else in this wave:** call the Agent tool once per task **in the current batch** (in parallel, at most `handoff.maxParallelAgents`), each with `subagent_type: "feature-implementer"`. Do NOT implement the tasks yourself in the current session — this step is contracted to the code tier (sonnet/unic-code), which only the spawned agent's frontmatter model guarantees.
+**Claude Code — MANDATORY, do this before anything else in this wave:** call the Agent tool once per task **in the current batch** (in parallel, at most `handoff.maxParallelAgents`), each with `subagent_type: "feature-implementer"` (omp: the `task` tool with `agent: "feature-implementer"`, likewise invoked once per task in the batch, not once per wave). Do NOT implement the tasks yourself in the current session — this step is contracted to the code tier (sonnet/unic-code), which only the spawned agent's frontmatter model guarantees.
 
 Each spawned agent works independently in its own worktree — **NO git commit, NO git add**:
 

package/templates/.claude/commands/ukit/handoff-review.md

@@ -1,9 +1,11 @@
 # /ukit:handoff-review — Phase 4: Review
 
 **Role: REVIEWER**
-**Tool: any** (Claude Code / Codex / Antigravity / Kilo / OpenCode — your choice)
+**Tool: any** (Claude Code / Codex / omp / Kilo / OpenCode — your choice)
 **Model: strong model, MUST differ from executor** (Opus · unic-smart · strongest available)
 
+> **omp model tiers:** the tiers above map to `.omp/config.yml`'s `modelRoles`, referenced from agent frontmatter as `@lite` / `@code` / `@smart`.
+
 ## Target (optional)
 $ARGUMENTS
 _Empty = all `pending_review` tasks. Or: "TASK-001" for a specific task._
@@ -52,7 +54,7 @@ If that diff is empty → handoff-implement was not completed. Report which task
 
 **Batch the review set — mandatory.** Read `handoff.maxParallelAgents` from `.ukit/storage/config.json`. If more `pending_review` tasks exist than that, split into consecutive batches of at most that many; finish one batch's verdicts (2a–2d, appended to each task file) before starting the next.
 
-**Claude Code — MANDATORY, do this before anything else:** for each batch, call the Agent tool once per `pending_review` task **in parallel** (at most `handoff.maxParallelAgents`), each with `subagent_type: "code-reviewer"`. Reviewer agents only read the diff and append a verdict to their own task file — no worktree, no shared write target — so running them in parallel carries none of Phase 3's file-conflict risk. Do NOT review the diff yourself in the current session — this step is contracted to the strong tier (opus/unic-smart) and MUST differ from the executor's model, which only the spawned agent's frontmatter model guarantees. Pass each agent: the task file path, the executor's report, and the diff.
+**Claude Code — MANDATORY, do this before anything else:** for each batch, call the Agent tool once per `pending_review` task **in parallel** (at most `handoff.maxParallelAgents`), each with `subagent_type: "code-reviewer"` (omp: the `task` tool with `agent: "code-reviewer"`, likewise invoked once per task in the batch, not once per wave). Reviewer agents only read the diff and append a verdict to their own task file — no worktree, no shared write target — so running them in parallel carries none of Phase 3's file-conflict risk. Do NOT review the diff yourself in the current session — this step is contracted to the strong tier (opus/unic-smart) and MUST differ from the executor's model, which only the spawned agent's frontmatter model guarantees. Pass each agent: the task file path, the executor's report, and the diff.
 
 The spawned reviewer agent performs 2a–2d below per task:
 

package/templates/.claude/ukit/index/route-catalog.mjs

@@ -256,7 +256,7 @@ export const ROUTE_CATALOG = [
     signals: [
       { type: 'prompt', regex: /\b(stale|refresh|cleanup|reinstall|maintenance|workspace drift|index freshness|out of date)\b/i, score: 4 },
       { type: 'command', regex: /\bukit install\b|\brefresh-index\.mjs\b|\bbuild-index\.mjs\b/i, score: 3 },
-      { type: 'file', regex: /\.claude\/|\.codex\/|\.antigravity\//i, score: 1 },
+      { type: 'file', regex: /\.claude\/|\.codex\/|\.antigravity\/|\.omp\//i, score: 1 },
     ],
   },
   {

package/templates/.claude/ukit/index/unic-gateway.mjs

@@ -13,14 +13,27 @@
  *   1. process.env.ANTHROPIC_BASE_URL                        -> 'env'
  *   2. project .claude/settings.json -> env.ANTHROPIC_BASE_URL -> 'claude-settings'
  *   3. ~/.claude/settings.json -> env.ANTHROPIC_BASE_URL       -> 'claude-settings'
+ *   4. process.env.OMP_BASE_URL (TASK-004, name unverified)   -> 'omp-env'
+ *   5. project .omp/config.yml -> baseUrl (TASK-004, key unverified) -> 'omp-config'
  *
- * Cross-tool configs are NOT probed. This module is only ever invoked from Claude Code hooks
- * (vision-router.sh, vision-gate.sh, route-task.mjs) to gate what THIS session does — a Codex
- * `config.toml` `base_url`, a Kilo `secrets.json` endpoint, or an `OPENAI_BASE_URL` env var
- * describe a completely different tool's outbound endpoint and say nothing about where Claude
- * Code itself is sending requests. Treating them as evidence produced permanent false positives
- * (any machine with Codex/Kilo pointed at the UNIC gateway would report `unicMode: true` for
- * every plain Claude Code session, deadlocking Edit/Write on any image-mentioning turn).
+ * Every probe here (including the two omp probes) is scoped to what changes the CALLING
+ * runtime's OWN outbound endpoint — same rule that already governs probes 1-3. Cross-tool
+ * configs are NOT probed. This module is only ever invoked from Claude Code / omp hooks
+ * (vision-router.sh, vision-gate.sh, route-task.mjs, and the omp bridge) to gate what THIS
+ * session does — a Codex `config.toml` `base_url`, a Kilo `secrets.json` endpoint, or an
+ * `OPENAI_BASE_URL` env var describe a completely different tool's outbound endpoint and say
+ * nothing about where Claude Code or omp itself is sending requests. Treating them as evidence
+ * produced permanent false positives (any machine with Codex/Kilo pointed at the UNIC gateway
+ * would report `unicMode: true` for every plain Claude Code session, deadlocking Edit/Write on
+ * any image-mentioning turn).
+ *
+ * Fail-safe direction (do not re-flip this): `unicMode` keeps BINARY semantics on every runtime
+ * — `unicMode = sources.length > 0`, default `false`. Inconclusive detection never resolves to
+ * `true`. The "assume UNIC when ambiguous" fail-safe some tools want belongs ONLY to the static
+ * `modelRoles` values TASK-003 writes unconditionally into `templates/.omp/config.yml`
+ * (`@vision: unic-vision`, no probe involved) — never to this module's boolean, because this
+ * module is shared by every runtime and flipping its default would make Codex/Kilo/OPENAI_BASE_URL
+ * sessions with zero omp/Claude signal start false-positively reporting UNIC mode.
  *
  * Contract: this module must NEVER throw and must NEVER exit non-zero, in any case (missing files,
  * malformed JSON, unreadable paths, etc. all degrade to a clean "no hit").
@@ -38,6 +51,22 @@ import { fileURLToPath } from 'node:url';
 const UNIC_TOKEN = 'unicjsc.com';
 const VISION_MODEL_ALIAS = 'unic-vision';
 
+// TODO(verify): omp's own base-URL env var name is a guess -- omp is not installed on this
+// machine and no source/schema is vendored, so this has never been confirmed against a real
+// omp runtime. Resolve via TASK-008's manual smoke test before treating this as confirmed.
+const OMP_BASE_URL_ENV_VAR = 'OMP_BASE_URL';
+
+// TODO(verify): the `.omp/config.yml` key path (`baseUrl`, top-level) is a guess for the same
+// reason as OMP_BASE_URL_ENV_VAR above. Deliberately matched with a narrow anchored regex
+// instead of importing the `yaml` package at runtime -- this file is installed into end-user
+// projects via `ukit install` and must not risk depending on `yaml` being resolvable from a
+// target project's own node_modules tree for a single-key check. This mirrors the codebase's
+// own established precedent for the analogous Codex `config.toml` probe (see git history:
+// CODEX_BASE_URL_UNIC_RE, pre-TASK-007), which rejected a TOML parser dependency for the same
+// reason and documented the trade-off: a malformed/unexpected file just degrades to no hit,
+// which fails safe rather than throwing.
+const OMP_CONFIG_BASE_URL_UNIC_RE = /^\s*baseUrl\s*:\s*["']?[^"'\r\n#]*unicjsc\.com[^"'\r\n#]*["']?\s*(?:#.*)?$/m;
+
 function safeReadFile(filePath) {
   try {
     return fs.readFileSync(filePath, 'utf8');
@@ -84,6 +113,14 @@ function probeClaudeSettings(filePath) {
   return typeof value === 'string' && value.includes(UNIC_TOKEN);
 }
 
+// Narrow anchored regex probe (no YAML parsing) for the omp config file's `baseUrl` key. A
+// missing file, unreadable path, or malformed YAML all degrade to "no hit" -- never throws.
+function probeOmpConfig(filePath) {
+  const raw = safeReadFile(filePath);
+  if (raw == null) return false;
+  return OMP_CONFIG_BASE_URL_UNIC_RE.test(raw);
+}
+
 /**
  * Checks whether the Codex model catalog exists and, if so, whether it lists `unic-vision`.
  * A missing/unreadable/malformed catalog is never an error — it degrades to "unknown" and the
@@ -126,6 +163,8 @@ export function detectUnicGateway(options = {}) {
     () => recordHit(probeEnvVar('ANTHROPIC_BASE_URL'), 'env'),
     () => recordHit(probeClaudeSettings(path.join(rootDir, '.claude', 'settings.json')), 'claude-settings'),
     () => recordHit(probeClaudeSettings(path.join(homeDir, '.claude', 'settings.json')), 'claude-settings'),
+    () => recordHit(probeEnvVar(OMP_BASE_URL_ENV_VAR), 'omp-env'),
+    () => recordHit(probeOmpConfig(path.join(rootDir, '.omp', 'config.yml')), 'omp-config'),
   ];
   for (const probe of probes) {
     try {

package/templates/.codex/README.md

@@ -8,7 +8,7 @@ Auto-generated by UKit for OpenAI Codex.
 ## Core UKit Rule
 
 - Human-facing workflow should optimize for one remembered command: `ukit install`.
-- After install, normal work should feel natural inside **Claude/Codex/OpenCode** (and Antigravity when installed).
+- After install, normal work should feel natural inside **Claude/Codex/OpenCode/omp**.
 - **Quality first, then speed, then token discipline**: do not waste reads, logs, or repeated helper output.
 - **Never stop after read-only steps.** For implement/apply/fix requests, continue to actual Edit/Write and verification in the same turn.
 

package/templates/.gitignore

@@ -46,9 +46,11 @@ Thumbs.db
 .claude/ukit/permission-usage.json
 .claude/ukit/permission-audit.log
 .cache/
+# legacy: Antigravity adapter removed in v2.2.0; leftovers must stay ignored
 .antigravity/
 .claude/
 .codex/
+.omp/
 .ukit/
 opencode.json
 AGENTS.md

package/templates/.omp/AGENTS.md

@@ -0,0 +1,9 @@
+# .omp/AGENTS.md — thin import, not a copy
+
+This file exists only so omp's native `.omp/AGENTS.md` provider (priority 100) does not shadow the
+project-root `AGENTS.md` (agents-md provider, priority 10) with duplicated content. omp resolves `@`
+imports relative to this file's own directory, so the single import line below pulls in the real,
+single-source-of-truth project instructions from the repo root. Do not inline root `AGENTS.md`'s body
+here — that would make root `AGENTS.md` stop loading on omp and let the two drift silently.
+
+@../AGENTS.md

package/templates/.omp/README.md

@@ -0,0 +1,96 @@
+# omp (Oh My Pi) adapter — {{project.name}}
+
+UKit installs this workspace so that [omp](https://omp.sh) gets the same guardrails, agents and
+context that Claude Code gets — without a second copy of the logic to keep in sync.
+
+Stack: {{project.stack}} · package manager: `{{runtime.packageManager}}`
+
+## What `ukit install` puts here
+
+Eleven files, all managed by UKit. Re-running `ukit install` overwrites them and keeps a backup of
+whatever was there before, so local edits are never silently lost — they move, they do not vanish.
+
+| Path | What it is |
+|------|------------|
+| `.omp/AGENTS.md` | Thin context entry point. Imports the root `AGENTS.md` (`@../AGENTS.md`) rather than duplicating it. |
+| `.omp/RULES.md` | Sticky hard rules that must survive compaction. |
+| `.omp/config.yml` | Model roles, tool approval policy, dangerous-command patterns, memory and compact settings. |
+| `.omp/README.md` | This file. |
+| `.omp/hooks/pre/ukit-bridge.js` | Translates omp events into Claude Code hook payloads and runs the real `.claude/hooks/*.sh` scripts. |
+| `.omp/agents/bug-debugger.md` | Debugging lane. |
+| `.omp/agents/code-reviewer.md` | Independent review lane. |
+| `.omp/agents/feature-implementer.md` | Implementation lane. |
+| `.omp/agents/handoff-planner.md` | Handoff planning lane. |
+| `.omp/agents/ukit-small-task-maintainer.md` | Low-risk chores lane. |
+| `.omp/agents/ukit-vision-analyst.md` | The only lane allowed to interpret images. |
+
+## Model roles
+
+`.omp/config.yml` defines four roles. Agent frontmatter references them as `@lite` / `@code` /
+`@smart` / `@vision`, so retargeting a whole tier is a one-line edit in one file.
+
+| Role | Default model | Agents using it |
+|------|---------------|-----------------|
+| `lite` | `unic-lite` | `ukit-small-task-maintainer` |
+| `code` | `unic-code` | `feature-implementer`, `bug-debugger` |
+| `smart` | `unic-smart` | `handoff-planner`, `code-reviewer` |
+| `vision` | `unic-vision` | `ukit-vision-analyst` |
+
+These are **literal model names on the UNIC gateway, not aliases**, and they ship as the installed
+default. If this project does not run against UNIC, a maintainer swaps the three cost tiers for the
+values in `orchestration.modelTiers[*].claudeModel` in `.ukit/storage/config.json`.
+
+`vision` is the exception and stays `unic-vision` either way: it is a *capability* lane, not a cost
+tier. `unic-code` and `unic-smart` cannot read images on this gateway, so substituting one of them
+would not downgrade image analysis — it would silently produce guesses.
+
+## The six agents are shared with Claude Code
+
+The agent names here are verbatim the same as the ones under `.claude/agents/`, so the same
+instruction ("hand this to the code reviewer") routes to the same role on either runtime.
+
+What differs is only the frontmatter contract: omp reads task agents from `.omp/agents/` and
+deliberately skips `.claude/agents/*.md`, and its model field takes a `@role` reference instead of a
+model id. The prompt bodies are ported, not rewritten.
+
+## The hook bridge
+
+`.omp/hooks/pre/ukit-bridge.js` does not reimplement any guardrail. It maps an omp event to the
+matching Claude Code hook payload and executes the existing shell script under `.claude/hooks/`.
+One source of truth, two runtimes — fix a hook once and both runtimes get the fix.
+
+Two things worth knowing:
+
+**Tool names are mapped explicitly, never guessed.** omp's write surface is `edit`, `write` *and*
+`ast_edit`; all three map to the `Edit` group, or `ast_edit` would slip past `protect-files.sh` and
+`vision-gate.sh`. `eval` maps to `Bash` so it still hits `block-dangerous.sh`. Anything not in the
+table maps to nothing and runs zero scripts — it never falls back to `Bash` or `Edit`.
+
+**Failure direction is per-script, transcribed from each script's own header — not a blanket rule.**
+
+- *Fail closed* (a crash or non-zero exit blocks the action): `protect-files.sh`,
+  `stale-spec-guard.sh`, `handoff-model-guard.sh`, `vision-gate.sh`, `context-hardcap-gate.sh`,
+  `block-dangerous.sh`, `verification-guard.sh`. These are gates; a broken gate must not open.
+- *Fail open* (a crash logs a warning and the action proceeds): the advisory scripts —
+  routing, backups, output compression, context reinjection, pressure reset, handoff resume.
+  These improve a session; none of them should be able to halt one.
+
+## Why there is no `.omp/skills/` or `.omp/commands/`
+
+Their absence is deliberate, not an oversight — and if you "fix" it, a test will fail on purpose.
+
+omp discovers capabilities from several providers in priority order, and its `claude` provider
+already reads `.claude/skills/` and `.claude/commands/` directly. A copy or symlink under `.omp/`
+would register at higher (native) priority, win deduplication, and give you a second location to
+keep in sync for exactly zero new capability.
+
+`.omp/agents/` is the one case that *must* be real files, because omp explicitly does not read
+`.claude/agents/*.md`.
+
+## Installing / removing
+
+```bash
+ukit install --tools=omp          # or --tools=oh-my-pi
+ukit install                      # installs every adapter, omp included
+ukit uninstall                    # removes the paths listed above
+```

package/templates/.omp/RULES.md

@@ -0,0 +1,34 @@
+# .omp/RULES.md — sticky always-apply rules
+
+omp re-attaches this file near every turn from its native location (`.omp/RULES.md` only, never a
+copy elsewhere). It carries the always-apply subset of root `CLAUDE.md` that omp's claude provider
+cannot see — that provider only reads `~/.claude/CLAUDE.md` and `<cwd>/.claude/CLAUDE.md`, never root
+`CLAUDE.md`. Keep this short: every line here is a per-turn tax.
+
+## 1. Execution Contract
+
+For implement/apply/fix requests, continue until the actual edit is made or a real blocker is found.
+Do not stop after a read-only inspection step (read/grep/glob/search).
+
+## 2. No "done" after read-only
+
+Never say "done", "applied", or "fixed" after a read-only step. Completion wording requires concrete
+edit/write evidence in the current turn, plus verification when the change is risky.
+
+## 3. Index-first loop
+
+Check `.cache/index/` freshness first. Then run
+`node .claude/ukit/index/query-index.mjs "<error|symbol|path>"` and open only the top 1-3 suspect
+files before widening further. These node scripts work unchanged under omp.
+
+## 4. Safe Patch
+
+Prefer unique current-file anchors over line numbers or stale pasted blocks. Never silently merge a
+stale spec — re-read current source and confirm before applying. Preserve existing BOM and line
+endings.
+
+## Model roles (see `.omp/config.yml`)
+
+`modelRoles` ships UNIC gateway names as the default. A maintainer on a non-UNIC omp provider edits
+only the three cost-tier values — `lite`, `code`, `smart` — never `vision`, which stays `unic-vision`
+because it is a capability lane, not a cost tier.

package/templates/.omp/agents/bug-debugger.md

@@ -0,0 +1,85 @@
+---
+name: bug-debugger
+description: "Debugging specialist for reproducible errors, failing tests, and unexpected behavior. Use proactively when investigation will involve noisy logs, stack traces, or a self-contained reproduce-trace-fix-verify loop. Do not use for trivial obvious fixes or broad architecture ideation."
+model: "@code"
+tools: ["read","grep","glob","bash","edit","ast_edit"]
+---
+
+Systematic debugging — understand before fixing.
+
+**Two modes:**
+- **Daily/ad-hoc** (DEFAULT): bug not coming from `docs/AI_HANDOFF/` → reproduce → fix → verify (no mandatory regression test if no pre-existing coverage; original lightweight flow).
+- **Handoff mode**: bug task lives in `docs/AI_HANDOFF/tasks/TASK-xxx.md` → activate Quality Gate: regression-test-first → green → reviewer.
+
+## Workflow
+
+### 1. Reproduce (required)
+
+- Run the failing command/action.
+- Capture exact error message and stack trace.
+- If not reproducible → document conditions and ask user.
+
+### 2. Trace Root Cause
+
+- Read error location and surrounding code.
+- Trace data flow: input → processing → failure point.
+- Identify: logic / state / integration error?
+
+### 3. Regression Test First (RED) — Handoff mode
+
+- Write a regression test that reproduces the bug as a failing test.
+- Run it: must FAIL with the original error/signature.
+- If you truly cannot write a regression test (pure UI glitch, env-only issue), document why and attach a manual repro script.
+- **Daily mode**: write a regression test only if the file already has tests; otherwise rely on the original repro command for verification.
+
+### 4. Fix (GREEN)
+
+- Apply smallest reliable fix at the root cause.
+- Do NOT patch symptoms — fix the cause.
+- Re-run the regression test: must PASS.
+
+### 5. Verify
+
+- Re-run the original failing command → must pass.
+- Run related tests: `yarn test [relevant-file]`.
+- If shared code touched, run wider suite.
+- Check no regression in adjacent functionality.
+
+### 6. Report
+
+```
+STATUS: DONE | BLOCKED | PARTIAL
+EXECUTOR_TOOL: [claude-code | kilo-code | codex | opencode | other]
+EXECUTOR_MODEL: [exact model name you are running as. "unknown" if you cannot tell.]
+EXECUTOR_SUBAGENT: [subagent name within your host, if any, else "-"]
+SUMMARY: [1-2 sentences — root cause and fix]
+ROOT_CAUSE: [what caused the bug]
+REGRESSION_TEST:
+  file: [path]
+  red_before: [exact error captured]
+  green_after: [pass output line]
+FILES_CHANGED:
+  - [file path]: [what changed]
+VERIFICATION:
+  command: [exact command]
+  result: [N pass / M fail / exit code]
+ISSUES: [any remaining risks or edge cases, or "none"]
+HANDOFF_TO_REVIEWER: yes | no — reason
+NEXT: [follow-up needed, or "ready for review"]
+```
+
+### 7. Trigger Reviewer — Handoff mode ONLY
+
+Daily mode: skip. Handoff mode: set task status `pending_review` in `INDEX.md`; a reviewer session (model from `handoff.reviewer.model`, MUST differ from this debugger's model) will pick it up.
+
+## Rules
+
+- **Iron law (Handoff mode):** no `DONE` without (a) regression test passing and (b) original failing command passing, both in this turn.
+- **Daily mode:** original — original failing command must pass; regression test optional unless prior coverage exists.
+- Don't patch blindly — confirm root cause with evidence.
+- For bug triage, use graduated doc budget:
+  - obvious/simple bug: `docs/MEMORY.md` only
+  - non-trivial bug: `docs/MEMORY.md` + `docs/PROJECT.md` + `docs/CODE_MAP.md`
+  - read `docs/WORKLOG.md` only recent relevant entries
+- Keep fix scope minimal — no drive-by refactors.
+- If root cause is unclear after 5 minutes of tracing → ask user for more context.