create-claude-rails 0.1.0

package/templates/skills/plan/phases/calibration-examples.md

@@ -0,0 +1,75 @@
+# Calibration Examples — Detailed Before/After Plans
+
+Provide project-specific before/after plan examples showing exact
+formatting. The /plan skill reads this file during calibration to
+reinforce what good and bad plans look like in your project's context.
+
+When this file is absent or empty, the default behavior is: use the
+narrative calibration examples in the skeleton only. To explicitly skip
+detailed examples, write only `skip: true`.
+
+## What to Include
+
+At least one bad plan and one good plan using your project's actual plan
+template format. Show:
+- Real-looking (but anonymized) content
+- The specific failure modes your project has encountered
+- How surface area, acceptance criteria, and feature completeness differ
+
+## Default Examples
+
+These generic examples apply to any project using the standard template:
+
+### Bad Plan
+
+```markdown
+## Implementation
+1. Add onProjectEmpty callback to useProjectActions hook
+2. Update FolderCard to accept the callback
+
+## Surface Area
+- files: hooks/useProjectActions.ts
+- files: components/FolderCard.tsx
+
+## Verification
+- Verify it works correctly
+- Check that the callback fires
+```
+
+Problems: Surface area is incomplete (page components that wire the
+callback are missing — the callback exists but nothing calls it).
+Verification criteria are untestable ("works correctly" is not pass/fail).
+The plan delivers dead code: an API nobody invokes.
+
+### Good Plan
+
+```markdown
+## Problem
+When all actions in a project's folder are completed or moved, the folder
+stays open with an empty list. Users have to manually navigate away.
+Auto-closing or prompting would reduce friction.
+
+## Implementation
+1. Add onProjectEmpty callback to useProjectActions hook (hooks/useProjectActions.ts)
+2. Implement empty-detection logic: after action complete/move, check remaining count
+3. Update FolderCard to accept and invoke onProjectEmpty (components/FolderCard.tsx)
+4. Wire callback in ActionsPage and ProjectDetailPage to navigate back on empty
+5. Add empty-state message for the brief moment before navigation
+
+## Surface Area
+- files: hooks/useProjectActions.ts
+- files: components/FolderCard.tsx
+- files: pages/ActionsPage.tsx
+- files: pages/ProjectDetailPage.tsx
+
+## Acceptance Criteria
+- [auto] TypeScript compiles clean: npx tsc -b --noEmit returns 0 errors
+- [auto] Completing last action in a project via API triggers callback (test with curl)
+- [manual] Completing last visible action in FolderCard navigates user back to parent view
+- [manual] Empty state message appears briefly before navigation
+- [manual] Projects with remaining actions are unaffected
+```
+
+Surface area includes every file mentioned in implementation. AC are
+pass/fail with [auto]/[manual] tags. The plan delivers a complete feature
+the user can see and verify — no dead code.

package/templates/skills/plan/phases/completeness-check.md

@@ -0,0 +1,44 @@
+# Completeness Check — Domain-Specific Completeness Rules
+
+Define additional completeness rules beyond the three generic checks
+(feature completeness, surface area completeness, testable AC). The
+/plan skill reads this file and applies these rules alongside the
+generic checks.
+
+When this file is absent or empty, the default behavior is: apply only
+the three generic completeness checks defined in the skeleton. To
+explicitly skip completeness checking, write only `skip: true`.
+
+## What to Include
+
+Domain-specific rules that catch incomplete plans in your project:
+- **Required artifacts** — what every plan of a certain type must include
+- **Coupling rules** — "if you change X, you must also change Y"
+- **Category-specific requirements** — different plan types have different
+  completeness criteria
+
+## Example Completeness Rules
+
+Uncomment and adapt these for your project:
+
+<!--
+### API Changes
+- Every new endpoint must include auth middleware in the surface area
+- Every schema change must include a migration script
+- Every API change must include at least one [auto] AC that exercises it
+
+### UI Changes
+- Every new page must include mobile viewport AC ([manual] at 375px)
+- Every new component must include empty state handling
+- If adding a page, App.tsx routing must be in the surface area
+
+### Infrastructure Changes
+- Cost estimate required for new services or storage
+- Rollback plan required for data migrations
+- Monitoring/alerting changes must accompany new infrastructure
+
+### Coupling Rules
+- Changes to the DB schema require corresponding API endpoint updates
+- Changes to API response format require corresponding frontend updates
+- Changes to shared types require checking all consumers
+-->

package/templates/skills/plan/phases/composition-check.md

