@ngockhoale/ukit 2.1.5 → 2.2.2

package/templates/AGENTS.md

@@ -1,16 +1,16 @@
 # AGENTS.md — {{project.name}}
 
-## Core UKit Rule
+## Core 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).
-- **Quality first, then speed, then token discipline**: do not waste reads, logs, or repeated helper output.
+- Human-facing UKit workflow should collapse to one remembered command: `ukit install`.
+- After install, default to natural-language work inside **Claude Code / Codex / OpenCode / omp**.
+- **Quality first, then speed, then token discipline.**
 - **Never stop after read-only steps.** For implement/apply/fix requests, continue to actual Edit/Write and verification in the same turn.
 
-## Fast Task Classification
+## Fast Classification
 
-- **Trivial** — typo, label, rename nhỏ, spacing, toggle flag, obvious config change.
-  - Act directly. No doc reads. No planning. No index.
+- **Trivial** — typo, label, small rename, spacing, toggle flag, obvious config change.
+  - Act directly. No doc reads. No planning. No index. No agents.
 - **Simple** — 1-2 files, clear scope, existing pattern.
   - Handle directly. Pull only the smallest useful context via resolver or targeted read.
 - **Non-trivial / Risky** — auth, security, migration, uninstall, shared runtime, race/flaky, data-loss.
@@ -44,11 +44,14 @@ For clearly non-code specialist lanes (docs-only, status, task queue), skip the
 ## Automatic Skill Activation (mandatory)
 
 - End users should not need to know skill names.
-- For every non-trivial task — and again after the first relevant tool calls — inspect installed project-local skills and **auto-activate the matching skill immediately**.
+- On every non-trivial task — and again after the first relevant tool calls — inspect installed project-local skills and **auto-activate the matching skill immediately**.
 - Match from both prompt wording and tool/file evidence.
 - Use the smallest effective set, usually 1-2 skills.
 - If evidence becomes more specific than the original prompt, upgrade the active skill choice immediately.
-- Prefer routed, compact context before widening manual reads.
+- If docs work is detected, read `.claude/skills/docs-quality/SKILL.md` when present.
+- Prefer routed context and routed verification over ad-hoc broad reading.
+- Reuse `.claude/ukit/skill-router-state.json` when it already carries compact route memory.
+- If shared route state already includes `previous-context` or `recent-output`, reuse those first.
 
 ### Common skill triggers
 
@@ -61,51 +64,65 @@ For clearly non-code specialist lanes (docs-only, status, task queue), skip the
 - auth / security / token / permission / validation / risky shell-path-delete-db work → `.claude/skills/discover-security/SKILL.md`
 - stale workspace / reinstall / cleanup / maintenance → `.claude/skills/repo-maintenance/SKILL.md`
 
-## Internal Helper Routing
+## Internal Helper Policy
 
-- If routing is complex or ambiguous, prefer the canonical helper first: `node .claude/ukit/index/route-task.mjs "<prompt>" [--tool-command <cmd>] [--target <file>]`.
-- If context is needed, prefer `node .claude/ukit/index/resolve-context.mjs ...`.
-- If a concrete verification lane is needed, prefer `node .claude/ukit/index/verify-context.mjs ...`.
-- These helper/index commands are internal orchestration. Run them yourself when needed; never turn them into required end-user workflow.
+- Prefer `node .claude/ukit/index/route-task.mjs "<prompt>" [--tool-command <cmd>] [--target <file>]` when routing is complex or ambiguous.
+- Prefer `node .claude/ukit/index/resolve-context.mjs ...` for indexed related-file context.
+- Prefer `node .claude/ukit/index/verify-context.mjs ...` for concrete verification lanes.
+- **Do not ask normal contributors to run internal helper commands**; run them yourself or tell them to rerun `ukit install`.
+- Do not ask normal contributors to memorize `ukit doctor`, `ukit diff`, `ukit uninstall`, or `ukit index ...` unless they explicitly need maintainer/debug help.
+- If the workspace needs a refresh, prefer telling them to rerun `ukit install`.
+
+## Skill Quality (maintainer-only)
+
+- When editing a template skill/agent under `templates/.claude/`, read `.claude/skills/skill-quality/SKILL.md` before shipping the change.
 
-## UKit v1.5.1 Shared Runtime
+## UKit v{{ukit.version}} Shared Runtime
 
 - Shared runtime state lives in `.ukit/storage/`.
 - Treat `.ukit/storage/config.json` as the source of runtime toggles for compact, token pipeline, router, memory, validation, and Safe Patch behavior.
-- Reuse `.ukit/storage/memory/` before asking users to restate prior decisions.
+- Reuse `.ukit/storage/memory/` before asking users to restate decisions.
 - For non-trivial work, prefer `ukit memory recall "<current task>"` before widening doc reads.
-- Reusable runtime cache lives in `.ukit/storage/cache/prompt-cache.json`, `.ukit/storage/cache/compact-history.json`, `.ukit/storage/cache/compact-pressure.json`, `.ukit/storage/cache/output-history.json`, and preserved raw tool outputs under `.ukit/storage/cache/tee/`.
+- Reusable cache/compact/output state lives in `.ukit/storage/cache/prompt-cache.json`, `.ukit/storage/cache/compact-history.json`, `.ukit/storage/cache/compact-pressure.json`, `.ukit/storage/cache/output-history.json`, and preserved raw tool outputs under `.ukit/storage/cache/tee/`.
 - Shared route memory lives in `.claude/ukit/skill-router-state.json`.
