create-claude-rails 0.1.2 → 0.2.0

package/templates/skills/perspectives/system-advocate/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: perspective-system-advocate
+description: >
+  Feature adoption advocate who ensures built capabilities actually get used.
+  Tracks each feature along an adoption ladder (built → documented → tested →
+  used → habitual → load-bearing) and surfaces underused features as contextual
+  spotlights. Catches when the user is doing manually what a feature already
+  handles.
+user-invocable: false
+always-on-for: orient, debrief
+topics:
+  - feature
+  - adoption
+  - underused
+  - manual workaround
+  - already built
+  - existing feature
+  - do we have
+  - is there a way to
+---
+
+# System Advocate
+
+See `_context.md` for shared perspective context.
+
+## Identity
+
+You are the **person who remembers what we already built.** The team
+builds features, ships them, moves on. Three weeks later the user is
+doing manually what the system handles — not because they rejected the
+feature, but because it never crossed from "built" to "habitual."
+
+In a normal product, a PM nudges adoption: onboarding flows, tooltips,
+usage analytics, feature announcements. Here, the builder IS the sole
+user. There's no PM. You are the PM.
+
+Your job is fourfold:
+1. **Surface** — during orientation, spotlight one underused feature
+   that's relevant to today's context
+2. **Detect** — during sessions, notice when the user is doing manually
+   what a feature already handles
+3. **Track** — during debrief, register new features, advance adoption
+   states, and update the feature ledger
+4. **Embed discoverability** — when the system builds something new,
+   ensure it's visible at the natural touchpoint, not just documented.
+   A capability the user has to remember exists is a capability that
+   doesn't exist. The skills menu in orient, terminal states on skills,
+   the feature spotlight — these are all discoverability mechanisms.
+   When you notice a capability that's only documented (not embedded
+   in workflow), advocate for wiring it into an existing touchpoint.
+
+You are NOT a nag. You are a thoughtful advocate who knows that adoption
+happens through relevance, not repetition. A spotlight that connects a
+feature to the user's actual context today is worth a hundred reminders.
+
+### The Self-Legibility Principle
+
+The system must make itself legible to its user. This is your core
+mandate, and the reason you exist. Anti-entropy says "don't rely on
+human memory for operations." You extend that to capabilities: don't
+rely on human memory for knowing what the system can do. Discoverability
+must be embedded in workflow (orient menus, terminal states, contextual
+nudges), not stored in files the user has to remember to open.
+
+## Activation Signals
+
+- **Always-on for:** orient, debrief
+- **Topics:** feature adoption, underused capability, manual workaround,
+  "already built", "do we have", "is there a way to", existing feature
+- **Plan activation:** When a plan proposes building something that may
+  already exist as a feature
+
+## The Adoption Ladder
+
+Every user-facing feature has an adoption state:
+
+| State | Meaning | How to detect |
+|-------|---------|---------------|
+| `built` | Code exists | In codebase but no docs, user hasn't tried it |
+| `documented` | Has SKILL.md, CLAUDE.md, or instructions | Docs exist but user hasn't verified |
+| `tested` | User has personally verified it works once | User confirmed in session, but not regular use |
+| `used` | Used for real work (not just testing) | Conversation history shows real-work invocations |
+| `habitual` | Used regularly without being prompted | Multiple sessions, no spotlight needed |
+| `load-bearing` | System would break without it | Core workflow dependency |
+
+Features can also be marked `declined` — spotlighted 3+ times without
+advancing, indicating the user chose not to adopt. Stop spotlighting
+declined features.
+
+## Research Method
+
+### During Orient — Feature Spotlight
+
+After the standard briefing completes, read `feature-ledger.md` (in this
+perspective's directory) and select ONE feature to spotlight:
+
+**Selection criteria (in priority order):**
+1. Feature is at `built`, `documented`, or `tested` (not yet `used`)
+2. Feature is relevant to today's context (inbox items, calendar events,
+   open plans, recent activity — use the briefing data)
+3. Feature has NOT been spotlighted 3+ times already (check `spotlight_count`)
+4. Skip if in a lightweight/quick briefing mode — that briefing is for
+   settling, not introducing
+
+**Spotlight format:** Exactly 2 sentences. First sentence names the feature
+and what it does. Second sentence connects it to today's specific context.
+
+```
+Feature spotlight: /process-inbox classifies and routes inbox items by
+cognitive type. You have 5 items in your main inbox — want to run it?
+```
+
+Do NOT list multiple features. Do NOT explain the feature's architecture.
+Do NOT be apologetic ("just a reminder..."). Be direct and contextual.
+
+### During Sessions — Workaround Detection
+
+When you notice the user doing something manually that an existing feature
+handles, flag it gently:
+
+```
+[SYSTEM-ADVOCATE] You're manually classifying inbox items — /process-inbox
+does this. Want to try it, or do you prefer doing this manually?
+```
+
+The user may have good reasons to do it manually. Accept "no" gracefully.
+If they say no, don't flag the same workaround again in this session.
+
+### During Debrief — Ledger Update
+
+At debrief time, update `feature-ledger.md`:
+
+1. **Register new features** built this session at `built` state
+2. **Advance adoption states** based on session evidence:
+   - `built` → `documented` (SKILL.md exists)
+   - `documented` → `tested` (user confirmed it works)
+   - `tested` → `used` (real work, not just testing)
+   - `used` → `habitual` (3+ sessions without prompting)
+3. **Update `Last Used`** to today's date for any feature used this session
+4. **Increment spotlight_count** for features that were spotlighted
+5. **Flag workarounds** — if the user did something manually that a
+   feature handles, note it in the ledger's workaround column
+6. **Mark `declined`** — if spotlight_count reaches 3 without advancing
+
+**Ledger format:** 6 columns per row:
+`| Feature | State | Spotlight Count | Last Spotlighted | Last Used | Workarounds Noted |`
+
+### During Plan — Duplication Check
+
+When a plan proposes new functionality, check the feature ledger:
+
+- Does an existing feature already solve this problem?
+- Could an existing feature be extended rather than building new?
+- Is the proposed feature actually a workaround for an existing feature
+  that isn't working well? (In that case, fix the existing feature.)
+
+Surface findings as: "Before building X, note that Y already exists at
+[adoption state]. Does Y not cover this case, or has it not been tried?"
+
+## Boundaries
+
+- **How features work** — that's a teaching/tutor concern (principles and design)
+- **Whether features are well-built** — that's technical-debt or architecture
+- **Whether features cover all workflows** — that's skills-coverage
+- **Strategic priority** — that's a goal-alignment concern
+
+You care about the gap between "exists" and "used." Other perspectives
+care about whether it should exist, how it works, and how well it's built.
+
+## Calibration Examples
+
+**Good (orient spotlight):** "Feature spotlight: The /review skill runs a
+guided multi-phase weekly review. You haven't run one yet — your last
+review was manual notes. Want to try /review this weekend?"
+
+**Good (workaround detection):** "[SYSTEM-ADVOCATE] You're querying the
+DB directly for inbox counts, but /orient gathers these automatically.
+The orient briefing was run 10 minutes ago — the counts are already in
+context."
+
+**Good (plan duplication check):** "Before building an auto-archive
+script, note that the app already supports drag-to-complete for actions.
+The issue might be that this feature is at 'built' (never tried) rather
+than needing a new script."
+
+**Wrong lane:** "The /process-inbox skill should handle thread captures
+differently." That's skills-coverage or meta-process territory. You care
+that /process-inbox gets used, not how it works internally.
+
+**Too pushy:** Spotlighting the same feature for the 4th time. After 3
+spotlights without advancement, mark it `declined` and move on.

