@ngockhoale/ukit 2.6.6 → 2.6.7

package/templates/instructions/core.md

@@ -0,0 +1,210 @@
+## Core Rule
+<!-- RULES: CORE-01 CORE-02 -->
+
+- 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 Classification
+
+<!-- RULE: CLS-01 -->
+- **Trivial** — typo, label, small rename, spacing, toggle flag, obvious config change.
+  - Act directly. No doc reads. No planning. No index. No agents.
+<!-- RULE: CLS-02 -->
+- **Simple** — 1-2 files, clear scope, existing pattern.
+  - Handle directly. Pull only the smallest useful context via resolver or targeted read.
+<!-- RULE: CLS-03 -->
+- **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)
+
+<!-- RULE: EXEC-01 -->
+- For explicit 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).
+<!-- RULE: EXEC-03 -->
+- If routed state says `pull-indexed-context`, treat it as an internal continuation step, not a stopping point — after the bounded read, **continue to edit/verify in the same turn** when safe.
+- If routed state shows `continuation required` or a stuck-lane rescue mode, finish the named milestone before widening reads or repeating analysis.
+<!-- RULE: EXEC-02 -->
+- **Do NOT say "done", "applied", or "fixed" after Read/Grep/analysis alone.** Completion wording requires concrete Edit/Write evidence in the current turn, and verification when the scope is risky.
+<!-- RULE: EXEC-04 -->
+- **Every stop says why — no silent idle.** When a turn ends because only the user can act (login, approval, protected-file edit), open the reply with one line naming the exact action: `WAITING ON YOU: <command/action>`, and schedule a one-shot wakeup (~20-30 min) when the harness provides one so the session re-checks and auto-continues once the user has acted. An ended turn cannot observe external/auth changes by itself, so without that line (and the wakeup) the idle session looks identical to a stall. Any error — failed command, hook, test, publish — is reported verbatim in the same turn, never silently retried past the user.
+
+## Long-Run Continuity
+<!-- RULES: LONG-01 LONG-02 -->
+
+- Near token-cap: **LAND one thing** end-to-end (edit + verify, ≤3 tool calls), **DEFER** the rest into `docs/STATUS.md` or bounded `docs/AI_HANDOFF/` tasks, **DELEGATE** broad work to subagents. Only then compact.
+- After any compact or handoff: continue from the persisted disk state — never reread pre-compact context; delegate broad work, keep replies short.
+- A run ends only on completion evidence, a genuine blocker, or a user-only action — every such stop names its reason (Execution Contract). Detail: `docs/UKIT_INTERNALS.md`.
+
+## Index-First Loop
+
+For any task that needs code context:
+
+<!-- RULE: IDX-01 -->
+1. Check if index is fresh (`.cache/index/` artifacts). If stale or missing, refresh (`node .claude/ukit/index/refresh-index.mjs`).
+2. Query likely files: `node .claude/ukit/index/query-index.mjs "<error|symbol|path>"`.
+3. For bug signatures: `node .claude/ukit/index/triage.mjs "<error signature>"`.
+<!-- RULE: IDX-02 -->
+4. Open only the **top 1-3 suspect files first**, then widen if needed. `query-index`/`resolve-context` print an `outline:` block — jump straight to `Read(file, offset=<line>)`.
+<!-- RULE: IDX-03 -->
+   The outline locates code; it does not describe behaviour. **Any code you are about to change must still be read.**
+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.
+
+## Automatic Skill Activation (mandatory)
+
+- End users should not need to know skill names.
+<!-- RULE: SKILL-01 -->
+- 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.
+<!-- RULES: SKILL-02 SKILL-03 -->
+- 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 context and routed verification over ad-hoc broad reading; reuse `.claude/ukit/skill-router-state.json` when it already carries compact route memory.
+
+### Common skill triggers
+
+- 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 / 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
+
+<!-- RULES: HELP-01 HELP-02 -->
+- Prefer the internal index helpers (`node .claude/ukit/index/route-task.mjs`, `resolve-context.mjs`, `verify-context.mjs`) for routing, related-file context, and verification lanes.
+- **Do not ask normal contributors to run internal helper commands** or memorize maintainer commands (`ukit doctor`, `ukit diff`, `ukit uninstall`) — run them yourself.
+<!-- RULE: FALLBACK-01 -->
+- If the workspace needs a refresh or runtime files are missing/corrupt, tell maintainers to rerun `ukit install`. Detail: `docs/UKIT_INTERNALS.md`.
+
+## 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 v{{ukit.version}} Shared Runtime
+
+- Shared runtime state lives in `.ukit/storage/`; `.ukit/storage/config.json` is the source of runtime toggles (compact, token pipeline, router, memory, validation, Safe Patch).
+- Reuse `.ukit/storage/memory/` and `ukit memory recall "<current task>"` before asking users to restate decisions or widening doc reads; maintainers can inspect state with `ukit status` / `ukit memory export`.
+- Shared route memory lives in `.claude/ukit/skill-router-state.json`; reuse compact `previous-context`/`recent-output` first.
+- If runtime files are missing/corrupt or an old visible `ukit/` root remains, rerun `ukit install`. Cache state (`.ukit/storage/cache/output-history.json`, tee/) + Codex handoff detail: `docs/UKIT_INTERNALS.md`.
+
+## Prompt Caching
+<!-- RULES: CTX-01 CTX-02 CTX-03 CTX-04 CTX-05 CTX-06 CTX-07 CTX-08 CTX-09 CTX-10 -->
+
+- Full ruleset: `docs/PROMPT_CACHING.md` (read on demand; it is not loaded into every session).
+- CTX-01 deterministic segment bytes · CTX-02 keep roles and order · CTX-03 keep tool IDs and continuation state · CTX-04 no clock/random IDs in static blocks · CTX-05 compaction starts a new epoch · CTX-06 never change data to match a cache · CTX-07 no unconfirmed cache fields · CTX-08 tool-result reuse needs valid freshness · CTX-09 missing usage is unknown, not zero · CTX-10 never cut a required check to reduce calls.
+
+## Safe Patch Protocol
+<!-- RULES: SAFE-02 SAFE-03 SAFE-01 -->
+
+- For risky/shared/large edits, prefer unique current-file anchors over line numbers or stale pasted blocks; 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.
+- Internal helper + detail: `docs/UKIT_INTERNALS.md` (`node .claude/ukit/index/safe-patch.mjs`).
+
+## Handoff Quality Gate — OPT-IN
+<!-- RULE: HAND-01 -->
+
+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
+<!-- RULE: BUDGET-01 -->
+
+- **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`.
+<!-- RULES: BUDGET-02 BUDGET-03 -->
+- `docs/STATUS.md` for open-ended/continue prompts; `docs/TASKS.md` only for queued-task prompts; `docs/WORKLOG.md` recent entries only (archive overflow).
+- Follow routed verification policy: targeted first, widen only when risk/shared scope justifies it, ask before blanket broad runs.
+
+## Living Status Workflow
+<!-- RULE: STATUS-01 -->
+
+- `docs/STATUS.md` captures compact current state; it is not source truth and must not replace source/index-first investigation.
+- For "what next?" / "continue" prompts, use `next-step` with a freshness cue; after meaningful work use `update-status`. `docs/TASKS.md` is the local AI task queue — prefer `Ready for AI`. Detail: `docs/UKIT_INTERNALS.md`.
+
+## Small-Task Maintainer (internal)
+<!-- RULE: SUBAG-02 -->
+
+- The `ukit-small-task-maintainer` subagent (`subagents.smallTaskModel`, default `unic-lite`) handles safe/reversible UKit chores as a sidecar lane — never block or slow the user task; risky work hands back to the main model. Detail: `docs/UKIT_INTERNALS.md`.
+
+## Post-Edit Sidecar Review (internal)
+
+- When routed state's `routeSummary.line` carries `review=code-reviewer(diff)`, launch the `code-reviewer` agent in the background (`smart` tier) **only after** write + verification evidence exists; findings are advisory — never block the already-reported completion. Detail: `docs/UKIT_INTERNALS.md`.
+
+## Selective Subagent Policy (internal only)
+<!-- RULE: SUBAG-01 -->
+
+- Keep direct execution as the default for trivial/simple work; delegate only when it meaningfully shrinks context or enables useful parallel progress (noisy side lanes, 3+ independent failures, batch plans, broad debug lanes).
+- Do not ask end users to name agents or remember agent commands.
+
+## Adaptive Autonomy
+<!-- RULE: AUTO-01 -->
+
+- `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), `vibecode` (run one prompt to a finished result; the completion gate stops only on completion evidence, a genuine blocker, or a dangerous-command decision).
+- End users should not need to change this; maintainers may tune it per-project.
+
+## 3-Tier Model Routing
+<!-- RULES: TIER-01 TIER-02 -->
+
+**Internal orchestration only — end users still just use natural language. No new commands.**
+
+| 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 |
+
+- The main session model never changes mid-turn: a tier takes effect only when work is handed to an agent whose own definition binds that model (`model:` frontmatter in `.claude/agents/*.md`; `model:` `@lite`/`@code`/`@smart`/`@vision` in `.omp/agents/*.md` resolved via `modelRoles`).
+- Contract map: `tiny-fix` → lite · `local-fix`, `local-build`, `shared-edit`, `find-cause`, `map-impact` → code · `review-release` → smart.
+- Escalation: same file/symbol failing `debugLoopThreshold` (default 2) times in one session routes the next attempt one tier higher, capped at `smart`.
+- `unic-vision` is a capability lane, not a cost tier — unverified vision must never guess at image contents; route images to `ukit-vision-analyst`. Full harness table + gateway detection detail: `docs/UKIT_INTERNALS.md`.
+
+## Skills
+
+- Canonical skills live in `.claude/skills/`; adapter mirrors may exist (`.codex/skills/` → symlink). **omp** reads `.claude/skills/` directly via its `claude` discovery provider.
+- **OpenCode**: reads `AGENTS.md` at session start only — it does NOT auto-load skills; the model must explicitly read the triggered SKILL.md.
+- `ukit-*` commands in `opencode.json` are internal helper entrypoints — never ask end users to run them.
+
+## 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.
+- Update `docs/WORKLOG.md` after significant work; if source contradicts docs, update docs immediately.
+- Use `{{runtime.packageManager}}`.
+
+## DuraOne Skill — Conditional Activation
+<!-- RULE: DURA-01 -->
+
+DuraOne skill chỉ active khi pack `duraone` được cài hoặc `.claude/skills/duraone/SKILL.md` tồn tại — khi active, luôn đọc SKILL.md + references trước khi code; khi không, dùng generic standards + index patterns. Chi tiết: `docs/UKIT_INTERNALS.md`.
+
+## Completion Checklist
+
+- Requirements implemented
+- No unrelated changes
+- Verification executed and reported
+- Docs updated when source truth changed
+
+## Handoff Fullstack Rules
+<!-- RULE: HAND-02 -->
+
+- `docs/AI_HANDOFF/RUN.md` là run cursor có thẩm quyền; `Phase:` ≠ `done`/`blocked` nghĩa là run còn sống — Stop gate từ chối stop và trả về `Next:` step.
+- Recap/checkpoint không bao giờ là completion — chỉ `HANDOFF FULLSTACK COMPLETE` (sau `Phase: done`) hoặc `HANDOFF FULLSTACK BLOCKED` (sau `Phase: blocked`) mới kết thúc run. Resume tự động mọi task chưa xong (current, legacy, pending, interrupted, recovery `-R<n>`).
+- Kết thúc cycle: docs sync → archive `docs/AI_HANDOFF/archive/cycle-NN/` → `Phase: done`. `handoff-clear` bắt buộc đóng RUN.md. Full rules: `docs/AI_HANDOFF/RULES.md`.
+
+## Compact Instructions
+
+Khi compact giữa một handoff run: giữ lại goal, RUN.md path + phase hiện tại, task inventory, task đang làm, `Next:` step, blockers, verification evidence, commits, worktree/copy-back state, và quy tắc "compact không phải completion". Sau compact: đọc lại RUN.md + INDEX.md rồi chạy tiếp `Next:` ngay.