@@ -0,0 +1,36 @@
+# Composition Check — Reusable Component Duplication
+
+Check whether the planned work duplicates existing reusable components
+in your project. The /plan skill reads this file after drafting and
+before perspective critique.
+
+When this file is absent or empty, the default behavior is: skip this
+phase entirely. To explicitly opt out, write only `skip: true`.
+
+## What to Include
+
+- **What counts as a reusable component** — skills, plugins, middleware,
+  shared libraries, utilities, templates
+- **How to search** — grep patterns, directory scans, registry queries
+- **What to check** — duplication of logic, missing dependency declarations
+
+## Example Composition Check
+
+Uncomment and adapt these for your project:
+
+<!--
+### Search for Duplication
+When the plan involves creating or modifying a reusable component
+(skill, plugin, middleware, etc.):
+
+1. Search existing components for overlapping keywords (API endpoints,
+   data-fetching patterns, routing logic).
+2. If overlap exists, the plan should compose with the existing component
+   (invoke it) rather than duplicate its logic.
+3. If the new component depends on others, declare the relationships
+   in the plan (e.g., `related` entries, dependency notes).
+
+### Skip When
+- The plan doesn't involve reusable components
+- The plan is a one-off task (bug fix, configuration change)
+-->

package/templates/skills/plan/phases/overlap-check.md

@@ -0,0 +1,62 @@
+# Overlap Check — Search for Existing Work
+
+Define how to search your project's work tracker for items that overlap
+with proposed work. The /plan skill reads this file before drafting to
+prevent duplicate plans.
+
+When this file is absent or empty, the default behavior is: query the
+reference data layer (pib-db) for open actions with similar text to the
+proposed work. If pib-db is not initialized, skip gracefully.
+
+## Default Behavior (pib-db)
+
+When no custom overlap check is configured:
+
+```bash
+# Search open actions for keywords related to the proposed work
+node scripts/pib-db.js query "SELECT fid, text, substr(notes, 1, 200) as notes_preview FROM actions WHERE completed = 0 AND deleted_at IS NULL AND (text LIKE '%keyword%' OR notes LIKE '%keyword%')"
+```
+
+Search with multiple keywords derived from the proposed plan's problem
+description. Surface any matches: "Found N open actions that may overlap
+with this plan" — then list them so the user can decide whether to
+proceed, merge, or defer.
+
+If pib-db doesn't exist, skip with a note.
+
+## What to Include
+
+- **How to query** — the command, API call, or file to search
+- **What to search** — open items, recently closed items, deferred items
+- **Keywords** — search with multiple relevant terms, not just one
+
+## Example Overlap Check Patterns
+
+Uncomment and adapt these for your project:
+
+<!--
+### Database Tracker
+```bash
+sqlite3 project.db "SELECT id, text, substr(notes, 1, 200) FROM tasks WHERE completed = 0 AND (text LIKE '%keyword%' OR notes LIKE '%keyword%')"
+```
+Search with multiple keywords relevant to the problem space.
+
+### GitHub Issues
+```bash
+gh issue list --state open --search "keyword" --json number,title,labels
+gh issue list --state closed --search "keyword" --limit 5 --json number,title
+```
+Check both open and recently closed issues — someone may have already
+solved this or started and abandoned it.
+
+### Markdown Backlog
+```bash
+grep -i "keyword" backlog.md tasks.md TODO.md
+```
+Search across all task-tracking files.
+
+### Linear / Jira / External Tracker
+```bash
+curl -s "https://api.example.com/issues?q=keyword" -H "Authorization: Bearer $TOKEN"
+```
+-->

package/templates/skills/plan/phases/perspective-critique.md

@@ -0,0 +1,47 @@
+# Perspective Critique — How to Activate Expert Review
+
+Define which perspectives to activate during planning, any special rules,
+and any project-specific critique workflow. The /plan skill reads this
+file before running the perspective critique step.
+
+When this file is absent or empty, the default behavior is: scan all
+perspectives in `.claude/skills/perspectives/*/SKILL.md`, activate those
+whose activation signals match the plan's surface area or topic keywords,
+and spawn each as a parallel agent. To explicitly skip perspective
+critique (even if perspectives exist), write only `skip: true`.
+
+If no perspectives exist in the project, critique is skipped regardless.
+
+## What to Include
+
+- **Always-on perspectives** — perspectives that activate for every plan
+- **Special committees** — groups of perspectives that work together for
+  specific plan types (e.g., UI plans get a design committee)
+- **Escalation overrides** — project-specific rules for how to handle
+  verdicts (stricter or more lenient than default)
+- **Additional context** — anything perspectives need beyond `_context.md`
+
+## Example Perspective Critique Configuration
+
+Uncomment and adapt these for your project:
+
+<!--
+### Always-On for Planning
+These perspectives activate for every plan regardless of surface area:
+- security — every change has security implications
+- architecture — structural coherence across the codebase
+
+### Design Committee (UI Plans)
+When the plan's surface area includes UI files (pages/*.tsx,
+components/**/*.tsx), activate both of these as a committee:
+- information-design — produces visual mock, evaluates hierarchy
+- usability — critiques interaction model, accessibility
+
+If the design committee produces a mock, open it in the browser for
+user review. User approval covers plan AND mock.
+
+### Escalation Rules
+- Any **block** from security → stop, no override without explicit user ack
+- Architecture **conditional** → always address before presenting
+- Other **conditional** → include in presentation, user decides
+-->