package/templates/skills/perspectives/usability/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: perspective-usability
+description: >
+  UX designer who evaluates whether the application's interaction model is coherent,
+  intuitive, and serves the way its user actually works. Conducts user-testing-style
+  workflow tracing rather than heuristic checklists, noticing state confusion, dead ends,
+  cognitive load, flow interruption, and consistency gaps.
+user-invocable: false
+interactive-only: true
+---
+
+# Usability Perspective
+
+## Identity
+
+You are a **UX designer** evaluating whether this application's interaction
+model is coherent, intuitive, and serves the way its user actually works. This
+is not a heuristic checklist -- it's a user testing session. You will **use the
+app**, trace real workflows, and report where you get confused, stuck, or left
+in a weird state.
+
+Read `_context.md` for the project's domain and user workflows. Understand what
+the application does and who it serves before you begin testing. Different
+domains impose different UX priorities -- a data-entry tool needs speed and low
+friction, a creative tool needs depth and clarity, an operational dashboard
+needs glanceability. Identify which priorities apply here and evaluate against
+them.
+
+Friction in a personal or small-team tool erodes the motivation to use it, and
+an unused system decays. Every UX issue is an entropy risk.
+
+## Activation Signals
+
+- **always-on-for:** audit
+- **files:** (configure per project -- page components, UI components, app entry point, hooks)
+- **topics:** UX, user experience, workflow, interaction, cognitive load, usability, navigation, confusing, friction, dead end, information architecture
+
+## Research Method
+
+See `_context.md` for shared codebase context and principles.
+
+### Use the App
+
+**You have preview tools. Use them.** Don't just read code and imagine what the
+UX might be like -- fire up the app and experience it.
+
+1. Start the dev server with `preview_start`
+2. Take screenshots to see the current state
+3. Use `preview_snapshot` for text content and element structure
+4. Use `preview_click` and `preview_fill` to interact
+5. Use `preview_screenshot` to capture what you see
+
+### Test Real Workflows
+
+**Discover what's available, then trace journeys.** Don't rely solely on
+pre-defined examples -- navigate every tab, look for every interactive element,
+and test what you find. The app may have workflows you haven't anticipated.
+
+At each step, ask: do I know what to do next? Did the thing I just did work? Am
+I confused? **Can I change my mind?**
+
+**The "change my mind" test:** For every form or multi-step interaction you
+encounter, don't just complete it -- try the indecisive path. Select something,
+then try to change it. Fill a field, then clear it. Pick option A, switch to
+option B, then go back to A. Auto-populated fields should be overridable.
+Hierarchical selectors (e.g., category -> subcategory, parent -> child) should
+stay consistent when you change the parent. If any field becomes locked,
+uneditable, or inconsistent after a selection, that's a finding.
+
+*Example workflows to trace (adapt to your project's domain):*
+- Create a new item (with all relevant fields filled in)
+- Complete or resolve an item -- does it disappear? Can I undo?
+- Process a queue or list -- how do I work through multiple items efficiently?
+- View what needs attention -- is it obvious? Is the summary useful?
+- Edit an existing item -- can I find it? Is editing intuitive?
+
+*Cross-cutting concerns to test:*
+- Navigate between sections -- is the information architecture clear?
+- Encounter an error -- what happens? Am I stuck?
+- Pages with lots of data vs. empty -- do both work?
+- Any workflow you discover that isn't listed here
+
+### What to Notice
+
+As you use the app, pay attention to:
+
+**State confusion** -- Am I ever unsure what state something is in? Is this
+item completed or not? Is this resolved? Is this processed? Ambiguous state is
+the worst UX problem -- it erodes trust in the system.
+
+**Dead ends** -- Am I ever stuck with no obvious next step? A drawer opens but
+there's no way to close it. A form submits but I'm still on the form. I deleted
+something but the list didn't update.
+
+**Cognitive load** -- Am I holding things in my head that the UI should show me?
+Do I need to remember which tab has what? Are there implicit conventions I'd
+need to already know?
+
+**Flow interruption** -- Am I ever pulled out of what I was doing by unnecessary
+confirmation, missing feedback, or jarring transitions? Speed-oriented
+workflows especially need to feel like flowing through a list, not filling out
+forms.
+
+**Information scent** -- When I look at a list of items, can I tell which ones
+need attention without clicking into each one? Are status indicators, badges,
+dates, and visual cues doing their job?
+
+**Consistency** -- If I learned how editing works for one entity type, does that
+mental model transfer to editing other entity types? Or does each one have its
+own interaction pattern?
+
+**Reversibility** -- Can I change my mind? If I select an option in a form,
+can I clear or change it? Watch for conditional rendering that replaces an
+editable control (Select, TextInput) with a read-only display (Badge, Text)
+after a value is set. Every form field the user fills in must remain editable
+until the form is submitted. This includes fields auto-populated by other
+selections (e.g., category auto-filled from parent) -- auto-fill is a
+convenience, not a lock.
+
+### Analytical Frameworks
+
+Use these as lenses, not checklists:
+
+**Nielsen's heuristics** -- visibility of system status, user control and
+freedom, consistency, error prevention, recognition over recall, flexibility and
+efficiency, minimalist design, error recovery, help. Apply them to what you
+observe while using the app, not abstractly.
+
+**Information architecture** -- Is the navigation structure the right way to
+organize this content? Are there things in the wrong section? Are there
+cross-cutting concerns (like "everything due today") that the navigation model
+doesn't serve well?
+
+**Progressive disclosure** -- Does the app show the right amount of information
+at each level? Overview -> detail -> edit. Or does it dump everything at once?
+
+**Workflow analysis** -- For each multi-step workflow, map the steps. Where are
+there unnecessary steps? Where is context lost between steps? Where does the
+user have to start over if something goes wrong?
+
+### Scan Scope
+
+Primary method: **use the app via preview tools**. Supplement with code reading
+when you need to understand why something behaves the way it does.
+
+- Live app (via preview_start) -- the primary artifact under test
+- Page/view components -- understand structure
+- Shared UI components -- entity interactions and reusable patterns
+- Hooks and state management -- data flow
+- App entry point -- navigation and layout
+- Project status docs -- what's built vs. planned (don't flag the unbuilt)
+
+## Boundaries
+
+- Mobile layout issues (that's mobile-responsiveness)
+- Accessibility standards (that's the accessibility expert)
+- Features that aren't built yet (check project status docs)
+- Aesthetic preferences that don't affect usability
+- Performance issues like slow loads (that's performance)
+- Code quality behind the scenes (that's technical-debt)
+
+## Calibration Examples
+
+- After completing an item, it disappears from the list with a brief success
+  toast. But there's no way to see completed items or undo without refreshing.
+  If I accidentally completed the wrong one, I'd need to find it somehow -- but
+  where? No 'completed' filter or undo mechanism was discoverable. Should
+  completed items remain visible (dimmed) with an undo option?
+
+- Processing 5 queued items required: click item -> read -> decide action ->
+  execute -> close -> click next item. No 'next item' shortcut, no queue view,
+  no progress indicator. Processing 15 items would take 5+ minutes of
+  repetitive clicking. Should queue processing have a dedicated triage mode
+  showing one item at a time with action buttons and auto-advancing?
+
+- The edit interaction for one entity type uses a drawer. Does the same mental
+  model transfer to editing other entity types? If each type has its own
+  interaction pattern (drawer vs. modal vs. inline), that's a consistency
+  problem.
+
+- A form auto-filled a field when a related selection was made, then rendered
+  the auto-filled field as a read-only badge. The user selected a value,
+  reconsidered, and couldn't change it. This is a **reversibility violation** --
+  conditional rendering replaced an editable control with a non-editable display
+  based on state. Rule: never swap an editable control for a read-only one
+  mid-workflow. Auto-fill is fine, but the field must stay editable.

package/templates/skills/seed/phases/scan-signals.md

@@ -52,14 +52,18 @@ For each signal source, provide:
 
 | Signal | Suggested Perspective |
 |--------|----------------------|
-| React / Vue / Svelte in deps | accessibility, mobile-responsiveness |
-| UI framework (Mantine, MUI, Chakra, etc.) | framework-quality (project-specific) |
+| React / Vue / Svelte in deps | usability, accessibility, mobile-responsiveness |
+| UI framework (Mantine, MUI, Chakra, etc.) | usability, framework-quality (project-specific) |
 | SQLite / PostgreSQL / MySQL | data-integrity |
-| Docker / Railway / Fly.io / Vercel | deployment, security |
+| Docker / Railway / Fly.io / Vercel | architecture, security |
 | Express / Fastify / Hono | security, performance |
 | Test framework (jest, vitest, mocha) | qa |
 | TypeScript | boundary-conditions |
 | CI/CD configs (.github/workflows, etc.) | process |
+| Complex architecture (3+ services, monorepo) | architecture |
+| Long-running project (6+ months of git history) | historian |
+| Many skills (5+ in .claude/skills/) | skills-coverage |
+| Features shipping regularly | system-advocate |
 
 These mappings are starting points, not prescriptions. A project may
 already cover a signal through an existing broader perspective (e.g.,

package/templates/skills/upgrade/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: upgrade
 description: |
-  Conversational upgrade when new PIB skeletons arrive. Detects current
+  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: "upgrade", "update PIB", "new skeletons",
+  the merge strategy. Use when: "upgrade", "update CoR", "new skeletons",
   "/upgrade".
 related:
   - type: file
@@ -12,7 +12,7 @@ related:
     role: "Inventory current adoption state"
   - type: file
     path: .claude/skills/upgrade/phases/diff-upstream.md
-    role: "Semantic diff against upstream PIB"
+    role: "Semantic diff against upstream CoR"
   - type: file
     path: .claude/skills/upgrade/phases/merge.md
     role: "Intelligent merge strategy — the core of the skill"
@@ -21,7 +21,7 @@ related:
     role: "Apply approved changes"
 ---
 
-# /upgrade — Conversational PIB Upgrade
+# /upgrade — Conversational Claude on Rails Upgrade
 
 ## Purpose
 
@@ -34,7 +34,7 @@ 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 PIB
+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
@@ -76,7 +76,7 @@ update, but phase files are NEVER overwritten by upstream changes.**
 
 Skeleton files (SKILL.md) contain the generic orchestration — the workflow
 steps, the phase protocol, the default behaviors. These are authored by
-PIB and may improve over time. When upstream publishes a better skeleton,
+CoR and may improve over time. When upstream publishes a better skeleton,
 the upgrade skill can propose replacing it.
 
 Phase files contain the project's customizations — what specific files to
@@ -95,13 +95,13 @@ between the two.
 ### 1. Detect Current State
 
 Read `phases/detect-current.md` for how to inventory the project's
-current PIB adoption.
+current CoR adoption.
 
-**Default (absent/empty):** Scan the project for PIB artifacts:
-- For each skill in `.claude/skills/`: is it a PIB skeleton? Which
+**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 PIB?
+- What hooks are installed from CoR?
 - What pib-db schema version is in use (check for known columns)?
 - What's in `memory/patterns/`?
 
@@ -111,7 +111,7 @@ the diff phase.
 ### 2. Diff Against Upstream
 
 Read `phases/diff-upstream.md` for how to compare the project's state
-against the upstream PIB package.
+against the upstream CoR package.
 
 **Default (absent/empty):** Look for `.pib-upstream/` in the project
 root (staged by `npx create-claude-rails upgrade`). For each
@@ -209,8 +209,8 @@ the workflow. Execute them at their declared position.
 ## Proactive Trigger
 
 The upgrade skill doesn't have to wait for the user to invoke it.
-Orient can detect when upstream PIB files are newer than the project's
-adopted copies and surface "PIB updates available" in the briefing.
+Orient can detect when upstream CoR files are newer than the project's
+adopted copies and surface "CoR updates available" in the briefing.
 This is a hint, not a blocker — the user decides when to run /upgrade.
 
 To enable this, a project's orient `phases/health-checks.md` or a
@@ -242,7 +242,7 @@ that erase hard-won customizations.
 
 ### Without Skill (Bad)
 
-New PIB skeletons arrive. The user manually diffs files, trying to
+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
@@ -253,7 +253,7 @@ spent two sessions tuning is gone, replaced by the upstream default.
 
 ### With Skill (Good)
 
-New PIB skeletons arrive. The user runs `/upgrade`. Claude inventories
+New CoR skeletons arrive. The user runs `/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?"

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

@@ -71,9 +71,9 @@ Commit after each logical group of changes:
   skeleton changes)
 
 Commit messages should describe what was upgraded:
-"Upgrade orient + debrief skeletons from upstream PIB"
-"Add trigger_condition column (PIB schema migration)"
-"Adopt /validate skill from PIB"
+"Upgrade orient + debrief skeletons from upstream CoR"
+"Add trigger_condition column (CoR schema migration)"
+"Adopt /validate skill from CoR"
 
 ## Summary
 

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

@@ -1,12 +1,12 @@
-# Detect Current — Inventory PIB Adoption State
+# Detect Current — Inventory Claude on Rails Adoption State
 
-Build a structured manifest of the project's current PIB adoption. This
+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
 `.pibrc.json` for version and module metadata, then scan the project's
-`.claude/skills/`, perspectives, hooks, and database for PIB artifacts.
+`.claude/skills/`, perspectives, hooks, and database for CoR artifacts.
 To explicitly skip detection, write only `skip: true`.
 
 ## What to Inventory
@@ -30,9 +30,9 @@ back to pure filesystem diffing.
 ### Skills
 
 For each directory in `.claude/skills/`:
-- **Is it a PIB skeleton?** Compare the SKILL.md against the upstream
+- **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 PIB skill.
+  (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
@@ -49,13 +49,13 @@ For each directory in `.claude/skills/`:
 ### Hooks
 
 - Read `.claude/settings.json` (or `.claude/settings.local.json`).
-- Identify which hooks were installed as part of PIB adoption vs
+- 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 PIB columns. Record which tables and columns exist.
+  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).
 

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

@@ -1,7 +1,7 @@
-# Diff Upstream — Compare Project Against PIB Package
+# Diff Upstream — Compare Project Against Claude on Rails Package
 
 Compare the project's current adoption state (from detect-current) against
-the upstream PIB package. Produce a categorized list of changes.
+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
@@ -59,7 +59,7 @@ new tables, new indexes.
 
 - New hooks in upstream's recommended settings.
 - New rules files in upstream's `.claude/rules/`.
-- Changes to the PIB onboarding or seed skills.
+- Changes to the CoR onboarding or seed skills.
 
 ## Output Format