create-claude-rails 0.1.2 → 0.2.0

package/templates/skills/onboard/SKILL.md

@@ -2,16 +2,22 @@
 name: onboard
 description: |
   Conversational interview that generates the initial context layer for a
-  project adopting PIB. Re-runnable at different maturity stages — each run
+  project adopting Claude on Rails. Re-runnable at different maturity stages — each run
   refines based on what the project has learned. Use when: "onboard",
-  "set up PIB", "bootstrap", "/onboard".
+  "set up CoR", "bootstrap", "/onboard".
 related:
   - type: file
     path: .claude/skills/onboard/phases/detect-state.md
-    role: "Detect existing PIB artifacts and determine run mode"
+    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-context.md
     role: "Generate or update context files"
@@ -33,7 +39,7 @@ related:
 
 ## Purpose
 
-Generate the context layer that makes every other PIB skill work. Without
+Generate the context layer that makes every other CoR skill work. Without
 context — what is this project, what stack does it use, what breaks, who
 works on it — the session loop runs blind. Orient reads files that don't
 exist yet. Debrief records lessons into a structure that hasn't been
@@ -69,7 +75,7 @@ Onboard is re-runnable. What it does depends on what already exists:
 
 ### 1. First Run (no _context.md)
 
-No PIB context layer exists yet. This is the full interview: who are you,
+No CoR context layer exists yet. This is the full interview: who are you,
 what is this, what breaks, what do you need. Generates the complete
 initial context layer — `_context.md`, CLAUDE.md additions, system-status.md,
 and session loop wiring. The goal is a working session loop by the end of
@@ -77,7 +83,7 @@ the conversation.
 
 ### 2. Early Re-Run (sparse artifacts)
 
-Some PIB artifacts exist but the project is young. The session loop has
+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 context
@@ -86,7 +92,7 @@ existing files rather than creating new ones.
 
 ### 3. Mature Re-Run (rich context)
 
-The project has been using PIB for a while. Context files are populated,
+The project has been using CoR for a while. Context 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
@@ -98,7 +104,7 @@ doesn't have to declare it.
 
 ## Why This Matters
 
-Every PIB skill reads from the context layer. Orient reads `_context.md`
+Every CoR skill reads from the context layer. Orient reads `_context.md`
 to know what files to check. Plan reads it to know where work items live.
 Perspectives read it to know where to look. If the context layer is empty
 or wrong, every skill downstream is degraded. Onboard is the foundation
@@ -113,9 +119,9 @@ the periodic recalibration that keeps the context layer honest.
 
 ### 1. Detect State
 
-Read `phases/detect-state.md` for how to scan existing PIB artifacts.
+Read `phases/detect-state.md` for how to scan existing CoR artifacts.
 
-**Default (absent/empty):** Scan for the standard PIB artifact set:
+**Default (absent/empty):** Scan for the standard CoR artifact set:
 `_context.md`, `system-status.md`, `orient/phases/`, `debrief/phases/`,
 `pib.db`, `_groups.yaml`, `memory/patterns/`. Count what exists, classify
 its richness (empty file vs populated), and determine the run mode. Report
@@ -149,12 +155,37 @@ 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 PIB module, note
+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. Generate Context
+### 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 `.pibrc.json` under `workTracking`
+and feeds into generate-context 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-conditions perspectives 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-context. Deferred decisions are
+noted as open questions in `_context.md`.
+
+### 5. Generate Context
 
 Read `phases/generate-context.md` for how to create or update the context
 layer from interview answers.
@@ -173,7 +204,7 @@ would change as diffs — never overwrite without showing the delta. Let
 the user approve, modify, or reject each change. The user owns their
 context files; onboard proposes, never imposes.
 
-### 4. Generate Session Loop
+### 6. Generate Session Loop
 
 Read `phases/generate-session-loop.md` for how to wire orient and debrief
 phase files.
@@ -196,9 +227,9 @@ 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.
 
-### 5. Modularity Menu
+### 7. Modularity Menu
 
-Read `phases/modularity-menu.md` for which PIB modules to present.
+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.
@@ -209,7 +240,7 @@ 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.
 
-### 6. Summary
+### 8. Summary
 
 Read `phases/summary.md` for how to present results.
 
@@ -221,7 +252,7 @@ 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
+### 9. Post-Onboard Audit
 
 Read `phases/post-onboard-audit.md` for the configuration sanity check.
 
@@ -240,8 +271,10 @@ pre-flight check, not a deferred finding.
 
 | Phase | Absent = | What it customizes |
 |-------|----------|-------------------|
