create-claude-rails 0.1.0

package/templates/skills/orient/SKILL.md

@@ -0,0 +1,240 @@
+---
+name: orient
+description: |
+  Session start orientation. Reads project state, syncs data, scans work
+  items, runs health checks and maintenance, then presents a briefing so
+  the session starts informed. This is a skeleton skill using the phases/
+  directory pattern. Use when: session start, "orient", "what's the state",
+  "/orient".
+related:
+  - type: file
+    path: .claude/skills/orient/phases/context.md
+    role: "Project-specific: what to read at session start"
+  - type: file
+    path: .claude/skills/orient/phases/data-sync.md
+    role: "Project-specific: how to sync fresh data"
+  - type: file
+    path: .claude/skills/orient/phases/work-scan.md
+    role: "Project-specific: what work items to check"
+  - type: file
+    path: .claude/skills/orient/phases/health-checks.md
+    role: "Project-specific: system health checks"
+  - type: file
+    path: .claude/skills/orient/phases/auto-maintenance.md
+    role: "Project-specific: recurring session-start tasks"
+  - type: file
+    path: .claude/skills/orient/phases/briefing.md
+    role: "Project-specific: how to present the orientation"
+  - type: file
+    path: .claude/skills/orient/phases/perspectives.md
+    role: "Project-specific: which perspectives to activate"
+  - type: file
+    path: .claude/skills/perspectives/_context.md
+    role: "Project identity and configuration"
+---
+
+# /orient — Session Orientation
+
+## Purpose
+
+Start every session with a clear picture of current state so the user
+doesn't have to carry it in their head. Without orientation, Claude starts
+blind — makes the same mistakes, asks the same questions, misses what
+changed since last time. The session loop is the system's learning
+mechanism: orient reads the past, debrief writes the future.
+
+This is a **skeleton skill** using the `phases/` directory pattern. The
+orchestration (what to do and in what order) is generic. Your project
+defines the specifics — what files to read, what data to sync, what work
+items to check — in phase files under `phases/`.
+
+### 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 |
+
+The skeleton always does something reasonable when a phase file is absent.
+Phase files customize, not enable. Use `skip: true` when you actively
+don't want a phase to run — not even the default.
+
+## Why This Matters
+
+If Claude Code starts a session without reading what happened last time,
+it has no memory. If it ends a session without recording what happened,
+the next session starts blind. Orient doesn't need to be complex — a
+minimal orient reads a project description and a status file. A mature
+orient pulls fresh data, checks queues, evaluates health, and surfaces
+what needs attention. The complexity grows from use: each check gets
+added because its absence caused a problem. But the loop itself must
+exist from day one, or nothing that follows has a foundation.
+
+## Workflow
+
+### 1. Load Context (core)
+
+Read `phases/context.md` for the list of files and state to load at
+session start. This typically includes status files, memory from prior
+sessions, and project-specific context.
+
+**Default (absent/empty):** Read at minimum:
+- The project's root `CLAUDE.md` (already loaded by Claude Code)
+- `system-status.md` or equivalent state file if one exists
+- Memory files from prior sessions if the project uses memory
+
+The goal: build a mental model of where things stand before doing
+anything else.
+
+### 2. Sync Data (core)
+
+Read `phases/data-sync.md` for how to pull fresh canonical data from
+remote sources (databases, APIs, shared storage).
+
+**Skip (absent/empty).** Purely local projects don't need it. Projects
+with remote canonical data stores define their sync commands here.
+
+Report if sync fails — a stale local cache is better than no data, but
+the user should know it's stale.
+
+### 3. Scan Work Items (core)
+
+Read `phases/work-scan.md` for what work items to check. This includes
+whatever the project uses to track work: a backlog, task list, inbox,
+queue, or issue tracker.
+
+**Skip (absent/empty).** But note: without work scanning, orient can
+only report on project state, not on what needs doing. This phase is
+what connects orientation to action.
+
+### 4. Health Checks (core)
+
+Read `phases/health-checks.md` for system health and validation checks
+to run at session start. These catch problems early — stale data, broken
+references, failed background processes, configuration drift.
+
+**Skip (absent/empty).** Projects add health checks as they discover
+failure modes worth detecting early.
+
+> **Orient vs Pulse vs Audit:** Orient health checks verify *operational*
+> state — is the system running, is data fresh, are processes alive?
+> Pulse (embedded in orient) verifies *descriptive* accuracy — do counts
+> match, do documented states match reality? Audit verifies *quality*
+> through expert perspectives — is the code sound, are conventions
+> holding? Orient runs every session; pulse runs inside it; audit runs
+> periodically. Each asks a different question about the same system.
+
+### 5. Auto-Maintenance (core)
+
+Read `phases/auto-maintenance.md` for recurring automated tasks that
+should run every session. These are operations that would decay if left
+to human memory — the anti-entropy principle in action.
+
+**Skip (absent/empty).** Projects add maintenance tasks as they discover
+operations that need regular execution but aren't worth remembering to
+invoke manually.
+
+### 6. Activate Perspectives (core)
+
+Read `phases/perspectives.md` for which expert perspectives or lenses
+should be active during this session. Perspectives watch for specific
+concerns (quality, security, process adherence, non-project items)
+without being explicitly invoked for each decision.
+
+**Skip (absent/empty).**
+
+### 7. Present Briefing (presentation)
+
+Read `phases/briefing.md` for how to present the orientation results.
+This phase controls format, sections, tone, and any time-aware or
+context-aware presentation modes.
+
+**Default (absent/empty):** Present a simple summary of what was gathered
+in steps 1-6: project state, work items needing attention, any health
+issues found, maintenance results.
+
+### 8. Discover Custom Phases
+
+After running the core phases above, check for any additional phase
+files in `phases/` that the skeleton doesn't define. These are project-
+specific extensions. Each custom phase file declares its position in the
+workflow (e.g., "runs after work scan, before briefing"). Execute them
+at their declared position.
+
+### 9. Name the Session
+
+Rename the session so the sidebar is scannable. Every session that starts
+with `/orient` looks identical in the history — naming fixes this.
+
+After the briefing and the user's response, derive a short name (3-6
+words) from what the user says they're working on. If the user hasn't
+stated a focus, ask.
+
+## Phase Summary
+
+| Phase | Absent = | What it customizes |
+|-------|----------|-------------------|
+| `context.md` | Default: read CLAUDE.md, status, memory | What files and state to load |
+| `data-sync.md` | Skip | How to sync remote data |
+| `work-scan.md` | Skip | What work items to check |
+| `health-checks.md` | Skip | System health checks |
+| `auto-maintenance.md` | Skip | Recurring session-start tasks |
+| `perspectives.md` | Skip | Which perspectives to activate |
+| `briefing.md` | Default: simple summary | How to present orientation |
+
+## Quick Mode
+
+Phases are either **core** (maintain system state) or **presentation**
+(surface information for the user). For lightweight sessions where the
+user already knows what they're doing, skip presentation phases. Core
+phases always run because they keep the system healthy.
+
+- **Core phases** (always run): context, data-sync, work-scan,
+  health-checks, auto-maintenance, perspectives
+- **Presentation phases** (skippable): briefing
+
+A project that wants a quick orient variant skips the briefing phase
+and outputs a one-line confirmation instead.
+
+## Extending
+
+To customize a phase: write content in the corresponding `phases/` file.
+To skip a phase: leave the file empty or don't create it.
+To add a phase the skeleton doesn't define: create a new file in
+`phases/` with a description of when it runs relative to the core
+phases. Claude reads whatever phase files exist at runtime.
+
+Examples of phases mature projects add:
+- Command queue processing (check for instructions from external UIs)
+- Deferred item evaluation (re-check trigger conditions on paused work)
+- Time-aware briefing modes (morning briefing vs. standard session)
+- Proactive skill suggestions (surface tools relevant to current state)
+- Calendar integration (upcoming events that need preparation)
+
+## Calibration
+
+**Core failure this targets:** Starting a session without context, forcing
+the user to reconstruct state from memory or ask for information the
+system already has.
+
+### Without Skill (Bad)
+
+New session starts. Claude says "How can I help?" The user asks about
+their project status — Claude searches files, reads logs, gives a partial
+picture. The user asks about pending tasks — Claude queries again. The
+user mentions something from last session — Claude has no memory of it.
+
+Three round trips to assemble context that one orientation would have
+surfaced. Meanwhile, an overdue deadline sits unmentioned because nobody
+asked about it.
+
+### With Skill (Good)
+
+New session starts. Claude loads project state, syncs fresh data, scans
+the work backlog, and presents: here's where things stand, here's what
+needs attention, here's what changed since last time. The overdue item
+is surfaced before the user has to remember it. One message, full
+picture. The user decides what to work on from an informed position.

