@ngockhoale/ukit 3.5.8 → 3.5.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -2,6 +2,19 @@
2
2
 
3
3
  All notable changes to UKit are documented here.
4
4
 
5
+ ## 3.5.9 - 2026-11-18
6
+
7
+ Playbooks now reach the agent. A telemetry review of 164 Claude Code sessions (1,426 unique prompts) found the playbook feature had no effect: only 9% of prompts got a playbook, 79% were dropped as ambiguous (for example bug-fix + release), and no session ever opened a playbook file, because the prompt hook never printed one and route-task pointed at a relative path that does not exist in projects. No new command was added; the change is in what the existing hooks and instructions deliver. No host was run live; the checks are unit, parity and hook-process tests.
8
+
9
+ - **The playbook text is injected with the route.** On a prompt turn the Claude Code / omp router prints the matched playbook body (frontmatter stripped, capped at 2,400 characters with a pointer to the full file) inside `<ukit-playbook id="…">`, with the instruction to copy its numbered steps as the first todos, keep skipped steps as `skip: <reason>` / `n/a: <reason>`, and end with its Reply contract. `route-task.mjs` (Codex and print consumers) prints the same block and drops the duplicate workflow lines when it does.
10
+ - **Ambiguous prompts get candidates instead of nothing.** When two or more playbooks match, the router lists up to four candidates and the absolute `~/.ukit/playbooks/<id>.md` path to read after picking by primary intent.
11
+ - **The intent → playbook map is part of the always-loaded instructions.** CLAUDE.md and AGENTS.md gain a "Playbooks (automatic — no command)" section; omp's RULES.md gains the same rule in one line. Plain continuations and trivial edits still need no playbook; `/ukit:handoff-*` commands keep their own phases.
12
+ - **Handoff executors use playbooks too.** `/ukit:handoff-implement` and `/ukit:handoff-fullstack` executor briefs tell defect, performance and migration tasks to copy the matching playbook steps; the brief still wins on commits, TDD and the report shape.
13
+ - **Route audit rows record why no playbook was chosen** (`playbookReason`, `playbookCandidates`) so the hit rate can be re-measured.
14
+ - **Questions no longer get a build playbook.** A Vietnamese question whose clause ends in "vậy." or "không," (for example "học hỏi gì thêm từ pstack vậy. apply có tốt hơn không, …") routed to small-feature and then the Stop gate asked for edits; it now routes investigation. "thêm" counts as the order "add" only when it leads its clause ("thêm nút Save…", "giúp tôi thêm…"); as "more/additional" ("tích hợp thêm ý tưởng", "thêm cũng có nghĩa là more") it no longer mints a build playbook.
15
+
16
+ Known limits: ambiguous prompts are not ranked yet; `~/.ukit/playbooks` seeds are never refreshed by `ukit update`, so older personal copies keep their older text.
17
+
5
18
  ## 3.5.8 - 2026-11-16
6
19
 
7
20
  Bug-fix release: one defect seen right after 3.5.7 shipped, fixed at its cause. No host (Claude Code, Codex, omp) was run live and nothing was run on Windows; the checks are unit tests and real hook processes (prompt router, evidence recorder, Stop gate) in a temporary project.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ngockhoale/ukit",