-| `detect-state.md` | Default: scan standard PIB artifacts | What artifacts to scan and how to determine mode |
+| `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-context.md` | Default: create/update _context.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 |
@@ -254,7 +287,7 @@ 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 PIB module.
+understand it, not to immediately map it to a CoR module.
 
 This matters because the quality of the context layer depends on the
 quality of the conversation. A mechanical interview produces mechanical
@@ -284,13 +317,13 @@ Examples of phases mature adopters add:
 
 ## Calibration
 
-**Core failure this targets:** Starting PIB adoption with empty context
+**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 PIB. They copy the skeleton files, run `/orient` — it
+A project adopts CoR. They copy the skeleton files, run `/orient` — it
 reads a blank `_context.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 — perspectives
@@ -305,7 +338,7 @@ discovering context gaps one at a time.
 
 ### With Skill (Good)
 
-A project adopts PIB and runs `/onboard`. The interview asks what the
+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

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

@@ -1,76 +1,58 @@
-# Detect State — Scan PIB Artifacts and Determine Mode
+# Detect State — Scan Claude on Rails Artifacts and Determine Mode
 
-Scan the project for existing PIB artifacts to determine whether this is
+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 PIB artifact set, classify each artifact's richness, and
+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`.
 
-## Pre-Check: CLI Metadata
+## Fast Path
 
