create-claude-cabinet 0.6.0

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

@@ -0,0 +1,122 @@
+# Summary — Present What Was Generated or Changed
+
+Close the onboard session with a clear accounting of what happened,
+what was deferred, and what comes next. The user should leave knowing
+exactly what files exist, what they do, and what the next step is.
+
+When this file is absent or empty, the default behavior is: present a
+structured summary as described below. To explicitly skip the summary,
+write only `skip: true`.
+
+## First-Run Summary
+
+Present three sections:
+
+### Files Generated
+
+List every file that was created, with a one-line description of what
+it does and where it's read:
+
+```
+Created:
+  cabinet/_briefing.md
+    Project identity and configuration. Read by all cabinet members.
+
+  system-status.md
+    Current state tracking. Read by orient, updated by debrief.
+
+  .claude/skills/orient/phases/context.md
+    What orient reads at session start. Points at _briefing.md and
+    system-status.md.
+
+  .claude/skills/orient/phases/data-sync.md
+    How to pull fresh data from [remote store]. Runs at session start.
+```
+
+### Modules Adopted
+
+List which modules were selected and what they provide:
+```
+Adopted:
+  Session loop (orient + debrief) — MANDATORY
+  Work tracking (pib-db) — set up with initial backlog
+
+Deferred:
+  Planning — will revisit when task complexity increases
+  Compliance stack — no recurring patterns to encode yet
+  Audit loop — codebase too small for systematic review
+  Capability seeding — not needed yet
+```
+
+### What to Do Next
+
+Concrete next steps, not abstract advice:
+- "Run `/orient` to start your first CoR session. It will read the
+  briefing files we just generated."
+- "After your first working session, run `/debrief` to close the loop."
+- "The briefing files are rough. After 3-5 sessions, run `/onboard` again
+  to refine based on what you've learned."
+
+Emphasize progressive refinement: these files are a starting point. The
+session loop will reveal what's missing, and re-running onboard captures
+those discoveries.
+
+## Re-Run Summary
+
+For re-runs, present a before/after view:
+
+### Changes Made
+
+Show each file that was modified with a summary of what changed and why:
+```
+Updated:
+  _briefing.md
+    Added scan scope for tests/ directory (orient wasn't checking tests).
+    Updated architecture section to reflect new API layer.
+
+  orient/phases/health-checks.md
+    Added deploy pipeline check (user reported stale deploys going unnoticed).
+
+  Removed:
+    orient/phases/auto-maintenance.md
+      Symlink check was running every session but symlinks haven't changed
+      in 6 weeks. Retired.
+```
+
+### Unchanged
+
+Note what was reviewed but left as-is, so the user knows it was
+considered:
+```
+Reviewed, no changes:
+  system-status.md — still accurate
+  debrief/phases/update-state.md — working as intended
+```
+
+### Module Status Changes
+
+If any modules were adopted or retired during this re-run:
+```
+Newly adopted:
+  Compliance stack — added first .claude/rules/ file for API conventions
+
+Retired:
+  (none this run)
+
+Still deferred:
+  Audit loop — revisit when codebase grows
+```
+
+### Next Steps
+
+Same as first-run but adapted to the project's maturity:
+- What to watch for in the next few sessions
+- When to consider the next re-run
+- Any manual steps that onboard couldn't automate
+
+## Tone
+
+Keep it factual and brief. The user just had a conversation — they don't
+need the conversation summarized back to them. They need to know what
+files exist, what changed, and what to do next. Every line in the summary
+should be actionable or informational, not decorative.

package/templates/skills/onboard/phases/work-tracking.md

