@ngockhoale/ukit 1.5.1 → 1.5.2

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 All notable changes to UKit are documented here.
 
+## 1.5.2 - 2026-05-28
+
+### Added
+
+- Added first-class `ukit:handoff` prompt detection and routing for explicit handoff/brainstorm-to-task flows.
+- Added `intentMode: handoff` to route summaries so hooks and helpers can prioritize `docs/AI_HANDOFF.md` automatically.
+- Added a reusable generic `docs/AI_HANDOFF.md` handoff template for installed projects.
+
+### Changed
+
+- Handoff prompts now route through `docs-quality` skill instead of generic `update-status`, making `docs/AI_HANDOFF.md` the primary coordination artifact.
+- Updated installed `next-step` skill guidance to read `docs/AI_HANDOFF.md` first for explicit handoff prompts.
+- Updated `route-task` mirror and hook behavior in both source and installed artifact so `ukit install` users get consistent handoff routing.
+
+### Fixed
+
+- Handoff authoring is now advisory (exit 0) in Safe Patch, so large `docs/AI_HANDOFF.md` batches no longer block the handoff workflow.
+- Hard runtime/shared-risk file broad rewrites still block by default unless `advisoryOnly=true` or `UKIT_SAFE_PATCH_ADVISORY=1` is set.
+
+### Tests
+
+- Added explicit handoff routing coverage in `tests/index/taskRouting.test.js`.
+- Verified Safe Patch protocol still passes 12 tests including the new handoff advisory case.
+
 ## 1.5.0 - 2026-05-24
 
 ### Fixed

package/README.md

@@ -32,8 +32,7 @@ ukit install
 4. Fill in the generated docs baseline:
    - `docs/PROJECT.md`
    - `docs/MEMORY.md`
-   - `docs/STATUS.md`
-   - `docs/TASKS.md`
+   - `docs/AI_HANDOFF.md`
    - `docs/WORKLOG.md`
 5. Open your AI tool and work in natural language.
 
@@ -66,7 +65,7 @@ If maintainers roll out a newer CLI build, the in-project workflow still stays t
 **Project support files**
 - `.claude/ukit/.ukit/` — installer manifests, metadata, backups
 - `.ukit/` — hidden shared runtime storage for config, cache, and cross-agent memory
-- `docs/` — PROJECT / MEMORY / STATUS / TASKS / WORKLOG baseline
+- `docs/` — PROJECT / MEMORY / AI_HANDOFF / WORKLOG baseline
 
 ## UKit v1.3.1 Runtime
 
@@ -91,8 +90,7 @@ UKit v1.3.1 keeps the same shared runtime contract while adding Safe Patch Proto
 - install globally with `npm install -g @ngockhoale/ukit`
 - keep using the exact same human workflow inside projects: `ukit install`
 - preserve the same `ukit` binary, hooks, and install-first orchestration while standardizing the runtime root as hidden `.ukit/`
-- install `docs/STATUS.md` as a compact living state file for active work, debug threads, blockers, verification, and next candidates
-- install gitignored `docs/TASKS.md` as a local AI task queue for deferred/ready work, with safe AI cleanup rules that remove duplicates and prune completed history without deleting unfinished human intent
+- install `docs/AI_HANDOFF.md` as the default cross-AI handoff file for plan → task breakdown → implementation continuity, with explicit sections so one AI can plan, another can refine tasks, and another can implement them reliably
 - auto-route open-ended “what next?” / “continue” prompts to the `next-step` skill with a visible freshness cue when status may be stale
 - auto-route explicit handoff/wrap-up requests to the `update-status` skill while skipping trivial/no-state-change tasks
 - keep concrete debug/implementation/review prompts primary, so project status never replaces source/index-first task work

package/manifests/platform.full.yaml

@@ -143,10 +143,10 @@ items:
     packs:
       - core
 
-  - id: docs-status
+  - id: docs-ai-handoff
     type: config
-    sourceTemplate: docs/STATUS.md
-    targetPath: docs/STATUS.md
+    sourceTemplate: docs/AI_HANDOFF.md
+    targetPath: docs/AI_HANDOFF.md
     requires:
       - docs-project
       - docs-memory
@@ -159,19 +159,6 @@ items:
     packs:
       - core
 
