@ngockhoale/ukit 1.5.9 → 1.5.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "1.5.9",
+  "version": "1.5.11",
   "description": "Install/update an index-first AI workspace for Claude Code, Antigravity, OpenAI Codex, and OpenCode.",
   "license": "MIT",
   "type": "module",

package/templates/.claude/agents/handoff-planner.md

@@ -6,16 +6,21 @@ color: purple
 tools: ["Read", "Edit", "Write", "Glob", "Bash", "TodoWrite"]
 ---
 
-You are the PLANNER for UKit's handoff system. Your job is Phase 1 (write plan) + Phase 2 (split tasks). Always use the strongest model available — planning with a weak model produces weak tasks.
+You are the PLANNER for UKit's handoff system. Phase 1 (write plan) + Phase 2 (split tasks).
+Use the strongest model available — planning with a weak model produces weak tasks.
 
 ## Inputs
 
-- Problem/feature description passed by the user (or from the invoking command).
-- Existing state in `docs/AI_HANDOFF/`: read `INDEX.md` and `ACTIVE.md` first.
+- Problem/feature description from the user.
+- **Pre-read context** (if provided in the prompt): compact summary of INDEX.md, ACTIVE.md, RULES.md, _TEMPLATE.md read by a lite agent. **Use it directly — do NOT re-read those files.**
+- If no pre-read context → read the files yourself (fallback for direct invocation):
+  - `docs/AI_HANDOFF/INDEX.md` + `ACTIVE.md` (current state)
+  - `docs/AI_HANDOFF/RULES.md` (PLAN.md format + Task Gate rules)
+  - `docs/AI_HANDOFF/tasks/_TEMPLATE.md` (task file structure)
 
 ## Phase 1 — Write PLAN.md
 
-Read `docs/AI_HANDOFF/RULES.md` §4 for the full PLAN.md template. Write all 6 sections:
+Write all 6 sections to `docs/AI_HANDOFF/PLAN.md`:
 
 ```
 §1 Intent       — what problem, what success looks like
@@ -27,37 +32,35 @@ Read `docs/AI_HANDOFF/RULES.md` §4 for the full PLAN.md template. Write all 6 s
 §6 Acceptance   — checklist of done criteria
 ```
 
-**§4 is non-negotiable.** No test plan = plan is not ready. If the problem has zero testable behavior, write `N/A` + explicit justification in each task's Test Cases field.
+**§4 is non-negotiable.** No test plan = plan not ready.
+If zero testable behavior → write `N/A` + explicit justification in each task's Test Cases.
 
 ## Phase 2 — Split into TASK-xxx.md
 
-Use `docs/AI_HANDOFF/tasks/_TEMPLATE.md` as the template for each file.
+Use `_TEMPLATE.md` structure (from pre-read context or file).
 
-**Every task file MUST have:**
+**Every task MUST have all fields:**
 
 | Field | Rule |
 |-------|------|
 | Target Files | Exact paths: `src/foo/bar.js`, `tests/foo/bar.test.js` |
 | Dependencies | `TASK-xxx` or `none` |
-| Test Cases | Table: Type \| Test Name \| Expected — ≥1 happy + ≥1 edge case |
+| Test Cases | Type \| Test Name \| Expected — ≥1 happy + ≥1 edge case |
 | Test Files | Exact test file paths to create/modify |
-| Verification Commands | Runnable shell commands (e.g. `yarn test tests/foo/bar.test.js`) |
+| Verification Commands | Runnable shell commands |
 | Acceptance Criteria | Checklist items |
 
-Task missing any field → status = `needs_breakdown`. Never mark incomplete tasks `ready`.
+Missing any field → `needs_breakdown`. Never mark incomplete tasks `ready`.
 