package/templates/skills/orient/phases/auto-maintenance.md

@@ -0,0 +1,48 @@
+# Auto-Maintenance — Recurring Session-Start Tasks
+
+Define automated tasks that should run every session. These are operations
+that would decay if left to human memory — the anti-entropy principle
+applied to session management.
+
+The distinction from health checks: health checks DETECT problems;
+auto-maintenance DOES work. A health check reports "data is stale."
+
+When this file is absent or empty, this step is skipped. (`skip: true`
+is equivalent to absent here.)
+An auto-maintenance task runs the sync to fix it.
+
+## What to Include
+
+For each task, provide:
+- **What** — the operation to perform
+- **Why every session** — what decays if this is skipped
+- **Command** — how to run it
+- **Auto-execute?** — yes (run silently) or surface (ask user first)
+
+## Example Maintenance Tasks
+
+Uncomment and adapt these for your project:
+
+<!--
+### Process Pending Queue Items
+```bash
+# Check for items queued by external systems
+curl -s https://your-api.example.com/api/queue/pending
+```
+Items queued from a UI or external integration since last session.
+Auto-execute routine items; surface unusual ones for confirmation.
+
+### Rotate Logs
+```bash
+# Truncate logs that grow unbounded
+tail -1000 sync/app.log > sync/app.log.tmp && mv sync/app.log.tmp sync/app.log
+```
+Prevents log files from consuming disk. Silent, no user interaction.
+
+### Refresh Cached Computations
+```bash
+./scripts/rebuild-index.sh
+```
+Regenerates derived data that may have drifted from source files.
+Run if source files changed since last session.
+-->

