create-claude-cabinet 0.6.0

package/templates/skills/onboard/SKILL.md

@@ -0,0 +1,356 @@
+---
+name: onboard
+description: |
+  Assemble the cabinet. Interviews you about your project and prepares the
+  briefings your cabinet members need to do their jobs — who you are, what
+  you're building, where things live, what matters. Re-runnable as the
+  project matures — each run refines based on what the project has learned.
+  Use when: "onboard", "set up CoR", "bootstrap", "/onboard".
+related:
+  - type: file
+    path: .claude/skills/onboard/phases/detect-state.md
+    role: "Detect existing CoR artifacts and determine run mode"
+  - type: file
+    path: .claude/skills/onboard/phases/interview.md
+    role: "Conversational interview questions"
+  - type: file
+    path: .claude/skills/onboard/phases/work-tracking.md
+    role: "Choose work tracking system (SQLite vs markdown vs external)"
+  - type: file
+    path: .claude/skills/onboard/phases/options.md
+    role: "Structured decision points before generation"
+  - type: file
+    path: .claude/skills/onboard/phases/generate-briefing.md
+    role: "Generate or update briefing files"
+  - type: file
+    path: .claude/skills/onboard/phases/generate-session-loop.md
+    role: "Wire orient/debrief phase files"
+  - type: file
+    path: .claude/skills/onboard/phases/modularity-menu.md
+    role: "Present opt-in modules"
+  - type: file
+    path: .claude/skills/onboard/phases/summary.md
+    role: "Present what was generated/changed"
+  - type: file
+    path: .claude/skills/onboard/phases/post-onboard-audit.md
+    role: "Configuration sanity check after generation"
+---
+
+# /onboard — Assemble the Cabinet
+
+## Purpose
+
+Assemble the cabinet. Before your advisors can do their jobs, they need
+briefings — who you are, what you're building, where things live, what
+matters. Without briefings, the session loop runs blind: orient reads
+files that don't exist, debrief records lessons into a structure that
+hasn't been defined, plan looks for overlap in a work tracker that
+hasn't been wired.
+
+Onboard fills this gap through conversation, not mechanical config. It
+interviews you about your project — like sitting down with a new hire
+and walking them through how things work here. The answers become the
+briefings your cabinet reads before every session. It's deliberately
+conversational because the best briefing comes from the person who
+lives with the project, not from scanning a directory tree.
+
+This is a **skeleton skill** using the `phases/` directory pattern. The
+orchestration is generic — detect state, interview, generate files. Your
+project customizes the specifics in phase files under `phases/`.
+
+### Phase File Protocol
+
+Phase files have three states:
+
+| State | Meaning |
+|-------|---------|
+| Absent or empty | Use this skeleton's **default behavior** for the phase |
+| Contains only `skip: true` | **Explicitly opted out** — skip this phase entirely |
+| Contains content | **Custom behavior** — use the file's content instead |
+
+The skeleton always does something reasonable when a phase file is absent.
+Phase files customize, not enable. Use `skip: true` when you actively
+don't want a phase to run — not even the default.
+
+## Three Modes
+
+Onboard is re-runnable. What it does depends on what already exists:
+
+### 1. First Run (no _briefing.md)
+
+No CoR briefing layer exists yet. This is the full interview: who are you,
+what is this, what breaks, what do you need. Generates the complete
+initial briefing layer — `_briefing.md`, CLAUDE.md additions, system-status.md,
+and session loop wiring. The goal is a working session loop by the end of
+the conversation.
+
+### 2. Early Re-Run (sparse artifacts)
+
+Some CoR artifacts exist but the project is young. The session loop has
+run a few times and the user has learned what works and what doesn't.
+The interview shifts to refinement: What has the session loop taught you
+that CLAUDE.md doesn't reflect? What friction have you hit? What briefing
+is missing that orient keeps needing? This mode proposes updates to
+existing files rather than creating new ones.
+
+### 3. Mature Re-Run (rich context)
+
+The project has been using CoR for a while. Briefing files are populated,
+multiple modules are active, patterns have accumulated. The interview
+becomes a health check: Which modules are you actually using? Is anything
+ready to retire? What gaps have you noticed? Are there new areas the
+system should cover? This mode may propose removing or simplifying things
+as often as adding them.
+
+The mode is detected automatically in the detect-state phase. The user
+doesn't have to declare it.
+
+## Why This Matters
+
+Every CoR skill reads from the briefing layer. Orient reads `_briefing.md`
+to know what files to check. Plan reads it to know where work items live.
+Cabinet members read it to know where to look. If the briefing layer is empty
+or wrong, every skill downstream is degraded. Onboard is the foundation
+pour — invisible when it's done right, catastrophic when it's missing.
+
+The re-run capability matters because projects change. The briefing that
+was accurate at day one drifts as the project grows, shifts direction, or
+discovers new pain points. Onboard is not a one-time setup wizard — it is
+the periodic recalibration that keeps the briefing layer honest.
+
+## Workflow
+
+### 1. Detect State
+
+Read `phases/detect-state.md` for how to scan existing CoR artifacts.
+
+**Default (absent/empty):** Scan for the standard CoR artifact set:
+`_briefing.md`, `system-status.md`, `orient/phases/`, `debrief/phases/`,
+`pib.db`, `committees.yaml`, `memory/patterns/`. Count what exists, classify
+its richness (empty file vs populated), and determine the run mode. Report
+findings so subsequent phases know whether they're generating, refining,
+or health-checking.
+
+In first-run mode, this phase is fast — almost nothing exists. In re-run
+modes, it provides the inventory that the interview phase uses to ask
+targeted questions.
+
+### 2. Interview
+
+Read `phases/interview.md` for the conversational questions adapted to
+the detected mode.
+
+**Default (absent/empty):**
+
+In first-run mode, start with the foundational questions: What is this
+project? What technology stack? Who works on it? What pain points led
+you here? What breaks silently? What do you wish Claude knew about this
+project from the start?
+
+In early re-run mode, shift to refinement: What has the session loop
+taught you that the briefing files don't capture? What does orient miss?
+What does debrief fail to close? Where is there friction?
+
+In mature re-run mode, shift to health: Which modules are you actually
+using? Anything that felt useful at first but isn't anymore? Gaps you've
+noticed in coverage? Any pain points that the system should have caught
+by now?
+
+This is a conversation, not a form. Ask 2-3 questions at a time, not all
+at once. Follow up on answers — if the user mentions a pain point, dig
+into it. If something sounds like it maps to a specific CoR module, note
+it for the modularity menu phase. The interview is the most valuable
+phase because it captures knowledge that no amount of file scanning can
+surface.
+
+### 3. Work Tracking
+
+Read `phases/work-tracking.md` for how to present work tracking options.
+
+**Default (absent/empty):** Detect existing work tracking (pib.db,
+tasks.md, GitHub Issues, custom phase files). Present two built-in
+options — SQLite database (pib-db) or markdown file (tasks.md) — plus
+bring-your-own for external systems. User picks one, the other, or
+neither. The choice is recorded in `.corrc.json` under `workTracking`
+and feeds into generate-briefing and generate-session-loop.
+
+### 4. Options
+
+Read `phases/options.md` for how to present structured decision points.
+
+**Default (absent/empty):** If the interview revealed open decisions
+(tech stack undecided, architecture unclear, "what would you recommend?"),
+present 2-3 options per decision with trade-offs. Uses architecture and
+boundary-man cabinet members internally to evaluate each option.
+Skips automatically when the user already has clear opinions or this is
+a re-run.
+
+The user's choices feed into generate-briefing. Deferred decisions are
+noted as open questions in `_briefing.md`.
+
+### 5. Generate Briefing
+
+Read `phases/generate-briefing.md` for how to create or update the briefing
+layer from interview answers.
+
+**Default (absent/empty):**
+
+In first-run mode, generate:
+- `_briefing.md` from the `_briefing-template.md` — populated with the
+  project's identity, stack, principles, architecture, and scan scopes
+- CLAUDE.md additions — project-specific instructions that Claude should
+  always follow
+- `system-status.md` — initial state tracking file
+
+In re-run mode, propose specific updates to existing files. Show what
+would change as diffs — never overwrite without showing the delta. Let
+the user approve, modify, or reject each change. The user owns their
+briefing files; onboard proposes, never imposes.
+
+### 6. Generate Session Loop
+
+Read `phases/generate-session-loop.md` for how to wire orient and debrief
+phase files.
+
+**Default (absent/empty):**
+
+In first-run mode, create the minimal phase files that make the session
+loop functional:
+- `orient/phases/context.md` pointing at the files generated in step 5
+- Any other orient phase files needed based on what the interview revealed
+  (e.g., `data-sync.md` if the project has a remote data store)
+- Debrief phase files if the interview revealed specific close-of-session
+  needs
+
+Reference existing skeleton defaults — only create phase files that need
+to diverge from defaults. If the default behavior for a phase is already
+correct for this project, don't create a file that restates the default.
+
+In re-run mode, examine existing phase files and propose refinements based
+on what the interview surfaced. If the user said "orient never shows me X,"
+that's a signal to update the work-scan or health-checks phase.
+
+### 7. Modularity Menu
+
+Read `phases/modularity-menu.md` for which CoR modules to present.
+
+**Default (absent/empty):** Present the module hierarchy with adoption
+recommendations based on the interview. The session loop is always set up.
+Other modules are presented with clear descriptions of what they add and
+what they cost in complexity. The user opts in to what makes sense now —
+they can always add more later.
+
+In re-run mode, show what's adopted alongside what's available. Surface
+retirement candidates — modules that were adopted but aren't being used.
+
+### 8. Summary
+
+Read `phases/summary.md` for how to present results.
+
+**Default (absent/empty):** Present what was generated or changed, what
+was skipped, and what to do next. Emphasize progressive refinement: these
+files are a starting point, not a finished product. They'll improve
+through use as orient and debrief reveal what's missing.
+
+In re-run mode, present a before/after view: what the briefing layer
+looked like before, what changed, and why.
+
+### 9. Post-Onboard Audit
+
+Read `phases/post-onboard-audit.md` for the configuration sanity check.
+
+**Default (absent/empty):** Run a lightweight audit from the cor-health
+cabinet member, scoped to what was just generated. Checks interview–config
+coherence (did mentioned technologies get wired into phase files?),
+module–phase alignment (do phase files reference skipped modules?),
+structural basics (do referenced files exist?), and first-session
+readiness (will orient work on its first run?).
+
+If everything checks out, one line: "Configuration looks clean." If
+issues are found, present them and offer to fix immediately. This is a
+pre-flight check, not a deferred finding.
+
+## Phase Summary
+
+| Phase | Absent = | What it customizes |
+|-------|----------|-------------------|
+| `detect-state.md` | Default: scan standard CoR artifacts | What artifacts to scan and how to determine mode |
+| `interview.md` | Default: mode-adapted questions | What to ask and how to follow up |
+| `work-tracking.md` | Default: detect & present choices | What work tracking system to use (pib-db, markdown, or external) |
+| `options.md` | Default: present decisions with trade-offs | What decisions to surface and how to frame options |
+| `generate-briefing.md` | Default: create/update _briefing.md, CLAUDE.md, system-status.md | What files to generate and how |
+| `generate-session-loop.md` | Default: wire orient/debrief phases | How to set up the session loop |
+| `modularity-menu.md` | Default: present module hierarchy | Which modules to present and how |
+| `summary.md` | Default: present changes + next steps | How to present results |
+| `post-onboard-audit.md` | Default: cor-health sanity check | What to verify after generation |
+
+## Conversational Stance
+
+Onboard is a companion, not a configurator. The framing is "let's figure
+out what your project needs" — not "I'll set up your system now." The
+interview is genuine curiosity about the project, not a checklist to get
+through. When the user describes a pain point, the right response is to
+understand it, not to immediately map it to a CoR module.
+
+This matters because the quality of the briefing layer depends on the
+quality of the conversation. A mechanical interview produces mechanical
+briefing files. A genuine conversation about what the project needs, what
+breaks, what matters — that produces briefing files worth reading.
+
+Concrete stance markers:
+- "Tell me about this project" not "Please provide your project description"
+- "What breaks that nobody notices?" not "List your system's failure modes"
+- "Based on what you've described, I think X would help because..." not
+  "Module X is recommended for projects with these characteristics"
+- Ask why, not just what. The reasoning behind a pain point often reveals
+  the right response better than the symptom itself.
+
+## 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 adopters add:
+- Team onboarding (multi-person context: who knows what, communication norms)
+- Migration import (pull context from an existing system being replaced)
+- Integration discovery (scan for connected services, APIs, databases)
+- Compliance baseline (capture regulatory or policy constraints upfront)
+
+## Calibration
+
+**Core failure this targets:** Starting CoR adoption with empty context
+files, causing the session loop to run without knowing anything about the
+project it's supposed to help.
+
+### Without Skill (Bad)
+
+A project adopts CoR. They copy the skeleton files, run `/orient` — it
+reads a blank `_briefing.md` and an empty `system-status.md`, reports
+nothing useful. They run `/debrief` — it tries to close work items but
+doesn't know where work is tracked. They create a plan — cabinet members
+activate but have no project briefing to ground their findings in. Every
+skill technically runs but none of them know enough to be useful.
+
+The user fills in briefing files manually, guessing at what sections
+matter. They miss the scan scopes section entirely, so cabinet members
+can't find the right directories. They write a project description that's
+too abstract to be actionable. Three weeks later, they're still
+discovering context gaps one at a time.
+
+### With Skill (Good)
+
+A project adopts CoR and runs `/onboard`. The interview asks what the
+project is, what stack it uses, what hurts. The user mentions they have a
+Rails app with a PostgreSQL database, three developers, and a recurring
+problem with stale feature flags. From the conversation, onboard generates
+a `_briefing.md` with the right scan scopes, a `system-status.md` that
+tracks feature flag freshness, and orient phase files that check the
+database and flag stale flags at session start.
+
+The session loop works from day one because it knows what to look at.
+Two weeks later, the user runs `/onboard` again. "Orient is great but it
+never mentions the deploy pipeline." Onboard proposes adding a
+health-check phase for deploy status. The briefing layer grows from use,
+not from guessing.

