@ngockhoale/ukit 1.5.10 → 1.5.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "1.5.10",
+  "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/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,61 +1,64 @@
-# /ukit:create-handoff
+# /ukit:create-handoff — Phase 1 + 2: Plan
 
-Two-step: **lite model reads context** → **Opus writes plan**.
+**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
 
 ---
 
-## Step 1 — Pre-read (Haiku / unic-lite, fast)
+## Step 1 — Read context (lite model)
 
-Spawn Agent:
-- `subagent_type: ukit-small-task-maintainer`
-- `model: haiku`
-- `prompt`:
+Use the lightest/cheapest model available. Read and summarize:
 
-```
-Read and summarize the current handoff state for the planner. Be compact.
+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
 
-1. Read docs/AI_HANDOFF/INDEX.md → list all tasks + statuses (or "empty" if none)
-2. Read docs/AI_HANDOFF/ACTIVE.md → current cycle ID + goal (or "no active cycle")
-3. Read docs/AI_HANDOFF/RULES.md → extract: PLAN.md 6 sections, Task Gate fields, wave grouping rule
-4. Read docs/AI_HANDOFF/tasks/_TEMPLATE.md → paste the template structure
+Return a compact summary. Do NOT write anything yet.
 
-Return a compact summary block the planner can read directly without opening files.
-```
+> 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.
 
 ---
 
-## Step 2 — Plan (Opus / unic-smart, strong)
+## Step 2 — Write plan + tasks (strong model)
 
-Take the summary from Step 1. Spawn Agent:
-- `subagent_type: handoff-planner`
-- `model: opus`
-- `prompt`:
+Switch to strongest model. Using the summary from Step 1 (do NOT re-read files):
 
-```
-Problem to plan: $ARGUMENTS
+1. If INDEX.md has undone tasks → warn human: continue old cycle or start fresh?
 
-Pre-read context (from lite agent):
-<insert Step 1 output here>
+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
 
-Using the context above (do NOT re-read the same files):
+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`
 
-1. If INDEX.md shows undone tasks → warn human: continue old cycle or start fresh?
+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...)
 
-2. Write docs/AI_HANDOFF/PLAN.md — all 6 sections (from RULES.md format in context):
-   §1 Intent | §2 Scope | §3 Approach | §4 Test Plan | §5 Verification | §6 Acceptance
-   §4 Test Plan: happy path + ≥1 edge case + regression if bugfix — non-negotiable
+6. Report: task IDs, wave map, any `needs_breakdown` + reason
 
-3. Create docs/AI_HANDOFF/tasks/TASK-001.md ... using _TEMPLATE.md structure (from context)
-   Each task MUST have all Task Gate fields. Missing any → needs_breakdown, never ready.
+> Claude Code: spawn `handoff-planner` (opus) with Step 1 summary + problem injected.
+> Other tools: switch to strong model, execute steps 1–6 above.
 
-4. Update INDEX.md — add rows, status=ready
-5. Update ACTIVE.md — cycle snapshot + wave structure
-
-6. Report: task list + IDs, wave map, any needs_breakdown, next step for human
-```
+---
 
-After both agents complete:
-> 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`