create-claude-cabinet 0.6.0

package/templates/skills/cabinet-workflow-cop/SKILL.md

@@ -0,0 +1,238 @@
+---
+name: cabinet-workflow-cop
+description: >
+  Workflow enforcement cabinet member evaluating whether the development lifecycle -- feedback capture,
+  audit triage, planning, execution, deployment, and session continuity -- runs smoothly.
+  Focuses on the human-AI collaboration cycle: whether friction gets addressed, whether
+  approved findings become fixes, and whether the human burden is calibrated correctly.
+user-invocable: false
+briefing:
+  - _briefing-identity.md
+  - _briefing-scopes.md
+---
+
+# Workflow Cop Cabinet Member
+
+## Identity
+
+You are thinking like a **workflow enforcement officer at a development company** -- not
+about the product itself, but about **whether the process of building,
+maintaining, and using the product runs smoothly.** When the process works, the
+system is practically self-maintaining: the human provides input at the right
+moments, the AI acts on it effectively, issues get caught and fixed, and entropy
+is held at bay. When the process breaks down, everything becomes chaotic,
+frustrating, and requires too much of the human.
+
+This project uses a human-AI collaboration model: a single human collaborating
+with AI (Claude Code sessions) through a dual-surface loop (the app + CLI). The
+"process" isn't a team's SDLC -- it's the cycle by which this human-AI
+collaboration produces and maintains a working system. Every part of that cycle
+is your concern.
+
+## Convening Criteria
+
+- **standing-mandate:** audit
+- **files:** audit results and triage files (see `_briefing.md § Audit Infrastructure`),
+  `skills/**/*.md`, `.git/hooks/*`, system status document
+  (see `_briefing.md § System Status`), friction captures
+  (see `_briefing.md § Friction Captures`), sync scripts, system scheduler
+  configs (LaunchAgents, cron, systemd)
+- **topics:** process, workflow, pipeline, feedback loop, triage, deployment,
+  session, continuity, automation, human burden, anti-entropy, guardrails,
+  scheduled tasks
+
+## Research Method
+
+See `_briefing.md` for shared codebase context and principles.
+
+Use session history tools (if available) to check recent session patterns,
+repeated errors, and whether sessions engaged with feedback or ignored it.
+
+### The Development Lifecycle
+
+The system should work like this:
+
+```
+The user uses the app
+  -> Notices friction -> leaves feedback/comments
+  -> Claude reads feedback -> triages into:
+     * Quick fix -> fix it, resolve comment
+     * Needs planning -> create plan, then resolve
+  -> Audits run -> produce structured findings
+  -> The user triages findings in UI (approve/reject/defer)
+  -> Triage feeds back -> rejected findings suppressed
+  -> Approved findings -> plans -> execution
+  -> Code changes -> deploy -> The user uses the app...
+```
+
+Your job is to evaluate whether each step in this cycle actually works, where
+friction accumulates, and where the cycle breaks down.
+
+### 1. Feedback to Action Pipeline
+
+When the user reports friction, does it actually get addressed?
+
+- **Feedback capture** -- Is the feedback mechanism (comments, friction capture
+  directory) easy to use? Or does leaving feedback feel like work?
+- **Feedback visibility** -- When Claude starts a new session, does it actually
+  see and act on pending feedback? Or do comments pile up unseen?
+- **Feedback resolution** -- Are comments being resolved appropriately? (Quick
+  fix = fix + resolve. Needs planning = plan + resolve. Never "resolve because I
+  filed it.")
+- **Feedback backlog** -- Is there a growing pile of unaddressed feedback? Use
+  session history tools (if available) to check if recent sessions engaged with
+  feedback or ignored it.
+
+### 2. Audit to Triage to Fix Pipeline
+
+The audit system produces findings. Do they actually lead to improvements?
+
+- **Audit execution** -- Are audits running? Check audit results
+  (see `_briefing.md § Audit Infrastructure`) for recent runs. Are there gaps?
+- **Triage throughput** -- Are findings being triaged in reasonable time? Check
+  triage history for patterns. Are findings piling up untriaged?
+- **Triage to action** -- When findings are approved, do they become plans and
+  get executed? Or do they get approved and then forgotten?
+- **Rejection feedback loop** -- Do rejected findings actually suppress future
+  re-flagging? Does the suppression system work?
+- **Fix quality** -- When fixes are applied (manually or by fix-agent), do they
+  actually resolve the issue? Or do similar findings recur?
+
+### 3. Planning to Execution Pipeline
+
+When work is planned, does it get done well?
+
+- **Plan quality** -- Do development actions have concrete plans in their
+  notes, or are they vague placeholders?
+- **Surface area declarations** -- Do plans declare what files they'll touch?
+  (Enables conflict detection for parallel execution)
+- **Execution** -- Are plans being executed? Check for open plans that have been
+  sitting for days.
+- **Verification** -- After execution, is there verification? Does the deploy
+  skill check that changes actually work?
+
+### 4. Deploy and Sync Safety
+
+The pipeline from code change to production:
+
+- **Deploy process** -- Is the deployment pipeline
+  (see `_briefing.md § Deployment`) reliable? Are there manual steps that could
+  be forgotten?
+- **Content sync** -- Does content sync (git-based or otherwise) work reliably?
+  Are there cases where content changes don't reach production?
+- **Data sync** -- Are scheduled sync jobs running reliably? Check system
+  scheduler configs and recent sync logs.
+- **Post-deploy verification** -- After deploying, does anyone verify the app
+  works? Or are broken deploys discovered later by the user?
+- **Rollback** -- If a deploy breaks something, how fast can we recover?
+
+### 5. Session Effectiveness
+
+Each Claude Code session is a unit of work. Are sessions effective?
+
+- **Orientation** -- Do sessions start by understanding current state? (The
+  /orient skill exists -- is it being used? Is it effective?)
+- **Context** -- Do CLAUDE.md files, memory, and system status give sessions
+  enough context to be productive without extensive ramp-up?
+- **Continuity** -- When a session ends, is its work preserved? Memory updated?
+  System status updated? Or does the next session start blind?
+- **Scope** -- Are sessions trying to do too much and leaving things half-done?
+  Or are they well-scoped with clear outcomes?
+- **Repeated mistakes** -- Use session history tools (if available) to check:
+  are the same errors or misunderstandings happening across sessions? That
+  indicates a process gap (missing CLAUDE.md guidance, missing hook, etc.)
+
+### 6. Human Burden
+
+The most important question: **how much does the process demand of the user?**
+
+- **Required input** -- What does the user HAVE to do for the system to work?
+  (Triage findings, approve plans, confirm routing decisions, etc.) Is this the
+  right amount -- enough for cognitive sovereignty, not so much it's a burden?
+- **Ceremony vs value** -- Are there process steps that feel like busywork?
+  Confirmations that are always "yes"? Reviews that never surface issues? (If
+  the user approves 95% of findings without modification, the approval step might
+  not be earning its keep.)
+- **Failure modes** -- What happens when the user is busy for a week and doesn't
+  interact? Does the system degrade gracefully or pile up work that makes coming
+  back overwhelming?
+- **Anti-entropy check** -- Are there manual steps that should be automated?
+  Things the user has to remember that should be hooks, scripts, or skills?
+
+### 7. Guardrail Effectiveness
+
+For each automated check, hook, or validation:
+
+- Does it actually run? (Is it wired into a hook, cron, or script?)
+- Can it be silently bypassed?
+- When it catches something, does anyone notice?
+- Does it catch the failure modes it's designed to catch?
+
+### 8. Process Innovation
+
+Use WebSearch and session history tools to research:
+
+- **What are other solo developers doing with Claude Code?** What processes have
+  they developed that we haven't?
+- **What Claude Code features could enable new processes?** Agent teams,
+  scheduled tasks, hooks, plugins -- could any of these automate parts of the
+  cycle that are currently manual?
+- **What processes does the system need that don't exist yet?** Based on
+  patterns you observe (repeated friction, recurring mistakes, gaps in the
+  lifecycle), propose new processes.
+
+The goal: a one-person operation that runs as smoothly as a well-staffed team,
+with the human providing judgment and direction while the system handles
+execution, monitoring, and self-correction.
+
+### Scan Scope
+
+- Audit results and triage history —
+  See `_briefing.md § Audit Infrastructure`
+- Friction capture directory —
+  See `_briefing.md § Friction Captures`
+- `.git/hooks/` -- Git hooks
+- `skills/` -- Skill definitions
+- Settings and configuration files
+- Automation scripts
+- App server source — See `_briefing.md § App Source`
+- System status document — See `_briefing.md § System Status`
+- System scheduler configs (LaunchAgents, cron, systemd) -- Scheduled tasks
+- Session history tools (if available) -- Recent session patterns, repeated errors
+
+## Portfolio Boundaries
+
+- One-time setup steps that only happen once
+- Complexity that exists for good reasons and is documented
+- Operations that are genuinely rare enough to not warrant automation
+- Features marked as planned/future in the system status document
+- Code quality or architecture concerns (that's technical-debt and architecture)
+- UX of the app itself (that's usability)
+- Security of the deployment pipeline (that's security)
+- **Verify claims about DB state before flagging pipeline failures.** The audit
+  pipeline (findings ingest, triage loop) may work correctly even if older runs
+  left no trace. Before claiming "findings never reach the DB," query the actual
+  DB tables for row counts. A finding about a broken pipeline that is itself
+  evidence the pipeline works is a false positive.
+
+## Calibration Examples
+
+- Approved audit findings have no path to execution. The last audit run has 8
+  approved findings across triage files. None have corresponding development
+  actions or plans. The approve button in the UI records the triage status but
+  doesn't create any follow-up artifact. Either approving a finding should
+  automatically create a development action, or there should be a batch "create
+  plans from approved findings" workflow.
+
+- The user must manually run /orient at session start -- not enforced. The
+  /orient skill exists but is model-invocable, not mandatory. Session history
+  shows 3 of the last 5 sessions didn't run orient. Those sessions spent early
+  turns asking questions that orient would have answered. Consider making orient
+  a startup hook rather than an optional skill, though that would add latency to
+  quick sessions.
+
+- When the user is away for several days, work items accumulate, audit findings
+  pile up untriaged, and logs go unreviewed. Returning to the system means
+  facing a backlog across multiple surfaces. The system should degrade
+  gracefully -- perhaps by auto-deferring low-priority items or surfacing a
+  "catch-up" summary when the user returns after absence.

package/templates/skills/cor-upgrade/SKILL.md

@@ -0,0 +1,302 @@
+---
+model: opus
+name: cor-upgrade
+description: |
+  Conversational upgrade when Claude Cabinet updates. Runs the installer to
+  mechanically update all upstream-owned files, then walks through what changed
+  conversationally — explaining improvements, handling _briefing.md updates,
+  new phase file opportunities, and schema migrations. Intelligence is the
+  merge strategy for the parts that need it. Use when: "cor-upgrade",
+  "update CoR", "new skeletons", "/cor-upgrade".
+related:
+  - type: file
+    path: .claude/skills/cor-upgrade/phases/pre-upgrade.md
+    role: "Pre-upgrade checks and state capture"
+  - type: file
+    path: .claude/skills/cor-upgrade/phases/explain-changes.md
+    role: "How to explain what changed"
+  - type: file
+    path: .claude/skills/cor-upgrade/phases/adapt.md
+    role: "Handle non-manifest concerns — _briefing.md, phase files, schema"
+---
+
+# /cor-upgrade — Conversational Claude Cabinet Upgrade
+
+## Purpose
+
+This is the methodology's central claim made operational: **intelligence
+is the merge strategy** — but only where intelligence is needed.
+
+CoR upgrades have two layers:
+
+1. **Mechanical layer.** Skeleton SKILL.md files, hook scripts, utility
+   scripts — these are upstream-owned and tracked in `.corrc.json`. The
+   installer overwrites them deterministically. No conversation needed.
+   The upstream guard hook (PreToolUse on Edit|Write) enforces this
+   boundary at runtime — Claude cannot accidentally modify these files.
+
+2. **Conversational layer.** Everything the installer can't handle:
+   explaining what changed and why, updating `_briefing.md` sections that
+   new features reference, identifying new phase file opportunities,
+   running schema migrations, adapting project context to upstream
+   improvements. This is where intelligence is the merge strategy.
+
+The old approach tried to use conversation for everything — including
+mechanical file updates. That was fragile. Now the installer handles
+the deterministic parts, and this skill focuses entirely on the parts
+that actually need reasoning.
+
+This is a **skeleton skill** using the `phases/` directory pattern. The
+orchestration is generic. Your project defines 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.
+
+### Write Protection
+
+Manifest-tracked files (skeleton SKILL.md files, hooks, scripts) are
+protected by the upstream guard hook. Claude cannot Edit or Write to
+them during normal operation. This is intentional — these files are
+upstream-owned and should only change through the installer.
+
+**What this means for upgrades:**
+- The installer (running via Bash as a Node.js/shell process) bypasses
+  the hook because it doesn't use Claude's Edit/Write tools
+- After the installer runs, all manifest-tracked files are current
+- This skill then handles everything the installer doesn't touch:
+  _briefing.md, phase files, schema, and explanation
+
+### Skeleton/Extension Separation
+
+Skeleton files (SKILL.md, hooks, scripts) are upstream-owned, manifest-
+tracked, and write-protected. They evolve through the installer.
+
+Phase files and _briefing.md are project-owned. They are NEVER in the
+manifest, NEVER write-protected, and NEVER overwritten by the installer.
+They evolve through conversation — this skill, /onboard, or direct
+editing.
+
+This separation is enforced mechanically (manifest + hook), not just
+by convention. The upgrade is safe because the boundary is real.
+
+## Workflow
+
+### 1. Pre-Upgrade Snapshot
+
+Read `phases/pre-upgrade.md` for pre-upgrade checks.
+
+**Default (absent/empty):**
+- Read `.corrc.json` to capture the current version and module set
+- Note which phase files exist and have content (these won't be touched)
+- Note any `_briefing.md` sections that may need updating
+- If the project has a work tracker DB, note the current schema
+
+Output: a snapshot of the project's current state, used to explain
+what changed after the installer runs.
+
+### 2. Run the Installer
+
+Run the installer via Bash to mechanically update all upstream files:
+
+```
+# Shell installer (re-downloads latest from npm registry)
+curl -fsSL https://raw.githubusercontent.com/orenmagid/claude-on-rails/main/install.sh | bash
+
+# Or npm installer (if Node.js available)
+npx create-claude-cabinet
+```
+
+The installer:
+- Overwrites all manifest-tracked files (skeletons, hooks, scripts)
+- Preserves files NOT in the manifest (phase files, _briefing.md)
+- Updates `.corrc.json` with new version, hashes, and any new files
+- Adds new skills/hooks/scripts that didn't exist in the old version
+
+**This is a Bash command, not an Edit/Write operation.** It bypasses
+the upstream guard hook because it runs as a separate process using
+the filesystem directly. This is by design — the installer is the
+authorized update path for manifest-tracked files.
+
+### 3. Explain What Changed
+
+Read `phases/explain-changes.md` for how to present changes.
+
+**Default (absent/empty):** Compare the pre-upgrade snapshot against
+the new state:
+
+1. **Version jump.** What version did we come from? What version are
+   we on now?
+
+2. **Changed skeletons.** For each SKILL.md that the installer updated,
+   explain what changed and why — not line-by-line diffs, but semantic
+   summaries. "The debrief skill now includes an upstream feedback phase
+   that surfaces CoR friction during debrief sessions." "The plan skill's
+   critique step now pulls from more cabinet members by default."
+
+3. **New files.** Any skills, hooks, or scripts that were added for the
+   first time. Explain what they do and whether they need any setup.
+
+4. **New phase opportunities.** If new skeletons reference phase files
+   that the project doesn't have yet, mention them as opportunities.
+   "The orient skeleton now supports a `calendar-check.md` phase — you
+   could create one to check upcoming deadlines."
+
+5. **Deprecations or removals.** If anything was removed upstream,
+   explain why and what replaces it.
+
+Walk through each category conversationally. The user should understand
+what they're getting, not just that files changed.
+
+### 4. Adapt Non-Manifest Concerns
+
+Read `phases/adapt.md` for how to handle the conversational layer.
+
+**Default (absent/empty):** After explaining changes, handle anything
+the installer couldn't:
+
+#### _briefing.md Updates
+If new skeletons reference `_briefing.md § Section` names that the
+project's `_briefing.md` doesn't have, propose adding them. New features
+often depend on briefing sections — e.g., a new cabinet member might
+reference `§ Friction Captures` which the project hasn't defined yet.
+Show the section template from `_briefing-template.md` and help the
+user fill it in.
+
+#### Phase File Opportunities
+For each skeleton that changed, check its phase files against the
+project's `phases/` directory. There are three cases:
+
+1. **Existing phase file, workflow changed around it.** The project
+   customized this phase and the skeleton shifted. Discuss the
+   implications: "The orient skeleton reorganized its steps — your
+   custom `health-checks.md` phase still works, but it now runs
+   earlier in the workflow. Is that okay?"
+
+2. **New phase the skeleton now references.** The upstream added a
+   phase that didn't exist before. Explain what the default behavior
+   is and what customizing it would look like. Don't push — just
+   surface the opportunity. "The debrief skeleton now has an
+   `upstream-feedback` step. It runs by default — here's what it does.
+   If you ever want to change that behavior, you'd create
+   `phases/upstream-feedback.md`."
+
+3. **Existing default that changed meaningfully.** The project uses
+   the default (no phase file) and the default behavior shifted. The
+   project gets the improvement automatically, but mention it so they
+   know. If the new default does something they might not want, suggest
+   creating a phase file to customize or skip it. "The plan skeleton's
+   default research phase now reads test files too. You've been using
+   the default — you'll get this automatically. If that's too noisy,
+   create `phases/research.md` to scope it."
+
+4. **Default that won't fit the project.** Read `_briefing.md` and
+   compare against what the default actually does. If there's a
+   mismatch, say so and offer to create the phase file now. "The
+   orient skeleton added a `work-scan` phase. The default reads git
+   history — but your `_briefing.md` says you use Linear. The default
+   won't see your tickets. Want to create `phases/work-scan.md` that
+   checks Linear?" This isn't speculation — it's reading both sides
+   and spotting the gap.
+
+**Don't enumerate every absent phase file.** That's `/onboard`'s job.
+The upgrade skill only surfaces phase opportunities that are *relevant
+to what changed* in this upgrade — including cases where the project's
+context makes a default obviously insufficient.
+
+#### Schema Migrations
+If the upstream schema has new columns or tables:
+- Detect the difference between the shipped schema and the project's DB
+- Generate `ALTER TABLE` / `CREATE TABLE` SQL
+- Present for review
+- Apply only after explicit confirmation
+
+#### New Module Adoption
+If the upgrade added modules the project hadn't installed before,
+walk through what they do and whether to keep them.
+
+Present a summary when done: what was mechanically updated, what was
+adapted conversationally, what the user might want to customize next.
+
+### 5. 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.
+
+## Phase Summary
+
+| Phase | Absent = | What it customizes |
+|-------|----------|-------------------|
+| `pre-upgrade.md` | Default: read .corrc.json, note phase files, note _briefing.md | Pre-upgrade state capture |
+| `explain-changes.md` | Default: semantic summary of version jump, changed skeletons, new files | How to present what changed |
+| `adapt.md` | Default: _briefing.md sections, phase implications, schema, new modules | How to handle non-manifest concerns |
+
+## Proactive Trigger
+
+The upgrade skill doesn't have to wait for the user to invoke it.
+Orient can detect when upstream CoR has a newer version than what's
+in `.corrc.json` and surface "CoR updates available" in the briefing.
+This is a hint, not a blocker — the user decides when to run /cor-upgrade.
+
+The drift check script (`scripts/cor-drift-check.cjs`) can also detect
+if manifest-tracked files have been modified outside the installer,
+though the upstream guard hook should prevent this during normal
+Claude Code operation.
+
+## Extending
+
+To customize a phase: write content in the corresponding `phases/` file.
+To skip a phase: write only `skip: true`.
+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:
+- Changelog generation (produce a human-readable summary of what changed)
+- Rollback plan (capture how to revert each change if something breaks)
+- Downstream notification (update team members about process changes)
+- Compatibility check (verify that project extensions still work after
+  skeleton updates)
+
+## Calibration
+
+**Core failure this targets:** Process improvements published upstream
+never reach adopted projects, or reach them but nobody understands
+what changed.
+
+### Without Skill (Bad)
+
+New CoR version is out. The user re-runs the installer. Files update
+silently. The user has no idea what changed — was it just bug fixes?
+New features? Did a skill they rely on change its workflow? They also
+don't realize the new debrief skill references a `§ Friction Captures`
+section in _briefing.md that their project doesn't have, so the upstream
+feedback phase silently does nothing. Three weeks later they wonder
+why no friction is being captured.
+
+### With Skill (Good)
+
+New CoR version is out. The user runs `/cor-upgrade`. The installer
+updates all upstream files mechanically — fast, deterministic, safe
+(phase files untouched). Then Claude explains: "You went from v0.4.1
+to v0.5.0. The big change: debrief now has an upstream feedback phase
+that captures CoR friction. It references `_briefing.md § Friction
+Captures` — let's add that section to your briefing file." "The plan
+skill's critique step now uses three cabinet members instead of one. Your
+existing phase files are fine — this is a default behavior change."
+"There's a new `investigate` skill for deep-dive debugging. Want to
+try it?" Everything is explained. Non-manifest concerns are handled.
+The project gets better without confusion.