@ngockhoale/ukit 1.1.8 → 1.2.1

package/templates/.claude/agents/ukit-small-task-maintainer.md

@@ -0,0 +1,72 @@
+---
+name: ukit-small-task-maintainer
+description: "Internal UKit maintenance subagent for low-risk, reversible UKit decisions. Use proactively when UKit needs to decide or perform safe cleanup such as pruning docs/TASKS.md, classifying queued work, choosing whether compact/summarization is appropriate, summarizing local docs/status, or maintaining small UKit runtime queues. Do not use for product implementation, security, release/publish, data-loss, architecture, or risky/shared code changes."
+model: inherit
+color: cyan
+tools: ["Read", "Grep", "Glob", "Edit", "Write"]
+---
+
+You are UKit's internal small-task maintainer. You run as a sidecar/parallel/non-blocking lane for safe, reversible UKit orchestration chores so the end user can stay focused on product work and only remember `ukit install`. You must follow `docs/UKIT_CODEV_PRINCIPLES.md`: hide complexity, preserve output quality, and never trade correctness for speed or token savings.
+
+## Model Policy
+
+- Use the model selected by `UKIT_SMALL_TASK_MODEL` when the host supports model selection for this subagent.
+- Default intended model: `unic-lite`.
+- If the host cannot bind a model from env directly, still follow this role and report that the configured model is a hint.
+- This lane must run separately from the user's main task model. It must never replace, pause, or slow down the main task.
+
+## Use For
+
+- Cleaning and deduplicating `docs/TASKS.md`.
+- Pruning stale local AI queue/status noise.
+- Classifying queued items by readiness/risk.
+- Deciding whether compacting or summarizing context/docs is appropriate.
+- Summarizing `docs/STATUS.md`, `docs/TASKS.md`, `docs/WORKLOG.md`, or memory snippets into compact handoff notes.
+- Deciding fast vs slow lane, safe vs risky lane, whether a skill should be activated, and whether the current prompt has enough steps planned.
+- Choosing compact-now vs compact-later and summarize-vs-keep-detail for UKit context hygiene.
+- Keeping agent context compact without removing existing lanes: Claude PreCompact/reinject stays active, OpenCode native auto/prune compaction stays active, and Codex Desktop soft handoffs use `UKIT_CODEX_COMPACT_TARGET` (default 150 lines; preferred 120-150; hard max 170) while preserving critical state.
+- Small, reversible UKit runtime maintenance decisions.
+
+## Never Use For
+
+- Security/auth/permission/secrets work.
+- Release, tag, publish, package ownership, or irreversible registry decisions.
+- Data deletion beyond clearly safe local queue/doc cleanup.
+- Architecture decisions, roadmap trade-offs, or deep product reasoning.
+- Product code changes or risky/shared implementation edits.
+- Any action where the consequence is not easy to inspect and undo.
+
+## Workflow
+
+1. Read the smallest relevant local state file first.
+2. Identify whether the requested action is safe and reversible.
+3. If risky, hand back to the main model with a concise reason; do not ask the end user and do not block the main AI flow.
+4. If the main task can continue without this sidecar result, return a compact recommendation and let the main task proceed immediately.
+5. If safe, make the smallest cleanup/summary/classification/routing decision.
+6. Follow the CoDev priority order: output quality first, then safety, then speed, then token discipline. Spend tokens/steps when they protect correctness.
+7. Use small step budgets: trivial = 1 step, simple = up to 2 steps, non-trivial = up to 4 planned steps before the main model reassesses.
+8. For long sessions, preserve existing Claude/OpenCode auto-compact behavior; for Codex Desktop, target a compact handoff of about 120-150 lines, never above 170 lines for this lane, not a full transcript replay.
+9. Preserve user-owned content; do not delete unclear tasks.
+10. Report exactly what changed or what decision was made.
+
+## Output Format
+
+```
+STATUS: DONE | SKIPPED | HAND_BACK
+MODEL_HINT: UKIT_SMALL_TASK_MODEL=<value-or-default>
+SUMMARY: [one sentence]
+CHANGES:
+  - [file/area]: [what changed]
+HAND_BACK_REASON: [only if HAND_BACK]
+NEXT: [small follow-up or "none"]
+```
+
+## Guardrails
+
+- Keep UKit invisible: never ask end users to remember this agent, model name, or config path.
+- Never block AI decision-making; escalate to the main model instead of waiting for user input when risk exceeds this lane.
+- Never block, replace, or slow the user's main task; this lane is a sidecar hint/maintenance worker only.
+- Prefer no-op over destructive cleanup when uncertain.
+- Do not invent product requirements.
+- Never choose cheap/fast if it risks wrong context, weak verification, over-compaction, or lower answer quality.
+- Do not widen reads beyond local UKit state unless the main model explicitly scoped the handoff.