-- If shared route state already includes compact `previous-context` or `recent-output` lines, reuse those first before rescanning memory or replaying noisy logs.
+- If shared route state already includes compact `previous-context` or `recent-output`, reuse those first.
 - If an older repo still has a visible `ukit/` runtime root, rerun `ukit install`; UKit should migrate the shared runtime into hidden `.ukit/` when safe.
 - Maintainers can inspect runtime state with `ukit status` and `ukit memory export`, but normal teammates should still only need `ukit install`.
-- If runtime files are missing/corrupt, tell maintainers to rerun `ukit install`.
+- If runtime files are missing or corrupt, tell maintainers to rerun `ukit install`.
 - Threshold-based compact pressure is internal orchestration; do not expose it to users.
 - For Codex Desktop long sessions, UKit can use soft auto-compact handoffs. Default `compact.codexContext.compactTarget=150` means about 150 compact handoff lines (120-150 preferred, hard max 170), not 150 tokens.
 
-## Handoff Quality Gate — OPT-IN
+## Safe Patch Protocol
+
+- Safe Patch is internal orchestration: normal users still only need `ukit install` and natural language.
+- For risky/shared/large edits, prefer unique current-file anchors over line numbers or stale pasted blocks.
+- Do not silently merge stale specs: if `old_string` is missing or ambiguous, re-read current source and ask whether to apply as-is, adapt, or skip.
+- Preserve UTF-8 BOM/no-BOM and LF/CRLF for existing multilingual/user-authored files.
+- Use `node .claude/ukit/index/safe-patch.mjs` internally when normal Edit/Write may normalize bytes or when anchor-based matching is needed.
 
-Activates ONLY when work goes through `docs/AI_HANDOFF/` (user says "execute task TASK-xxx" or target is `docs/AI_HANDOFF/tasks/*.md`). Daily prompts → unchanged lightweight flow, no test-first/reviewer overhead.
+## Handoff Quality Gate — OPT-IN
 
-In Handoff mode: read `docs/AI_HANDOFF/RULES.md` for the 4-phase spec (Idea+Plan → Create Tasks → Implement+Test → Review+Test), state machine, comment thread, and self-reported model contract. Config: `.ukit/storage/config.json` → `handoff.*`.
+CHỈ kích hoạt khi task đi qua `docs/AI_HANDOFF/` (user nói "execute task TASK-xxx" hoặc target là `docs/AI_HANDOFF/tasks/*.md`). Daily prompt → KHÔNG đụng, flow cũ giữ nguyên.
 
+Khi Handoff mode: đọc `docs/AI_HANDOFF/RULES.md` để biết 4 phase (Idea+Plan → Create Tasks → Implement+Test → Review+Test) + state machine + comment thread + self-report model. Config: `.ukit/storage/config.json` → `handoff.*`.
 
 ## Context + Verification Budget
 
-- **Trivial**: no docs, no index query unless the file target is unclear.
-- **Simple**: default to `docs/MEMORY.md` only; pull related files/tests with the resolver.
-- **Non-trivial**: read `docs/MEMORY.md` + `docs/PROJECT.md` + `docs/CODE_MAP.md`.
-- `docs/STATUS.md`: read for open-ended status/continue prompts or meaningful continuation context; treat stale status as orientation only and verify against source/index.
-- `docs/TASKS.md`: read only for queued-task prompts or when status points at queued work; safely clean exact duplicates/completed overflow by default without deleting unfinished human-authored tasks.
-- `docs/WORKLOG.md`: only recent, relevant entries for continuation/debugging.
-- Follow routed verification policy: targeted first when localized, widen in order for shared/risky scope, ask before blanket broad runs when no related-test evidence exists.
+- **Trivial**: no docs, and no index query unless the file target is unclear.
+- **Simple**: `docs/MEMORY.md` only, plus resolver-selected files/tests.
+- **Non-trivial**: `docs/MEMORY.md` + `docs/PROJECT.md` + `docs/CODE_MAP.md`.
+- `docs/STATUS.md`: use for open-ended status/continue prompts or meaningful continuation context; stale status is orientation only.
+- `docs/TASKS.md`: use only for queued-task prompts or when status points at queued work; safely clean exact duplicates/completed overflow by default without deleting unfinished human-authored tasks.
+- `docs/WORKLOG.md`: only recent relevant entries. Follow the Budget Rules at the top of the file; archive oldest entries to `docs/WORKLOG_ARCHIVE.md` when over limits.
+- Follow routed verification policy: targeted first, widen only when risk/shared scope justifies it, ask before blanket broad runs.
 
 ## Living Status Workflow
 
-- `docs/STATUS.md` is compact current state, not a transcript and not source truth.
-- When the user asks "what next?", "continue", or "project đang ở đâu?" without a concrete target, use the `next-step` skill and show a freshness cue (fresh / possibly stale / stale / missing).
-- Concrete debug/implementation/review prompts beat open-ended wording; use the concrete skill first and only use status as background.
-- After meaningful work, use `update-status` to record state, verification, blockers, and next candidates; skip trivial/no-state-change tasks.
+- `docs/STATUS.md` captures compact current state, active work, debug threads, blockers, verification, and next candidates.
+- It is not source truth and must not replace source/index-first investigation.
+- For "what next?" / "continue" prompts without a concrete target, use `next-step` and show a freshness cue before relying on the status file.
+- For concrete debug/implementation/review prompts, keep the concrete workflow primary even if the user asks for an approach or next step.
+- After meaningful work, use `update-status`; skip trivial/no-state-change tasks and avoid transcript-style noise.
 - `docs/TASKS.md` is a local AI task queue: prefer `Ready for AI` when asked to pick queued work, and clean duplicates/prune `Done Recently` safely when reading/updating it.
 
 ## Small-Task Maintainer (internal)
