@ngockhoale/ukit 1.5.8 → 1.5.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "1.5.8",
+  "version": "1.5.10",
   "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

@@ -2,6 +2,8 @@
 
 Spawn **ukit-small-task-maintainer** (Haiku / unic-lite) to archive and reset the cycle.
 
+**HARD GATE: Will NOT clear if any task is not `done`.**
+
 ---
 
 Spawn Agent:
@@ -12,30 +14,59 @@ Spawn Agent:
 ```
 Clear the current handoff cycle.
 
-1. Read docs/AI_HANDOFF/INDEX.md
-   → If any task is in_progress or pending_review → WARN human, ask to confirm before proceeding
-
-2. Cleanup worktrees:
-   git worktree list | grep handoff/
-   For each .worktrees/task-xxx:
-     git worktree remove .worktrees/task-xxx --force
-     git branch -D handoff/task-xxx
-   git worktree prune
-
-3. Archive cycle:
-   Write docs/AI_HANDOFF/archive/cycle-NNN.md:
-     # Cycle NNN — <YYYY-MM-DD>
-     ## Summary: <1 paragraph>
-     ## Tasks: <INDEX.md table>
-   If archive/ has > 3 files → delete oldest, append 1-line to HISTORY.md
-
-4. Reset state files:
-   PLAN.md       → "# PLAN\n_(empty)_"
-   INDEX.md      → empty table header
-   ACTIVE.md     → "# ACTIVE\n_(no active cycle)_"
-   tasks/TASK-*.md → delete all (keep _TEMPLATE.md)
-
-5. Report: cycle archived, worktrees removed, ready for new cycle
+## Step 1 — GATE CHECK (mandatory, cannot skip)
+
+Read docs/AI_HANDOFF/INDEX.md.
+List every task and its status.
+
+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
+  
+  Fix all tasks first, then re-run /ukit:clear-handoff.
+
+Only continue to Step 2 if ALL tasks are done.
+
+## Step 2 — Cleanup worktrees
+
+git worktree list | grep handoff/
+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.
+
+## 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:

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

@@ -1,13 +1,35 @@
 # /ukit:create-handoff
 
-Spawn a **handoff-planner** agent (Opus / unic-smart) to run Phase 1 + Phase 2.
+Two-step: **lite model reads context** → **Opus writes plan**.
 
 ## Problem / feature
 $ARGUMENTS
 
 ---
 
+## Step 1 — Pre-read (Haiku / unic-lite, fast)
+
 Spawn Agent:
+- `subagent_type: ukit-small-task-maintainer`
+- `model: haiku`
+- `prompt`:
+
+```
+Read and summarize the current handoff state for the planner. Be compact.
+
+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 block the planner can read directly without opening files.
+```
+
+---
+
+## Step 2 — Plan (Opus / unic-smart, strong)
+
+Take the summary from Step 1. Spawn Agent:
 - `subagent_type: handoff-planner`
 - `model: opus`
 - `prompt`:
@@ -15,25 +37,25 @@ Spawn Agent:
 ```
 Problem to plan: $ARGUMENTS
 
-1. Read docs/AI_HANDOFF/INDEX.md + ACTIVE.md
-   → If undone tasks exist, warn and ask human: continue old cycle or start fresh?
+Pre-read context (from lite agent):
+<insert Step 1 output here>
+
+Using the context above (do NOT re-read the same files):
 
-2. Read docs/AI_HANDOFF/RULES.md for PLAN.md format + Task Gate rules
+1. If INDEX.md shows undone tasks → warn human: continue old cycle or start fresh?
 
-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
+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
 
-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)
+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.
 
-5. Update INDEX.md — add row per task, status=ready
-6. Update ACTIVE.md — cycle snapshot + wave structure
+4. Update INDEX.md — add rows, status=ready
+5. Update ACTIVE.md — cycle snapshot + wave structure
 
-7. Report: task list + statuses, wave map, next step for human
+6. Report: task list + IDs, wave map, any needs_breakdown, next step for human
 ```
 
-After agent completes, tell human:
+After both agents complete:
 > Switch to **Sonnet / unic-code** → run `/ukit:implement-handoff`