-**Wave grouping:** Group tasks so Wave 1 = tasks with `dependencies: none`, Wave 2 = tasks depending on Wave 1, etc. Document the wave structure in `ACTIVE.md`.
+**Wave grouping:** Wave 1 = `dependencies: none`, Wave 2 = depends on Wave 1, etc. Document in ACTIVE.md.
 
 ## Phase 3 — Update state files
 
-**INDEX.md** — add one row per task:
-```
-| TASK-001 | <short name> | ready | none | - |
-```
+**INDEX.md** row per task: `| TASK-001 | <name> | ready | none | - |`
 
-**ACTIVE.md** — write snapshot:
+**ACTIVE.md** snapshot:
 ```
-Cycle: <cycle-ID>   Date: <YYYY-MM-DD>
+Cycle: <ID>   Date: <YYYY-MM-DD>
 Goal: <1 sentence>
 Tasks: <N> total | Wave 1: TASK-001, TASK-002 | Wave 2: TASK-003
 Status: planning_done — ready for executor
@@ -65,15 +68,13 @@ Status: planning_done — ready for executor
 
 ## Output
 
-Report:
-- Number of tasks created + their IDs
-- Wave structure
-- Any tasks flagged `needs_breakdown` (explain why)
-- Exact next step for human: "Switch to Sonnet/unic-code → run `/ukit:implement-handoff`"
+- Task count + IDs, wave structure
+- Any `needs_breakdown` tasks + reason
+- Next step: "Switch to Sonnet/unic-code → run `/ukit:implement-handoff`"
 
 ## Rules
 
-- Do NOT start implementing. Your job ends when all tasks are `ready` (or `needs_breakdown`).
-- If existing INDEX.md has undone tasks → warn human, ask: continue old cycle or clear and start fresh?
-- Prefer more smaller tasks over fewer large tasks. Each task should be completable in one executor session.
-- If you cannot determine test cases for a task → flag `needs_breakdown`, add a Discussion thread note explaining what's missing.
+- Do NOT implement. Job ends when all tasks are `ready` or `needs_breakdown`.
+- Undone tasks in INDEX.md → warn human: continue old cycle or start fresh?
+- Prefer smaller tasks. Each task = one executor session.
+- Cannot determine test cases → `needs_breakdown` + Discussion thread note.

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

@@ -1,73 +1,64 @@
-# /ukit:clear-handoff
+# /ukit:clear-handoff — Archive + Reset
 
-Spawn **ukit-small-task-maintainer** (Haiku / unic-lite) to archive and reset the cycle.
+**Role: CLEANUP**
+**Tool: any**
+**Model: lite model** (haiku · unic-lite · cheapest available — this is just file ops)
 
 **HARD GATE: Will NOT clear if any task is not `done`.**
 
 ---
 
-Spawn Agent:
-- `subagent_type: ukit-small-task-maintainer`
-- `model: haiku`
-- `prompt`:
+## Step 1 — Gate check (mandatory, cannot skip)
 
-```
-Clear the current handoff cycle.
-
-## Step 1 — GATE CHECK (mandatory, cannot skip)
+Read `docs/AI_HANDOFF/INDEX.md`. List every task + status.
 
-Read docs/AI_HANDOFF/INDEX.md.
-List every task and its status.
+If ANY task has status ≠ `done` → **STOP**. Report and exit:
 
-Find all tasks where status ≠ done:
-  - ready             → not started (run /ukit:implement-handoff TASK-xxx)
-  - in_progress       → executor still working
-  - pending_review    → waiting for review (run /ukit:review-handoff TASK-xxx)
-  - changes_requested → executor must fix (run /ukit:implement-handoff TASK-xxx)
-  - critical_block    → executor must fix (run /ukit:implement-handoff TASK-xxx)
-  - needs_breakdown   → planner must split (run /ukit:create-handoff to re-plan)
-  - blocked           → needs human decision
-
-If ANY task has status ≠ done → STOP IMMEDIATELY. Do NOT proceed to steps 2-4.
-Report:
+```
+⛔ Cannot clear — X task(s) not done:
+  TASK-001 [pending_review]    → run /ukit:review-handoff TASK-001
+  TASK-003 [changes_requested] → run /ukit:implement-handoff TASK-003
+  TASK-005 [ready]             → run /ukit:implement-handoff TASK-005
 
-  ⛔ Cannot clear — X task(s) not done:
-  - TASK-001 [pending_review] → run /ukit:review-handoff TASK-001
-  - TASK-003 [changes_requested] → run /ukit:implement-handoff TASK-003
-  
-  Fix all tasks first, then re-run /ukit:clear-handoff.
+Fix all tasks first, then re-run /ukit:clear-handoff.
+```
 