3
- "version": "3.5.8",
3
+ "version": "3.5.9",
4
4
  "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex and omp (Oh My Pi).",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -49,7 +49,7 @@ export const PLAYBOOK_ID_ALIASES = Object.freeze({
49
49
  // --- Shared signal vocabulary ------------------------------------------------
50
50
  // Compiled once; every row's discriminator reads the same normalized signals so
51
51
  // confusable pairs split on the discriminator column, never trigger text.
52
- const CREATE_VERB_RE = /\b(create|add|write|build|implement|scaffold|tạo|thêm)\b/i;
52
+ const CREATE_VERB_RE = /\b(create|add|write|build|implement|scaffold|tạo|thêm)\b|(?<![\p{L}\p{N}_])(?:viết|viet)(?![\p{L}\p{N}_])/iu;
53
53
  // Vietnamese words never match `\b` (JS word chars are ASCII-only — 'sửa' ends
54
54
  // in a non-word char, 'đổi' starts with one), so the diacritic alternates use
55
55
  // explicit lookarounds instead. Same word list as the original literal.
@@ -397,6 +397,20 @@ function matchFirst(text, regexes) {
397
397
  return -1;
398
398
  }
399
399
 
400
+ // "thêm" is both the order "add" and the adverb "more/additional". The order
401
+ // leads its clause ("thêm nút Save", "giúp tôi thêm …"); the adverb trails a
402
+ // verb/noun ("học hỏi gì thêm", "tích hợp thêm ý tưởng") or is the word under
403
+ // discussion ("thêm cũng có nghĩa là more"). Only the order counts as create.
404
+ const THEM_ORDER_LEAD = new Set(['hãy', 'hay', 'giúp', 'giùm', 'cho', 'tôi', 'mình', 'em', 'anh', 'bạn', 'và', 'rồi', 'thì', 'cần', 'lại', 'luôn', 'lòng', 'please']);
405
+ function stripAdverbialThem(text) {
406
+ return text
407
+ .replace(/(^|[\s.,;:!?])thêm(?=\s+(?:cũng|có nghĩa|nghĩa là|là|nữa)(?![\p{L}\p{N}_]))/giu, '$1 ')
408
+ .replace(/(?<!\S)(\S{1,40})(\s+)thêm(?![\p{L}\p{N}_])/giu, (match, prev, space) => {
409
+ if (/[.,;:!?]$/.test(prev) || THEM_ORDER_LEAD.has(prev.toLowerCase())) return match;
410
+ return `${prev}${space} `;
411
+ });
412
+ }
413
+
400
414
  async function buildRouteSignals({
401
415
  signalText,
402
416
  rawPromptText = '',
@@ -411,10 +425,14 @@ async function buildRouteSignals({
411
425
  // because no consult pattern consumes its clause.
412
426
  const verbScanText = signalText
413
427
  .replace(/(?:^|[.!;\n]\s*)(?:should|shall|do|does|did|can|could|would|will|is|are|am)\s+(?:i|we|you)\s+[^\n?]*/g, ' ')
414
- .replace(/[^\n.,;?]{0,80}\b(?:chưa|chua|được không|duoc khong|đúng không|dung khong|không nhỉ|khong nhi|không|khong|rồi|roi|nhỉ|nhi|ạ|a)\s*[?.!]?\s*$/g, ' ')
415
- .replace(/\b(?:có|co)\s+(?:nên|nen|cần|can|phải|phai)\s+[^\n?]*/g, ' ');
428
+ .replace(/[^\n.,;?]{0,80}\b(?:chưa|chua|được không|duoc khong|đúng không|dung khong|không nhỉ|khong nhi|không|khong|rồi|roi|nhỉ|nhi|ạ|a)\s{0,16}[?.!]?\s{0,16}$/g, ' ')
429
+ .replace(/\b(?:có|co)\s+(?:nên|nen|cần|can|phải|phai)\s+[^\n?]*/g, ' ')
430
+ // A mid-prompt question clause ("học hỏi gì thêm … vậy.", "apply có tốt hơn
431
+ // không, …") is an ask too — only true question particles close it here
432
+ // ('rồi' stays out: "fix X rồi, chạy test" means "then").
433
+ .replace(/[^\n.,;?]{0,80}(?:\b(?:không|khong|chưa|chua|được không|duoc khong|đúng không|dung khong|nhỉ)|(?<![A-Za-z0-9_])vậy)\s*[?.!,;]/g, ' ');
416
434
  const changeIdx = verbScanText.search(CHANGE_VERB_RE);
417
- const createIdx = verbScanText.search(CREATE_VERB_RE);
435
+ const createIdx = stripAdverbialThem(verbScanText).search(CREATE_VERB_RE);
418
436
  const explainIdx = signalText.search(EXPLAIN_ASK_RE);
419
437
  const defectIdx = signalText.search(DEFECT_TRIGGER_RE);
420
438
  const checkIdx = signalText.search(CHECK_VERB_RE);
@@ -422,7 +440,7 @@ async function buildRouteSignals({
422
440
  const consultLead = /(?:^|[.!;\n]\s*)(?:should|shall|do|does|did|can|could|would|will|is|are|am)\s+(?:i|we|you)\s+/
423
441
  .test(signalText)
424
442
  || /\b(?:co|có)\s+(?:nên|nen|cần|can|phải|phai)\s+/.test(signalText)
425
- || /\b(?:chưa|chua|được không|duoc khong|đúng không|dung khong|không nhỉ|khong nhi|nhỉ|nhi|rồi|roi)\s*[?.!]?\s*$/.test(signalText);
443
+ || /\b(?:chưa|chua|được không|duoc khong|đúng không|dung khong|không nhỉ|khong nhi|nhỉ|nhi|rồi|roi)\s{0,16}[?.!]?\s{0,16}$/.test(signalText);
426
444
  const firstVerbIdx = [changeIdx, createIdx].filter((i) => i !== -1).sort((a, b) => a - b)[0] ?? -1;
427
445
  const explanationAsk = explainIdx !== -1 && (firstVerbIdx === -1 || explainIdx < firstVerbIdx);
428
446
  const changeRequested = !consultLead && firstVerbIdx !== -1 && (explainIdx === -1 || firstVerbIdx < explainIdx);
@@ -440,7 +458,7 @@ async function buildRouteSignals({
440
458
  || /\b(how|why|what|when|which|where|who|is|are|does|do|did|can|could|would|should|will)\b/.test(signalText)
441
459
  || /(?:có|co)\s+(?:phải|phai)\s+/.test(signalText)
442
460
  || /(?:chưa|chua|được không|duoc khong|đúng không|dung khong|không nhỉ|khong nhi|thế nào|the nao|như thế nào|nhu the nao|tại sao|tai sao|là gì|la gi|bao giờ|bao gio|khi nào|khi nao|ở đâu|o dau|không biết|khong biet)/.test(signalText)
443
- || /(?:chưa|chua|đúng không|dung khong|không|khong)\s*[?.!]?\s*$/.test(signalText);
461
+ || /(?:chưa|chua|đúng không|dung khong|không|khong)\s{0,16}[?.!]?\s{0,16}$/.test(signalText);
444
462
  const questionAsk = questionShaped && !changeRequested;
445
463
  const referenceTarget = REFERENCE_TARGET_RE.test(signalText);
446
464
  const cloneIntent = CLONE_INTENT_RE.test(signalText);
@@ -623,6 +641,34 @@ export async function loadRegistry({ projectRoot = null, homeDir = null, builtin
623
641
  return records;
624
642
  }
625
643
 
644
+ // Delivery: the playbook body (frontmatter stripped, CRLF normalized) for
645
+ // injection into the routed turn. Bounded so a hand-edited user playbook can
646
+ // never flood the context; null on any read/parse failure (fail-open).
647
+ export const PLAYBOOK_BODY_MAX_CHARS = 2400;
648
+ export async function readPlaybookBody(filePath, { maxChars = PLAYBOOK_BODY_MAX_CHARS } = {}) {
649
+ if (typeof filePath !== 'string' || filePath === '') return null;
650
+ let raw;
651
+ try {
652
+ raw = await fs.readFile(filePath, 'utf8');
653
+ } catch {
654
+ return null;
655
+ }
656
+ const text = String(raw).replace(/\r\n/g, '\n');
657
+ let body = text;
658
+ if (text.startsWith('---\n')) {
659
+ const fenceIndex = text.indexOf('\n---', 3);
660
+ if (fenceIndex === -1) return null;
661
+ body = text.slice(fenceIndex + 4).replace(/^\n/, '');
662
+ }
663
+ // A body cannot close the <ukit-playbook> wrapper early.
664
+ body = body.trim().replace(/<\/ukit-playbook>/gi, '&lt;/ukit-playbook>');
665
+ if (body === '') return null;
666
+ if (body.length <= maxChars) return body;
667
+ // Cut on a code-point boundary (never split a surrogate pair).
668
+ const cut = Array.from(body.slice(0, maxChars + 1)).slice(0, -1).join('').slice(0, maxChars);
669
+ return `${cut.trimEnd()}\n[…truncated — full text: ${filePath}]`;
670
+ }
671
+
626
672
  function findRegistryRecord(records, playbookId) {
627
673
  const direct = records.find((r) => r.frontmatterValid && r.playbookId === playbookId);
628
674
  if (direct) return direct;
@@ -814,5 +860,11 @@ export async function resolvePlaybookRoute({
814
860
  fastPath: resolution.fastPath ?? null,
815
861
  reason: resolution.reason ?? null,
816
862
  playbookLoad: resolution.reason === 'playbook-missing' ? 'missing' : null,
863
+ // Delivery fields: the resolved file lets the hook inject the playbook body
864
+ // (agents never Read a relative `playbooks/<id>.md` that does not exist in
865
+ // the project); ambiguous candidates let the agent pick instead of losing
866
+ // the playbook entirely (pstack posture — the model chooses on ties).
867
+ file: resolution.file ?? null,
868
+ candidates: Array.isArray(resolution.candidates) ? resolution.candidates : null,
817
869
  };
818
870
  }
@@ -443,6 +443,10 @@ export async function deriveTaskRoute({
443
443
  routeSummary.workGroup = playbookResolution.workGroup;
444
444
  routeSummary.playbookReason = playbookResolution.reason;
445
445
  routeSummary.playbookLoad = playbookResolution.playbookLoad;
446
+ // Playbook delivery parity with route-task.mjs: file/body/candidates ride
447
+ // the route so the printed state carries the playbook text itself.
448
+ routeSummary.playbookFile = playbookResolution.file ?? null;
449
+ routeSummary.playbookCandidates = Array.isArray(playbookResolution.candidates) ? playbookResolution.candidates : null;
446
450
  // BL-010 (ARCH Task Contract): `path` = direct|handoff; `fastPathKind` is
447
451
  // the ARCH `none|small-feature|bug-fix` enum — named Kind because
448
452
  // routeSummary.fastPath already carries the FR-004 eligibility object.
@@ -692,6 +692,10 @@ no compound.)
692
692
  ```
693
693
  Read docs/AI_HANDOFF/tasks/TASK-xxx.md
694
694
 
695
+ Playbook — if the task is a defect, read bug-fix.md from ~/.ukit/playbooks/ (perf:
696
+ performance.md, migration: migration.md) and copy its numbered steps into your todos (skip:/n/a: <reason>,
697
+ never drop one). This brief wins on conflict: no commits, TDD and the report shape below.
698
+
695
699
  TDD — mandatory:
696
700
  1. Write tests from §Test Cases
697
701
  run <test command> from the worktree root (your cwd IS .worktrees/task-xxx — no cd)
@@ -150,6 +150,10 @@ Read the SPEC.md sections named in the task's `Spec references` — the spec is
150
150
  the task file is the slice. If they disagree, implement the spec and note it in the task's
151
151
  ## Discussion.
152
152
 
153
+ Playbook — if the task is a defect, read bug-fix.md from ~/.ukit/playbooks/ (perf:
154
+ performance.md, migration: migration.md) and copy its numbered steps into your todos (skip:/n/a: <reason>,
155
+ never drop one). This brief wins on conflict: no commits, TDD and the report shape below.
156
+
153
157
  TDD — mandatory:
154
158
  1. Write tests from §Test Cases
155
159
  run <test command> from the worktree root (your cwd IS .worktrees/task-xxx — no cd)
@@ -1444,6 +1444,34 @@ function applyTaskSemantics(contract, semantic) {
1444
1444
  }
1445
1445
  return tierLaneModule;
1446
1446
  }
1447
+ // Playbook delivery (pstack port): the selected playbook body rides the
1448
+ // prompt turn verbatim — telemetry showed agents never Read a playbook file
1449
+ // from a "read playbooks/<id>.md" cue (relative path absent in projects).
1450
+ // Ambiguous routes list the candidates so the agent picks one instead of the
1451
+ // playbook silently vanishing. Prompt turns only; fail-open.
1452
+ async function writePlaybookLines(summary) {
1453
+ try {
1454
+ if (summary?.playbookId && summary.playbookFile) {
1455
+ const registry = await loadPlaybookRegistry();
1456
+ const body = typeof registry?.readPlaybookBody === 'function'
1457
+ ? await registry.readPlaybookBody(summary.playbookFile)
1458
+ : null;
1459
+ if (body) {
1460
+ process.stdout.write(`[ukit-skill-router] Playbook: ${summary.playbookId} — copy its numbered steps verbatim as your first todos; a step you skip stays with "skip: <reason>", a step that does not apply stays with "n/a: <reason>"; end with its Reply contract.\n<ukit-playbook id="${summary.playbookId}">\n${body}\n</ukit-playbook>\n`);
1461
+ return;
1462
+ }
1463
+ }
1464
+ const candidates = Array.isArray(summary?.playbookCandidates)
1465
+ ? summary.playbookCandidates.filter((id) => typeof id === 'string' && id && id !== 'handoff-cycle').slice(0, 4)
1466
+ : [];
1467
+ if (!summary?.playbookId && summary?.playbookReason === 'ambiguous-route' && candidates.length > 1) {
1468
+ const dir = path.join(os.homedir(), '.ukit', 'playbooks');
1469
+ process.stdout.write(`[ukit-skill-router] Playbook candidates: ${candidates.join(', ')} — pick the one matching the user's primary intent, Read ${dir}/<id>.md and follow its steps (or note "playbook: none — <reason>").\n`);
1470
+ }
1471
+ } catch {
1472
+ // delivery is advisory — never break routing
1473
+ }
1474
+ }
1447
1475
  function writeTierLaneLines(summary, taskId) {
1448
1476
  if (summary?.playbookId === 'bug-fix') {
1449
1477
  process.stdout.write('[ukit-skill-router] Bug-fix evidence (include in any worker prompt): before editing, run the failing repro once and keep its failing result; after the fix re-run that same command and keep the passing result; state the root cause with UKIT_EVIDENCE="class=root-cause;claim=<mechanism>" on a Bash call. A worker\'s own runs count for this task only through its host-linked session.\n');
@@ -1584,7 +1612,7 @@ function applyTaskSemantics(contract, semantic) {
1584
1612
  // bundle the hook spreads into routeSummary — hook and helper emit the
1585
1613
  // identical playbookId/workGroup. Missing registry degrades to
1586
1614
  // playbookId: null (the state still carries the field for parity).
1587
- const playbook = { playbookId: null, workGroup: null, playbookReason: null, playbookLoad: null, path: null, fastPathKind: null };
1615
+ const playbook = { playbookId: null, workGroup: null, playbookReason: null, playbookLoad: null, path: null, fastPathKind: null, playbookFile: null, playbookCandidates: null };
1588
1616
  try {
1589
1617
  const registry = await loadPlaybookRegistry();
1590
1618
  if (registry && typeof registry.resolvePlaybookRoute === 'function') {
@@ -1607,6 +1635,10 @@ function applyTaskSemantics(contract, semantic) {
1607
1635
  // resolver's FR-004 fastPath eligibility object intact (M03).
1608
1636
  playbook.path = resolution.path ?? null;
1609
1637
  playbook.fastPathKind = resolution.fastPath ?? null;
1638
+ // Delivery fields: the resolved file (body injected on the prompt turn)
1639
+ // and ambiguous candidates (agent picks — never silently drop).
1640
+ playbook.playbookFile = resolution.file ?? null;
1641
+ playbook.playbookCandidates = Array.isArray(resolution.candidates) ? resolution.candidates : null;
1610
1642
  }
1611
1643
  } catch {
1612
1644
  playbook.playbookReason = 'registry-error';
@@ -1671,6 +1703,10 @@ function applyTaskSemantics(contract, semantic) {
1671
1703
  if (routeSummary.playbookReason === undefined) {
1672
1704
  routeSummary.playbookReason = fields.playbookReason ?? null;
1673
1705
  }
1706
+ if (!onlyMissing || routeSummary.playbookFile === undefined) {
1707
+ routeSummary.playbookFile = fields.playbookFile ?? null;
1708
+ routeSummary.playbookCandidates = fields.playbookCandidates ?? null;
1709
+ }
1674
1710
  if (routeSummary.playbookLoad === undefined) {
1675
1711
  routeSummary.playbookLoad = fields.playbookLoad ?? null;
1676
1712
  }
@@ -1686,6 +1722,7 @@ function applyTaskSemantics(contract, semantic) {
1686
1722
  if (!routeSummary || !prev?.playbookId) return;
1687
1723
  if (!taskId || previousState.taskInstanceId !== taskId) return;
1688
1724
  if (!routeSummary.playbookId) {
1725
+ // playbookFile is deliberately NOT inherited: a continuation turn must not re-inject the body.
1689
1726
  for (const key of ['playbookId', 'workGroup', 'playbookReason', 'playbookLoad', 'path', 'fastPathKind']) {
1690
1727
  if (prev[key] !== undefined && prev[key] !== null) routeSummary[key] = prev[key];
1691
1728
  }
@@ -4154,6 +4191,8 @@ function applyTaskSemantics(contract, semantic) {
4154
4191
  fastPathKind: routeSummary.fastPathKind ?? null,
4155
4192
  ...(routeSummary.playbookReason ? { playbookReason: routeSummary.playbookReason } : {}),
4156
4193
  ...(routeSummary.playbookLoad ? { playbookLoad: routeSummary.playbookLoad } : {}),
4194
+ ...(routeSummary.playbookFile ? { playbookFile: routeSummary.playbookFile } : {}),
4195
+ ...(Array.isArray(routeSummary.playbookCandidates) && routeSummary.playbookCandidates.length ? { playbookCandidates: routeSummary.playbookCandidates } : {}),
4157
4196
  completionState: routeSummary.completionState || null,
4158
4197
  continuationState: routeSummary.continuationState || null,
4159
4198
  delegateHint: routeSummary.delegateHint || null,
@@ -4258,6 +4297,11 @@ function applyTaskSemantics(contract, semantic) {
4258
4297
  playbookId: routeSummary.playbookId ?? null,
4259
4298
  workGroup: routeSummary.workGroup ?? null,
4260
4299
  playbookLoad: routeSummary.playbookLoad ?? null,
4300
+ // Telemetry: why a playbook did or did not resolve (ambiguous-route,
4301
+ // no-route-match, playbook-missing …) + the tied candidates, so the
4302
+ // selector hit rate is measurable from route-audit alone.
4303
+ playbookReason: routeSummary.playbookReason ?? null,
4304
+ playbookCandidates: Array.isArray(routeSummary.playbookCandidates) ? routeSummary.playbookCandidates.slice(0, 8) : null,
4261
4305
  // BL-010: direct/handoff path + fast-path enum on the audit row so the
4262
4306
  // eval join can assert `direct, fastPath=small-feature` (E-01).
4263
4307
  path: routeSummary.path ?? null,
@@ -6310,6 +6354,9 @@ function applyTaskSemantics(contract, semantic) {
6310
6354
  process.stdout.write(`[ukit-skill-router] Delegate: ${routeSummary.delegateHint}\n`);
6311
6355
  }
6312
6356
  writeTierLaneLines(routeSummary, taskInstanceId);
6357
+ if (!payload.tool_name && promptText && routingContext.taskType !== 'trivial') {
6358
+ await writePlaybookLines(routeSummary);
6359
+ }
6313
6360
  if (
6314
6361
  routeSummary.helperHint
6315
6362
  && !routeSummary.nextActionCommand
@@ -48,7 +48,7 @@ export const PLAYBOOK_ID_ALIASES = Object.freeze({
48
48
  // --- Shared signal vocabulary ------------------------------------------------
49
49
  // Compiled once; every row's discriminator reads the same normalized signals so
50
50
  // confusable pairs split on the discriminator column, never trigger text.
51
- const CREATE_VERB_RE = /\b(create|add|write|build|implement|scaffold|tạo|thêm)\b/i;
51
+ const CREATE_VERB_RE = /\b(create|add|write|build|implement|scaffold|tạo|thêm)\b|(?<![\p{L}\p{N}_])(?:viết|viet)(?![\p{L}\p{N}_])/iu;
52
52
  // Vietnamese words never match `\b` (JS word chars are ASCII-only — 'sửa' ends
53
53
  // in a non-word char, 'đổi' starts with one), so the diacritic alternates use
54
54
  // explicit lookarounds instead. Same word list as the original literal.
@@ -396,6 +396,20 @@ function matchFirst(text, regexes) {
396
396
  return -1;
397
397
  }
398
398
 
399
+ // "thêm" is both the order "add" and the adverb "more/additional". The order
400
+ // leads its clause ("thêm nút Save", "giúp tôi thêm …"); the adverb trails a
401
+ // verb/noun ("học hỏi gì thêm", "tích hợp thêm ý tưởng") or is the word under
402
+ // discussion ("thêm cũng có nghĩa là more"). Only the order counts as create.
403
+ const THEM_ORDER_LEAD = new Set(['hãy', 'hay', 'giúp', 'giùm', 'cho', 'tôi', 'mình', 'em', 'anh', 'bạn', 'và', 'rồi', 'thì', 'cần', 'lại', 'luôn', 'lòng', 'please']);
404
+ function stripAdverbialThem(text) {
405
+ return text
406
+ .replace(/(^|[\s.,;:!?])thêm(?=\s+(?:cũng|có nghĩa|nghĩa là|là|nữa)(?![\p{L}\p{N}_]))/giu, '$1 ')
407
+ .replace(/(?<!\S)(\S{1,40})(\s+)thêm(?![\p{L}\p{N}_])/giu, (match, prev, space) => {
408
+ if (/[.,;:!?]$/.test(prev) || THEM_ORDER_LEAD.has(prev.toLowerCase())) return match;
409
+ return `${prev}${space} `;
410
+ });
411
+ }
412
+
399
413
  async function buildRouteSignals({
400
414
  signalText,
401
415
  rawPromptText = '',
@@ -410,10 +424,14 @@ async function buildRouteSignals({
410
424
  // because no consult pattern consumes its clause.
411
425
  const verbScanText = signalText
412
426
  .replace(/(?:^|[.!;\n]\s*)(?:should|shall|do|does|did|can|could|would|will|is|are|am)\s+(?:i|we|you)\s+[^\n?]*/g, ' ')
413
- .replace(/[^\n.,;?]{0,80}\b(?:chưa|chua|được không|duoc khong|đúng không|dung khong|không nhỉ|khong nhi|không|khong|rồi|roi|nhỉ|nhi|ạ|a)\s*[?.!]?\s*$/g, ' ')
414
- .replace(/\b(?:có|co)\s+(?:nên|nen|cần|can|phải|phai)\s+[^\n?]*/g, ' ');
427
+ .replace(/[^\n.,;?]{0,80}\b(?:chưa|chua|được không|duoc khong|đúng không|dung khong|không nhỉ|khong nhi|không|khong|rồi|roi|nhỉ|nhi|ạ|a)\s{0,16}[?.!]?\s{0,16}$/g, ' ')
428
+ .replace(/\b(?:có|co)\s+(?:nên|nen|cần|can|phải|phai)\s+[^\n?]*/g, ' ')
429
+ // A mid-prompt question clause ("học hỏi gì thêm … vậy.", "apply có tốt hơn
430
+ // không, …") is an ask too — only true question particles close it here
431
+ // ('rồi' stays out: "fix X rồi, chạy test" means "then").
432
+ .replace(/[^\n.,;?]{0,80}(?:\b(?:không|khong|chưa|chua|được không|duoc khong|đúng không|dung khong|nhỉ)|(?<![A-Za-z0-9_])vậy)\s*[?.!,;]/g, ' ');
415
433
  const changeIdx = verbScanText.search(CHANGE_VERB_RE);
416
- const createIdx = verbScanText.search(CREATE_VERB_RE);
434
+ const createIdx = stripAdverbialThem(verbScanText).search(CREATE_VERB_RE);
417
435
  const explainIdx = signalText.search(EXPLAIN_ASK_RE);
418
436
  const defectIdx = signalText.search(DEFECT_TRIGGER_RE);
419
437
  const checkIdx = signalText.search(CHECK_VERB_RE);
@@ -421,7 +439,7 @@ async function buildRouteSignals({
421
439
  const consultLead = /(?:^|[.!;\n]\s*)(?:should|shall|do|does|did|can|could|would|will|is|are|am)\s+(?:i|we|you)\s+/
422
440
  .test(signalText)
423
441
  || /\b(?:co|có)\s+(?:nên|nen|cần|can|phải|phai)\s+/.test(signalText)
424
- || /\b(?:chưa|chua|được không|duoc khong|đúng không|dung khong|không nhỉ|khong nhi|nhỉ|nhi|rồi|roi)\s*[?.!]?\s*$/.test(signalText);
442
+ || /\b(?:chưa|chua|được không|duoc khong|đúng không|dung khong|không nhỉ|khong nhi|nhỉ|nhi|rồi|roi)\s{0,16}[?.!]?\s{0,16}$/.test(signalText);
425
443
  const firstVerbIdx = [changeIdx, createIdx].filter((i) => i !== -1).sort((a, b) => a - b)[0] ?? -1;
426
444
  const explanationAsk = explainIdx !== -1 && (firstVerbIdx === -1 || explainIdx < firstVerbIdx);
427
445
  const changeRequested = !consultLead && firstVerbIdx !== -1 && (explainIdx === -1 || firstVerbIdx < explainIdx);
@@ -439,7 +457,7 @@ async function buildRouteSignals({
439
457
  || /\b(how|why|what|when|which|where|who|is|are|does|do|did|can|could|would|should|will)\b/.test(signalText)
440
458
  || /(?:có|co)\s+(?:phải|phai)\s+/.test(signalText)
441
459
  || /(?:chưa|chua|được không|duoc khong|đúng không|dung khong|không nhỉ|khong nhi|thế nào|the nao|như thế nào|nhu the nao|tại sao|tai sao|là gì|la gi|bao giờ|bao gio|khi nào|khi nao|ở đâu|o dau|không biết|khong biet)/.test(signalText)
442
- || /(?:chưa|chua|đúng không|dung khong|không|khong)\s*[?.!]?\s*$/.test(signalText);
460
+ || /(?:chưa|chua|đúng không|dung khong|không|khong)\s{0,16}[?.!]?\s{0,16}$/.test(signalText);
443
461
  const questionAsk = questionShaped && !changeRequested;
444
462
  const referenceTarget = REFERENCE_TARGET_RE.test(signalText);
445
463
  const cloneIntent = CLONE_INTENT_RE.test(signalText);
@@ -622,6 +640,34 @@ export async function loadRegistry({ projectRoot = null, homeDir = null, builtin
622
640
  return records;
623
641
  }
624
642
 
643
+ // Delivery: the playbook body (frontmatter stripped, CRLF normalized) for
644
+ // injection into the routed turn. Bounded so a hand-edited user playbook can
645
+ // never flood the context; null on any read/parse failure (fail-open).
646
+ export const PLAYBOOK_BODY_MAX_CHARS = 2400;
647
+ export async function readPlaybookBody(filePath, { maxChars = PLAYBOOK_BODY_MAX_CHARS } = {}) {
648
+ if (typeof filePath !== 'string' || filePath === '') return null;
649
+ let raw;
650
+ try {
651
+ raw = await fs.readFile(filePath, 'utf8');
652
+ } catch {
653
+ return null;
654
+ }
655
+ const text = String(raw).replace(/\r\n/g, '\n');
656
+ let body = text;
657
+ if (text.startsWith('---\n')) {
658
+ const fenceIndex = text.indexOf('\n---', 3);
659
+ if (fenceIndex === -1) return null;
660
+ body = text.slice(fenceIndex + 4).replace(/^\n/, '');
661
+ }
662
+ // A body cannot close the <ukit-playbook> wrapper early.
663
+ body = body.trim().replace(/<\/ukit-playbook>/gi, '&lt;/ukit-playbook>');
664
+ if (body === '') return null;
665
+ if (body.length <= maxChars) return body;
666
+ // Cut on a code-point boundary (never split a surrogate pair).
667
+ const cut = Array.from(body.slice(0, maxChars + 1)).slice(0, -1).join('').slice(0, maxChars);
668
+ return `${cut.trimEnd()}\n[…truncated — full text: ${filePath}]`;
669
+ }
670
+
625
671
  function findRegistryRecord(records, playbookId) {
626
672
  const direct = records.find((r) => r.frontmatterValid && r.playbookId === playbookId);
627
673
  if (direct) return direct;
@@ -813,5 +859,11 @@ export async function resolvePlaybookRoute({
813
859
  fastPath: resolution.fastPath ?? null,
814
860
  reason: resolution.reason ?? null,
815
861
  playbookLoad: resolution.reason === 'playbook-missing' ? 'missing' : null,
862
+ // Delivery fields: the resolved file lets the hook inject the playbook body
863
+ // (agents never Read a relative `playbooks/<id>.md` that does not exist in
864
+ // the project); ambiguous candidates let the agent pick instead of losing
865
+ // the playbook entirely (pstack posture — the model chooses on ties).
866
+ file: resolution.file ?? null,
867
+ candidates: Array.isArray(resolution.candidates) ? resolution.candidates : null,
816
868
  };
817
869
  }
@@ -77,7 +77,7 @@ import {
77
77
  deriveRouteFields,
78
78
  } from './route-resolver.mjs';
79
79
  import { applyMeasuredTier, loadTierMap } from './tier-selection.mjs';
80
- import { resolvePlaybookRoute, loadRegistry, deriveRouteOrchestrationSignals } from './playbook-registry.mjs';
80
+ import { resolvePlaybookRoute, loadRegistry, deriveRouteOrchestrationSignals, readPlaybookBody as readRegistryPlaybookBody } from './playbook-registry.mjs';
81
81
  import { extractHistorySignalsAsync } from './session-history-extractor.mjs';
82
82
  import { carryProgress, buildDecompositionPlan, estimateContextWindow, MIN_AUTO_SPLIT_CONFIDENCE } from '../runtime/context-budget-policy.mjs';
83
83
  import {
@@ -1560,7 +1560,7 @@ async function main() {
1560
1560
  try { await requirePersistedRouteState(sharedStatePath, sharedState, { expectedRouteBytes }); }
1561
1561
  catch (error) { console.error(`route-task: state persist degraded — ${error?.message ?? error}`); }
1562
1562
  }
1563
- printRouteState(sharedState);
1563
+ printRouteState(await withPlaybookBody(sharedState));
1564
1564
  return;
1565
1565
  }
1566
1566
 
@@ -1666,7 +1666,7 @@ async function main() {
1666
1666
  console.error(`route-task: state persist degraded — ${error?.message ?? error}`);
1667
1667
  }
1668
1668
  }
1669
- printRouteState(sharedState);
1669
+ printRouteState(await withPlaybookBody(sharedState));
1670
1670
  return;
1671
1671
  }
1672
1672
 
@@ -1729,7 +1729,7 @@ async function main() {
1729
1729
  }
1730
1730
  }
1731
1731
 
1732
- printRouteState(sharedState);
1732
+ printRouteState(await withPlaybookBody(sharedState));
1733
1733
 
1734
1734
  // 3.3.0: Codex has no hook lifecycle — route-task is the one helper it runs
1735
1735
  // per task, so it doubles as the self-improve trigger there. Fire-and-forget:
@@ -2765,6 +2765,8 @@ async function finalizeTaskRoute({
2765
2765
  routeSummary.workGroup = playbookResolution.workGroup;
2766
2766
  routeSummary.playbookReason = playbookResolution.reason;
2767
2767
  routeSummary.playbookLoad = playbookResolution.playbookLoad;
2768
+ routeSummary.playbookFile = playbookResolution.file ?? null;
2769
+ routeSummary.playbookCandidates = Array.isArray(playbookResolution.candidates) ? playbookResolution.candidates : null;
2768
2770
  // BL-010 (ARCH Task Contract): `path` = direct|handoff; `fastPathKind` is
2769
2771
  // the ARCH `none|small-feature|bug-fix` enum — named Kind because
2770
2772
  // routeSummary.fastPath already carries the FR-004 eligibility object.
@@ -2969,6 +2971,21 @@ async function finalizeTaskRoute({
2969
2971
  };
2970
2972
  }
2971
2973
 
2974
+ // Playbook delivery: Codex/omp/print consumers read stdout, not files — an
2975
+ // absolute path alone was never followed, so the body prints with the route.
2976
+ // Read here (print-only copy) so persisted state never carries the body;
2977
+ // trivial routes get no playbook (instructions: trivial edits need none).
2978
+ async function withPlaybookBody(state) {
2979
+ try {
2980
+ const summary = state?.routeSummary;
2981
+ if (!summary?.playbookId || !summary.playbookFile || state?.routingContext?.taskType === 'trivial') return state;
2982
+ const playbookBody = await readRegistryPlaybookBody(summary.playbookFile);
2983
+ return playbookBody ? { ...state, routeSummary: { ...summary, playbookBody } } : state;
2984
+ } catch {
2985
+ return state;
2986
+ }
2987
+ }
2988
+
2972
2989
  function printRouteState(state) {
2973
2990
  const compactSummary = formatDisplayRouteSummary(state.routeSummary, state.routingContext);
2974
2991
  const nextDisplay = formatDisplayNextAction(state.routeSummary);
@@ -3051,13 +3068,27 @@ function printRouteState(state) {
3051
3068
  // TASK-007 (BL-009): playbook surface — the instruction-mediated load cue
3052
3069
  // Codex and print consumers read. playbookId only prints when a playbook
3053
3070
  // resolved; the degrade reason stays machine-side on the route record.
3054
- if (state.routeSummary?.playbookId) {
3055
- console.log(`playbook: ${state.routeSummary.playbookId} — read playbooks/${state.routeSummary.playbookId}.md and run its steps verbatim`);
3071
+ const trivialRoute = state.routingContext?.taskType === 'trivial';
3072
+ if (state.routeSummary?.playbookId && !trivialRoute) {
3073
+ console.log(`playbook: ${state.routeSummary.playbookId} — copy its numbered steps verbatim as your first todos; skipped steps keep skip:<reason>, non-applicable keep n/a:<reason>`);
3074
+ if (state.routeSummary.playbookBody) {
3075
+ console.log(`<ukit-playbook id="${state.routeSummary.playbookId}">\n${state.routeSummary.playbookBody}\n</ukit-playbook>`);
3076
+ } else if (state.routeSummary.playbookFile) {
3077
+ console.log(`playbookFile: ${state.routeSummary.playbookFile}`);
3078
+ }
3079
+ } else if (!trivialRoute && state.routeSummary?.playbookReason === 'ambiguous-route' && Array.isArray(state.routeSummary.playbookCandidates)) {
3080
+ const candidates = state.routeSummary.playbookCandidates.filter((id) => id && id !== 'handoff-cycle').slice(0, 4);
3081
+ if (candidates.length > 1) {
3082
+ console.log(`playbook candidates: ${candidates.join(', ')} — pick the one matching the primary intent and Read ${path.join(os.homedir(), '.ukit', 'playbooks')}/<id>.md`);
3083
+ }
3056
3084
  }
3057
- if (state.routeSummary?.workflowPolicyName) {
3085
+ // The injected playbook body supersedes the lane workflow policy — printing
3086
+ // both would duplicate the step list (token waste, conflicting steps).
3087
+ const playbookDelivered = Boolean(state.routeSummary?.playbookId && state.routeSummary?.playbookBody);
3088
+ if (!playbookDelivered && state.routeSummary?.workflowPolicyName) {
3058
3089
  console.log(`workflow: ${state.routeSummary.workflowPolicyName} — copy steps verbatim into your todo list; skipped steps keep skip:<reason>`);
3059
3090
  }
3060
- if (state.routeSummary?.workflowPolicy) {
3091
+ if (!playbookDelivered && state.routeSummary?.workflowPolicy) {
3061
3092
  console.log(state.routeSummary.workflowPolicy);
3062
3093
  }
3063
3094
  if (state.routeSummary?.principleIndex) {
@@ -6347,6 +6378,11 @@ export function compactRouteSummary(routeSummary = null) {
6347
6378
  fastPathKind: routeSummary.fastPathKind ?? null,
6348
6379
  ...(routeSummary.playbookReason ? { playbookReason: routeSummary.playbookReason } : {}),
6349
6380
  ...(routeSummary.playbookLoad ? { playbookLoad: routeSummary.playbookLoad } : {}),
6381
+ // Playbook delivery: file/candidates survive compaction (the body is read
6382
+ // at print time and never persisted; conditional — absent keys keep
6383
+ // unrouted states byte-identical).
6384
+ ...(routeSummary.playbookFile ? { playbookFile: routeSummary.playbookFile } : {}),
6385
+ ...(Array.isArray(routeSummary.playbookCandidates) && routeSummary.playbookCandidates.length ? { playbookCandidates: routeSummary.playbookCandidates } : {}),
6350
6386
  // M04.1 (TASK-007): the resumable-run pointer survives compaction so
6351
6387
  // reinject-context resumes from the same taskId/boundary. Conditional
6352
6388
  // spread — stage-off output stays byte-identical (no key when absent).
@@ -6506,6 +6542,8 @@ function buildRouteAuditEntry({ route = null, state = null } = {}) {
6506
6542
  playbookId: routeSummary.playbookId ?? null,
6507
6543
  workGroup: routeSummary.workGroup ?? null,
6508
6544
  playbookLoad: routeSummary.playbookLoad ?? null,
6545
+ playbookReason: routeSummary.playbookReason ?? null,
6546
+ playbookCandidates: Array.isArray(routeSummary.playbookCandidates) ? routeSummary.playbookCandidates.slice(0, 8) : null,
6509
6547
  path: routeSummary.path ?? null,
6510
6548
  fastPathKind: routeSummary.fastPathKind ?? null,
6511
6549
  source: state?.source ?? 'task-route',
@@ -34,7 +34,7 @@ files before widening further. These node scripts work unchanged under omp.
34
34
 
35
35
  Skills live in `.claude/skills/`, read by omp through its `claude` discovery provider — no mirror under
36
36
  `.omp/`. On any non-trivial task — and again after the first tool calls reveal the real work — read the
37
- matching `SKILL.md` without being asked. Users never name skills.
37
+ matching `SKILL.md` without being asked. Users never name skills. Playbooks (no command): a routed `<ukit-playbook>`/`playbook:` → copy its numbered steps as first todos (`skip:`/`n/a: <reason>`, never drop), end with its **Reply**; none or candidates → pick by intent from `~/.ukit/playbooks/` (bug-fix, small-feature, feature-implementation, refactor, investigation, performance, migration, verification, release, session-pickup) and read it.
38
38
 
39
39
  ## 6. Delegate to bind a model tier
40
40
 
@@ -56,6 +56,11 @@
56
56
  ### Common skill triggers
57
57
  - review/audit/diff → `code-review` · bug/error/crash → `debugging-toolkit` · test/coverage → `testing-quality` · docs/README/`docs/` → `docs-quality` (`.claude/skills/docs-quality/SKILL.md`) · open-ended/continue → `next-step` · wrap-up/`docs/STATUS.md` → `update-status` · auth/security/risky → `discover-security` · stale workspace/cleanup → `repo-maintenance`
58
58
 
59
+ ## Playbooks (automatic — no command)
60
+ - Non-trivial work runs a playbook from `~/.ukit/playbooks/<id>.md`. When the router injects one (`<ukit-playbook>` block or `playbook:` route line), copy its numbered steps verbatim as your first todos — a skipped step stays as `skip: <reason>`, a non-applicable one as `n/a: <reason>` — and end with its **Reply** contract.
61
+ - No playbook injected, or the router lists candidates → pick yourself from the user's primary intent and Read that file: defect → `bug-fix` · new/changed behavior → `small-feature` (1-2 files) or `feature-implementation` · structure only → `refactor` · read-only question → `investigation` · measured slowness → `performance` · live hang/leak → `runtime-forensics` · data/schema move → `migration` · run a named check → `verification` · ship/publish → `release` · resume earlier work → `session-pickup`. Trivial edits and plain continuations ("tiếp tục", "push luôn") need none.
62
+ - `/ukit:handoff-*` commands already carry their own phases; follow them, not a second playbook (their executor briefs name one per task where it applies).
63
+
59
64
  ## Internal Helper Policy
60
65
  <!-- RULES: HELP-01 HELP-02 -->
61
66
  - Prefer the internal index helpers (`node .claude/ukit/index/route-task.mjs`, `resolve-context.mjs`, `verify-context.mjs`) for routing, context, verification.
@@ -56,6 +56,11 @@
56
56
  ### Common skill triggers
57
57
  - review/audit/diff → `code-review` · bug/error/crash → `debugging-toolkit` · test/coverage → `testing-quality` · docs/README/`docs/` → `docs-quality` (`.claude/skills/docs-quality/SKILL.md`) · open-ended/continue → `next-step` · wrap-up/`docs/STATUS.md` → `update-status` · auth/security/risky → `discover-security` · stale workspace/cleanup → `repo-maintenance`
58
58
 
59
+ ## Playbooks (automatic — no command)
60
+ - Non-trivial work runs a playbook from `~/.ukit/playbooks/<id>.md`. When the router injects one (`<ukit-playbook>` block or `playbook:` route line), copy its numbered steps verbatim as your first todos — a skipped step stays as `skip: <reason>`, a non-applicable one as `n/a: <reason>` — and end with its **Reply** contract.
61
+ - No playbook injected, or the router lists candidates → pick yourself from the user's primary intent and Read that file: defect → `bug-fix` · new/changed behavior → `small-feature` (1-2 files) or `feature-implementation` · structure only → `refactor` · read-only question → `investigation` · measured slowness → `performance` · live hang/leak → `runtime-forensics` · data/schema move → `migration` · run a named check → `verification` · ship/publish → `release` · resume earlier work → `session-pickup`. Trivial edits and plain continuations ("tiếp tục", "push luôn") need none.
62
+ - `/ukit:handoff-*` commands already carry their own phases; follow them, not a second playbook (their executor briefs name one per task where it applies).
63
+
59
64
  ## Internal Helper Policy
60
65
  <!-- RULES: HELP-01 HELP-02 -->
61
66
  - Prefer the internal index helpers (`node .claude/ukit/index/route-task.mjs`, `resolve-context.mjs`, `verify-context.mjs`) for routing, context, verification.
@@ -53,6 +53,11 @@
53
53
  ### Common skill triggers
54
54
  - review/audit/diff → `code-review` · bug/error/crash → `debugging-toolkit` · test/coverage → `testing-quality` · docs/README/`docs/` → `docs-quality` (`.claude/skills/docs-quality/SKILL.md`) · open-ended/continue → `next-step` · wrap-up/`docs/STATUS.md` → `update-status` · auth/security/risky → `discover-security` · stale workspace/cleanup → `repo-maintenance`
55
55
 
56
+ ## Playbooks (automatic — no command)
57
+ - Non-trivial work runs a playbook from `~/.ukit/playbooks/<id>.md`. When the router injects one (`<ukit-playbook>` block or `playbook:` route line), copy its numbered steps verbatim as your first todos — a skipped step stays as `skip: <reason>`, a non-applicable one as `n/a: <reason>` — and end with its **Reply** contract.
58
+ - No playbook injected, or the router lists candidates → pick yourself from the user's primary intent and Read that file: defect → `bug-fix` · new/changed behavior → `small-feature` (1-2 files) or `feature-implementation` · structure only → `refactor` · read-only question → `investigation` · measured slowness → `performance` · live hang/leak → `runtime-forensics` · data/schema move → `migration` · run a named check → `verification` · ship/publish → `release` · resume earlier work → `session-pickup`. Trivial edits and plain continuations ("tiếp tục", "push luôn") need none.
59
+ - `/ukit:handoff-*` commands already carry their own phases; follow them, not a second playbook (their executor briefs name one per task where it applies).
60
+
56
61
  ## Internal Helper Policy
57
62
  <!-- RULES: HELP-01 HELP-02 -->
58
63
  - Prefer the internal index helpers (`node .claude/ukit/index/route-task.mjs`, `resolve-context.mjs`, `verify-context.mjs`) for routing, context, verification.
@@ -18,6 +18,7 @@ outputs:
18
18
  - { from: core, heading: Long-Run Continuity }
19
19
  - { from: core, heading: Index-First Loop }
20
20
  - { from: core, heading: Automatic Skill Activation (mandatory) }
21
+ - { from: core, heading: Playbooks (automatic — no command) }
21
22
  - { from: core, heading: Internal Helper Policy }
22
23
  - { from: core, heading: Skill Quality (maintainer-only) }
23
24
  - { from: core, heading: 'UKit v{{ukit.version}} Shared Runtime' }
@@ -50,6 +51,7 @@ outputs:
50
51
  - { from: core, heading: Long-Run Continuity }
51
52
  - { from: core, heading: Index-First Loop }
52
53
  - { from: core, heading: Automatic Skill Activation (mandatory) }
54
+ - { from: core, heading: Playbooks (automatic — no command) }
53
55
  - { from: core, heading: Internal Helper Policy }
54
56
  - { from: core, heading: Skill Quality (maintainer-only) }
55
57
  - { from: core, heading: 'UKit v{{ukit.version}} Shared Runtime' }
@@ -92,6 +94,7 @@ outputs:
92
94
  - { from: core, heading: Long-Run Continuity }
93
95
  - { from: core, heading: Index-First Loop }
94
96
  - { from: core, heading: Automatic Skill Activation (mandatory) }
97
+ - { from: core, heading: Playbooks (automatic — no command) }
95
98
  - { from: core, heading: Internal Helper Policy }
96
99
  - { from: core, heading: Skill Quality (maintainer-only) }
97
100
  - { from: core, heading: 'UKit v{{ukit.version}} Shared Runtime' }
@@ -125,6 +128,7 @@ outputs:
125
128
  - { from: core, heading: Long-Run Continuity }
126
129
  - { from: core, heading: Index-First Loop }
127
130
  - { from: core, heading: Automatic Skill Activation (mandatory) }
131
+ - { from: core, heading: Playbooks (automatic — no command) }
128
132
  - { from: core, heading: Internal Helper Policy }
129
133
  - { from: core, heading: Skill Quality (maintainer-only) }
130
134
  - { from: core, heading: 'UKit v{{ukit.version}} Shared Runtime' }
@@ -31,7 +31,7 @@ files before widening further. These node scripts work unchanged under omp.
31
31
 
32
32
  Skills live in `.claude/skills/`, read by omp through its `claude` discovery provider — no mirror under
33
33
  `.omp/`. On any non-trivial task — and again after the first tool calls reveal the real work — read the
34
- matching `SKILL.md` without being asked. Users never name skills.
34
+ matching `SKILL.md` without being asked. Users never name skills. Playbooks (no command): a routed `<ukit-playbook>`/`playbook:` → copy its numbered steps as first todos (`skip:`/`n/a: <reason>`, never drop), end with its **Reply**; none or candidates → pick by intent from `~/.ukit/playbooks/` (bug-fix, small-feature, feature-implementation, refactor, investigation, performance, migration, verification, release, session-pickup) and read it.
35
35
 
36
36
  ## 6. Delegate to bind a model tier
37
37