-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.
+Check for `_context.md` (or `.claude/skills/perspectives/_context.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.
 
-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.
+Also read `.pibrc.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.
 
-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.
+## Full Scan (re-runs only)
 
-## What to Scan
-
-Check for these artifacts and classify each as absent, empty, or populated:
+Only when `_context.md` exists, scan these artifacts to distinguish
+early vs mature re-run:
 
 | Artifact | Path Pattern | Indicates |
 |----------|-------------|-----------|
-| Project context | `_context.md` or `.claude/skills/perspectives/_context.md` | Context layer exists |
 | 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 |
 | Perspective groups | `_groups.yaml` or `.claude/skills/perspectives/_groups.yaml` | Audit system configured |
-| Memory patterns | `memory/patterns/*.md` | Feedback loop is active |
+| 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 |
 
-## Mode Determination
-
-**First run:** `_context.md` does not exist. No PIB context layer has been
-generated yet. Even if other artifacts exist (e.g., a CLAUDE.md written
-by hand), the absence of the generated context file means onboard hasn't
-run before.
-
-**Early re-run:** `_context.md` exists but the artifact set is sparse.
-Fewer than 5 of the scanned artifacts are populated. The session loop
-may be wired but modules like work tracking, audit, and enforcement are
-not yet active. The project is young — it has been through a few sessions
-but hasn't accumulated rich process infrastructure.
-
-**Mature re-run:** `_context.md` exists and 5 or more scanned artifacts
-are populated. The project has a working session loop, some form of work
-tracking, and at least one additional module (audit, enforcement, or
-memory). The context layer has had time to accumulate gaps and drift.
+**Early re-run:** Fewer than 5 of the above are populated.
+**Mature re-run:** 5 or more are populated.
 
 ## Output
 
-Report findings as a structured summary that subsequent phases can
+For first-run: `Mode: first-run` — that's it. Move on.
+
+For re-runs, report a structured summary that subsequent phases can
 reference:
 
 ```
-Mode: first-run | early-rerun | mature-rerun
+Mode: early-rerun | mature-rerun
 
 Artifacts found:
-  - _context.md: populated (last modified 2026-03-15)
   - system-status.md: populated
   - orient phases: 3 files (context.md, work-scan.md, health-checks.md)
-  - debrief phases: 2 files (inventory.md, update-state.md)
   - pib.db: absent
   - memory patterns: 4 files
   ...

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

@@ -1,6 +1,6 @@
 # Generate Context — Create or Update Context Files
 
-Transform interview answers into the files that make the rest of PIB
+Transform interview answers into the files that make the rest of Claude on Rails
 functional. This is where conversation becomes infrastructure — but it
 is always a proposal, never an imposition.
 

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

@@ -60,7 +60,7 @@ are valid starting points.
 
 ## First-Run Questions
 
-The detect-state phase identified this as a first run (no PIB context
+The detect-state phase identified this as a first run (no CoR context
 layer exists). But "first run" covers two very different situations:
 
 ### Greenfield (no project yet, or near-empty directory)
@@ -174,12 +174,32 @@ cruft. This is a health check.
 - Are there patterns in your memory/feedback that suggest a structural
   change rather than another rule?
 
+## Scope Boundary
+
+You are configuring the **process layer** — what Claude should know about
+this project, how sessions start and end, what to track and check. You
+are NOT:
+
+- Recommending tech stacks, frameworks, or architecture
+- Advising on what to build or how to build it
+- Making product decisions
+
+If the user asks "what should I use?" or "what do you recommend?" for
+their actual project, redirect: "That's a great question for your first
+working session after we finish setup. Right now I'm just learning about
+your project so the session loop knows what to look for. What do you
+know so far about what you'll be building?"
+
+Record what they tell you about their intentions and tools — that goes
+into `_context.md`. But choosing those tools is their decision, not
+onboard's job.
+
 ## Conversation Guidelines
 
 - **2-3 questions per round.** Let the user respond before asking more.
 - **Follow up on substance.** If an answer reveals something important,
   dig into it before moving on to the next topic.
-- **Note PIB module signals.** When someone describes a pain point that
+- **Note CoR module signals.** When someone describes a pain point that
   maps to a specific module, note it internally for the modularity menu
   phase — but don't interrupt the conversation to pitch the module.
 - **Don't assume answers.** Even if you can see the project's files, ask

package/templates/skills/onboard/phases/modularity-menu.md

@@ -1,6 +1,6 @@
 # Modularity Menu — Present Opt-In Modules
 
-Present the PIB module hierarchy so the user can decide what to adopt now
+Present the Claude on Rails module hierarchy so the user can decide what to adopt now
 and what to defer. The session loop is mandatory; everything else is
 opt-in. Progressive adoption means starting with what you need and adding
 modules as the project matures.
@@ -38,7 +38,7 @@ Present these in order from most fundamental to most specialized:
 
 ### 1. Session Loop (orient + debrief) — MANDATORY
 
-Always set up. This is the minimum viable PIB adoption. Orient reads
+Always set up. This is the minimum viable CoR adoption. Orient reads
 state at session start; debrief writes state at session end. Without
 this, nothing else has a foundation.
 
@@ -49,21 +49,24 @@ with each session instead of resetting to zero.
 **Cost:** Two phase directories with a few files each. Runs at the
 start and end of every session (adds 30-60 seconds each).
 
-### 2. Work Tracking (pib-db) — RECOMMENDED
+### 2. Work Tracking — RECOMMENDED
 
-A lightweight SQLite-based task and project tracker. Gives orient
-something to scan and debrief something to close.
+How work items are tracked. The work-tracking onboard phase presents the
+options in detail; this is the module-level view.
 
-**What you get:** Open actions, due dates, project containers, flagged
-items. Orient surfaces what's overdue or due today. Debrief marks
-things done. Plan creates work items.
+**Options (chosen during onboard work-tracking phase):**
+- **pib-db (SQLite):** Structured, queryable, local-only. CLI interface.
+  Integrates with plan/execute and audit findings. Requires `better-sqlite3`.
+- **Markdown (tasks.md):** Simple, git-friendly, zero dependencies. Open
+  items are checkbox lines in a file. Good for solo/quick-start projects.
+- **External:** Wire orient/debrief to GitHub Issues, Linear, Jira, etc.
+  You customize phase files after onboard.
 
-**Cost:** One SQLite database, CLI interface via `node scripts/pib-db.js`.
-No external service dependency.
+**What you get:** Open actions, due dates, flagged items. Orient surfaces
+what needs attention. Debrief marks things done. Plan creates work items.
 
-**Skip if:** You already have a work tracker you're happy with (GitHub
-Issues, Linear, Jira, a markdown file). You can wire the session loop to
-your existing tracker instead.
+**Skip if:** You don't need work tracking in the session loop. You can
+always add it later by re-running `/onboard`.
 
 ### 3. Planning (plan + execute) — OPT-IN
 
@@ -115,7 +118,7 @@ head.
 
 ### 6. Capability Seeding (seed) — OPT-IN
 
-Bootstrap new skills, perspectives, or process components from PIB
+Bootstrap new skills, perspectives, or process components from CoR
 skeleton templates.
 
 **What you get:** Quick scaffolding of new capabilities with all required

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

@@ -0,0 +1,98 @@
+# Options — Structured Decision Points Before Generation
+
+After the interview and before generating context files, surface the key
+decisions that shape how the project and process layer get set up. Present
+options with trade-offs so the user makes informed choices — not Claude
+making choices for them.
+
+When this file is absent or empty, the default behavior is: identify
+decisions implied by the interview, present options, let the user choose.
+To explicitly skip (e.g., the user already has strong opinions from the
+interview), write only `skip: true`.
+
+## When This Phase Activates
+
+Not every onboard needs this. Skip it when:
+- The user described a clear tech stack and workflow (nothing to decide)
+- This is a re-run (decisions were already made)
+- The project is already built and this is process-layer-only
+
+Run it when the interview revealed **open decisions** — things the user
+hasn't settled yet that will affect what context files contain:
+
+- "I'm not sure what database to use"
+- "I don't know if I need a backend"
+- "What would you recommend?" (redirected here from the interview)
+- Greenfield project where the user described *what* but not *how*
+
+## How to Present Options
+
+For each open decision, present 2-3 concrete options with trade-offs.
+Use two expert perspectives internally (do not spawn agents — just
+reason from these viewpoints):
+
+### Architecture Perspective
+Evaluates each option for: complexity, maintenance burden, whether it
+matches the user's described skill level and project scope. Flags when
+an option is overkill for a weekend project or too lightweight for
+something ambitious.
+
+### Boundary Conditions Perspective
+Evaluates each option for: what breaks first, what's hard to change
+later, what locks you in. Flags irreversible decisions that deserve
+extra thought.
+
+### Format
+
+```
+## [Decision: e.g., "How to store data"]
+
+Based on what you described — [reference specific things from interview] —
+here are your options:
+
+**Option A: [name]**
+- What it is: [1 sentence]
+- Good for: [when this is the right choice]
+- Trade-off: [what you give up]
+
+**Option B: [name]**
+- What it is: [1 sentence]
+- Good for: [when this is the right choice]
+- Trade-off: [what you give up]
+
+**Option C: [name]** (if applicable)
+- ...
+
+What sounds right for your situation?
+```
+
+### Tone
+
+- **Present, don't prescribe.** "Here are your options" not "I recommend X."
+- **Reference the interview.** "You mentioned it's just you and this is a
+  side project, so..." — ground options in their specific situation.
+- **Be honest about complexity.** If one option is simpler but limited,
+  say so. If another is powerful but requires more setup, say so.
+- **Respect "I don't know."** If the user can't decide, suggest starting
+  with the simplest option and note that it can be changed later. Don't
+  pressure decisions.
+
+## What This Is NOT
+
+- **Not architecture consulting.** You present options the interview
+  surfaced, not a comprehensive technology evaluation. If the user wants
+  deep architecture advice, that's a working session topic, not onboard.
+- **Not prescriptive.** Never say "you should use X." Always frame as
+  options with trade-offs.
+- **Not exhaustive.** 2-3 options per decision. Not every possible
+  approach.
+
+## Output
+
+The user's choices feed into generate-context. Each decision becomes
+concrete content in `_context.md` (architecture section), CLAUDE.md
+(conventions), and potentially orient phase files (what to check).
+
+If the user defers a decision ("I'll figure that out later"), note it
+in `_context.md` as an open question — don't leave the section empty
+without explanation.

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

@@ -61,7 +61,25 @@ Quick filesystem checks:
 - `system-status.md` exists and has initial content
 - Hook scripts in `.claude/hooks/` are executable (if hooks module adopted)
 
-### 4. First-Session Readiness
+### 4. Technology-Implied Perspectives
+
+Check whether the project's technology signals suggest perspectives that
+aren't activated. Cross-reference the interview answers and detected
+technologies against the perspective catalog:
+
+- **UI framework detected** → usability, accessibility, mobile-responsiveness
+- **Database detected** → data-integrity
+- **API server detected** → security, performance
+- **Complex architecture (3+ layers/services)** → architecture
+- **Long-running project** → historian
+- **Many skills (5+)** → skills-coverage
+- **Features shipping regularly** → system-advocate
+
+If implied perspectives aren't in `_groups.yaml` (or equivalent), note
+it as a recommendation — not a blocker. The user may have good reasons
+to skip them, or may want to add them later via `/seed`.
+
+### 5. First-Session Readiness
 
 Simulate what `/orient` will do on its first run:
 

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

@@ -51,7 +51,7 @@ Deferred:
 ### What to Do Next
 
 Concrete next steps, not abstract advice:
-- "Run `/orient` to start your first PIB session. It will read the
+- "Run `/orient` to start your first CoR session. It will read the
   context files we just generated."
 - "After your first working session, run `/debrief` to close the loop."
 - "The context files are rough. After 3-5 sessions, run `/onboard` again