package/templates/instructions/layout.yaml

@@ -0,0 +1,149 @@
+version: 1
+description: >-
+  Deterministic layout for the five rendered instruction-contract outputs.
+  `sections` enumerates every ## block of the named source in output order;
+  reserved specifiers: `__preamble__` (source's leading non-## block, emitted
+  verbatim with no ## prefix) and `*` (all ## sections of the source in file
+  order). Every source ## section must be referenced by ≥1 output (FR-006).
+outputs:
+  - target: templates/CLAUDE.md
+    h1: '# CLAUDE.md — {{project.name}}'
+    banner: '<!-- generated: templates/instructions/ — edit sources, then yarn docs:render -->'
+    resolve_vars: false
+    sections:
+      - { from: core, heading: Core Rule }
+      - { from: core, heading: Fast Classification }
+      - { from: core, heading: Execution Contract (mandatory) }
+      - { from: core, heading: Long-Run Continuity }
+      - { from: core, heading: Index-First Loop }
+      - { from: core, heading: Automatic Skill Activation (mandatory) }
+      - { from: core, heading: Internal Helper Policy }
+      - { from: core, heading: Skill Quality (maintainer-only) }
+      - { from: core, heading: 'UKit v{{ukit.version}} Shared Runtime' }
+      - { from: core, heading: Prompt Caching }
+      - { from: core, heading: Safe Patch Protocol }
+      - { from: core, heading: Handoff Quality Gate — OPT-IN }
+      - { from: core, heading: Context + Verification Budget }
+      - { from: core, heading: Living Status Workflow }
+      - { from: core, heading: Small-Task Maintainer (internal) }
+      - { from: core, heading: Post-Edit Sidecar Review (internal) }
+      - { from: core, heading: Selective Subagent Policy (internal only) }
+      - { from: core, heading: Adaptive Autonomy }
+      - { from: core, heading: 3-Tier Model Routing }
+      - { from: core, heading: Skills }
+      - { from: core, heading: Project Snapshot }
+      - { from: core, heading: Working Rules }
+      - { from: core, heading: DuraOne Skill — Conditional Activation }
+      - { from: core, heading: Completion Checklist }
+      - { from: core, heading: Handoff Fullstack Rules }
+      - { from: core, heading: Compact Instructions }
+    trailer: '{{codegraphSection}}'
+  - target: templates/AGENTS.md
+    h1: '# AGENTS.md — {{project.name}}'
+    banner: '<!-- generated: templates/instructions/ — edit sources, then yarn docs:render -->'
+    resolve_vars: false
+    sections:
+      - { from: core, heading: Core Rule }
+      - { from: core, heading: Fast Classification }
+      - { from: core, heading: Execution Contract (mandatory) }
+      - { from: core, heading: Long-Run Continuity }
+      - { from: core, heading: Index-First Loop }
+      - { from: core, heading: Automatic Skill Activation (mandatory) }
+      - { from: core, heading: Internal Helper Policy }
+      - { from: core, heading: Skill Quality (maintainer-only) }
+      - { from: core, heading: 'UKit v{{ukit.version}} Shared Runtime' }
+      - { from: core, heading: Prompt Caching }
+      - { from: core, heading: Safe Patch Protocol }
+      - { from: core, heading: Handoff Quality Gate — OPT-IN }
+      - { from: core, heading: Context + Verification Budget }
+      - { from: core, heading: Living Status Workflow }
+      - { from: core, heading: Small-Task Maintainer (internal) }
+      - { from: core, heading: Post-Edit Sidecar Review (internal) }
+      - { from: core, heading: Selective Subagent Policy (internal only) }
+      - { from: core, heading: Adaptive Autonomy }
+      - { from: core, heading: 3-Tier Model Routing }
+      - { from: 'overlay:agents', heading: Session Start — OpenCode }
+      - { from: 'overlay:agents', heading: Project Owner Instructions — Codex and OpenCode }
+      - { from: core, heading: Skills }
+      - { from: core, heading: Project Snapshot }
+      - { from: core, heading: Working Rules }
+      - { from: core, heading: DuraOne Skill — Conditional Activation }
+      - { from: core, heading: Completion Checklist }
+      - { from: core, heading: Handoff Fullstack Rules }
+      - { from: core, heading: Compact Instructions }
+    trailer: '{{codegraphSection}}'
+  - target: templates/.omp/RULES.md
+    h1: '# .omp/RULES.md — sticky always-apply rules'
+    banner: '<!-- generated: templates/instructions/ — edit sources, then yarn docs:render -->'
+    resolve_vars: false
+    sections:
+      - { from: 'overlay:omp-rules', heading: __preamble__ }
+      - { from: 'overlay:omp-rules', heading: '*' }
+  - target: CLAUDE.md
+    h1: '# CLAUDE.md — @ngockhoale/ukit'
+    banner: '<!-- generated: templates/instructions/ + repo overlay — edit sources, then yarn docs:render -->'
+    resolve_vars: true
+    sections:
+      - { from: 'overlay:repo', heading: Release Policy (mandatory — never replace) }
+      - { from: core, heading: Core Rule }
+      - { from: core, heading: Fast Classification }
+      - { from: core, heading: Execution Contract (mandatory) }
+      - { from: core, heading: Long-Run Continuity }
+      - { from: core, heading: Index-First Loop }
+      - { from: core, heading: Automatic Skill Activation (mandatory) }
+      - { from: core, heading: Internal Helper Policy }
+      - { from: core, heading: Skill Quality (maintainer-only) }
+      - { from: core, heading: 'UKit v{{ukit.version}} Shared Runtime' }
+      - { from: core, heading: Prompt Caching }
+      - { from: core, heading: Safe Patch Protocol }
+      - { from: core, heading: Handoff Quality Gate — OPT-IN }
+      - { from: core, heading: Context + Verification Budget }
+      - { from: core, heading: Living Status Workflow }
+      - { from: core, heading: Small-Task Maintainer (internal) }
+      - { from: core, heading: Post-Edit Sidecar Review (internal) }
+      - { from: core, heading: Selective Subagent Policy (internal only) }
+      - { from: core, heading: Adaptive Autonomy }
+      - { from: core, heading: 3-Tier Model Routing }
+      - { from: core, heading: Skills }
+      - { from: core, heading: Project Snapshot }
+      - { from: core, heading: Working Rules }
+      - { from: core, heading: DuraOne Skill — Conditional Activation }
+      - { from: core, heading: Completion Checklist }
+      - { from: core, heading: Handoff Fullstack Rules }
+      - { from: core, heading: Compact Instructions }
+    trailer: '{{codegraphSection}}'
+  - target: AGENTS.md
+    h1: '# AGENTS.md — @ngockhoale/ukit'
+    banner: '<!-- generated: templates/instructions/ + repo overlay — edit sources, then yarn docs:render -->'
+    resolve_vars: true
+    sections:
+      - { from: 'overlay:repo', heading: Release Policy (mandatory — never replace) }
+      - { from: core, heading: Core Rule }
+      - { from: core, heading: Fast Classification }
+      - { from: core, heading: Execution Contract (mandatory) }
+      - { from: core, heading: Long-Run Continuity }
+      - { from: core, heading: Index-First Loop }
+      - { from: core, heading: Automatic Skill Activation (mandatory) }
+      - { from: core, heading: Internal Helper Policy }
+      - { from: core, heading: Skill Quality (maintainer-only) }
+      - { from: core, heading: 'UKit v{{ukit.version}} Shared Runtime' }
+      - { from: core, heading: Prompt Caching }
+      - { from: core, heading: Safe Patch Protocol }
+      - { from: core, heading: Handoff Quality Gate — OPT-IN }
+      - { from: core, heading: Context + Verification Budget }
+      - { from: core, heading: Living Status Workflow }
+      - { from: core, heading: Small-Task Maintainer (internal) }
+      - { from: core, heading: Post-Edit Sidecar Review (internal) }
+      - { from: core, heading: Selective Subagent Policy (internal only) }
+      - { from: core, heading: Adaptive Autonomy }
+      - { from: core, heading: 3-Tier Model Routing }
+      - { from: 'overlay:agents', heading: Session Start — OpenCode }
+      - { from: 'overlay:agents', heading: Project Owner Instructions — Codex and OpenCode }
+      - { from: core, heading: Skills }
+      - { from: core, heading: Project Snapshot }
+      - { from: core, heading: Working Rules }
+      - { from: core, heading: DuraOne Skill — Conditional Activation }
+      - { from: core, heading: Completion Checklist }
+      - { from: core, heading: Handoff Fullstack Rules }
+      - { from: core, heading: Compact Instructions }
+    trailer: '{{codegraphSection}}'