package/templates/skills/plan/phases/plan-template.md

@@ -0,0 +1,69 @@
+# Plan Template — Your Project's Plan Structure
+
+Define the sections every plan should have and what each section contains.
+The /plan skill reads this file when drafting and structures the plan
+accordingly.
+
+When this file is absent or empty, the default template is used:
+Problem, Implementation, Surface Area, Acceptance Criteria. To explicitly
+skip (no template structure), write only `skip: true`.
+
+## What to Include
+
+- **Required sections** — what every plan must have
+- **Section descriptions** — what goes in each section, how detailed
+- **Optional sections** — sections to include when relevant
+- **Format conventions** — how to mark file paths, new files, categories
+
+## Example Plan Templates
+
+Uncomment and adapt these for your project:
+
+<!--
+### Standard Plan Template
+
+```markdown
+## Problem
+What friction, gap, or issue exists. Why this matters. Include links
+to related issues or feedback if applicable.
+
+## Implementation
+Numbered steps with file paths (`src/components/...`). Enough detail
+to execute without re-exploring. Each step should be independently
+verifiable where possible.
+
+## Surface Area
+Every file that will be created or modified:
+- files: path/to/file1.ext
+- files: path/to/file2.ext (new)
+- dirs: path/to/new-directory/ (new)
+
+## Acceptance Criteria
+Testable criteria — each marked by category:
+- [auto] Criteria verifiable by running a command
+- [manual] Criteria requiring human judgment or interaction
+- [deferred] Criteria that can't be tested until later
+
+## Design Decisions
+Key choices made and why. Include alternatives considered and why they
+were rejected. This helps future sessions evaluate whether the plan
+still makes sense if context has changed.
+```
+
+### Extended Template (for larger plans)
+
+Add these sections when the plan is complex:
+
+```markdown
+## Dependencies
+Other work items that must be completed first, or that this plan
+affects. Reference by ID, not by description.
+
+## Risk Assessment
+What could go wrong. What's the rollback plan if this doesn't work.
+
+## Migration / Rollout
+If this changes data or behavior, how to migrate. Can it be deployed
+incrementally?
+```
+-->

package/templates/skills/plan/phases/present.md

@@ -0,0 +1,60 @@
+# Present — How and Where to Present the Plan
+
+Define how to present the plan for user approval. The /plan skill reads
+this file when presenting the finished plan.
+
+When this file is absent or empty, the default behavior is: present the
+full plan inline in conversation with perspective critique summary,
+design decisions, and uncertainties. Wait for explicit approval.
+
+User approval is always required regardless of this file's content —
+this phase customizes HOW the plan is presented, not WHETHER. Using
+`skip: true` here skips the custom presentation but the skeleton still
+presents the plan and waits for approval.
+
+## What to Include
+
+- **Presentation format** — how to structure the presentation
+- **Required elements** — anything beyond the plan itself (cost, risk,
+  effort estimates, stakeholder impact)
+- **Medium** — where the plan is presented (conversation, document,
+  review tool, external system)
+- **Approval workflow** — who approves, how approval is captured
+
+## Example Presentation Configurations
+
+Uncomment and adapt these for your project:
+
+<!--
+### Standard Presentation
+Present inline in conversation with:
+1. The complete plan (all template sections)
+2. Perspective critique summary (concerns and verdicts)
+3. Design decisions and alternatives considered
+4. Open questions or uncertainties
+5. Estimated effort (S/M/L)
+
+Ask: "Does this plan look right? Anything to change before I file it?"
+
+### Document-Based Presentation
+For larger plans, write to a plan document:
+```bash
+# Write plan to a review file
+Write plan to docs/plans/YYYY-MM-DD-plan-title.md
+```
+Then present a summary in conversation with a link to the full document.
+
+### Review Tool Integration
+Post the plan to the project's review system:
+```bash
+# Example: post to a review channel or tool
+curl -X POST https://review-tool.example.com/api/plans \
+  -H "Content-Type: application/json" \
+  -d '{"title": "...", "body": "...", "author": "claude"}'
+```
+Present the link in conversation and wait for approval.
+
+### Multi-Stakeholder Plans
+For plans that affect multiple areas, present to each stakeholder
+and collect approval. Note who approved and any conditions.
+-->