package/templates/.claude/skills/docs-quality/SKILL.md

@@ -61,7 +61,7 @@ Docs should **not** become:
 
 - update README / docs after code changes
 - fix source-vs-doc drift
-- improve `docs/PROJECT.md`, `docs/MEMORY.md`, `docs/STATUS.md`, `docs/WORKLOG.md`, `docs/CODE_MAP.md`
+- improve `docs/PROJECT.md`, `docs/MEMORY.md`, `docs/STATUS.md`, `docs/TASKS.md`, `docs/WORKLOG.md`, `docs/CODE_MAP.md`
 - prepare durable handoff notes
 - tighten or remove stale setup instructions
 - document newly discovered module boundaries, dangerous areas, or bug patterns
@@ -105,6 +105,20 @@ Use for compact current state:
 
 Do **not** treat it as source truth or duplicate full session history here.
 
+#### `docs/TASKS.md`
+Use for:
+- local AI task queue items the human or an AI may hand to another AI/agent later
+- `Inbox` ideas that still need acceptance/verification details
+- `Ready for AI` tasks that are specific enough to implement without scanning the whole repo
+
+Default cleanup when reading/updating it:
+- remove exact duplicates
+- prune `Done Recently` to 10 compact lines
+- move stale/vague/blocked tasks to `Deferred / Needs Human Review`
+- only delete unfinished human-authored tasks when explicitly asked and clearly obsolete/duplicated
+
+Do **not** treat it as a roadmap, project history, or source truth. It is local working state.
+
 #### `docs/WORKLOG.md`
 Use for session-level execution history:
 - what changed

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

@@ -1,6 +1,6 @@
 ---
 name: next-step
-description: Use when the user asks what to do next, asks for project status, says continue/làm tiếp without a concrete target, or needs a lightweight session-start orientation from docs/STATUS.md. Do not use as the primary skill for concrete debug, implementation, review, or docs tasks.
+description: Use when the user asks what to do next, asks for project status, says continue/làm tiếp without a concrete target, or needs a lightweight session-start orientation from docs/STATUS.md and optional docs/TASKS.md. Do not use as the primary skill for concrete debug, implementation, review, or docs tasks.
 ---
 
 # Next Step
@@ -21,8 +21,10 @@ It is **not** a replacement for concrete workflows. If the user names a bug, fea
 - End users should not need to know this skill name.
 - Do not ask users to run a `next-step` command. The human workflow remains `ukit install` + natural language.
 - `docs/STATUS.md` is orientation, not truth. Source code, tests, and the UKit index win.
+- `docs/TASKS.md` is a local AI task queue, not a roadmap and not source truth.
 - Concrete task beats open-ended wording. Example: "I'm fixing login bug but unsure next step" is a debug approach question, not a global roadmap request.
 - Do not scan the whole repo unless `docs/STATUS.md` is missing/stale and the user still wants project-level direction.
+- When reading `docs/TASKS.md`, perform only safe cleanup by default: remove exact duplicates, prune `Done Recently` to 10 lines, and move stale/vague items to `Deferred / Needs Human Review`; do not delete unfinished human-authored tasks unless explicitly asked and clearly obsolete/duplicated.
 
 ## Freshness Check
 
@@ -43,9 +45,10 @@ If stale or missing, downgrade confidence and verify with the smallest current t
 
 Read only what is needed:
 1. `docs/STATUS.md` (or existing root `STATUS.md` fallback)
-2. `docs/CODE_MAP.md` only when navigation is needed
-3. `docs/MEMORY.md` only when constraints/decisions affect the suggestion
-4. routed index/tree summary only if status is stale, missing, or contradicted
+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
 
 ## Output Shape
 
@@ -60,6 +63,10 @@ Suggested next steps:
 1. Candidate — why now — likely files — verification — risk
 2. Candidate — why now — likely files — verification — risk
 
+Queued tasks (if `docs/TASKS.md` was used):
+- Ready: task title — acceptance — verification
+- Deferred/blocked: compact note only if relevant
+
 Recommended: ...
 Why: ...
 First check: ...
@@ -68,7 +75,8 @@ First check: ...
 ## Intent Handling
 
 - `open-ended-status`: read status and suggest 1-3 candidates.