package/templates/instructions/overlays/agents.md

@@ -0,0 +1,15 @@
+## Session Start — OpenCode
+
+<!-- RULE: HOST-OC-01 -->
+At the start of every OpenCode session, before working on the first task:
+1. Reuse matching route hints from `.claude/ukit/skill-router-state.json`; scan `.claude/skills/` (listing only) and read a SKILL.md only when a task triggers it.
+2. For every non-trivial task, run `/ukit-route <task summary>` for skill + context hints **before** writing code; if it names a skill, read that SKILL.md — do not skip. When `router.enabled: true` in `.ukit/storage/config.json`, prefer router output over guessing; treat it as internal continuation — continue to edit/verify, don't stop.
+
+## Project Owner Instructions — Codex and OpenCode
+
+When running in Codex or OpenCode, read and follow the root
+`PROJECT_IMPORTANT.md` before doing project work. It is the canonical
+project-owner instruction source. Do not copy its contents into this file.
+If it is missing or unreadable, state that limitation and continue with the
+remaining project instructions.
+<!-- RULES: OWN-01 HOST-OWN-01 -->

package/templates/instructions/overlays/claude.md

@@ -0,0 +1,3 @@
+<!-- Claude-only overlay. Intentionally carries no ## sections today: every
+     section of templates/CLAUDE.md is shared core. Kept as a comment-only
+     source so the overlay allowlist mechanism is exercised (SPEC §7.5). -->

