create-claude-cabinet 0.35.0 → 0.36.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-claude-cabinet",
-  "version": "0.35.0",
+  "version": "0.36.0",
   "description": "Claude Cabinet — opinionated process scaffolding for Claude Code projects",
   "bin": {
     "create-claude-cabinet": "bin/create-claude-cabinet.js"

package/templates/cabinet/skill-best-practices.md

@@ -40,6 +40,13 @@ slash commands for CC maintenance.
 
 These hold for every SKILL.md regardless of type.
 
+**Runtime output formatting lives in a sibling doc.** This doc covers
+*write-time* authoring. For *runtime* user-facing output — when a running
+skill should present choices via the native `AskUserQuestion` tool versus
+prose versus a markdown table, plus the AskUserQuestion schema facts
+authors must get right — see `skill-output-conventions.md`. Follow that
+pointer whenever a skill prompts the user to make a decision.
+
 ### Body under 500 lines
 
 The SKILL.md **body** — content after the closing `---` of

package/templates/cabinet/skill-output-conventions.md

@@ -0,0 +1,153 @@
+# Skill Output Conventions
+
+How skills format **user-facing output** and **interactive prompts** at
+runtime. The companion to `skill-best-practices.md`.
+
+## 1. Purpose & Scope
+
+`skill-best-practices.md` governs **write-time** authoring rules — file
+structure, naming, frontmatter, length. This doc governs **runtime**
+interaction: how a skill, while executing, presents choices and
+information to the user. `output-contract.md` is a third, separate
+concern — the JSON cabinet members emit during audits, not user-facing
+output.
+
+Stating the boundary keeps the three docs from drifting together: if a
+rule is about *how a SKILL.md is written*, it belongs in
+skill-best-practices; if it's about *what the running skill shows the
+user*, it belongs here.
+
+## 2. When to Use AskUserQuestion
+
+`AskUserQuestion` is the native interactive primitive — a structured
+menu of 2-4 options the user picks from. Use it when **all** of these
+hold:
+
+- The choice is among **discrete options** (not free text).
+- The answer **branches the skill's behavior** (it's a real decision).
+- There are **2-4 mutually-exclusive choices** (or a small set if
+  multiSelect).
+- It is **not an obvious-default confirm** — a yes/no where one answer
+  is plainly expected (see §5).
+- The item count is **bounded and small** — not a variable-length loop
+  (see §4).
+
+If any answer is "no," use prose (§5) or a table (§6) instead.
+
+## 3. Schema Facts Authors Must Get Right
+
+Verified against the live schema. Get these wrong and the call fails or
+behaves unexpectedly.
+
+- **1-4 questions per call; 2-4 options per question.** Outside this
+  range fails validation.
+- **`header` is REQUIRED** — a short chip/tag, **max 12 chars** (e.g.
+  `Branch`, `Verdict`, `Decision`). Omitting it fails validation. This
+  is the most common authoring mistake.
+- **Cost is per-session, not per-call.** AskUserQuestion is a deferred
+  tool: the first use in a session loads its schema (one ToolSearch
+  round-trip, ~200 tokens); every call after that is free. Don't
+  under-use it to "save" a cost that's already paid.
+- **`multiSelect` is required.** `false` for mutually-exclusive choices
+  (the norm — one answer). `true` only when the user may legitimately
+  pick more than one.
+- **"Other" is auto-added** by the harness. Never add an "Other" /
+  "Something else" option manually — it duplicates.
+- **No reliable preview/comparison field.** The official schema has no
+  dependable preview surface; don't build conventions on preview
+  behavior or expect side-by-side rendering.
+- **Unavailable in Task-spawned subagents.** Agents launched via the
+  Task tool (execute-group worktree agents, Workflow agents,
+  `context:fork`) cannot call AskUserQuestion — they must use prose.
+  This warning outlives any current wiring: a skill that runs in the
+  main session today may be called from a subagent tomorrow.
+- **Pre-specify each call site** in the SKILL.md prose — exact `header`,
+  `question`, and option labels/descriptions. In a long skill body the
+  model otherwise drifts to a prose question instead of emitting the
+  structured call. (This is an authoring practice — `skill-best-practices.md`
+  is the write-time home for it — surfaced here because it's what makes a
+  runtime AskUserQuestion call fire reliably.)
+
+## 4. Bounded-List Caveat
+
+AskUserQuestion is for **decisions**, not **batch processing**. A
+variable-length loop of homogeneous items — reviewing 12 copy edits,
+approving 30 line items — should not become 30 sequential dialogs. Past
+~5 items, prefer a single batch path (present all, take one combined
+response) over N prompts. The fatigue of N near-identical dialogs
+outweighs the structure they add.
+
+The test: are these **genuine, distinct decisions** (→ AskUserQuestion,
+one per item up to a small cap) or **homogeneous review items** (→ batch
+path)?
+
+## 5. When to Use Prose
+
+Use plain conversational prose for:
+
+- **Free-text gathering** — names, reasons, descriptions, anything not
+  a fixed menu.
+- **Clarifications and reasons** — "why did you defer this?"
+- **Obvious-default confirms** — a yes/no where one answer is plainly
+  expected and the other is rare. A structured menu over-formalizes it;
+  a prose "Want me to X? (I'll skip if not)" is lighter.
+
+## 6. When to Use Markdown Tables
+
+Use a table for **rosters, status, or any data with ≥2 columns** —
+where the value is in *comparing rows*, not *choosing one*. The `/menu`
+skill (skills × description) and `/cabinet` (member × domain) are
+canonical examples. A table presents; AskUserQuestion decides. Don't use
+a table to offer a choice, and don't use AskUserQuestion to display a
+list the user isn't picking from.
+
+## 7. Option-Block Format
+
+When presenting options as prose (subagent context, or >4 options), the
+canonical format is in `templates/skills/onboard/phases/options.md` —
+name, "what it is," "good for," "trade-off" per option. Do not duplicate
+that format here; reference it.
+
+## 8. Section Structure & Tone
+
+`options.md` is also canonical for tone: **present, don't prescribe.**
+"Here are your options" not "I recommend X." Ground choices in the
+user's actual situation. This applies whether the choice is rendered via
+AskUserQuestion or prose — the primitive changes, the posture doesn't.
+
+## 9. Calibration Examples
+
+**Before/after — engagement decision items** (the Tier 1 conversion):
+
+> Before: "Present the options conversationally and let the client
+> choose."
+> After: For each decision item, one AskUserQuestion call — `header:
+> "Decision"`, `question:` the item's client-facing prompt, `options:`
+> the item's own authored option list, `multiSelect: false`. One call
+> per item; never batched.
+
+Why: the items already carry discrete, consultant-authored options, and
+this is the consultant↔client boundary where ambiguity is most expensive
+and the client can't ask for real-time clarification.
+
+**Before/after — triage-audit fallback verdict:**
+
+> Before: a prose prompt listing "Fix / Defer / Reject / Question" and
+> asking the user to type one.
+> After: AskUserQuestion — `header: "Verdict"`, four options, one per
+> finding, `multiSelect: false`.
+
+Why: four discrete mutually-exclusive verdicts that branch behavior —
+this scores well on all five §2 criteria.
+
+**EXCLUDED — orient registry-orphan prompt** (do NOT convert):
+
+> "Your old project 'deal-v1' seems to have been deleted — want me to
+> remove it from the registry?"
+
+This looks like a Remove/Keep choice but is an **obvious-default
+confirm**: the path no longer exists, so removal is plainly expected and
+"keep" is the rare exception. A structured two-option menu over-formalizes
+a routine yes/no. Leave it prose. This is the boundary that stops
+AskUserQuestion from being applied to every binary question in the
+codebase.

