create-claude-cabinet 0.6.0

package/templates/skills/execute/phases/commit-and-deploy.md

@@ -0,0 +1,66 @@
+# Commit and Deploy — How to Persist and Deploy Changes
+
+Define how your project persists work (commit strategy) and deploys
+changes (if applicable). The /execute skill reads this file at Step 6
+after validation passes.
+
+When this file is absent or empty, the default behavior is: commit with
+a clear message describing the implementation. Don't push or deploy —
+deployment strategy is project-specific. To explicitly skip commit
+(e.g., changes are committed manually), write only `skip: true`.
+
+## What to Include
+
+- **Commit strategy** — message format, what to stage, branch conventions
+- **Push rules** — when to push, to which remote
+- **Deployment** — how to deploy, whether deploy is automatic or manual
+- **Post-deploy verification** — how to confirm deployment succeeded
+
+## Example Commit-and-Deploy Configurations
+
+Uncomment and adapt these for your project:
+
+<!--
+### Standard Git Workflow
+```bash
+# Stage specific files (never git add -A)
+git add path/to/changed/files
+
+# Commit with descriptive message
+git commit -m "feat: description of what was implemented
+
+Co-Authored-By: Claude <noreply@anthropic.com>"
+
+# Push to remote
+git push origin current-branch
+```
+
+### Deployment (auto-deploy on push)
+If your platform auto-deploys on push (Railway, Vercel, Netlify):
+- Push triggers deployment automatically
+- Run /verify-deploy or equivalent to confirm
+- Wait for deployment to complete before marking work done
+
+### Deployment (manual)
+```bash
+# Build and deploy
+npm run build
+railway up  # or: vercel deploy, fly deploy, etc.
+```
+
+### Deployment (split: code vs. content)
+Some projects deploy code and content differently:
+- **Code changes** → full deploy (rebuild required)
+- **Content/markdown changes** → git push triggers a pull on the server
+  (no rebuild, instant update)
+
+Determine which type of change was made and use the appropriate path.
+
+### Post-Deploy Verification
+```bash
+# Check deployment health
+curl -s https://your-app.example.com/health | jq .
+# Verify the specific change is live
+curl -s https://your-app.example.com/api/version
+```
+-->

package/templates/skills/execute/phases/load-plan.md

@@ -0,0 +1,49 @@
+# Load Plan — Where Plans Live and How to Read Them
+
+Define where your project stores plans and how to read them. The /execute
+skill reads this file to find and load the plan before implementing.
+
+When this file is absent or empty, the default behavior is: expect the
+plan to be provided in conversation or referenced by the user. To
+explicitly skip plan loading (plan is always provided inline), write
+only `skip: true`.
+
+## What to Include
+
+- **Where plans live** — database, markdown files, issue tracker, etc.
+- **How to query** — the command or API to fetch a specific plan
+- **What to extract** — implementation steps, surface area, acceptance
+  criteria, plan type (code vs. walkthrough)
+
+## Example Load-Plan Configurations
+
+Uncomment and adapt these for your project:
+
+<!--
+### Database API
+```bash
+# Fetch plan from action notes
+curl -s https://your-app.example.com/api/tasks/TASK_ID \
+  -H "Authorization: Bearer $API_TOKEN" | jq '.notes'
+```
+Parse the notes for: ## Implementation, ## Surface Area, ## Acceptance Criteria
+
+### Local Database
+```bash
+sqlite3 project.db "SELECT notes FROM tasks WHERE id = 'TASK_ID'"
+```
+
+### GitHub Issue
+```bash
+gh issue view ISSUE_NUMBER --json body | jq -r '.body'
+```
+
+### Markdown File
+```bash
+Read docs/plans/YYYY-MM-DD-plan-title.md
+```
+
+### Plan Identification
+When the user says "execute the plan," look up the most recent active
+plan item. When ambiguous, list open plan items and ask which one.
+-->

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

