create-claude-rails 0.4.2 → 0.5.0

package/README.md

@@ -1,21 +1,39 @@
 # Claude on Rails
 
-Opinionated process scaffolding for Claude Code projects.
+Process scaffolding for Claude Code projects, by a guy who'd rather
+talk to Claude than write code.
 
 One command gives you a session loop (orient/debrief), work tracking,
 structured planning, an audit system with expert perspectives, and
 enforcement hooks — all configured through conversational onboarding.
+Most of it was built by Claude. I just complained until it worked.
 
-## Quick Start
+## Install
+
+Open a terminal, `cd` into your project folder, and run:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/orenmagid/claude-on-rails/main/install.sh | bash
+```
+
+That's it. No Node.js, no npm, no git required — just a terminal.
+
+Then open [Claude Code](https://claude.ai/code) in the same folder and
+say `/onboard`. It'll interview you about your project and set everything
+up based on your answers.
+
+### For developers
+
+If you have Node.js installed and want interactive module selection,
+database setup, or the full install:
 
 ```bash
 npx create-claude-rails
 ```
 
-That's it. The CLI walks you through module selection, copies skill files,
+The CLI walks you through module selection, copies skill files,
 sets up hooks, and optionally installs a local SQLite work tracker. When
-it's done, open Claude Code and run `/onboard` — it interviews you about
-your project and generates the context layer that makes everything work.
+it's done, open Claude Code and run `/onboard`.
 
 ## What You Get
 
@@ -36,9 +54,9 @@ you already use GitHub Issues, Linear, or something else.
 - **`/execute`** — step-through execution with checkpoints and guardrails.
 
 ### Audit System (opt-in)
-15 expert perspectives (security, accessibility, data integrity,
-performance, etc.) that analyze your codebase and produce structured
-findings. Triage UI for reviewing results.
+20 expert perspectives (security, accessibility, data integrity,
+performance, architecture, process, etc.) that analyze your codebase and
+produce structured findings. Triage UI for reviewing results.
 
 ### Compliance Stack (opt-in)
 Scoped instructions in `.claude/rules/` that load by file path. An
@@ -102,8 +120,14 @@ scripts/
 
 ## Upgrading
 
+Re-run the installer to pick up new versions:
+
 ```bash