-  - id: docs-tasks
-    type: config
-    sourceTemplate: docs/TASKS.md
-    targetPath: docs/TASKS.md
-    requires:
-      - docs-status
-    mergeStrategy: skip
-    variables:
-      - project.name
-    enabledByDefault: true
-    packs:
-      - core
-
   - id: docs-bugfix
     type: config
     sourceTemplate: docs/BUGFIX.md
@@ -495,8 +482,7 @@ items:
     targetPath: .claude/skills/next-step/SKILL.md
     requires:
       - docs-quality-skill
-      - docs-status
-      - docs-tasks
+      - docs-ai-handoff
     mergeStrategy: overwrite_with_backup
     variables: []
     enabledByDefault: true
@@ -509,8 +495,7 @@ items:
     targetPath: .claude/skills/update-status/SKILL.md
     requires:
       - docs-quality-skill
-      - docs-status
-      - docs-tasks
+      - docs-ai-handoff
     mergeStrategy: overwrite_with_backup
     variables: []
     enabledByDefault: true

package/package.json

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

package/src/cli/commands/doctor.js

@@ -62,8 +62,7 @@ export async function runDoctor({ packageRoot, projectRoot, argv = [] }) {
     sessionMemoryDirExists: await pathExists(runtimePaths.sessionsDir),
     docsProjectExists: await pathExists(path.join(projectRoot, 'docs', 'PROJECT.md')),
     docsMemoryExists: await pathExists(path.join(projectRoot, 'docs', 'MEMORY.md')),
-    docsStatusExists: await pathExists(path.join(projectRoot, 'docs', 'STATUS.md')),
-    docsTasksExists: await pathExists(path.join(projectRoot, 'docs', 'TASKS.md')),
+    docsAiHandoffExists: await pathExists(path.join(projectRoot, 'docs', 'AI_HANDOFF.md')),
     docsWorklogExists: await pathExists(path.join(projectRoot, 'docs', 'WORKLOG.md')),
     allProvidersConfigured: providers.allSupported,
     ...(codexAdapterTracked
@@ -105,8 +104,7 @@ export async function runDoctor({ packageRoot, projectRoot, argv = [] }) {
   console.log(`[UKit]   ${ok(checks.sessionMemoryDirExists)}  .ukit/storage/memory/sessions/`);
   console.log(`[UKit]   ${ok(checks.docsProjectExists)}  docs/PROJECT.md`);
   console.log(`[UKit]   ${ok(checks.docsMemoryExists)}  docs/MEMORY.md`);
-  console.log(`[UKit]   ${ok(checks.docsStatusExists)}  docs/STATUS.md`);
-  console.log(`[UKit]   ${ok(checks.docsTasksExists)}  docs/TASKS.md`);
+  console.log(`[UKit]   ${ok(checks.docsAiHandoffExists)}  docs/AI_HANDOFF.md`);
   console.log(`[UKit]   ${ok(checks.docsWorklogExists)}  docs/WORKLOG.md`);
   if (codexAdapterTracked) {
     console.log(`[UKit]   ${ok(checks.codexReadmeExists)}  .codex/README.md`);

package/src/cli/commands/install.js

@@ -239,10 +239,10 @@ export async function runInstall({ packageRoot, projectRoot, packageVersion, arg
   const docsLabels = [
     'docs/PROJECT.md',
     'docs/MEMORY.md',
-    'docs/STATUS.md',
-    'docs/TASKS.md',
+    'docs/AI_HANDOFF.md',
     'docs/WORKLOG.md',
   ];
+
   const docsPaths = docsLabels.map((label) => path.join(projectRoot, ...label.split('/')));
   const missingDocs = [];
   for (let i = 0; i < docsPaths.length; i++) {
@@ -254,7 +254,7 @@ export async function runInstall({ packageRoot, projectRoot, packageVersion, arg
   if (missingDocs.length > 0) {
     console.log(`[UKit] Missing docs — fill these in before first use: ${missingDocs.join(', ')}`);
   } else {
-    console.log('[UKit] Docs baseline ready: docs/PROJECT.md, docs/MEMORY.md, docs/STATUS.md, docs/TASKS.md, docs/WORKLOG.md');
+    console.log('[UKit] Docs baseline ready: docs/PROJECT.md, docs/MEMORY.md, docs/AI_HANDOFF.md, docs/WORKLOG.md');
     console.log('[UKit] Fill them once with real project context for the best results.');
   }
 

package/src/cli/commands/uninstall.js

@@ -47,5 +47,5 @@ export async function runUninstall({ projectRoot, argv = [] }) {
   }
 
   console.log(`[UKit] Uninstall complete. Removed ${result.removed}/${result.attempted} managed paths.`);
-  console.log('[UKit] Note: docs/PROJECT.md, docs/MEMORY.md, docs/STATUS.md, docs/TASKS.md, docs/WORKLOG.md contain user content and were preserved. Delete manually if needed.');
+  console.log('[UKit] Note: docs/PROJECT.md, docs/MEMORY.md, docs/AI_HANDOFF.md, docs/WORKLOG.md contain user content and were preserved. Delete manually if needed.');
 }

package/src/core/ensureGitignore.js

@@ -11,8 +11,6 @@ const UKIT_ENTRIES = [
   'opencode.json',
   'AGENTS.md',
   'CLAUDE.md',
-  'docs/STATUS.md',
-  'docs/TASKS.md',
   '.claude/ukit/.ukit/',
   '.claude/ukit/permission-usage.json',
   '.claude/ukit/permission-audit.log',

package/src/core/runtimeConfig.js

@@ -49,7 +49,7 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
   const safeOverrides = isPlainObject(overrides) ? overrides : {};
 
   return mergeObjects({
-    version: '1.5.1',
+    version: '1.5.2',
     agent: 'claude-code',
     autonomy: {
       level: 'balanced',

package/src/index/taskRouting.js

@@ -243,8 +243,10 @@ export function buildRouteSummary({
       ),
   );
   const nextActionCommand = compactHelperLane ? null : nextAction?.command ?? null;
+  const handoffFile = routingContext.intentMode === 'handoff' ? 'docs/AI_HANDOFF.md' : null;
   const summaryLine = [
     routingContext.taskType ? `task=${routingContext.taskType}` : null,
+    handoffFile ? `handoff=${handoffFile}` : null,
     formatCompactSegment('targets', primaryTargets),
     formatCompactSegment('tests', relatedTests),
     formatCompactSegment('styles', styleFiles),
@@ -267,6 +269,7 @@ export function buildRouteSummary({
     completionState,
     continuationState,
     intentMode: routingContext.intentMode ?? null,
+    handoffFile,
     delegateHint: delegationRecommendation?.hint ?? null,
     nextActionType: nextAction?.type ?? null,
     nextActionCommand,
@@ -783,11 +786,11 @@ async function selectActiveSkills({ rootDir, promptText, commandText, targetFile
 }
 
 function shouldKeepRouteEntryForIntent(entry, intentMode) {
-  if (entry.id === 'next-step' && ['scoped-advice', 'docs-specific'].includes(intentMode)) {
+  if (entry.id === 'next-step' && ['scoped-advice', 'docs-specific', 'handoff'].includes(intentMode)) {
     return false;
   }
 
-  if (entry.id === 'update-status' && intentMode === 'docs-specific') {
+  if (entry.id === 'update-status' && ['docs-specific', 'handoff'].includes(intentMode)) {
     return false;
   }
 
@@ -896,6 +899,10 @@ function deriveIntentMode({ promptText = '', commandText = '', targetFile = null
   const openEndedStatus = hasOpenEndedStatusSignal(lower, raw) || taskQueueNext;
   const concreteTask = hasConcreteTaskSignal(lower, raw, targetFile, { taskQueueNext });
 
+  if (hasHandoffSignal(lower, raw)) {
+    return 'handoff';
+  }
+
   if (docsSpecific) {
     return 'docs-specific';
   }
@@ -927,6 +934,20 @@ function deriveIntentMode({ promptText = '', commandText = '', targetFile = null
   return null;
 }
 
+function hasHandoffSignal(lower, raw) {
+  return /\bukit:handoff\b/.test(raw)
+    || /\b(ai handoff|handoff phase|handoff mode|clear handoff|update handoff|start handoff|handoff clear)\b/.test(lower)
+    || /\b(brainstorm|idea dump|ideas?).{0,80}\b(handoff|tasks?|taskify|split|breakdown)\b/.test(lower)
+    || /\b(handoff|tasks?|taskify|split|breakdown).{0,80}\b(brainstorm|idea dump|ideas?)\b/.test(lower)
+    || /\b(gom|chia|tach|tách|lên|len|xóa|clear|dọn).{0,80}\b(idea|ý tưởng|y tuong|task|công việc|cong viec|handoff)\b/.test(raw)
+    || /\b(bàn giao|ban giao).{0,80}\b(ai|task|công việc|cong viec)\b/.test(raw);
+}
+
+function hasHandoffClearSignal(lower, raw) {
+  return /\b(clear handoff|handoff clear|dọn handoff|xóa handoff|reset handoff|compact handoff)\b/.test(lower)
+    || (/\bukit:handoff\b/.test(raw) && /\b(clear|dọn|xóa|reset|compact)\b/.test(lower));
+}
+
 function hasStatusUpdateSignal(lower, raw) {
   return /\b(update|refresh|write|sync|record|capture|summarize|summarise).{0,64}\b(status\.md|project status|current state|next candidates|session state)\b/.test(lower)
     || /\b(status\.md|project status).{0,64}\b(update|refresh|write|sync|record|capture|summarize|summarise)\b/.test(lower)

package/templates/.claude/skills/next-step/SKILL.md

@@ -44,11 +44,12 @@ If stale or missing, downgrade confidence and verify with the smallest current t
 ## Input Order
 
 Read only what is needed:
-1. `docs/STATUS.md` (or existing root `STATUS.md` fallback)
-2. `docs/TASKS.md` only for queued-task prompts, “continue” with no active status, or when status points at queued work
-3. `docs/CODE_MAP.md` only when navigation is needed
-4. `docs/MEMORY.md` only when constraints/decisions affect the suggestion
-5. routed index/tree summary only if status/tasks are stale, missing, or contradicted
+1. `docs/AI_HANDOFF.md` first when the prompt explicitly names handoff / `ukit:handoff` / brainstorm-to-task flow
+2. `docs/STATUS.md` (or existing root `STATUS.md` fallback) for normal status/continue prompts
+3. `docs/TASKS.md` only for queued-task prompts, “continue” with no active status, or when status points at queued work
+4. `docs/CODE_MAP.md` only when navigation is needed
+5. `docs/MEMORY.md` only when constraints/decisions affect the suggestion
+6. routed index/tree summary only if status/tasks are stale, missing, or contradicted
 
 ## Output Shape
 

package/templates/.claude/ukit/index/post-edit-verify.mjs

@@ -17,6 +17,10 @@ function getFilePath(payload = {}) {
   return payload.tool_input?.file_path || payload.file_path || '';
 }
 
+function isHandoffAuthoringFile(relativePath) {
+  return relativePath === 'docs/AI_HANDOFF.md';
+}
+
 async function listManifestPaths(backupsRoot) {
   const dates = await fs.readdir(backupsRoot, { withFileTypes: true }).catch(() => []);
   return dates
@@ -152,7 +156,8 @@ export async function verifyPostEdit({ projectRoot = process.cwd(), payload = {}
 
   const overChangedLines = delta.changedLines > Number(config.deltaMaxChangedLines || 120);
   const overHunks = delta.hunkCount > Number(config.deltaMaxHunks || 3);
-  const status = risk.strict && (overChangedLines || overHunks) ? 'blocked' : 'ok';
+  const handoffAdvisory = isHandoffAuthoringFile(resolved.relative) && risk.labels.every((label) => ['large-file', 'multilingual-text'].includes(label));
+  const status = risk.strict && (overChangedLines || overHunks) ? (handoffAdvisory ? 'advisory' : 'blocked') : 'ok';
   const postEntry = {
     event: 'post-edit',
     file: resolved.relative,
@@ -169,8 +174,8 @@ export async function verifyPostEdit({ projectRoot = process.cwd(), payload = {}
 
   return {
     ...postEntry,
-    message: status === 'blocked'
-      ? `BLOCKED: '${resolved.relative}' exceeded Safe Patch delta budget (changedLines=${delta.changedLines}/${config.deltaMaxChangedLines}, hunks=${delta.hunkCount}/${config.deltaMaxHunks}). Review diff or restore from ${latest.entry.rollbackPath}.`
+    message: status === 'blocked' || status === 'advisory'
+      ? `${status === 'advisory' ? 'ADVISORY' : 'BLOCKED'}: '${resolved.relative}' exceeded Safe Patch delta budget (changedLines=${delta.changedLines}/${config.deltaMaxChangedLines}, hunks=${delta.hunkCount}/${config.deltaMaxHunks}). Review diff or restore from ${latest.entry.rollbackPath}.`
       : `OK: '${resolved.relative}' delta changedLines=${delta.changedLines}, hunks=${delta.hunkCount}.`,
   };
 }
@@ -193,6 +198,9 @@ async function main() {
     process.stdout.write(`${JSON.stringify(result)}\n`);
   } else if (result.status === 'ok') {
     process.stdout.write(`[ukit-safe-patch] ${result.message}\n`);
+  } else if (result.status === 'advisory') {
+    process.stderr.write(`[ukit-safe-patch] ${result.message}\n`);
+    process.stderr.write('[ukit-safe-patch] handoff authoring advisory — change is already written; continue updating docs/AI_HANDOFF.md.\n');
   }
   if (result.status === 'blocked') {
     const advisory = isSafePatchAdvisoryOnly(runtimeConfig);

package/templates/.claude/ukit/index/route-task.mjs

@@ -723,11 +723,11 @@ async function selectActiveSkills({ rootDir, promptText, commandText, targetFile
 }
 
 function shouldKeepRouteEntryForIntent(entry, intentMode) {
-  if (entry.id === 'next-step' && ['scoped-advice', 'docs-specific'].includes(intentMode)) {
+  if (entry.id === 'next-step' && ['scoped-advice', 'docs-specific', 'handoff'].includes(intentMode)) {
     return false;
   }
 
-  if (entry.id === 'update-status' && intentMode === 'docs-specific') {
+  if (entry.id === 'update-status' && ['docs-specific', 'handoff'].includes(intentMode)) {
     return false;
   }
 
@@ -835,6 +835,10 @@ function deriveIntentMode({ promptText = '', commandText = '', targetFile = null
     return 'docs-specific';
   }
 
+  if (hasHandoffSignal(lower, raw)) {
+    return 'handoff';
+  }
+
   if (statusUpdate) {
     return 'status-update';
   }
@@ -870,6 +874,20 @@ function hasStatusUpdateSignal(lower, raw) {
     || /\b(cập nhật|ghi lại|tổng kết|chốt session|bàn giao).{0,64}\b(status|trạng thái|việc tiếp theo)\b/.test(raw);
 }
 
+function hasHandoffSignal(lower, raw) {
+  return /\bukit:handoff\b/.test(raw)
+    || /\b(ai handoff|handoff phase|handoff mode|clear handoff|update handoff|start handoff|handoff clear)\b/.test(lower)
+    || /\b(brainstorm|idea dump|ideas?).{0,80}\b(handoff|tasks?|taskify|split|breakdown)\b/.test(lower)
+    || /\b(handoff|tasks?|taskify|split|breakdown).{0,80}\b(brainstorm|idea dump|ideas?)\b/.test(lower)
+    || /\b(gom|chia|tach|tách|lên|len|xóa|clear|dọn).{0,80}\b(idea|ý tưởng|y tuong|task|công việc|cong viec|handoff)\b/.test(raw)
+    || /\b(bàn giao|ban giao).{0,80}\b(ai|task|công việc|cong viec)\b/.test(raw);
+}
+
+function hasHandoffClearSignal(lower, raw) {
+  return /\b(clear handoff|handoff clear|dọn handoff|xóa handoff|reset handoff|compact handoff)\b/.test(lower)
+    || (/\bukit:handoff\b/.test(raw) && /\b(clear|dọn|xóa|reset|compact)\b/.test(lower));
+}
+
 function hasOpenEndedStatusSignal(lower, raw) {
   return /\b(what next|what is next|what's next|next step|next steps|project status|current status|where are we|continue|continue from last session|roadmap|status\.md|task queue|tasks\.md|next queued task|pick next task|work from tasks)\b/.test(lower)
     || /\b(lam gi tiep|buoc tiep theo|tiep theo lam gi|lam tiep|dang o dau|trang thai project|tinh trang project|task tiep theo|viec tiep theo trong tasks)\b/.test(lower)

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.1",
+  "version": "1.5.2",
   "agent": "claude-code",
   "autonomy": {
     "level": "balanced",