-Only continue to Step 2 if ALL tasks are done.
+Only proceed if ALL tasks are `done`.
 
 ## Step 2 — Cleanup worktrees
 
+```bash
 git worktree list | grep handoff/
-For each .worktrees/task-xxx:
-  git worktree remove .worktrees/task-xxx --force
-  git branch -D handoff/task-xxx
+# For each .worktrees/task-xxx:
+git worktree remove .worktrees/task-xxx --force
+git branch -D handoff/task-xxx
 git worktree prune
+```
 
 ## Step 3 — Archive cycle
 
-Read INDEX.md cycle ID.
-Write docs/AI_HANDOFF/archive/cycle-NNN.md:
-  # Cycle NNN — <YYYY-MM-DD>
-  ## Summary: <1 paragraph of what was accomplished>
-  ## Tasks: <copy INDEX.md table>
-
-If archive/ has > 3 files → delete oldest, append 1-line summary to HISTORY.md.
+Write `docs/AI_HANDOFF/archive/cycle-NNN.md`:
+```
+# Cycle NNN — <YYYY-MM-DD>
+## Summary: <1 paragraph of what was accomplished>
+## Tasks: <copy INDEX.md table>
+```
+If `archive/` has > 3 files → delete oldest, append 1-line to `HISTORY.md`.
 
 ## Step 4 — Reset state files
 
+```
 PLAN.md       → "# PLAN\n_(empty)_"
 INDEX.md      → empty table header only
 ACTIVE.md     → "# ACTIVE\n_(no active cycle)_"
 tasks/TASK-*.md → delete all (keep _TEMPLATE.md)
+```
 
 ## Step 5 — Report
 
 Cycle NNN archived. X tasks completed. Worktrees removed. Ready for new cycle.
-```
 
-After agent completes:
-> Ready for new cycle → `/ukit:create-handoff <description>`
+> Claude Code: spawn `ukit-small-task-maintainer` (haiku) with steps 1–5.
+> Other tools: use lite model, follow steps 1–5 above.
+
+**Next:** `/ukit:create-handoff <new problem description>`

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

@@ -1,39 +1,64 @@
-# /ukit:create-handoff
+# /ukit:create-handoff — Phase 1 + 2: Plan
 
-Spawn a **handoff-planner** agent (Opus / unic-smart) to run Phase 1 + Phase 2.
+**Role: PLANNER**
+**Tool: any** (Claude Code / Codex / Antigravity / Kilo / OpenCode — your choice)
+**Model split:**
+- Read/understand → lite model (haiku · unic-lite · cheapest available)
+- Write plan + tasks → strong model (Opus · unic-smart · strongest available)
 
 ## Problem / feature
 $ARGUMENTS
 
 ---
 
-Spawn Agent:
-- `subagent_type: handoff-planner`
-- `model: opus`
-- `prompt`:
+## Step 1 — Read context (lite model)
 
-```
-Problem to plan: $ARGUMENTS
+Use the lightest/cheapest model available. Read and summarize:
 