@@ -0,0 +1,50 @@
+# Validators — What Validation to Run
+
+Define what validation to run after implementation and before commit.
+The /execute skill reads this file at Step 6. This may reference or
+duplicate your project's /validate skill phases — that's fine, the
+execute skeleton needs to know what to run inline.
+
+When this file is absent or empty, the default behavior is: run the
+project's /validate skill if it exists. If no validate skill exists,
+run the project's type checker and linter at minimum. To explicitly
+skip validation, write only `skip: true`.
+
+## What to Include
+
+- **Type checking** — command to verify types
+- **Linting** — command to check style and correctness
+- **Build** — command to verify the project builds
+- **Structural validation** — project-specific integrity checks
+- **Pass criteria** — what "passing" means (zero errors? warnings OK?)
+
+## Example Validator Configurations
+
+Uncomment and adapt these for your project:
+
+<!--
+### TypeScript Project
+```bash
+npx tsc -b --noEmit        # Type checking — must exit 0
+npx eslint . --max-warnings 0  # Linting — zero warnings
+npm run build               # Build — must succeed
+```
+
+### Python Project
+```bash
+mypy src/                   # Type checking
+ruff check src/             # Linting
+python -m pytest --co -q    # Verify tests collect (don't run full suite)
+```
+
+### Structural Validation
+```bash
+./scripts/validate-fids.sh          # Entity ID coverage
+./scripts/validate-threads.sh       # Thread structure integrity
+./scripts/validate-schema.sh        # Schema consistency
+```
+
+### Pass Criteria
+All commands must exit 0. Warnings are acceptable for linting only if
+they existed before this session's changes (don't introduce new ones).
+-->

package/templates/skills/execute/phases/verification-tools.md

@@ -0,0 +1,67 @@
+# Verification Tools — How to Check Acceptance Criteria
+
+Define what tools your project has for verifying acceptance criteria.
+The /execute skill reads this file during the QA gate (Step 7) to know
+what's available for checking [manual] criteria.
+
+When this file is absent or empty, the default behavior is: 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. To skip tool-based verification
+entirely (defer all manual criteria to user), write only `skip: true`.
+
+## What to Include
+
+- **Available tools** — what verification tools the project has
+- **Tool-to-criterion mapping** — which tool to use for which kind of check
+- **Limitations** — what genuinely can't be verified with tools
+  (physical hardware, native gestures, audio output)
+
+## Example Verification Tool Configurations
+
+Uncomment and adapt these for your project:
+
+<!--
+### Preview Tools (Claude Code built-in)
+For web applications with a dev server:
+- preview_start — ensure a dev server is running
+- preview_snapshot — check page content, structure, element presence
+- preview_screenshot — capture visual state for layout/styling checks
+- preview_click — test interactive elements (buttons, toggles, menus)
+- preview_fill — test form inputs
+- preview_console_logs — check for runtime errors
+- preview_inspect — verify CSS properties
+- preview_eval — run JS to navigate, scroll, check DOM state
+- preview_resize — test responsive behavior
+
+Tool-to-criterion mapping:
+- "Page renders X" → preview_snapshot or preview_screenshot
+- "Clicking X does Y" → preview_click + preview_snapshot
+- "No console errors" → preview_console_logs
+- "Element has style X" → preview_inspect
+- "Responsive at Npx" → preview_resize + preview_screenshot
+
+### Test Runner
+```bash
+npm test -- --grep "test-pattern"
+pytest -k "test_pattern"
+```
+
+### API Verification
+```bash
+curl -s -o /dev/null -w "%{http_code}" https://localhost:3000/api/endpoint
+```
+
+### Browser Automation (external)
+If using Playwright, Cypress, or similar:
+```bash
+npx playwright test tests/specific-test.spec.ts
+```
+
+### What Can't Be Tool-Verified
+These genuinely require user interaction:
+- Native touch gestures on physical device
+- Audio output quality
+- Physical hardware interaction
+- Real-time performance under production load
+-->

