ralphie 1.0.0 → 1.1.0

package/templates/.claude/ralphie.md

@@ -254,7 +254,7 @@ npx bundlephobia <package>
 
 ### Required Reading
 Before starting work in a Ralphie loop:
-- **Always read:** `SPEC.md` - Project requirements and task list
+- **Always read:** Active spec in `specs/active/` - Project requirements and task list
 - **Read if needed:** `STATE.txt` - Check if unsure what's already done
 - **Read if needed:** `.ai/ralphie/index.md` - Last 3-5 commits for context
 
@@ -322,7 +322,7 @@ You: Any specific dotfiles it must support, or auto-discover from home directory
 [Generate SPEC after gathering sufficient detail]
 ```
 
-**Important:** When starting a new project, replace the existing SPEC.md entirely. Each SPEC represents one project or feature set.
+**Important:** When starting a new project, create a new spec in `specs/active/`. Each spec represents one project or feature set.
 
 ### Writing SPECs
 

package/templates/RALPHIE.md

@@ -1,11 +1,11 @@
 # Using Ralphie
 
-Ralphie is an autonomous AI coding loop. You write a SPEC, Ralphie works through it task by task.
+Ralphie is an autonomous AI coding loop. You write a spec, Ralphie works through it task by task.
 
 ## Quick Start
 
-1. **Create a SPEC.md** with your project requirements and tasks
-2. **Run Ralphie**: `ralphie run` or `ralphie run -n 5` for multiple iterations
+1. **Create a spec** in `specs/active/` with your project requirements
+2. **Run Ralphie**: `ralphie run` or `ralphie run --all` to complete all tasks
 
 ## Project Structure
 
@@ -14,87 +14,115 @@ Ralphie expects this structure:
 ```
 your-project/
 ├── .claude/
-│   └── ralphie.md      # Coding standards (auto-created)
-├── .ai/ralphie/
-│   ├── plan.md       # Current task plan (Ralphie writes this)
-│   └── index.md      # Commit history (Ralphie appends here)
-├── SPEC.md            # YOUR requirements (you write this)
-├── STATE.txt      # Progress log (Ralphie updates this)
-└── src/              # Your code
+│   └── ralphie.md        # Coding standards (auto-created)
+├── specs/
+│   ├── active/           # Current specs (you write here)
+│   │   └── my-feature.md
+│   └── completed/        # Archived specs (auto-moved)
+├── STATE.txt             # Progress log (Ralphie updates this)
+└── src/                  # Your code
 ```
 
-## Writing a SPEC
+## Writing a Spec (V2 Format)
 
-Your SPEC.md should have checkboxes for tasks. **Each checkbox = one Ralphie iteration**, so batch related work together.
+Specs use task IDs and status tracking:
 
 ```markdown
-# My Project
-
-## Overview
-Brief description of what you're building.
-
-## Phase 1: Setup
-- [ ] Initialize project with TypeScript, testing, and linting
-- [ ] Set up database models and migrations
-  - User model with email, password hash, timestamps
-  - Post model with title, body, author reference
-  - Comment model with body, author, post reference
-
-## Phase 2: Core Features
-- [ ] Implement authentication system
-  - POST /auth/register - create user with hashed password
-  - POST /auth/login - validate credentials, return JWT
-  - POST /auth/logout - invalidate token
-  - Middleware for protected routes
-  - Tests for all auth flows
-
-- [ ] Build posts API with full CRUD
-  - GET/POST/PUT/DELETE endpoints
-  - Authorization (only author can edit/delete)
-  - Pagination for list endpoint
-  - Tests for all operations
+# My Feature
+
+Goal: Brief description of what you're building.
+
+## Context
+
+Background information for the AI implementing this spec.
+
+## Tasks
+
+### T001: Initialize project with TypeScript and testing
+- Status: pending
+- Size: M
+
+**Deliverables:**
+- TypeScript configuration with strict mode
+- Vitest setup with coverage
+- Basic project structure
+
+**Verify:** `npm run type-check && npm test`
+
+---
+
+### T002: Set up database models
+- Status: pending
+- Size: M
+
+**Deliverables:**
+- User model with email, password hash, timestamps
+- Post model with title, body, author reference
+- Migration scripts
+
+**Verify:** `npm run migrate && npm test`
+
+---
+
+### T003: Implement authentication system
+- Status: pending
+- Size: L
+
+**Deliverables:**
+- POST /auth/register endpoint
+- POST /auth/login endpoint with JWT
+- Auth middleware for protected routes
+- Tests for all auth flows
+
+**Verify:** `npm test -- auth`
+
+---
+
+## Acceptance Criteria
+
+- WHEN user registers, THEN account is created with hashed password
+- WHEN user logs in with valid credentials, THEN JWT is returned
 ```
 
 ### Task Design Principles
 
-**One checkbox = one iteration.** Sub-bullets are implementation details, not separate tasks.
+**One task = one logical unit of work.** Deliverables are implementation details.
 
-| Pattern | Iterations | Throughput |
-|---------|------------|------------|
-| `- [ ] Create db.ts`<br>`- [ ] Create redis.ts`<br>`- [ ] Create queue.ts` | 3 | Low |
-| `- [ ] Create data layer (db.ts, redis.ts, queue.ts)` | 1 | High |
+| Size | Points | Description |
+|------|--------|-------------|
+| S | 1 | Single file, < 50 lines |
+| M | 2 | Multiple files, 50-200 lines |
+| L | 4 | Complex feature, 200+ lines |
 
 **Batching heuristics:**
-- Same verb? Batch them. ("Create X, Create Y" → "Create X and Y")
-- Same feature? Batch them. (model + API + tests = one task)
-- Files that import each other? Batch them.
-- Sweet spot: 3-7 files or ~200-500 lines per task
-
-**Include with each task:**
-- Implementation AND tests
-- Related files that depend on each other
-- All sub-components of a feature
+- Same feature? One task. (model + API + tests = T001)
+- Files that import each other? One task.
+- Sweet spot: 3-7 files per task
 
 ## Commands
 
 ```bash
 ralphie run              # Run one iteration
