@ngockhoale/ukit 1.1.7 → 1.2.1

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

@@ -230,11 +230,17 @@ async function prepareTaskRoute({
   const normalizedPrompt = String(promptText || '').trim();
   const normalizedCommand = String(commandText || '').trim();
   const normalizedTarget = normalizeRelativeFile(absoluteRoot, targetFile);
+  const intentMode = deriveIntentMode({
+    promptText: normalizedPrompt,
+    commandText: normalizedCommand,
+    targetFile: normalizedTarget,
+  });
   const activeSkills = await selectActiveSkills({
     rootDir: absoluteRoot,
     promptText: normalizedPrompt,
     commandText: normalizedCommand,
     targetFile: normalizedTarget,
+    intentMode,
   });
   const selectedIds = activeSkills.map((entry) => entry.id);
   const contextIntent = deriveContextIntent({
@@ -262,6 +268,7 @@ async function prepareTaskRoute({
       targetFile: normalizedTarget,
       contextIntent,
       taskType: inferredTaskType,
+      intentMode,
     },
   };
 }
@@ -624,7 +631,7 @@ async function readHelperCacheSnapshot({
   };
 }
 
-async function selectActiveSkills({ rootDir, promptText, commandText, targetFile }) {
+async function selectActiveSkills({ rootDir, promptText, commandText, targetFile, intentMode = null }) {
   const routeSignals = {
     promptRawText: String(promptText || '').toLowerCase(),
     promptNormalizedText: buildNormalizedRouteSignalText(promptText),
@@ -635,6 +642,7 @@ async function selectActiveSkills({ rootDir, promptText, commandText, targetFile
   const scoredEntries = ROUTE_CATALOG
     .map((entry) => scoreSkillRouteEntry(entry, routeSignals))
     .filter((entry) => entry.score > 0)
+    .filter((entry) => shouldKeepRouteEntryForIntent(entry, intentMode))
     .sort((a, b) => b.score - a.score || a.order - b.order);
   const active = [];
 
@@ -650,6 +658,22 @@ async function selectActiveSkills({ rootDir, promptText, commandText, targetFile
   return active.map(({ order, ...rest }) => rest);
 }
 
+function shouldKeepRouteEntryForIntent(entry, intentMode) {
+  if (entry.id === 'next-step' && ['scoped-advice', 'docs-specific'].includes(intentMode)) {
+    return false;
+  }
+
+  if (entry.id === 'update-status' && intentMode === 'docs-specific') {
+    return false;
+  }
+
+  if (entry.id === 'docs-quality' && ['open-ended-status', 'status-update'].includes(intentMode)) {
+    return false;
+  }
+
+  return true;
+}
+
 function scoreSkillRouteEntry(entry, routeSignals = {}) {
   let score = 0;
   const reasons = [];
@@ -718,6 +742,131 @@ function getSignalTexts(signalType, routeSignals = {}) {
   };
 }
 
+function deriveIntentMode({ promptText = '', commandText = '', targetFile = null } = {}) {
+  const lower = buildNormalizedRouteSignalText(promptText, commandText);
+  const raw = `${promptText ?? ''}\n${commandText ?? ''}`.toLowerCase();
+  const taskQueueNext = hasTaskQueueNextSignal(lower, raw);
+  const docsSpecific = hasDocsSpecificTaskSignal(lower, raw, targetFile, { taskQueueNext });
+  const statusUpdate = hasStatusUpdateSignal(lower, raw);
+  const openEndedStatus = hasOpenEndedStatusSignal(lower, raw) || taskQueueNext;
+  const concreteTask = hasConcreteTaskSignal(lower, raw, targetFile, { taskQueueNext });
+
+  if (docsSpecific) {
+    return 'docs-specific';
+  }
+
+  if (statusUpdate) {
+    return 'status-update';
+  }
+
+  if (concreteTask && openEndedStatus) {
+    return 'scoped-advice';
+  }
+
+  if (openEndedStatus) {
+    return 'open-ended-status';
+  }
+
+  if (concreteTask) {
+    if (/\b(bug|debug|error|crash|broken|failing|stack trace|triage|fix|login|timeout)\b/.test(lower)) {
+      return 'debug-specific';
+    }
+    if (/\b(review|audit|diff|pr feedback|code review|kiem tra|soat)\b/.test(lower)) {
+      return 'review-specific';
+    }
+    if (/\b(implement|build|create|add|ship|deliver|refactor|integrate|integration|scaffold|feature)\b/.test(lower)) {
+      return 'implement-specific';
+    }
+  }
+
+  return null;
+}
+
+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)
+    || /\b(wrap up|handoff|end this session|ending this session|session summary|before final)\b/.test(lower)
+    || /\b(cap nhat|ghi lai|tong ket|chot session|ban giao).{0,64}\b(status|trang thai|viec tiep theo)\b/.test(lower)
+    || /\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 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)
+    || /\b(làm gì tiếp|bước tiếp theo|tiếp theo làm gì|làm tiếp|đang ở đâu|trạng thái project|tình trạng project|task tiếp theo|việc tiếp theo trong tasks)\b/.test(raw);
+}
+
+function hasTaskQueueNextSignal(lower, raw) {
+  return /\b(task queue|tasks\.md|next queued task|pick next task|work from tasks|next task from tasks|ready for ai)\b/.test(lower)
+    || /\b(task tiếp theo|việc tiếp theo trong tasks|làm task trong tasks|lấy task tiếp theo)\b/.test(raw);
+}
+
+function hasConcreteTaskSignal(lower, raw, targetFile, { taskQueueNext = false } = {}) {
+  if (targetFile && !isStatusFileTarget(targetFile) && !(taskQueueNext && isTasksFileTarget(targetFile))) {
+    return true;
+  }
+
+  return /\b(bug|debug|error|crash|broken|failing|stack trace|triage|fix|implement|build|create|add|ship|deliver|refactor|integrate|integration|scaffold|feature|review|audit|diff|pr feedback|code review|auth|login|api|endpoint|test|spec)\b/.test(lower)
+    || /\b(sửa|fix|lỗi|bug|debug|implement|cài|thêm|review|kiểm tra|soát|đăng nhập)\b/.test(raw);
+}
+
+function hasDocsSpecificTaskSignal(lower, raw, targetFile, { taskQueueNext = false } = {}) {
+  if (!targetFile || !isDocsTarget(targetFile)) {
+    return /\b(clean tasks|cleanup tasks|prune tasks|dedupe tasks|clear completed tasks|dọn tasks|dọn task)\b/.test(lower)
+      || /\b(dọn tasks|dọn task|dọn danh sách task|xóa task đã xong)\b/.test(raw);
+  }
+
+  if (taskQueueNext && isTasksFileTarget(targetFile) && !/\b(clean|cleanup|prune|dedupe|edit|template|wording|format|structure)\b/.test(lower)) {
+    return false;
+  }
+
+  const targetName = path.posix.basename(String(targetFile || '').replaceAll('\\', '/')).toLowerCase();
+  const explicitStatusUpdate = hasExplicitStatusUpdateSignal(lower, raw);
+
+  if (!isStatusFileTarget(targetFile)) {
+    if (explicitStatusUpdate && !mentionsTargetDoc(lower, targetName)) {
+      return false;
+    }
+
+    return mentionsTargetDoc(lower, targetName)
+      || /\b(edit|write|improve|document|docs?|readme|changelog|worklog|memory|code map|template|wording|copy|grammar|format|structure|heading|section|handoff notes?)\b/.test(lower)
+      || /\b(câu chữ|chỉnh|sửa chữ|ngữ pháp|định dạng|cấu trúc|tài liệu|ghi chú bàn giao)\b/.test(raw);
+  }
+
+  return /\b(template|wording|edit|copy|grammar|format|structure|heading|section|docs?)\b/.test(lower)
+    || /\b(mẫu|câu chữ|chỉnh|sửa chữ|ngữ pháp|định dạng|cấu trúc|tài liệu)\b/.test(raw);
+}
+
+function hasExplicitStatusUpdateSignal(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)
+    || /\b(cap nhat|ghi lai|tong ket|chot session|ban giao).{0,64}\b(status|trang thai|viec tiep theo)\b/.test(lower)
+    || /\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 mentionsTargetDoc(lower, targetName) {
+  if (!targetName) {
+    return false;
+  }
+
+  const escaped = targetName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const withoutExt = escaped.replace(/\\\.md$/i, '');
+  return new RegExp(`\\b(?:${escaped}|${withoutExt})\\b`, 'i').test(lower);
+}
+
+function isStatusFileTarget(targetFile) {
+  return /(?:^|\/)docs\/STATUS\.md$|(?:^|\/)STATUS\.md$/i.test(String(targetFile || ''));
+}
+
+function isTasksFileTarget(targetFile) {
+  return /(?:^|\/)docs\/TASKS\.md$|(?:^|\/)TASKS\.md$/i.test(String(targetFile || ''));
+}
+
+function isDocsTarget(targetFile) {
+  const normalized = String(targetFile || '').replaceAll('\\', '/');
+  return /(?:^|\/)docs\/.+\.md$|(?:^|\/)(?:README|CHANGELOG|AGENTS|CLAUDE|STATUS)\.md$/i.test(normalized);
+}
+
 function shouldUseIndexedContext({ activeSkills = [], targetFile = null } = {}) {
   if (activeSkills.length === 0) {
     return Boolean(targetFile);
@@ -966,6 +1115,16 @@ function deriveDelegationRecommendation({
   const hasRelatedTests = (preview.relatedTests ?? []).length > 0;
   const when = contextRecommendation?.command ? 'after-context' : 'now';
 
+  const smallTaskMaintenanceSignal = /\b(?:ukit|docs\/tasks\.md|tasks\.md|task queue|queued tasks?|compact(?:ion)?|summari[sz](?:e|ation)|doc(?:ument)? summary|cleanup|clean up|dọn rác|dọn dẹp|auto[- ]?triage|queue maintenance|small decision|ra quyết định)\b/.test(lower)
+    && /\b(?:task|queue|compact(?:ion)?|summari[sz](?:e|ation)|doc(?:ument)?s?|cleanup|clean up|dọn rác|dọn dẹp|classif(?:y|ication)|triage|maintenance|small decision|ra quyết định)\b/.test(lower);
+  if (smallTaskMaintenanceSignal) {
+    return {
+      hint: 'ukit-small-task-maintainer',
+      when,
+      reason: 'Low-risk UKit maintenance decisions should use the configured small-task model without blocking the main AI flow.',
+    };
+  }
+
   if (routingContext.taskType === 'trivial') {
     return null;
   }
@@ -1055,6 +1214,7 @@ function buildRouteSummary({
     formatCompactSegment('targets', primaryTargets),
     formatCompactSegment('tests', relatedTests),
     formatCompactSegment('styles', styleFiles),
+    delegationRecommendation?.hint ? `delegate=${delegationRecommendation.hint}` : null,
     policyMode ? `policy=${policyMode}` : null,
   ].filter(Boolean).join(' | ');
 
@@ -1063,6 +1223,7 @@ function buildRouteSummary({
     fallbackCommands,
     preferredOrder,
     policyMode,
+    intentMode: routingContext.intentMode ?? null,
     delegateHint: delegationRecommendation?.hint ?? null,
     nextActionType: nextAction?.type ?? null,
     nextActionCommand,
@@ -1580,6 +1741,7 @@ function compactRoutingContext(routingContext = {}) {
     adapter: routingContext.adapter ?? 'claude',
     lastExplicitUserPromptText: routingContext.lastExplicitUserPromptText ?? '',
     taskType: routingContext.taskType ?? null,
+    intentMode: routingContext.intentMode ?? null,
   };
 }
 

package/templates/.codex/README.md

@@ -12,7 +12,7 @@ Auto-generated by UKit for OpenAI Codex.
 - Do not make end users memorize skill names, helper scripts, or routing internals unless they are debugging UKit itself.
 - **Treat helper commands as internal orchestration. Do not ask end users to run them.**
 
-## UKit v1.1.7 Shared Runtime
+## UKit v1.2.1 Shared Runtime
 
 - Shared runtime state lives in `.ukit/storage/`.
 - Treat `.ukit/storage/config.json` as the source of compact, token-pipeline, router, memory, and validation toggles.
@@ -23,12 +23,15 @@ Auto-generated by UKit for OpenAI Codex.
 - Maintainers can inspect runtime state with `ukit status` and `ukit memory export`.
 - Reuse compact `previous-context` / `recent-output` route snapshots before replaying raw history.
 - Threshold-based compact pressure is internal orchestration; Codex users should not need to manage it manually.
+- UKit keeps Claude PreCompact/reinject and OpenCode native auto/prune compaction intact. For Codex Desktop long sessions, UKit can use `UKIT_SMALL_TASK_MODEL` through `ukit-small-task-maintainer` to decide soft auto-compact handoffs. Default `UKIT_CODEX_COMPACT_TARGET=150` means about 150 compact handoff lines (120-150 preferred, hard max 170), not 150 app-context tokens.
 
 ## Speed / Reading Contract
 
 - **Trivial**: no docs.
 - **Simple**: `docs/MEMORY.md` only.
 - **Non-trivial**: `docs/MEMORY.md` + `docs/PROJECT.md` + `docs/CODE_MAP.md`.
+- `docs/STATUS.md`: read for open-ended status/continue prompts or meaningful continuation context; stale status is orientation only.
+- `docs/TASKS.md`: read only for queued-task prompts or when status points at queued work; safely clean exact duplicates/completed overflow by default without deleting unfinished human-authored tasks.
 - Read `docs/WORKLOG.md` only when recent continuation/debug context matters.
 - Source is truth; if docs are stale, update docs and continue.
 
@@ -52,6 +55,9 @@ For clearly non-code specialist lanes, avoid dragging the source-code index into
 - Match from prompt wording plus tool/file evidence.
 - Use the smallest useful set, usually 1-2 skills.
 - If docs work is detected, prefer `.codex/skills/docs-quality/SKILL.md`.
+- For open-ended “what next?” / “continue” / project-status / queued-task prompts, prefer `.codex/skills/next-step/SKILL.md` and show a status freshness cue when status is used.
+- For explicit handoff/wrap-up/status updates, prefer `.codex/skills/update-status/SKILL.md`.
+- Concrete debug/implementation/review prompts beat open-ended wording; do not let `next-step` replace the concrete workflow.
 - If routing is complex or ambiguous, prefer `node .codex/ukit/index/route-task.mjs "<prompt>" [--tool-command <cmd>] [--target <file>]`.
 - That helper should keep shared route memory in `.claude/ukit/skill-router-state.json` so Claude and Codex continue from the same compact route state.
 - When route memory already includes `previous-context` or `recent-output`, reuse it before widening reads or logs.
@@ -68,6 +74,8 @@ For clearly non-code specialist lanes, avoid dragging the source-code index into
 ## Docs Discipline
 
 After significant work, update only what changed:
+- `docs/STATUS.md` — compact current state, blockers, verification, next candidates
+- `docs/TASKS.md` — local AI task queue; remove duplicates/prune completed overflow safely, never delete unfinished human intent by default
 - `docs/WORKLOG.md`
 - `docs/MEMORY.md`
 - `docs/CODE_MAP.md`

package/templates/.codex/settings.json

@@ -33,9 +33,18 @@
     "maxAnalogFiles": 3,
     "maxSharedAbstractions": 2,
     "contextBudgetByTier": {
-      "trivial": { "minFiles": 1, "maxFiles": 2 },
-      "simple": { "minFiles": 2, "maxFiles": 5 },
-      "non-trivial": { "minFiles": 4, "maxFiles": 8 }
+      "trivial": {
+        "minFiles": 1,
+        "maxFiles": 2
+      },
+      "simple": {
+        "minFiles": 2,
+        "maxFiles": 5
+      },
+      "non-trivial": {
+        "minFiles": 4,
+        "maxFiles": 8
+      }
     }
   },
   "skillRouter": {
@@ -65,6 +74,12 @@
       ],
       "maintenance": [
         "repo-maintenance"
+      ],
+      "nextStep": [
+        "next-step"
+      ],
+      "statusUpdate": [
+        "update-status"
       ]
     },
     "toolSignals": {
@@ -89,7 +104,8 @@
     },
     "routingRule": {
       "endUserShouldNotNeedSkillNames": true,
-      "selectSmallestUsefulSkillSet": true
+      "selectSmallestUsefulSkillSet": true,
+      "concreteTaskBeatsOpenEndedStatus": true
     },
     "delegationBridge": {
       "enabled": true,
@@ -130,6 +146,119 @@
         "askBeforeBroadVerificationWithoutRelatedTests": true,
         "preferCommandOrderFromVerificationPlan": true
       }
+    },
+    "smallTaskModel": {
+      "env": "UKIT_SMALL_TASK_MODEL",
+      "default": "unic-lite",
+      "agent": "ukit-small-task-maintainer",
+      "useFor": [
+        "task-cleanup",
+        "compact-decision",
+        "codex-context-budget",
+        "doc-summarization",
+        "classification",
+        "small-decision",
+        "auto-triage",
+        "queue-maintenance",
+        "workspace-maintenance"
+      ],
+      "keepMainModelFor": [
+        "security",
+        "risky-code-change",
+        "release",
+        "data-loss",
+        "architecture-decision",
+        "deep-reasoning"
+      ],
+      "internalOnly": true,
+      "decisionPolicy": {
+        "nonBlocking": true,
+        "endUserInvisible": true,
+        "handBackOnRisk": true,
+        "optimizeOrder": [
+          "quality",
+          "safety",
+          "speed",
+          "token-discipline"
+        ],
+        "decisions": [
+          "fast-vs-slow-lane",
+          "safe-vs-risky-lane",
+          "skill-routing-needed",
+          "step-budget-enough",
+          "compact-now-or-later",
+          "summarize-docs-or-keep-detail"
+        ],
+        "stepBudgets": {
+          "trivial": {
+            "maxSteps": 1,
+            "verification": "skip-unless-risky"
+          },
+          "simple": {
+            "maxSteps": 2,
+            "verification": "targeted-if-covered"
+          },
+          "nonTrivial": {
+            "maxSteps": 4,
+            "verification": "targeted-then-widen-on-risk"
+          }
+        },
+        "executionMode": "sidecar-parallel",
+        "mustNotBlockMainTask": true,
+        "maxSidecarWaitMs": 0
+      },
+      "codexContext": {
+        "autoCompact": true,
+        "budgetTokens": 60000,
+        "compactTarget": 150,
+        "compactTargetUnit": "lines",
+        "targetEnv": "UKIT_CODEX_COMPACT_TARGET",
+        "budgetEnv": "UKIT_CODEX_CONTEXT_BUDGET",
+        "autoCompactEnv": "UKIT_CODEX_AUTO_COMPACT",
+        "mode": "soft-handoff",
+        "preserve": [
+          "current-goal",
+          "non-negotiable-rules",
+          "active-files",
+          "decisions",
+          "unresolved-failures",
+          "verification-evidence",
+          "next-actions"
+        ],
+        "compactTargetRecommendedRange": [
+          120,
+          170
+        ],
+        "compactTargetMax": 170
+      },
+      "agentContext": {
+        "preserveClaudePreCompact": true,
+        "preserveOpenCodeCompaction": true,
+        "codexSoftHandoff": {
+          "autoCompact": true,
+          "budgetTokens": 60000,
+          "compactTarget": 150,
+          "compactTargetUnit": "lines",
+          "targetEnv": "UKIT_CODEX_COMPACT_TARGET",
+          "budgetEnv": "UKIT_CODEX_CONTEXT_BUDGET",
+          "autoCompactEnv": "UKIT_CODEX_AUTO_COMPACT",
+          "mode": "soft-handoff",
+          "preserve": [
+            "current-goal",
+            "non-negotiable-rules",
+            "active-files",
+            "decisions",
+            "unresolved-failures",
+            "verification-evidence",
+            "next-actions"
+          ],
+          "compactTargetRecommendedRange": [
+            120,
+            170
+          ],
+          "compactTargetMax": 170
+        }
+      }
     }
   },
   "execution": {
@@ -151,7 +280,7 @@
         "autoAllowInWorkspaceOnly": [
           "build",
           "format",
-        "safe file writes"
+          "safe file writes"
         ]
       },
       "high": {

package/templates/.gitignore

@@ -54,6 +54,8 @@ Thumbs.db
 opencode.json
 AGENTS.md
 CLAUDE.md
+docs/STATUS.md
+docs/TASKS.md
 .codex/settings.local.json
 
 # Keep tracked template hook sources under templates/.claude/hooks/

package/templates/AGENTS.md

@@ -30,7 +30,9 @@
 - review / audit / diff / PR feedback → `.claude/skills/code-review/SKILL.md`
 - bug / error / crash / triage / failing path → `.claude/skills/debugging-toolkit/SKILL.md`
 - test / spec / coverage / fixture → `.claude/skills/testing-quality/SKILL.md`
-- docs / README / changelog / handoff / editing `docs/` → `.claude/skills/docs-quality/SKILL.md`
+- docs / README / changelog / handoff / editing `docs/` / cleaning `docs/TASKS.md` → `.claude/skills/docs-quality/SKILL.md`
+- open-ended next step / project status / continue with no concrete target / choose queued task → `.claude/skills/next-step/SKILL.md`
+- explicit handoff / wrap up / update `docs/STATUS.md` → `.claude/skills/update-status/SKILL.md`
 - auth / security / token / permission / validation / risky shell-path-delete-db work → `.claude/skills/discover-security/SKILL.md`
 - stale workspace / reinstall / cleanup / maintenance → `.claude/skills/repo-maintenance/SKILL.md`
 
@@ -41,7 +43,7 @@
 - If a concrete verification lane is needed, prefer `node .claude/ukit/index/verify-context.mjs ...`.
 - These helper/index commands are internal orchestration. Run them yourself when needed; never turn them into required end-user workflow.
 
-## UKit v1.1.7 Shared Runtime
+## UKit v1.2.1 Shared Runtime
 
 - Shared runtime state lives in `.ukit/storage/`.
 - Treat `.ukit/storage/config.json` as the source of runtime toggles for compact, token pipeline, router, memory, and validation behavior.
@@ -59,9 +61,28 @@
 - **Trivial**: no docs, no index query unless the file target is unclear.
 - **Simple**: default to `docs/MEMORY.md` only; pull related files/tests with the resolver.
 - **Non-trivial**: read `docs/MEMORY.md` + `docs/PROJECT.md` + `docs/CODE_MAP.md`.
+- `docs/STATUS.md`: read for open-ended status/continue prompts or meaningful continuation context; treat stale status as orientation only and verify against source/index.
+- `docs/TASKS.md`: read only for queued-task prompts or when status points at queued work; safely clean exact duplicates/completed overflow by default without deleting unfinished human-authored tasks.
 - `docs/WORKLOG.md`: only recent, relevant entries for continuation/debugging.
 - Follow routed verification policy: targeted first when localized, widen in order for shared/risky scope, ask before blanket broad runs when no related-test evidence exists.
 
+## Living Status Workflow
+
+- `docs/STATUS.md` is compact current state, not a transcript and not source truth.
+- When the user asks “what next?”, “continue”, or “project đang ở đâu?” without a concrete target, use the `next-step` skill and show a freshness cue (fresh / possibly stale / stale / missing).
+- Concrete debug/implementation/review prompts beat open-ended wording; use the concrete skill first and only use status as background.
+- After meaningful work, use `update-status` to record state, verification, blockers, and next candidates; skip trivial/no-state-change tasks.
+- `docs/TASKS.md` is a local AI task queue: prefer `Ready for AI` when asked to pick queued work, and clean duplicates/prune `Done Recently` safely when reading/updating it.
+- Detailed task context files such as `docs/context/<slug>.md` are a future extension, not required baseline workflow.
+
+
+## Small-Task Maintainer (internal)
+
+- UKit may route low-risk internal decisions to the `ukit-small-task-maintainer` subagent using `UKIT_SMALL_TASK_MODEL` (default `unic-lite`).
+- Use it for safe/reversible UKit chores: dọn `docs/TASKS.md`, queued-task classification, fast-vs-slow/safe-vs-risky lane decisions, skill-routing/step-budget hints, agent context-budget decisions, compact/summary decisions, docs/status summarization, auto-triage, queue maintenance, and small workspace cleanup.
+- Run it as a sidecar/parallel lane only; do not block, replace, or slow the user task. Do not block the main AI flow: if the small-task lane sees security, risky/shared code, release/publish, data-loss, architecture, deep-reasoning risk, weak context, or quality risk, it hands back to the main model instead of asking the end user to decide.
+- This is optional internal orchestration config from `.claude/ukit/.env` / `.ukit/storage/config.json`; never turn it into an end-user workflow. End users still only need `ukit install` and natural-language product work. Always preserve the CoDev priority: quality > safety > speed > token discipline. Keep Claude PreCompact/reinject and OpenCode native auto/prune compaction enabled. For Codex Desktop long sessions, `UKIT_CODEX_COMPACT_TARGET` defaults to 150 compact handoff lines (120-150 preferred, hard max 170), decided internally by the small-task maintainer.
+
 ## Subagent Policy (internal only)
 
 - Default to direct execution for trivial/simple work.

package/templates/CLAUDE.md

@@ -28,7 +28,9 @@
 - review / audit / diff → `.claude/skills/code-review/SKILL.md`
 - bug / error / crash / triage → `.claude/skills/debugging-toolkit/SKILL.md`
 - test / spec / coverage → `.claude/skills/testing-quality/SKILL.md`
-- docs / README / changelog / handoff / editing `docs/` → `.claude/skills/docs-quality/SKILL.md`
+- docs / README / changelog / handoff / editing `docs/` / cleaning `docs/TASKS.md` → `.claude/skills/docs-quality/SKILL.md`
+- open-ended next step / project status / continue with no concrete target / choose queued task → `.claude/skills/next-step/SKILL.md`
+- explicit handoff / wrap up / update `docs/STATUS.md` → `.claude/skills/update-status/SKILL.md`
 - auth / security / token / permission / validation → `.claude/skills/discover-security/SKILL.md`
 - stale workspace / reinstall / cleanup → `.claude/skills/repo-maintenance/SKILL.md`
 
@@ -40,7 +42,7 @@
 - **Do not ask normal contributors to run internal helper commands**; run them yourself or tell them to rerun `ukit install`.
 - Do not ask normal contributors to memorize `ukit doctor`, `ukit diff`, `ukit uninstall`, or `ukit index ...` unless they explicitly need maintainer/debug help.
 
-## UKit v1.1.7 Shared Runtime
+## UKit v1.2.1 Shared Runtime
 
 - Shared runtime state lives in `.ukit/storage/`.
 - Treat `.ukit/storage/config.json` as the source of runtime toggles for compact, token pipeline, router, memory, and validation behavior.
@@ -56,9 +58,28 @@
 - **Trivial**: no docs.
 - **Simple**: `docs/MEMORY.md` only, plus resolver-selected files/tests.
 - **Non-trivial**: `docs/MEMORY.md` + `docs/PROJECT.md` + `docs/CODE_MAP.md`.
+- `docs/STATUS.md`: use for open-ended status/continue prompts or meaningful continuation context; stale status is orientation only.
+- `docs/TASKS.md`: use only for queued-task prompts or when status points at queued work; safely clean exact duplicates/completed overflow by default without deleting unfinished human-authored tasks.
 - `docs/WORKLOG.md`: only recent relevant entries.
 - Follow routed verification policy: targeted first, widen only when risk/shared scope justifies it, ask before blanket broad runs.
 
+## Living Status Workflow
+
+- `docs/STATUS.md` captures compact current state, active work, debug threads, blockers, verification, and next candidates.
+- It is not source truth and must not replace source/index-first investigation.
+- For “what next?” / “continue” prompts without a concrete target, use `next-step` and show a freshness cue before relying on the status file.
+- For concrete debug/implementation/review prompts, keep the concrete workflow primary even if the user asks for an approach or next step.
+- After meaningful work, use `update-status`; skip trivial/no-state-change tasks and avoid transcript-style noise.
+- `docs/TASKS.md` is a local AI task queue: prefer `Ready for AI` when asked to pick queued work, and clean duplicates/prune `Done Recently` safely when reading/updating it.
+
+
+## Small-Task Maintainer (internal)
+
+- UKit may route low-risk internal decisions to the `ukit-small-task-maintainer` subagent using `UKIT_SMALL_TASK_MODEL` (default `unic-lite`).
+- Use it for safe/reversible UKit chores: dọn `docs/TASKS.md`, queued-task classification, fast-vs-slow/safe-vs-risky lane decisions, skill-routing/step-budget hints, agent context-budget decisions, compact/summary decisions, docs/status summarization, auto-triage, queue maintenance, and small workspace cleanup.
+- Run it as a sidecar/parallel lane only; do not block, replace, or slow the user task. Do not block the main AI flow: if the small-task lane sees security, risky/shared code, release/publish, data-loss, architecture, deep-reasoning risk, weak context, or quality risk, it hands back to the main model instead of asking the end user to decide.
+- This is optional internal orchestration config from `.claude/ukit/.env` / `.ukit/storage/config.json`; never turn it into an end-user workflow. End users still only need `ukit install` and natural-language product work. Always preserve the CoDev priority: quality > safety > speed > token discipline. Keep Claude PreCompact/reinject and OpenCode native auto/prune compaction enabled. For Codex Desktop long sessions, `UKIT_CODEX_COMPACT_TARGET` defaults to 150 compact handoff lines (120-150 preferred, hard max 170), decided internally by the small-task maintainer.
+
 ## Selective Subagent Policy (internal only)
 
 - Keep direct execution as the default for trivial/simple work.

package/templates/docs/INSTALL.md

@@ -47,6 +47,8 @@ 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/WORKLOG.md`
 
 ### 4) Open your AI tool
@@ -96,6 +98,8 @@ 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/WORKLOG.md`
 
 ---

package/templates/docs/PROJECT.md

@@ -44,7 +44,9 @@
 
 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/CODE_MAP.md` if it exists — structural navigation index
-4. Use the installed source-code index / routed helpers to localize the smallest relevant file + test set first
-5. Scan recent `docs/WORKLOG.md` entries if continuing prior work
-6. Verify understanding against source before acting — **docs orient, source is truth; keep the index-first workflow intact**
+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**