package/templates/skills/orient/phases/briefing.md

@@ -0,0 +1,53 @@
+# Briefing — How to Present the Orientation
+
+Define how to present the results of orientation to the user. This is
+the presentation phase — it can be skipped in quick mode without losing
+any system maintenance value.
+
+When this file is absent or empty, the default behavior is: present a
+simple summary of project state, work items, and any health issues.
+To explicitly skip the briefing, write only `skip: true`.
+
+## What to Include
+
+- **Format** — how to structure the briefing (sections, order, grouping)
+- **Tone** — how to communicate (practical, warm, terse, etc.)
+- **Modes** — if your project uses different presentation modes (e.g.,
+  morning vs. standard, verbose vs. compact), define them here
+- **Suggestions** — contextual recommendations based on gathered data
+
+## Example Briefing Formats
+
+Uncomment and adapt these for your project:
+
+<!--
+### Standard Briefing
+
+Present in this order:
+1. **Items needing attention** — overdue, flagged, or blocked work
+2. **Inbox** — counts of unprocessed items
+3. **Recent activity** — what changed since last session
+4. **Suggested focus** — 1-3 items grounded in data, not generic
+
+Tone: direct, practical. Lead with what matters most.
+Close with: "What are we working on?"
+
+### Compact Briefing (quick mode fallback)
+
+One line per category, counts only:
+```
+Overdue: 2 | Due today: 1 | Inbox: 5 | Health: OK
+```
+No suggestions, no narrative. Just the numbers.
+
+### Time-Aware Modes
+
+If the session time matters for your project:
+- **Morning** (first session of day): include calendar, completions
+  since yesterday, day-ahead view
+- **Evening** (after 5pm): include tomorrow preview, prep needed
+- **Standard** (all other): focus on work surface and system state
+
+Track which mode ran today with a datestamp file to avoid repeating
+the morning briefing on subsequent sessions.
+-->