package/templates/skills/onboard/phases/detect-state.md

@@ -0,0 +1,79 @@
+# Detect State — Scan Claude Cabinet Artifacts and Determine Mode
+
+Scan the project for existing CoR artifacts to determine whether this is
+a first run, early re-run, or mature re-run. The mode determination
+drives how every subsequent phase behaves.
+
+When this file is absent or empty, the default behavior is: scan for the
+standard CoR artifact set, classify each artifact's richness, and
+determine the mode. To explicitly skip state detection (force first-run
+mode), write only `skip: true`.
+
+## Fast Path
+
+Check for `_briefing.md` (or `cabinet/_briefing.md`).
+If it doesn't exist, the mode is **first-run** — skip the full scan and
+move to the interview immediately. No need to check 10 artifact types
+when the primary signal is absent.
+
+Also read `.corrc.json` if it exists — it records which modules the CLI
+installed and which were skipped (with reasons). The interview phase uses
+this to skip redundant questions.
+
+## User-Level State
+
+Before scanning the project, check the user-level layer:
+
+- **`~/.claude/CLAUDE.md`** — does a user profile exist? If yes, the
+  interview can skip identity questions. If it's sparse or stale (e.g.,
+  mentions a role the user seems to have moved past), flag it for the
+  interview phase to offer an update.
+- **`~/.claude/cor-registry.json`** — how many other projects does this
+  user have? The interview phase uses this to ask about relationships
+  between projects. If the registry doesn't exist, skip — the user may
+  have installed via npm instead of the shell installer.
+
+## Full Scan (re-runs only)
+
+Only when `_briefing.md` exists, scan these artifacts to distinguish
+early vs mature re-run:
+
+| Artifact | Path Pattern | Indicates |
+|----------|-------------|-----------|
+| System status | `system-status.md` | State tracking exists |
+| Orient phases | `.claude/skills/orient/phases/*.md` | Session loop is wired |
+| Debrief phases | `.claude/skills/debrief/phases/*.md` | Session loop is wired |
+| Work tracking DB | `pib.db` | Work tracking is active |
+| Cabinet committees | `committees.yaml` or `cabinet/committees.yaml` | Audit system configured |
+| Memory patterns | `memory/patterns/*.md` or `.claude/memory/patterns/*.md` | Feedback loop is active |
+| CLAUDE.md | Root `CLAUDE.md` | Project instructions exist |
+| Rules files | `.claude/rules/*.md` | Scoped instructions exist |
+| Hook config | `.claude/settings.json` or `.claude/settings.local.json` | Enforcement hooks exist |
+
+**Early re-run:** Fewer than 5 of the above are populated.
+**Mature re-run:** 5 or more are populated.
+
+## Output
+
+For first-run: `Mode: first-run` — that's it. Move on.
+
+For re-runs, report a structured summary that subsequent phases can
+reference:
+
+```
+Mode: early-rerun | mature-rerun
+
+Artifacts found:
+  - system-status.md: populated
+  - orient phases: 3 files (context.md, work-scan.md, health-checks.md)
+  - pib.db: absent
+  - memory patterns: 4 files
+  ...
+
+Summary: Early re-run. Session loop is wired but work tracking and
+audit are not yet active. Context layer is 3 weeks old.
+```
+
+This summary is not presented to the user directly — it feeds into the
+interview phase so questions can be targeted. The user sees the mode
+reflected in the questions they're asked, not as a diagnostic report.