package/templates/skills/extract/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: extract
+description: |
+  Analyze non-CoR skills, cabinet members, and other artifacts in a consuming
+  project and propose candidates for upstreaming into Claude Cabinet as
+  generic templates. Does not perform the extraction — files a proposal
+  that surfaces during orient in the CoR repo. Use when: "extract",
+  "upstream this", "should this be in CoR?", "/extract".
+---
+
+# /extract — Propose Artifacts for Upstreaming to CoR
+
+## Purpose
+
+Consuming projects grow custom skills, cabinet members, phase files, and
+other artifacts that solve real problems. Some of those solutions are
+project-specific. Others solve problems that any project would have.
+This skill identifies the latter and proposes upstreaming them into
+Claude Cabinet as generic templates.
+
+**This skill proposes. It does not extract.** The actual separation of
+generic orchestration from project-specific context happens in the CoR
+repo after a human reviews and accepts the proposal. The consuming
+project then adopts the CoR version via `/cor-upgrade`.
+
+## Where This Runs
+
+**Consuming projects only.** If run from the CoR source repo
+(`package.json` name is `create-claude-cabinet`), say: "This skill runs
+from consuming projects. Here, use orient to review incoming proposals."
+
+## Workflow
+
+### 1. Inventory Non-CoR Artifacts
+
+Compare the project's `.claude/` directory against `.corrc.json`'s
+manifest. Anything not in the manifest is project-specific:
+
+- **Custom skills** — `.claude/skills/*/SKILL.md` not in manifest
+- **Custom cabinet members** — `.claude/skills/cabinet-*/SKILL.md`
+  not in the standard set
+- **Custom phase files** — phase files in CoR skills that override
+  defaults with substantial logic (not just `skip: true`)
+- **Custom hooks** — hook scripts not installed by CoR
+- **Custom rules** — `.claude/rules/` files beyond the CoR defaults
+- **Patterns** — `.claude/memory/patterns/` entries that encode
+  reusable lessons
+
+### 2. Assess Each Candidate
+
+For each non-CoR artifact, evaluate:
+
+**Generalizability** — Would other projects benefit from this?
+- Does it solve a problem tied to this specific project, or a class
+  of problems?
+- Could the project-specific parts be isolated into phase files?
+- Is the core logic reusable if you strip out hardcoded paths, names,
+  and domain concepts?
+
+**Maturity** — Is this ready to propose?
+- Has it been used enough to know it works? (Check telemetry if
+  available, or ask the user.)
+- Has it been refined, or is it a first draft?
+- Are there known issues or things the user wants to change?
+
+**Category** — What kind of CoR artifact would this become?
+- A new skill template (SKILL.md + default phase behaviors)
+- A new cabinet member (SKILL.md with scan scope and finding format)
+- A new phase file for an existing skill (e.g., a custom orient check)
+- A new hook or rule template
+- A new pattern worth promoting to the standard set
+
+Rate each candidate: **strong** (clearly generic, proven, ready),
+**possible** (could be generic with work), or **project-specific**
+(not a candidate). Only propose strong and possible candidates.
+
+### 3. Draft Proposals
+
+For each candidate, draft a proposal that includes:
+
+```markdown
+# Extraction Proposal: [artifact name]
+
+## Source
+- Project: [project name/path]
+- Artifact: [path to the artifact]
+- Type: skill | cabinet-member | phase | hook | rule | pattern
+
+## What It Does
+[1-2 paragraphs describing the artifact's purpose and how it works
+in the source project]
+
+## Why It's Generic
+[Why this solves a class of problems, not just this project's problem.
+What other projects would use it for.]
+
+## Suggested Generalized Form
+[How this would look as a CoR template. What becomes the skeleton,
+what becomes phase-file-configurable, what gets dropped as
+project-specific. Include a rough SKILL.md outline if it's a skill
+or cabinet member.]
+
+## What Stays Project-Specific
+[What parts of the current implementation would remain as phase files
+or project configuration after extraction]
+
+## Assessment
+- Generalizability: strong | possible
+- Maturity: proven | early
+- Complexity: low | medium | high (effort to extract)
+
+## Source Artifact Content
+[Full content of the artifact being proposed, so the CoR repo has
+everything needed to evaluate without access to the source project]
+```
+
+### 4. File Proposals
+
+**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 each proposal as a markdown file in the CoR repo's
+  `proposals/` directory (create it if needed)
+- Filename: `[source-project]-[artifact-name].md`
+  (e.g., `flow-review-pr.md`)
+- These will surface during orient in the CoR repo
+
+**If not linked** (CoR is installed from npm):
+
+- Open a GitHub issue on the CoR repo for each proposal
+- Title: `Extract proposal: [artifact name] from [project]`
+- Label: `extraction-proposal` (create if needed)
+- Body: the full proposal markdown
+- Requires `gh` CLI to be authenticated
+
+**If neither works** (no link, no gh access):
+
+- Output the proposals to the terminal and tell the user to
+  file them manually or copy them to the CoR repo
+
+### 5. Summary
+
+After filing, summarize:
+- How many artifacts were scanned
+- How many proposals were filed (strong + possible)
+- How many were project-specific (not proposed)
+- Where the proposals went (local files or GitHub issues)
+- Remind: "Review these in the CoR repo. Accepted proposals get
+  built as generic templates, then your project adopts them via
+  /cor-upgrade."
+
+## Running on a Subset
+
+The user can target specific artifacts:
+
+- `/extract` — scan everything
+- `/extract skills/my-skill` — evaluate a specific skill
+- `/extract cabinet-members` — evaluate all custom cabinet members
+
+## What This Does NOT Do
+
+- **Does not modify the consuming project.** No files are changed here.
+- **Does not modify CoR templates.** Proposals are filed, not applied.
+- **Does not decide.** A human reviews each proposal in the CoR repo.
+- **Does not extract phase files from skills.** The separation of
+  skeleton from phases happens during implementation in CoR, not here.
+  The proposal includes a *suggested* separation, not a final one.

