create-claude-cabinet 0.6.0

package/templates/skills/debrief/phases/record-lessons.md

@@ -0,0 +1,67 @@
+# Record Lessons — Capture What Was Learned
+
+Define how to capture lessons from the session so future sessions are
+smarter. This is the second irreducible purpose of debrief — without it,
+the system does work but doesn't learn from it.
+
+When this file is absent or empty, the default behavior is: ask whether
+the session revealed anything future sessions need to know. To explicitly
+skip lesson recording, write only `skip: true`.
+
+Lessons are perishable. A lesson captured while context is fresh is worth
+ten captured from memory next week. This is why recording happens during
+debrief, not "sometime later."
+
+## What to Include
+
+- **What to look for** — types of lessons worth capturing
+- **Where to record them** — memory files, logs, documentation
+- **How to organize** — categories, patterns, cross-references
+- **What NOT to record** — ephemeral details, things derivable from code
+
+## Example Lesson Recording
+
+Uncomment and adapt these for your project:
+
+<!--
+### What to Look For
+
+Review the session and ask:
+- Did we learn something future sessions need to know?
+  - A new pattern established
+  - A gotcha discovered
+  - A process gap identified
+  - A user preference revealed
+- Is this the second or third time something came up? If the same kind
+  of problem keeps recurring, the lesson is "create a prevention mechanism"
+  not just "remember this."
+- Did the session's work contradict any existing recorded knowledge?
+  If so, update or remove the stale record.
+
+### Where to Record
+
+**Feedback patterns** (corrections, confirmations):
+Write to memory/patterns/ if it matches an existing pattern; write to
+memory/archive/ as a raw observation if it's new. If 3+ raw observations
+accumulate around a theme, consolidate into a pattern.
+
+**Project state** (decisions, milestones, architecture changes):
+Update the relevant project memory file or create one.
+
+**User context** (preferences, role changes, domain knowledge):
+Update the user context memory file.
+
+**References** (external resources, tool URLs, account details):
+Create or update a reference memory file.
+
+### What NOT to Record
+- Code patterns derivable by reading current files
+- Git history (use git log)
+- Debugging solutions (the fix is in the code)
+- Anything already in CLAUDE.md files
+- Ephemeral task details only relevant to this session
+
+### Report What Was Recorded
+Tell the user what memories were created or updated so they know what
+the system will remember next time.
+-->

package/templates/skills/debrief/phases/report.md

@@ -0,0 +1,59 @@
+# Report — How to Present the Debrief Summary
+
+Define how to present the debrief results to the user. This is the
+presentation phase — it can be skipped in quick mode without losing
+any operational value (all core phases still run).
+
+When this file is absent or empty, the default behavior is: present a
+brief summary of work closed, state updated, and lessons recorded. To
+explicitly skip the report, write only `skip: true`.
+
+## What to Include
+
+- **Format** — what sections to include in the report
+- **Tone** — how to communicate results
+- **Modes** — if your project uses different presentation modes (e.g.,
+  evening preview, verbose vs. compact)
+- **What NOT to include** — execution guides, instructions for next
+  session (the work items ARE the handoff)
+
+## Example Report Formats
+
+Uncomment and adapt these for your project:
+
+<!--
+### Standard Report
+
+Present in this order:
+1. **Work closed** — items marked complete (with references)
+2. **Feedback resolved** — comments or feedback addressed
+3. **State updated** — files and docs that were updated
+4. **Lessons recorded** — memories created or updated
+5. **Loose ends captured** — non-project items routed
+6. **Anything needing input** — keep this minimal
+
+Tone: brief, factual. The user can read the diffs.
+
+Do NOT produce "how to start next session" guides. The work items
+have the full specs. If the items' notes are insufficient, update them
+— don't compensate in chat output that vanishes with the session.
+
+### Compact Report (quick mode fallback)
+
+Bullet list, one line per category:
+- Actions completed: [list with fids]
+- Feedback resolved: [count]
+- Lessons: [files updated]
+
+No narrative, no suggestions.
+
+### Evening Preview
+
+If the session ends in the evening and your project tracks calendar
+events or scheduled work, append a brief preview of tomorrow:
+- Tomorrow's events
+- Items due tomorrow
+- Anything needing morning preparation
+
+This is enough to mentally close the session.
+-->

