create-claude-cabinet 0.45.0 → 0.47.0

package/templates/skills/debrief-classic/calibration.md

@@ -0,0 +1,44 @@
+# debrief-classic Extending and Calibration
+
+## Extending
+
+To customize a phase: write content in the corresponding `phases/` file.
+To skip a phase: leave the file empty or don't create it.
+To add a phase the skeleton doesn't define: create a new file in
+`phases/` with a description of when it runs relative to the core
+phases. Claude reads whatever phase files exist at runtime.
+
+Examples of phases mature projects add:
+- Project completion scanning (auto-close projects with zero open items)
+- Prep/research passes on open work items
+- Evening preview (tomorrow's calendar, due items, prep needed)
+- Compliance checks (verify required skills were invoked)
+- Machine/environment drift detection
+
+## Calibration
+
+**Core failure this targets:** Ending a session without closing loops,
+leaving completed work marked as open, unrecorded lessons, and stale
+state that degrades the next session's orient.
+
+### Without Skill (Bad)
+
+Session ends. Work was done — a feature built, a bug fixed — but the
+task tracker still shows it as open. Feedback that was addressed stays
+unresolved. A lesson learned about a tricky API behavior isn't written
+down. Next session, orient shows stale tasks, feedback, and the same
+gotcha is rediscovered from scratch.
+
+The system is doing work but not learning from it. Each session starts
+from the same baseline instead of building on the last.
+
+### With Skill (Good)
+
+Session ends. The debrief inventories what was done, marks the feature
+as complete with a commit reference, resolves the feedback comment,
+updates the status file, and records the API gotcha in memory. Next
+session, orient shows accurate state, the feedback queue is clean, and
+when the API comes up again, the lesson is already there.
+
+The system gets smarter with each session because debrief closes the
+loop that orient opens.

package/templates/skills/debrief-classic/phases/audit-pattern-capture.md

@@ -0,0 +1,78 @@
+# Audit Pattern Capture
+
+Runs after cabinet consultations (step 3) and before recording lessons.
+Detects recurring audit findings and writes them to the relevant cabinet
+member's `patterns-project.md` file.
+
+## When This Runs
+
+After cabinet members have completed their debrief consultations. This
+phase consumes what they produced — it doesn't run cabinet members itself.
+
+## What to Do
+
+### 1. Collect This Session's Audit Findings
+
+If an audit ran this session (check for audit output in the session's
+work), collect the findings by cabinet member. If no audit ran, skip
+this phase entirely.
+
+### 2. Check for Recurrence
+
+For each cabinet member that produced findings this session, check
+whether the same CLASS of finding has appeared before:
+
+- Check triage history if available: use `pib_triage_history` (or
+  `node scripts/pib-db.mjs triage-history` CLI fallback).
+  Look for approved findings from the same cabinet member with similar
+  descriptions.
+
+- Check the member's existing `patterns-project.md` if it exists —
+  is this finding already captured?
+
+**A pattern is recurring when:** The same cabinet member flags the same
+class of issue (not identical text, but the same underlying problem)
+in 2+ separate audit runs. One-time findings stay as findings; recurring
+ones become patterns.
+
+### 3. Write to patterns-project.md
+
+For each newly detected recurring pattern, append it to the member's
+project pattern file:
+
+**Path:** `.claude/skills/cabinet-{member-name}/patterns-project.md`
+
+Create the file if it doesn't exist. Append if it does.
+
+**Entry format:**
+```markdown
+### [Short pattern name]
+
+**Occurrences:** [N] times across [N] audits (first: YYYY-MM-DD, latest: YYYY-MM-DD)
+
+[1-2 sentence description of the pattern — what the issue is and why
+it recurs. Be specific enough that the cabinet member can detect it
+in future audits without re-reading the original findings.]
+```
+
+### 4. Surface Pattern Promotion Candidates
+
+After writing project patterns, check if any patterns in
+`patterns-project.md` look universal (not specific to this project's
+domain, codebase, or technology choices). If so, note them for the
+CC feedback phase — they may be candidates for upstream promotion.
+
+Signals that a pattern is universal:
+- It describes a general coding practice, not a project-specific convention
+- It would apply to any project using the same technology
+- The pattern name doesn't reference project-specific entities
+
+Do NOT auto-promote. Just surface the candidate so the CC feedback
+phase can decide whether to file it.
+
+## What NOT to Do
+
+- Don't capture one-time findings as patterns
+- Don't duplicate patterns already in `patterns-project.md`
+- Don't modify the upstream SKILL.md section — that's CC-owned
+- Don't create `patterns-project.md` for members with no recurring findings

package/templates/skills/debrief-classic/phases/auto-maintenance.md

@@ -0,0 +1,48 @@
+# Auto-Maintenance — Recurring Session-End Tasks
+
+Define automated tasks that should run at the end of every session.
+Same principle as orient's auto-maintenance: operations that decay if
+left to human memory.
+
+Session-end maintenance differs from session-start: orient's maintenance
+prepares for work, debrief's maintenance cleans up after it.
+
+When this file is absent or empty, this step is skipped. (`skip: true`
+is equivalent to absent here.)
+
+## What to Include
+
+For each task, provide:
+- **What** — the operation to perform
+- **Why every session** — what decays if this is skipped
+- **Command** — how to run it
+- **Auto-execute?** — yes (run silently) or surface (ask user first)
+
+## Example Maintenance Tasks
+
+Uncomment and adapt these for your project:
+
+<!--
+### Scan for Stale Work Items
+```bash
+# Find items that should have been closed but weren't
+sqlite3 project.db "SELECT id, text FROM tasks WHERE status = 'active' AND updated_at < date('now', '-14 days')"
+```
+Items that haven't been touched in two weeks may be stale. Surface for
+user decision: still active, defer, or close.
+
+### Clean Build Artifacts
+```bash
+rm -rf .build-cache/tmp/*
+```
+Temporary build artifacts that accumulate. Silent cleanup.
+
+### Refresh Research / Prep
+```bash
+# Scan open items for ones that could benefit from background research
+sqlite3 project.db "SELECT id, text FROM tasks WHERE status = 'active' AND prep_status IS NULL"
+```
+Identify work items where doing a quick research pass now would save
+time in a future session. Auto-execute for quick items; surface complex
+ones.
+-->

package/templates/skills/debrief-classic/phases/checklist-feedback.md

@@ -0,0 +1,123 @@
+# Checklist Feedback — bug → sharpen dimension
+
+Runs after Record Lessons (step 9), before Methodology Capture (step 10).
+This phase closes the learning loop for the change-impact checklist: when
+a bug slips through, the checklist should learn from it.
+
+## No-op guards (checked in order)
+
+1. **No bugs caught this session.** If the session inventory (step 1) and
+   close-work (step 2) didn't identify any bug fixes, unexpected failures,
+   or regressions, skip silently. The trigger is "something went wrong
+   that shouldn't have" — not every session has one.
+
+2. **qa-dimensions.yaml doesn't exist.** If `.claude/cabinet/qa-dimensions.yaml`
+   is absent, the checklist engine isn't active for this project. Instead
+   of skipping silently, emit a one-time bootstrap nudge:
+
+   > A bug was caught this session. If you had a change-impact checklist,
+   > this category could be flagged automatically next time. Want to set
+   > one up? Copy `.claude/cabinet/qa-dimensions-template.yaml` to
+   > `.claude/cabinet/qa-dimensions.yaml` and customize it, or run
+   > `/checklist-discover` to build one from your codebase.
+
+   Then stop — don't try to update a file that doesn't exist.
+
+## What to do (when both guards pass)
+
+### 1. Identify the bug category
+
+For each bug caught/fixed this session, ask:
+
+- **What files were involved?** (the surface area of the fix)
+- **What class of problem was it?** (data integrity, API contract break,
+  UI rendering, security gap, missing validation, etc.)
+- **Was it caught by the checklist?** Check the session's CP3 output —
+  did the change-impact checklist surface a relevant check, or did this
+  bug slip through uncovered?
+
+If the checklist DID surface a relevant check and the bug was caught
+via that check, this is a hit — the system worked. Record it: append
+`{date, check (quoted as written), note}` to that dimension's `catches`
+in `.claude/cabinet/checklist-stats.json` (write protocol:
+`cabinet/checklist-stats-schema.md`; atomic temp + rename, fail-open).
+Catches are the evidence that keeps a dimension alive when the audit
+skill's `checklist-pruning` phase reviews hit rates. Then no further
+action for this bug.
+
+If the bug slipped through, continue to step 2.
+
+### 2. Map to a dimension
+
+Read `.claude/cabinet/qa-dimensions.yaml`. For the bug's file paths and
+category, determine:
+
+- **Existing dimension covers it:** A dimension's paths match the bug's
+  files, but the checks weren't specific enough to catch this class of
+  problem. Propose sharpening — add a new check to the existing dimension.
+
+- **No dimension covers it:** No dimension's paths match the bug's files,
+  or no dimension's category is relevant. Propose a new dimension with
+  path patterns derived from the bug's file paths and an initial check
+  derived from the bug's class.
+
+### 3. Propose the change (one at a time)
+
+If this is the user's first time seeing a checklist proposal, precede
+it with a one-sentence orientation:
+
+> The change-impact checklist is organized by *dimensions* — categories
+> of code change that need verification. Each dimension has path patterns
+> (which files trigger it) and checks (what to verify). Here's a
+> suggested change based on what slipped through today:
+
+Then present each proposed change individually. For a sharpened check:
+
+> **Sharpen dimension: data-coherence**
+> Add check: `[review] Verify migration handles NULL values in existing rows`
+> Reason: session bug — migration assumed non-null column, broke on legacy data
+>
+> Accept / Edit / Skip?
+
+For a new dimension:
+
+> **New dimension: config-drift**
+> Paths: `["**/config*", "**/.env*"]`
+> Severity: moderate
+> Initial check: `[review] Verify config change is reflected in all environments`
+> Reason: session bug — .env.production missed a new variable
+>
+> Accept / Edit / Skip?
+
+Never batch — one proposal at a time so the user can think about each.
+
+### 4. Apply approved changes
+
+For accepted proposals, update `.claude/cabinet/qa-dimensions.yaml`:
+- Sharpened check → append to the dimension's `checks` list
+- New dimension → append to the `dimensions` map
+
+**Back up before writing:**
+
+```bash
+cp .claude/cabinet/qa-dimensions.yaml .claude/cabinet/qa-dimensions.yaml.bak
+```
+
+Read the file, apply the change, write the file. Preserve existing
+formatting and comments.
+
+**Post-write validation:** re-read the file and confirm the top-level
+`dimensions:` key is still present and the new entry has `paths`,
+`severity`, and `checks`. If validation fails, restore from `.bak`
+and report the error.
+
+## Constraints
+
+- **Add-only.** This phase NEVER proposes removing or weakening checks.
+  Pruning is a separate concern at audit cadence — the audit skill's
+  `checklist-pruning` phase, fed by the hit-rate sidecar this phase
+  writes catches to — not session-end debrief.
+- **User approves every change.** No silent modifications to
+  qa-dimensions.yaml.
+- **One proposal at a time.** Don't batch multiple proposals into a
+  single question.

package/templates/skills/debrief-classic/phases/close-work.md

@@ -0,0 +1,163 @@
+# Close Work — Match, Close, and Resolve
+
+Define how to match the session's work against open items and close them.
+This includes marking tasks done, resolving feedback, and updating any
+tracking system. The /debrief skill reads this file after inventorying
+what was done.
+
+When this file is absent or empty, the default behavior is: query the
+reference data layer (pib-db) for open actions, match against the
+session's git log, and propose marking matched actions as done. If
+pib-db is not initialized, skip gracefully.
+
+## Default Behavior (pib-db)
+
+**Access method:** Use `pib_*` MCP tools when available (see
+`.claude/cabinet/pib-db-access.md`), fall back to `node scripts/pib-db.mjs`
+CLI.
+
+When no custom close-work is configured:
+
+1. **Get session work:** Review `git log --oneline` for this session's
+   commits (since session start or last 2 hours)
+2. **Get open actions:** Use `pib_list_actions` (or `node scripts/pib-db.mjs list-actions`)
+3. **Match:** For each open action, check if this session's work
+   addresses it (compare action text/notes against commit messages
+   and changed files)
+4. **Propose:** Present matched actions and ask the user to confirm
+   which to close
+5. **Close confirmed:** Use `pib_complete_action` (or `node scripts/pib-db.mjs complete-action <fid>`)
+
+If pib-db doesn't exist, skip with a note.
+
+## What to Include
+
+- **How to query open items** — where your work tracker lives, how to
+  read it
+- **How to mark items done** — the command or API to update status
+- **How to resolve feedback** — if your project tracks feedback or
+  comments, how to mark them addressed
+- **What to include in completion notes** — commit references, summary
+  of what was built
+
+## Example Close-Work Patterns
+
+Uncomment and adapt these for your project:
+
+<!--
+### Task Tracker (Database)
+```bash
+# Query open tasks
+sqlite3 project.db "SELECT id, text, status FROM tasks WHERE status != 'done'"
+
+# Mark a task done with commit reference
+COMMIT=$(git log -1 --format=%h)
+sqlite3 project.db "UPDATE tasks SET status = 'done', notes = notes || '\n\nCompleted in $COMMIT' WHERE id = 'TASK_ID'"
+```
+
+### Task Tracker (API)
+```bash
+# Query open tasks
+curl -s https://your-api.example.com/api/tasks?status=open
+
+# Mark done
+curl -X PATCH https://your-api.example.com/api/tasks/TASK_ID \
+  -H "Content-Type: application/json" \
+  -d '{"status": "done", "completedRef": "COMMIT_HASH"}'
+```
+
+### Task Tracker (Markdown)
+```bash
+# Find open tasks
+grep -n '- \[ \]' tasks.md
+
+# Mark done (replace checkbox)
+# Edit the file to change `- [ ]` to `- [x]` for completed items
+```
+
+### Feedback / Comments
+```bash
+# Query unresolved feedback
+sqlite3 project.db "SELECT id, text FROM feedback WHERE resolved = 0"
+
+# Cross-reference against session work — if the feedback was addressed,
+# resolve it with a note about what fixed it
+sqlite3 project.db "UPDATE feedback SET resolved = 1, resolution = 'Fixed in COMMIT' WHERE id = FEEDBACK_ID"
+```
+
+### Follow-On Work
+When closing an item that has documented sub-phases or next steps in its
+notes, create new items for each. Known work that lives only in completed
+items' notes will be forgotten. There is no "later" — create it now.
+-->
+
+## Resolve Field Feedback
+
+After closing actions, check the `feedback/` directory for field feedback
+files from consuming projects. For each file, evaluate whether this
+session's work addressed the friction described.
+
+**Trigger conditions** (check ALL, not just git-log matching):
+1. **Git-log matching:** Cross-reference feedback files against this
+   session's changed files and commit messages.
+2. **Project-name matching:** If any closed project's name or description
+   contains "feedback", "remediation", or "field feedback", explicitly
+   scan ALL feedback files and present them for resolution — the project
+   was likely created to address them.
+3. **Component matching:** If this session edited files in a component
+   mentioned by a feedback file (e.g., session edited `cc-publish/SKILL.md`
+   and a feedback file has `component: skills/cc-publish`), surface it.
+
+**How to check:**
+1. Scan `feedback/` for `.md` files (skip `.gitkeep`)
+2. For each file, read the `component` from frontmatter and the friction
+   description
+3. Apply all trigger conditions above — any match means the feedback
+   should be presented for resolution
+4. For each resolved item, present to the user:
+   > "Field feedback resolved: [title] from [source] — [one-line summary
+   > of what fixed it]. Delete the feedback file? (yes/no)"
+5. On confirmation, delete the feedback file. It served its purpose —
+   the friction was addressed and the fix is in the commit history.
+
+**Why delete rather than mark resolved?** Feedback files are a queue, not
+a ledger. The commit history records what was fixed and when. Keeping
+resolved feedback files around creates stale noise that orient has to
+filter through every session.
+
+**Partially addressed feedback** stays open. If the session fixed one
+aspect but not another, note what was fixed in the file (append a
+`## Partial resolution` section) but don't delete it.
+
+## Project Completion Scan
+
+After closing individual actions, check for projects that may be ready
+to complete. A project with actions where all are done is finished —
+leaving it active is stale state that erodes trust in the work tracker.
+
+When using pib-db (default):
+
+Use `pib_query` (or `node scripts/pib-db.mjs query`) with:
+```sql
+SELECT p.fid, p.name,
+  (SELECT COUNT(*) FROM actions a WHERE a.project_fid = p.fid) as total,
+  (SELECT COUNT(*) FROM actions a WHERE a.project_fid = p.fid AND a.completed = 1) as done
+FROM projects p
+WHERE p.status = 'active'
+  AND p.deleted_at IS NULL
+  AND (SELECT COUNT(*) FROM actions a WHERE a.project_fid = p.fid) > 0
+  AND (SELECT COUNT(*) FROM actions a WHERE a.project_fid = p.fid AND a.completed = 0 AND a.deleted_at IS NULL) = 0
+```
+
+For each result: all actions are complete. Propose completing the project:
+- Show the project name and action count (e.g., "prj:abc — My Project (5/5 actions done)")
+- Ask the user to confirm before closing
+- On confirmation, use `pib_query` (or `node scripts/pib-db.mjs query`) with:
+  `UPDATE projects SET status = 'done', completed_at = date('now') WHERE fid = '<fid>'`
+
+**Design notes:**
+- Projects with zero total actions are excluded — they may be containers
+  or newly created, not "done."
+- This runs AFTER individual action closing, so newly-completed actions
+  from this session are counted.
+- If pib-db doesn't exist, skip this check.