package/templates/skills/investigate/SKILL.md

@@ -0,0 +1,160 @@
+---
+model: opus
+name: investigate
+description: |
+  Structured codebase exploration before planning. Four phases: observe
+  (gather facts), hypothesize (form explanations), test (verify), conclude
+  (summarize findings). Replaces ad-hoc grepping with a systematic approach.
+  Use when: "investigate", "explore this", "figure out how X works",
+  "why is X happening", "look into", "/investigate".
+related:
+  - type: skill
+    name: plan
+    role: "Terminal state — /investigate feeds into /plan"
+  - type: skill
+    name: audit
+    role: "Audit finds issues, /investigate explores them"
+  - type: file
+    path: cabinet/_briefing.md
+    role: "System briefing for investigation scope"
+model: opus
+---
+
+# /investigate — Structured Codebase Exploration
+
+## Purpose
+
+Replace ad-hoc grepping and scattered file reads with a disciplined
+exploration protocol. When you need to understand how something works,
+why something is broken, or what the codebase looks like before planning
+a change, /investigate gives you a structured path from question to answer.
+
+Adapted from obra/superpowers systematic-debugging pattern.
+
+## Workflow
+
+### 1. Frame the Question
+
+State the investigation question clearly. Good questions:
+- "How does inbox processing route items to threads?"
+- "Why are telemetry events showing duplicate session-start entries?"
+- "What would need to change to support recurring actions?"
+
+Bad questions (too vague — narrow first):
+- "How does the system work?" → Pick a specific subsystem
+- "Is the code good?" → That's /audit, not /investigate
+
+### 2. Observe (Gather Facts)
+
+Collect raw data without interpreting it. Use the Explore agent or
+direct Grep/Glob/Read calls:
+
+- **Map the surface area:** Which files, functions, and data flows
+  are involved? Use Glob to find relevant files, Grep to find key
+  function names and call sites.
+- **Read the code:** Read the actual implementation, not just the docs.
+  Docs can be stale; code is ground truth.
+- **Check the data:** If the question involves runtime behavior, look
+  at actual data (DB contents, log files, telemetry, API responses).
+- **Note surprises:** Anything that contradicts your expectations is
+  a finding worth recording.
+
+**Output:** A bulleted list of concrete observations. Each observation
+should cite a specific file:line or data point.
+
+### 3. Hypothesize (Form Explanations)
+
+Based on observations, form 1-3 hypotheses that explain what you're seeing.
+
+For each hypothesis:
+- State it clearly in one sentence
+- Identify what evidence would confirm it
+- Identify what evidence would refute it
+
+**The discipline here is generating alternatives.** Don't lock onto the
+first explanation. If you only have one hypothesis, you're not investigating
+— you're confirming.
+
+### 4. Test (Verify)
+
+For each hypothesis, actively seek the confirming AND refuting evidence
+you identified. This may involve:
+- Reading more code to check call paths
+- Running commands to check actual behavior
+- Querying the database for state
+- Checking git history for when behavior changed
+
+**Record results per hypothesis:** confirmed, refuted, or inconclusive
+(with what additional data would resolve it).
+
+### 5. Conclude
+
+Summarize findings in a structured report:
+
+```markdown
+## Investigation: {question}
+
+### Observations
+- {key observation 1} — {file:line}
+- {key observation 2} — {file:line}
+
+### Findings
+- {finding 1}: {what we learned and why it matters}
+- {finding 2}: {what we learned and why it matters}
+
+### Unresolved
+- {anything still unclear, if applicable}
+
+### Recommendation
+{What to do with these findings — usually "proceed to /plan"}
+```
+
+Present the report to the user. If the findings are sufficient to act on,
+the next step is `/plan`.
+
+## Terminal State
+
+Next step: `/plan` (if findings warrant action) or report findings and
+close (if the investigation was purely informational).
+
+## Principles
+
+- **Observe before hypothesizing.** Gather facts first. Premature
+  hypotheses create confirmation bias — you read code looking for
+  evidence of what you already believe.
+- **Generate alternatives.** One hypothesis is confirmation, not
+  investigation. Force yourself to consider at least one alternative
+  explanation.
+- **Cite evidence.** Every observation and finding should point to a
+  specific file, line, data point, or command output. Unsourced claims
+  are opinions, not findings.
+- **Know when to stop.** Investigation serves planning. Once you have
+  enough understanding to plan confidently, stop. Exhaustive exploration
+  of every tangent is a different activity.
+
+## Calibration
+
+**Core failure this targets:** Starting implementation based on assumptions
+about how the codebase works, then discovering mid-implementation that the
+assumptions were wrong.
+
+### Without Skill (Bad)
+
+User says "add a feature to archive completed items." Claude greps for
+"item" in a few files, reads the config, and starts writing an archive
+script. Mid-implementation, discovers that items are referenced by ID
+in API endpoints, in 3 different UI routes, in a sync mechanism, and
+in foreign key relationships across 2 database tables. The archive
+script moved the records but broke 6 references. Rolls back and starts
+over with a proper plan.
+
+### With Skill (Good)
+
+User says `/investigate` — "what would need to change to archive items?"
+Claude maps the surface area: config files, API endpoints, UI routes,
+database foreign keys, sync references. Forms two hypotheses: (1) items
+can be soft-deleted with a status flag, (2) items need physical removal
+with cascade cleanup. Tests both against the codebase. Concludes with a
+complete dependency map and recommends `/plan` with the status-flag
+approach. The subsequent plan accounts for all 6 reference points from
+the start.

