create-claude-rails 0.1.2 → 0.3.0

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

@@ -1,18 +1,18 @@
 # 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.
 
 When this file is absent or empty, the default behavior is: read
-`.pibrc.json` for module selections made during CLI install, then present
+`.corrc.json` for module selections made during CLI install, then present
 the module hierarchy with that context. To explicitly skip the menu,
 write only `skip: true`.
 
-## Reading CLI Selections (.pibrc.json)
+## Reading CLI Selections (.corrc.json)
 
-If `.pibrc.json` exists in the project root, the CLI has already asked
+If `.corrc.json` exists in the project root, the CLI has already asked
 about module selections. Read the `modules` and `skipped` fields:
 
 - **Installed modules** (`modules` map, value `true`): These are already
@@ -29,7 +29,7 @@ For skipped modules with alternatives, the interview (previous phase)
 should have already asked about the alternative system. Use those answers
 here to confirm the wiring plan.
 
-If `.pibrc.json` doesn't exist (manual install or pre-npm adoption),
+If `.corrc.json` doesn't exist (manual install or pre-npm adoption),
 fall back to presenting the full menu as described below.
 
 ## Module Hierarchy
@@ -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

@@ -39,7 +39,7 @@ Compare what the interview revealed against what was generated:
 
 ### 2. Module–Phase Alignment
 
-Cross-reference `.pibrc.json` (installed vs skipped modules) against the
+Cross-reference `.corrc.json` (installed vs skipped modules) against the
 generated phase files:
 
 - **Skipped modules:** No phase file should reference a skipped module's
@@ -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

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-context.md
+Uses the choice to populate `_context.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/perspectives/_groups-template.yaml

@@ -46,4 +46,4 @@ groups:
   #     - process
   #     - documentation
   #     - meta-process
-  #     - box-health          # PIB adoption health, configuration drift, anti-bloat
+  #     - box-health          # CoR adoption health, configuration drift, anti-bloat