package/templates/skills/cabinet-roster-check/SKILL.md

@@ -321,6 +321,20 @@ information-design's mock output. This should be sequential: designer
 produces mock, then usability critiques the interaction model using the
 mock as input."
 
+**Good (output conventions — prose where AskUserQuestion fits):** "/triage-audit's
+CLI-fallback path prompts the user to type one of Fix / Defer / Reject /
+Question. These are four discrete, mutually-exclusive verdicts that branch
+behavior — the canonical case for the native `AskUserQuestion` tool per
+`skill-output-conventions.md` §2. Rendering them as a prose 'type one of…'
+prompt is a guidance-layer drift. Flag as a finding pointing to that doc."
+Do NOT raise this finding for: free-text gathering (names, reasons), open
+clarifying questions, obvious-default confirms (e.g. orient's "remove the
+deleted project from the registry?" — removal is plainly expected, so prose
+is correct), or variable-length per-item loops of homogeneous items (those
+prefer a batch path, not N dialogs). Match the finding to the doc's §2
+checklist; if any checklist item fails, prose is the right call and there is
+no finding.
+
 **Too narrow (belongs to another cabinet member):** "The deploy script has a
 race condition." That's technical-debt or architecture territory.
 

package/templates/skills/engagement/SKILL.md

@@ -123,9 +123,25 @@ in `needs_you` was resolved upstream; don't nag about it.)
 Then split `needs_you` into two groups:
 
 - **Decisions** — items with a populated `options` list (or
-  `kind === 'decision'`). These are **never** batch-approved. Walk each
-  one individually: present the options conversationally, let the client
-  choose. A real decision always gets explicit engagement.
+  `kind === 'decision'`). These are **never** batch-approved — walk each
+  one individually with exactly **one `AskUserQuestion` call per decision
+  item**. Never bundle two decisions into a single call. Pre-specify the
+  call this way:
+  - `header`: `"Decision"` (within the 12-char cap).
+  - `question`: the item's client-facing prompt/title.
+  - `options`: the item's own `options` list, one labeled choice each.
+    **If an item has more than 4 options**, AskUserQuestion can't hold
+    them — fall back to presenting that item's options as prose and let
+    the client answer in their own words.
+  - `multiSelect: false` — a single verdict per decision.
+  - Do **not** add an "Other" choice; the harness adds it automatically.
+    If the client picks "Other" or says something off-menu, handle it
+    conversationally and map to the right verdict (see the table below).
+
+  A real decision always gets explicit engagement. (AskUserQuestion is
+  available here because `/engagement` runs in the main session, not a
+  subagent. See `.claude/cabinet/skill-output-conventions.md` for the
+  conventions behind this.)
 - **Approvals / FYIs** — items with no options. These are eligible for
   the batch default.
 