package/templates/skills/link/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: link
+description: |
+  Set up local development linking for Claude Cabinet. Detects whether
+  you're in the CoR source repo or a consuming project and runs the
+  appropriate npm link command. Use when: "link", "local dev", "use local
+  CoR", "/link".
+---
+
+# /link — Local Development Linking
+
+## Purpose
+
+Connect a consuming project to a local checkout of Claude Cabinet so
+template changes are immediately available without publishing to npm.
+
+## Context Detection
+
+Before doing anything, determine where you are:
+
+**CoR source repo** (`package.json` has `name: "create-claude-cabinet"`):
+- Run `npm link` to register the package globally
+- This makes the local checkout available to any project that links to it
+- Tell the user: "Registered locally. In your other projects, run `/link`
+  to connect them to this checkout."
+
+**Any other project** (anything that isn't the CoR source repo):
+- Run `npm link create-claude-cabinet` to point to the local CoR checkout
+- Verify it worked: check that `npx create-claude-cabinet --help` resolves
+  to the local version
+- If CoR is already installed (`.corrc.json` exists): "Linked to local
+  CoR. Run `/cor-upgrade` to pull template changes into your installed
+  skills."
+- If CoR is not yet installed: "Linked to local CoR. Run
+  `npx create-claude-cabinet` to install."
+
+## Prerequisites
+
+The CoR source repo must have been linked first (`npm link` from the CoR
+directory). If a consuming project tries to link and the global link
+doesn't exist, npm will error. In that case, tell the user to run `/link`
+in their CoR checkout first.
+
+## What This Encodes
+
+- `npm link` (in source) registers a global symlink to the package
+- `npm link create-claude-cabinet` (in consumer) creates a local symlink
+  to the globally registered package
+- The link survives across terminal sessions
+- The link uses whatever is on disk — no version pinning, no caching
+- After linking, `npx create-claude-cabinet` and `/cor-upgrade` both
+  resolve to the local checkout

package/templates/skills/menu/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: menu
+description: |
+  Show available skills with descriptions and invocability.
+  Use when: "menu", "what can you do", "what skills", "help", "/menu".
+---
+
+# /menu — Available Skills
+
+## Purpose
+
+Dynamically discover and display all available skills, what they do, and
+whether they are auto-invocable or manual-only.
+
+## Workflow
+
+1. **Discover skills:** Use the Glob tool to find all `.claude/skills/*/SKILL.md` files.
+
+2. **Read frontmatter from each:** For every discovered SKILL.md, use the Read tool
+   to extract the YAML frontmatter (between the `---` delimiters). Parse these fields:
+   - `name` — the skill name (used as `/name` in the table)
+   - `description` — first line or sentence of the description (strip the
+     "Use when:" portion for display)
+   - `disable-model-invocation` — if `true`, the skill is manual-only.
+     If absent or false, Claude can invoke it automatically.
+
+3. **Group skills into two categories:**
+
+   **Auto (Claude uses these when relevant)** — skills where
+   `disable-model-invocation` is absent or false. These trigger automatically
+   when the context matches.
+
+   **Manual (user invokes these — they have side effects)** — skills where
+   `disable-model-invocation: true`. The user must explicitly invoke these.
+
+   Note: `/menu` itself goes in whichever category its own frontmatter indicates.
+
+4. **Format as two tables:**
+
+   ### Auto (Claude uses these when relevant)
+   | Skill | When it triggers |
+   |---|---|
+   | `/name` | description (from the "Use when:" part of the description field) |
+
+   ### Manual (you invoke these — they have side effects)
+   | Skill | What it does |
+   |---|---|
+
+   Sort alphabetically within each group.
+
+5. **Suggest relevant skills:** Based on current context (open work items,
+   queued tasks, recent activity), suggest which skills are most relevant
+   right now.
+
+## Important
+
+- Do NOT hardcode any skill names or descriptions. Every entry must come
+  from reading the actual SKILL.md files at discovery time.
+- If a new skill is added to `.claude/skills/`, it automatically appears
+  in the menu on the next invocation. No updates to this file needed.
+- If a SKILL.md has no description, show the skill name with "(no description)".