@@ -0,0 +1,231 @@
+# Work Tracking — Choose How to Track Work
+
+After the interview and before generating context, surface how the project
+tracks work — or start tracking if nothing exists yet. This phase presents
+two built-in options plus bring-your-own. The user chooses one, the other,
+or neither.
+
+When this file is absent or empty, the default behavior is: detect existing
+work tracking, present options, record the choice in `.corrc.json`. To skip
+work-tracking decisions entirely, write only `skip: true`.
+
+## When This Phase Activates
+
+This phase runs in all onboard modes (first-run, early re-run, mature re-run).
+
+- **First-run:** Present the two default options, ask user to choose
+- **Early re-run:** Show what's currently set up, ask if it's working well
+- **Mature re-run:** Review what's being used, surface if it's time to switch
+
+## Detection: What Already Exists
+
+Before presenting options, scan for signs of existing work tracking:
+
+1. **pib.db** — SQLite database from a previous CoR install or work-tracking
+   module selection
+2. **Markdown task files** — `tasks.md`, `TODO.md`, `backlog.md`, `work.md`
+   in the project root or `docs/`
+3. **GitHub Issues** — `gh issue list` returns results (if `gh` CLI is available)
+4. **Custom work-scan phase** — `.claude/skills/orient/phases/work-scan.md`
+   with non-default content
+5. **`.corrc.json` workTracking field** — Previous choice already recorded
+
+If something is already set up and working, acknowledge it: "I see you're
+using [X]. Is that working well, or would you like to try something
+different?" Don't re-present the full menu unless the user wants to switch.
+
+## Detecting Prior Interview Context
+
+If the interview already revealed how work is tracked ("I use GitHub Issues",
+"I keep a list in Notion"), reference that answer here. Don't re-ask.
+Instead: "You mentioned using [system]. Should we wire the session loop to
+that, or would you like to try one of these built-in options?"
+
+## The Two Built-In Options
+
+### Option A: SQLite Database (pib-db)
+
+**What it is:** A lightweight, local SQLite database with semantic IDs,
+status tracking, project containers, and tagging. The reference data layer
+that CoR skills (orient, debrief, plan) use by default.
+
+**Good for:**
+- Projects that want zero external dependencies (no API keys, no service)
+- Projects where work is created from plans (plan → action in pib-db)
+- Projects with multiple active workstreams that need querying
+- Projects that also use the audit loop (findings can link to actions)
+
+**What gets set up:**
+- `pib.db` — SQLite database (created by `node scripts/pib-db.js init`)
+- `scripts/pib-db.js` — CLI for create/query/close operations
+- `scripts/pib-db-schema.sql` — Schema definition
+- Orient `work-scan.md` phase — queries pib-db for open items
+- Plan `work-tracker.md` phase — creates actions from plans
+- Debrief `close-work.md` phase — marks items done
+
+**Trade-offs:**
+- Requires `better-sqlite3` npm dependency
+- Work must be created via CoR skills or the CLI
+- No native web UI (though custom dashboards are possible)
+
+**Cost:** 2-3 minutes to `npm install better-sqlite3` and initialize.
+
+### Option B: Markdown File (tasks.md)
+
+**What it is:** A single markdown file with checkbox task items and optional
+metadata tags. No database, no schema, no dependencies. Work items are
+lines in a file, checked off when done:
+
+```markdown
+## Active
+
+- [ ] Build auth API <!-- area: backend -->
+- [ ] Write docs for onboarding <!-- area: docs -->
+
+## Done
+
+- [x] Set up CI pipeline <!-- area: infra, completed: 2025-04-01 -->
+```
+
+Orient and debrief read and write by parsing the markdown file. Plans
+append new items. Everything lives in git.
+
+**Good for:**
+- Projects that want all work in git (history, blame, review)
+- Solo projects that want minimal tooling
+- Projects that prefer reading work as a flat file
+- Quick-start projects that might upgrade to pib-db later
+
+**What gets set up:**
+- `tasks.md` (or user-chosen name) — The task file
+- Orient `work-scan.md` phase — parses tasks.md for open items
+- Plan `work-tracker.md` phase — appends to tasks.md
+- Debrief `close-work.md` phase — checks off completed items
+
+**Trade-offs:**
+- No semantic queries (orient must parse and sort in markdown)
+- Concurrency issues if multiple agents write simultaneously
+- Manual cleanup of old items (no soft-delete)
+- Can't correlate work items with audit findings
+
+**Cost:** Zero dependencies, instant setup.
+
+### Option C: Bring Your Own
+
+**What it is:** You already have a work tracker (GitHub Issues, Linear,
+Jira, Notion, a spreadsheet). This phase doesn't create anything — it
+records what system you use and wires orient/debrief/plan to reference it.
+
+**Good for:**
+- Teams with established tracking workflows
+- Projects with complex workflows needing tool-specific integrations
+- Systems that already have API access set up
+
+**What gets set up:**
+- Interview notes about the external system
+- Placeholder phase files that reference your system:
+  - Orient `work-scan.md` — example queries for your tracker
+  - Plan `work-tracker.md` — example creation commands
+  - Debrief `close-work.md` — example completion commands
+- You customize the phase files to fit your specific system
+
+## Presentation Format
+
+Present options concisely, grounded in what the interview revealed:
+
+```
+## Work Tracking
+
+Based on our conversation: [quote or reference from interview, or "you
+haven't mentioned how you track work yet"]
+
+I can set up one of three approaches:
+
+**Option A: SQLite Database (pib-db)**
+- Structured, queryable, local-only, no external services
+- Best for: Multiple workstreams, plan→action pipeline, audit integration
+- Cost: npm install + init (~2 min)
+
+**Option B: Markdown File (tasks.md)**
+- Simple, git-friendly, zero dependencies
+- Best for: Solo projects, quick start, everything-in-git preference
+- Cost: Zero, instant
+
+**Option C: Your Existing System**
+- Wire orient/debrief to GitHub Issues, Linear, Jira, etc.
+- Best for: Teams with established workflows
+- Cost: Customize phase files after onboard
+
+Which approach fits your project? You can also skip work tracking for now.
+```
+
+## Recording the Choice
+
+Record the choice in `.corrc.json` under a `workTracking` field:
+
+```json
+{
+  "workTracking": {
+    "choice": "pib-db"
+  }
+}
+```
+
+Or for markdown:
+```json
+{
+  "workTracking": {
+    "choice": "markdown",
+    "file": "tasks.md"
+  }
+}
+```
+
+Or for external:
+```json
+{
+  "workTracking": {
+    "choice": "external",
+    "system": "github-issues"
+  }
+}
+```
+
+Or if skipped:
+```json
+{
+  "workTracking": {
+    "choice": "none"
+  }
+}
+```
+
+## What Downstream Phases Do With This
+
+### generate-briefing.md
+Uses the choice to populate `_briefing.md`:
+- pib-db: Documents CLI commands, DB location, query patterns
+- markdown: Documents file location, format conventions
+- external: Documents system name, access patterns
+- none: Notes that work tracking is not configured
+
+### generate-session-loop.md
+Creates phase files appropriate to the choice:
+- pib-db: work-scan queries the DB, close-work marks actions done
+- markdown: work-scan parses the file, close-work checks off items
+- external: scaffolds placeholder phases the user customizes
+- none: no work-related phase files created
+
+### modularity-menu.md
+Reflects the choice in the module status table. If the user chose markdown,
+the "Work Tracking" module shows as "ACTIVE (markdown)" not "NOT ADOPTED."
+
+## Migration Path
+
+If a user chose markdown initially and later wants to switch to pib-db:
+
+1. Run `/onboard` again
+2. Early re-run detects markdown tracking
+3. Work-tracking phase asks: "Still using tasks.md? Anything missing?"
+4. If user wants to upgrade: offer to import from markdown into pib-db
+5. Update `.corrc.json` and regenerate phase files