package/templates/skills/debrief-classic/phases/health-checks.md

@@ -0,0 +1,54 @@
+# Health Checks — Session-End Verification
+
+Define health checks to run at the end of the session. These verify that
+the session's work didn't break anything and that the system is in a
+good state for the next session.
+
+When this file is absent or empty, this step is skipped. (`skip: true`
+is equivalent to absent here.)
+
+End-of-session health checks differ from start-of-session: orient checks
+catch pre-existing problems; debrief checks catch problems the session
+may have introduced.
+
+## What to Include
+
+For each check, provide:
+- **Name** — short label for reporting
+- **Command** — how to run the check
+- **What it catches** — what could have gone wrong during the session
+- **If it fails** — fix now, or note for next session?
+
+## Example Health Checks
+
+Uncomment and adapt these for your project:
+
+<!--
+### Memory Index Freshness
+```bash
+# Verify all memory files are listed in the index
+ls memory/*.md | while read f; do
+  basename="$(basename $f)"
+  grep -q "$basename" memory/MEMORY.md || echo "MISSING: $basename"
+done
+```
+Catches memory files created during the session that weren't added to
+the index. Fix immediately — an unlisted memory file is invisible.
+
+### State File Consistency
+```bash
+# Verify system-status.md was updated if code changed
+CHANGED=$(git diff --name-only HEAD~5 | grep -v '.md$' | wc -l)
+STATUS_CHANGED=$(git diff --name-only HEAD~5 | grep 'system-status.md' | wc -l)
+[ "$CHANGED" -gt 0 ] && [ "$STATUS_CHANGED" -eq 0 ] && echo "WARN: code changed but status not updated"
+```
+If code was changed but the status file wasn't updated, the next
+orient will read stale state. Fix before closing.
+
+### Build Verification
+```bash
+npm run build 2>&1 | tail -5
+```
+Verify the project still builds after changes. If broken, fix before
+committing or note the failure clearly.
+-->

