create-claude-cabinet 0.6.0

package/templates/skills/onboard/phases/interview.md

@@ -0,0 +1,233 @@
+# Interview — Conversational Questions Adapted to Mode
+
+The heart of onboarding. This is a dialogue, not a form — ask questions,
+listen to answers, follow up on what's interesting or unclear. The quality
+of the briefing layer depends directly on the quality of this conversation.
+
+When this file is absent or empty, the default behavior is: ask mode-
+adapted questions as described below, one at a time, with follow-ups.
+To explicitly skip the interview (e.g., when generating context from
+existing documentation), write only `skip: true`.
+
+## System Introduction (First Run Only)
+
+Before asking about the project, check: does the user know what Claude
+on Rails does? Ask once:
+
+> "Have you used Claude Cabinet before, or is this your first time?"
+
+If **first time**, give a brief walkthrough before the interview:
+
+> "Let me explain how this works, then we'll set it up for your project.
+>
+> Claude Cabinet gives your Claude Code sessions a **session loop** —
+> a start and end routine that creates continuity between sessions.
+>
+> - **`/orient`** — you type this at the start of a session. It reads
+>   where things stand — what you were working on, what's due, what
+>   broke. Instead of starting blind, Claude starts informed.
+> - **`/debrief`** — you type this at the end of a session. It records
+>   what happened — what got done, what's still open, what you learned.
+>   That's what orient reads next time.
+>
+> Neither runs automatically — you invoke them when you're ready. If
+> you forget `/debrief`, Claude will nudge you before the session ends.
+>
+> Beyond the session loop, there are optional modules: **work tracking**
+> (a local task database), **planning** (structured plans with critique
+> before you build), **audit** (expert cabinet members that review your
+> codebase), and more. We'll get to those after we talk about your project.
+>
+> The whole system is customizable through small files called phase files.
+> You don't need to touch them now — that's what this onboarding does."
+
+Then proceed to the interview. Keep it conversational — if they ask
+questions about the system, answer them before moving on.
+
+If **experienced** (they've used it before, or say "I know how it works"),
+skip the walkthrough entirely and go straight to the interview.
+
+## User Context (Read Before Interviewing)
+
+Before asking any questions, read two global files if they exist:
+
+1. **`~/.claude/CLAUDE.md`** — the user's identity and preferences.
+   If this has an "About Me" section, you already know who they are
+   and what they do. Don't re-ask questions this answers. Acknowledge
+   it: "I see you run a real estate fund — let's talk about how this
+   project fits into that."
+
+2. **`~/.claude/cor-registry.json`** — a list of all their CoR projects.
+   If they have other projects registered, explain what that means and
+   ask how this project relates: "I see you're also using Claude on
+   Rails in [project X] — that's a separate project you've set up with
+   the same session loop. Does this project connect to that one in any
+   way? For example, does one feed data to the other, or do they share
+   code?" The answer goes into `_briefing.md` so orient and debrief can
+   flag when work in one project might affect the other.
+
+If neither file exists, that's fine — the installer may not have created
+them (npm install path, or the user skipped the identity questions).
+Proceed normally.
+
+## Communication Calibration
+
+Don't ask the user how technical they are. Listen to how they talk.
+Within the first 2-3 answers, you'll know whether they reference
+technical concepts naturally or describe things in terms of outcomes.
+Match their register — mirror their vocabulary, explain at the level
+they're engaging at. Don't talk down, don't talk over.
+
+This isn't a variable to detect ("technical_level: 3"). It's a
+conversational stance: meet people where they are. Someone who says
+"I need a REST API with PostgreSQL" gets different follow-ups than
+someone who says "I need a way to track client appointments." Both
+are valid starting points.
+
+## First-Run Questions
+
+The detect-state phase identified this as a first run (no CoR context
+layer exists). But "first run" covers two very different situations:
+
+### Greenfield (no project yet, or near-empty directory)
+
+The user just ran the CLI in an empty or near-empty directory. There's
+nothing to scan, no workflow to reflect on yet. Questions must be
+**forward-looking** — about intentions, not retrospection.
+
+**Questions (ask one at a time, in order — skip or reorder based on
+what the conversation reveals):**
+1. What are you trying to build?
+2. What will you be using Claude Code for on this project?
+3. How do you usually keep track of what needs to be done?
+4. Will anyone else be working on this with you?
+5. Have you struggled with anything on past projects that you'd want
+   to get ahead of this time?
+6. How big is this? A weekend project, something you'll be working on
+   for months?
+7. What does done look like, roughly?
+
+**Follow-up instincts:**
+- If they describe something ambitious, ask what the first milestone is
+- If they mention past frustrations, dig into what specifically went wrong
+- If they're vague about the project, that's fine — they may be figuring
+  it out. Ask what they know so far and what's still open
+- If they mention collaborators, ask how they'll coordinate
+
+### Existing Project (source files, config, or meaningful content present)
+
+The user ran the CLI in a project that already has substance. There are
+files to scan — use them for tech detection instead of asking. Focus the
+conversation on **work and pain**, not tooling.
+
+**Before asking:** Scan the project for tech signals (package.json,
+Cargo.toml, requirements.txt, Dockerfile, .github/, etc.). Note what
+you find — it informs your follow-ups but doesn't replace the
+conversation. Don't announce what you found; weave it in naturally.
+
+**Questions (ask one at a time, in order — skip or reorder based on
+what the conversation reveals):**
+1. Tell me about this project. What does it do?
+2. What are you mainly working on right now?
+3. What tends to break or get forgotten?
+4. What do you wish Claude knew about this project from the very start
+   of every session?
+5. Is there anything that fails silently — things that go wrong without
+   anyone noticing until it's too late?
+6. How do you currently keep track of what needs to be done?
+7. What does a typical working session on this project look like?
+8. Is there a deploy pipeline or remote environment?
+
+**Follow-up instincts:**
+- If someone mentions a pain point, ask *why* it happens and how often
+- If someone says "it's just me," ask how they keep context between sessions
+- If someone mentions a team, ask about handoff friction
+- If someone describes their workflow, listen for things that could be
+  automated or checked
+
+## Early Re-Run Questions
+
+The session loop has been running. Shift from "what is this" to "what
+have you learned."
+
+**Questions (ask one at a time, in order — skip or reorder based on
+what the conversation reveals):**
+1. What has the session loop taught you that the briefing files don't
+   currently capture?
+2. Does orient give you what you need at session start? What's missing?
+3. Does debrief close the right loops? What falls through?
+4. Where have you hit friction with the current setup?
+5. Are there things you keep having to tell Claude that should already be
+   in the briefing?
+6. Any phase files that aren't pulling their weight?
+7. Has the project changed since the initial onboard?
+8. Are you ready for any of the modules you skipped last time?
+9. Anything you've been doing manually that should be automated?
+
+## Mature Re-Run Questions
+
+The system has been running long enough to accumulate both value and
+cruft. This is a health check.
+
+**Questions (ask one at a time, in order — skip or reorder based on
+what the conversation reveals):**
+1. Which modules are you actually using regularly?
+2. Anything that felt useful at first but you've stopped relying on?
+3. Are there modules you adopted but never really configured properly?
+4. What gaps have you noticed? Things the system should catch but doesn't.
+5. Has the project's architecture or priorities shifted since the last
+   onboard run?
+6. Any new pain points that weren't there before?
+7. Is anything ready to retire?
+8. Could any of your custom phase files be simplified now that you know
+   what you actually need?
+9. Are there patterns in your memory/feedback that suggest a structural
+   change rather than another rule?
+
+## Scope Boundary
+
+You are configuring the **process layer** — what Claude should know about
+this project, how sessions start and end, what to track and check. You
+are NOT:
+
+- Recommending tech stacks, frameworks, or architecture
+- Advising on what to build or how to build it
+- Making product decisions
+
+If the user asks "what should I use?" or "what do you recommend?" for
+their actual project, redirect: "That's a great question for your first
+working session after we finish setup. Right now I'm just learning about
+your project so the session loop knows what to look for. What do you
+know so far about what you'll be building?"
+
+Record what they tell you about their intentions and tools — that goes
+into `_briefing.md`. But choosing those tools is their decision, not
+onboard's job.
+
+## Conversation Guidelines
+
+- **One question at a time.** Ask a single question, wait for the answer,
+  then ask the next one. Never stack multiple questions in one message.
+  The rounds below are a *sequence*, not a batch — each bullet is its own
+  turn. Follow-ups based on the answer take priority over the next
+  planned question.
+- **Follow up on substance.** If an answer reveals something important,
+  dig into it before moving on to the next topic.
+- **Note CoR module signals.** When someone describes a pain point that
+  maps to a specific module, note it internally for the modularity menu
+  phase — but don't interrupt the conversation to pitch the module.
+- **Don't assume answers.** Even if you can see the project's files, ask
+  about things like pain points and priorities that only the user knows.
+- **Earn the right to ask about specifics.** Don't ask about tech stack,
+  deployment pipelines, or architecture until the conversation has shown
+  the user has context to give a meaningful answer. Lead with open
+  questions ("tell me about this project") and let specifics emerge
+  naturally. If the user is non-technical or early in their thinking,
+  those questions may never be appropriate — and that's fine.
+- **Summarize before generating.** After the interview, reflect back what
+  you heard: "Here's what I'm taking away from this conversation..." Let
+  the user correct before generating files.
+- **For skipped modules (.corrc.json):** If the CLI's `skipped` field
+  shows a module was opted out with a reason, weave that into the
+  conversation naturally. "I see you're tracking work somewhere else —
+  tell me about that" rather than "Module work-tracking was skipped."

package/templates/skills/onboard/phases/modularity-menu.md

@@ -0,0 +1,162 @@
+# Modularity Menu — Present Opt-In Modules
+
+Present the Claude Cabinet module hierarchy so the user can decide what to adopt now
+and what to defer. The session loop is mandatory; everything else is
+opt-in. Progressive adoption means starting with what you need and adding
+modules as the project matures.
+
+When this file is absent or empty, the default behavior is: read
+`.corrc.json` for module selections made during CLI install, then present
+the module hierarchy with that context. To explicitly skip the menu,
+write only `skip: true`.
+
+## Reading CLI Selections (.corrc.json)
+
+If `.corrc.json` exists in the project root, the CLI has already asked
+about module selections. Read the `modules` and `skipped` fields:
+
+- **Installed modules** (`modules` map, value `true`): These are already
+  set up. Don't re-ask. Confirm what's installed and move on.
+- **Skipped modules** (`skipped` map, with reasons): The user opted out
+  during CLI install. The reason matters — it tells you what alternative
+  to ask about. For example:
+  - `"work-tracking": "User has existing Railway API"` → ask how they
+    track work so you can wire phase files to their system
+  - `"work-tracking": "Not needed yet"` → note it's available later, move on
+  - `"audit": "Project too small"` → respect the decision, note the threshold
+
+For skipped modules with alternatives, the interview (previous phase)
+should have already asked about the alternative system. Use those answers
+here to confirm the wiring plan.
+
+If `.corrc.json` doesn't exist (manual install or pre-npm adoption),
+fall back to presenting the full menu as described below.
+
+## Module Hierarchy
+
+Present these in order from most fundamental to most specialized:
+
+### 1. Session Loop (orient + debrief) — MANDATORY
+
+Always set up. This is the minimum viable CoR adoption. Orient reads
+state at session start; debrief writes state at session end. Without
+this, nothing else has a foundation.
+
+**What you get:** Context continuity between sessions. Claude starts
+informed and ends by recording what happened. The project gets smarter
+with each session instead of resetting to zero.
+
+**Cost:** Two phase directories with a few files each. Runs at the
+start and end of every session (adds 30-60 seconds each).
+
+### 2. Work Tracking — RECOMMENDED
+
+How work items are tracked. The work-tracking onboard phase presents the
+options in detail; this is the module-level view.
+
+**Options (chosen during onboard work-tracking phase):**
+- **pib-db (SQLite):** Structured, queryable, local-only. CLI interface.
+  Integrates with plan/execute and audit findings. Requires `better-sqlite3`.
+- **Markdown (tasks.md):** Simple, git-friendly, zero dependencies. Open
+  items are checkbox lines in a file. Good for solo/quick-start projects.
+- **External:** Wire orient/debrief to GitHub Issues, Linear, Jira, etc.
+  You customize phase files after onboard.
+
+**What you get:** Open actions, due dates, flagged items. Orient surfaces
+what needs attention. Debrief marks things done. Plan creates work items.
+
+**Skip if:** You don't need work tracking in the session loop. You can
+always add it later by re-running `/onboard`.
+
+### 3. Planning (plan + execute) — OPT-IN
+
+Structured implementation planning with cabinet member-based critique and
+execution with checkpoints.
+
+**What you get:** Plans that carry enough detail for a future session to
+execute without re-exploring the codebase. Cabinet member agents that
+critique plans before execution. Execution with structured checkpoints.
+
+**Cost:** Plan and execute skill configuration. Cabinet member setup if you
+want critique. Adds deliberation time before building — this is the point.
+
+**Skip if:** Your project's work is mostly small, clear tasks that don't
+benefit from structured planning. Add this module when you start hitting
+edge cases or duplicating work.
+
+### 4. Compliance Stack (rules, hooks) — OPT-IN
+
+Scoped instructions in `.claude/rules/` and deterministic enforcement
+via hooks in `.claude/settings.json`.
+
+**What you get:** Path-specific rules that load automatically (e.g.,
+"when editing tests/, always run the test suite"). Hooks that enforce
+hard guardrails (e.g., block commits without tests, validate file formats).
+
+**Cost:** Rule files and hook scripts that need maintenance. Hooks run on
+every tool invocation — poorly written hooks add latency.
+
+**Skip if:** Your project doesn't yet have recurring mistakes worth
+encoding. Add rules as patterns emerge from debrief lessons.
+
+### 5. Audit Loop (audit + triage-audit + cabinet members) — OPT-IN
+
+Periodic cabinet member analysis of the codebase with structured
+triage of findings.
+
+**What you get:** Semantic analysis by specialized cabinet members (security,
+accessibility, data integrity, etc.). Structured findings with severity
+levels. Triage workflow to accept, defer, or dismiss findings.
+
+**Cost:** Cabinet member configuration, audit runs (LLM-intensive), triage
+time. This is the most expensive module in compute and attention.
+
+**Skip if:** Your project is small enough to review holistically, or
+you're not yet at the stage where systematic quality analysis adds value.
+Add this when the codebase grows beyond what one person can hold in their
+head.
+
+### 6. Capability Seeding (seed) — OPT-IN
+
+Bootstrap new skills, cabinet members, or process components from CoR
+skeleton templates.
+
+**What you get:** Quick scaffolding of new capabilities with all required
+files and wiring in place.
+
+**Cost:** Minimal. This is tooling for extending the system itself.
+
+**Skip if:** You're happy with the modules you have and aren't planning
+to build custom skills or cabinet members. Come back to this when you want
+to extend.
+
+## Presentation Guidelines
+
+- **Present the full menu** so the user sees the landscape, but recommend
+  based on what the interview revealed.
+- **Mark the mandatory module** clearly — the session loop isn't optional.
+- **Connect modules to pain points.** If the user mentioned stale deploys,
+  note that health checks (part of the session loop) address this. If they
+  mentioned duplicated work, note that the planning module helps.
+- **Respect "not yet."** Deferring a module is fine. The menu is always
+  available via re-running onboard.
+
+## Re-Run Presentation
+
+For re-runs, augment the menu with current adoption state:
+
+```
+Module                  Status          Notes
+Session loop            ACTIVE          3 orient phases, 2 debrief phases
+Work tracking           ACTIVE          47 actions, 8 projects
+Planning                ACTIVE          Using plan + execute
+Compliance stack        PARTIAL         2 rules files, no hooks
+Audit loop              NOT ADOPTED     —
+Capability seeding      NOT ADOPTED     —
+```
+
+Also surface:
+- **Retirement candidates:** Modules or phase files that show signs of
+  disuse (e.g., a health check that hasn't fired in weeks)
+- **Growth candidates:** Modules the project seems ready for based on
+  accumulated patterns or interview answers

package/templates/skills/onboard/phases/options.md

@@ -0,0 +1,98 @@
+# Options — Structured Decision Points Before Generation
+
+After the interview and before generating briefing files, surface the key
+decisions that shape how the project and process layer get set up. Present
+options with trade-offs so the user makes informed choices — not Claude
+making choices for them.
+
+When this file is absent or empty, the default behavior is: identify
+decisions implied by the interview, present options, let the user choose.
+To explicitly skip (e.g., the user already has strong opinions from the
+interview), write only `skip: true`.
+
+## When This Phase Activates
+
+Not every onboard needs this. Skip it when:
+- The user described a clear tech stack and workflow (nothing to decide)
+- This is a re-run (decisions were already made)
+- The project is already built and this is process-layer-only
+
+Run it when the interview revealed **open decisions** — things the user
+hasn't settled yet that will affect what briefing files contain:
+
+- "I'm not sure what database to use"
+- "I don't know if I need a backend"
+- "What would you recommend?" (redirected here from the interview)
+- Greenfield project where the user described *what* but not *how*
+
+## How to Present Options
+
+For each open decision, present 2-3 concrete options with trade-offs.
+Use two cabinet members internally (do not spawn agents — just
+reason from these viewpoints):
+
+### Architecture Cabinet Member
+Evaluates each option for: complexity, maintenance burden, whether it
+matches the user's described skill level and project scope. Flags when
+an option is overkill for a weekend project or too lightweight for
+something ambitious.
+
+### Boundary Man
+Evaluates each option for: what breaks first, what's hard to change
+later, what locks you in. Flags irreversible decisions that deserve
+extra thought.
+
+### Format
+
+```
+## [Decision: e.g., "How to store data"]
+
+Based on what you described — [reference specific things from interview] —
+here are your options:
+
+**Option A: [name]**
+- What it is: [1 sentence]
+- Good for: [when this is the right choice]
+- Trade-off: [what you give up]
+
+**Option B: [name]**
+- What it is: [1 sentence]
+- Good for: [when this is the right choice]
+- Trade-off: [what you give up]
+
+**Option C: [name]** (if applicable)
+- ...
+
+What sounds right for your situation?
+```
+
+### Tone
+
+- **Present, don't prescribe.** "Here are your options" not "I recommend X."
+- **Reference the interview.** "You mentioned it's just you and this is a
+  side project, so..." — ground options in their specific situation.
+- **Be honest about complexity.** If one option is simpler but limited,
+  say so. If another is powerful but requires more setup, say so.
+- **Respect "I don't know."** If the user can't decide, suggest starting
+  with the simplest option and note that it can be changed later. Don't
+  pressure decisions.
+
+## What This Is NOT
+
+- **Not architecture consulting.** You present options the interview
+  surfaced, not a comprehensive technology evaluation. If the user wants
+  deep architecture advice, that's a working session topic, not onboard.
+- **Not prescriptive.** Never say "you should use X." Always frame as
+  options with trade-offs.
+- **Not exhaustive.** 2-3 options per decision. Not every possible
+  approach.
+
+## Output
+
+The user's choices feed into generate-briefing. Each decision becomes
+concrete content in `_briefing.md` (architecture section), CLAUDE.md
+(conventions), and potentially orient phase files (what to check).
+
+If the user defers a decision ("I'll figure that out later"), note it
+in `_briefing.md` as an open question — don't leave the section empty
+without explanation.

package/templates/skills/onboard/phases/post-onboard-audit.md

@@ -0,0 +1,121 @@
+# Post-Onboard Audit — Configuration Sanity Check
+
+After generating all files and presenting the summary, run a lightweight
+audit from the cor-health cabinet member to catch configuration issues before
+the user starts their first session.
+
+When this file is absent or empty, the default behavior is: run the audit
+as described below. To explicitly skip it, write only `skip: true`.
+
+## Why This Exists
+
+Onboard generates a lot of files from conversation. The interview is
+freeform — the user might mention a database but the data-sync phase
+doesn't get wired. They might skip a module but a phase file references
+it. They might describe a deployment pipeline but no health check covers
+it. These gaps are invisible until orient runs and something is wrong.
+
+A quick audit immediately after generation catches these before the user
+starts relying on the configuration.
+
+## What to Check
+
+Run as the **cor-health cabinet member** but scoped to what onboard just
+generated. This is NOT a full audit — it's a focused sanity check on
+the fresh configuration.
+
+### 1. Interview–Configuration Coherence
+
+Compare what the interview revealed against what was generated:
+
+- **Technologies mentioned** → Are they reflected in `_briefing.md` scan
+  scopes and relevant phase files?
+- **Pain points described** → Did at least one phase file or health check
+  address each significant pain point?
+- **Data sources mentioned** → Is `data-sync.md` wired if the project has
+  remote data? Is it absent if the project is purely local?
+- **Collaboration details** → If multiple people work on the project, are
+  coordination-relevant checks present?
+
+### 2. Module–Phase Alignment
+
+Cross-reference `.corrc.json` (installed vs skipped modules) against the
+generated phase files:
+
+- **Skipped modules:** No phase file should reference a skipped module's
+  infrastructure. If work-tracking was skipped, no phase should reference
+  `pib.db` or `pib-db.js`. If audit was skipped, no phase should reference
+  `committees.yaml` or cabinet member activation.
+- **Installed modules:** Each installed module should have at least a
+  minimal presence in the generated configuration. A module that's installed
+  but has zero phase file references is a configuration gap.
+
+### 3. Structural Basics
+
+Quick filesystem checks:
+
+- Every generated file is valid markdown (no truncated content, no
+  template placeholders left unfilled)
+- Phase files that reference other files point at files that exist
+- `_briefing.md` has non-empty project description, stack, and scan scopes
+- `system-status.md` exists and has initial content
+- Hook scripts in `.claude/hooks/` are executable (if hooks module adopted)
+
+### 4. Technology-Implied Cabinet Members
+
+Check whether the project's technology signals suggest cabinet members that
+aren't activated. Cross-reference the interview answers and detected
+technologies against the cabinet member catalog:
+
+- **UI framework detected** → usability, accessibility, small-screen
+- **Database detected** → data-integrity
+- **API server detected** → security, speed-freak
+- **Complex architecture (3+ layers/services)** → architecture
+- **Long-running project** → historian
+- **Many skills (5+)** → roster-check
+- **Features shipping regularly** → system-advocate
+
+If implied cabinet members aren't in `committees.yaml` (or equivalent), note
+it as a recommendation — not a blocker. The user may have good reasons
+to skip them, or may want to add them later via `/seed`.
+
+### 5. First-Session Readiness
+
+Simulate what `/orient` will do on its first run:
+
+- Walk through orient's phases mentally. For each phase that will run,
+  verify the files it reads exist and have content.
+- If orient would hit an empty phase that should have content (given what
+  the interview revealed), flag it.
+- If debrief would try to update a file that doesn't exist yet, flag it.
+
+## How to Present
+
+**If everything checks out:** One line after the summary:
+
+> "Configuration looks clean — orient should work on first run."
+
+**If issues are found:** Present them briefly, grouped by severity:
+
+> "Before you run /orient, I noticed a few things:
+>
+> - data-sync.md references your PostgreSQL database, but no connection
+>   details are in the phase file. Orient will try to sync and fail.
+> - The security cabinet member is activated but _briefing.md doesn't include
+>   API routes in its scan scopes — it won't find anything to review.
+>
+> Want me to fix these now?"
+
+Fix issues immediately if the user says yes. This is not a deferred
+finding — it's a pre-flight check.
+
+## What This Is NOT
+
+- **Not a full cor-health audit.** That runs periodically via /audit and
+  covers telemetry, usage patterns, drift over time. This only checks
+  what was just generated.
+- **Not a product quality review.** Whether the _briefing.md is well-written
+  or the health checks are comprehensive — that improves through use.
+  This just checks that the configuration is structurally sound.
+- **Not blocking.** If the audit finds issues and the user wants to move
+  on, let them. The issues will surface again naturally when orient runs.