create-claude-rails 0.1.0 → 0.1.2

package/lib/cli.js

@@ -221,8 +221,13 @@ async function run() {
     selectedModules = Object.keys(MODULES);
     if (flags.noDb) {
       includeDb = false;
+      // work-tracking templates are still copied (pib-db.js, schema) but
+      // the DB isn't initialized. Mark it as skipped so /onboard knows
+      // to ask about the alternative work tracking system.
+      selectedModules = selectedModules.filter(m => m !== 'work-tracking');
+      skippedModules['work-tracking'] = 'Database setup skipped (--no-db)';
     }
-    console.log(`  Installing all ${selectedModules.length} modules.${flags.noDb ? ' (skipping DB)' : ''}\n`);
+    console.log(`  Installing all ${selectedModules.length} modules.${flags.noDb ? ' (skipping work-tracking DB)' : ''}\n`);
   } else {
     const { installAll } = await prompts({
       type: 'confirm',
@@ -306,7 +311,15 @@ async function run() {
 
       const stat = fs.statSync(srcPath);
       if (stat.isDirectory()) {
-        const results = await copyTemplates(srcPath, destPath, { dryRun: flags.dryRun });
+        // For skill directories, skip phases/ — absent phase files use
+        // skeleton defaults. Phase files are created by /onboard based
+        // on the project interview, not copied as generic templates.
+        const isSkill = tmpl.startsWith('skills/') && !tmpl.startsWith('skills/perspectives');
+        const results = await copyTemplates(srcPath, destPath, {
+          dryRun: flags.dryRun,
+          skipConflicts: flags.yes,
+          skipPhases: isSkill,
+        });
         totalCopied += results.copied.length;
         totalSkipped += results.skipped.length;
         totalOverwritten += results.overwritten.length;

package/lib/copy.js

@@ -6,13 +6,13 @@ const prompts = require('prompts');
  * Recursively copy files from src to dest, surfacing conflicts.
  * Returns { copied: string[], skipped: string[], overwritten: string[] }
  */
-async function copyTemplates(src, dest, { dryRun = false } = {}) {
+async function copyTemplates(src, dest, { dryRun = false, skipConflicts = false, skipPhases = false } = {}) {
   const results = { copied: [], skipped: [], overwritten: [] };
-  await walkAndCopy(src, dest, src, results, dryRun);
+  await walkAndCopy(src, dest, src, results, dryRun, skipConflicts, skipPhases);
   return results;
 }
 
-async function walkAndCopy(srcRoot, destRoot, currentSrc, results, dryRun) {
+async function walkAndCopy(srcRoot, destRoot, currentSrc, results, dryRun, skipConflicts, skipPhases) {
   const entries = fs.readdirSync(currentSrc, { withFileTypes: true });
 
   for (const entry of entries) {
@@ -21,10 +21,16 @@ async function walkAndCopy(srcRoot, destRoot, currentSrc, results, dryRun) {
     const destPath = path.join(destRoot, relPath);
 
     if (entry.isDirectory()) {
+      // Skip phases/ directories — absent phase files use skeleton defaults,
+      // which is the correct behavior for most adopters. Phase files are
+      // only created when the user customizes behavior via /onboard.
+      if (skipPhases && entry.name === 'phases') {
+        continue;
+      }
       if (!dryRun && !fs.existsSync(destPath)) {
         fs.mkdirSync(destPath, { recursive: true });
       }
-      await walkAndCopy(srcRoot, destRoot, srcPath, results, dryRun);
+      await walkAndCopy(srcRoot, destRoot, srcPath, results, dryRun, skipConflicts, skipPhases);
     } else {
       if (fs.existsSync(destPath)) {
         const existing = fs.readFileSync(destPath, 'utf8');
@@ -35,6 +41,11 @@ async function walkAndCopy(srcRoot, destRoot, currentSrc, results, dryRun) {
           continue;
         }
 
+        if (skipConflicts) {
+          results.skipped.push(relPath);
+          continue;
+        }
+
         const response = await prompts({
           type: 'select',
           name: 'action',

package/package.json

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

package/templates/skills/onboard/SKILL.md

@@ -24,6 +24,9 @@ related:
   - 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 — Project Onboarding Interview
@@ -218,6 +221,21 @@ through use as orient and debrief reveal what's missing.
 In re-run mode, present a before/after view: what the context layer
 looked like before, what changed, and why.
 
+### 7. Post-Onboard Audit
+
+Read `phases/post-onboard-audit.md` for the configuration sanity check.
+
+**Default (absent/empty):** Run a lightweight audit from the box-health
+perspective, 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 |
@@ -228,6 +246,7 @@ looked like before, what changed, and why.
 | `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: box-health sanity check | What to verify after generation |
 
 ## Conversational Stance
 

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

@@ -9,6 +9,20 @@ standard PIB artifact set, classify each artifact's richness, and
 determine the mode. To explicitly skip state detection (force first-run
 mode), write only `skip: true`.
 
+## Pre-Check: CLI Metadata
+
+Before scanning artifacts, read `.pibrc.json` at the project root. This
+file is created by `npx create-claude-rails` and records which modules
+were installed, which were skipped (with reasons), and the package version.
+
+If `.pibrc.json` is absent, this skill was installed manually (not via
+the CLI). That's fine — proceed with the artifact scan. The interview
+and modularity menu will handle module decisions.
+
+If `.pibrc.json` exists, note the installed and skipped modules. The
+interview phase uses this to skip redundant questions and the modularity
+menu uses `skipped` reasons to ask about alternatives.
+
 ## What to Scan
 
 Check for these artifacts and classify each as absent, empty, or populated:

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

@@ -9,6 +9,41 @@ adapted questions as described below, 2-3 at a time, with follow-ups.
 To explicitly skip the interview (e.g., when generating context from
 existing documentation), write only `skip: true`.
 
+## System Introduction (First Run Only)
+
+Before asking about the project, check: does the user know what Claude
+on Rails does? Ask once:
+
+> "Have you used Claude on Rails before, or is this your first time?"
+
+If **first time**, give a brief walkthrough before the interview:
+
+> "Let me explain how this works, then we'll set it up for your project.
+>
+> Claude on Rails gives your Claude Code sessions a **session loop** —
+> a start and end routine that creates continuity between sessions.
+>
+> - **`/orient`** runs at the start. It reads where things stand — what
+>   you were working on, what's due, what broke. Instead of starting
+>   blind, Claude starts informed.
+> - **`/debrief`** runs at the end. It records what happened — what got
+>   done, what's still open, what you learned. That's what orient reads
+>   next time.
+>
+> Beyond the session loop, there are optional modules: **work tracking**
+> (a local task database), **planning** (structured plans with critique
+> before you build), **audit** (expert perspectives that review your
+> codebase), and more. We'll get to those after we talk about your project.
+>
+> The whole system is customizable through small files called phase files.
+> You don't need to touch them now — that's what this onboarding does."
+
+Then proceed to the interview. Keep it conversational — if they ask
+questions about the system, answer them before moving on.
+
+If **experienced** (they've used it before, or say "I know how it works"),
+skip the walkthrough entirely and go straight to the interview.
+
 ## Communication Calibration
 
 Don't ask the user how technical they are. Listen to how they talk.

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

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

package/templates/skills/orient/SKILL.md

@@ -84,7 +84,9 @@ 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
-- Memory files from prior sessions if the project uses memory
+- `.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.

package/templates/skills/orient/phases/context.md

@@ -5,21 +5,12 @@ of where things stand. The /orient skill reads this file and loads each
 item before proceeding.
 
 When this file is absent or empty, the default behavior is: read the
-project's root CLAUDE.md, system-status.md, and relevant memory files.
-To explicitly skip context loading, write only `skip: true`.
+project's root CLAUDE.md, system-status.md, and enforcement patterns
+from `.claude/memory/patterns/`. To explicitly skip context loading,
+write only `skip: true`.
 
-## What to Include
+## Default Context Sources
 
-For each context source, provide:
-- **What** — the file or data to read
-- **Why** — what it tells you about current state
-- **How** — the command or tool to read it (Read tool, sqlite3, curl, etc.)
-
-## Example Context Sources
-
-Uncomment and adapt these for your project:
-
-<!--
 ### System Status
 ```
 Read system-status.md
@@ -28,14 +19,30 @@ The single-source-of-truth for what's built, what's broken, and what's
 next. Read every session — it's the fastest way to know where things
 stand.
 
-### Memory Files
+### Enforcement Patterns
+```
+Scan .claude/memory/patterns/ — read each pattern file.
+```
+Project-level feedback from prior sessions. These are consolidated
+observations about what works and what doesn't — they guide behavior
+so the same mistakes aren't repeated. Patterns with `enforcement: guide`
+are behavioral rules. Patterns with `enforcement: prevent` or `detect`
+should already be encoded as hooks or rules, but reading them provides
+context for why those guardrails exist.
+
+## Additional Context Sources
+
+Uncomment and adapt these for your project:
+
+<!--
+### Memory Index
 ```
-Read memory/MEMORY.md for the index, then load files relevant to the
-session's likely focus.
+Read .claude/memory/MEMORY.md for the index, then load files relevant
+to the session's likely focus.
 ```
-Persistent context from prior sessions — user preferences, project
-state, feedback patterns, references. Don't read everything — scan
-the index and load what's relevant.
+If your project uses a memory index beyond patterns (user context,
+project state, references), scan the index and load what's relevant.
+Don't read everything — selective loading based on session focus.
 
 ### Project-Specific State
 ```