-npx create-claude-rails            # re-run to add modules
+# Shell installer (re-downloads latest)
+curl -fsSL https://raw.githubusercontent.com/orenmagid/claude-on-rails/main/install.sh | bash
+
+# npm installer (if using Node.js)
+npx create-claude-rails
 ```
 
 In Claude Code, run `/cor-upgrade` for conversational merge of upstream
@@ -121,8 +145,14 @@ starts from zero. Orient/debrief creates continuity. Planning with
 perspectives catches problems before they ship. The enforcement pipeline
 turns recurring mistakes into permanent fixes.
 
-None of this requires you to be a developer. The onboarding interview
-meets you where you are, and the system adapts based on what you tell it.
+None of this requires you to be a developer. I'm barely one myself. The
+onboarding interview meets you where you are, and the system adapts
+based on what you tell it.
+
+This is very much a work in progress. Things will break. The session
+loop is solid; everything else is still finding its shape. If you try it
+and something's weird, that's not you — it's probably me. Or Claude.
+We're figuring it out together.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-claude-rails",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "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

@@ -2,24 +2,22 @@
 model: opus
 name: cor-upgrade
 description: |
-  Conversational upgrade when new Claude on Rails skeletons arrive. Detects current
-  adoption state, diffs against upstream, and for each change walks through
-  an intelligent merge — conversation not mechanical copy. Intelligence is
-  the merge strategy. Use when: "cor-upgrade", "update CoR", "new skeletons",
-  "/cor-upgrade".
+  Conversational upgrade when Claude on Rails updates. Runs the installer to
+  mechanically update all upstream-owned files, then walks through what changed
+  conversationally — explaining improvements, handling _context.md updates,
+  new phase file opportunities, and schema migrations. Intelligence is the
+  merge strategy for the parts that need it. Use when: "cor-upgrade",
+  "update CoR", "new skeletons", "/cor-upgrade".
 related:
   - type: file
-    path: .claude/skills/cor-upgrade/phases/detect-current.md
-    role: "Inventory current adoption state"
+    path: .claude/skills/cor-upgrade/phases/pre-upgrade.md
+    role: "Pre-upgrade checks and state capture"
   - type: file
-    path: .claude/skills/cor-upgrade/phases/diff-upstream.md
-    role: "Semantic diff against upstream CoR"
+    path: .claude/skills/cor-upgrade/phases/explain-changes.md
+    role: "How to explain what changed"
   - type: file
-    path: .claude/skills/cor-upgrade/phases/merge.md
-    role: "Intelligent merge strategy — the core of the skill"
-  - type: file
-    path: .claude/skills/cor-upgrade/phases/apply.md
-    role: "Apply approved changes"
+    path: .claude/skills/cor-upgrade/phases/adapt.md
+    role: "Handle non-manifest concerns — _context.md, phase files, schema"
 ---
 
 # /cor-upgrade — Conversational Claude on Rails Upgrade
@@ -27,34 +25,30 @@ related:
 ## Purpose
 
 This is the methodology's central claim made operational: **intelligence
-is the merge strategy.**
-
-Traditional frameworks distribute as code. You install a new version,
-run a migration script, resolve merge conflicts in config files, and hope
-nothing breaks. The upgrade path is mechanical — diff, patch, pray. This
-works for code because code has precise semantics. It fails for process
-because process is always adapted to context.
-
-AI-native methodology distributes as conversation. The upstream CoR
-package publishes new skeletons, updated defaults, additional perspectives,
-schema migrations. But the project has already adapted those skeletons —
-customized phase files, tuned perspectives, extended workflows. A
-mechanical merge would destroy the adaptations. A manual merge would
-require the user to understand both what changed upstream and how their
-project diverged, then mentally compose the two. Neither works.
-
-The upgrade skill reads both sides — the upstream change and the
-downstream context — and translates improvements into the project's
-idiom. It explains what changed and why, examines how the project
-currently handles that area, and proposes an adaptation that preserves
-local customizations while incorporating upstream improvements. The
-user confirms, modifies, or rejects each proposal. Nothing is applied
-silently.
+is the merge strategy** — but only where intelligence is needed.
+
+CoR upgrades have two layers:
+
+1. **Mechanical layer.** Skeleton SKILL.md files, hook scripts, utility
+   scripts — these are upstream-owned and tracked in `.corrc.json`. The
+   installer overwrites them deterministically. No conversation needed.
+   The upstream guard hook (PreToolUse on Edit|Write) enforces this
+   boundary at runtime — Claude cannot accidentally modify these files.
+
+2. **Conversational layer.** Everything the installer can't handle:
+   explaining what changed and why, updating `_context.md` sections that
+   new features reference, identifying new phase file opportunities,
+   running schema migrations, adapting project context to upstream
+   improvements. This is where intelligence is the merge strategy.
+
+The old approach tried to use conversation for everything — including
+mechanical file updates. That was fragile. Now the installer handles
+the deterministic parts, and this skill focuses entirely on the parts
+that actually need reasoning.
 
 This is a **skeleton skill** using the `phases/` directory pattern. The
-orchestration (detect, diff, merge, apply) is generic. Your project
-defines specifics — where upstream lives, what's adopted, how to
-present changes — in phase files under `phases/`.
+orchestration is generic. Your project defines specifics in phase files
+under `phases/`.
 
 ### Phase File Protocol
 
@@ -70,126 +64,135 @@ 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.
 
-### Skeleton/Extension Separation
+### Write Protection
+
+Manifest-tracked files (skeleton SKILL.md files, hooks, scripts) are
+protected by the upstream guard hook. Claude cannot Edit or Write to
+them during normal operation. This is intentional — these files are
+upstream-owned and should only change through the installer.
+
+**What this means for upgrades:**
+- The installer (running via Bash as a Node.js/shell process) bypasses
+  the hook because it doesn't use Claude's Edit/Write tools
+- After the installer runs, all manifest-tracked files are current
+- This skill then handles everything the installer doesn't touch:
+  _context.md, phase files, schema, and explanation
 
-This skill understands a critical boundary: **skeleton SKILL.md files may
-update, but phase files are NEVER overwritten by upstream changes.**
+### Skeleton/Extension Separation
 
-Skeleton files (SKILL.md) contain the generic orchestration — the workflow
-steps, the phase protocol, the default behaviors. These are authored by
-CoR and may improve over time. When upstream publishes a better skeleton,
-the upgrade skill can propose replacing it.
+Skeleton files (SKILL.md, hooks, scripts) are upstream-owned, manifest-
+tracked, and write-protected. They evolve through the installer.
 
-Phase files contain the project's customizations — what specific files to
-read, what specific APIs to call, what specific checks to run. These are
-authored by the project adopter (you and Claude together). Upstream has
-no knowledge of them and no authority to change them. Even if upstream
-adds a new phase file as an example or default, it never overwrites an
-existing project phase file.
+Phase files and _context.md are project-owned. They are NEVER in the
+manifest, NEVER write-protected, and NEVER overwritten by the installer.
+They evolve through conversation — this skill, /onboard, or direct
+editing.
 
-This separation is what makes upgrades safe. The skeleton evolves; the
-customizations persist. The merge intelligence sits at the boundary
-between the two.
+This separation is enforced mechanically (manifest + hook), not just
+by convention. The upgrade is safe because the boundary is real.
 
 ## Workflow
 
-### 1. Detect Current State
+### 1. Pre-Upgrade Snapshot
+
+Read `phases/pre-upgrade.md` for pre-upgrade checks.
 
-Read `phases/detect-current.md` for how to inventory the project's
-current CoR adoption.
+**Default (absent/empty):**
+- Read `.corrc.json` to capture the current version and module set
+- Note which phase files exist and have content (these won't be touched)
+- Note any `_context.md` sections that may need updating
+- If the project has a work tracker DB, note the current schema
 
-**Default (absent/empty):** Scan the project for CoR artifacts:
-- For each skill in `.claude/skills/`: is it a CoR skeleton? Which
-  phase files are customized vs using defaults vs explicitly skipped?
-- Which perspectives are adopted? Which groups configured?
-- What hooks are installed from CoR?
-- What pib-db schema version is in use (check for known columns)?
-- What's in `memory/patterns/`?
+Output: a snapshot of the project's current state, used to explain
+what changed after the installer runs.
 
-Output: a structured manifest of current adoption state, consumed by
-the diff phase.
+### 2. Run the Installer
 
-### 2. Diff Against Upstream
+Run the installer via Bash to mechanically update all upstream files:
 
-Read `phases/diff-upstream.md` for how to compare the project's state
-against the upstream CoR package.
+```
+# Shell installer (re-downloads latest from npm registry)
+curl -fsSL https://raw.githubusercontent.com/orenmagid/claude-on-rails/main/install.sh | bash
 
