@ngockhoale/ukit 1.5.22 → 1.5.23

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to UKit are documented here.
 
+## 1.5.23 - 2026-06-10
+
+### Added
+
+- `handoff-fullstack`: new all-in-one slash command combining `handoff-create` + `handoff-implement` + `handoff-review` into a single pipeline. Per-step model split (haiku/unic-lite for light work, sonnet/unic-code for implementation, opus/unic-smart for planning + review), plan auto-commit, conditional push on full approval, always-on worktree/branch cleanup, guaranteed clean git state at cycle end.
+
+## 1.5.22 - 2026-06-09
+
+### Changed
+
+- Internal: bumped version for release.
+
 ## 1.5.21 - 2026-06-09
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "1.5.22",
+  "version": "1.5.23",
   "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/handoff-fullstack.md

@@ -0,0 +1,331 @@
+# /ukit:handoff-fullstack — Full Pipeline: Plan → Implement → Review
+
+**Role: ORCHESTRATOR**
+**Tool: any** (Claude Code / Codex / Kilo / OpenCode — your choice)
+
+## Model Split
+
+| Work type | Model |
+|-----------|-------|
+| Light work (git ops, reads, summaries, consolidation) | haiku · unic-lite · lightest available |
+| Implementation (TDD, write code, edit files) | sonnet · unic-code · code model |
+| Planning + Review (reasoning, design, verification) | opus · unic-smart · strongest available |
+
+> Claude Code: spawn `ukit-small-task-maintainer` (haiku) for light steps; spawn `handoff-planner` (opus) for planning; spawn `feature-implementer` (sonnet) agents for implementation; spawn `code-reviewer` (opus) per task for review.
+
+---
+
+## Problem / feature
+$ARGUMENTS
+
+> **If `$ARGUMENTS` is empty:** Do NOT proceed. Ask the user: "What problem or feature would you like to tackle in this handoff cycle? Please describe it in one or more sentences." Wait for the answer before running any phase.
+
+---
+
+## Phase 1+2 — Plan (strong model)
+
+### P1 — Read context (lite model)
+
+Use the lightest model available. Read and return a compact summary of:
+
+1. `docs/AI_HANDOFF/INDEX.md` — current tasks + statuses (or "empty / no tasks")
+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, state machine
+4. `docs/AI_HANDOFF/tasks/_TEMPLATE.md` — task file structure
+
+Return a compact summary. Do NOT write any files yet.
+
+> Claude Code: spawn `ukit-small-task-maintainer` (haiku) for P1.
+
+### P2 — Write PLAN.md + task files (strong model)
+
+Switch to strongest model (opus / unic-smart). Use P1 summary — do NOT re-read files.
+
+1. **Guard — check INDEX statuses:**
+   - All tasks are `ready` (planning only) → re-run is allowed: overwrite `PLAN.md` and `TASK-xxx.md` freely (iterative refinement).
+   - Any task has status `pending_review`, `changes_requested`, `merge_conflict`, or `blocked` → **STOP**: warn the human — tasks are already in implement/review phase, cannot overwrite safely.
+   - No tasks → fresh cycle, proceed.
+
+2. **Resolve base branch:**
+   ```bash
+   BASE=$(git symbolic-ref --short HEAD)
+   ```
+
+3. **Write `docs/AI_HANDOFF/PLAN.md`** — all 6 sections mandatory:
+   - §1 Intent — problem + success definition
+   - §2 Scope — in / out of scope; same-wave tasks must not modify the same file (prevents merge conflicts)
+   - §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 (prefer verifiable criteria with commands)
+
+4. **Create `docs/AI_HANDOFF/tasks/TASK-001.md`, `TASK-002.md`...** from `_TEMPLATE.md`.
+   Every task MUST have:
+   - Target Files (exact paths — no two tasks in same wave share a file)
+   - Dependencies (`TASK-xxx` or `none` — wave structure inferred from this)
+   - Test Cases (Type | Name | Expected — ≥1 happy + ≥1 edge case)
+   - Test Files (exact paths)
+   - Verification Commands (runnable shell commands)
+   - Acceptance Criteria (verifiable checklist)
+   Missing any field → status `needs_breakdown`, never `ready`.
+
+5. **Update `docs/AI_HANDOFF/INDEX.md`** — one row per task, `status=ready`.
+
+6. **Update `docs/AI_HANDOFF/ACTIVE.md`:**
+   ```
+   Cycle: <ID>   Date: <YYYY-MM-DD>   Base: <BASE>
+   Goal: <1 sentence>
+   Tasks: <N> total
+   Status: planning_done — ready for executor
+   ```
+
+7. **Report:** task IDs, dependency graph, any `needs_breakdown` tasks + reason.
+
+> Claude Code: spawn `handoff-planner` (opus) with P1 summary + `$ARGUMENTS` problem.
+
+### P3 — Commit the plan (lite model)
+
+Use the lightest model. Run:
+```bash
+git add docs/AI_HANDOFF/ && git commit -m "handoff: plan — <goal>"
+```
+
+Replace `<goal>` with the one-sentence goal from ACTIVE.md. This locks the plan in git before any implementation begins.
+
+> Claude Code: spawn `ukit-small-task-maintainer` (haiku) for P3.
+
+---
+
+## Phase 3 — Implement (code model)
+
+### I1 — Setup + verify (lite model)
+
+Use the lightest model. Read:
+- `docs/AI_HANDOFF/ACTIVE.md` → get `Base: <BASE>`
+- `docs/AI_HANDOFF/INDEX.md` → collect all `ready` tasks
+
+If no ready tasks → report and stop.
+
+Verify working tree is clean after the plan commit:
+```bash
+git status   # must be clean — plan commit already done in P3
+```
+
+If working tree is dirty → stop. Ask human to resolve uncommitted changes first.
+
+> Claude Code: spawn `ukit-small-task-maintainer` (haiku) for I1.
+
+### I2 — Infer wave groups
+
+Read each `docs/AI_HANDOFF/tasks/TASK-xxx.md` for `Dependencies` field:
+- Wave 1: tasks with `Dependencies: none` (or all deps already `done`)
+- Wave N+1: tasks whose deps are all in Wave N or earlier
+- Chain A→B→C = 3 waves of 1 task each (sequential)
+- Independent A, B, C = 1 wave of 3 tasks (parallel)
+
+### I3 — Execute wave by wave (code model agents)
+
+For each wave:
+
+**3a — Create worktrees** (one per task, from `$BASE`):
+```bash
+git worktree add -b handoff/task-xxx .worktrees/task-xxx $BASE
+# (omit -b if branch already exists)
+```
+
+**3b — Run tasks in parallel** — one code-model agent per task, each in its own worktree. Each agent:
+```
+Read docs/AI_HANDOFF/tasks/TASK-xxx.md
+
+TDD — mandatory:
+  1. Write tests from §Test Cases
+     cd .worktrees/task-xxx && <test command>
+     Confirm RED (immediately GREEN → test is wrong — flag this)
+  2. Implement → run → confirm GREEN
+  3. Run §Verification Commands inside the worktree:
+     cd .worktrees/task-xxx && <each verification command>
+     Paste full output.
+
+DO NOT run: git add, git commit, git push — leave files as-is in worktree.
+
+Executor Report (append to task file — do NOT touch INDEX.md):
+  ## Executor Report
+  EXECUTOR_TOOL: <tool>
+  EXECUTOR_MODEL: <exact model ID — mandatory>
+  EXECUTOR_SUBAGENT: <name or "-">
+  Verification Output: <paste full output>
+  Status: PASS | FAIL
+  Note: <issues or "none">
+```
+
+> Claude Code: spawn `feature-implementer` (sonnet) agents in parallel, one per task in the wave.
+
+**3c — Copy changes back + delete worktrees** (orchestrator, after each task reports):
+
+For **PASS + EXECUTOR_MODEL present:**
+```bash
+WORKTREE=".worktrees/task-xxx"
+
+# Copy modified tracked files to main working tree
+git -C "$WORKTREE" diff --name-only | while read f; do
+  mkdir -p "$(dirname "$f")"
+  cp "$WORKTREE/$f" "$f"
+done
+
+# Copy new untracked files
+git -C "$WORKTREE" ls-files --others --exclude-standard | while read f; do
+  mkdir -p "$(dirname "$f")"
+  cp "$WORKTREE/$f" "$f"
+done
+
+# Delete worktree and branch immediately
+git worktree remove "$WORKTREE" --force
+git branch -D handoff/task-xxx
+```
+
+For **FAIL:**
+```bash
+git worktree remove .worktrees/task-xxx --force
+git branch -D handoff/task-xxx
+```
+
+For **EXECUTOR_MODEL missing:**
+```bash
+git worktree remove .worktrees/task-xxx --force
+git branch -D handoff/task-xxx
+# mark needs_executor_report in INDEX
+```
+
+Worktrees are **always deleted immediately** — no exceptions.
+
+### I4 — Consolidate + update INDEX (lite model)
+
+After all waves complete:
+
+1. Update `docs/AI_HANDOFF/INDEX.md`:
+   - PASS tasks → `pending_review`
+   - FAIL tasks → `blocked`
+   - EXECUTOR_MODEL missing → `needs_executor_report`
+
+2. Verify cleanup:
+   ```bash
+   git worktree list           # must show only main worktree
+   git branch | grep handoff   # must be empty
+   git diff --stat             # summary of all uncommitted changes
+   ```
+
+> Claude Code: spawn `ukit-small-task-maintainer` (haiku) for I4.
+
+---
+
+## Phase 4 — Review (strong model)
+
+### R1 — Setup (lite model)
+
+Use the lightest model. Read:
+- `docs/AI_HANDOFF/ACTIVE.md` → get `Base: <BASE>`
+- `docs/AI_HANDOFF/INDEX.md` → collect `pending_review` tasks
+
+Run:
+```bash
+git status       # should show modified/new files, no handoff branches/worktrees
+git diff --stat  # summary of all changes
+```
+
+If `git diff` is empty and `git status` is clean → implement was not completed. Stop and re-run Phase 3.
+
+> Claude Code: `ukit-small-task-maintainer` (haiku) for R1 reads; orchestrator handles R1 guard check.
+
+### R2 — Model isolation check (strong model, always first)
+
+Read `EXECUTOR_MODEL` from each task file `## Executor Report`.
+
+| Executor model | Reviewer model | Action |
+|----------------|----------------|--------|
+| present, ≠ reviewer | present | proceed |
+| present, == reviewer | present | **REFUSE** → `changes_requested`: "reviewer ≠ executor required" |
+| missing / blank | any | **REFUSE** → `changes_requested`: "EXECUTOR_MODEL missing — re-run Phase 3" |
+| "unknown" | present | proceed + flag: "executor model unverified — human confirm" |
+
+> Claude Code: spawn `code-reviewer` (opus) per task for R2–R4.
+
+### R3 — Re-run Verification Commands (strong model)
+
+```bash
+<each command from §Verification Commands across all pending_review tasks>
+```
+
+If any command fails → verdict `critical_block`. Stop. Do NOT proceed to R4.
+
+### R4 — Review unified diff + append verdict (strong model)
+
+```bash
+git diff    # all uncommitted changes vs $BASE
+git status  # overview of modified/new/deleted files
+```
+
+Review as one unified diff — correctness, regression risk, security, edge cases, maintainability. Cross-reference each task's intent in `docs/AI_HANDOFF/tasks/TASK-xxx.md`.
+
+Append verdict to each task file:
+```
+## Reviewer Verdict
+VERDICT: approved | approved_minor | changes_requested | critical_block
+REVIEWER_MODEL: <your exact model ID>
+EXECUTOR_MODEL: <from Executor Report>
+VERIFICATION_RERUN: PASS | FAIL
+FINDINGS:
+  critical: <file:line — what fails> | none
+  important: <file:line — risk> | none
+  minor: <style/naming> | none
+NEXT_STATUS_FOR_INDEX: <status>
+```
+
+### R5 — Commit + push or stop (orchestrator)
+
+**All tasks `approved` or `approved_minor`:**
+
+Update `docs/AI_HANDOFF/INDEX.md`: all approved tasks → `done`.
+
+```bash
+git add . && git commit -m "handoff: implement <goal>" && git push origin $BASE
+```
+
+Replace `<goal>` with the one-sentence goal from ACTIVE.md.
+
+**Any task `changes_requested` or `critical_block`:**
+
+Report which tasks need fixes. Do NOT push. Executor re-runs Phase 3 for those tasks.
+
+---
+
+## Cleanup Verification (always)
+
+Run at the very end of every cycle, regardless of outcome:
+
+```bash
+git worktree list           # must show ONLY main worktree
+git branch | grep handoff   # must be EMPTY
+git status                  # clean (fully approved + pushed) or expected partial state
+```
+
+If any lingering worktrees or handoff branches found, force-remove them:
+```bash
+# For each lingering worktree/branch:
+git worktree remove .worktrees/<name> --force
+git branch -D handoff/<name>
+```
+
+Re-run assertions after removal to confirm clean state.
+
+---
+
+## Final Report
+
+```
+handoff-fullstack complete:
+  Cycle: <ID>
+  Tasks: <N> approved, <M> blocked
+  Git: committed + pushed to <branch> | pending human (<M> blocked)
+  Worktrees: all cleaned
+  Branches: all cleaned
+```