-1. Read docs/AI_HANDOFF/INDEX.md + ACTIVE.md
-   → If undone tasks exist, warn and ask human: continue old cycle or start fresh?
+1. `docs/AI_HANDOFF/INDEX.md` → current tasks + statuses (or "empty")
+2. `docs/AI_HANDOFF/ACTIVE.md` → active cycle info (or "no active cycle")
+3. `docs/AI_HANDOFF/RULES.md` → PLAN.md 6-section format + Task Gate required fields
+4. `docs/AI_HANDOFF/tasks/_TEMPLATE.md` → task file structure
 
-2. Read docs/AI_HANDOFF/RULES.md for PLAN.md format + Task Gate rules
+Return a compact summary. Do NOT write anything yet.
 
-3. Write docs/AI_HANDOFF/PLAN.md — all 6 sections mandatory:
-   §1 Intent | §2 Scope | §3 Approach | §4 Test Plan | §5 Verification Commands | §6 Acceptance Criteria
-   §4 Test Plan: happy path + ≥1 edge case + regression if bugfix
+> Claude Code: spawn `ukit-small-task-maintainer` (haiku) with the above prompt.
+> Other tools: switch to your lite model, run the above steps, keep the summary in context.
 
-4. Create docs/AI_HANDOFF/tasks/TASK-001.md ... using _TEMPLATE.md
-   Each task MUST have: Target Files, Dependencies, Test Cases, Test Files,
-   Verification Commands, Acceptance Criteria
-   Missing any field → status: needs_breakdown (never ready)
+---
+
+## Step 2 — Write plan + tasks (strong model)
+
+Switch to strongest model. Using the summary from Step 1 (do NOT re-read files):
+
+1. If INDEX.md has undone tasks → warn human: continue old cycle or start fresh?
+
+2. Write `docs/AI_HANDOFF/PLAN.md` — all 6 sections mandatory:
+   - §1 Intent — problem + success definition
+   - §2 Scope — in / out of scope
+   - §3 Approach — solution, trade-offs, alternatives rejected
+   - §4 Test Plan — happy path + ≥1 edge case + regression if bugfix (non-negotiable)
+   - §5 Verification — exact shell commands executor will run
+   - §6 Acceptance — done checklist
 
-5. Update INDEX.md — add row per task, status=ready
-6. Update ACTIVE.md — cycle snapshot + wave structure
+3. Create `docs/AI_HANDOFF/tasks/TASK-001.md`, `TASK-002.md`... from `_TEMPLATE.md`
+   Every task MUST have:
+   - Target Files (exact paths)
+   - Dependencies (`TASK-xxx` or `none`)
+   - Test Cases (Type | Name | Expected — ≥1 happy + ≥1 edge case)
+   - Test Files (exact paths)
+   - Verification Commands (runnable shell commands)
+   - Acceptance Criteria (checklist)
+   Missing any field → status: `needs_breakdown`, never `ready`
 
-7. Report: task list + statuses, wave map, next step for human
-```
+4. Update `INDEX.md` — one row per task, `status=ready`
+5. Update `ACTIVE.md` — cycle snapshot + wave structure (Wave 1 = no deps, Wave 2 = depends on Wave 1...)
+
+6. Report: task IDs, wave map, any `needs_breakdown` + reason
+
+> Claude Code: spawn `handoff-planner` (opus) with Step 1 summary + problem injected.
+> Other tools: switch to strong model, execute steps 1–6 above.
+
+---
 
-After agent completes, tell human:
-> Switch to **Sonnet / unic-code** → run `/ukit:implement-handoff`
+**Next:** switch to code model → `/ukit:implement-handoff`

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

@@ -1,47 +1,56 @@
-# /ukit:implement-handoff
+# /ukit:implement-handoff — Phase 3: Execute
 
-Spawn **feature-implementer** agents in parallel waves (Sonnet / unic-code).
+**Role: EXECUTOR**
+**Tool: any** (Claude Code / Codex / Antigravity / Kilo / OpenCode — your choice)
+**Model: code model** (Sonnet · unic-code · cheap-smart available)
 
 ## Target (optional)
 $ARGUMENTS
-_Empty = all ready tasks. Or: "TASK-001" for a specific task._
+_Empty = all `ready` tasks. Or: "TASK-001" for a specific task._
 
 ---
 
 1. Read `docs/AI_HANDOFF/INDEX.md`
-   - Collect tasks with status `ready` (or the specific task from $ARGUMENTS)
+   - Collect all tasks with status `ready` (or specific task from $ARGUMENTS)
    - If none → report and stop
 
-2. Group tasks into waves by dependency:
-   - Wave 1: tasks with `dependencies: none` or all deps already `done`
-   - Wave 2+: tasks whose deps are in the previous wave
+2. Group into waves by dependency:
+   - Wave 1: `dependencies: none` or all deps already `done`
+   - Wave 2+: depends on previous wave
 
-3. For each wave — spawn feature-implementer agents **in parallel**, one per task:
+3. For each wave — run tasks **in parallel** (one agent/session per task):
 
-```
-Implement docs/AI_HANDOFF/tasks/TASK-xxx.md in handoff mode.
+   **Each task executor does:**
 