package/templates/skills/engagement-add/SKILL.md

@@ -32,8 +32,16 @@ Access pib-db via [pib-db-access.md](../../cabinet/pib-db-access.md).
    - "What's the item?" (internal `text`)
    - "Who should see it?" — map to `audience:<id>` (and, for a delegate,
      `assignee:<id>` — the **sole** basis for a delegate seeing it).
-   - "Is it a decision the client must make, or a credential they must
-     provide?" → `needs:decision` / `needs:credential` (or neither).
+   - Collect item type via `AskUserQuestion`:
+     - `header`: `"Item type"`
+     - `question`: "What kind of item is this?"
+     - `options`:
+       - Decision — "Client must choose among options you provide"
+       - Credential — "Client must hand over a secret (secure dialog)"
+       - Neither — "Informational or approval item, no special handling"
+     - `multiSelect: false`
+     Map: Decision → tag `needs:decision`. Credential → tag
+     `needs:credential`. Neither → no needs tag.
    - "What scope?" (optional `scope:<scope>`)
    - To make a **project itself** visible to clients as a roll-up
      (e.g., "E-signing: Done"), tag the project `client-visible` and author
@@ -50,6 +58,9 @@ Access pib-db via [pib-db-access.md](../../cabinet/pib-db-access.md).
    - Always include `client-visible` (an item with no `client-visible`
      tag appears in **no** packet).
 
+   (See `.claude/cabinet/skill-output-conventions.md` for when structured
+   choices apply.)
+
 3. **Prompt for the client-facing copy block** (optional — the
    consultant can write it now or let `/engagement-sync` draft it):
    - "Want to write the client-facing copy now, or let `/engagement-sync`

package/templates/skills/engagement-create/SKILL.md

@@ -53,14 +53,24 @@ id, name, email, and their role."
 For each recipient, capture:
 - **id** — short handle (e.g. `ed`, `sydney`), used in tags
 - **name**, **email**
-- **role** — `principal` (sees everything, gets billing) or `delegate`
-  (sees only items assigned to them, no billing)
+- **role** — collect via `AskUserQuestion`:
+  - `header`: `"Role"`
+  - `question`: "What role for [name]?"
+  - `options`:
+    - Principal — "Sees everything, gets billing, defaults to interactive delivery"
+    - Delegate — "Sees only assigned items, no billing, defaults to email"
+  - `multiSelect: false`
 - **scopes** — topical areas they care about (e.g. `[marketing]`); a
   principal is usually `[all]`