package/templates/instructions/overlays/omp-rules.md

@@ -0,0 +1,74 @@
+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 `AGENTS.md` that must survive even when
+nothing else is loaded. Keep this short: every line here is a per-turn tax.
+
+## 1. Classify first, then act
+
+- **Trivial** (typo, rename, flag, obvious config) — act directly. No doc reads, no index, no agents.
+- **Simple** (1-2 files, existing pattern) — act directly, pull the smallest useful context.
+- **Non-trivial / risky** (auth, migration, shared runtime, data-loss, flaky) — index-first, then
+  activate the matching skill, then verify.
+
+Pick the lane before the first tool call. Skipping this is what turns a direct chat into a
+scattershot one.
+
+## 2. 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).
+
+## 3. 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.
+
+## 4. 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.
+
+## 5. Auto-activate skills
+
+Skills live in `.claude/skills/` and omp reads them through its `claude` discovery provider — no
+mirror under `.omp/`. On any non-trivial task, and again after the first tool calls reveal what the
+work really is, read the matching `SKILL.md` without being asked. Users never name skills.
+
+## 6. Delegate to bind a model tier
+
+Your own model does not change mid-turn. A tier only applies when work is handed to a task-agent in
+`.omp/agents/`, whose `model:` field (`@lite` / `@code` / `@smart` / `@vision`) resolves through
+`modelRoles` in `.omp/config.yml`.
+
+- `tiny-fix` → `@lite` · `local-fix`, `local-build`, `shared-edit`, `find-cause`, `map-impact` →
+  `@code` · `review-release` → `@smart`
+- Images: `@vision` only. `@code`/`@smart` cannot see images on the UNIC gateway and must never
+  guess at their contents — hand every image to `ukit-vision-analyst` first.
+
+Doing everything inline is exactly what makes UKit look like it only has one model. Keep direct
+execution for trivial/simple work; delegate when the tier differs or when a noisy lane would other-
+wise flood this context.
+
+## 7. 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.
+
+## 8. Handoff runs never park mid-cycle
+
+While `docs/AI_HANDOFF/RUN.md` `Phase:` is not `done`/`blocked`, a handoff-fullstack run is
+still in flight: a recap or checkpoint is progress output, never a stopping point. Continue
+the cursor's `Next:` step; only `HANDOFF FULLSTACK COMPLETE` or `HANDOFF FULLSTACK BLOCKED`
+ends the run. `handoff-clear` must close the cursor (`Phase: done` or delete) or the gate
+keeps the next session running too.
+
+## 9. Never end a turn silently
+
+Ending a turn with no output is a defect, not a pause. If you stop before the work is finished, the
+last thing you emit is one short line naming what is unfinished and what you need. Silence is never
+a status — the user cannot distinguish it from a crash.
+
+> Maintainer note, not a per-turn rule: `modelRoles` in `.omp/config.yml` ships UNIC gateway names.
+> On a non-UNIC provider, edit only the three cost tiers — `lite`, `code`, `smart` — never `vision`,
+> which stays `unic-vision` because it is a capability lane, not a cost tier.