-Worktree:
-  git worktree add -b handoff/task-xxx .worktrees/task-xxx
-  (skip -b if branch already exists)
+   ```
+   Worktree (isolated per task):
+     git worktree add -b handoff/task-xxx .worktrees/task-xxx
+     (omit -b if branch already exists)
 
-TDD (mandatory):
-  1. Write tests from §Test Cases → run → confirm RED
-  2. Implement → run → confirm GREEN
-  3. Run §Verification Commands → paste full output
+   TDD — mandatory:
+     1. Read §Test Cases from task file
+     2. Write tests → run → confirm RED
+     3. Implement → run → confirm GREEN
+     4. Run §Verification Commands → paste full output
 
-Executor Report (append to task file):
-  EXECUTOR_TOOL / EXECUTOR_MODEL / EXECUTOR_SUBAGENT: feature-implementer
-  Verification Output: <paste>
-  Status: PASS | FAIL
+   Executor Report (append to task file):
+     ## Executor Report
+     EXECUTOR_TOOL: <tool name>
+     EXECUTOR_MODEL: <exact model ID — must be honest, reviewer will check>
+     Verification Output: <paste>
+     Status: PASS | FAIL
 
-Update INDEX.md: status → pending_review
+   Update INDEX.md: status → pending_review
 
-If tests FAIL → fix in same worktree before updating status. Never mark pending_review with a FAIL.
-```
+   If FAIL → fix in same worktree before updating status.
+   Never mark pending_review while tests still fail.
+   ```
 
-4. Wait for all agents in the wave → run next wave
+   > Claude Code: spawn `feature-implementer` agent per task (parallel).
+   > Other tools: open each task in a separate session/tab with code model, follow steps above.
 
-5. Report: PASS/FAIL per task, worktrees created, any blockers
+4. Wait for all tasks in wave → run next wave if any
 
-> Switch to **Opus / unic-smart** → run `/ukit:review-handoff`
+5. Report: PASS/FAIL per task, worktrees created, blockers
+
+**Next:** switch to strong model → `/ukit:review-handoff`

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

@@ -1,11 +1,12 @@
-# /ukit:review-handoff
+# /ukit:review-handoff — Phase 4: Review
 
-Spawn **code-reviewer** agents (Opus / unic-smart — MUST differ from executor).
-After approval: merge worktree → delete branch + worktree.
+**Role: REVIEWER**
+**Tool: any** (Claude Code / Codex / Antigravity / Kilo / OpenCode — your choice)
+**Model: strong model, MUST differ from executor** (Opus · unic-smart · strongest available)
 
 ## Target (optional)
 $ARGUMENTS
-_Empty = all pending_review tasks. Or: "TASK-001" for a specific task._
+_Empty = all `pending_review` tasks. Or: "TASK-001" for a specific task._
 
 ---
 
@@ -13,34 +14,44 @@ _Empty = all pending_review tasks. Or: "TASK-001" for a specific task._
    - Collect tasks with status `pending_review` (or specific task from $ARGUMENTS)
    - If none → report and stop
 
-2. For each task — spawn a **code-reviewer** agent:
+2. For each task — **MUST use a different model than the executor**:
 
-```
-Review docs/AI_HANDOFF/tasks/TASK-xxx.md
+   ```
+   Read task file: docs/AI_HANDOFF/tasks/TASK-xxx.md
+
+   Model isolation check (first thing):
+     Read EXECUTOR_MODEL from Executor Report
+     → REFUSE if your model == EXECUTOR_MODEL (or either is unknown)
+     → This is non-negotiable. Same model reviewing its own work defeats the quality gate.
+
+   Re-run §Verification Commands fresh:
+     → Do NOT trust executor's output. Run them yourself.
+     → If FAIL → verdict: critical_block. Stop.
 
-Inputs:
-  - Task file (Test Plan + Verification Commands + Executor Report)
-  - Diff: git -C .worktrees/task-xxx diff main
+   Review diff:
+     git -C .worktrees/task-xxx diff main
+     Check: correctness, regression risk, security, edge cases, maintainability
 
-Steps:
-  1. Read EXECUTOR_MODEL from Executor Report
-     → REFUSE if same as your model (or model unknown)
-  2. Re-run §Verification Commands fresh — do NOT trust executor output
-     → If FAIL → verdict: critical_block, stop
-  3. Review diff: correctness, regression risk, security, maintainability
-  4. Append ## Reviewer Verdict to task file:
-       VERDICT: approved | approved_minor | changes_requested | critical_block
-       REVIEWER_MODEL / EXECUTOR_MODEL
-       VERIFICATION_RERUN: result
-       FINDINGS: critical / important / minor
-       NEXT_STATUS_FOR_INDEX: <status>
+   Append ## Reviewer Verdict to task file:
+     VERDICT: approved | approved_minor | changes_requested | critical_block
+     REVIEWER_MODEL: <your model>
+     EXECUTOR_MODEL: <from report>
+     VERIFICATION_RERUN: PASS | FAIL
+     FINDINGS:
+       critical: ...
+       important: ...
+       minor: ...
+     NEXT_STATUS_FOR_INDEX: <status>
+
+   Update INDEX.md: status = NEXT_STATUS_FOR_INDEX
+   ```
 
