create-claude-rails 0.5.0 → 0.5.2

package/lib/cli.js

@@ -15,7 +15,7 @@ const MODULES = {
     name: 'Session Loop (orient + debrief)',
     description: 'Context continuity between sessions. Claude starts informed, ends by recording what happened.',
     mandatory: true,
-    templates: ['skills/orient', 'skills/debrief', 'skills/debrief/phases/upstream-feedback.md', 'skills/menu', 'hooks/stop-hook.md'],
+    templates: ['skills/orient', 'skills/orient-quick', 'skills/debrief', 'skills/debrief-quick', 'skills/debrief/phases/upstream-feedback.md', 'skills/menu', 'hooks/stop-hook.md'],
   },
   'hooks': {
     name: 'Git Guardrails + Telemetry',
@@ -500,6 +500,23 @@ async function run() {
     }
   }
 
+  // --- Clean up files removed upstream ---
+  if (Object.keys(existingManifest).length > 0) {
+    let totalRemoved = 0;
+    for (const oldPath of Object.keys(existingManifest)) {
+      if (!allManifest[oldPath]) {
+        const fullPath = path.join(projectDir, oldPath);
+        if (fs.existsSync(fullPath)) {
+          if (!flags.dryRun) fs.unlinkSync(fullPath);
+          totalRemoved++;
+        }
+      }
+    }
+    if (totalRemoved > 0) {
+      console.log(`  🧹 Removed ${totalRemoved} file${totalRemoved === 1 ? '' : 's'} no longer in upstream`);
+    }
+  }
+
   // --- Write metadata ---
   if (!flags.dryRun) {
     createMetadata(projectDir, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-claude-rails",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Claude on Rails — opinionated process scaffolding for Claude Code projects",
   "bin": {
     "create-claude-rails": "bin/create-claude-rails.js"

package/templates/skills/cor-upgrade/SKILL.md

@@ -174,11 +174,46 @@ reference `§ Friction Captures` which the project hasn't defined yet.
 Show the section template from `_context-template.md` and help the
 user fill it in.
 
-#### Phase File Implications
-If a skeleton's workflow changed in a way that interacts with existing
-phase files, discuss the implications. "The orient skeleton reorganized
-its steps — your custom `health-checks.md` phase still works, but it
-now runs earlier in the workflow. Is that okay?"
+#### Phase File Opportunities
+For each skeleton that changed, check its phase files against the
+project's `phases/` directory. There are three cases:
+
+1. **Existing phase file, workflow changed around it.** The project
+   customized this phase and the skeleton shifted. Discuss the
+   implications: "The orient skeleton reorganized its steps — your
+   custom `health-checks.md` phase still works, but it now runs
+   earlier in the workflow. Is that okay?"
+
+2. **New phase the skeleton now references.** The upstream added a
+   phase that didn't exist before. Explain what the default behavior
+   is and what customizing it would look like. Don't push — just
+   surface the opportunity. "The debrief skeleton now has an
+   `upstream-feedback` step. It runs by default — here's what it does.
+   If you ever want to change that behavior, you'd create
+   `phases/upstream-feedback.md`."
+
+3. **Existing default that changed meaningfully.** The project uses
+   the default (no phase file) and the default behavior shifted. The
+   project gets the improvement automatically, but mention it so they
+   know. If the new default does something they might not want, suggest
+   creating a phase file to customize or skip it. "The plan skeleton's
+   default research phase now reads test files too. You've been using
+   the default — you'll get this automatically. If that's too noisy,
+   create `phases/research.md` to scope it."
+
+4. **Default that won't fit the project.** Read `_context.md` and
+   compare against what the default actually does. If there's a
+   mismatch, say so and offer to create the phase file now. "The
+   orient skeleton added a `work-scan` phase. The default reads git
+   history — but your `_context.md` says you use Linear. The default
+   won't see your tickets. Want to create `phases/work-scan.md` that
+   checks Linear?" This isn't speculation — it's reading both sides
+   and spotting the gap.
+
+**Don't enumerate every absent phase file.** That's `/onboard`'s job.
+The upgrade skill only surfaces phase opportunities that are *relevant
+to what changed* in this upgrade — including cases where the project's
+context makes a default obviously insufficient.
 
 #### Schema Migrations
 If the upstream schema has new columns or tables:

package/templates/skills/debrief/SKILL.md

@@ -5,7 +5,9 @@ description: |
   updates state, captures lessons, and reports results. The operational
   closing that prevents entropy between sessions. This is a skeleton skill
   using the phases/ directory pattern. Use when: session end, "debrief",
-  "wrap up", "/debrief", or after completing significant work.
+  "wrap up", "/debrief", "quick debrief", "debrief-quick", "/debrief-quick",
+  or after completing significant work. If "quick" is mentioned, use the
+  Quick Mode section — run core phases only, skip presentation phases.
 related:
   - type: file
     path: .claude/skills/debrief/phases/inventory.md

package/templates/skills/debrief-quick/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: debrief-quick
+description: |
+  Quick post-session debrief — core phases only, skip presentation.
+  Use when: "debrief-quick", "quick debrief", "/debrief-quick".
+---
+
+# /debrief-quick
+
+Load the `/debrief` skill and run it in **Quick Mode** — core phases
+only, skip presentation phases. See the debrief SKILL.md's Quick Mode
+section for details.

package/templates/skills/orient/SKILL.md

@@ -5,7 +5,9 @@ description: |
   items, runs health checks and maintenance, then presents a briefing 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".
+  "/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

package/templates/skills/orient-quick/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: orient-quick
+description: |
+  Quick session orientation — core phases only, skip presentation.
+  Use when: "orient-quick", "quick orient", "/orient-quick".
+---
+
+# /orient-quick
+
+Load the `/orient` skill and run it in **Quick Mode** — core phases
+only, skip presentation phases. See the orient SKILL.md's Quick Mode
+section for details.

package/templates/skills/cor-upgrade/phases/apply.md

@@ -1,86 +0,0 @@
-# Apply — Execute Approved Changes
-
-Apply the changes approved during the merge conversation. Each change
-type has a specific application method.
-
-When this file is absent or empty, the default behavior is: apply each
-approved change using the type-appropriate method below, commit after
-each logical group, and present a summary. To explicitly skip applying
-(dry-run mode where merge proposes but nothing is written), write only
-`skip: true`.
-
-## Application Methods
-
-### Skeleton SKILL.md Updates
-
-Copy the updated SKILL.md from upstream to the project's `.claude/skills/`
-directory. The project's `phases/` directory is untouched — only the
-skeleton orchestration file changes.
-
-Before copying, verify:
-- The project's phase files still exist and are intact
-- The new skeleton's phase references match the phase files that exist
-- If the new skeleton references a phase the project doesn't have,
-  note it (the project will use the default behavior)
-
-### Phase File Collaborative Edits
-
-When a merge proposal includes changes to a phase file (always with
-user approval):
-- Show the exact diff before writing
-- Make the edit
-- Read back the result so the user can verify
-
-Never bulk-replace a phase file. Edits are surgical and approved.
-
-### Schema Migrations
-
-- Present the SQL one more time before executing
-- Run the migration against the project's database
-- Verify the schema change took effect (query the table structure)
-- If migration fails, report the error — don't retry or attempt fixes
-  without user input
-
-### New Skills
-
-- Copy the skeleton SKILL.md from upstream
-- Create an empty `phases/` directory
-- Do NOT copy upstream example phase files — the project starts fresh
-  and customizes from the skeleton's defaults
-- Note the new skill in the summary so the user knows to customize it
-
-### New Perspectives
-
-- Copy new perspective files to the project's perspective directory
-- If the project has a group configuration, note the new perspective
-  but don't auto-add it to any group — the user decides placement
-
-### New Hooks or Rules
-
-- Present the hook/rule configuration
-- Add to `.claude/settings.json` or `.claude/rules/` after confirmation
-- If the project has existing hooks that might conflict, flag it
-
-## Commit Strategy
-
-Commit after each logical group of changes:
-- All skeleton updates in one commit
-- Schema migrations in a separate commit (easy to revert)
-- New skills in a separate commit
-- Phase file edits in a separate commit (clearly separated from
-  skeleton changes)
-
-Commit messages should describe what was upgraded:
-"Upgrade orient + debrief skeletons from upstream CoR"
-"Add trigger_condition column (CoR schema migration)"
-"Adopt /validate skill from CoR"
-
-## Summary
-
-After all changes are applied, present:
-- **Applied:** what was changed, with commit references
-- **Skipped:** what the user chose not to adopt, with their reasons
-  (useful context for the next upgrade)
-- **Review next:** suggestions for customization — new skills that
-  need phase files, new phases that might benefit from project-specific
-  content, perspectives to consider adding to groups

package/templates/skills/cor-upgrade/phases/detect-current.md

@@ -1,82 +0,0 @@
-# Detect Current — Inventory Claude on Rails Adoption State
-
-Build a structured manifest of the project's current CoR adoption. This
-manifest is consumed by the diff-upstream phase to determine what has
-changed.
-
-When this file is absent or empty, the default behavior is: read
-`.corrc.json` for version and module metadata, then scan the project's
-`.claude/skills/`, perspectives, hooks, and database for CoR artifacts.
-To explicitly skip detection, write only `skip: true`.
-
-## What to Inventory
-
-### Package Metadata (.corrc.json)
-
-Read `.corrc.json` from the project root. This file is written by the
-CLI installer (`npx create-claude-rails`) and contains:
-
-- **`version`** — the installed package version (for diff-upstream comparison)
-- **`installedAt`** — when the install or last upgrade happened
-- **`modules`** — which module groups were selected (boolean map)
-- **`skipped`** — modules the user opted out of, with reasons
-- **`upstreamPackage`** — the npm package name (`create-claude-rails`)
-
-If `.corrc.json` is missing, this is either a pre-npm adoption or a
-manual install. Note this in the manifest — the diff-upstream phase
-needs to know whether version comparison is possible or if it must fall
-back to pure filesystem diffing.
-
-### Skills
-
-For each directory in `.claude/skills/`:
-- **Is it a CoR skeleton?** Compare the SKILL.md against the upstream
-  upstream templates directory. If it matches a known skeleton
-  (by name or by frontmatter `name` field), it's a CoR skill.
-- **Phase file status:** For each phase file the skeleton defines, check
-  whether the project's copy is: absent (using default), empty (using
-  default), contains `skip: true` (opted out), or contains custom content
-  (project-specific adaptation).
-- **Custom phases:** Any phase files in the project's `phases/` directory
-  that the skeleton doesn't define are project extensions.
-
-### Perspectives
-
-- Which perspective groups exist in `.claude/skills/perspectives/`?
-- Which perspectives are listed in each group's `_group.yaml`?
-- Which perspectives have project-customized content vs upstream defaults?
-
-### Hooks
-
-- Read `.claude/settings.json` (or `.claude/settings.local.json`).
-- Identify which hooks were installed as part of CoR adoption vs
-  project-specific additions.
-
-### Database Schema
-
-- If the project uses `pib-db`, check the actual DB schema against
-  known CoR columns. Record which tables and columns exist.
-- Note the effective schema version (inferred from which columns are
-  present, not from a version number).
-
-### Memory and Patterns
-
-- Count files in `memory/patterns/` and `memory/archive/`.
-- Note whether the enforcement pipeline is active (patterns have
-  `enforcement` frontmatter fields).
-
-## Output Format
-
-Produce a structured manifest (in conversation, not a file) listing:
-- **Package version** from `.corrc.json` (or "unknown — no .corrc.json")
-- **Installed modules** from `.corrc.json` modules map
-- **Skipped modules** with reasons from `.corrc.json` skipped map
-- Each adopted skill with its phase file statuses
-- Each adopted perspective group with member count
-- Hook count and types
-- Schema state
-- Pattern/archive counts
-
-This manifest feeds directly into the diff-upstream phase. The version
-field is especially critical — it determines whether diff-upstream can
-do a targeted version-to-version comparison or must diff everything.

package/templates/skills/cor-upgrade/phases/diff-upstream.md

@@ -1,72 +0,0 @@
-# Diff Upstream — Compare Project Against Claude on Rails Package
-
-Compare the project's current adoption state (from detect-current) against
-the upstream CoR package. Produce a categorized list of changes.
-
-When this file is absent or empty, the default behavior is: look for
-`.pib-upstream/` in the project root (staged by `npx create-claude-rails
-upgrade`) and perform semantic diffs of all adopted skeletons. To
-explicitly skip diffing, write only `skip: true`.
-
-## Locating Upstream
-
-Default: `.pib-upstream/` in the project root. This directory is created
-by `npx create-claude-rails upgrade`, which fetches the latest package
-from npm and stages its templates here for comparison. The directory is
-gitignored — it's a transient diff target, not a permanent fixture.
-
-If `.pib-upstream/` doesn't exist, prompt the user:
-"Run `npx create-claude-rails upgrade` first — it fetches the latest
-upstream and stages it for comparison."
-
-If your project stores upstream elsewhere (a submodule, a symlinked
-directory, a separate checkout), specify the path here.
-
-## Diff Strategy
-
-The diff is **semantic, not textual.** Line-by-line diffs of markdown
-files are noisy and miss the point. Instead:
-
-### For Each Adopted Skeleton SKILL.md
-
-Compare section by section:
-- **Purpose/description** — has the framing changed?
-- **Workflow steps** — are there new phases? Removed phases? Reordered?
-- **Phase summary table** — do defaults differ?
-- **Default behaviors** — for each phase, has the "absent/empty" behavior
-  changed? This matters most for projects using defaults.
-- **Calibration** — has the failure mode description evolved?
-- **Extending section** — new extension examples?
-
-### For Non-Adopted Skills
-
-List any skills in upstream that the project hasn't adopted. For each,
-note: name, one-line description, what problem it addresses.
-
-### For Perspectives
-
-- New perspectives in upstream that the project doesn't have.
-- Updated perspectives where upstream content differs from project copy.
-- New perspective groups.
-
-### For Schema
-
-Compare `pib-db-schema.sql` (or equivalent) column-by-column against
-the project's actual database tables. Flag: new columns, changed types,
-new tables, new indexes.
-
-### For Infrastructure
-
-- New hooks in upstream's recommended settings.
-- New rules files in upstream's `.claude/rules/`.
-- Changes to the CoR onboarding or seed skills.
-
-## Output Format
-
-A categorized change list, where each change has:
-- **What** changed (specific file, section, or artifact)
-- **Category** (1-6, matching the SKILL.md's change categories)
-- **Summary** of the change in plain language
-- **Impact** on the project (does this touch something the project customized?)
-
-This feeds directly into the merge phase.

package/templates/skills/cor-upgrade/phases/merge.md

@@ -1,97 +0,0 @@
-# Merge — Intelligent Upgrade Conversation
-
-THE INTELLIGENCE. For each change detected by diff-upstream, walk
-through a conversational merge: explain, examine, propose, dialogue.
-
-When this file is absent or empty, the default behavior is: process
-each change using the category-based strategy defined in the skeleton
-SKILL.md. To explicitly skip merging (just list changes without
-proposing anything), write only `skip: true`.
-
-## The Merge Loop
-
-For each change in the categorized list:
-
-### 1. Explain What Changed and Why
-
-Read the upstream change in full. Don't summarize from the diff — read
-the actual new content. Infer purpose from:
-- The change itself (what does it add, remove, or alter?)
-- Surrounding documentation (did a README or methodology essay mention it?)
-- Commit messages if accessible
-- The pattern of changes (if several skeletons gained the same phase,
-  that's a methodology-wide shift)
-
-Communicate at the level of intent, not lines: "The orient skeleton now
-checks for stale deferred items because projects found that deferred
-work was being forgotten" — not "lines 140-155 were added."
-
-### 2. Examine the Project's Current Implementation
-
-Before proposing anything, understand how the project handles this area:
-- Read the relevant phase files (customized? default? skipped?)
-- Check if the project has custom phases that address the same concern
-- Look at related memory patterns or feedback
-- Understand why the project's current approach exists
-
-### 3. Propose Adaptation
-
-Based on the change category:
-
-**Category 1 (new default):** "This applies automatically since you're
-using the default. Here's what it adds: [description]. No action needed
-unless you want to customize it."
-
-**Category 2 (changed default):** "The default behavior for [phase]
-changed from [old] to [new]. You're currently using the default. The
-new version [explanation]. Adopt the new default, or would you prefer
-to pin the old behavior by writing it into your phase file?"
-
-**Category 3 (new phase):** "Upstream added a [name] phase to [skill].
-It handles [description]. Your project [does/doesn't] have something
-similar. Want to opt in, or skip it for now?"
-
-**Category 4 (changed workflow):** "The [skill] skeleton's workflow
-changed: [description]. Your project has customized [these phases].
-Here's how I'd adapt: [proposal]. Let's walk through it."
-
-**Category 5 (new skill):** "There's a new [name] skill available. It
-handles [description]. Adopting it would involve [steps]. Want to
-explore it, or skip for now?"
-
-**Category 6 (schema migration):** "The upstream schema adds [columns/
-tables]. Here's the migration SQL: [SQL]. This would enable [features].
-Want me to apply it?"
-
-### 4. Dialogue
-
-Wait for the user's response. They may:
-- Accept as proposed
-- Want modifications (co-author the adaptation)
-- Skip with a reason (record why for future upgrades)
-- Ask questions (answer from upstream context)
-
-## CRITICAL: Phase File Protection
-
-Phase files are NEVER overwritten by this process. The merge handles:
-- Skeleton SKILL.md updates (the generic orchestration)
-- New capabilities and defaults
-- Schema migrations
-- New skills and perspectives
-
-It does NOT handle:
-- Replacing project phase files with upstream examples
-- Overwriting custom perspectives
-- Changing project-specific hook configurations
-
-If an upstream change interacts with a phase file's content (e.g., a
-skeleton now references a concept the phase file also addresses), propose
-a **collaborative edit** — show the user what you'd change in their
-phase file and why, get approval before touching it.
-
-## Batch vs Interactive
-
-For small upgrades (1-3 changes), walk through each one interactively.
-For large upgrades (many changes), group by category and handle
-auto-adopt items (category 1) in batch, then walk through the rest
-individually.