-**Default (absent/empty):** Look for `.pib-upstream/` in the project
-root (staged by `npx create-claude-rails upgrade`). For each
-adopted skeleton: perform a semantic diff of SKILL.md — section by
-section, not line by line. Identify new phases, changed workflows,
-updated defaults. For non-adopted skills: list what's new and available.
-For perspectives: detect new or updated ones in upstream. For schema:
-compare `pib-db-schema.sql` columns against the project's actual DB
-tables.
+# Or npm installer (if Node.js available)
+npx create-claude-rails
+```
 
-Output: a categorized list of changes, each tagged with a change
-category (see below).
+The installer:
+- Overwrites all manifest-tracked files (skeletons, hooks, scripts)
+- Preserves files NOT in the manifest (phase files, _context.md)
+- Updates `.corrc.json` with new version, hashes, and any new files
+- Adds new skills/hooks/scripts that didn't exist in the old version
 
-### 3. Merge — The Intelligence
+**This is a Bash command, not an Edit/Write operation.** It bypasses
+the upstream guard hook because it runs as a separate process using
+the filesystem directly. This is by design — the installer is the
+authorized update path for manifest-tracked files.
 
-Read `phases/merge.md` for how to handle each detected change. This is
-the core of the skill — where conversation replaces mechanical patching.
+### 3. Explain What Changed
 
-**Default (absent/empty):** For each change detected in the diff phase:
+Read `phases/explain-changes.md` for how to present changes.
 
-1. **Explain** what changed and why. Read the upstream change, infer its
-   purpose from context (commit messages, surrounding documentation,
-   the change itself). Don't just say "line 47 changed" — say "the
-   orient skeleton now includes a calendar-check phase because projects
-   found that missing upcoming deadlines was a recurring failure mode."
+**Default (absent/empty):** Compare the pre-upgrade snapshot against
+the new state:
 
-2. **Examine** how the project currently handles this area. Read the
-   relevant phase files, skill definitions, and configuration. Understand
-   the project's adaptation before proposing anything.
+1. **Version jump.** What version did we come from? What version are
+   we on now?
 
-3. **Propose** an adaptation. Based on the change category (see below),
-   recommend one of: adopt as-is, adapt to fit the project's patterns,
-   or skip with a reason. Explain what each option would mean concretely.
+2. **Changed skeletons.** For each SKILL.md that the installer updated,
+   explain what changed and why — not line-by-line diffs, but semantic
+   summaries. "The debrief skill now includes an upstream feedback phase
+   that surfaces CoR friction during debrief sessions." "The plan skill's
+   critique step now pulls from more perspectives by default."
 
-4. **Dialogue.** The user decides. This is conversation, not mechanical
-   merge. If the user wants something different from what you proposed,
-   co-author the adaptation together.
+3. **New files.** Any skills, hooks, or scripts that were added for the
+   first time. Explain what they do and whether they need any setup.
 
-#### Change Categories
+4. **New phase opportunities.** If new skeletons reference phase files
+   that the project doesn't have yet, mention them as opportunities.
+   "The orient skeleton now supports a `calendar-check.md` phase — you
+   could create one to check upcoming deadlines."
 
-Each detected change falls into one of six categories. The category
-determines the default merge strategy:
+5. **Deprecations or removals.** If anything was removed upstream,
+   explain why and what replaces it.
 
-| # | Category | Default Strategy |
-|---|----------|-----------------|
-| 1 | **New default behavior** — a phase the project uses defaults for gains a new default | Auto-adopt. The project was already trusting upstream defaults; the new default is strictly additive. Mention it but don't require confirmation. |
-| 2 | **Changed default behavior** — a phase the project uses defaults for has its default modified | Explain + propose. The project trusted the old default; the new one is different. Show what changed and let the user decide. |
-| 3 | **New phase added to skeleton** — upstream added a phase that didn't exist before | Explain what the phase does, propose opt-in. New phases start as "absent" (using default or skipped), so adoption is always explicit. |
-| 4 | **Changed skeleton workflow** — the SKILL.md orchestration itself changed | The most sensitive category. Examine the project's phase files and any custom phases. Co-author the adaptation — don't just replace the skeleton. |
-| 5 | **New skeleton skill available** — upstream published a skill the project hasn't adopted | Present what the skill does, what problem it solves, what adoption would involve. User decides whether and when to adopt. |
-| 6 | **Schema migration** — upstream schema has new columns or tables | Detect the difference, generate ALTER TABLE / CREATE TABLE SQL, present for review, apply only after explicit confirmation. |
+Walk through each category conversationally. The user should understand
+what they're getting, not just that files changed.
 
-**CRITICAL:** Phase files are NEVER overwritten. The merge handles
-skeleton SKILL.md updates and new capabilities. Project-specific
-customizations in phase files are sacred — they represent the project's
-adaptation of the methodology to its own context. If an upstream change
-would interact with a phase file's content (e.g., a skeleton now
-references a concept the phase file also addresses), the merge proposes
-a collaborative edit, not a replacement.
+### 4. Adapt Non-Manifest Concerns
 
-### 4. Apply Approved Changes
+Read `phases/adapt.md` for how to handle the conversational layer.
 
-Read `phases/apply.md` for how to apply the changes the user approved
-in the merge phase.
+**Default (absent/empty):** After explaining changes, handle anything
+the installer couldn't:
 
-**Default (absent/empty):**
-- For skeleton-only changes: copy the updated SKILL.md from upstream,
-  preserving the project's phase files untouched.
-- For changes that interact with phase files: make collaborative edits
-  as approved in the merge dialogue — show the diff before writing.
-- For schema migrations: run the approved SQL against the project's DB.
-- For new skills: copy the skeleton SKILL.md, create an empty `phases/`
-  directory. The project customizes from there.
-- Commit after each logical group of changes with a clear message
-  describing what was upgraded and why.
-- Present a summary: what was applied, what was skipped (with reasons),
-  what the user might want to review or customize next.
+#### _context.md Updates
+If new skeletons reference `_context.md § Section` names that the
+project's `_context.md` doesn't have, propose adding them. New features
+often depend on context sections — e.g., a new perspective might
+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?"
+
+#### Schema Migrations
+If the upstream schema has new columns or tables:
+- Detect the difference between the shipped schema and the project's DB
+- Generate `ALTER TABLE` / `CREATE TABLE` SQL
+- Present for review
+- Apply only after explicit confirmation
+
+#### New Module Adoption
+If the upgrade added modules the project hadn't installed before,
+walk through what they do and whether to keep them.
+
+Present a summary when done: what was mechanically updated, what was
+adapted conversationally, what the user might want to customize next.
 
 ### 5. Discover Custom Phases
 
@@ -202,23 +205,21 @@ the workflow. Execute them at their declared position.
 
 | Phase | Absent = | What it customizes |
 |-------|----------|-------------------|
-| `detect-current.md` | Default: scan .claude/skills/, perspectives, hooks, DB | How to inventory adoption state |
-| `diff-upstream.md` | Default: compare against .pib-upstream/ (staged by CLI) | Where upstream lives and how to diff |
-| `merge.md` | Default: explain + examine + propose for each change | How to handle each change category |
-| `apply.md` | Default: copy skeletons, collaborative edits, SQL migrations | How to apply approved changes |
+| `pre-upgrade.md` | Default: read .corrc.json, note phase files, note _context.md | Pre-upgrade state capture |
+| `explain-changes.md` | Default: semantic summary of version jump, changed skeletons, new files | How to present what changed |
+| `adapt.md` | Default: _context.md sections, phase implications, schema, new modules | How to handle non-manifest concerns |
 
 ## Proactive Trigger
 
 The upgrade skill doesn't have to wait for the user to invoke it.
-Orient can detect when upstream CoR files are newer than the project's
-adopted copies and surface "CoR updates available" in the briefing.
+Orient can detect when upstream CoR has a newer version than what's
+in `.corrc.json` and surface "CoR updates available" in the briefing.
 This is a hint, not a blocker — the user decides when to run /cor-upgrade.
 
-To enable this, a project's orient `phases/health-checks.md` or a
-custom orient phase can compare modification times between upstream
-skeleton SKILL.md files and their adopted counterparts. When drift is
-detected, orient mentions it. When the user is ready, they invoke
-/cor-upgrade and the full conversational merge begins.
+The drift check script (`scripts/cor-drift-check.cjs`) can also detect
+if manifest-tracked files have been modified outside the installer,
+though the upstream guard hook should prevent this during normal
+Claude Code operation.
 
 ## Extending
 
@@ -238,29 +239,29 @@ Examples of phases mature projects add:
 ## Calibration
 
 **Core failure this targets:** Process improvements published upstream
-never reach adopted projects, or reach them as destructive overwrites
-that erase hard-won customizations.
+never reach adopted projects, or reach them but nobody understands
+what changed.
 
 ### Without Skill (Bad)
 
-New CoR skeletons arrive. The user manually diffs files, trying to
-figure out what changed. Some changes are obvious — a new skill directory
-appeared. Others are subtle — a default behavior in an existing skeleton
-shifted. The user copies files they think are updated, accidentally
-overwrites a phase file they'd customized, doesn't notice a schema
-migration is needed. Three sessions later, a skill fails because it
-references a DB column that doesn't exist yet. The customization they
-spent two sessions tuning is gone, replaced by the upstream default.
+New CoR version is out. The user re-runs the installer. Files update
+silently. The user has no idea what changed — was it just bug fixes?
+New features? Did a skill they rely on change its workflow? They also
+don't realize the new debrief skill references a `§ Friction Captures`
+section in _context.md that their project doesn't have, so the upstream
+feedback phase silently does nothing. Three weeks later they wonder
+why no friction is being captured.
 
 ### With Skill (Good)
 
-New CoR skeletons arrive. The user runs `/cor-upgrade`. Claude inventories
-what's adopted, diffs against upstream, and walks through each change:
-"The orient skeleton added a calendar-check phase. Your project doesn't
-have calendar integration, so this would be a no-op — skip it for now?"
-"The debrief skeleton's default inventory behavior now includes checking
-for uncommitted stash entries. You're using the default here, so this
-improvement applies automatically." "There's a new schema column for
-deferred trigger conditions. Here's the ALTER TABLE — want me to apply
-it?" Nothing is lost. Everything is explained. The project gets better
-without getting broken.
+New CoR version is out. The user runs `/cor-upgrade`. The installer
+updates all upstream files mechanically — fast, deterministic, safe
+(phase files untouched). Then Claude explains: "You went from v0.4.1
+to v0.5.0. The big change: debrief now has an upstream feedback phase
+that captures CoR friction. It references `_context.md § Friction
+Captures` — let's add that section to your context file." "The plan
+skill's critique step now uses three perspectives instead of one. Your
+existing phase files are fine — this is a default behavior change."
+"There's a new `investigate` skill for deep-dive debugging. Want to
+try it?" Everything is explained. Non-manifest concerns are handled.
+The project gets better without confusion.