-  5. Update INDEX.md: set status = NEXT_STATUS_FOR_INDEX
-```
+   > Claude Code: spawn `code-reviewer` agent (opus) per task.
+   > Other tools: switch to strong model (different from executor), follow steps above per task.
 
-3. After each agent verdict:
+3. After each verdict:
 
-   **approved / approved_minor:**
+   **approved / approved_minor →** merge + cleanup:
    ```bash
    git merge handoff/task-xxx --no-ff -m "feat: merge TASK-xxx"
    git worktree remove .worktrees/task-xxx
@@ -48,14 +59,14 @@ Steps:
    # INDEX.md: status → done
    ```
 
-   **changes_requested / critical_block:**
+   **changes_requested / critical_block →** keep worktree for executor to fix:
    ```
-   Keep worktree — executor must fix
-   Write findings in task file §Discussion
+   Write findings in §Discussion of task file
    # INDEX.md: status → changes_requested | critical_block
    ```
 
-4. Report: approved+merged tasks, tasks needing fixes, remaining worktrees
+4. Report: merged tasks, tasks needing fixes, remaining worktrees
 
-> All done? → `/ukit:clear-handoff`
-> Tasks need fixes? → human runs `/ukit:implement-handoff TASK-xxx`
+**Next:**
+- All done → `/ukit:clear-handoff`
+- Has fixes → executor runs `/ukit:implement-handoff TASK-xxx`