+ralphie run --all        # Run until spec complete
 ralphie run -n 5         # Run 5 iterations
-ralphie run --help       # See all options
+ralphie status           # Show progress
+ralphie archive          # Move completed spec to archive
+ralphie --help           # See all options
 ```
 
 ## The Loop
 
 Each iteration, Ralphie:
-1. Reads SPEC.md to find the next incomplete task
-2. Writes a plan to .ai/ralphie/plan.md
-3. Implements the task with tests
+1. Reads spec from `specs/active/` to find pending tasks
+2. Implements the task with tests
+3. Updates task status to `passed` or `failed`
 4. Commits changes
-5. Updates STATE.txt and .ai/ralphie/index.md
+5. Updates STATE.txt
 
 ## Tips
 
 - **Clean git state**: Ralphie requires no uncommitted changes before running
-- **One task per iteration**: Don't expect multiple checkboxes done at once
-- **Check STATE.txt**: See what's been done if you're unsure
-- **Edit SPEC anytime**: Add/remove/reorder tasks between runs
+- **One task per iteration**: Tasks transition pending → in_progress → passed/failed
+- **Check status**: Run `ralphie status` to see progress
+- **Edit spec anytime**: Add/remove/reorder tasks between runs
+

package/templates/specs/lessons.md

@@ -0,0 +1,18 @@
+# Lessons Learned
+
+Cross-spec learnings that apply to future projects. Add entries as you discover patterns, pitfalls, and solutions.
+
+## Format
+
+```markdown
+### YYYY-MM-DD: Brief title
+**Context:** What spec/task this came from
+**Lesson:** What you learned
+**Apply when:** When this lesson is relevant
+```
+
+---
+
+## Lessons
+
+<!-- Add lessons below this line -->

package/templates/specs/templates/bugfix.md

@@ -0,0 +1,66 @@
+# Bug Fix: Issue Title
+
+Goal: Fix the bug where [describe the incorrect behavior].
+
+## Context
+
+**Observed behavior:** What's happening now (the bug)
+**Expected behavior:** What should happen instead
+**Reproduction steps:** How to trigger the bug
+**Affected areas:** Which parts of the system are impacted
+
+## Tasks
+
+### T001: Investigate root cause
+- Status: pending
+- Size: S
+
+**Deliverables:**
+- Identify the source of the bug
+- Document findings in Notes section
+- Determine fix approach
+
+**Verify:** Root cause documented below
+
+---
+
+### T002: Implement fix
+- Status: pending
+- Size: M
+
+**Deliverables:**
+- Code change that fixes the bug
+- No regressions in existing functionality
+- Follows existing code patterns
+
+**Verify:** `npm test` passes
+
+---
+
+### T003: Add regression test
+- Status: pending
+- Size: S
+
+**Deliverables:**
+- Test that fails without the fix
+- Test that passes with the fix
+- Test covers edge cases if applicable
+
+**Verify:** `npm test -- bug-name` passes
+
+---
+
+## Acceptance Criteria
+
+- WHEN reproducing the original bug steps, THEN correct behavior occurs
+- WHEN running test suite, THEN all tests pass including new regression test
+
+## Notes
+
+<!-- AI updates this section during implementation -->
+
+### Investigation Findings
+<!-- Document root cause here -->
+
+### Fix Approach
+<!-- Document chosen solution here -->

package/templates/specs/templates/feature.md

@@ -0,0 +1,56 @@
+# Feature Name
+
+Goal: One-sentence description of what this feature accomplishes.
+
+## Context
+
+Background information for the agent implementing this spec:
+- What problem does this solve?
+- What existing code/patterns should it follow?
+- Any constraints or requirements?
+
+## Tasks
+
+### T001: First task title
+- Status: pending
+- Size: S
+
+**Deliverables:**
+- What to build (WHAT, not HOW)
+- Another deliverable
+
+**Verify:** `npm test -- something`
+
+---
+
+### T002: Second task title
+- Status: pending
+- Size: M
+
+**Deliverables:**
+- Deliverable description
+- Another deliverable
+
+**Verify:** `curl localhost:3000/api` returns 200
+
+---
+
+### T003: Third task title
+- Status: pending
+- Size: S
+
+**Deliverables:**
+- Deliverable description
+
+**Verify:** `npm run type-check` passes
+
+---
+
+## Acceptance Criteria
+
+- WHEN user does X, THEN Y happens
+- WHEN condition Z, THEN expected outcome
+
+## Notes
+
+<!-- AI updates this section during implementation -->

package/templates/specs/templates/refactor.md

@@ -0,0 +1,80 @@
+# Refactor: Component/Module Name
+
+Goal: Improve code quality of [target] without changing external behavior.
+
+## Context
+
+**Why refactor:** What's wrong with the current code?
+**Target scope:** Which files/modules are being refactored
+**Constraints:** What must remain unchanged (APIs, behavior, etc.)
+
+## Tasks
+
+### T001: Audit current implementation
+- Status: pending
+- Size: S
+
+**Deliverables:**
+- Document current code structure
+- Identify specific issues to address
+- List files to modify
+
+**Verify:** Audit documented in Notes section
+
+---
+
+### T002: Refactor core logic
+- Status: pending
+- Size: M
+
+**Deliverables:**
+- Improved code structure
+- Better naming/organization
+- Reduced complexity or duplication
+- No behavior changes
+
+**Verify:** `npm test` passes with same coverage
+
+---
+
+### T003: Update related code
+- Status: pending
+- Size: S
+
+**Deliverables:**
+- Update callers if signatures changed
+- Update imports if files moved
+- Update types if interfaces changed
+
+**Verify:** `npm run type-check` passes
+
+---
+
+### T004: Verify no regressions
+- Status: pending
+- Size: S
+
+**Deliverables:**
+- All existing tests pass
+- Manual verification of key flows
+- Performance not degraded
+
+**Verify:** `npm test && npm run type-check` passes
+
+---
+
+## Acceptance Criteria
+
+- WHEN running test suite, THEN all tests pass
+- WHEN comparing before/after behavior, THEN external behavior unchanged
+- WHEN reviewing code, THEN identified issues are resolved
+
+## Notes
+
+<!-- AI updates this section during implementation -->
+
+### Current Issues
+<!-- List specific code smells/issues -->
+
+### Refactoring Approach
+<!-- Document strategy -->

package/skills/create-spec/SKILL.md

@@ -1,222 +0,0 @@
----
-name: create-spec
-description: Create a SPEC.md through structured interview and LLM review. Use this when starting a new project or feature.
-context: fork
-allowed-tools: Read, Write, Edit, AskUserQuestion, Task
----
-
-# Create SPEC Skill
-
-Create a well-structured SPEC.md through guided interview and quality review.
-
-## Workflow
-
-```
-Interview → Generate → Review → Finalize
-```
-
-## Step 1: Interview
-
-Use **AskUserQuestion** to gather requirements in batches. Don't generate the spec until you have enough context.
-
-### Batch 1: Project Foundation
-
-```typescript
-AskUserQuestion({
-  questions: [
-    {
-      question: "What type of project is this?",
-      header: "Type",
-      multiSelect: false,
-      options: [
-        { label: "CLI tool", description: "Command-line application" },
-        { label: "Web API", description: "REST/GraphQL backend" },
-        { label: "Library", description: "Reusable package" },
-        { label: "Full-stack", description: "Frontend + backend" }
-      ]
-    },
-    {
-      question: "What language/framework?",
-      header: "Stack",
-      multiSelect: false,
-      options: [
-        { label: "TypeScript/Node.js (Recommended)", description: "Modern JS with types" },
-        { label: "Python", description: "Great for data, ML, scripting" },
-        { label: "Go", description: "Fast, good for systems" },
-        { label: "Rust", description: "Memory-safe systems" }
-      ]
-    }
-  ]
-})
-```
-
-### Batch 2: Core Requirements
-
-Ask about:
-- Primary use case (what problem does it solve?)
-- Target users (who will use this?)
-- Core features (what must it do?)
-- External integrations (APIs, databases, services?)
-
-### Batch 3: Quality & Constraints
-
-Ask about:
-- Testing expectations (unit only / unit+integration / full)
-- Auth requirements (none / basic / OAuth / custom)
-- Performance constraints (if any)
-- Timeline/priority (MVP vs full feature set)
-
-### Interview Tips
-
-- Ask follow-up questions if answers are vague
-- Dig into edge cases: "What happens when X fails?"
-- Clarify scope: "Is Y a must-have or nice-to-have?"
-- Don't proceed until you understand the core requirements
-
-## Step 2: Generate SPEC
-
-Write `SPEC.md` following these rules:
-
-### Structure
-
-```markdown
-# Project Name
-
-Brief description (1-2 sentences).
-
-## Goal
-What this project achieves when complete.
-
-## Tasks
-
-### Phase 1: Foundation
-- [ ] Task description
-  - Deliverable 1
-  - Deliverable 2
-
-### Phase 2: Core Features
-- [ ] Another task
-  - Deliverable 1
-```
-
-### Task Rules
-
-**Each checkbox = one Ralphie iteration.** Batch related work.
-
-```markdown
-# BAD - 4 iterations
-- [ ] Create UserModel.ts
-- [ ] Create UserService.ts
-- [ ] Create UserController.ts
-- [ ] Create user.test.ts
-
-# GOOD - 1 iteration
-- [ ] Create User module (Model, Service, Controller) with tests
-```
-
-### What SPECs Must NOT Include
-
-SPECs describe **requirements**, not solutions.
-
-**Never include:**
-- Code snippets or implementation examples
-- File:line references (e.g., `auth.ts:42`)
-- Shell commands (`npm install X`, `git log`)
-- Root cause analysis ("The bug is because...")
-- "Technical Notes" or "Fix Approach" sections
-- Implementation instructions
-
-**Sub-bullets are deliverables, not instructions:**
-
-```markdown
-# BAD - prescribes HOW
-- [ ] Fix auth bug
-  - Use `bcrypt.compare()` instead of `===`
-  - Add try/catch at line 50
-
-# GOOD - describes WHAT
-- [ ] Fix auth bug
-  - Password comparison should be timing-safe
-  - Handle comparison errors gracefully
-```
-
-### Verification Steps
-
-Each task SHOULD include a **Verify:** section with concrete checks:
-
-```markdown
-- [ ] Implement authentication system
-  - POST /auth/register - create user with hashed password
-  - POST /auth/login - validate credentials, return JWT
-  - Tests for all auth flows
-
-  **Verify:**
-  - `curl -X POST localhost:3000/auth/register -d '{"email":"test@test.com","password":"test123"}'` → 201
-  - `curl -X POST localhost:3000/auth/login -d '{"email":"test@test.com","password":"test123"}'` → returns JWT
-  - `npm test` → all tests pass
-```
-
-Good verification steps:
-- API calls with expected response codes
-- CLI commands with expected output
-- File existence checks (`ls dist/` → contains index.js)
-- Test commands (`npm test` → all pass)
-
-## Step 3: Review with LLM
-
-After generating the spec, spawn a review agent to check for violations:
-
-```typescript
-Task({
-  subagent_type: 'general-purpose',
-  description: 'Review SPEC.md',
-  prompt: `Review SPEC.md for convention violations.
-
-Check for these anti-patterns:
-1. Code snippets (any \`\`\` blocks with implementation code)
-2. File:line references (e.g., setup.ts:150)
-3. Shell commands in tasks (npm, git, docker, etc.)
-4. "Technical Notes" or "Fix Approach" sections
-5. Implementation instructions ("Use X to...", "Change line Y")
-
-For each violation found:
-- Quote the problematic line
-- Explain why it's a violation
-- Suggest a requirement-focused alternative
-
-Respond with:
-- PASS: No violations found
-- FAIL: List each violation with fix suggestion`
-})
-```
-
-### If Review Fails
-
-1. Fix each violation the reviewer identified
-2. Re-run the review
-3. Only proceed when review passes
-
-## Step 4: Finalize
-
-After review passes:
-
-1. Confirm with user: "SPEC is ready. Review it or start first iteration?"
-2. Wait for explicit approval
-3. Do NOT auto-start implementation
-
-```markdown
-✓ SPEC.md created with X tasks across Y phases
-✓ Passed convention review
-
-Ready to proceed? Say "start" to begin first iteration.
-```
-
-## Quick Reference
-
-| Do | Don't |
-|----|-------|
-| Describe outcomes | Prescribe implementation |
-| Use deliverable sub-bullets | Use instruction sub-bullets |
-| Batch related tasks | Split tiny tasks |
-| Keep it scannable | Add code examples |
-| Run LLM review | Skip validation |