-- `continue-existing-work`: prefer Active Work / Current Debug Threads, then Next Candidates.
+- `queued-task-selection`: read `docs/TASKS.md`, prefer `Ready for AI`, and suggest the best next task with acceptance/verification.
+- `continue-existing-work`: prefer Active Work / Current Debug Threads, then `Ready for AI`, then Next Candidates.
 - `scoped-advice`: do not produce a global roadmap; hand off to the concrete skill and suggest the immediate approach only.
 - `debug-specific`, `implement-specific`, `review-specific`: do not use this skill as primary.
 

package/templates/.claude/skills/update-status/SKILL.md

@@ -22,7 +22,8 @@ Do **not** run for trivial typo-only edits, pure Q&A, or exploration with no dur
 - End users should not need to know this skill name.
 - Do not ask users to run a `update-status` command. The human workflow remains `ukit install` + natural language.
 - Keep `docs/STATUS.md` compact. It is not `docs/WORKLOG.md` and not a raw session transcript.
-- Source code and tests are truth. If status conflicts with source, update status to match source or mark uncertainty.
+- Keep `docs/TASKS.md` compact when the completed/active work is related to queued tasks; this queue is local working state and should stay gitignored.
+- Source code and tests are truth. If status/tasks conflict with source, update the docs to match source or mark uncertainty.
 - Do not invent verification. Record only commands actually run and their outcome.
 - Preserve user edits and rewrite the smallest relevant section.
 
@@ -35,6 +36,7 @@ Before editing, ask internally:
 3. Was a root cause, decision, blocker, or next action confirmed?
 4. What verification ran?
 5. Will future sessions be faster if this is recorded?
+6. Did any `docs/TASKS.md` queued task become done, duplicate, stale, or blocked?
 
 If all answers are no, skip the update and mention that no status change was needed.
 
@@ -85,4 +87,16 @@ Avoid:
 
 ## Future Context Note
 
-Do not create task-scoped `CONTEXT.md` as part of v1.1.8 unless the project already has that convention. If detailed bug/feature context is needed, note it as a v1.2 candidate or link to an existing `docs/context/<slug>.md` file.
+Do not create task-scoped `CONTEXT.md` by default unless the project already has that convention. If detailed bug/feature context is needed, note it as a v1.2 candidate or link to an existing `docs/context/<slug>.md` file.
+
+## TASKS.md Cleanup
+
+When the session touched queued work or the user asks to clean/dọn tasks:
+
+- Read `docs/TASKS.md` if it exists; do not create noisy task entries just to summarize the session.
+- Auto-remove exact duplicate tasks.
+- Auto-prune `Done Recently` to max 10 compact lines.
+- Remove a task from active sections only after all are true: it is done, verification is recorded, and completion is summarized in `docs/WORKLOG.md` or `Done Recently`.
+- Move stale, vague, or blocked tasks to `Deferred / Needs Human Review` instead of deleting uncertain human intent.
+- Do not delete non-completed human-authored tasks unless the user explicitly asked for cleanup and the task is clearly obsolete or duplicated.
+- Report the cleanup in one compact line: removed duplicates, moved deferred, pruned done, or no safe cleanup.

package/templates/.claude/ukit/.env.example

@@ -0,0 +1,17 @@
+# UKit optional local runtime overrides.
+# Copy to .claude/ukit/.env only if you need machine-local overrides.
+# This is internal orchestration config; normal teammates still only need `ukit install`.
+
+# Lightweight model for the internal UKit small-task maintainer subagent.
+# Used for safe UKit decisions such as task cleanup, compact decisions,
+# doc summarization, classification, auto-triage, and queue maintenance.
+# It follows UKit CoDev principles: quality > speed > token savings.
+# Risky/shared/security/release/data-loss/architecture work must keep the main model.
+UKIT_SMALL_TASK_MODEL=unic-lite
+
+# Codex Desktop soft auto-compact handoff budget.
+# Target is compact handoff length (lines), not full app context tokens.
+# 120-150 is preferred; 170 lines is the hard max for this lane.
+UKIT_CODEX_AUTO_COMPACT=true
+UKIT_CODEX_CONTEXT_BUDGET=60000
+UKIT_CODEX_COMPACT_TARGET=150

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

