create-claude-cabinet 0.6.0

package/templates/skills/pulse/SKILL.md

@@ -0,0 +1,242 @@
+---
+name: pulse
+description: |
+  Self-description accuracy check. Verifies that what the system claims
+  matches what the system actually is — counts, states, conventions,
+  documented behaviors. Two modes: embedded (silent in orient/debrief,
+  15-second budget) and standalone (systematic, three categories).
+  Use when: embedded in orient/debrief, "pulse", "/pulse", or when
+  system descriptions feel stale.
+related:
+  - type: file
+    path: .claude/skills/pulse/phases/checks.md
+    role: "Project-specific: what to verify"
+  - type: file
+    path: .claude/skills/pulse/phases/auto-fix-scope.md
+    role: "Project-specific: what can be fixed automatically"
+  - type: file
+    path: .claude/skills/pulse/phases/output.md
+    role: "Project-specific: how to present results"
+  - type: file
+    path: cabinet/_briefing.md
+    role: "Project identity and configuration"
+---
+
+# /pulse — Self-Description Accuracy Check
+
+## Purpose
+
+Self-description drifts from reality. A status file says "12 skills"
+but the directory has 14. A CLAUDE.md documents a workflow that was
+replaced two weeks ago. A configuration file references a path that
+was renamed. These discrepancies are small individually but compound
+into a system that describes one thing and does another — creating
+confusion, wasted effort, and incorrect assumptions.
+
+Pulse catches these before they compound. It's the system's mirror:
+hold up what you claim to be, check what you actually are, and flag
+every gap.
+
+This is a **skeleton skill** using the `phases/` directory pattern. The
+orchestration is generic. Your project defines the specifics — what
+to check, what to auto-fix, how to report — 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 |
+
+## Identity
+
+You are the mirror. You don't judge quality or propose improvements —
+that's the auditor's job. You verify accuracy: does the description
+match the thing it describes? You are fast, factual, and silent when
+everything checks out.
+
+Your checks are mechanical: count files and compare to documented
+counts, read paths and verify they exist, check dates and flag staleness.
+You don't interpret or weigh significance — you just report
+discrepancies. The human decides which ones matter.
+
+## Two Modes
+
+### Embedded Mode (in orient/debrief)
+
+Silent when healthy. Runs within a 15-second budget as part of orient
+or debrief. Only speaks if something needs attention. This is how pulse
+runs most of the time — a background health check that's invisible when
+the system is accurate.
+
+**When embedded in orient:** Check before the briefing so any issues
+can be included in the briefing.
+
+**When embedded in debrief:** Check after state updates so the debrief
+can fix any discrepancies before the session closes.
+
+### Standalone Mode (/pulse)
+
+Systematic check across three categories. Used when you suspect drift
+has accumulated or want a comprehensive accuracy check. Reports
+everything — not just problems.
+
+## Workflow
+
+### 1. Run Checks (core)
+
+Read `phases/checks.md` for what to verify.
+
+**Default (absent/empty):** Run three categories of checks:
+
+**Category A — Count Freshness.** Enumerate actual items and compare
+to any documented counts. Examples:
+- Count files matching `skills/*/SKILL.md` vs any documented skill count
+- Count files matching `skills/cabinet-*/SKILL.md` vs documented
+  cabinet member count
+- Count entries in configuration files vs documented totals
+- Count items in any enumerated list vs documented count
+
+**Category B — Dead Reference Spot-Check.** Pick 3-5 paths, references,
+or links from documentation files (CLAUDE.md, README.md, status files)
+and verify they resolve:
+- File paths — does the file exist?
+- Directory references — does the directory exist?
+- Script references — does the script exist and is it executable?
+- Cross-references between docs — does the target section exist?
+
+**Category C — Staleness Detection.** Check for time-sensitive content
+that may have drifted:
+- Files with dates in their content — is the date current?
+- "Last updated" or "as of" references — how old are they?
+- Version numbers or counts that should change as the project evolves
+
+In embedded mode, run a quick subset (one check from each category).
+In standalone mode, run all checks.
+
+### 2. Determine Auto-Fix Scope (core)
+
+Read `phases/auto-fix-scope.md` for what can be fixed automatically
+without human judgment.
+
+**Default (absent/empty):** Auto-fix is limited to numeric counts only.
+If a document says "12 skills" and you counted 14, update the number.
+Everything else — stale descriptions, dead references, outdated
+workflows — gets reported but not changed, because the fix might
+require judgment about what the correct content should be.
+
+**The closed-list principle:** Only auto-fix what's mechanically
+verifiable. A count is either right or wrong. A description is a matter
+of judgment. Pulse auto-fixes the first kind and reports the second.
+
+### 3. Present Output (presentation)
+
+Read `phases/output.md` for how to present results.
+
+**Default (absent/empty):**
+
+In **embedded mode**: silence means health. Only speak if there are
+discrepancies. When reporting, be brief: "Pulse: skill count says 12,
+found 14. Dead ref: `scripts/old-tool.sh` (referenced in README)."
+
+In **standalone mode**: present a stratified report:
+- **Fixed** — discrepancies auto-corrected (with what changed)
+- **Options** — discrepancies that need human judgment (with what you
+  found vs what's documented)
+- **Questions** — things you couldn't verify or aren't sure about
+
+### 4. Discover Custom Phases
+
+After running the core phases above, 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 |
+|-------|----------|-------------------|
+| `checks.md` | Default: count freshness + dead refs + staleness | What to verify |
+| `auto-fix-scope.md` | Default: numeric counts only | What can be fixed automatically |
+| `output.md` | Default: silent-when-healthy (embedded) or stratified (standalone) | How to present results |
+
+## How Pulse Connects to Other Skills
+
+**Orient** checks operational state — is the system running? **Pulse**
+checks descriptive accuracy — does the documentation match reality?
+Orient runs first; pulse runs inside orient (embedded) to catch stale
+descriptions before they mislead.
+
+**Audit** examines quality through expert cabinet members — is the code
+good, is the architecture sound? **Pulse** examines accuracy through
+mechanical comparison — does the number match? Audit requires judgment;
+pulse requires counting. They complement each other: pulse catches the
+trivially verifiable so audit can focus on the substantive.
+
+**Debrief** updates state files after work. **Pulse** verifies those
+updates are consistent. When pulse runs inside debrief, it catches
+cases where the debrief updated one file but not another.
+
+### Boundary Table
+
+| Question | Tool |
+|----------|------|
+| "Is this code correct?" | /audit |
+| "Is the documentation accurate?" | /pulse |
+| "Does the count match?" | /pulse |
+| "Is the architecture sound?" | /audit |
+| "Is the system running?" | /orient |
+
+Projects with additional skills extend this table in their SKILL.md.
+
+## Extending
+
+To customize a phase: write content in the corresponding `phases/` file.
+To skip a phase: write only `skip: true` in the file.
+To add a phase: create a new file in `phases/`.
+
+Examples of checks mature projects add:
+- Schema validation (do entity definitions match what's in the database?)
+- Hook verification (do configured hooks still point to valid scripts?)
+- Dependency freshness (are documented dependencies still current?)
+- Environment consistency (do env vars match what scripts expect?)
+
+## Calibration
+
+**Core failure this targets:** Self-description gradually diverging from
+reality until the documentation becomes misleading rather than helpful.
+
+### Without Skill (Bad)
+
+The project evolves over months. Each session builds features, refactors
+code, reorganizes directories. Documentation gets updated sometimes but
+not always. The README says the project has 12 skills, but 3 more were
+added. A CLAUDE.md references a script that was renamed. The status file
+describes a workflow that was replaced last month.
+
+Someone reads the documentation and builds a mental model based on what
+it says. That mental model is wrong. They make decisions based on it.
+The documentation has become an actively misleading artifact.
+
+### With Skill (Good)
+
+Every session, pulse runs embedded. Counts are verified, references are
+spot-checked, staleness is detected. Most of the time it's silent —
+everything checks out. When a count drifts, it's auto-fixed. When a
+reference dies, it's flagged and fixed in the same session.
+
+The documentation stays accurate not through discipline but through
+verification. The system describes what it is because something is
+always checking.
+
+## Assessment Log
+
+Standalone pulse appends lightweight eval results here. Each entry
+records the date, mode, counts of findings by category, and any skills
+assessed. This section accumulates over time — it's pulse's memory of
+what it has checked and found.
+
+(No assessments yet. First standalone /pulse run will establish the baseline.)

package/templates/skills/pulse/phases/auto-fix-scope.md

@@ -0,0 +1,40 @@
+# Auto-Fix Scope — What Can Be Fixed Automatically
+
+Define what pulse is allowed to correct without asking. The /pulse skill
+reads this file to determine its auto-fix boundaries.
+
+When this file is absent or empty, the default behavior is: auto-fix
+numeric counts only. Everything else is reported but not changed.
+To explicitly disable all auto-fix, write only `skip: true`.
+
+## The Closed-List Principle
+
+Pulse only auto-fixes what's mechanically verifiable. The question is
+not "can I fix this?" but "is there exactly one correct value?"
+
+- A count is either right or wrong → auto-fix
+- A date is either current or stale → auto-fix
+- A description is a matter of judgment → report only
+- A dead reference could mean rename, delete, or rethink → report only
+
+When you expand auto-fix scope, you're asserting that the fix requires
+zero human judgment. Be conservative — a wrong auto-fix is worse than
+a reported discrepancy.
+
+## Example Expanded Scope
+
+Uncomment and adapt for your project:
+
+<!--
+### Numeric Counts (default)
+Update documented counts to match actual counts.
+
+### Date Stamps
+Update "last verified" dates in cabinet member SKILL.md files after
+a successful pulse check confirms they're still accurate.
+
+### Known Renames
+If a file was renamed (git log shows the rename) and a reference
+still uses the old path, update the reference. Only when the git
+history unambiguously shows a 1:1 rename, not a split or merge.
+-->

package/templates/skills/pulse/phases/checks.md

@@ -0,0 +1,58 @@
+# Checks — What to Verify
+
+Define what pulse checks for self-description accuracy. The /pulse skill
+reads this file to know what to verify.
+
+When this file is absent or empty, the default behavior is: run three
+categories of checks (count freshness, dead reference spot-check,
+staleness detection). To explicitly skip all checks, write only
+`skip: true`.
+
+## What to Include
+
+For each check, provide:
+- **What** — what to compare (documented value vs actual value)
+- **How** — how to get the actual value (command, file read, count)
+- **Auto-fixable** — can the discrepancy be corrected mechanically?
+- **Category** — count freshness, dead reference, or staleness
+
+## Example Checks
+
+Uncomment and adapt for your project:
+
+<!--
+### Count Freshness
+
+#### Skill Count
+- Document: system-status.md says "N skills"
+- Actual: `ls skills/*/SKILL.md | wc -l`
+- Auto-fixable: yes (update the number)
+
+#### Cabinet Member Count
+- Document: system-status.md says "N cabinet members"
+- Actual: `ls skills/cabinet-*/SKILL.md | wc -l`
+- Auto-fixable: yes (update the number)
+
+#### Hook Count
+- Document: CLAUDE.md says "N hooks"
+- Actual: count hooks in `.claude/settings.json`
+- Auto-fixable: yes (update the number)
+
+### Dead Reference Spot-Check
+
+Pick 3-5 paths from documentation and verify they exist:
+- CLAUDE.md references to scripts
+- README.md references to directories
+- Status file references to configuration files
+- Phase file references to other files
+
+### Staleness Detection
+
+#### Status File
+- Check: when was system-status.md last modified?
+- Flag if: older than 7 days and there have been commits since
+
+#### "As of" Dates
+- Check: grep for "as of" in documentation files
+- Flag if: the date is more than 30 days old
+-->

package/templates/skills/pulse/phases/output.md

@@ -0,0 +1,54 @@
+# Output — How to Present Results
+
+Define how pulse presents its findings. The /pulse skill reads this
+file to determine output format and destination.
+
+When this file is absent or empty, the default behavior is:
+- **Embedded mode:** silent when healthy, brief flags when not
+- **Standalone mode:** stratified report (Fixed / Options / Questions)
+To explicitly skip output, write only `skip: true`.
+
+## What to Include
+
+Define your output strategy:
+- **Embedded format** — how to report within orient/debrief output
+- **Standalone format** — how to present the full report
+- **Destination** — conversation only, or also written to a file/log
+
+## Example Output Configuration
+
+Uncomment and adapt for your project:
+
+<!--
+### Embedded Mode
+When running inside orient or debrief:
+- Silent when all checks pass
+- One-line per discrepancy: "Pulse: [what] says X, found Y"
+- Include auto-fixes already applied: "Pulse: updated skill count 12→14"
+
+### Standalone Mode
+When running as /pulse:
+
+#### Fixed (auto-corrected)
+List each discrepancy that was auto-fixed:
+- What was wrong
+- What it was changed to
+- Where (file and line)
+
+#### Options (needs human judgment)
+List each discrepancy that requires a decision:
+- What the documentation says
+- What was actually found
+- Why this can't be auto-fixed (ambiguous correction)
+
+#### Questions (uncertain)
+List anything that couldn't be verified:
+- What was checked
+- Why verification failed
+- Suggested next step
+
+### Log File
+In addition to conversation output, append results to
+`sync/pulse-log.txt` for trend tracking. One line per check:
+`YYYY-MM-DD HH:MM:SS | check-name | pass/fail | details`
+-->

package/templates/skills/seed/SKILL.md

@@ -0,0 +1,257 @@
+---
+name: seed
+description: |
+  Recruit new cabinet members. Scans your project for technologies and
+  frameworks, proposes expert members to cover them, builds them
+  collaboratively, and maintains existing ones over time. Use when: "seed",
+  "check for new tech", "build a cabinet member", "/seed", after adding
+  dependencies or frameworks.
+related:
+  - type: file
+    path: .claude/skills/seed/phases/scan-signals.md
+    role: "Where to look for technology signals"
+  - type: file
+    path: .claude/skills/seed/phases/evaluate-existing.md
+    role: "Check existing cabinet members against detected tech"
+  - type: file
+    path: .claude/skills/seed/phases/build-member.md
+    role: "How to build a new cabinet member collaboratively"
+  - type: file
+    path: .claude/skills/seed/phases/maintain.md
+    role: "Maintain existing cabinet members (retirement, updates)"
+  - type: file
+    path: cabinet/_lifecycle.md
+    role: "Cabinet member lifecycle guidance"
+  - type: file
+    path: cabinet/_briefing-template.md
+    role: "Template for project briefing"
+---
+
+# /seed — Recruit New Cabinet Members
+
+## Purpose
+
+Recruit cabinet members as your project grows. When you adopt React, you
+need accessibility expertise. When you add SQLite, you need data-integrity
+expertise. When you deploy to Railway, you need security and deployment
+expertise. These connections are predictable, but people don't reliably
+act on them at the moment of adoption — they add the dependency, start
+building, and only discover the expertise gap after an incident.
+
+Seed makes that recruitment systematic. It scans for technology
+signals in your project's configuration files, compares them against
+your existing cabinet members, identifies gaps, and initiates
+collaborative conversations to build the missing expertise.
+
+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 — what signals to scan for, what expertise to
+associate with each signal, how to build cabinet members — 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.
+
+## Relationship to /onboard
+
+Onboarding and skill management are the same system at different tempos.
+`/onboard` runs at inception — when a project first adopts the methodology,
+it does a comprehensive scan and builds the initial cabinet member roster
+from scratch. `/seed` runs at steady state — when the project evolves,
+a new dependency appears, a framework is added, infrastructure changes.
+
+The detection logic overlaps intentionally. `/onboard` calls `/seed`'s
+scan internally. `/seed` is the ongoing mechanism that keeps the cabinet
+current as the project grows. Think of `/onboard` as the first `/seed`
+run — comprehensive and foundational. Every subsequent `/seed` is
+incremental and conversational.
+
+## Workflow
+
+### 1. Scan for Technology Signals
+
+Read `phases/scan-signals.md` for where to look and what signal-to-
+expertise mappings to apply. This phase reads package manifests, config
+files, infrastructure definitions, and database artifacts to build a
+picture of what technologies the project uses.
+
+**Default (absent/empty):** Scan standard locations:
+- `package.json` / `requirements.txt` / `Cargo.toml` / `go.mod` for
+  dependencies
+- Config files (`.eslintrc`, `tailwind.config.*`, `tsconfig.json`,
+  `docker-compose.yml`, etc.)
+- Infrastructure files (`Dockerfile`, `.github/workflows/`,
+  `railway.json`, `vercel.json`, `fly.toml`)
+- Database artifacts (`*.db` files, `migrations/`, `prisma/`,
+  `drizzle.config.*`)
+
+Apply the default signal-to-expertise mapping table (defined in the
+phase file). Projects override this phase to add domain-specific signals
+— a healthcare project might map HIPAA-related dependencies to a
+compliance cabinet member; a financial project might map payment libraries
+to a financial-integrity cabinet member.
+
+### 2. Evaluate Existing Cabinet Members
+
+Read `phases/evaluate-existing.md` for how to compare detected signals
+against the current cabinet members.
+
+**Default (absent/empty):** For each detected technology signal:
+1. Check `.claude/skills/cabinet-*/` for a cabinet member whose domain
+   covers that technology
+2. If a matching cabinet member exists: check whether its scan scope still
+   covers the right directories and whether the technology version has
+   changed significantly since the cabinet member was created
+3. If no matching cabinet member exists: flag as a gap
+
+Build two lists:
+- **Gaps** — technologies without corresponding expertise
+- **Stale** — cabinet members that exist but may need updating
+
+Present both lists to the user before proceeding. The user decides which
+gaps to fill and which staleness to address. Not every technology needs
+a cabinet member — some are too minor, some are well-understood, some are
+covered by existing cabinet members with broader scope.
+
+### 3. Build New Cabinet Members
+
+Read `phases/build-member.md` for how to collaboratively build a
+new cabinet member with the user.
+
+**Default (absent/empty):** For each gap the user wants to fill, run a
+collaborative expertise-building conversation:
+1. Research the technology (check docs, use available MCP tools)
+2. Ask the user: what matters about this technology in YOUR project?
+3. Draft a cabinet member `SKILL.md` following `_lifecycle.md` guidance
+4. Walk through Identity, Research Method, Boundaries, and Calibration
+   with the user
+5. Create the file in `cabinet-{name}/SKILL.md`
+6. Update `committees.yaml` if the cabinet member belongs in a committee
+
+This is co-authoring, not auto-generating. The user's domain knowledge
+is what makes a cabinet member useful for their specific project. A generic
+"React best practices" cabinet member catches generic issues. A cabinet member
+built with the user's input — "we use Mantine, we care about keyboard
+navigation, our users are on slow connections" — catches what actually
+matters.
+
+### 4. Maintain Existing Cabinet Members
+
+Read `phases/maintain.md` for how to review the health of existing
+cabinet members and recommend changes.
+
+**Default (absent/empty):** Review the cabinet for:
+- **Retirement candidates:** technologies removed from the project,
+  cabinet members with high rejection rates in audit triage, cabinet members
+  whose scan scopes reference files that no longer exist
+- **Update candidates:** technology version changed significantly,
+  new features added that the cabinet member doesn't cover, scan scope
+  needs expanding to cover new directories
+- **Coverage gaps:** areas of the codebase not covered by any
+  cabinet member's scan scope
+
+Apply `_lifecycle.md` criteria. Recommend retirements as readily as
+adoptions — a lean cabinet is better than a comprehensive one full of
+dead weight. Present recommendations; the user decides.
+
+### 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 |
+|-------|----------|-------------------|
+| `scan-signals.md` | Default: scan standard locations + default mappings | Where to look, what signals map to what expertise |
+| `evaluate-existing.md` | Default: compare signals to cabinet members | How to assess gaps and staleness |
+| `build-member.md` | Default: collaborative conversation | How to co-author a new cabinet member |
+| `maintain.md` | Default: review cabinet health | How to assess retirement, updates, gaps |
+
+## Companion Framing
+
+Seed is conversational by design. It doesn't auto-generate cabinet members
+or silently add expertise. The tone is:
+
+> "I noticed you added Express as a dependency. That typically means we
+> should carry some expertise around security and request handling for
+> this project. Want to explore what a security cabinet member should look
+> like for your setup?"
+
+The user might say "yes, let's build it," or "we don't need that — this
+is an internal tool with no auth," or "good idea, but let's do it next
+session." All valid responses. The skill proposes; the user decides.
+
+This framing matters because expertise is contextual. The same technology
+in two different projects needs different cabinet members. Express in a
+public API needs security hardening. Express in a local dev tool needs
+almost none. The conversation is where that context gets encoded.
+
+## Extending
+
+To customize a phase: write content in the corresponding `phases/` file.
+To skip a phase: write only `skip: true` in the file.
+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.
+
+Examples of phases mature projects add:
+- **Dependency changelog scanning** — check what changed between the old
+  and new version of a dependency, flag breaking changes that affect
+  existing cabinet members
+- **Team expertise mapping** — map detected technologies to team members
+  who have relevant expertise, surface when a technology has no human
+  expert (single point of failure)
+- **Cost estimation** — flag technologies that have cost implications
+  (cloud services, paid APIs, licensed frameworks)
+- **Compliance mapping** — map technologies to compliance requirements
+  (HIPAA, SOC2, GDPR) based on what data they handle
+
+## Calibration
+
+**Core failure this targets:** Reactive expertise acquisition. Technology
+is adopted, expertise is not built until an incident reveals the gap.
+The gap between adoption and incident is where preventable problems live.
+
+### Without Skill (Bad)
+
+Developer adds a SQLite database to the project. Builds features against
+it for weeks. Nobody thinks about data integrity until a migration
+corrupts production data. After the incident, someone writes a checklist
+of "things to check with SQLite." The checklist lives in a wiki page
+that nobody reads. Six months later, the same class of bug recurs because
+the checklist wasn't integrated into the development workflow.
+
+The expertise was reactive — built in response to pain, stored where it
+couldn't influence behavior.
+
+### With Skill (Good)
+
+Developer adds a SQLite database. Next `/seed` run detects the `*.db`
+file and `better-sqlite3` in dependencies. It says: "I see you've
+adopted SQLite. Projects using SQLite typically benefit from a
+data-integrity cabinet member that watches for type coercion issues, WAL
+mode configuration, migration safety, and backup strategies. Want to
+build one together?"
+
+The developer says yes. They spend 10 minutes in conversation: "We're
+using WAL mode, our biggest risk is concurrent writes from the sync
+process, and we've had issues with empty-string-vs-NULL before." The
+resulting cabinet member is specific to this project's actual risks. It
+activates during audits and catches the NULL coercion bug before it
+ships.
+
+The expertise was proactive — built at the moment of adoption, stored
+where it actively influences every audit cycle.