package/templates/skills/onboard/phases/generate-briefing.md

@@ -0,0 +1,127 @@
+# Generate Briefing — Create or Update Briefing Files
+
+Transform interview answers into the files that make the rest of Claude Cabinet
+functional. This is where conversation becomes infrastructure — but it
+is always a proposal, never an imposition.
+
+When this file is absent or empty, the default behavior is: generate
+or update files as described below, always showing the user what will
+be created or changed before writing. To explicitly skip briefing
+generation, write only `skip: true`.
+
+## First-Run Generation
+
+Create split briefing files from interview answers. The cabinet system
+uses focused files instead of one monolith — see `_briefing-template.md`
+for the full architecture guide.
+
+### Always generate
+
+**`_briefing.md`** — The hub/index file. Lists which briefing files were
+created and a one-line summary of each. Always created first.
+
+**`_briefing-identity.md`** — Use `_briefing-identity-template.md` as the
+starting point. Populate from interview answers:
+- **What This Project Is** — from identity questions
+- **Core Principles** — from pain points and priorities
+- **User Context** — from who works on the project
+
+**`_briefing-architecture.md`** — Use `_briefing-architecture-template.md`.
+Populate from interview answers:
+- **System Structure** — from tech stack and architecture discussion
+- **Codebase Layout** — from where code lives
+- **Technology Stack** — from frameworks, libraries, databases discussed
+
+### Generate if interview covered it
+
+**`_briefing-scopes.md`** — Use `_briefing-scopes-template.md`. Only create
+if the interview revealed specific paths and locations. Populate from
+architecture discussion (where does code live, where is the DB, where
+are deploy configs?). Only fill in sections that have real content.
+
+**`_briefing-cabinet.md`** — Use `_briefing-cabinet-template.md`. Only
+create after cabinet member selection (during or after onboard). Lists which
+cabinet members are active and how they're grouped.
+
+**`_briefing-work-tracking.md`** — Use `_briefing-work-tracking-template.md`.
+Only create if work tracking was discussed in the interview — where items
+live, how to query them, how to mutate them.
+
+**`_briefing-api.md`** — Use `_briefing-api-template.md`. Only create if
+the project has an API and the interview covered endpoints, auth, or
+entity types.
+
+### Rules
+
+- **Never generate empty files.** Only create a briefing file if the
+  interview produced real content for it. An absent file is better than
+  one full of placeholders.
+- **The hub lists what exists.** After creating individual files, update
+  `_briefing.md` to index them with one-line summaries.
+- **Old monolithic format still works.** If migrating from an existing
+  monolithic `_briefing.md`, `/cor-upgrade` handles the split. Don't
+  rewrite an existing monolith during onboard re-runs — propose the
+  migration instead.
+
+### CLAUDE.md Additions
+
+If the project already has a CLAUDE.md, propose additions — don't
+overwrite. If it doesn't, generate an initial one with:
+- Project description (1 paragraph)
+- Key files and directories
+- Conventions and constraints from the interview
+- Any "Claude should always/never" rules that emerged
+
+### system-status.md
+
+Create an initial state tracking file with:
+- What's built (current state of the project)
+- What's active (current focus areas)
+- What's planned (near-term intentions from the interview)
+
+Keep it concise. This file gets updated every debrief — it doesn't
+need to be comprehensive on day one.
+
+## Re-Run Updates
+
+For existing files, never overwrite silently. The protocol:
+
+1. Read the current file content
+2. Identify what the interview suggests should change
+3. Present proposed changes as clear before/after diffs
+4. Let the user approve, modify, or reject each change
+5. Apply approved changes
+
+Common re-run updates:
+- Adding scan scopes that were missing (user said "cabinet members never
+  check my tests directory")
+- Updating architecture sections after a stack change
+- Adding new core principles discovered through use
+- Updating work tracking configuration after switching tools
+- Removing stale information that no longer applies
+
+## Update Project Registry
+
+After generating the briefing layer, update `~/.claude/cor-registry.json`
+with what you learned from the interview. The installer registers the
+project with just its folder name and an empty description — onboard
+is where the real name and description get filled in.
+
+Find this project's entry by path and update:
+- **`name`** — the project's actual name (from the interview, not the
+  folder name, unless they match)
+- **`description`** — one line about what the project does
+
+This is a silent update — don't ask the user to confirm registry changes
+separately. The information already came from the interview.
+
+## Quality Standards
+
+- **Populated, not padded.** Every section should contain real project
+  information, not generic advice or placeholder text.
+- **Specific paths, not patterns.** "Server code lives in `src/server/`"
+  not "The server code directory."
+- **Decisions, not descriptions.** "We use PostgreSQL because X" carries
+  more context than "Database: PostgreSQL."
+- **The user's voice.** Use language from the interview. If they called
+  it "the deploy pipeline" don't write "CI/CD infrastructure."