@@ -223,8 +223,8 @@ export const ROUTE_CATALOG = [
     path: '.claude/skills/docs-quality/SKILL.md',
     order: 12,
     signals: [
-      { type: 'prompt', regex: /\b(docs|documentation|readme|changelog|handoff|worklog|memory|code map|status\.md)\b/i, score: 4 },
-      { type: 'file', regex: /\bdocs\/|readme\.md$|project\.md$|memory\.md$|status\.md$|worklog\.md$|code_map\.md$/i, score: 4 },
+      { type: 'prompt', regex: /\b(docs|documentation|readme|changelog|handoff|worklog|memory|code map|status\.md|tasks\.md|task queue|clean tasks|cleanup tasks|dọn tasks|dọn task)\b/i, score: 4 },
+      { type: 'file', regex: /\bdocs\/|readme\.md$|project\.md$|memory\.md$|status\.md$|tasks\.md$|worklog\.md$|code_map\.md$/i, score: 4 },
     ],
   },
   {
@@ -233,8 +233,8 @@ export const ROUTE_CATALOG = [
     order: 12.1,
     contextMode: 'standalone',
     signals: [
-      { type: 'prompt', regex: /\b(what(?:'s| is)? next|next steps?|project status|current status|where are we|continue(?: from)?(?: last session)?|roadmap|status\.md)\b/i, score: 7 },
-      { type: 'prompt', regex: /\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)\b/i, score: 7 },
+      { type: 'prompt', regex: /\b(what(?:'s| is)? next|next steps?|project status|current status|where are we|continue(?: from)?(?: last session)?|roadmap|status\.md|task queue|tasks\.md|next queued task|pick next task|work from tasks)\b/i, score: 7 },
+      { type: 'prompt', regex: /\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/i, score: 7 },
     ],
   },
   {

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

@@ -745,10 +745,11 @@ function getSignalTexts(signalType, routeSignals = {}) {
 function deriveIntentMode({ promptText = '', commandText = '', targetFile = null } = {}) {
   const lower = buildNormalizedRouteSignalText(promptText, commandText);
   const raw = `${promptText ?? ''}\n${commandText ?? ''}`.toLowerCase();
-  const docsSpecific = hasDocsSpecificTaskSignal(lower, raw, targetFile);
+  const taskQueueNext = hasTaskQueueNextSignal(lower, raw);
+  const docsSpecific = hasDocsSpecificTaskSignal(lower, raw, targetFile, { taskQueueNext });
   const statusUpdate = hasStatusUpdateSignal(lower, raw);
-  const openEndedStatus = hasOpenEndedStatusSignal(lower, raw);
-  const concreteTask = hasConcreteTaskSignal(lower, raw, targetFile);
+  const openEndedStatus = hasOpenEndedStatusSignal(lower, raw) || taskQueueNext;
+  const concreteTask = hasConcreteTaskSignal(lower, raw, targetFile, { taskQueueNext });
 
   if (docsSpecific) {
     return 'docs-specific';
@@ -790,13 +791,18 @@ function hasStatusUpdateSignal(lower, 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)\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)\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)\b/.test(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 hasConcreteTaskSignal(lower, raw, targetFile) {
-  if (targetFile && !isStatusFileTarget(targetFile)) {
+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;
   }
 
@@ -804,8 +810,13 @@ function hasConcreteTaskSignal(lower, raw, targetFile) {
     || /\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) {
+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;
   }
 
@@ -847,6 +858,10 @@ 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);
@@ -1100,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;
   }
@@ -1189,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(' | ');
 

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.8 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,6 +23,7 @@ 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
 
@@ -30,6 +31,7 @@ Auto-generated by UKit for OpenAI Codex.
 - **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.
 
@@ -53,7 +55,7 @@ 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 prompts, prefer `.codex/skills/next-step/SKILL.md` and show a status freshness cue.
+- 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>]`.
@@ -73,6 +75,7 @@ For clearly non-code specialist lanes, avoid dragging the source-code index into
 
 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": {
@@ -137,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": {
@@ -158,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,8 +30,8 @@
 - 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`
-- open-ended next step / project status / continue with no concrete target → `.claude/skills/next-step/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`
@@ -43,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.8 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.
@@ -62,6 +62,7 @@
 - **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.
 
@@ -71,8 +72,17 @@
 - 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,8 +28,8 @@
 - 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`
-- open-ended next step / project status / continue with no concrete target → `.claude/skills/next-step/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`
@@ -42,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.8 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,6 +59,7 @@
 - **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.
 
@@ -69,6 +70,15 @@
 - 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)
 

package/templates/docs/INSTALL.md

@@ -48,6 +48,7 @@ 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
@@ -98,6 +99,7 @@ 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`
 
 ---