anvil-dev-framework 0.1.6

package/docs/command-reference.md

@@ -0,0 +1,2022 @@
+# Anvil Command Reference
+
+> Complete documentation for the Anvil CLI and all slash commands.
+
+---
+
+## Quick Reference
+
+| Command | One-liner |
+|---------|-----------|
+| `anvil init` | Initialize a new project with Anvil framework |
+| `anvil-issue` | Manage local issues without Linear integration |
+| `/orient` | Start-of-session orientation and context recovery |
+| `/ready` | List unblocked work sorted by priority |
+| `/sprint` | Quick session planning with focus suggestions |
+| `/handoff` | Generate session continuity doc for next session |
+| `/explore` | Discovery phase before new feature work |
+| `/spec` | Generate formal feature specification |
+| `/plan` | Create implementation plan from approved spec |
+| `/tasks` | Create Linear sub-issues from approved plan |
+| `/change` | Brownfield change proposal for existing features |
+| `/discover` | File discovered work (bugs, debt) during implementation |
+| `/validate` | Environment validation before code changes |
+| `/evidence` | Capture quality gate proof before PR |
+| `/linear-setup` | Configure Linear integration for project |
+| `/anvil-sync` | Sync framework updates to project |
+| `/anvil-settings` | Manage framework settings |
+| `/release` | Consolidate [Unreleased] into versioned release |
+| `/healthcheck` | Framework diagnostics and session health |
+| `/retro` | Write retrospective to capture learnings |
+| `/shard` | Break large specs into atomic pieces |
+| `/decay-review` | Archive old issues and clean handoffs |
+| `/weekly-review` | Weekly analytics and improvement recommendations |
+| `/insights` | Synthesize patterns from retros and healthchecks |
+| `/hud` | Launch multi-agent monitoring dashboard |
+| `/ralph` | Ralph Wiggum autonomous execution mode (power tool) |
+
+---
+
+## Table of Contents
+
+- [Anvil CLI](#anvil-cli)
+  - [Installation](#installation)
+  - [Usage](#usage)
+  - [Options](#options)
+  - [Hook Options Explained](#hook-options-explained)
+  - [Examples](#examples)
+  - [What Gets Created](#what-gets-created)
+- [Local Issue CLI](#local-issue-cli)
+  - [Overview](#overview)
+  - [Commands](#commands)
+  - [Status Workflow](#status-workflow)
+  - [Priority Levels](#priority-levels)
+- [Slash Commands Overview](#slash-commands-overview)
+- [Session Commands](#session-commands)
+  - [/orient](#orient)
+  - [/ready](#ready)
+  - [/sprint](#sprint)
+  - [/handoff](#handoff)
+- [Workflow Commands](#workflow-commands)
+  - [/explore](#explore)
+  - [/spec](#spec)
+  - [/plan](#plan)
+  - [/tasks](#tasks)
+  - [/change](#change)
+  - [/discover](#discover)
+- [Quality Commands](#quality-commands)
+  - [/validate](#validate)
+  - [/evidence](#evidence)
+  - [/healthcheck](#healthcheck)
+  - [/retro](#retro)
+- [Multi-Agent Commands](#multi-agent-commands)
+  - [/hud](#hud)
+- [Maintenance Commands](#maintenance-commands)
+  - [/release](#release)
+  - [/shard](#shard)
+  - [/decay-review](#decay-review)
+  - [/weekly-review](#weekly-review)
+  - [/insights](#insights)
+- [Power Mode Commands](#power-mode-commands)
+  - [/ralph](#ralph)
+- [Setup Commands](#setup-commands)
+  - [/linear-setup](#linear-setup)
+  - [/anvil-sync](#anvil-sync)
+  - [/anvil-settings](#anvil-settings)
+- [Command Cheat Sheet](#command-cheat-sheet)
+- [Command Dependencies](#command-dependencies)
+
+---
+
+## Anvil CLI
+
+The `anvil` command-line tool initializes new projects with the Anvil Framework.
+
+### Installation
+
+**Option 1: Bun (Recommended)**
+```bash
+bun install -g anvil-dev-framework
+```
+
+**Option 2: npm**
+```bash
+npm install -g anvil-dev-framework
+```
+
+**Option 3: Homebrew (macOS)**
+```bash
+brew tap alexandercahiz/anvil
+brew install anvil
+```
+
+**Option 4: From Source**
+```bash
+git clone https://github.com/alexandercahiz/anvil-dev-framework.git
+cd anvil-dev-framework
+./scripts/install.sh  # Auto-configures PATH
+```
+
+### Usage
+
+```bash
+anvil init [options]
+anvil --help
+anvil --version
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `--template <type>` | Project template: `saas`, `api-python`, `generic` (default: generic) |
+| `--no-tts` | Disable TTS voice announcements (keeps safety hooks) |
+| `--no-memory` | Disable claude-mem context loading (keeps safety hooks) |
+| `--no-hooks` | Skip ALL hooks including safety (use with caution) |
+| `--with-linear` | Include Linear integration setup |
+| `--force` | Overwrite existing configuration (backs up first) |
+| `--dry-run` | Preview changes without modifying filesystem |
+
+### Hook Options Explained
+
+By default, Anvil installs all hooks including:
+- **Safety hooks**: Block dangerous `rm -rf` commands, prevent `.env` file access
+- **TTS announcements**: Voice feedback for session events
+- **Memory integration**: Load context from claude-mem at session start
+
+Use `--no-tts` or `--no-memory` to disable specific features while keeping safety protections:
+
+```bash
+# Full setup (default)
+anvil init
+
+# No voice announcements, but safety hooks active
+anvil init --no-tts
+
+# No memory loading, but safety hooks and TTS active
+anvil init --no-memory
+
+# Safety hooks only (no TTS, no memory)
+anvil init --no-tts --no-memory
+
+# Minimal setup - NO SAFETY PROTECTIONS (shows warning)
+anvil init --no-hooks
+```
+
+### Examples
+
+```bash
+# Initialize with all features
+anvil init
+
+# Preview what would be created
+anvil init --dry-run
+
+# SaaS project (Next.js + Supabase + Vercel) with Linear
+anvil init --template saas --with-linear
+
+# Python API project (FastAPI + PostgreSQL)
+anvil init --template api-python
+
+# Silent mode (no voice) with safety hooks
+anvil init --no-tts
+
+# Reinitialize existing project (backs up existing files)
+anvil init --force
+```
+
+### What Gets Created
+
+```
+.claude/
+├── CLAUDE.md              # Project configuration (from template)
+├── constitution.md        # Non-negotiable principles
+├── product.md             # Product definition
+├── settings.local.json    # Hook configurations
+├── commands/              # Symlinks to slash commands
+├── hooks/                 # Symlinks to hook scripts
+│   └── utils/tts/         # TTS provider scripts
+├── specs/                 # Specification documents
+│   ├── current/
+│   └── archive/
+├── handoffs/              # Session continuity documents
+├── retros/                # Retrospective documents
+├── docs/                  # Project documentation
+├── examples/              # Code convention examples
+├── agents/                # Agent configurations
+└── changes/               # Change proposals
+```
+
+---
+
+## Local Issue CLI
+
+The `anvil-issue` command-line tool provides file-based issue tracking for projects without Linear integration. All Anvil workflow commands (`/orient`, `/ready`, `/sprint`, `/tasks`) work seamlessly with local issues.
+
+### Overview
+
+**When to Use**: Projects without Linear integration, offline development, personal projects, or when you prefer local issue storage.
+
+**Storage**: Issues are stored in `~/.anvil/issues/index.json`
+
+**Provider Detection**: Anvil automatically uses local issues when no `.claude/linear.yaml` exists.
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `list` | List issues (optionally filtered by status) |
+| `create` | Create a new issue |
+| `show` | Show issue details |
+| `update` | Update an existing issue |
+| `move` | Change issue status |
+| `assign` | Assign issue to an agent |
+| `stats` | Show issue statistics |
+| `ready` | Show issues ready to work on |
+| `delete` | Delete an issue |
+
+#### list
+
+List issues with optional filtering.
+
+```bash
+anvil-issue list [OPTIONS]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--status`, `-s` | Filter by status (backlog, todo, in-progress, in-review, done, cancelled) |
+| `--limit`, `-n` | Maximum issues to show (default: 50) |
+
+**Examples:**
+```bash
+anvil-issue list
+anvil-issue list --status todo
+anvil-issue list --status in-progress --limit 10
+```
+
+#### create
+
+Create a new issue.
+
+```bash
+anvil-issue create --title "TITLE" [OPTIONS]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--title`, `-t` | Issue title (required) |
+| `--description`, `-d` | Issue description |
+| `--priority`, `-p` | Priority: urgent/p0, high/p1, medium/p2, low/p3, none/p4 |
+| `--labels`, `-l` | Comma-separated labels |
+| `--parent` | Parent issue identifier (creates sub-issue) |
+
+**Examples:**
+```bash
+anvil-issue create --title "Add dark mode"
+anvil-issue create --title "Critical bug" --priority urgent --labels "bug,critical"
+anvil-issue create --title "Phase 1: Setup" --parent LOCAL-001
+```
+
+#### show
+
+Show detailed issue information.
+
+```bash
+anvil-issue show IDENTIFIER
+```
+
+**Example:**
+```bash
+anvil-issue show LOCAL-001
+```
+
+#### update
+
+Update an existing issue.
+
+```bash
+anvil-issue update IDENTIFIER [OPTIONS]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--title`, `-t` | New title |
+| `--description`, `-d` | New description |
+| `--priority`, `-p` | New priority |
+| `--labels`, `-l` | New labels (comma-separated) |
+
+**Example:**
+```bash
+anvil-issue update LOCAL-001 --title "Updated title" --priority high
+```
+
+#### move
+
+Change issue status.
+
+```bash
+anvil-issue move IDENTIFIER --to STATUS
+```
+
+**Examples:**
+```bash
+anvil-issue move LOCAL-001 --to in-progress
+anvil-issue move LOCAL-001 --to done
+```
+
+#### assign
+
+Assign or unassign an agent.
+
+```bash
+anvil-issue assign IDENTIFIER [OPTIONS]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--agent`, `-a` | Agent ID to assign |
+| `--unassign`, `-u` | Remove assignment |
+
+**Examples:**
+```bash
+anvil-issue assign LOCAL-001 --agent swift-falcon-a3f2
+anvil-issue assign LOCAL-001 --unassign
+```
+
+#### stats
+
+Show issue statistics.
+
+```bash
+anvil-issue stats
+```
+
+**Output:**
+```
+=== Issue Statistics ===
+
+Total Issues: 15
+Assigned:     3
+Unassigned:   12
+
+--- By Status ---
+  Backlog         5
+  Todo            4
+  In Progress     2
+  In Review       1
+  Done            3
+
+--- By Priority ---
+  P0              1
+  P1              3
+  P2              8
+  P3              3
+```
+
+#### ready
+
+Show issues ready to work on, sorted by priority.
+
+```bash
+anvil-issue ready [OPTIONS]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--limit`, `-n` | Maximum issues (default: 10) |
+
+#### delete
+
+Delete an issue.
+
+```bash
+anvil-issue delete IDENTIFIER [OPTIONS]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--hard` | Permanently delete (default: soft delete/cancel) |
+
+**Examples:**
+```bash
+anvil-issue delete LOCAL-001           # Marks as cancelled
+anvil-issue delete LOCAL-001 --hard    # Permanently removes
+```
+
+### Status Workflow
+
+```
+┌─────────┐
+│ Backlog │  Not yet prioritized
+└────┬────┘
+     │
+┌────▼────┐
+│  Todo   │  Ready to start
+└────┬────┘
+     │
+┌────▼─────────┐
+│ In Progress  │  Being worked on
+└────┬─────────┘
+     │
+┌────▼────────┐
+│  In Review  │  PR awaiting review
+└────┬────────┘
+     │
+┌────▼────┐
+│  Done   │  Completed
+└─────────┘
+```
+
+### Priority Levels
+
+| Priority | Code | Description |
+|----------|------|-------------|
+| Urgent | P0 | Drop everything, fix now |
+| High | P1 | Next up after current task |
+| Medium | P2 | This sprint (default) |
+| Low | P3 | Backlog |
+| None | P4 | No priority set |
+
+The `ready` command sorts by priority (P0 first) then by age (oldest first).
+
+**See Also**: [Local Issue Tracking Guide](local-issues.md) for comprehensive documentation including Python API and migration guides.
+
+---
+
+## Slash Commands Overview
+
+Anvil provides 23 slash commands organized into six categories:
+
+| Category | Commands | Purpose |
+|----------|----------|---------|
+| **Session** | `/orient`, `/ready`, `/sprint`, `/handoff` | Session lifecycle management |
+| **Workflow** | `/explore`, `/spec`, `/plan`, `/tasks`, `/change`, `/discover` | Phase-gated development |
+| **Quality** | `/validate`, `/evidence`, `/healthcheck`, `/retro` | Quality assurance |
+| **Multi-Agent** | `/hud` | Multi-agent coordination |
+| **Maintenance** | `/release`, `/shard`, `/decay-review`, `/weekly-review`, `/insights` | System maintenance |
+| **Setup** | `/linear-setup`, `/anvil-sync`, `/anvil-settings` | Project configuration |
+
+---
+
+## Session Commands
+
+### /orient
+
+**Purpose**: Session startup orientation and context recovery.
+
+**When to Use**: Start of every session.
+
+**Fast-Path Execution** (Recommended):
+```bash
+python3 global/lib/orient_fast.py          # Full (~700ms)
+python3 global/lib/orient_fast.py --fast   # Skip Linear (~200ms)
+python3 global/lib/orient_fast.py --json   # JSON output
+```
+
+The fast-path script runs all checks in parallel (10-20x faster than manual steps).
+
+**What It Does**:
+1. Checks for recent handoff document (< 48 hours)
+2. Reads git state (branch, uncommitted changes, recent commits)
+3. Queries Linear for in-progress issues (cached for 60s)
+4. Calculates ready work (no blockers)
+5. Presents options and waits for direction
+
+**Output Format**:
+
+```markdown
+## Session Orientation
+
+### Resuming From
+[Last handoff: 2025-12-16 or Fresh start]
+
+### Current Branch
+`feature/xyz` — 3 commits ahead of main
+
+### In-Progress Work
+| Issue | Title | Progress |
+|-------|-------|----------|
+| ENG-42 | Fix auth flow | 60% complete |
+
+### Ready Work Available
+| Priority | Issue | Title | Age |
+|----------|-------|-------|-----|
+| P0 | ENG-38 | Critical bug | 3 days |
+| P1 | ENG-45 | New feature | 5 days |
+
+### Recommended Action
+Continue ENG-42 (in progress) or switch to ENG-38 (higher priority)?
+
+Awaiting direction.
+```
+
+**Success Criteria**: Agent understands current state and awaits human direction before proceeding.
+
+---
+
+### /ready
+
+**Purpose**: Calculate ready (unblocked) work from Linear.
+
+**When to Use**: Before selecting a task, when unsure what to work on.
+
+**Relationship to /sprint**: `/ready` is the **foundation** — a pure data query for unblocked work. `/sprint` **builds on** `/ready` by adding broader context (In Progress, In Review, Blocked items) and Top 3 recommendations. Use `/ready` when you just want to see what's available; use `/sprint` when you need help prioritizing.
+
+**What It Does**:
+1. Fetches issues from Linear (filtered by team from `linear.yaml`)
+2. Filters issues where ALL blockers are Done (or no blockers)
+3. Checks for agent conflicts via `.claude/coordination.md`
+4. Sorts by priority (P0 first), then age (oldest first)
+5. Presents ready work list with conflict warnings
+
+**Algorithm**:
+
+```
+For each issue in (Todo, Backlog):
+  If issue has no "blocked by" relationships:
+    Add to ready set
+  Else:
+    For each blocker:
+      If blocker.status != Done:
+        Mark issue as blocked
+        Break
+    If not blocked:
+      Add to ready set
+
+Check coordination.md for active agents:
+  For each ready issue:
+    If issue key matches active agent work:
+      Mark with conflict warning
+
+Sort ready set by:
+  1. Priority (P0 > P1 > P2 > P3 > None)
+  2. Created date (oldest first)
+
+Return ready items with status
+```
+
+**Output Format**:
+
+```markdown
+## Ready Work — [team_key]
+
+| Priority | Issue | Title | Age | Status |
+|----------|-------|-------|-----|--------|
+| P0 | ENG-38 | Critical auth bug | 3d | Available |
+| P1 | ENG-42 | Password reset | 5d | ⚠️ swift-falcon-a3f2 active |
+| P2 | ENG-51 | Profile page | 2d | Available |
+
+**Total ready**: 3 issues
+**Blocked**: 2 issues waiting on dependencies
+**Conflicts**: 1 issue has active agent
+
+Recommend starting with: ENG-38 (Critical auth bug)
+```
+
+---
+
+### /sprint
+
+**Purpose**: Quick session planning and prioritization.
+
+**When to Use**: After `/orient` when multiple work options exist.
+
+**Relationship to /ready**: `/sprint` internally uses `/ready`'s unblocked work logic, then adds broader context by also querying In Progress, In Review, and Blocked items. It provides Top 3 recommendations with reasoning.
+
+**What It Does**:
+1. Applies `/ready`'s logic to get unblocked Todo/Backlog items with agent conflicts
+2. Also queries In Progress, In Review, and Blocked issues
+3. Builds state summary table
+4. Identifies priorities using heuristics
+5. Suggests top 3 focus items (preferring available over conflicting)
+6. Highlights blockers needing human action
+
+**Priority Heuristics** (in order):
+1. Blocked items you can unblock (high value)
+2. In-review items with feedback (quick wins)
+3. In-progress items (momentum)
+4. High priority ready items (P0/P1) — **available** over conflicting
+
+**Output Format**:
+
+```markdown
+## Sprint State — [team_key]
+
+| Status | Count | Attention Needed |
+|--------|-------|------------------|
+| Blocked | 2 | Waiting on external API decision |
+| In Progress | 1 | ENG-42 (60% complete) |
+| In Review | 1 | ENG-38 has feedback |
+| Ready | 5 | 2 P1, 3 P2 items (1 has active agent) |
+
+## Suggested Focus
+
+1. **ENG-38**: Address review feedback
+   - Why: Quick to complete, unblocks merge
+   - Effort: ~30 min
+
+2. **ENG-42**: Continue password reset
+   - Why: Already in progress, has momentum
+   - Effort: ~2 hours remaining
+
+3. **ENG-51**: Start profile page
+   - Why: P2, available (no agent conflicts)
+   - Effort: ~3 hours
+
+## Agent Conflicts
+⚠️ ENG-45 has swift-falcon-a3f2 active — skipped in recommendations
+
+## Blockers Requiring Attention
+- ENG-50 blocked by external API team decision
+
+Which would you like to work on?
+```
+
+---
+
+### /handoff
+
+**Purpose**: Generate session continuity document for next session.
+
+**When to Use**: End of every session, before context compaction, when switching tasks.
+
+**What It Does**:
+1. Summarizes work completed this session
+2. Documents in-progress state
+3. Lists discovered work filed
+4. Records critical context
+5. Captures environment state
+6. Recommends next task
+
+**Output Location**: `.claude/handoffs/[YYYY-MM-DD]-[topic].md`
+
+**Output Format**:
+
+```markdown
+---
+session_date: 2025-12-17
+session_time: 09:00 - 12:30
+branch: feature/password-reset
+---
+
+# Session Handoff: December 17, 2025
+
+## Session Summary
+Implemented password reset email flow and discovered rate limiting gap.
+
+## Completed This Session
+| Issue | Title | Outcome |
+|-------|-------|---------|
+| ENG-42 | Email templates | Merged PR #123 |
+
+## In Progress
+| Issue | Title | Current State | Next Step |
+|-------|-------|---------------|-----------|
+| ENG-38 | Reset flow | 60% - Email done | Implement reset endpoint |
+
+## Discovered Work Filed
+| Issue | Title | Discovered From | Priority |
+|-------|-------|-----------------|----------|
+| ENG-52 | Rate limiting | ENG-38 | P1 |
+
+## Recommended Next Task
+**ENG-38** — Continue password reset (momentum, 60% complete)
+
+## Critical Context for Next Session
+- Password reset uses new email service (`src/services/email.ts`)
+- Rate limiting discovery (ENG-52) should be addressed before launch
+- Test user: `reset-test@example.com` in staging
+
+## Environment State
+- Branch: `feature/password-reset`
+- PR: #125 (draft)
+- Tests: 14/16 passing (2 skipped pending mock)
+
+## Files Modified This Session
+- src/services/email.ts (new)
+- src/components/ResetForm.tsx (modified)
+- src/app/api/auth/reset/route.ts (new)
+```
+
+---
+
+## Workflow Commands
+
+### /explore
+
+**Purpose**: Discovery phase before any new feature work.
+
+**When to Use**: Before starting any new feature or significant change.
+
+**What It Does**:
+1. Clarifies the request with the user
+2. Searches for existing related code
+3. Reads related files, noting patterns
+4. Checks existing specs for overlap
+5. Reviews architecture constraints
+6. Generates exploration report
+
+**Gate**: Wait for user confirmation before proceeding to /spec
+
+**Output Format**:
+
+```markdown
+## Exploration Report: [Feature Name]
+
+### Understanding
+[1-2 sentences summarizing the request]
+
+### Existing Related Code
+| File | Relevance | Notes |
+|------|-----------|-------|
+| src/auth/login.ts | High | Similar auth pattern |
+| src/services/user.ts | Medium | User data access |
+
+### Observed Patterns
+- Authentication: JWT with refresh tokens
+- API routes: Next.js App Router style
+- Error handling: Custom AppError class
+
+### Existing Specs
+- None overlapping (or list overlaps)
+
+### Architecture Constraints
+- Must use existing Supabase client
+- Should follow existing error patterns
+
+### Questions Before Proceeding
+1. [Any clarifying questions]
+
+### Recommendation
+[Proceed to spec / Need more info / Blocked by X]
+
+Awaiting approval to proceed with /spec.
+```
+
+---
+
+### /spec
+
+**Purpose**: Generate formal feature specification.
+
+**When to Use**: After exploration phase is approved.
+
+**What It Does**:
+1. Creates structured specification document
+2. Defines functional and non-functional requirements
+3. Writes Gherkin-style acceptance scenarios
+4. Documents technical considerations
+5. Explicitly lists out-of-scope items
+6. Captures open questions
+
+**Output Location**: `.claude/specs/current/SPEC-[YYYYMMDD]-[XXX]-[slug].md`
+
+**Gate**: All open questions must be answered, status must be 'approved' before /plan
+
+**Output Format**:
+
+```markdown
+---
+spec_id: SPEC-20251217-001
+title: Password Reset Flow
+status: draft
+created: 2025-12-17
+author: Claude
+---
+
+# Password Reset Flow
+
+## Overview
+Allow users to reset their password via email verification.
+
+## Requirements
+
+### Functional Requirements
+1. **FR-1**: User can request password reset by email
+2. **FR-2**: System sends reset link valid for 1 hour
+3. **FR-3**: User can set new password via reset link
+4. **FR-4**: System invalidates all existing sessions on reset
+
+### Non-Functional Requirements
+1. **NFR-1**: Reset link must be cryptographically secure
+2. **NFR-2**: Rate limit: max 3 requests per email per hour
+3. **NFR-3**: Email delivery within 30 seconds
+
+## User Scenarios
+
+### Scenario: Successful password reset
+
+**Context**:
+- **GIVEN** a registered user with email "user@example.com"
+- **AND** the user has forgotten their password
+
+**Action**:
+- **WHEN** the user requests a password reset
+- **AND** clicks the link in the email
+- **AND** enters a new valid password
+
+**Outcome**:
+- **THEN** the password is updated
+- **AND** all existing sessions are invalidated
+- **AND** user is redirected to login
+
+### Scenario: Expired reset link
+
+**Context**:
+- **GIVEN** a reset link older than 1 hour
+
+**Action**:
+- **WHEN** the user clicks the expired link
+
+**Outcome**:
+- **THEN** the system shows "Link expired" message
+- **AND** offers to request a new reset link
+
+## Technical Considerations
+- Use existing Supabase auth for token generation
+- Store reset tokens in `password_reset_requests` table
+- Use existing email service for delivery
+
+## Out of Scope
+- Password strength requirements (existing)
+- Two-factor authentication (separate feature)
+- Account lockout (separate feature)
+
+## Open Questions
+1. ~~What is the reset link expiry time?~~ → 1 hour (decided)
+2. Should we notify on successful reset? → **NEEDS ANSWER**
+
+## Dependencies
+- Email service must be operational
+- Supabase connection required
+```
+
+---
+
+### /plan
+
+**Purpose**: Create implementation plan from approved specification.
+
+**When to Use**: After spec is approved (status = approved, no open questions).
+
+**Prerequisites**:
+- **Exploration completed** (`/explore`) — soft gate warns if skipped
+- Specification approved (`/spec`)
+- No blocking open questions
+
+**Explore Gate**:
+
+Before creating a plan, `/plan` checks for evidence of exploration:
+
+```
+⚠️ **Exploration Check**
+
+No recent `/explore` found for this feature.
+
+Before planning, run `/explore [feature name]` to:
+- Search for existing code that might solve this
+- Find patterns to follow
+- Discover infrastructure to reuse
+
+**Why this matters**: In 5/7 recent retros, we found existing infrastructure
+that would have saved implementation time.
+
+Continue anyway? Or run `/explore` first?
+```
+
+**What It Does**:
+1. Verifies exploration was done (soft gate)
+2. Breaks spec into implementation phases
+3. Lists specific file changes per phase
+4. Defines testing strategy
+5. Identifies risks and mitigations
+6. Documents rollback plan
+
+**Output Location**: `.claude/specs/current/PLAN-[YYYYMMDD]-[XXX]-[slug].md`
+
+**Gate**: Plan must be approved before /tasks
+
+**Output Format**:
+
+```markdown
+---
+plan_id: PLAN-20251217-001
+spec_id: SPEC-20251217-001
+title: Password Reset Implementation
+estimated_hours: 6
+---
+
+# Implementation Plan: Password Reset
+
+## Approach
+Implement as vertical slice: database → API → UI in single branch.
+
+## Phase 1: Database Setup (1h)
+### Files to Create
+- `supabase/migrations/[timestamp]_password_reset.sql`
+
+### Changes
+- Create `password_reset_requests` table
+- Add RLS policies for reset tokens
+- Create cleanup function for expired tokens
+
+### Verification
+- Migration applies cleanly
+- RLS policies tested
+
+## Phase 2: API Endpoints (2h)
+### Files to Create
+- `src/app/api/auth/reset/request/route.ts`
+- `src/app/api/auth/reset/confirm/route.ts`
+
+### Files to Modify
+- `src/services/authService.ts` (add reset methods)
+
+### Verification
+- Unit tests for service methods
+- API route tests with mocks
+
+## Phase 3: UI Components (2h)
+### Files to Create
+- `src/components/auth/ResetRequestForm.tsx`
+- `src/components/auth/ResetConfirmForm.tsx`
+- `src/app/reset-password/page.tsx`
+
+### Verification
+- Component renders correctly
+- Form validation works
+- Error states display
+
+## Phase 4: Integration & Polish (1h)
+### Tasks
+- Email template styling
+- Error message refinement
+- E2E test for full flow
+
+### Verification
+- Full flow works in staging
+- E2E test passes
+
+## Testing Strategy
+| Type | Coverage | Files |
+|------|----------|-------|
+| Unit | Service methods | authService.test.ts |
+| Integration | API routes | reset.test.ts |
+| E2E | Full flow | reset.e2e.ts |
+
+## Risks and Mitigations
+| Risk | Likelihood | Mitigation |
+|------|------------|------------|
+| Email delivery delay | Medium | Retry logic, user feedback |
+| Token collision | Low | Use UUID v4 |
+
+## Rollback Plan
+1. Revert migration: `supabase migration repair --status reverted [timestamp]`
+2. Remove API routes
+3. Remove UI components
+4. Remove service methods
+```
+
+---
+
+### /tasks
+
+**Purpose**: Create Linear sub-issues from approved implementation plan, nested under parent feature issue.
+
+**When to Use**: After plan is approved.
+
+**What It Does**:
+1. Identifies parent issue from spec's `linear_issue:` field
+2. Creates sub-issues for each implementation phase using `--parent` flag
+3. Sets dependencies (blocked by relationships)
+4. Adds acceptance criteria from spec
+5. Assigns estimates
+6. Adds appropriate labels
+
+**Rules**:
+- **Always create as sub-issues** under the parent feature issue
+- Each task completable in 1-4 hours
+- Each task has clear acceptance criteria
+- Each task independently verifiable
+- Dependencies explicitly set
+- Title convention: `[PARENT-ID] Phase N: [Description]`
+
+**CLI Reference**:
+
+| Command | Option | Description |
+|---------|--------|-------------|
+| `create-issue` | `--team` | Team UUID (required) |
+| | `--title` | Issue title (required) |
+| | `--description` | Description text |
+| | `--parent` | Parent UUID (for sub-issues) |
+| `update-issue` | `--id` | Issue ID e.g. "ANV-12" |
+| | `--state` | State UUID (not name!) |
+| | `--parent` | Parent UUID |
+| `list-issues` | `--team` | Team UUID (required) |
+| | `--status` | Filter by state name e.g. "In Progress" |
+| | `--state` | Filter by state UUID |
+| | `--full` | Include full details (labels, comments) |
+
+> **Common Mistakes**:
+> - Use `list-issues` NOT `list_issues` (hyphens, not underscores)
+> - Use `--team` NOT `--team-id`
+> - Use `--status` to filter by state name, `--state` for state UUID
+
+**CLI Examples**:
+```bash
+# Create new sub-issue
+python3 scripts/linear.py create-issue \
+  --team "TEAM_UUID" \
+  --title "[ANV-5] Phase 1: Core Implementation" \
+  --parent "parent-issue-uuid"
+
+# Convert existing issue to sub-issue
+python3 scripts/linear.py update-issue \
+  --id "ANV-12" \
+  --parent "parent-issue-uuid"
+
+# List issues for a team (filter by status name)
+python3 scripts/linear.py list-issues --team "TEAM_UUID" --status "In Progress"
+```
+
+**Output**: Linear sub-issues created with links provided, nested under parent
+
+---
+
+### /change
+
+**Purpose**: Create brownfield change proposal for modifying existing features.
+
+**When to Use**: When modifying existing functionality that has a spec.
+
+**What It Does**:
+1. Identifies affected existing specs
+2. Documents proposed changes with delta markers
+3. Assesses impact on existing functionality
+4. Creates migration plan if needed
+
+**Output Location**: `.claude/changes/CHANGE-[YYYYMMDD]-[XXX]/`
+
+**Output Format**:
+
+```markdown
+---
+change_id: CHANGE-20251217-001
+affects_specs: [SPEC-20251201-001]
+title: Add 2FA to Login
+---
+
+# Change Proposal: Add 2FA to Login
+
+## Summary
+Add optional two-factor authentication to existing login flow.
+
+## Motivation
+Security requirement for enterprise users.
+
+## Proposed Changes
+
+### MODIFIED: Login Flow (SPEC-20251201-001)
+**Previously**: Single-factor password authentication
+**Now**: Password + optional TOTP verification
+
+### ADDED: 2FA Setup
+New requirement for users to enable/disable 2FA.
+
+### ADDED: Backup Codes
+Allow recovery if user loses 2FA device.
+
+## Impact Analysis
+- Existing users: No change unless they enable 2FA
+- Login API: Backward compatible (2FA optional)
+- Database: New table for TOTP secrets
+
+## Migration Required
+- [ ] Add `user_2fa_settings` table
+- [ ] Backfill existing users with 2FA disabled
+
+## Rollback Plan
+Feature flag allows disabling 2FA without code changes.
+```
+
+---
+
+### /discover
+
+**Purpose**: File discovered work during implementation.
+
+**When to Use**: When you find bugs, missing features, or technical debt while working on something else.
+
+**What It Does**:
+1. Creates Linear issue immediately
+2. Links to parent issue (discovered-from)
+3. Adds discovery context
+4. Sets appropriate priority
+5. Adds `discovered` label
+
+**Usage**: `/discover [title]`
+
+**Output**: Linear issue created with link
+
+---
+
+## Quality Commands
+
+### /validate
+
+**Purpose**: Environment validation checkpoint before any code changes.
+
+**When to Use**: Before making any changes to the codebase.
+
+**What It Does**:
+1. Checks git status (must be clean)
+2. Checks branch (must not be main)
+3. Runs `npm ci` (dependencies)
+4. Runs `npm test` (baseline)
+5. Runs `npm run typecheck` (types)
+
+**Critical Behavior**: If ANY step fails → STOP and report. Do NOT proceed.
+
+**Output Format**:
+
+```markdown
+## Environment Validation
+
+| Check | Status | Details |
+|-------|--------|---------|
+| Git Status | ✅ PASS | Working tree clean |
+| Branch | ✅ PASS | On `feature/reset` (not main) |
+| Dependencies | ✅ PASS | npm ci completed |
+| Tests | ✅ PASS | 142/142 passing |
+| Types | ✅ PASS | No errors |
+
+**Result**: Environment validated. Safe to proceed with changes.
+```
+
+Or if failed:
+
+```markdown
+## Environment Validation
+
+| Check | Status | Details |
+|-------|--------|---------|
+| Git Status | ❌ FAIL | 3 uncommitted files |
+| Branch | — | Skipped |
+| Dependencies | — | Skipped |
+| Tests | — | Skipped |
+| Types | — | Skipped |
+
+**Result**: BLOCKED. Cannot proceed until git status is clean.
+
+**Action Required**: Commit or stash uncommitted changes.
+```
+
+---
+
+### /evidence
+
+**Purpose**: Capture quality gate proof before creating PR.
+
+**When to Use**: After implementation complete, before creating or updating PR.
+
+**What It Does**:
+1. Runs lint, captures full output
+2. Runs typecheck, captures full output
+3. Runs tests, captures full output
+4. Runs git status, lists changed files
+5. Checks documentation status (soft prompt)
+6. Checks changelog entry (soft prompt)
+7. Runs code review if configured (optional)
+8. Formats evidence block for PR
+
+**Quality Gate Types**:
+
+| Gate | Type | Description |
+|------|------|-------------|
+| Lint | ✅ Required | Must pass with 0 errors |
+| TypeScript | ✅ Required | Must pass with 0 errors |
+| Tests | ✅ Required | All tests must pass |
+| Git Status | ✅ Required | Only expected files changed |
+| Documentation | ⚪ Soft | Prompts if docs may need updating |
+| Changelog | ⚪ Soft | Warns if no [Unreleased] entry |
+| Code Review | ⚪ Optional | Runs if enabled in config |
+
+**Configuration** (`.claude/anvil.config.json`):
+
+```json
+{
+  "codeReview": {
+    "enabled": true,
+    "tool": "coderabbit",
+    "command": "coderabbit --prompt-only",
+    "enforcement": "soft"
+  }
+}
+```
+
+Code review enforcement levels:
+- **hard**: Run automatically, block PR if critical issues
+- **soft**: Prompt "Run code review? (recommended)"
+- **manual**: Skip automatic prompt, user triggers when wanted
+
+**Output Format**:
+
+```markdown
+## Quality Gate Evidence
+
+### Lint Check
+```
+$ npm run lint
+✔ No problems found
+```
+
+### Type Check
+```
+$ npm run typecheck
+✔ No errors
+```
+
+### Test Results
+```
+$ npm test
+Test Suites: 3 passed, 3 total
+Tests:       12 passed, 12 total
+```
+
+### Changed Files
+```
+$ git status
+Changes to be committed:
+  new file:   src/services/email.ts
+  modified:   src/services/authService.ts
+```
+
+### Documentation Status
+- [x] Docs updated: docs/api-reference.md
+- [ ] No docs needed
+- [ ] Docs TODO
+
+### Changelog Status
+✅ Entry added to [Unreleased] section
+
+### Code Review
+**Tool**: CodeRabbit
+**Status**: ✅ No critical issues
+
+**Result**: All gates passed. Ready for PR.
+```
+
+---
+
+### /healthcheck
+
+**Purpose**: Framework diagnostics and session health analysis.
+
+**When to Use**: After sessions with issues, periodically for maintenance, debugging framework problems.
+
+**What It Does**:
+1. Reads current session logs (`logs/*.json`)
+2. Analyzes session transcript for patterns
+3. Identifies blocked commands, tool errors, hook failures
+4. Calculates metrics (success rate, tool invocations)
+5. Generates actionable recommendations
+6. Saves report to `.claude/healthchecks/YYYY-MM/`
+
+**Metrics Tracked**:
+| Metric | Description |
+|--------|-------------|
+| Tool Invocations | Total tool calls in session |
+| Success Rate | Percentage of successful tool calls |
+| Blocked Commands | Commands blocked by safety hooks |
+| Tool Errors | Tools that returned errors |
+| Hook Failures | Hooks that failed to execute |
+
+**Status Thresholds**:
+| Status | Criteria |
+|--------|----------|
+| ✅ Healthy | Success rate > 95% |
+| ⚠️ Warning | Success rate 80-95% |
+| ❌ Problem | Success rate < 80% |
+
+**Output Format**:
+
+```markdown
+# Healthcheck: 2025-12-26 14:46
+
+**Session ID**: abc123...
+**Duration**: ~1 hour
+**Status**: ✅ Healthy
+
+## Metrics
+| Metric | Value | Status |
+|--------|-------|--------|
+| Tool Invocations | 17 | — |
+| Success Rate | 100% | ✅ |
+| Blocked Commands | 0 | ✅ |
+
+## Recommendations
+Framework operating normally. No action required.
+```
+
+**Integration**: Use `/discover` to file any issues found during healthcheck.
+
+---
+
+### /retro
+
+**Purpose**: Write a retrospective to capture learnings.
+
+**When to Use**: After completing significant work, after debugging >1 hour, after unexpected complexity.
+
+**What It Does**:
+1. Identifies topic (usually issue key + title)
+2. Assesses outcome (success/partial/failed)
+3. Writes narrative of what happened
+4. Extracts one key learning
+5. Defines one "next time" action
+6. Saves to `.claude/retros/YYYY-MM/[slug].md`
+
+**Output Format**:
+
+```markdown
+# ENG-42: Password Reset Token Generation
+
+**Outcome:** success
+**Date:** 2025-12-17
+
+## What Happened
+Started by copying the email verification pattern but discovered
+password reset needs single-use tokens with faster expiry...
+
+## Key Learning
+Don't assume similar features can share infrastructure.
+
+## For Next Time
+Make a requirements checklist BEFORE copying patterns.
+```
+
+---
+
+## Multi-Agent Commands
+
+### /hud
+
+**Purpose**: Launch the multi-agent monitoring dashboard.
+
+**When to Use**: When running multiple Claude Code agents in parallel.
+
+**What It Does**:
+1. Opens terminal-based dashboard (TUI)
+2. Shows all active agents with context usage
+3. Displays cost per agent and total
+4. Shows which issues each agent is working on
+5. Warns on context thresholds (>70%, >85%)
+
+**Launch**:
+```bash
+# In a separate terminal pane
+uv run global/tools/anvil-hud.py
+
+# Demo mode with sample data
+uv run global/tools/anvil-hud.py --demo
+```
+
+**Dashboard Keybindings**:
+| Key | Action |
+|-----|--------|
+| `q` | Quit HUD |
+| `r` | Force refresh |
+| `d` | Toggle detailed view |
+| `?` | Show help |
+
+**Agent Panel Shows**:
+- **Agent ID**: Human-readable name (e.g., `swift-falcon-a3f2`)
+- **Model**: Current model (Opus/Sonnet/Haiku)
+- **Context**: Usage percentage with color-coded warnings
+- **Cost**: Session spend in USD
+- **Project**: Working directory
+- **Status**: Active, idle, or stale
+
+**Status Indicators**:
+| Icon | Meaning |
+|------|---------|
+| ● | Active (recent activity) |
+| ○ | Idle (no recent activity) |
+| ⚠ | Context warning (>70%) |
+| 🔴 | Context critical (>85%) |
+
+**Data Sources**:
+- `~/.anvil/agents.json` — Agent registry (auto-updated by statusline hook)
+- `.claude/anvil-state.json` — Current session state
+
+**Related Commands**:
+- `/orient` — Registers agent at session start
+- `/handoff` — Preserves context before ending session
+
+---
+
+## Maintenance Commands
+
+### /release
+
+**Purpose**: Consolidate [Unreleased] changes into a versioned release.
+
+**When to Use**: At sprint end, after major feature merges, when ready to cut a release.
+
+**Why This Exists**: In multi-agent environments, version assignment is dangerous. Multiple agents working simultaneously can create version conflicts. This command provides a single coordination point.
+
+**Multi-Agent Rule**: Agents NEVER assign versions during development. All agents add entries to [Unreleased]. One agent or human runs `/release` at the coordination point.
+
+**What It Does**:
+1. Parses CHANGELOG.md [Unreleased] section
+2. Calculates version bump (BREAKING→major, Added→minor, Fixed→patch)
+3. Shows preview and requires confirmation
+4. Transforms changelog: [Unreleased] → [X.Y.Z] - date
+5. Updates VERSION file
+6. Creates annotated git tag
+
+**Version Bump Rules**:
+
+| Change Type | Bump | Example |
+|-------------|------|---------|
+| `BREAKING CHANGE` | MAJOR | 1.3.0 → 2.0.0 |
+| `### Added` | MINOR | 1.3.0 → 1.4.0 |
+| `### Changed/Fixed/Removed` only | PATCH | 1.3.0 → 1.3.1 |
+
+**Output Format**:
+```markdown
+## Release Preview
+
+**Current version**: 1.3.0
+**New version**: 1.4.0 (MINOR bump)
+**Reason**: New features added
+
+### Changes to include:
+- Enhanced `/evidence` Command
+- Enhanced `/handoff` Command
+
+**Proceed with release?** [y/N]
+```
+
+After confirmation:
+```markdown
+## Release Complete
+
+**Version**: 1.4.0
+**Tag**: v1.4.0
+**Commit**: abc1234
+
+Next steps:
+1. Push to remote: `git push origin main --tags`
+2. Create GitHub release (optional)
+```
+
+---
+
+### /shard
+
+**Purpose**: Break large specifications into atomic pieces.
+
+**When to Use**: When specs exceed ~2000 tokens.
+
+**What It Does**:
+1. Analyzes spec for natural boundaries
+2. Creates master spec with references
+3. Creates epic shards
+4. Creates story shards from epics
+5. Maintains cross-references
+
+**Output Structure**:
+
+```
+.claude/specs/current/
+├── SPEC-001-user-auth.md           # Master (overview + refs)
+├── SPEC-001-user-auth/
+│   ├── epic-001-registration.md    # Epic shard
+│   ├── epic-002-login.md           # Epic shard
+│   └── epic-003-password-reset.md  # Epic shard
+│       ├── story-001-request.md    # Story shard
+│       └── story-002-confirm.md    # Story shard
+```
+
+---
+
+### /decay-review
+
+**Purpose**: Weekly maintenance to archive old work.
+
+**When to Use**: Weekly (suggest: Friday afternoon).
+
+**What It Does**:
+1. Finds issues closed >30 days ago
+2. Adds archive summary comment
+3. Archives the issues
+4. Cleans handoff directory (keeps last 7)
+5. Reports metrics
+
+**Target Metrics**:
+- Active issues: < 50
+- Active handoffs: ≤ 7
+
+---
+
+### /weekly-review
+
+**Purpose**: Generate weekly analytics and improvement recommendations.
+
+**When to Use**: Weekly (suggest: Monday morning).
+
+**What It Does**:
+1. Runs Prompt Coach analysis (if installed)
+2. Gathers metrics from Linear
+3. Analyzes CodeRabbit patterns
+4. Reviews discovered work
+5. Generates improvement recommendations
+
+**Output Format**:
+
+```markdown
+## Weekly Review: Dec 11-17, 2025
+
+### Metrics
+| Metric | This Week | Target | Status |
+|--------|-----------|--------|--------|
+| Orientation time | 1.5 min | < 2 min | ✅ |
+| Ready work accuracy | 98% | > 95% | ✅ |
+| Phase gate compliance | 100% | 100% | ✅ |
+| First-pass PR rate | 65% | > 70% | ⚠️ |
+
+### Prompt Quality
+- Clarification rate: 12% (target: <15%) ✅
+- Time lost to vague prompts: 15 min
+- Top improvement: Include file paths in bug reports
+
+### CodeRabbit Patterns
+- Most common finding: Missing error handling (3 instances)
+- Recommendation: Add error handling to skill checklist
+
+### Discovered Work
+- 4 issues discovered this week
+- 2 from ENG-38, 2 from ENG-45
+- All P2 or lower (no blockers created)
+
+### Actions for Next Week
+1. Focus on error handling in new code
+2. Update convention examples with error patterns
+3. Review P2 discovered issues for patterns
+```
+
+---
+
+### /insights
+
+**Purpose**: Synthesize patterns from recent retrospectives, healthchecks, and handoffs.
+
+**When to Use**: Weekly, after multiple healthchecks, or before starting similar work.
+
+**Data Sources**:
+
+| Source | Path | Contains |
+|--------|------|----------|
+| Retrospectives | `.claude/retros/` | Session learnings |
+| Healthchecks | `.claude/healthchecks/` | Framework diagnostics |
+| Handoffs | `.claude/handoffs/` | Session context |
+
+**What It Does**:
+1. Reads retrospectives and healthchecks from last 2 weeks
+2. Identifies patterns (issues mentioned 2+ times)
+3. Categorizes by source: Development Patterns vs Framework Health
+4. Outputs separate improvement recommendations
+5. **Generates CLAUDE.md patch** with table rows for patterns
+6. Optionally applies patch to update project's CLAUDE.md
+
+**CLAUDE.md Integration**:
+
+After identifying patterns, `/insights` generates a patch:
+
+```markdown
+## CLAUDE.md Patch
+
+Add these rows to the "Project-Learned Patterns" table in CLAUDE.md:
+
+| Pattern | Evidence | Added |
+|---------|----------|-------|
+| Discover Before Building | BGG-149, BGG-146 | 2025-12-31 |
+| Always Destructure Query Results | BGG-148 | 2025-12-31 |
+
+**Apply this patch?**
+- Say "apply patch" to update CLAUDE.md automatically
+- Or copy the table rows manually
+```
+
+This closes the feedback loop: patterns learned from retros flow back into CLAUDE.md.
+
+**Output Format**:
+
+```markdown
+## Insights: Dec 11-17, 2025
+
+### Development Patterns (from retros)
+
+**Process**
+- Skipping /explore leads to rework (3 instances)
+
+**Tooling**
+- ESLint rule for exhaustive-deps would catch hook issues
+
+### Framework Health (from healthchecks)
+
+**Hook Issues**
+- Pre-tool-use hook timeout on large files (2 sessions)
+
+**Safety Rules**
+- rm -rf blocked appropriately (no false positives)
+
+### Recommended Actions
+
+**Development Improvements**
+1. Add pre-/spec checklist to verify /explore was run
+
+**Framework Improvements**
+1. Increase hook timeout for Bash operations
+
+### No Action Needed
+- One-off issue with staging database (resolved)
+```
+
+---
+
+## Setup Commands
+
+### /linear-setup
+
+**Purpose**: Configure Linear integration for this project.
+
+**When to Use**: First time setting up a project, or when Linear team changes.
+
+**What It Does**:
+1. Checks for existing `.claude/linear.yaml` configuration
+2. Lists available Linear teams
+3. Lets user select a team (or create new one)
+4. Optionally filters to a specific project within the team
+5. Saves configuration to `.claude/linear.yaml`
+
+**Why It Matters**:
+Without Linear configuration, commands like `/orient`, `/sprint`, `/tasks`, and `/discover` will show issues from ALL teams or fail. This ensures each project maps to the correct Linear team.
+
+**Output**: Creates/updates `.claude/linear.yaml`:
+```yaml
+team_key: "ANV"
+team_id: "uuid-here"
+project_name: ""
+project_id: ""
+issue_prefix: "ANV"
+```
+
+**Configuration Reference**:
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `team_key` | Yes | 2-4 letter team identifier |
+| `team_id` | Yes | Linear UUID for the team |
+| `project_name` | No | Filter to specific project |
+| `project_id` | No | Linear UUID for the project |
+| `issue_prefix` | Yes | Prefix for issue IDs |
+
+---
+
+### /anvil-sync
+
+**Purpose**: Sync Anvil framework updates to this project or global config.
+
+**When to Use**: After pulling framework updates, when commands or hooks seem outdated.
+
+**Arguments**:
+- `target`: Where to sync — `project` (default), `global`, or `both`
+- `force`: Overwrite protected files (default: false)
+- `dry-run`: Preview changes without applying (default: false)
+
+**What It Does**:
+1. Locates Anvil framework source (ANVIL_HOME or auto-detect)
+2. Syncs hooks, examples, agents, commands based on target
+3. Protects customized files (CLAUDE.md, product.md, constitution.md)
+4. Updates version marker (.anvil-version)
+
+**Protected Files** (not overwritten without `force:true`):
+- `CLAUDE.md` — Project-specific AI instructions
+- `product.md` — Product definition
+- `constitution.md` — Project principles
+- `settings.local.json` — Local permissions and hooks
+
+**Always Updated**:
+- `hooks/` — All hook scripts
+- `examples/` — Reference templates
+- `agents/` — Sub-agent definitions
+- `commands/` — Slash commands
+
+**Usage Examples**:
+```
+/anvil-sync                    # Sync current project
+/anvil-sync target:global      # Sync ~/.claude/
+/anvil-sync target:both        # Sync both
+/anvil-sync dry-run:true       # Preview changes
+/anvil-sync force:true         # Overwrite protected files
+```
+
+**CLI Alternative**:
+```bash
+# From anywhere with ANVIL_HOME set
+anvil-sync --global --project .
+
+# Or directly
+$ANVIL_HOME/scripts/sync.sh --project /path/to/project
+```
+
+---
+
+### /anvil-settings
+
+**Purpose**: Manage Anvil framework settings for the current project.
+
+**When to Use**: Configure auto-trigger behavior, view current settings, reset to defaults.
+
+**Usage**:
+```bash
+/anvil-settings                    # View all settings
+/anvil-settings autoRetro on       # Enable auto-retro prompt
+/anvil-settings autoHealthcheck on # Enable auto-healthcheck
+/anvil-settings reset              # Reset to defaults
+```
+
+**Available Settings**:
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `autoRetro` | `off` | Prompt for `/retro` at session end |
+| `autoHealthcheck` | `off` | Run `/healthcheck` at session end |
+
+**What It Does**:
+1. Reads `.claude/anvil.config.json`
+2. Displays or modifies settings
+3. Creates config file if missing
+
+**Config File**: `.claude/anvil.config.json`
+```json
+{
+  "version": "1.0",
+  "autoRetro": false,
+  "autoHealthcheck": false
+}
+```
+
+**Output Format**:
+```markdown
+## Anvil Settings
+
+| Setting | Value | Description |
+|---------|-------|-------------|
+| autoRetro | off | Prompt for /retro at session end |
+| autoHealthcheck | off | Run /healthcheck at session end |
+```
+
+**Auto-Trigger Behavior**:
+
+When enabled, the stop hook reads the config and outputs a reminder:
+
+```
+[Anvil Auto-Trigger]
+The following commands are configured to run at session end:
+  → /healthcheck
+  → /retro
+
+Consider running these commands before ending the session.
+```
+
+This reminder appears in the hook output, prompting you to run the configured commands.
+
+---
+
+## Power Mode Commands
+
+### /ralph
+
+**Purpose**: Ralph Wiggum autonomous execution mode for long-running, unattended AI development.
+
+> **Important**: Ralph is a specialized power tool for specific scenarios, NOT a replacement for the standard workflow. Use it for large refactoring, migrations, or overnight runs — not for daily work.
+
+**When to Use**:
+- Large-scale refactoring with clear completion criteria
+- Framework migrations (Jest→Vitest, CJS→ESM)
+- TDD with clear failing tests to pass
+- Greenfield projects with detailed specs
+- Test coverage expansion
+- Overnight/unattended execution
+
+**When NOT to Use**:
+- Exploratory work
+- Ambiguous requirements
+- Security-sensitive code
+- Architecture decisions
+- Quick fixes (overkill)
+- Interactive debugging
+
+**Usage**:
+```bash
+# Start autonomous execution
+/ralph start "Migrate all tests from Jest to Vitest"
+
+# With options
+/ralph start "Add OAuth authentication" --max-iterations 30
+
+# Check progress
+/ralph status
+
+# Stop early
+/ralph stop
+```
+
+**Arguments**:
+
+| Argument | Description |
+|----------|-------------|
+| `start [description]` | Initialize Ralph mode with a task |
+| `status` | Show current iteration and progress |
+| `stop` | Force exit Ralph mode cleanly |
+
+**Flags**:
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--max-iterations` | 50 | Maximum iterations before stopping |
+| `--completion-promise` | COMPLETE | Text that signals completion |
+
+**What It Does**:
+
+1. **Start**: Breaks task into atomic TODO items, creates PROMPT.md, fix_plan.md, progress.txt
+2. **Loop**: Executes ONE item per iteration, updates progress.txt, checks completion
+3. **Safety**: Circuit breaker stops stuck loops automatically
+
+**Files Created**:
+
+| File | Purpose |
+|------|---------|
+| `PROMPT.md` | Main prompt fed to Claude each iteration |
+| `fix_plan.md` | TODO list with checkboxes |
+| `progress.txt` | Iteration log to prevent repeated mistakes |
+| `.claude/ralph-state.json` | State tracking |
+
+**Circuit Breaker (Safety)**:
+
+Ralph includes automatic safety stops:
+
+| Condition | Threshold | Action |
+|-----------|-----------|--------|
+| No file changes | 3 iterations | Stop loop |
+| Repeated errors | 5 iterations | Stop loop |
+| Max iterations | 50 (default) | Stop loop |
+| `<fatal>` signal | Immediate | Stop loop |
+
+**Cost Estimates**:
+
+| Scenario | Estimated Cost |
+|----------|----------------|
+| 10 iterations, small codebase | $5-15 |
+| 50 iterations, medium codebase | $50-100+ |
+| 100+ iterations, large codebase | $200+ |
+
+**Start small**: Use `--max-iterations 10` to understand costs before overnight runs.
+
+**Output Format** (`/ralph status`):
+```markdown
+## Ralph Wiggum Status
+
+| Metric | Value |
+|--------|-------|
+| Status | Running |
+| Iteration | 5 of 50 |
+| Started | 2026-01-07T10:00:00Z |
+| Duration | 45 minutes |
+| Items Complete | 3 of 8 |
+| Last Action | Implemented OAuth callback |
+
+### Recent Progress (last 3 iterations)
+- Iteration 5: Added token refresh logic
+- Iteration 4: Fixed callback URL parsing
+- Iteration 3: Implemented OAuth redirect
+```
+
+**Environment Variables**:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `RALPH_MAX_ITERATIONS` | 50 | Max iterations |
+| `RALPH_COMPLETION_PROMISE` | COMPLETE | Completion text |
+| `RALPH_STATE_FILE` | .claude/ralph-state.json | State file path |
+| `RALPH_ENABLE_LOGGING` | false | Enable detailed logging |
+
+**Decision Guide**:
+```
+Is this task...
+├── Quick fix or bug? → Use standard workflow
+├── Exploratory / unclear? → Use standard workflow
+├── Needs human decisions? → Use standard workflow
+├── Large with clear spec? → Consider Ralph
+├── Migration / refactoring? → Consider Ralph
+└── Overnight / unattended? → Ralph is ideal
+```
+
+---
+
+## Command Cheat Sheet
+
+### Daily Workflow
+```
+/orient → /sprint → /validate → [work] → /discover → /evidence → /handoff
+```
+
+### New Feature Flow
+```
+/explore → /spec → [approve] → /plan → [approve] → /tasks → [implement]
+```
+
+### Brownfield Change Flow
+```
+/explore → /change → [approve] → /plan → [approve] → /tasks → [implement]
+```
+
+### Weekly Maintenance
+```
+/weekly-review → /insights → /decay-review
+```
+
+### Ralph Wiggum Mode (Power Tool)
+```
+/ralph start "task description" → [autonomous loop] → /ralph status → completion
+```
+
+> **Note**: Ralph is for large refactoring, migrations, or overnight runs — NOT for daily work.
+
+---
+
+## Command Dependencies
+
+```
+                    ┌─────────────┐
+                    │   /orient   │
+                    └──────┬──────┘
+                           │
+                    ┌──────▼──────┐
+                    │   /ready    │
+                    └──────┬──────┘
+                           │
+                    ┌──────▼──────┐
+                    │  /validate  │
+                    └──────┬──────┘
+                           │
+         ┌─────────────────┼─────────────────┐
+         │                 │                 │
+  ┌──────▼──────┐   ┌──────▼──────┐   ┌──────▼──────┐
+  │  /explore   │   │   /change   │   │  [direct]   │
+  └──────┬──────┘   └──────┬──────┘   └──────┬──────┘
+         │                 │                 │
+  ┌──────▼──────┐   ┌──────▼──────┐         │
+  │    /spec    │   │  [approve]  │         │
+  └──────┬──────┘   └──────┬──────┘         │
+         │                 │                 │
+  ┌──────▼──────┐          │                 │
+  │  [approve]  │          │                 │
+  └──────┬──────┘          │                 │
+         │                 │                 │
+  ┌──────▼──────┐   ┌──────▼──────┐         │
+  │    /plan    │◄──┤    /plan    │         │
+  └──────┬──────┘   └─────────────┘         │
+         │                                   │
+  ┌──────▼──────┐                           │
+  │  [approve]  │                           │
+  └──────┬──────┘                           │
+         │                                   │
+  ┌──────▼──────┐                           │
+  │   /tasks    │                           │
+  └──────┬──────┘                           │
+         │                                   │
+         └─────────────────┬─────────────────┘
+                           │
+                    ┌──────▼──────┐
+                    │ [implement] │
+                    │             │
+                    │  /discover  │
+                    └──────┬──────┘
+                           │
+                    ┌──────▼──────┐
+                    │  /evidence  │
+                    └──────┬──────┘
+                           │
+                    ┌──────▼──────┐
+                    │  /handoff   │
+                    └─────────────┘
+```
+
+---
+
+*For implementation details, see the [Implementation Guide](implementation-guide.md).*