package/templates/skills/plan/phases/research.md

@@ -0,0 +1,43 @@
+# Research — What to Investigate Before Planning
+
+Define what to always investigate before drafting a plan. The /plan skill
+reads this file and follows this guidance before proposing any solution.
+
+When this file is absent or empty, the default behavior is: explore the
+codebase to understand what files are involved, what patterns exist, what
+the current behavior is, and what constraints apply. To explicitly skip
+this phase (no default, no custom), write only `skip: true`.
+
+## What to Include
+
+Project-specific research guidance:
+- **Required reading** — files, docs, or external sources to always check
+- **Domain resources** — architecture decision records, design system docs,
+  API changelogs, wikis
+- **Consultation patterns** — "always check with [person/team] for changes
+  to [area]"
+- **External sources** — MCP servers, documentation sites, ecosystem tools
+
+## Example Research Guidance
+
+Uncomment and adapt these for your project:
+
+<!--
+### Always Read First
+- `docs/architecture-decisions/` — check for ADRs related to this area
+- `CHANGELOG.md` — understand recent changes that might affect this work
+- The relevant `CLAUDE.md` in the directory being modified
+
+### Domain Documentation
+Before proposing API changes, check the API style guide at `docs/api-style.md`.
+Before proposing UI changes, check the design system at `docs/design-system.md`.
+
+### External Sources
+Use the framework-docs MCP server to check for relevant framework patterns
+before proposing implementation approaches that might have well-known
+solutions.
+
+### Stakeholder Context
+For changes to shared infrastructure, check whether other teams have
+open work in the same area (query the issue tracker).
+-->

package/templates/skills/plan/phases/work-tracker.md

@@ -0,0 +1,95 @@
+# Work Tracker — How to File Work Items
+
+Define how to file an approved plan as a work item in your project's
+tracking system. The /plan skill reads this file after user approval.
+
+When this file is absent or empty, the default behavior is: create an
+action in the reference data layer (pib-db) with the plan summary in
+notes. If pib-db is not initialized, note that work tracking is available
+via `node scripts/pib-db.js init`.
+
+## Default Behavior (pib-db)
+
+When no custom work tracker is configured:
+
+```bash
+# Create an action for the approved plan
+node scripts/pib-db.js create-action "Short imperative plan title" \
+  --area "<area>" \
+  --notes "## Problem\n...\n\n## Implementation\n..."
+```
+
+Derive the area from the plan's context. Include the full plan in the
+action's notes so it's self-contained — the action IS the plan.
+
+If the plan relates to an existing project in pib-db, include
+`--project <project-fid>` to link them.
+
+If pib-db doesn't exist, note: "Work tracking available — run
+`node scripts/pib-db.js init` to set up. Plan saved in conversation
+only."
+
+## What to Include
+
+- **How to create items** — the API call, CLI command, or file operation
+- **Required fields** — what metadata to include (area, project, priority)
+- **How to determine fields** — where to look up the correct values
+- **Confirmation** — what to report back after creating
+
+## Example Work Tracker Configurations
+
+Uncomment and adapt these for your project:
+
+<!--
+### Database API
+```bash
+curl -X POST https://your-app.example.com/api/tasks \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $API_TOKEN" \
+  -d '{
+    "text": "Short imperative description",
+    "area": "<area>",
+    "projectId": "<project-id>",
+    "notes": "## Problem\n...\n\n## Implementation\n..."
+  }'
+```
+Look up the correct area from the project:
+```bash
+sqlite3 project.db "SELECT area FROM projects WHERE id = '...'"
+```
+
+### GitHub Issues
+```bash
+gh issue create --title "Plan: short description" \
+  --body "$(cat <<'EOF'
+## Problem
+...
+
+## Implementation
+...
+
+## Surface Area
+...
+
+## Acceptance Criteria
+...
+EOF
+)" --label "plan"
+```
+
+### Markdown File
+Write the plan to a tasks file:
+```markdown
+## [Plan Title] — YYYY-MM-DD
+Status: planned
+
+[full plan content]
+```
+
+### Report Back
+After creating, present:
+- Item ID/link
+- Project/area it was filed under
+- Status
+- Any open questions deferred
+-->