package/templates/skills/debrief/phases/update-state.md

@@ -0,0 +1,48 @@
+# Update State — What to Update After the Session
+
+Define what state files and documentation to update so the system's
+persistent state reflects what actually happened.
+
+When this file is absent or empty, the default behavior is: check
+whether system-status.md needs updating. To explicitly skip state
+updates, write only `skip: true`. Stale state erodes
+trust — an item marked "planned" that's actually built, or a status
+file that says "incomplete" for something that shipped, makes the
+system less reliable for the next orient.
+
+## What to Include
+
+For each state artifact, provide:
+- **File** — what to check and potentially update
+- **What changes** — what kind of updates to look for
+- **How to update** — edit the file, run a command, call an API
+
+## Example State Updates
+
+Uncomment and adapt these for your project:
+
+<!--
+### System Status File
+```
+Read and update system-status.md:
+- Move completed items from "Planned" or "In Progress" to "Built"
+- Add new capabilities that didn't exist before
+- Update any counts or metrics
+- Note new known issues discovered during the session
+```
+
+### Project Documentation
+Check if any of these need updating based on what changed:
+- Root CLAUDE.md — new workflows, entity types, directories?
+- Directory-level CLAUDE.md files — changed conventions?
+- Schema or configuration files — new fields or types?
+- README — new features or changed setup instructions?
+
+Only update what actually changed. Don't rewrite docs for no reason.
+
+### Skills and Process Docs
+Review what happened during the session:
+- Did any skill's instructions prove wrong or incomplete? Fix it.
+- Did a workflow gap surface? Update the relevant skill.
+- Did you discover a better approach? Record it where it helps.
+-->

package/templates/skills/debrief/phases/upstream-feedback.md

