anvil-dev-framework 0.1.6

package/global/commands/plan.md

@@ -0,0 +1,228 @@
+# /plan - Create Implementation Plan
+
+> Create a detailed implementation plan from an approved specification.
+
+## When to Use
+- After specification is approved
+- Before creating Linear issues
+- When implementation approach needs documentation
+
+## Prerequisites
+- **Exploration completed** (`/explore`) — Did you search for existing code first?
+- Specification created and approved (`/spec`)
+- Technical decisions resolved
+- No blocking open questions
+
+## Execution Steps
+
+### Step 0: Verify Exploration Was Done
+
+**Before planning, confirm exploration happened:**
+
+Check if an exploration report exists or was discussed:
+- Look for recent `/explore` output in conversation
+- Check for `.claude/specs/current/EXPLORE-*.md` files
+
+If no exploration evidence:
+```
+⚠️ **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?
+```
+
+If user chooses to skip: proceed but note the skip in the plan.
+
+### Step 1: Review Specification
+Read the approved spec:
+- Understand all requirements
+- Note acceptance criteria
+- Identify technical constraints
+
+### Step 2: Design Implementation Phases
+Break work into logical phases:
+- Each phase should be independently deployable if possible
+- Consider dependencies between phases
+- Aim for 1-4 hour tasks
+
+### Step 3: Write Implementation Plan
+
+Create file at: `.claude/specs/current/PLAN-[spec-id].md`
+
+Template:
+```markdown
+---
+plan_id: PLAN-[spec-id]
+spec_ref: SPEC-[number]
+status: draft | approved | in-progress | complete
+created: YYYY-MM-DD
+estimated_hours: [X-Y hours]
+---
+
+# Implementation Plan: [Feature Name]
+
+## Specification Reference
+- **Spec**: SPEC-[number]
+- **Linear Issue**: [Issue key]
+
+## Implementation Strategy
+[High-level approach to implementing this feature]
+
+## Phases
+
+### Phase 1: [Phase Name] (Est: X hours)
+**Goal**: [What this phase accomplishes]
+
+**Tasks**:
+1. [ ] [Task description]
+2. [ ] [Task description]
+3. [ ] [Task description]
+
+**Files to Create/Modify**:
+| File | Action | Purpose |
+|------|--------|---------|
+| src/components/X.tsx | Create | [Purpose] |
+| src/services/y.ts | Modify | [Purpose] |
+
+**Acceptance**: [How to verify phase is complete]
+
+---
+
+### Phase 2: [Phase Name] (Est: X hours)
+**Goal**: [What this phase accomplishes]
+**Depends on**: Phase 1
+
+**Tasks**:
+1. [ ] [Task description]
+2. [ ] [Task description]
+
+**Files to Create/Modify**:
+| File | Action | Purpose |
+|------|--------|---------|
+
+**Acceptance**: [How to verify phase is complete]
+
+---
+
+### Phase 3: Testing & Polish (Est: X hours)
+**Goal**: Verify all acceptance criteria, fix edge cases
+
+**Tasks**:
+1. [ ] Write unit tests for [component]
+2. [ ] Write integration tests for [flow]
+3. [ ] Manual testing of acceptance scenarios
+4. [ ] Address any edge cases found
+
+**Acceptance**: All tests pass, all Gherkin scenarios verified
+
+## File Change Summary
+
+### New Files
+| Path | Purpose |
+|------|---------|
+| src/components/Feature.tsx | Main component |
+| src/hooks/useFeature.ts | Feature logic |
+
+### Modified Files
+| Path | Changes |
+|------|---------|
+| src/services/api.ts | Add new endpoint call |
+
+### Deleted Files
+| Path | Reason |
+|------|--------|
+| [none expected] | |
+
+## Testing Strategy
+
+### Unit Tests
+- [ ] [Component/function to test]
+- [ ] [Component/function to test]
+
+### Integration Tests
+- [ ] [Flow to test]
+
+### Manual Testing
+- [ ] [Scenario to manually verify]
+
+## Risks and Rollback
+
+### Known Risks
+| Risk | Mitigation |
+|------|------------|
+| [Risk] | [Mitigation] |
+
+### Rollback Plan
+[How to rollback if something goes wrong]
+
+## Definition of Done
+- [ ] All tasks complete
+- [ ] All tests passing
+- [ ] Code reviewed
+- [ ] Acceptance criteria verified
+- [ ] Documentation updated (if needed)
+```
+
+### Step 4: Request Approval
+
+Output:
+```
+## Implementation Plan Created
+
+**File**: .claude/specs/current/PLAN-[spec-id].md
+**Estimated effort**: X-Y hours
+**Phases**: N phases
+
+### Phase Summary
+1. **[Phase 1]**: [Goal] (X hrs)
+2. **[Phase 2]**: [Goal] (X hrs)
+3. **Testing**: [Goal] (X hrs)
+
+### Files Affected
+- Create: X files
+- Modify: Y files
+- Delete: Z files
+
+**Next Step**: Review and approve plan, then run `/tasks` to create Linear issues.
+
+Please confirm:
+- [ ] Phases are logical
+- [ ] Estimates are reasonable
+- [ ] File changes are expected
+- [ ] Testing strategy is adequate
+```
+
+## Key Behaviors
+- Plans must be **approved** before creating tasks
+- Each phase should be completable in one session
+- Include rollback strategy for risky changes
+- Be explicit about file changes
+
+## State Sync (ANV-176)
+
+After creating the implementation plan, update the session state:
+
+```bash
+python3 global/lib/state_manager.py plan ".claude/specs/current/PLAN-XXX.md"
+```
+
+This updates `.claude/anvil-state.json` with:
+- `phase: "plan"`
+- `activePlan: [path to plan file]`
+- Sets `lastCommand: "/plan"`
+
+And syncs to the agent registry for statusline visibility.
+
+## Integration Points
+- Follows: `/spec` specification
+- Precedes: `/tasks` issue creation
+- Creates: `.claude/specs/current/PLAN-*.md`