-- **has_claude_code** — "Does [name] have Claude Code installed? If yes:
-  they get the interactive `/engagement` view with rich status updates.
-  If no: they get a formatted email summary instead. (Principals default
-  to yes, delegates default to no.)"
+- **has_claude_code** — collect via `AskUserQuestion`:
+  - `header`: `"Delivery"`
+  - `question`: "Does [name] have Claude Code installed?"
+  - `options`:
+    - Yes — "Interactive /engagement view with rich status"
+    - No — "Formatted email summary instead"
+  - `multiSelect: false`
+  (Principals default to yes, delegates default to no — use as the
+  pre-selected suggestion in the question phrasing.)
 
 The default `roles` block is:
 ```yaml
@@ -86,8 +96,17 @@ confirmation before proceeding.
 "Do you bill time on this engagement?" If yes:
 - **timelog** path (default `./timelog.md`)
 - **rate** (default `190`), **currency** (default `USD`)
-- **period** — `engagement` (running total), `month`, or
-  `since-last-sync` (only since the last packet) — default `engagement`
+- **period** — collect via `AskUserQuestion`:
+  - `header`: `"Billing"`
+  - `question`: "How should billing be calculated?"
+  - `options`:
+    - Running total — "Cumulative from engagement start (default)"
+    - Monthly — "Reset each calendar month"
+    - Since last sync — "Only time since the last packet was sent"
+  - `multiSelect: false`
+
+(See `.claude/cabinet/skill-output-conventions.md` for when structured
+choices apply.)
 
 Billing appears only in `principal`-role packets.
 

package/templates/skills/engagement-sync/SKILL.md

@@ -150,15 +150,33 @@ For every `client-visible` action or project **lacking** a `<!-- client-facing -
 summary: "N items need new copy (no block). M items have stale copy
 (status changed). Total: N+M items to review."
 
-**Batch option for large sets.** If more than 5 items need review, offer:
-"Review each individually, or review as a batch? (Batch shows all drafts
-at once — you confirm, edit by number, or skip any.)"
+**Batch option for large sets.** If more than 5 items need review,
+collect the choice via `AskUserQuestion`:
+- `header`: `"Review"`
+- `question`: "N items need copy review. How to proceed?"
+- `options`:
+  - Individual — "One at a time, decide each separately"
+  - Batch — "Show all drafts at once, confirm/edit by number"
+- `multiSelect: false`
 
 **Skip if block exists.** An existing block (hand-written or previously approved) is authoritative. Never overwrite it. Check: `parseClientCopy(notes) !== null → skip`.
 
 **Draft from structured data.** Call `buildGenerationSource(item)` (from `engagement.mjs`) to get the structured metadata — status, completion, needs, options. For projects, pre-compute `child_summary` via `computeChildSummary(actions, project.fid)` and attach it to the project object before calling. Claude drafts a `client_title` + `client_why` from this metadata. The internal `text` field is NEVER an input to generation.
 
-**Per-item review loop (not batch approve).** For each generated draft, show the consultant: the structured source data and the generated title + why. Consultant chooses **Accept / Edit / Skip** per item. Accepted or edited copy proceeds to write-back. Skipped items remain without copy (the dispatch gate drops them).
+**Per-item review loop (not batch approve).** For each generated draft,
+show the consultant the structured source data and the generated title +
+why, then collect the verdict via `AskUserQuestion`:
+- `header`: `"Copy"`
+- `question`: "[item title] — accept this draft?"
+- `options`:
+  - Accept — "Use this copy as-is"
+  - Edit — "I'll provide revised text"
+  - Skip — "Leave without copy (dispatch gate will drop it)"
+- `multiSelect: false`
+
+Accepted or edited copy proceeds to write-back. Skipped items remain
+without copy (the dispatch gate drops them). If "Edit" is chosen, ask
+for the revised text conversationally, then write back.
 
 **Write-back.** On approval, call `spliceClientCopy(notes, newBlock, markerLine)` (from `engagement.mjs`) to produce the updated notes. `newBlock` is the `<!-- client-facing ... -->` block. `markerLine` is `<!-- cc-generated:<ISO timestamp> status:<current status> -->` — placed OUTSIDE the copy block (never inside, or `parseClientCopy` would include it in `client_why`). Write via `pib_update_action({ fid, notes: splicedNotes })` or `pib_update_project({ fid, notes: splicedNotes })`.
 
@@ -218,14 +236,23 @@ For project roll-ups, show: `E-signing (roll-up: 3 done, 1 in progress)`
 vs action items: `DNS cutover (action, needs:decision)`. For projects
 with individually-visible children, note the count.
 
