create-claude-rails 0.1.0

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

@@ -0,0 +1,97 @@
+# Merge — Intelligent Upgrade Conversation
+
+THE INTELLIGENCE. For each change detected by diff-upstream, walk
+through a conversational merge: explain, examine, propose, dialogue.
+
+When this file is absent or empty, the default behavior is: process
+each change using the category-based strategy defined in the skeleton
+SKILL.md. To explicitly skip merging (just list changes without
+proposing anything), write only `skip: true`.
+
+## The Merge Loop
+
+For each change in the categorized list:
+
+### 1. Explain What Changed and Why
+
+Read the upstream change in full. Don't summarize from the diff — read
+the actual new content. Infer purpose from:
+- The change itself (what does it add, remove, or alter?)
+- Surrounding documentation (did a README or methodology essay mention it?)
+- Commit messages if accessible
+- The pattern of changes (if several skeletons gained the same phase,
+  that's a methodology-wide shift)
+
+Communicate at the level of intent, not lines: "The orient skeleton now
+checks for stale deferred items because projects found that deferred
+work was being forgotten" — not "lines 140-155 were added."
+
+### 2. Examine the Project's Current Implementation
+
+Before proposing anything, understand how the project handles this area:
+- Read the relevant phase files (customized? default? skipped?)
+- Check if the project has custom phases that address the same concern
+- Look at related memory patterns or feedback
+- Understand why the project's current approach exists
+
+### 3. Propose Adaptation
+
+Based on the change category:
+
+**Category 1 (new default):** "This applies automatically since you're
+using the default. Here's what it adds: [description]. No action needed
+unless you want to customize it."
+
+**Category 2 (changed default):** "The default behavior for [phase]
+changed from [old] to [new]. You're currently using the default. The
+new version [explanation]. Adopt the new default, or would you prefer
+to pin the old behavior by writing it into your phase file?"
+
+**Category 3 (new phase):** "Upstream added a [name] phase to [skill].
+It handles [description]. Your project [does/doesn't] have something
+similar. Want to opt in, or skip it for now?"
+
+**Category 4 (changed workflow):** "The [skill] skeleton's workflow
+changed: [description]. Your project has customized [these phases].
+Here's how I'd adapt: [proposal]. Let's walk through it."
+
+**Category 5 (new skill):** "There's a new [name] skill available. It
+handles [description]. Adopting it would involve [steps]. Want to
+explore it, or skip for now?"
+
+**Category 6 (schema migration):** "The upstream schema adds [columns/
+tables]. Here's the migration SQL: [SQL]. This would enable [features].
+Want me to apply it?"
+
+### 4. Dialogue
+
+Wait for the user's response. They may:
+- Accept as proposed
+- Want modifications (co-author the adaptation)
+- Skip with a reason (record why for future upgrades)
+- Ask questions (answer from upstream context)
+
+## CRITICAL: Phase File Protection
+
+Phase files are NEVER overwritten by this process. The merge handles:
+- Skeleton SKILL.md updates (the generic orchestration)
+- New capabilities and defaults
+- Schema migrations
+- New skills and perspectives
+
+It does NOT handle:
+- Replacing project phase files with upstream examples
+- Overwriting custom perspectives
+- Changing project-specific hook configurations
+
+If an upstream change interacts with a phase file's content (e.g., a
+skeleton now references a concept the phase file also addresses), propose
+a **collaborative edit** — show the user what you'd change in their
+phase file and why, get approval before touching it.
+
+## Batch vs Interactive
+
+For small upgrades (1-3 changes), walk through each one interactively.
+For large upgrades (many changes), group by category and handle
+auto-adopt items (category 1) in batch, then walk through the rest
+individually.