package/global/commands/ralph.md

@@ -0,0 +1,346 @@
+# /ralph - Ralph Wiggum Long-Running Mode
+
+> Enable long-running unattended execution with completion promises and circuit breakers.
+
+Based on Geoffrey Huntley's technique: "6 repos overnight", "$50k contract for $297"
+
+## 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 |
+| `--issue` | — | Linear issue ID to fetch subtasks from (e.g., `ANV-209`) |
+| `--project` | — | Linear project name to process all issues |
+| `--subtasks` | — | Filter subtasks (e.g., `ANV-1..ANV-5` or `ANV-1,ANV-3`) |
+| `--no-sync` | false | Disable syncing status back to Linear |
+
+---
+
+## Execution: /ralph start
+
+### Step 1: Gather Task Information
+
+**Option A: From Linear Issue (Recommended)**
+
+If `--issue` flag is provided:
+```bash
+python3 global/lib/ralph_state.py init-linear \
+    --issue "ANV-209" \
+    [--filter "ANV-210..ANV-215"] \
+    [--no-sync]
+```
+
+This automatically:
+- Fetches the parent issue title as the objective
+- Fetches all subtasks as TODO items
+- Enables Linear sync to update subtask status
+- Creates `[ANV-XXX]` prefixed items in fix_plan.md
+
+**Option B: Manual Input**
+
+Ask for or parse from arguments:
+- Task name (short identifier)
+- Objective (what needs to be accomplished)
+- TODO items (break down into atomic steps)
+
+### Step 2: Create Task Structure
+
+Create the following files:
+
+**PROMPT.md** - Main prompt fed to Claude each iteration:
+```bash
+# Use template
+cp global/templates/ralph/PROMPT.md.template PROMPT.md
+# Substitute variables
+```
+
+**fix_plan.md** - TODO list with checkboxes:
+```markdown
+# Fix Plan: [Task Name]
+
+## TODO Items
+- [ ] Item 1
+- [ ] Item 2
+- [ ] Item 3
+```
+
+**When using Linear integration**, items include issue links:
+```markdown
+# Fix Plan: Linear: ANV-209
+
+> Linear Issue: [ANV-209](https://linear.app/your-org/issue/ANV-209)
+
+## TODO Items
+- [ ] [ANV-210] Phase 1: LinearProvider Implementation
+- [ ] [ANV-211] Phase 2: Ralph State Linear Fields
+- [ ] [ANV-212] Phase 3: Command Interface Update
+```
+
+**progress.txt** - Iteration progress log:
+```markdown
+# Ralph Wiggum Progress Log
+
+## Iteration 0 - Initialization
+- Created fix_plan.md
+- Ready to start
+```
+
+### Step 3: Initialize State
+
+Create `.claude/ralph-state.json`:
+```json
+{
+  "task_name": "...",
+  "objective": "...",
+  "iteration": 0,
+  "started_at": "2026-01-07T00:00:00Z",
+  "status": "running",
+  "no_change_count": 0,
+  "last_diff_hash": ""
+}
+```
+
+### Step 4: Enable Stop Hook
+
+The ralph_stop.sh hook will automatically:
+- Block exit until `<promise>COMPLETE</promise>` detected
+- Track iterations and enforce max limit
+- Activate circuit breaker on stuck loops
+- Create git checkpoints before restart
+
+### Step 5: Start Loop
+
+Begin the Ralph loop (external bash or let Claude Code handle):
+```bash
+while :; do
+    cat PROMPT.md | npx --yes @anthropic/claude-code --print
+done
+```
+
+---
+
+## Execution: /ralph status
+
+Show current Ralph mode status:
+
+```
+## 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
+```
+
+**With Linear integration**, additional fields are shown:
+
+```
+## 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 |
+| Progress | 38% |
+
+### Linear Integration
+| Field | Value |
+|-------|-------|
+| Parent Issue | [ANV-209](https://linear.app/your-org/issue/ANV-209) |
+| Subtasks | 3 done, 0 skipped, 5 remaining |
+| Last Sync | 2026-01-07T10:45:00Z |
+| Sync Status | Enabled |
+
+### Current Subtask
+[ANV-212] Phase 3: Command Interface Update
+
+### Recently Completed
+- [ANV-210] Phase 1: LinearProvider Implementation
+- [ANV-211] Phase 2: Ralph State Linear Fields
+```
+
+---
+
+## Execution: /ralph stop
+
+Force exit Ralph mode:
+
+1. Set status to "stopped" in state file
+2. Log the manual stop
+3. Clean up state file
+4. Output summary of progress
+
+```
+## Ralph Wiggum Stopped
+
+Task: Implement OAuth
+Iterations completed: 5
+Items completed: 3 of 8
+Status: Manually stopped
+
+Remaining items:
+- [ ] Add session persistence
+- [ ] Implement logout
+- [ ] Add refresh token handling
+- [ ] Write tests
+
+Files modified:
+- src/auth/oauth.ts
+- src/auth/callback.ts
+- src/auth/tokens.ts
+
+To resume later, run: /ralph start "Continue OAuth implementation"
+```
+
+---
+
+## Critical Rules
+
+| Rule | Reason |
+|------|--------|
+| **ONE item per loop** | Prevents context overflow |
+| **Update progress.txt every iteration** | Prevents repeated mistakes |
+| **Subagents for research** | Keeps main context clean (500 max) |
+| **Single agent for build/test** | Prevents race conditions |
+| **Commit on success** | Each item gets committed |
+| **Tests gate progress** | No marking complete without tests |
+
+---
+
+## Circuit Breaker
+
+The Ralph stop hook includes automatic circuit breaker:
+
+| 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 |
+
+---
+
+## 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 |
+
+---
+
+## Cost Considerations
+
+| Scenario | Estimated Cost |
+|----------|----------------|
+| 10 iterations, small codebase | $5-15 |
+| 50 iterations, medium codebase | $50-100+ |
+| 100+ iterations, large codebase | $200+ |
+
+**Recommendation**: Start with `--max-iterations 10` to understand costs.
+
+---
+
+## When to Use Ralph
+
+**Good for:**
+- Large-scale refactoring with clear completion criteria
+- Framework migrations (Jest→Vitest, etc.)
+- TDD workflows (implement to pass failing tests)
+- Greenfield projects with defined specs
+- Test coverage expansion
+
+**Not good for:**
+- Ambiguous requirements
+- Architectural decisions needing human judgment
+- Security-sensitive code
+- Exploratory debugging
+
+---
+
+## Example Usage
+
+### Basic Start
+```
+/ralph start "Migrate all tests from Jest to Vitest"
+```
+
+### With Options
+```
+/ralph start "Add OAuth authentication" --max-iterations 30 --completion-promise "AUTH_COMPLETE"
+```
+
+### From Linear Issue (Recommended)
+```
+/ralph start --issue ANV-209
+```
+
+This fetches the issue title and all subtasks automatically.
+
+### From Linear with Subtask Filter
+```
+/ralph start --issue ANV-209 --subtasks ANV-210..ANV-213
+```
+
+Only process phases 1-4 (ANV-210 through ANV-213).
+
+### From Linear without Syncing
+```
+/ralph start --issue ANV-209 --no-sync
+```
+
+Run Ralph but don't update Linear issue statuses.
+
+### Check Progress
+```
+/ralph status
+```
+
+### Stop Early
+```
+/ralph stop
+```
+
+---
+
+## Integration Points
+
+- **Stop Hook**: `global/hooks/ralph_stop.sh`
+- **Templates**: `global/templates/ralph/`
+- **State File**: `.claude/ralph-state.json`
+- **Logs**: `.claude/logs/ralph.log`
+- **Linear State**: `global/lib/ralph_state.py` (Linear integration)
+- **Linear Provider**: `global/lib/linear_provider.py` (API wrapper)
+
+## Anti-Patterns
+
+| Don't | Do Instead |
+|-------|------------|
+| Multiple items per iteration | Complete ONE item, then restart |
+| Skip progress.txt updates | ALWAYS update progress.txt |
+| Ignore test failures | Fix tests before marking complete |
+| Vague completion criteria | Define objective, measurable criteria |
+| Run without max-iterations | Always set a reasonable limit |