package/templates/skills/orient/SKILL.md

@@ -0,0 +1,251 @@
+---
+name: orient
+description: |
+  Session briefing. Reads project state, syncs data, scans work items,
+  runs health checks, then briefs you so the session starts informed.
+  This is a skeleton skill using the phases/ directory pattern. Use when:
+  session start, "orient", "what's the state", "/orient", "quick orient",
+  "orient-quick", "/orient-quick". If "quick" is mentioned, use the Quick
+  Mode section — run core phases only, skip presentation phases.
+related:
+  - type: file
+    path: .claude/skills/orient/phases/context.md
+    role: "Project-specific: what to read at session start"
+  - type: file
+    path: .claude/skills/orient/phases/data-sync.md
+    role: "Project-specific: how to sync fresh data"
+  - type: file
+    path: .claude/skills/orient/phases/work-scan.md
+    role: "Project-specific: what work items to check"
+  - type: file
+    path: .claude/skills/orient/phases/health-checks.md
+    role: "Project-specific: system health checks"
+  - type: file
+    path: .claude/skills/orient/phases/auto-maintenance.md
+    role: "Project-specific: recurring session-start tasks"
+  - type: file
+    path: .claude/skills/orient/phases/briefing.md
+    role: "Project-specific: how to present the orientation"
+  - type: file
+    path: .claude/skills/orient/phases/cabinet.md
+    role: "Project-specific: which cabinet members to activate"
+  - type: file
+    path: cabinet/_briefing.md
+    role: "Project identity and configuration"
+---
+
+# /orient — Session Briefing
+
+## Purpose
+
+Start every session with a briefing. Before anyone makes a decision,
+assemble what happened since last time, what needs attention, and what's
+on the agenda. Without this, Claude starts every session blind — same
+mistakes, same questions, same missed context. Orient reads the past so
+debrief can write the future. That's the loop that gives your cabinet
+continuity.
+
+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 files to read, what data to sync, what work
+items to check — 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.
+
+## Why This Matters
+
+If Claude Code starts a session without reading what happened last time,
+it has no memory. If it ends a session without recording what happened,
+the next session starts blind. Orient doesn't need to be complex — a
+minimal orient reads a project description and a status file. A mature
+orient pulls fresh data, checks queues, evaluates health, and surfaces
+what needs attention. The complexity grows from use: each check gets
+added because its absence caused a problem. But the loop itself must
+exist from day one, or nothing that follows has a foundation.
+
+## Workflow
+
+### 1. Load Context (core)
+
+Read `phases/context.md` for the list of files and state to load at
+session start. This typically includes status files, memory from prior
+sessions, and project-specific context.
+
+**Default (absent/empty):** Read at minimum:
+- The project's root `CLAUDE.md` (already loaded by Claude Code)
+- `system-status.md` or equivalent state file if one exists
+- `.claude/memory/patterns/` — enforcement patterns from prior sessions.
+  Scan the directory, read each pattern file. These are project-level
+  feedback that guides behavior (what to avoid, what to keep doing).
+
+The goal: build a mental model of where things stand before doing
+anything else.
+
+### 2. Sync Data (core)
+
+Read `phases/data-sync.md` for how to pull fresh canonical data from
+remote sources (databases, APIs, shared storage).
+
+**Skip (absent/empty).** Purely local projects don't need it. Projects
+with remote canonical data stores define their sync commands here.
+
+Report if sync fails — a stale local cache is better than no data, but
+the user should know it's stale.
+
+### 3. Scan Work Items (core)
+
+Read `phases/work-scan.md` for what work items to check. This includes
+whatever the project uses to track work: a backlog, task list, inbox,
+queue, or issue tracker.
+
+**Skip (absent/empty).** But note: without work scanning, orient can
+only report on project state, not on what needs doing. This phase is
+what connects orientation to action.
+
+### 4. Health Checks (core)
+
+Read `phases/health-checks.md` for system health and validation checks
+to run at session start. These catch problems early — stale data, broken
+references, failed background processes, configuration drift.
+
+**Skip (absent/empty).** Projects add health checks as they discover
+failure modes worth detecting early.
+
+**Built-in check (always runs):** If `~/.claude/cor-registry.json`
+exists, verify this project is in it and the entry is current. If
+other registry entries point to paths that no longer exist, silently
+note it — mention during briefing only if the user might care (e.g.,
+"Your old project 'deal-v1' seems to have been deleted — want me to
+remove it from the registry?").
+
+> **Orient vs Pulse vs Audit:** Orient health checks verify *operational*
+> state — is the system running, is data fresh, are processes alive?
+> Pulse (embedded in orient) verifies *descriptive* accuracy — do counts
+> match, do documented states match reality? Audit verifies *quality*
+> through expert cabinet members — is the code sound, are conventions
+> holding? Orient runs every session; pulse runs inside it; audit runs
+> periodically. Each asks a different question about the same system.
+
+### 5. Auto-Maintenance (core)
+
+Read `phases/auto-maintenance.md` for recurring automated tasks that
+should run every session. These are operations that would decay if left
+to human memory — the anti-entropy principle in action.
+
+**Skip (absent/empty).** Projects add maintenance tasks as they discover
+operations that need regular execution but aren't worth remembering to
+invoke manually.
+
+### 6. Activate Cabinet Members (core)
+
+Read `phases/cabinet.md` for which expert cabinet members or lenses
+should be active during this session. Cabinet members watch for specific
+concerns (quality, security, process adherence, non-project items)
+without being explicitly invoked for each decision.
+
+**Skip (absent/empty).**
+
+### 7. Present Briefing (presentation)
+
+Read `phases/briefing.md` for how to present the orientation results.
+This phase controls format, sections, tone, and any time-aware or
+context-aware presentation modes.
+
+**Default (absent/empty):** Present a simple summary of what was gathered
+in steps 1-6: project state, work items needing attention, any health
+issues found, maintenance results.
+
+### 8. 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 (e.g., "runs after work scan, before briefing"). Execute them
+at their declared position.
+
+### 9. Name the Session
+
+Rename the session so the sidebar is scannable. Every session that starts
+with `/orient` looks identical in the history — naming fixes this.
+
+After the briefing and the user's response, derive a short name (3-6
+words) from what the user says they're working on. If the user hasn't
+stated a focus, ask.
+
+## Phase Summary
+
+| Phase | Absent = | What it customizes |
+|-------|----------|-------------------|
+| `context.md` | Default: read CLAUDE.md, status, memory | What files and state to load |
+| `data-sync.md` | Skip | How to sync remote data |
+| `work-scan.md` | Skip | What work items to check |
+| `health-checks.md` | Skip | System health checks |
+| `auto-maintenance.md` | Skip | Recurring session-start tasks |
+| `cabinet.md` | Skip | Which cabinet members to activate |
+| `briefing.md` | Default: simple summary | How to present orientation |
+
+## Quick Mode
+
+Phases are either **core** (maintain system state) or **presentation**
+(surface information for the user). For lightweight sessions where the
+user already knows what they're doing, skip presentation phases. Core
+phases always run because they keep the system healthy.
+
+- **Core phases** (always run): context, data-sync, work-scan,
+  health-checks, auto-maintenance, cabinet
+- **Presentation phases** (skippable): briefing
+
+A project that wants a quick orient variant skips the briefing phase
+and outputs a one-line confirmation instead.
+
+## Extending
+
+To customize a phase: write content in the corresponding `phases/` file.
+To skip a phase: leave the file empty or don't create it.
+To add a phase the skeleton doesn't define: create a new file in
+`phases/` with a description of when it runs relative to the core
+phases. Claude reads whatever phase files exist at runtime.
+
+Examples of phases mature projects add:
+- Command queue processing (check for instructions from external UIs)
+- Deferred item evaluation (re-check trigger conditions on paused work)
+- Time-aware briefing modes (first session of day vs. returning session)
+- Proactive skill suggestions (surface tools relevant to current state)
+- Calendar integration (upcoming events that need preparation)
+
+## Calibration
+
+**Core failure this targets:** Starting a session without context, forcing
+the user to reconstruct state from memory or ask for information the
+system already has.
+
+### Without Skill (Bad)
+
+New session starts. Claude says "How can I help?" The user asks about
+their project status — Claude searches files, reads logs, gives a partial
+picture. The user asks about pending tasks — Claude queries again. The
+user mentions something from last session — Claude has no memory of it.
+
+Three round trips to assemble context that one orientation would have
+surfaced. Meanwhile, an overdue deadline sits unmentioned because nobody
+asked about it.
+
+### With Skill (Good)
+
+New session starts. Claude loads project state, syncs fresh data, scans
+the work backlog, and presents: here's where things stand, here's what
+needs attention, here's what changed since last time. The overdue item
+is surfaced before the user has to remember it. One message, full
+picture. The user decides what to work on from an informed position.