package/templates/skills/onboard/phases/generate-session-loop.md

@@ -0,0 +1,87 @@
+# Generate Session Loop — Wire Orient and Debrief Phase Files
+
+Create or refine the phase files that make the session loop functional
+for this specific project. The session loop is the mandatory minimum —
+orient reads state, debrief writes state, and the project gets smarter
+with each session.
+
+When this file is absent or empty, the default behavior is: create the
+minimal set of phase files that diverge from skeleton defaults, based
+on what the interview revealed. To explicitly skip session loop wiring,
+write only `skip: true`.
+
+## First-Run Wiring
+
+The skeleton defaults handle many cases. Only create phase files where
+this project needs something different from the default.
+
+### Always Create
+
+**`orient/phases/context.md`** — Point at the briefing files generated in
+the previous phase. At minimum:
+- Read `_briefing.md` for project identity and configuration
+- Read `system-status.md` for current state
+- Read `CLAUDE.md` if it has project-specific instructions beyond what
+  Claude Code auto-loads
+
+### Create If Interview Revealed
+
+**`orient/phases/data-sync.md`** — If the project has a remote canonical
+data store (database on a server, shared file storage, external API that
+needs fresh pulls). Include the specific sync commands.
+
+**`orient/phases/work-scan.md`** — If the project uses a specific work
+tracking system that differs from pib-db defaults (e.g., GitHub Issues,
+Linear, a custom backlog file). If they're using pib-db, the default
+work-scan behavior already handles it — don't create a redundant file.
+
+**`orient/phases/health-checks.md`** — If the interview surfaced specific
+failure modes worth detecting at session start (stale deploys, broken
+connections, configuration drift).
+
+**`debrief/phases/close-work.md`** — If work items need to be closed in
+a specific system (API calls, issue tracker commands). If using pib-db,
+the default handles it.
+
+**`debrief/phases/update-state.md`** — If state lives somewhere specific
+that the default (check system-status.md) wouldn't find.
+
+### Never Create Redundantly
+
+Don't create a phase file that restates the skeleton's default behavior.
+If the default is correct, leave the file absent. Phase files exist to
+customize, not to document that the default is fine.
+
+Compare what the skeleton says it does by default (in the orient and
+debrief SKILL.md files) with what this project needs. Only write a phase
+file where they diverge.
+
+## Re-Run Refinements
+
+In re-run mode, the session loop is already wired. Examine existing
+phase files in the context of what the interview revealed:
+
+- **Missing coverage:** User said "orient never mentions X" — does a
+  phase file need to be created or updated to scan for X?
+- **Noisy phases:** User said "the health check for Y fires every session
+  but it's never a real problem" — should that check be removed or have
+  its threshold adjusted?
+- **Stale wiring:** Phase files reference paths or commands that have
+  changed since initial onboard. Update them.
+- **Default promotion:** A project that's been using the default work-scan
+  may have outgrown it. If the interview suggests the default isn't enough,
+  create a custom phase file.
+
+Present proposed changes as diffs against current content. Let the user
+approve before modifying existing phase files.
+
+## Structural Principles
+
+- **Minimal divergence.** The fewer custom phase files, the less
+  maintenance burden. Defaults exist for a reason.
+- **Specific commands.** Phase files should contain the exact commands,
+  queries, or file paths — not descriptions of what to do. "Run
+  `sqlite3 app.db 'SELECT ...'`" not "Check the database for stale items."
+- **Fail gracefully.** Every phase file should handle the case where its
+  target doesn't exist yet (DB not initialized, file not created, service
+  not running). Surface the gap, don't crash.