@@ -117,36 +134,78 @@ In Handoff mode: read `docs/AI_HANDOFF/RULES.md` for the 4-phase spec (Idea+Plan
 - This is optional internal orchestration config from `.ukit/storage/config.json`; never turn it into an end-user workflow.
 - Always preserve the CoDev priority: quality > safety > speed > token discipline.
 
-## Subagent Policy (internal only)
+## Post-Edit Sidecar Review (internal)
 
-- Default to direct execution for trivial/simple work.
-- Delegate only when it clearly reduces context bloat or enables useful parallel progress.
+- If routed state's `routeSummary.line` includes a `review=code-reviewer(diff)` segment, a `local-build` or `shared-edit` task qualifies for a non-blocking second opinion — this exists because the daily-flow executor model can miss edge cases.
+- Only launch it once write evidence AND verification evidence already exist for the task (never before; never as a substitute for either).
+- Launch the `code-reviewer` agent (see the harness table under 3-Tier Model Routing) with `REVIEW_TARGET_TYPE=diff`, in the background, on the `smart` tier per `subagents.diffReviewModel`. Do not wait for it — continue and report the task as done using the normal completion rules.
+- Its findings are advisory only: never re-open, block, or delay the already-reported completion on their account. Surface them to the user as a follow-up note if/when they arrive.
+- This is internal orchestration — end users never invoke it directly; `ukit install` plus natural language remains the whole surface. No new commands.
+
+## Selective Subagent Policy (internal only)
+
+- Keep direct execution as the default for trivial/simple work.
+- Delegate only when it meaningfully shrinks context or enables useful parallel progress.
 - Good delegation triggers:
   - noisy side lanes (broad logs/search/test output)
   - 3+ independent failures/files/checks
   - explicit batch/plan execution
   - broad implementation/debug lanes that can return a concise summary
-- If route memory already includes `delegate=<lane>`, treat it as an internal hint after any required indexed-context step.
+- If route memory includes `delegate=<lane>`, treat it as an internal hint after any required indexed-context step.
 - Do not ask end users to name agents or remember agent commands.
 
-## Safe Patch Protocol
+## Adaptive Autonomy
 
-- Safe Patch is internal orchestration: normal users still only need `ukit install` and natural language.
-- For risky/shared/large edits, prefer unique current-file anchors over line numbers or stale pasted blocks.
-- Do not silently merge stale specs: if `old_string` is missing or ambiguous, re-read current source and ask whether to apply as-is, adapt, or skip.
-- Preserve UTF-8 BOM/no-BOM and LF/CRLF for existing multilingual/user-authored files.
-- Use `node .claude/ukit/index/safe-patch.mjs` internally when normal Edit/Write may normalize bytes or when anchor-based matching is needed.
+- `autonomy.level` in `.ukit/storage/config.json` controls how much UKit acts without asking first: `conservative` (ask more), `balanced` (default), `free-run` (auto-run more).
+- End users should not need to change this; maintainers may tune it per-project.
 
-## Team Workflow Safety
+## 3-Tier Model Routing
 
-- Do not teach normal contributors `ukit doctor`, `ukit diff`, `ukit uninstall`, or `ukit index ...` unless they are explicitly debugging UKit itself.
-- If the workspace needs a refresh, prefer telling them to rerun `ukit install`.
-- Keep scope tight, prefer the smallest correct change set, reuse existing code, and update docs when source changes.
+**Internal orchestration only — end users still just use natural language. No new commands.**
 
-## Adaptive Autonomy
+UKit routes tasks to one of three model tiers based on task complexity:
 
-- `autonomy.level` in `.ukit/storage/config.json` controls how much UKit acts without asking first: `conservative` (ask more), `balanced` (default), `free-run` (auto-run more).
-- End users should not need to change this; maintainers may tune it per-project.
+| Tier | Generic alias | Claude model | Typical tasks |
+|------|--------------|--------------|---------------|
+| lite | `unic-lite` | claude-haiku | Reads, git queries, bash summaries, small doc edits |
+| code | `unic-code` | claude-sonnet | Normal coding, local fixes, shared edits, builds, debugging, impact mapping |
+| smart | `unic-smart` | claude-opus | Release review/audit, and escalated deep reasoning after repeated failure |
+
+### Contract-to-tier mapping
+
+| Contract | Tier |
+|----------|------|
+| `tiny-fix` | lite |
+| `local-fix`, `local-build`, `shared-edit`, `find-cause`, `map-impact` | code |
+| `review-release` | smart |
+
+### How a tier is actually bound
+
+The main session model never changes mid-turn. A tier only takes effect when work is handed to
+an agent whose own definition binds that model:
+
+| Harness | Agent definitions | How to launch one |
+|---------|-------------------|-------------------|
+| Claude Code | `.claude/agents/*.md` (`model:` frontmatter) | Agent tool, `subagent_type: "<name>"` |
+| omp | `.omp/agents/*.md` (`model: "@lite"` / `"@code"` / `"@smart"` / `"@vision"`, resolved through `modelRoles` in `.omp/config.yml`) | task-agent `<name>` |
+
+When a task's contract maps to a tier other than the current session model, hand it to the
+matching agent instead of doing it inline. Doing everything inline is exactly what makes UKit
+behave as if it only had one model — the tier table above has no effect on its own.
+
+### Escalation rule
+
+When the same file or symbol fails `debugLoopThreshold` (default: 2) times in one session, UKit routes the next attempt one tier higher (capped at `smart`). Config: `orchestration.escalation` in `.ukit/storage/config.json`.
+
+This is internal orchestration — end users do not need to know about tiers, thresholds, or escalation. The AI handles routing transparently.
+
+### Vision lane (capability, not a cost tier)
+
+`unic-vision` is a **capability lane**, not a fourth cost tier — it is orthogonal to lite/code/smart above and never appears as a row in the tier table. `unic-code` and `unic-smart` cannot read images on the UNIC gateway; they must never guess at image contents.
+
+- **Gateway detection**: UNIC routing for a Claude Code session is decided ONLY by what changes Claude Code's own outbound endpoint — `ANTHROPIC_BASE_URL` (env var, or the `env.ANTHROPIC_BASE_URL` key in project/home `.claude/settings.json`) containing `unicjsc.com`. Other tools' configs — Codex `config.toml`, Kilo `secrets.json`, or an `OPENAI_BASE_URL` env var — describe a different tool's endpoint entirely and never decide this session's routing.
+- **Enforcement**: every image (pasted, local file path, or URL) must be analysed by the `ukit-vision-analyst` agent running on the vision lane before any related edit happens. `Edit`/`Write` are **hard-blocked** until an analysis receipt exists for every pending image; `Read`/`Grep`/`Glob`/`Bash` stay unblocked so the analyst itself can see the image and write its receipt.
+- This is internal orchestration — end users never invoke a vision command directly; `ukit install` plus natural language remains the whole surface. No new commands.
 
 ## Session Start — OpenCode
 
@@ -155,35 +214,43 @@ At the start of every OpenCode session, before working on the first task:
 2. Note which skills are installed by scanning `.claude/skills/` (directory listing only); read the full SKILL.md only when a task triggers it.
 3. For every non-trivial task: run `/ukit-route <task summary>` immediately to get skill + context hints **before** writing any code.
 4. If the route result points to a skill, read that SKILL.md before acting — do not skip this step.
-5. If `.ukit/storage/config.json` has `router.enabled: true`, prefer the router's output over ad-hoc guessing.
-
-## Environment Snapshot
-
-- Project name: {{project.name}}
-- Detected packs: {{project.stack}}
-- Frontend detected: {{stack.frontend}}
-- Backend API detected: {{stack.backendApi}}
-- PostgreSQL detected: {{stack.postgres}}
-- Package manager: {{runtime.packageManager}}
+5. If `.ukit/storage/config.json` has `router.enabled: true`, prefer the router output over ad-hoc guessing.
 
 ## Skills
 
 - Canonical skills live in `.claude/skills/`.
-- Adapter mirrors may also exist, for example `.codex/skills/` → `.claude/skills/` (symlink) and `.antigravity/skills/`.
-- **OpenCode**: reads `AGENTS.md` at session start only — it does NOT auto-load `.claude/skills/`. The model must explicitly read the triggered SKILL.md (see Session Start section above).
+- Adapter mirrors may also exist, for example `.codex/skills/` → `.claude/skills/` (symlink). **omp** has no mirror: it reads `.claude/skills/` directly through its own `claude` discovery provider.
+- **OpenCode**: reads `AGENTS.md` at session start only — it does NOT auto-load `.claude/skills/`. The model must explicitly read the triggered SKILL.md.
 - If `opencode.json` ships `ukit-*` commands, treat them as internal helper entrypoints only and **never ask end users to run them**; humans should still only need `ukit install`.
 
+## Project Snapshot
+
+- Project: {{project.name}} | Root: {{project.root}}
+- Packs: {{project.stack}} | Frontend: {{stack.frontend}} | Backend API: {{stack.backendApi}} | PostgreSQL: {{stack.postgres}}
+- Package manager: {{runtime.packageManager}} | OS: {{runtime.os}} | Node: {{runtime.nodeVersion}} | Provider: {{providers.unic}}
+
+## Working Rules
+
+- Keep scope tight, prefer the smallest correct change set, and reuse existing code.
+- For explicit implement/apply/fix requests, keep working until the actual edit is made or a real blocker is found; do not stop after a read-only inspection step.
+- If routed state still says `pull-indexed-context`, treat it as an internal continuation step, not a stopping point.
+- If routed state shows `continuation required` or a stuck-lane rescue mode, finish the named milestone before widening reads or rephrasing the same partial status.
+- Never claim "done", "applied", or "fixed" after Read/Grep/analysis alone. Completion language requires concrete Edit/Write evidence in the current turn, plus verification when the change is risky.
+- Update `docs/WORKLOG.md` after significant work.
+- If source contradicts docs, update docs immediately.
+- Use `{{runtime.packageManager}}`.
+
 ## DuraOne Skill — Conditional Activation
 
 DuraOne skill chỉ active khi pack `duraone` được cài hoặc `.claude/skills/duraone/SKILL.md` tồn tại.
 
-- Khi active: đọc `.claude/skills/duraone/SKILL.md` trước khi code.
+- Khi active: luôn đọc `.claude/skills/duraone/SKILL.md` trước khi code.
 - References:
   - `.claude/skills/duraone/references/frontend.md`
   - `.claude/skills/duraone/references/backend.md`
   - `.claude/skills/duraone/references/sql.md`
   - `.claude/skills/duraone/references/workflow.md`
-- Khi không active: dùng generic coding standards + project patterns từ index.
+- Khi không active: dùng generic coding standards + project-specific patterns từ index.
 
 ## Completion Checklist
 
@@ -191,3 +258,4 @@ DuraOne skill chỉ active khi pack `duraone` được cài hoặc `.claude/skil
 - No unrelated changes
 - Verification executed and reported
 - Docs updated when source truth changed
+{{codegraphSection}}

package/templates/CLAUDE.md

@@ -3,15 +3,19 @@
 ## Core Rule
 
 - Human-facing UKit workflow should collapse to one remembered command: `ukit install`.
-- After install, default to natural-language work inside Claude/Codex.
+- After install, default to natural-language work inside **Claude Code / Codex / OpenCode / omp**.
 - **Quality first, then speed, then token discipline.**
 - **Never stop after read-only steps.** For implement/apply/fix requests, continue to actual Edit/Write and verification in the same turn.
 
 ## Fast Classification
 
-- **Trivial**: act directly, no doc reads, no agents.
-- **Simple**: keep scope tight; use the smallest useful context.
-- **Non-trivial / Risky**: read deeper, verify harder, and avoid shortcuts.
+- **Trivial** — typo, label, small rename, spacing, toggle flag, obvious config change.
+  - Act directly. No doc reads. No planning. No index. No agents.
+- **Simple** — 1-2 files, clear scope, existing pattern.
+  - Handle directly. Pull only the smallest useful context via resolver or targeted read.
+- **Non-trivial / Risky** — auth, security, migration, uninstall, shared runtime, race/flaky, data-loss.
+  - Read deeper, verify harder, and avoid shortcuts.
+  - Use index-first loop, then skill activation, then targeted verification.
 
 ## Execution Contract (mandatory)
 
@@ -33,6 +37,7 @@ For any task that needs code context:
 3. For bug signatures:
    - `node .claude/ukit/index/triage.mjs "<error signature>"`
 4. Open only the **top 1-3 suspect files first**, then widen if needed.
+5. For analog/reuse patterns, check if `resolve-context` returns related existing patterns.
 
 For clearly non-code specialist lanes (docs-only, status, task queue), skip the source-code index.
 
@@ -40,8 +45,9 @@ For clearly non-code specialist lanes (docs-only, status, task queue), skip the
 
 - End users should not need to know skill names.
 - On every non-trivial task — and again after the first relevant tool calls — inspect installed project-local skills and **auto-activate the matching skill immediately**.
-- Match from prompt signals plus tool/file evidence.
-- Use the smallest useful set.
+- Match from both prompt wording and tool/file evidence.
+- Use the smallest effective set, usually 1-2 skills.
+- If evidence becomes more specific than the original prompt, upgrade the active skill choice immediately.
 - If docs work is detected, read `.claude/skills/docs-quality/SKILL.md` when present.
 - Prefer routed context and routed verification over ad-hoc broad reading.
 - Reuse `.claude/ukit/skill-router-state.json` when it already carries compact route memory.
@@ -49,22 +55,23 @@ For clearly non-code specialist lanes (docs-only, status, task queue), skip the
 
 ### Common skill triggers
 
-- review / audit / diff → `.claude/skills/code-review/SKILL.md`
-- bug / error / crash / triage → `.claude/skills/debugging-toolkit/SKILL.md`
-- test / spec / coverage → `.claude/skills/testing-quality/SKILL.md`
+- review / audit / diff / PR feedback → `.claude/skills/code-review/SKILL.md`
+- bug / error / crash / triage / failing path → `.claude/skills/debugging-toolkit/SKILL.md`
+- test / spec / coverage / fixture → `.claude/skills/testing-quality/SKILL.md`
 - docs / README / changelog / handoff / editing `docs/` / cleaning `docs/TASKS.md` → `.claude/skills/docs-quality/SKILL.md`
 - open-ended next step / project status / continue with no concrete target / choose queued task → `.claude/skills/next-step/SKILL.md`
 - explicit handoff / wrap up / update `docs/STATUS.md` → `.claude/skills/update-status/SKILL.md`
-- auth / security / token / permission / validation → `.claude/skills/discover-security/SKILL.md`
-- stale workspace / reinstall / cleanup → `.claude/skills/repo-maintenance/SKILL.md`
+- auth / security / token / permission / validation / risky shell-path-delete-db work → `.claude/skills/discover-security/SKILL.md`
+- stale workspace / reinstall / cleanup / maintenance → `.claude/skills/repo-maintenance/SKILL.md`
 
 ## Internal Helper Policy
 
-- Prefer `node .claude/ukit/index/route-task.mjs ...` when routing is complex.
+- Prefer `node .claude/ukit/index/route-task.mjs "<prompt>" [--tool-command <cmd>] [--target <file>]` when routing is complex or ambiguous.
 - Prefer `node .claude/ukit/index/resolve-context.mjs ...` for indexed related-file context.
 - Prefer `node .claude/ukit/index/verify-context.mjs ...` for concrete verification lanes.
 - **Do not ask normal contributors to run internal helper commands**; run them yourself or tell them to rerun `ukit install`.
 - Do not ask normal contributors to memorize `ukit doctor`, `ukit diff`, `ukit uninstall`, or `ukit index ...` unless they explicitly need maintainer/debug help.
+- If the workspace needs a refresh, prefer telling them to rerun `ukit install`.
 
 ## Skill Quality (maintainer-only)
 
@@ -76,11 +83,11 @@ For clearly non-code specialist lanes (docs-only, status, task queue), skip the
 - Treat `.ukit/storage/config.json` as the source of runtime toggles for compact, token pipeline, router, memory, validation, and Safe Patch behavior.
 - Reuse `.ukit/storage/memory/` before asking users to restate decisions.
 - For non-trivial work, prefer `ukit memory recall "<current task>"` before widening doc reads.
-- Reusable cache/compact/output state lives in `.ukit/storage/cache/prompt-cache.json`, `.ukit/storage/cache/compact-history.json`, `.ukit/storage/cache/compact-pressure.json`, and `.ukit/storage/cache/output-history.json`.
+- Reusable cache/compact/output state lives in `.ukit/storage/cache/prompt-cache.json`, `.ukit/storage/cache/compact-history.json`, `.ukit/storage/cache/compact-pressure.json`, `.ukit/storage/cache/output-history.json`, and preserved raw tool outputs under `.ukit/storage/cache/tee/`.
 - Shared route memory lives in `.claude/ukit/skill-router-state.json`.
 - If shared route state already includes compact `previous-context` or `recent-output`, reuse those first.
 - If an older repo still has a visible `ukit/` runtime root, rerun `ukit install`; UKit should migrate the shared runtime into hidden `.ukit/` when safe.
-- Maintainers can inspect runtime state with `ukit status` and `ukit memory export`.
+- Maintainers can inspect runtime state with `ukit status` and `ukit memory export`, but normal teammates should still only need `ukit install`.
 - If runtime files are missing or corrupt, tell maintainers to rerun `ukit install`.
 - Threshold-based compact pressure is internal orchestration; do not expose it to users.
 - For Codex Desktop long sessions, UKit can use soft auto-compact handoffs. Default `compact.codexContext.compactTarget=150` means about 150 compact handoff lines (120-150 preferred, hard max 170), not 150 tokens.
@@ -99,10 +106,9 @@ CHỈ kích hoạt khi task đi qua `docs/AI_HANDOFF/` (user nói "execute task
 
 Khi Handoff mode: đọc `docs/AI_HANDOFF/RULES.md` để biết 4 phase (Idea+Plan → Create Tasks → Implement+Test → Review+Test) + state machine + comment thread + self-report model. Config: `.ukit/storage/config.json` → `handoff.*`.
 
-
 ## Context + Verification Budget
 
-- **Trivial**: no docs.
+- **Trivial**: no docs, and no index query unless the file target is unclear.
 - **Simple**: `docs/MEMORY.md` only, plus resolver-selected files/tests.
 - **Non-trivial**: `docs/MEMORY.md` + `docs/PROJECT.md` + `docs/CODE_MAP.md`.
 - `docs/STATUS.md`: use for open-ended status/continue prompts or meaningful continuation context; stale status is orientation only.
@@ -132,7 +138,7 @@ Khi Handoff mode: đọc `docs/AI_HANDOFF/RULES.md` để biết 4 phase (Idea+P
 
 - If routed state's `routeSummary.line` includes a `review=code-reviewer(diff)` segment, a `local-build` or `shared-edit` task qualifies for a non-blocking second opinion — this exists because the daily-flow executor model can miss edge cases.
 - Only launch it once write evidence AND verification evidence already exist for the task (never before; never as a substitute for either).
-- Launch the `code-reviewer` agent via the Agent tool with `REVIEW_TARGET_TYPE=diff` and `run_in_background: true` (model `unic-smart` per `subagents.diffReviewModel`). Do not wait for it — continue and report the task as done using the normal completion rules.
+- Launch the `code-reviewer` agent (see the harness table under 3-Tier Model Routing) with `REVIEW_TARGET_TYPE=diff`, in the background, on the `smart` tier per `subagents.diffReviewModel`. Do not wait for it — continue and report the task as done using the normal completion rules.
 - Its findings are advisory only: never re-open, block, or delay the already-reported completion on their account. Surface them to the user as a follow-up note if/when they arrive.
 - This is internal orchestration — end users never invoke it directly; `ukit install` plus natural language remains the whole surface. No new commands.
 
@@ -140,8 +146,13 @@ Khi Handoff mode: đọc `docs/AI_HANDOFF/RULES.md` để biết 4 phase (Idea+P
 
 - Keep direct execution as the default for trivial/simple work.
 - Delegate only when it meaningfully shrinks context or enables useful parallel progress.
-- Good delegation triggers: noisy research/log lanes, 3+ independent failures, explicit batch execution, or a broad debug/implementation lane with a clean handoff.
+- Good delegation triggers:
+  - noisy side lanes (broad logs/search/test output)
+  - 3+ independent failures/files/checks
+  - explicit batch/plan execution
+  - broad implementation/debug lanes that can return a concise summary
 - If route memory includes `delegate=<lane>`, treat it as an internal hint after any required indexed-context step.
+- Do not ask end users to name agents or remember agent commands.
 
 ## Adaptive Autonomy
 
@@ -168,6 +179,20 @@ UKit routes tasks to one of three model tiers based on task complexity:
 | `local-fix`, `local-build`, `shared-edit`, `find-cause`, `map-impact` | code |
 | `review-release` | smart |
 
+### How a tier is actually bound
+
+The main session model never changes mid-turn. A tier only takes effect when work is handed to
+an agent whose own definition binds that model:
+
+| Harness | Agent definitions | How to launch one |
+|---------|-------------------|-------------------|
+| Claude Code | `.claude/agents/*.md` (`model:` frontmatter) | Agent tool, `subagent_type: "<name>"` |
+| omp | `.omp/agents/*.md` (`model: "@lite"` / `"@code"` / `"@smart"` / `"@vision"`, resolved through `modelRoles` in `.omp/config.yml`) | task-agent `<name>` |
+
+When a task's contract maps to a tier other than the current session model, hand it to the
+matching agent instead of doing it inline. Doing everything inline is exactly what makes UKit
+behave as if it only had one model — the tier table above has no effect on its own.
+
 ### Escalation rule
 
 When the same file or symbol fails `debugLoopThreshold` (default: 2) times in one session, UKit routes the next attempt one tier higher (capped at `smart`). Config: `orchestration.escalation` in `.ukit/storage/config.json`.
@@ -179,9 +204,16 @@ This is internal orchestration — end users do not need to know about tiers, th
 `unic-vision` is a **capability lane**, not a fourth cost tier — it is orthogonal to lite/code/smart above and never appears as a row in the tier table. `unic-code` and `unic-smart` cannot read images on the UNIC gateway; they must never guess at image contents.
 
 - **Gateway detection**: UNIC routing for a Claude Code session is decided ONLY by what changes Claude Code's own outbound endpoint — `ANTHROPIC_BASE_URL` (env var, or the `env.ANTHROPIC_BASE_URL` key in project/home `.claude/settings.json`) containing `unicjsc.com`. Other tools' configs — Codex `config.toml`, Kilo `secrets.json`, or an `OPENAI_BASE_URL` env var — describe a different tool's endpoint entirely and never decide this session's routing.
-- **Enforcement**: every image (pasted, local file path, or URL) must be analysed by the `ukit-vision-analyst` agent running on `unic-vision` before any related edit happens. `Edit`/`Write` are **hard-blocked** until an analysis receipt exists for every pending image; `Read`/`Grep`/`Glob`/`Bash` stay unblocked so the analyst itself can see the image and write its receipt.
+- **Enforcement**: every image (pasted, local file path, or URL) must be analysed by the `ukit-vision-analyst` agent running on the vision lane before any related edit happens. `Edit`/`Write` are **hard-blocked** until an analysis receipt exists for every pending image; `Read`/`Grep`/`Glob`/`Bash` stay unblocked so the analyst itself can see the image and write its receipt.
 - This is internal orchestration — end users never invoke a vision command directly; `ukit install` plus natural language remains the whole surface. No new commands.
 
+## Skills
+
+- Canonical skills live in `.claude/skills/`.
+- Adapter mirrors may also exist, for example `.codex/skills/` → `.claude/skills/` (symlink). **omp** has no mirror: it reads `.claude/skills/` directly through its own `claude` discovery provider.
+- **OpenCode**: reads `AGENTS.md` at session start only — it does NOT auto-load `.claude/skills/`. The model must explicitly read the triggered SKILL.md.
+- If `opencode.json` ships `ukit-*` commands, treat them as internal helper entrypoints only and **never ask end users to run them**; humans should still only need `ukit install`.
+
 ## Project Snapshot
 
 - Project: {{project.name}} | Root: {{project.root}}
@@ -190,8 +222,7 @@ This is internal orchestration — end users do not need to know about tiers, th
 
 ## Working Rules
 
-- Keep scope tight.
-- Reuse existing code.
+- Keep scope tight, prefer the smallest correct change set, and reuse existing code.
 - For explicit implement/apply/fix requests, keep working until the actual edit is made or a real blocker is found; do not stop after a read-only inspection step.
 - If routed state still says `pull-indexed-context`, treat it as an internal continuation step, not a stopping point.
 - If routed state shows `continuation required` or a stuck-lane rescue mode, finish the named milestone before widening reads or rephrasing the same partial status.
@@ -211,4 +242,11 @@ DuraOne skill chỉ active khi pack `duraone` được cài hoặc `.claude/skil
   - `.claude/skills/duraone/references/sql.md`
   - `.claude/skills/duraone/references/workflow.md`
 - Khi không active: dùng generic coding standards + project-specific patterns từ index.
+
+## Completion Checklist
+
+- Requirements implemented
+- No unrelated changes
+- Verification executed and reported
+- Docs updated when source truth changed
 {{codegraphSection}}

package/templates/docs/PROJECT.md

@@ -37,7 +37,7 @@
 ## Delivery Profile
 
 - Primary workflow: natural-language AI tooling installed by UKit
-- Shared adapters: Claude Code, OpenAI Codex, Antigravity
+- Shared adapters: Claude Code, OpenAI Codex, OpenCode, omp (Oh My Pi)
 - Change policy: smallest correct change with clear verification
 
 ## Session Start Routine

package/templates/ukit/storage/config.json

@@ -53,6 +53,11 @@
           "mode": "native-auto-prune",
           "preserveExistingCompaction": true
         },
+        "omp": {
+          "autoCompact": true,
+          "mode": "precompact-reinject",
+          "preserveExistingHooks": true
+        },
         "codex": {
           "autoCompact": true,
           "mode": "soft-handoff",
@@ -410,6 +415,11 @@
             "mode": "native-auto-prune nghĩa là OpenCode dùng compaction.auto/prune native.",
             "preserveExistingCompaction": "Nên giữ true để không gỡ compact native của OpenCode."
           },
+          "omp": {
+            "autoCompact": "Giữ compact lane của omp (Oh My Pi) bật.",
+            "mode": "precompact-reinject nghĩa là UKit dùng hook session.compacting/session_before_compact của omp để bơm lại context quan trọng trước khi compact.",
+            "preserveExistingHooks": "Nên giữ true để không gỡ các module hooks/pre của bạn khi UKit cài bridge."
+          },
           "codex": {
             "autoCompact": "Bật policy soft handoff compact cho Codex Desktop.",
             "mode": "soft-handoff nghĩa là UKit tạo/dùng state tóm tắt, không can thiệp trực tiếp vào internals của app Codex.",

package/templates/adapter-presets/antigravity/README.md

@@ -1,22 +0,0 @@
-# {{project.name}}
-
-Auto-generated by UKit for Google Antigravity.
-
-- Packs: {{project.stack}}
-- Package manager: {{runtime.packageManager}}
-
-## Start
-Use graduated doc budget:
-- Trivial: no docs
-- Simple: `docs/MEMORY.md`
-- Non-trivial: `docs/MEMORY.md` + `docs/PROJECT.md` + `docs/CODE_MAP.md`
-- `docs/WORKLOG.md`: recent relevant entries only
-
-If routing is complex/ambiguous, use:
-- `node .antigravity/ukit/index/route-task.mjs "<prompt>" [--tool-command <cmd>] [--target <file>]`
-
-Routing uses natural-language intent (fix/review/brainstorm/build/test/docs).  
-If confidence is low, ask one short clarifying question.
-
-## Skills
-Skills are shared from `.claude/skills/` via symlink. Each skill folder contains `SKILL.md`.

package/templates/adapter-presets/antigravity/rules.md

@@ -1,49 +0,0 @@
-# Project Rules — {{project.name}}
-
-Auto-generated by UKit. Edit `.claude/` sources to update.
-
-## Core policy
-
-- Natural language only; do not require slash commands or skill names.
-- If helper/index commands are needed, run them internally and never ask users to run them.
-- Quality first, keep latency low, avoid repeated token waste.
-- Reuse shared route state from `.claude/ukit/skill-router-state.json`. If it already carries compact `previous-context` or `recent-output` lines, use those before widening docs, memory, or raw logs.
-- Shared runtime lives in `.ukit/storage/`. Reuse `.ukit/storage/memory/`, `.ukit/storage/cache/compact-pressure.json`, `.ukit/storage/cache/output-history.json`, and `.ukit/storage/cache/tee/` before asking users to restate context.
-
-## Route fast
-
-- `fix/bug/error/debug/lỗi/sửa` → fix lane
-- `review/audit/check/soát code` → review lane
-- `brainstorm/idea/design/plan` → design lane
-- `build/implement/add/create` → build lane
-- `clone/copy/similar/giống/tương tự` → follow-pattern lane
-- `test/spec/coverage` → test lane
-- `docs/readme/changelog/tài liệu` → docs lane
-- If intent is ambiguous, ask one short clarifying question.
-- If routing is complex or shared route memory needs refresh, run `node .antigravity/ukit/index/route-task.mjs "<prompt>" [--tool-command <cmd>] [--target <file>]`.
-
-## Skill + context loop
-
-- Auto-activate the smallest useful installed skill set from prompt + tool/file evidence.
-- Prefer `node .antigravity/ukit/index/resolve-context.mjs "<intent>" [--target <file>]` after choosing a skill.
-- Prefer `node .antigravity/ukit/index/verify-context.mjs "<intent>" [--target <file>]` for verification planning.
-
-## Indexed reading + verification
-
-- Trivial: no docs, 1-2 files, minimal verify.
-- Simple: `docs/MEMORY.md` only, 2-5 files, targeted verify.
-- Non-trivial/risky: `docs/MEMORY.md` + `docs/PROJECT.md` + `docs/CODE_MAP.md`, broader verify.
-- `docs/WORKLOG.md`: recent relevant entries only.
-- Clone/follow-pattern: open at least 1 analog file.
-- Shared logic: open the shared abstraction.
-- Bug with tests: open related test first.
-- If broad verification is blocked because targeted verification was skipped, go back to the routed targeted lane first.
-- For bugfix tasks, run index-first triage: `node .antigravity/ukit/index/build-index.mjs` then `node .antigravity/ukit/index/triage.mjs "<error signature>"`, inspect top suspects, then widen only if needed.
-
-## Safety
-
-- Package manager: `{{runtime.packageManager}}`.
-- Keep scope tight and prefer existing code paths.
-- Update `docs/WORKLOG.md`, `docs/MEMORY.md`, `docs/CODE_MAP.md`, or `docs/PROJECT.md` after significant work when relevant.
-- Never edit `.env*`, lock files, `.git/`, or `node_modules/`.
-- Never run destructive commands without explicit confirmation.