package/templates/skills/debrief-classic/phases/inventory.md

@@ -0,0 +1,40 @@
+# Inventory — How to Identify What Was Done
+
+Define how to determine what the session accomplished. The /debrief skill
+reads this file to build a list of completed work before matching it
+against open items.
+
+When this file is absent or empty, the default behavior is: review git
+log, files changed, and session context. To explicitly skip inventory,
+write only `skip: true`.
+
+## What to Include
+
+For each evidence source, provide:
+- **Source** — where to look for what changed
+- **Command** — how to query it
+- **What it reveals** — commits, file changes, conversation actions
+
+## Example Inventory Methods
+
+Uncomment and adapt these for your project:
+
+<!--
+### Git History
+```bash
+git log --oneline -20    # recent commits
+git diff --stat HEAD~5   # files changed
+```
+The primary evidence of what was built, fixed, or modified.
+
+### Conversation Context
+Review what was discussed, what plans were executed, what features were
+built, what bugs were fixed. This catches work that isn't yet committed.
+
+### Deployment Log
+```bash
+cat deploy/latest.log
+```
+If the session included a deployment, note what was deployed and whether
+it succeeded.
+-->

package/templates/skills/debrief-classic/phases/loose-ends.md

@@ -0,0 +1,52 @@
+# Loose Ends — Non-Project Items to Capture
+
+Define how to sweep for non-project items and environmental concerns
+before closing the session. Sessions generate work that isn't part of
+the main project — manual tasks, purchases, emails, configuration
+changes, appointments. If these aren't captured, they rely on human
+memory, which violates the anti-entropy principle.
+
+When this file is absent or empty, this step is skipped. (`skip: true`
+is equivalent to absent here.)
+
+## What to Include
+
+- **What to scan for** — categories of non-project items
+- **Where to route them** — inbox, task tracker, notes, specific lists
+- **How to capture** — API calls, file edits, commands
+
+## Example Loose Ends Patterns
+
+Uncomment and adapt these for your project:
+
+<!--
+### Non-Project Tasks
+Scan the session for anything that came up which isn't a project task
+but should be tracked:
+- Manual steps the user needs to take outside the terminal
+- Purchases or orders to place
+- Emails or messages to send
+- License acceptances or account actions
+- Appointments or scheduling tasks
+
+Route each to its proper home — don't dump everything in a generic
+inbox if you know the category. An item that's already classified
+should go directly to the right place.
+
+### Environment Changes
+If the session changed anything that lives outside of git:
+- New background processes or services started
+- System permissions granted
+- New tools or dependencies installed globally
+- Environment variables added or changed
+- Configuration files outside the project directory
+
+Record these in a setup or environment file so the configuration can
+be reproduced. An environment change that isn't documented is a change
+that gets lost on the next machine.
+
+### If Nothing Surfaced
+This is the most common outcome. If no non-project items came up during
+the session, skip this phase silently — don't report "no loose ends
+found."
+-->