package/templates/skills/orient/phases/context.md

@@ -0,0 +1,47 @@
+# Context — What to Read at Session Start
+
+Define what files and state to load so the session starts with a model
+of where things stand. The /orient skill reads this file and loads each
+item before proceeding.
+
+When this file is absent or empty, the default behavior is: read the
+project's root CLAUDE.md, system-status.md, and relevant memory files.
+To explicitly skip context loading, write only `skip: true`.
+
+## What to Include
+
+For each context source, provide:
+- **What** — the file or data to read
+- **Why** — what it tells you about current state
+- **How** — the command or tool to read it (Read tool, sqlite3, curl, etc.)
+
+## Example Context Sources
+
+Uncomment and adapt these for your project:
+
+<!--
+### System Status
+```
+Read system-status.md
+```
+The single-source-of-truth for what's built, what's broken, and what's
+next. Read every session — it's the fastest way to know where things
+stand.
+
+### Memory Files
+```
+Read memory/MEMORY.md for the index, then load files relevant to the
+session's likely focus.
+```
+Persistent context from prior sessions — user preferences, project
+state, feedback patterns, references. Don't read everything — scan
+the index and load what's relevant.
+
+### Project-Specific State
+```
+Read config/project-state.yaml
+```
+Whatever your project uses to track configuration, feature flags,
+environment state, or deployment status. Anything that changes between
+sessions and affects how you work.
+-->

package/templates/skills/orient/phases/data-sync.md

@@ -0,0 +1,35 @@
+# Data Sync — How to Pull Fresh Canonical Data
+
+Define how to sync data from remote canonical sources so the local
+environment has current information. The /orient skill reads this file
+and runs each sync step before scanning work items.
+
+When this file is absent or empty, this step is skipped — purely local
+projects don't need it. (`skip: true` is equivalent to absent here.)
+
+## What to Include
+
+For each sync source, provide:
+- **Source** — where the canonical data lives
+- **Command** — how to pull it locally
+- **Failure handling** — what to do if sync fails (use stale data? report?)
+
+## Example Sync Sources
+
+Uncomment and adapt these for your project:
+
+<!--
+### Database Sync
+```bash
+./scripts/sync-db.sh --pull
+```
+Pulls the production database to a local cache. If this fails, note
+staleness and continue — stale data is better than no data.
+
+### API State Refresh
+```bash
+curl -s https://your-api.example.com/api/status > .cache/api-status.json
+```
+Fetches current state from a remote API. Cache locally so subsequent
+queries during the session don't require network calls.
+-->

package/templates/skills/orient/phases/health-checks.md

@@ -0,0 +1,50 @@
+# Health Checks — System Health at Session Start
+
+Define health and validation checks to run early in the session. These
+catch problems before they waste time — stale data, broken references,
+failed background processes, configuration drift.
+
+Projects add health checks as they discover failure modes worth detecting
+early. A new project may have none; a mature project may have many.
+
+When this file is absent or empty, this step is skipped. (`skip: true`
+is equivalent to absent here.)
+
+## What to Include
+
+For each check, provide:
+- **Name** — short label for reporting
+- **Command** — how to run the check
+- **What it catches** — what failure looks like
+- **Severity** — blocking (stop and fix) vs. warning (note and continue)
+
+## Example Health Checks
+
+Uncomment and adapt these for your project:
+
+<!--
+### Data Freshness
+```bash
+# Check if local data cache is recent enough to trust
+LAST_SYNC=$(stat -f %m .cache/db.sqlite 2>/dev/null || echo 0)
+NOW=$(date +%s)
+AGE=$(( (NOW - LAST_SYNC) / 3600 ))
+[ "$AGE" -lt 24 ] && echo "fresh" || echo "STALE: ${AGE}h old"
+```
+Warns if local data hasn't been synced in over 24 hours. Not blocking —
+stale data is usable but may be wrong.
+
+### Background Process Health
+```bash
+# Check if a background process is still running
+pgrep -f "your-daemon" > /dev/null && echo "running" || echo "NOT RUNNING"
+```
+Warns if a background process that should be running has stopped.
+
+### Reference Integrity
+```bash
+./scripts/validate-refs.sh
+```
+Checks that cross-references between files are still valid. Catches
+renames and deletions that break links.
+-->