package/templates/skills/validate/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: validate
+description: |
+  Run structural validation checks and present a unified summary. The
+  orchestration pattern is generic; the specific validators are project-defined
+  in phases/validators.md. Use when: "validate", "run checks", "/validate",
+  or after any structural changes.
+related:
+  - type: file
+    path: .claude/skills/validate/phases/validators.md
+    role: "Project-specific validator definitions"
+  - type: file
+    path: .claude/skills/perspectives/_context.md
+    role: "Scan scopes for validation targets"
+---
+
+# /validate — Run All Validation Checks
+
+## Purpose
+
+Run every configured validator and report results in a unified summary.
+Zero errors is the standard.
+
+This is a **skeleton skill** using the `phases/` directory pattern. The
+orchestration (run → collect → report) is generic. Your project defines
+which validators to run in `phases/validators.md`.
+
+### Phase File Protocol
+
+Phase files have three states:
+
+| State | Meaning |
+|-------|---------|
+| Absent or empty | Use this skeleton's **default behavior** for the phase |
+| Contains only `skip: true` | **Explicitly opted out** — skip this phase entirely |
+| Contains content | **Custom behavior** — use the file's content instead |
+
+## Workflow
+
+### 1. Read Validators
+
+Read `phases/validators.md` for the list of project-specific checks.
+Each validator has a name, command, and description of what it catches.
+
+If `phases/validators.md` is empty or missing, report that no validators
+are configured and suggest the user define some.
+
+### 2. Run Each Validator
+
+Execute each validator command in sequence. For each:
+- Run the command
+- Capture stdout/stderr and exit code
+- Record pass (exit 0) or fail (non-zero) with output
+
+If a validator fails, continue running the rest — don't stop at the
+first failure. The point is a complete picture.
+
+### 3. Report
+
+Present a unified summary:
+
+```
+## Validation Results
+
+| Check | Status | Details |
+|-------|--------|---------|
+| {name} | PASS/FAIL | {error count or "clean"} |
+| ... | ... | ... |
+
+### Errors
+{For each failed check, list the specific errors}
+```
+
+If errors found:
+- For quick fixes (obvious typo, missing tag): propose the fix
+- For complex issues: suggest creating a plan via /plan
+- Never silently skip errors
+
+### 4. Terminal State
+
+- All pass → ready to commit and deploy
+- Any fail → fix errors and re-validate
+
+## Extending
+
+To add a new validator:
+1. Add an entry to `phases/validators.md`
+2. Ensure the script/command exists and returns exit 0 on success
+3. Run `/validate` to confirm it works
+
+To skip a validator temporarily: comment it out in `phases/validators.md`.
+
+To add a phase the skeleton doesn't define: create a new file in `phases/`
+(e.g., `phases/pre-validate.md` for setup steps). Claude reads whatever
+phase files exist at runtime.
+
+## Calibration
+
+**Core failure this targets:** Committing or deploying code that has
+structural problems (broken references, type errors, lint violations)
+because checks weren't run or results weren't reviewed.
+
+### Without Skill (Bad)
+
+Developer makes changes across several files, commits, and deploys.
+The deploy fails because of a type error that local checking would have
+caught. Or worse: the deploy succeeds but a broken cross-reference
+causes a runtime error that isn't discovered for days.
+
+### With Skill (Good)
+
+Developer runs `/validate` after changes. The unified summary shows
+one type error and one structural issue. Both are fixed before commit.
+The deploy succeeds cleanly. The structural issue would have caused a
+subtle bug that wouldn't have surfaced until a user hit a specific
+code path.

package/templates/skills/validate/phases/validators.md

@@ -0,0 +1,53 @@
+# Validators
+
+Define your project-specific validation checks here. Each validator is
+a named check with a command to run. The /validate skill reads this file
+and executes each check in sequence.
+
+## Format
+
+For each validator, provide:
+- **Name** — short label for the summary table
+- **Command** — shell command that returns exit 0 on success, non-zero on failure
+- **What it catches** — brief description of what this validator detects
+
+## Example Validators
+
+Uncomment and adapt these for your project:
+
+<!--
+### Type Check
+```bash
+cd your-app-dir && npx tsc --noEmit
+```
+Catches type errors before they reach production.
+
+### Lint
+```bash
+cd your-app-dir && npx eslint src/
+```
+Catches style violations and common code quality issues.
+
+### Production Build
+```bash
+cd your-app-dir && npx vite build
+```
+Catches what the type checker misses: bare catch blocks, runtime-only
+errors, bundle resolution failures. A type check pass + build fail =
+broken deploy.
+
+### Structural Validation
+```bash
+./scripts/validate-structure.sh
+```
+Project-specific structural checks (e.g., required files exist, cross-references
+are valid, configuration is consistent). Write these scripts for your
+project's invariants.
+
+### Memory/Docs Validation
+```bash
+./scripts/validate-docs.sh
+```
+Checks that documentation references (memory index, CLAUDE.md links) point
+to files that actually exist.
+-->