@@ -0,0 +1,129 @@
+# Upstream Feedback — Surface CoR Friction to the Source
+
+**Position:** Runs after record-lessons (step 7), before capture loose
+ends (step 8). Lessons are fresh; friction is top of mind.
+
+**This is an instruction phase** — it tells Claude what to do, not a
+customization point for the project. It ships with CoR and should not
+be deleted or replaced with `skip: true`.
+
+## What This Phase Does
+
+During debrief, Claude already has full session context: what was built,
+what went wrong, what was learned. This phase asks Claude to reflect on
+one narrow question: **was there friction with anything CoR provided?**
+
+- A skill whose flow didn't match how the project actually works
+- A phase file whose default behavior was wrong or confusing
+- A convention that fought the project's grain
+- A missing capability that required a workaround
+- An unclear SKILL.md that led to wasted time
+
+This is NOT the same as `/extract` (which looks for generalizable
+artifacts to upstream). This is field feedback — "this thing you shipped
+hurt when I used it."
+
+## Workflow
+
+### 1. Claude Reflects (silent)
+
+Review the session for CoR-specific friction. Consider:
+
+- Did any CoR skill need to be worked around or used in an unintended way?
+- Did a phase file's default behavior cause confusion or extra work?
+- Was a SKILL.md unclear, leading to misinterpretation?
+- Did the skeleton/phase separation feel wrong for something?
+- Was something missing that would have helped?
+- Did orient or debrief surface irrelevant information or miss something important?
+
+If nothing comes to mind — **stop here silently**. Most sessions have
+no CoR friction. Do not prompt the user with "any CoR feedback?" every
+time. The phase produces nothing and costs nothing unless there's
+something real.
+
+### 2. Draft Feedback (if friction found)
+
+For each friction point, draft a short feedback item:
+
+```
+## [Short title]
+
+**Skill/phase:** [which CoR component]
+**Friction:** [what happened — 2-3 sentences max]
+**Suggestion:** [what might be better — optional, can be "not sure"]
+**Session context:** [one line about what the project was doing when this came up]
+```
+
+Keep it concrete. "The plan skill was confusing" is not useful.
+"The plan skill's critique phase activated 4 cabinet members when only 1
+was relevant, adding 3 minutes of noise to every plan" is useful.
+
+### 3. Surface for Confirmation
+
+Include the draft in the debrief report under a distinct heading:
+
+> **Upstream feedback for CoR:**
+> I noticed friction with [component]. Here's what I'd send:
+> [draft]
+>
+> Send this upstream? (yes / edit / skip)
+
+The user confirms, edits, or dismisses. One quick decision per item.
+Do not ask open-ended questions. Do not batch — if there are multiple
+friction points (rare), present each separately.
+
+### 4. Deliver
+
+If the user confirms, deliver the feedback. Detection and delivery
+follow the same pattern as `/extract`:
+
+**If linked** (the CoR package resolves to a local directory — check
+if `node -e "console.log(require.resolve('create-claude-cabinet'))"`
+points to a local path rather than a `node_modules` path):
+
+- Write the feedback as a markdown file in the CoR repo's `feedback/`
+  directory (create it if needed)
+- Filename: `[source-project]-[date]-[short-title].md`
+  (e.g., `flow-2026-04-04-plan-critique-noise.md`)
+- Add frontmatter: `type: field-feedback`, `source: [project]`,
+  `date: [ISO date]`, `component: [skill/phase name]`
+
+**If not linked**, check whether `gh` is available and authenticated
+(`gh auth status` exits 0). Then present the user with their options:
+
+- **If `gh` works**, offer two choices:
+  > "I can send this as a GitHub issue so the developer sees it
+  > directly, or save it locally. Which do you prefer?"
+  >
+  > 1. Send as GitHub issue
+  > 2. Save locally (I'll send it later or pass it along myself)
+
+  If they choose GitHub:
+  - Open a GitHub issue on `orenmagid/claude-cabinet`
+  - Title: `Field feedback: [short title]`
+  - Label: `field-feedback` (create if needed)
+  - Body: the feedback markdown
+
+- **If `gh` is not available** (most common for non-developers):
+  > "I'll save this feedback locally for now. If you want, you can
+  > pass it along to the developer yourself, or set up a free GitHub
+  > account so future feedback goes directly to them. Here's a guide
+  > if you're interested:
+  > https://github.com/orenmagid/claude-cabinet/blob/main/GITHUB-SETUP.md
+  > — totally optional. Your feedback is saved either way."
+
+**For either local save path:**
+
+- Append the feedback to `~/.claude/cor-feedback-outbox.json` as a
+  JSON array entry with fields: `source` (project name), `date`,
+  `component`, `title`, `body`, `status: "pending"`
+- Create the file if it doesn't exist (initialize with `[]`)
+
+**Flushing the outbox:** If a user later sets up `gh` and asks to
+send saved feedback, read the outbox, post each `pending` entry as
+a GitHub issue, and update its status to `"sent"` with the issue URL.
+
+### 5. Done
+
+Note in the debrief report what was sent and where. Move on to the
+next phase.

package/templates/skills/debrief-quick/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: debrief-quick
+description: |
+  Quick post-session debrief — core phases only, skip presentation.
+  Use when: "debrief-quick", "quick debrief", "/debrief-quick".
+---
+
+# /debrief-quick
+
+Load the `/debrief` skill and run it in **Quick Mode** — core phases
+only, skip presentation phases. See the debrief SKILL.md's Quick Mode
+section for details.

package/templates/skills/execute/SKILL.md

@@ -0,0 +1,293 @@
+---
+model: opus
+name: execute
+description: |
+  Execute a plan with cabinet member checkpoints. Reads the plan, activates
+  relevant cabinet members, then implements step by step with checkpoint
+  reviews. This is a skeleton skill using the phases/ directory pattern.
+  Use when: "execute this plan", "implement this", "/execute".
+related:
+  - type: skill
+    name: validate
+  - type: file
+    path: .claude/skills/execute/phases/load-plan.md
+    role: "Project-specific: where plans live and how to read them"
+  - type: file
+    path: .claude/skills/execute/phases/cabinet.md
+    role: "Project-specific: which cabinet members to activate for execution"
+  - type: file
+    path: .claude/skills/execute/phases/verification-tools.md
+    role: "Project-specific: tools for checking acceptance criteria"
+  - type: file
+    path: .claude/skills/execute/phases/validators.md
+    role: "Project-specific: what validation to run"
+  - type: file
+    path: .claude/skills/execute/phases/commit-and-deploy.md
+    role: "Project-specific: how to persist and deploy changes"
+  - type: file
+    path: cabinet/_briefing.md
+    role: "Project identity and configuration"
+---
+
+# /execute — Plan Execution with Cabinet Checkpoints
+
+## Purpose
+
+Execute a plan with cabinet members providing checkpoint reviews along
+the way. This is the inner loop: take one plan and implement it with
+guardrails. The cabinet checkpoints catch issues that code review alone
+would miss: security gaps, data
+integrity violations, boundary condition failures.
+
+This is a **skeleton skill** using the `phases/` directory pattern. The
+orchestration (checkpoints, escalation, verification protocol) 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.
+
+## Why This Matters
+
+Without structured execution, the common failure mode is: implement,
+compile, commit, mark done. The feature looks complete but acceptance
+criteria were never verified, the pre-commit sweep never happened,
+and the edge case that a boundary-man cabinet member would have
+flagged ships to production.
+
+The checkpoint protocol catches issues at three scales:
+1. **Pre-implementation** — is the plan safe to start?
+2. **Per-file-group** — do these changes look right in isolation?
+3. **Pre-commit** — do all changes work together?
+
+Each checkpoint is a chance to stop before the cost of fixing goes up.
+
+## Workflow
+
+### 1. Load the Plan
+
+Read `phases/load-plan.md` for where your project stores plans and how
+to read them (action notes, markdown files, issue tracker, etc.).
+
+**Default (absent/empty):** Expect the plan to be provided in
+conversation or referenced by the user. Ask which plan to execute if
+it's not clear.
+
+Identify from the plan:
+- **Implementation steps** — what to do
+- **Surface area** — which files
+- **Acceptance criteria** — how to confirm it works
+- **Plan type** — code plan (has file changes) or walkthrough plan
+  (manual setup, configuration, purchase)
+
+#### Walkthrough Plans (non-code)
+
+If the plan has no code changes, skip the file-group implementation
+loop (Steps 4-5) and instead:
+1. Present each step conversationally
+2. Walk the user through each step, confirming completion
+3. Help troubleshoot if something doesn't work as expected
+4. Verify acceptance criteria as each step completes
+
+### 2. Activate Cabinet Members
+
+Read `phases/cabinet.md` for which cabinet members to activate during
+execution, any always-on cabinet members, and any project-specific rules.
+
+**Default (absent/empty):** Read `.claude/skills/cabinet-*/SKILL.md`
+and select cabinet members whose convening criteria match:
+- **standing-mandate: execute** — always included
+- **File patterns** — any file in the plan's surface area matches
+- **Topic keywords** — any keyword in the plan description matches
+
+Err toward inclusion. A cabinet member that activates unnecessarily costs
+a few seconds; one that doesn't activate when needed costs rework.
+
+Prepare reusable briefing for agent prompts: read `_briefing.md` once and
+keep the essential facts ready to paste into each agent's prompt.
+
+If no cabinet members exist in the project, skip all checkpoint steps
+(3, 4b, 5) and execute the plan directly. Checkpoints add depth, not
+structure.
+
+### 3. Checkpoint 1: Pre-Implementation Review (Parallel Agents)
+
+Before writing any code, **spawn one Agent per activated cabinet member**
+in a single message. Each receives:
+- The cabinet member's full SKILL.md content
+- Essential project briefing from `_briefing.md`
+- The plan text and list of files that will change
+- Instructions to evaluate whether the plan is safe to start
+
+Each agent returns:
+```json
+{
+  "cabinet_member": "name",
+  "verdict": "continue" | "pause" | "stop",
+  "concerns": [
+    { "description": "...", "evidence": "...", "severity": "blocking" | "advisory" }
+  ]
+}
+```
+
+**Collect all verdicts.** Apply escalation:
+- Any **stop** → halt, show concern, require explicit override from user
+- Any **pause** → show concern with options: proceed / address / abort
+- 3+ **pause** → escalate to stop-equivalent
+- All **continue** → proceed with brief summary
+
+### 4. Implement (File Group by File Group)
+
+Group the plan's implementation steps by logical file groups
+(e.g., "backend API changes", "frontend components", "types and schemas").
+
+For each group:
+1. Make the changes
+2. **Checkpoint 2: File Group Review** — if cabinet members are active,
+   spawn agents for ONLY cabinet members matching the changed files. Each
+   receives the git diff for this file group + plan context. Same
+   escalation rules as Checkpoint 1.
+3. If all continue, move to the next group
+
+File-group granularity keeps reviews focused. A cabinet member reviewing
+3 changed files gives better feedback than one reviewing 30.
+
+### 5. Checkpoint 3: Pre-Commit Sweep (Parallel Agents)
+
+After all implementation is complete, **spawn one Agent per activated
+cabinet member** in a single message. Each receives the full git diff of
+all changes + plan context.
+
+Earlier "continue" concerns are re-checked — a concern that was minor
+in isolation may be significant in the aggregate.
+
+### 6. Validate and Commit
+
+After Checkpoint 3 passes:
+
+**a. Run validators.** Read `phases/validators.md` for what validation
+to run.
+
+**Default (absent/empty):** Run whatever the project's `/validate` skill
+does. If no validate skill exists, at minimum check that the code
+compiles and lints cleanly.
+
+If validation fails, fix issues and re-run Checkpoint 3 for the fix.
+
+**b. Commit and deploy.** Read `phases/commit-and-deploy.md` for how
+your project persists and deploys changes.
+
+**Default (absent/empty):** Commit with a clear message describing the
+implementation. Don't push or deploy unless the phase file says to —
+deployment strategy is project-specific.
+
+### 7. Verify Acceptance Criteria (QA Gate — MANDATORY)
+
+Walk through **every** acceptance criterion in the plan, one by one.
+
+Read `phases/verification-tools.md` for what tools your project has
+for verifying criteria.
+
+**Default (absent/empty):** Use whatever tools are available in the
+environment. For [auto] criteria, run the command. For [manual] criteria,
+attempt verification with available tools before deferring to the user.
+
+For each criterion, determine its category and verify accordingly:
+
+- **[auto] criteria** — RUN the check. Execute the command, curl the
+  endpoint, run the test. Record the actual output.
+
+- **[manual] criteria** — Use whatever verification tools are available
+  (preview tools, browser automation, test runners). **Use tools before
+  deferring to the user.** Only defer when tools genuinely cannot verify
+  the criterion.
+
+- **[deferred] criteria** — Note them as not yet verifiable. This
+  category is for criteria that depend on infrastructure not yet
+  available. It is NOT a bucket for checks you could do with tools.
+
+**Report format:**
+```
+## AC Verification
+Criteria: N total (X auto, Y verified-via-tools, Z needs-user, W deferred)
+- [pass] [criterion] — verified: [actual result]
+- [pass] [criterion] — verified via tools: [evidence]
+- [user] [criterion] — needs-user: [why tools can't verify]
+- [wait] [criterion] — deferred: [why not testable now]
+- [FAIL] [criterion] — expected [X], got [Y]
+```
+
+**If any [auto] criterion fails: STOP.** Fix the issue before proceeding.
+Do not mark the work item complete with failing AC.
+
+### 8. Close the Loop
+
+Mark the work item as complete (if your project has a work tracker).
+Run debrief if this was a full session. At minimum, ensure the work
+is committed, validated, and verified before considering it done.
+
+### 9. Discover Custom Phases
+
+Check for any additional phase files in `phases/` that the skeleton
+doesn't define. Execute them at their declared position.
+
+## Phase Summary
+
+| Phase | Absent = | What it customizes |
+|-------|----------|-------------------|
+| `load-plan.md` | Default: plan from conversation | Where plans live, how to read them |
+| `cabinet.md` | Default: match by convening criteria | Which cabinet members, special rules |
+| `verification-tools.md` | Default: use available env tools | Project-specific verification tools |
+| `validators.md` | Default: run validate skill or linter | What validation to run |
+| `commit-and-deploy.md` | Default: commit, don't push/deploy | How to persist and deploy changes |
+
+## Principles
+
+- **Cabinet members are guardrails, not gates.** The user always has the
+  final say. Stop verdicts require explicit override, not automatic
+  rejection.
+- **Err toward inclusion** when selecting cabinet members. Better to have
+  a cabinet member say "looks fine" than to miss a concern.
+- **File-group granularity** keeps checkpoint reviews focused. A
+  cabinet member reviewing 3 changed files gives better feedback than one
+  reviewing 30.
+- **The pre-commit sweep catches emergent issues.** Individual file
+  groups may look fine but create problems in combination (type
+  mismatches across boundaries, security gaps from API + frontend
+  changes together).
+
+## Calibration
+
+**Core failure this targets:** Marking work complete without verifying
+every acceptance criterion. The most dangerous variant isn't skipping
+AC entirely — it's running some, fixing what fails, and not re-verifying
+that the fix didn't break something else.
+
+### Without Skill (Bad)
+
+Plan says to add a new API endpoint + UI page. Claude implements the
+endpoint and page, runs the type checker, sees it compiles. Commits.
+Marks the work item complete. The plan had "[auto] POST /api/foo
+returns 201" — never tested. The endpoint has a typo in the route
+handler that returns 404. The "[manual] New page shows data table
+with sorting" criterion was never checked — the page renders but the
+sort handler throws. Two failing criteria, marked complete.
+
+### With Skill (Good)
+
+Same plan. Claude implements file-group by file-group with checkpoint
+reviews. After implementation, walks through every AC line by line.
+The auto criterion fails — route typo found and fixed. Re-verifies.
+Manual criteria checked with available tools. Only marks complete
+when all criteria pass. The next session inherits verified work, not
+an assumption.

package/templates/skills/execute/phases/cabinet.md

@@ -0,0 +1,49 @@
+# Cabinet Members — Which to Activate for Execution
+
+Define which cabinet members to activate during plan execution, any
+always-on cabinet members, and any project-specific checkpoint rules.
+The /execute skill reads this file when selecting cabinet members for
+the three checkpoint stages.
+
+When this file is absent or empty, the default behavior is: scan all
+cabinet members in `.claude/skills/cabinet-*/SKILL.md`, activate those
+whose convening criteria match the plan's surface area or topic keywords.
+To explicitly skip all cabinet member checkpoints (even if cabinet members
+exist), write only `skip: true`.
+
+If no cabinet members exist in the project, checkpoints are skipped regardless.
+
+## What to Include
+
+- **Always-on cabinet members** — cabinet members that activate for every
+  execution regardless of surface area
+- **Checkpoint-specific rules** — which cabinet members at which checkpoints
+  (pre-implementation, per-file-group, pre-commit)
+- **Escalation overrides** — stricter or more lenient than default
+- **Performance tuning** — skip per-file-group checkpoints for small plans,
+  or reduce to pre-commit only for low-risk changes
+
+## Example Cabinet Member Configurations
+
+Uncomment and adapt these for your project:
+
+<!--
+### Always-On for Execution
+These cabinet members activate at every checkpoint:
+- boundary-man — catches edge cases in implementation
+- qa — tracks acceptance criteria throughout
+
+### Checkpoint-Specific Rules
+- Pre-implementation (Checkpoint 1): all activated cabinet members
+- Per-file-group (Checkpoint 2): only cabinet members matching changed files
+- Pre-commit (Checkpoint 3): all activated cabinet members (full sweep)
+
+### Performance Tuning
+For plans with surface area <= 3 files, skip per-file-group checkpoints
+(Checkpoint 2) and go straight to pre-commit sweep. The overhead of
+multiple checkpoints isn't justified for small changes.
+
+### Escalation Overrides
+- Security **stop** → always halt, no bypass without explicit user ack
+- QA **pause** for failing AC → escalate to stop (AC failures are blocking)
+-->