package/templates/skills/orient/phases/perspectives.md

@@ -0,0 +1,46 @@
+# Perspectives — Which Expert Lenses to Activate
+
+Define which perspectives (expert evaluation lenses) should be active
+during this session. Active perspectives watch for specific concerns
+throughout the session without being explicitly invoked for each decision.
+
+When this file is absent or empty, this step is skipped. (`skip: true`
+is equivalent to absent here.)
+
+## What to Include
+
+For each perspective, provide:
+- **Name** — the perspective to activate
+- **Path** — where the perspective's SKILL.md lives
+- **When active** — always, or only under certain conditions
+- **What it watches for** — the concern this lens monitors
+
+## Example Perspective Configurations
+
+Uncomment and adapt these for your project:
+
+<!--
+### Always-On Perspectives
+
+These activate every session regardless of focus:
+
+**QA Perspective** (`.claude/skills/perspectives/qa/SKILL.md`):
+Watches for untested changes, missing edge cases, and quality gaps.
+Active whenever code is being written or modified.
+
+**Process Perspective** (`.claude/skills/perspectives/process/SKILL.md`):
+Watches for process deviations — skipped steps, missing validation,
+undocumented decisions. Active every session.
+
+### Conditional Perspectives
+
+These activate based on session context:
+
+**Security Perspective** (`.claude/skills/perspectives/security/SKILL.md`):
+Activate when the session involves authentication, data handling,
+external APIs, or user input processing.
+
+**Performance Perspective** (`.claude/skills/perspectives/performance/SKILL.md`):
+Activate when the session involves database queries, rendering logic,
+or data processing at scale.
+-->

package/templates/skills/orient/phases/work-scan.md

@@ -0,0 +1,69 @@
+# Work Scan — What Work Items to Check
+
+Define what work items to scan so orient can surface what needs attention.
+This is what connects orientation to action — without it, orient can
+only report on project state, not on what needs doing.
+
+When this file is absent or empty, the default behavior is: query the
+reference data layer (pib-db) for open actions and projects. If pib-db
+is not initialized, skip gracefully with a note that work tracking is
+available via `node scripts/pib-db.js init`.
+
+## Default Behavior (pib-db)
+
+When no custom work-scan is configured, query pib-db:
+
+```bash
+# Open actions (overdue first, then due today, then flagged, then recent)
+node scripts/pib-db.js list-actions
+
+# Active projects with open action counts
+node scripts/pib-db.js list-projects
+```
+
+Present grouped by urgency:
+- **Overdue** — actions with `due` before today
+- **Due today** — actions with `due` = today
+- **Flagged** — actions with `flagged = 1`
+- **Recent** — actions created in the last 7 days
+
+If pib-db doesn't exist (file not found), skip with: "Work tracking
+available — run `node scripts/pib-db.js init` to set up."
+
+## What to Include
+
+For each work source, provide:
+- **What** — the query or command to find open work
+- **What it surfaces** — overdue items, due today, flagged/urgent, blocked
+- **Format** — how to present results (counts, lists, grouped)
+
+## Example Work Scans
+
+Uncomment and adapt these for your project:
+
+<!--
+### Task Backlog
+```bash
+sqlite3 project.db "SELECT id, text, status, due_date FROM tasks WHERE status != 'done' ORDER BY due_date"
+```
+All open tasks. Group by: overdue, due today, due this week, no date.
+
+### Inbox / Queue
+```bash
+sqlite3 project.db "SELECT COUNT(*) FROM inbox WHERE processed = 0"
+```
+Unprocessed items that arrived since last session. Report count; details
+come during processing.
+
+### Issue Tracker
+```bash
+gh issue list --state open --assignee @me --json number,title,labels
+```
+Open issues assigned to the user. Flag any marked urgent or blocking.
+
+### Markdown Task Lists
+```bash
+grep -r '- \[ \]' docs/todo.md
+```
+If work is tracked in markdown files, scan for unchecked items.
+-->