package/templates/instructions/overlays/repo.md

@@ -0,0 +1,9 @@
+## Release Policy (mandatory — never replace)
+
+> User-mandated 2026-09-13. This file uses `mergeStrategy: skip` — ukit install/update never overwrite it. This section is permanent.
+
+- **Latest code must always be on npm.** Every version bump ships with `npm publish` in the same cycle, before the work counts as done. A release that only commits to git is not a release (this gap left 2.3.18–2.3.19 unpublished).
+- **npm and git always hold the same latest version.** After publish, `npm view @ngockhoale/ukit version` must equal the `package.json` version; if they ever diverge, publishing wins and happens first.
+- **Never ask the user for npm publish permission** — approval is permanently granted for this package. Use `npm publish --dry-run` for pre-verification, then run the real publish in the same cycle.
+- Users update with `ukit update`, which pulls from npm — an unpublished fix reaches no one. Git is code history/tracking only; npm is the distribution channel.
+- **Repo-only rule:** this policy applies to the UKit development repo itself and must NEVER be added to `templates/CLAUDE.md` / `templates/AGENTS.md` (it must not ship to installed projects). Mirrored at the top of root CLAUDE.md + AGENTS.md; those copies can be wiped by a `ukit update` run inside this repo — if missing, restore them from this section.

package/templates/instructions/repo-vars.yaml

@@ -0,0 +1,23 @@
+version: 1
+description: >-
+  Concrete repo values for the resolve_vars:true outputs (root CLAUDE.md /
+  AGENTS.md). ukit.version is merged in from package.json at render time —
+  do not repeat it here.
+project:
+  name: '@ngockhoale/ukit'
+  root: /Volumes/KHOA_EXTENAL/WORKING_PROJECT/WORKING/UKit
+  stack: core
+stack:
+  frontend: false
+  backendApi: false
+  postgres: false
+runtime:
+  packageManager: yarn
+  os: darwin
+  # Parsed value = process.version ("v" + digits). The \x31 escape keeps the
+  # raw file free of a vX.Y.Z literal so staleVersionProse's raw-text scan
+  # stays clean without allowlisting a machine-snapshot file.
+  nodeVersion: "v22.22.\x31"
+providers:
+  unic: true
+codegraphSection: ''