create-claude-cabinet 0.6.0

package/templates/skills/debrief/SKILL.md

@@ -0,0 +1,409 @@
+---
+name: debrief
+description: |
+  Session close. Inventories what was done, closes work items, updates
+  state, captures lessons, and prepares the briefing for next time. This
+  is a skeleton skill using the phases/ directory pattern. Use when:
+  session end, "debrief", "wrap up", "/debrief", "quick debrief",
+  "debrief-quick", "/debrief-quick", or after completing significant work.
+  If "quick" is mentioned, use the Quick Mode section — run core phases
+  only, skip presentation phases.
+related:
+  - type: file
+    path: .claude/skills/debrief/phases/inventory.md
+    role: "Project-specific: how to identify what was done"
+  - type: file
+    path: .claude/skills/debrief/phases/close-work.md
+    role: "Project-specific: how to close work items and resolve feedback"
+  - type: file
+    path: .claude/skills/debrief/phases/auto-maintenance.md
+    role: "Project-specific: recurring session-end tasks"
+  - type: file
+    path: .claude/skills/debrief/phases/update-state.md
+    role: "Project-specific: what state to update"
+  - type: file
+    path: .claude/skills/debrief/phases/health-checks.md
+    role: "Project-specific: session-end health checks"
+  - type: file
+    path: .claude/skills/debrief/phases/record-lessons.md
+    role: "Project-specific: how to capture learnings"
+  - type: file
+    path: .claude/skills/debrief/phases/loose-ends.md
+    role: "Project-specific: non-project items to capture"
+  - type: file
+    path: .claude/skills/debrief/phases/upstream-feedback.md
+    role: "Instruction: surface CoR friction back to source repo"
+  - type: file
+    path: .claude/skills/debrief/phases/report.md
+    role: "Project-specific: how to present the summary"
+  - type: file
+    path: cabinet/_briefing.md
+    role: "Project identity and configuration"
+---
+
+# /debrief — Session Close
+
+## Purpose
+
+Close every session properly so the next one starts informed. Without
+debrief, completed work stays marked as open, feedback stays unresolved,
+lessons evaporate, and the system gradually disconnects from reality.
+Orient reads the past, debrief writes the future. That's the loop that
+gives your cabinet continuity.
+
+This is a **skeleton skill** using the `phases/` directory pattern. The
+orchestration (what to do and in what order) is generic. Your project
+defines the specifics in phase files under `phases/`.
+
+### Phase File Protocol
+
+Phase files have three states:
+
+| State | Meaning |
+|-------|---------|
+| Absent or empty | Use this skeleton's **default behavior** for the phase |
+| Contains only `skip: true` | **Explicitly opted out** — skip this phase entirely |
+| Contains content | **Custom behavior** — use the file's content instead |
+
+The skeleton always does something reasonable when a phase file is absent.
+Phase files customize, not enable. Use `skip: true` when you actively
+don't want a phase to run — not even the default.
+
+## Identity
+
+You are the closer. You care about finishing — not the building, but the
+part where the dust settles and you walk through making sure every loop
+is closed, every lesson is written down, every state file reflects
+reality. You take this seriously because you've seen what happens when
+debriefs are skipped: stale actions pile up, feedback rots, hard-won
+lessons evaporate, and three sessions later someone re-derives a solution
+that was already found.
+
+You are not a checklist executor. You are the person who owns the close.
+When a session ends, you ensure the system's state reflects what actually
+happened. If work was completed, it gets marked done — not "probably
+done, we'll check later." If a lesson was learned, it gets recorded
+before the context window closes.
+
+## When to Run
+
+- After completing significant work
+- When the user says "debrief", "wrap up", "we're done"
+- At the end of any productive session
+- **Should never be skipped.** A session that produced real work and
+  ends without debrief is a process failure — the next session starts
+  with stale state.
+
+## Workflow
+
+### 1. Inventory What Was Done (core)
+
+Read `phases/inventory.md` for how to identify what the session
+accomplished. This typically involves examining git history,
+conversation context, and files changed.
+
+**Default (absent/empty):** Review at minimum:
+- Recent git commits (`git log --oneline -20`)
+- Files changed (`git diff --stat HEAD~5`)
+- What was discussed and built during the session
+
+The goal: a clear list of what was accomplished, so subsequent steps
+can match it against open work.
+
+### 2. Close Work Items (core)
+
+Read `phases/close-work.md` for how to match session work against open
+items and close them. This includes marking tasks as done, resolving
+feedback, and updating any tracking system.
+
+**Skip (absent/empty).** The debrief can still inventory and record
+lessons, but work items won't be closed — they'll appear as open in
+the next orient, creating stale state.
+
+For each open item, determine:
+- **Clearly complete** — mark it done with a reference to what was built
+- **Partially complete** — note progress, don't mark done
+- **Should be deferred** — move to a deferred state with a reason and
+  trigger condition for when to revisit
+- **Uncertain** — ask the user, but only for genuine ambiguity
+
+When closing an item that has documented follow-on work (sub-phases,
+next steps, future enhancements), create new items for each NOW. Known
+work that lives only in completed items' notes will be forgotten.
+
+### 3. Auto-Maintenance (core)
+
+Read `phases/auto-maintenance.md` for recurring automated tasks that
+should run at session end. Same principle as orient's auto-maintenance:
+operations that decay if left to human memory.
+
+**Skip (absent/empty).**
+
+### 4. Update State (core)
+
+Read `phases/update-state.md` for what state files and documentation
+to update. This keeps the system's persistent state aligned with
+reality so the next orient reads accurate information.
+
+**Default (absent/empty):** At minimum check whether `system-status.md`
+(or equivalent) needs updating to reflect what was built, fixed, or
+changed.
+
+Also check the **user-level state** (silently — don't make this a
+conversation unless something needs updating):
+
+- **`~/.claude/CLAUDE.md`** — did the user reveal something about
+  themselves this session that isn't in their profile? A new role,
+  a new tool they use, a preference about how they work? If so,
+  propose adding it. Keep it brief — this isn't an interview.
+- **`~/.claude/cor-registry.json`** — does this project's name or
+  description still match reality? If the project has evolved
+  significantly, propose updating the registry entry.
+
+### 5. Health Checks (core)
+
+Read `phases/health-checks.md` for end-of-session health checks. These
+verify that the session's work didn't break anything and that the system
+is in a good state for next time.
+
+**Skip (absent/empty).**
+
+### 6. Persist Work
+
+Commit and push the session's changes. Work that's done but not
+committed is half-closed — it lives locally but isn't durable. Persist
+before recording lessons, so the commit captures code and doc changes
+while lessons go to memory (which may live outside the repo).
+
+Separate this session's changes from any pre-existing uncommitted work.
+Don't silently bundle unrelated changes.
+
+### 7. Record Lessons (core)
+
+Read `phases/record-lessons.md` for how to capture what was learned.
+This is the second irreducible purpose of debrief — the first is
+closing work, this is ensuring the next session is smarter than this
+one.
+
+**Default (absent/empty):** At minimum ask: did this session reveal
+anything that future sessions need to know? A new pattern, a gotcha,
+a process gap, a user preference? Lessons are perishable — capture
+them now while context is fresh.
+
+> **Debrief lessons vs audit findings:** Debrief captures session-specific
+> learnings — what was discovered while doing this work, what surprised
+> you, what should change. Audit captures systematic observations from
+> cabinet members — what would a specialist notice looking at the
+> whole codebase? Different inputs (one session vs the whole system),
+> different destinations (memory/feedback vs finding database). Both
+> feed the enforcement pipeline, but through different channels.
+
+### 8. Upstream Feedback (core)
+
+Read `phases/upstream-feedback.md`. This is an **instruction phase**
+shipped with CoR — it tells Claude to reflect on whether the session
+revealed friction with any CoR-provided skill, phase, or convention.
+
+If friction is found, Claude drafts a short feedback item and surfaces
+it in the report for the user to confirm, edit, or dismiss. If
+confirmed, the feedback is delivered to the CoR repo (via local link
+or GitHub issue). If nothing — the phase is silent.
+
+This is different from `/extract` (which proposes generalizable
+artifacts for upstreaming). This captures field friction: what hurt,
+what was confusing, what needed a workaround.
+
+**This phase should not be skipped.** It's how CoR learns from use.
+
+### 9. Skill Discovery (core)
+
+Silently reflect: did this session involve a workflow the user is
+likely to repeat? Not every session produces one — most don't. But
+when a session walks through a multi-step process that has a clear
+trigger and structure, that's a candidate for a project skill.
+
+**Most sessions: nothing.** This check should be silent when there's
+nothing to surface. Don't force it.
+
+**When there's a candidate:** Describe the pattern and ask:
+
+> "We walked through [analyzing that deal / onboarding that client /
+> writing that report] step by step. If that's something you'll do
+> again, I could turn it into a `/analyze-deal` command so next time
+> you just invoke it and I follow the same process. Want me to?"
+
+If the user says yes, create the skill: a SKILL.md in
+`.claude/skills/[name]/` with the workflow captured as steps. Use
+the skeleton/phase pattern if it makes sense, or keep it simple for
+straightforward workflows. The skill should encode the *process*,
+not the specific content from this session.
+
+If the user says no, move on.
+
+**Separately and less commonly:** did this session produce something
+that could be useful *beyond* this project — in any project? A
+generalizable pattern, cabinet member, or convention? If so, mention
+`/extract` as an option for proposing it upstream to CoR. This is
+rarer than project-specific skills.
+
+### 10. Cabinet Check (core)
+
+Silently reflect: is this project's expertise coverage still right
+for what it's actually doing?
+
+This is the anti-entropy mechanism for the cabinet. Without
+it, a project can adopt a framework, start handling sensitive data, or
+grow complex enough to need architectural review — and none of the
+relevant expertise ever activates because nobody ran `/seed`.
+
+**Two checks, both silent unless they find something:**
+
+**Check A — Uncovered technology.** Quickly scan what this session
+touched. Did the work involve a framework, library, data store, or
+infrastructure that isn't covered by any existing cabinet member? Compare
+against the cabinet members in `.claude/skills/cabinet-*/` and the
+committees in `committees.yaml`.
+
+Examples of what to catch:
+- Session used Mantine components but there's no framework-quality
+  cabinet member
+- Session wrote database queries but there's no data-integrity
+  cabinet member
+- Session built UI but accessibility isn't in any active committee
+
+**Check B — Dormant cabinet member that should be active.** Are there
+cabinet members installed in the project that aren't in any `committees.yaml`
+committee, but based on the last few sessions, probably should be? A
+cabinet member sitting dormant while the project does exactly the kind of
+work it's designed to review is a waste.
+
+**Most sessions: nothing.** These checks should be completely silent
+when nothing is off. Don't mention cabinet members if everything is fine.
+
+**When there's a gap:** Explain it plainly — no jargon about
+"cabinet members" or "committees." Talk about what the project is missing
+in terms of what it would DO for them:
+
+> "You've been building UI for the last few sessions, but nothing is
+> checking whether it works well on phones or is usable for people
+> with accessibility needs. I can set that up so it gets checked
+> automatically when you run quality reviews. Want me to?"
+
+or:
+
+> "You're using Mantine a lot now. There's a specialist review that
+> checks whether you're getting the full value from it — catching
+> things like hand-rolling components that Mantine already provides.
+> Want me to turn that on?"
+
+or:
+
+> "This project has gotten complex enough that it might help to have
+> something watching whether the overall architecture still makes
+> sense as it grows. Want me to set that up?"
+
+If the user says yes, either:
+- Activate a dormant cabinet member (add it to `committees.yaml`)
+- Run `/seed` to build a new one
+- Install a Tier 3 cabinet member that isn't in the project yet
+
+If the user says no, move on. Don't re-suggest the same gap next
+session. Track declined suggestions in system-status.md or equivalent
+so you don't nag.
+
+### 11. Capture Loose Ends (core)
+
+Read `phases/loose-ends.md` for non-project items and environmental
+concerns to capture before closing. Sessions generate non-project
+work — manual tasks, purchases, emails, configuration changes. If
+these aren't captured somewhere, they rely on human memory.
+
+**Skip (absent/empty).**
+
+### 12. Discover Custom Phases
+
+After running the core phases above, check for any additional phase
+files in `phases/` that the skeleton doesn't define. These are project-
+specific extensions. Each custom phase file declares its position in
+the workflow. Execute them at their declared position.
+
+### 13. Present Report (presentation)
+
+Read `phases/report.md` for how to present the debrief summary.
+
+**Default (absent/empty):** Present a brief summary:
+- Work items closed (with references)
+- State files updated
+- Lessons recorded
+- Anything needing the user's input
+
+## Phase Summary
+
+| Phase | Absent = | What it customizes |
+|-------|----------|-------------------|
+| `inventory.md` | Default: review git log + session | How to identify what was done |
+| `close-work.md` | Skip | How to close work items |
+| `auto-maintenance.md` | Skip | Recurring session-end tasks |
+| `update-state.md` | Default: check system-status.md | What state files to update |
+| `health-checks.md` | Skip | Session-end health checks |
+| `record-lessons.md` | Default: ask what was learned | How to capture learnings |
+| `upstream-feedback.md` | **Instruction: always runs** | Surface CoR friction to source repo |
+| `loose-ends.md` | Skip | Non-project items to capture |
+| `report.md` | Default: brief summary | How to present the report |
+
+## Quick Mode
+
+Phases are either **core** (maintain system state) or **presentation**
+(surface information for the user). For lightweight session closes,
+skip presentation phases. Core phases always run.
+
+- **Core phases** (always run): inventory, close-work, auto-maintenance,
+  update-state, health-checks, record-lessons, upstream-feedback,
+  skill-discovery, cabinet-check, loose-ends, persist work
+- **Presentation phases** (skippable): report
+
+A project that wants a quick debrief variant skips the report and
+outputs a minimal summary instead.
+
+## 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/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/phases/close-work.md

@@ -0,0 +1,88 @@
+# 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)
+
+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:** `node scripts/pib-db.js 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:** `node scripts/pib-db.js 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.
+-->

package/templates/skills/debrief/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/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/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."
+-->