-Then ask: **"Send these updates now, or review a recipient's packet in
-detail first?"**
-
-- **"Send"** → proceed to archive + dispatch (steps 7–9).
-- **"Show me Ed's"** → render Ed's full packet (needs_you titles, in_flight,
-  shipped, messages, billing) so the consultant can read exactly what Ed will
-  see. Then re-ask.
-- **"Cancel"** → abort the sync, nothing sent.
+Then collect the dispatch decision via `AskUserQuestion`:
+- `header`: `"Dispatch"`
+- `question`: "Ready to send to N recipients?"
+- `options`:
+  - Send — "Archive and dispatch all packets now"
+  - Review — "Show me a recipient's packet in detail first"
+  - Cancel — "Abort this sync, nothing sent"
+- `multiSelect: false`
+
+- **Send** → proceed to archive + dispatch (steps 7–9).
+- **Review** → ask which recipient, render their full packet (needs_you,
+  in_flight, shipped, messages, billing), then re-present this same
+  AskUserQuestion (loop until Send or Cancel).
+- **Cancel** → abort, nothing sent.
+
+(See `.claude/cabinet/skill-output-conventions.md` for when structured
+choices apply.)
 
 This confirmation step is the human-in-the-loop gate — the safety checks
 (assertPacketInvariants) catch structural violations, but only the

package/templates/skills/orient/SKILL.md

@@ -282,7 +282,19 @@ items are returned, skip silently. Otherwise:
    (`triggered | still-waiting | needs-info | condition-obsolete`)
    and brief reasoning in notes.
 4. Include any items that evaluated to `triggered` in the briefing's
-   **Attention Items** section. Do not auto-reopen — the user decides.
+   **Attention Items** section. For each, collect the user's decision
+   via `AskUserQuestion`:
+   - `header`: `"Triggered"`
+   - `question`: "[fid] appears triggered — [trigger summary]. What to do?"
+   - `options`:
+     - Reopen — "Change status back to open, ready to work"
+     - Leave deferred — "Keep it deferred, not ready yet"
+     - Mark obsolete — "Trigger condition no longer relevant"
+   - `multiSelect: false`
+
+   Map: Reopen → status to open; Leave deferred → no-op; Mark obsolete
+   → `pib_mark_trigger_checked` with `condition-obsolete`.
+   (See `skill-output-conventions.md`.)
 
 **Cost control:** Cap this phase at 30 seconds total. If N > 10 items,
 evaluate only the 5 least-recently-checked.
@@ -344,9 +356,18 @@ done
 Also check `git worktree list` for active worktrees whose branches
 have diverged from main.
 
-Surface as advisory:
-> ⚠ Branch `feature-x` has N commits ahead of main (last touched
-> [date]). Merge, continue working, or discard?
+Surface as advisory, then collect the decision via `AskUserQuestion`:
+- `header`: `"Branch"`
+- `question`: "Branch `[name]` has N commits ahead of main. What to do?"
+- `options`:
+  - Merge — "Merge into main now"
+  - Continue — "Leave it, still working on it"
+  - Discard — "Delete the branch (destructive)"
+- `multiSelect: false`
+
+Map: Merge → `git merge [branch]` (surface conflicts if any). Continue →
+no-op. Discard → warn "permanently deletes N commits" and require
+explicit second confirmation before `git branch -D`.
 
 **Known platform limitation:** The Claude Code Agent tool with
 `isolation: "worktree"` branches from the remote tracking ref, not

package/templates/skills/triage-audit/SKILL.md

@@ -136,8 +136,23 @@ assumption, evidence, question, and your commentary. The user needs to
 see everything to make good decisions.
 
 **Fallback (no browser available):** Present findings in the conversation
-grouped by cabinet member, severity-ordered within each group. Ask for
-verdicts one group at a time to avoid overwhelming.
+grouped by cabinet member, severity-ordered within each group. For each
+finding, show its full context (title, description, assumption, evidence,
+question, and your commentary), then collect the verdict via one
+`AskUserQuestion` call:
+
+- `header`: `"Verdict"`
+- `question`: the finding's title
+- `options`:
+  - Fix — "Real finding, approve for action"
+  - Defer — "Real but not now — revisit later"
+  - Reject — "Not a real problem for this project"
+  - Question — "Need more information before deciding"
+- `multiSelect: false`
+
+One call per finding, walked individually within each group. (See
+`.claude/cabinet/skill-output-conventions.md` for when this pattern
+applies.)
 
 ### 3. Apply Verdicts (core)