@ngockhoale/ukit 1.5.0 → 1.5.2

package/templates/docs/AI_HANDOFF.md

@@ -0,0 +1,118 @@
+# AI Handoff — {{project.name}}
+
+Dùng file này làm active handoff duy nhất cho project.
+Source code và test vẫn là sự thật cuối cùng.
+
+---
+
+## 1. Current Cycle Snapshot
+
+- Handoff status: `draft | ready_for_planning | ready_for_breakdown | ready_for_implementation | blocked | ready_for_next_cycle | done`
+- Current phase: `planning | breakdown | implementation | verification | wrap_up | cleared`
+- Updated at:
+- Updated by AI:
+- Human decision needed: `yes | no`
+- Human decision summary:
+
+---
+
+## 2. Handoff Rules
+
+### How human should submit ideas
+- Có thể nói tự nhiên: `ukit:handoff`, `đưa vào handoff`, `gom các ý tưởng này thành task`, `chia việc cho AI làm tiếp`.
+- Nếu request đã là task cụ thể, rõ file/logic/đầu ra hoặc đủ nhỏ để làm ngay, bypass handoff và thực hiện trực tiếp.
+- Nếu request là ý tưởng rộng, nhiều tính năng, cải tiến mơ hồ, brainstorming, nhiều plan/task, hoặc cần chia cho AI kế tiếp, dùng handoff.
+
+### Default handoff flow
+1. Capture ideas/request.
+2. Write a concrete plan.
+3. Split the plan into ordered tasks.
+4. Add target files, verification, dependencies, acceptance criteria, and stop conditions.
+5. Resolve `ready` tasks in order.
+6. Update this file with results.
+7. Clear active handoff by keeping summary + carry-forward backlog only.
+
+### Fast-AI task gate
+Một task chỉ được là `ready` khi có:
+- target file/folder rõ;
+- action cụ thể;
+- dependency/blocker rõ;
+- verification rõ;
+- acceptance criteria rõ;
+- stop condition rõ;
+- không cần đoán product decision.
+
+Nếu thiếu, để `needs_breakdown`, `blocked`, hoặc `needs_human`.
+
+### Clear rule
+- `clear handoff` không bao giờ là wipe mù.
+- Trước khi clear, AI phải resolve hoặc triage task còn lại.
+- Completed work thành summary ngắn.
+- Unfinished work thành carry-forward backlog ngắn.
+- Sau clear, file phải ngắn, sẵn sàng cho cycle tiếp theo.
+
+### Docs sync rule
+- Handoff không thay thế docs.
+- Sau khi xong cycle, update các file docs trực tiếp bị ảnh hưởng như `docs/WORKLOG.md`, `docs/PROJECT.md`, `docs/CODE_MAP.md`, `CHANGELOG.md` nếu có liên quan.
+- Không cần update toàn bộ `docs/` nếu không bị ảnh hưởng.
+
+---
+
+## 3. Completed Cycle Summary
+
+### Cycle summary
+- completed:
+- verification:
+- important decisions:
+- carry-forward needed:
+
+---
+
+## 4. Carry-Forward Backlog
+
+### TASK-001
+- Title:
+- Priority: `P0-now | P1-next | P2-later | blocked | needs_human`
+- Size: `S | M | L`
+- AI capability: `fast_ai_ok | needs_smart_ai | needs_human`
+- Goal:
+- Target files:
+- Dependencies:
+- Must do:
+- Must not do:
+- Acceptance criteria:
+- Verification:
+- Stop condition:
+- Status: `ready | blocked | in_progress | done | needs_breakdown | needs_human`
+- Owner AI:
+
+### TASK-002
+- Title:
+- Priority: `P0-now | P1-next | P2-later | blocked | needs_human`
+- Size: `S | M | L`
+- AI capability: `fast_ai_ok | needs_smart_ai | needs_human`
+- Goal:
+- Target files:
+- Dependencies:
+- Must do:
+- Must not do:
+- Acceptance criteria:
+- Verification:
+- Stop condition:
+- Status: `ready | blocked | in_progress | done | needs_breakdown | needs_human`
+- Owner AI:
+
+---
+
+## 5. Decisions Made By Human
+
+- 
+- 
+
+---
+
+## 6. Do Not Lose This Context
+
+- 
+- 
+- 

package/templates/docs/INSTALL.md

@@ -47,8 +47,7 @@ End users do not need to manage any of that manually.
 Complete these files before first serious use:
 - `docs/PROJECT.md`
 - `docs/MEMORY.md`
-- `docs/STATUS.md`
-- `docs/TASKS.md`
+- `docs/AI_HANDOFF.md`
 - `docs/WORKLOG.md`
 
 ### 4) Open your AI tool
@@ -98,8 +97,7 @@ ukit install
 Check that the docs baseline files exist and are filled in:
 - `docs/PROJECT.md`
 - `docs/MEMORY.md`
-- `docs/STATUS.md`
-- `docs/TASKS.md`
+- `docs/AI_HANDOFF.md`
 - `docs/WORKLOG.md`
 
 ---

package/templates/docs/PROJECT.md

@@ -44,9 +44,8 @@
 
 1. Run `ukit memory recall "<current task>"` for non-trivial work; reuse relevant `## Previous Context` before asking the user to restate prior decisions
 2. Read `docs/MEMORY.md` — architecture decisions, active constraints, known bugs
-3. Read `docs/STATUS.md` for open-ended status/continue prompts or meaningful continuation context; treat stale status as orientation only
-4. Read `docs/TASKS.md` only when selecting queued AI work, or when status points at queued tasks; apply safe cleanup without deleting unfinished human intent
-5. Read `docs/CODE_MAP.md` if it exists — structural navigation index
-6. Use the installed source-code index / routed helpers to localize the smallest relevant file + test set first
-7. Scan recent `docs/WORKLOG.md` entries if continuing prior work
-8. Verify understanding against source before acting — **docs orient, source is truth; keep the index-first workflow intact**
+3. Read `docs/AI_HANDOFF.md` when continuing cross-AI planning, task breakdown, or task implementation handoff work
+4. Read `docs/CODE_MAP.md` if it exists — structural navigation index
+5. Use the installed source-code index / routed helpers to localize the smallest relevant file + test set first
+6. Scan recent `docs/WORKLOG.md` entries if continuing prior work
+7. Verify understanding against source before acting — **docs orient, source is truth; keep the index-first workflow intact**

package/templates/docs/UKIT_USAGE_GUIDE.md

@@ -138,11 +138,10 @@ Project đang ở đâu, làm gì tiếp?
 
 Expected UKit behavior:
 1. auto-load the hidden next-step lane
-2. read `docs/STATUS.md` first and show whether it is fresh, possibly stale, stale, or missing
-3. read `docs/TASKS.md` only when selecting queued work or when status points at queued tasks
+2. read `docs/AI_HANDOFF.md` when the team is passing planning, task breakdown, or implementation context between AIs
+3. verify the handoff against source/index before treating it as authoritative
 4. suggest only a few actionable next candidates
-5. if status/tasks are stale, verify with source/index before treating any candidate as authoritative
-6. if the prompt names a concrete bug/feature/review target, keep the concrete workflow primary instead of producing a global roadmap
+5. if the prompt names a concrete bug/feature/review target, keep the concrete workflow primary instead of producing a global roadmap
 
 ---
 

package/templates/ukit/storage/config.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.5.0",
+  "version": "1.5.2",
   "agent": "claude-code",
   "autonomy": {
     "level": "balanced",