package/templates/skills/orient/phases/auto-maintenance.md

@@ -0,0 +1,48 @@
+# Auto-Maintenance — Recurring Session-Start Tasks
+
+Define automated tasks that should run every session. These are operations
+that would decay if left to human memory — the anti-entropy principle
+applied to session management.
+
+The distinction from health checks: health checks DETECT problems;
+auto-maintenance DOES work. A health check reports "data is stale."
+
+When this file is absent or empty, this step is skipped. (`skip: true`
+is equivalent to absent here.)
+An auto-maintenance task runs the sync to fix it.
+
+## What to Include
+
+For each task, provide:
+- **What** — the operation to perform
+- **Why every session** — what decays if this is skipped
+- **Command** — how to run it
+- **Auto-execute?** — yes (run silently) or surface (ask user first)
+
+## Example Maintenance Tasks
+
+Uncomment and adapt these for your project:
+
+<!--
+### Process Pending Queue Items
+```bash
+# Check for items queued by external systems
+curl -s https://your-api.example.com/api/queue/pending
+```
+Items queued from a UI or external integration since last session.
+Auto-execute routine items; surface unusual ones for confirmation.
+
+### Rotate Logs
+```bash
+# Truncate logs that grow unbounded
+tail -1000 sync/app.log > sync/app.log.tmp && mv sync/app.log.tmp sync/app.log
+```
+Prevents log files from consuming disk. Silent, no user interaction.
+
+### Refresh Cached Computations
+```bash
+./scripts/rebuild-index.sh
+```
+Regenerates derived data that may have drifted from source files.
+Run if source files changed since last session.
+-->