@arvorco/relentless 0.3.0 → 0.4.2

package/.claude/skills/convert/SKILL.md

@@ -0,0 +1,248 @@
+---
+name: convert
+description: "Convert tasks.md to prd.json with smart routing classification. Use after creating tasks. Triggers on: convert to prd, generate prd.json, convert tasks."
+---
+
+# Tasks to PRD Converter (with Smart Routing)
+
+Convert user stories from tasks.md into prd.json format WITH automatic routing classification.
+
+> **Note:** This command is typically auto-run by the `/relentless.tasks` skill.
+> Manual execution is only needed if you edit `tasks.md` by hand after generation.
+
+---
+
+## The Job
+
+1. Locate tasks.md in the current feature directory
+2. Validate story structure, dependencies, and TDD compliance
+3. Preview conversion (show story count, dependency chain)
+4. Run the conversion with routing: `relentless convert tasks.md --feature <name>`
+5. Validate the generated prd.json HAS routing metadata
+6. Display routing summary (cost estimates per story)
+7. Report next step
+
+---
+
+## Why Routing Matters
+
+Routing is the **core value** of Relentless:
+
+- **Simple tasks** use cheap models (haiku, flash) - saves money
+- **Complex tasks** use SOTA models (opus, gpt-5) - ensures quality
+- **Estimated costs** BEFORE execution - no surprises
+- **Compare estimated vs actual** after execution - learn and improve
+
+Without routing, you lose the intelligent cost optimization that makes Relentless valuable.
+
+---
+
+## Step 1: Find Feature Directory
+
+Look in `relentless/features/` for the most recent feature:
+
+```bash
+ls -la relentless/features/
+```
+
+Verify:
+- [ ] tasks.md exists in the feature directory
+- [ ] spec.md exists (for context)
+- [ ] Feature directory follows naming convention (NNN-feature-name)
+
+If tasks.md doesn't exist, suggest running `/relentless.tasks` first.
+
+---
+
+## Step 2: Validate tasks.md Structure
+
+Before conversion, validate the tasks.md file:
+
+### Required Elements
+
+- [ ] Each story has unique ID (US-XXX format)
+- [ ] Each story has acceptance criteria
+- [ ] **TDD criteria included** (tests must be mentioned in acceptance criteria)
+- [ ] Dependencies reference valid story IDs
+- [ ] No circular dependencies
+- [ ] Routing Preference line present (recommended)
+
+### Example Valid Story
+
+```markdown
+### US-001: Create User Registration
+
+**Description:** As a new user, I want to register so I can access the app.
+
+**Acceptance Criteria:**
+- [ ] POST /api/register endpoint exists
+- [ ] Email validation works
+- [ ] Password is hashed
+- [ ] Unit tests pass
+- [ ] Integration test passes
+
+**Dependencies:** None
+**Phase:** Foundation
+**Priority:** 1
+```
+
+---
+
+## Step 3: Run Conversion (with Routing)
+
+Execute the convert command:
+
+```bash
+relentless convert relentless/features/<feature>/tasks.md --feature <feature-name>
+```
+
+### Options
+
+| Flag | Description |
+|------|-------------|
+| `--mode <mode>` | Routing mode: free, cheap, good (default), genius |
+| `--skip-routing` | Skip routing (NOT recommended) |
+| `--auto-number` | Auto-number feature directory |
+| `--with-checklist` | Merge checklist criteria |
+
+### Expected Output
+
+```
+Converting tasks.md...
+
+Classifying 6 stories for routing (mode: good)...
+  US-001: simple -> claude/haiku-4.5 ($0.0012)
+  US-002: medium -> claude/sonnet-4.5 ($0.0034)
+  US-003: complex -> claude/opus-4.5 ($0.0156)
+  US-004: simple -> claude/haiku-4.5 ($0.0010)
+  US-005: medium -> claude/sonnet-4.5 ($0.0028)
+  US-006: expert -> claude/opus-4.5 ($0.0234)
+
+Total estimated cost: $0.0474
+
+Created relentless/features/NNN-feature/
+  prd.json - 6 stories
+  Routing metadata included
+  prd.md - from tasks.md
+  progress.txt - progress log
+```
+
+---
+
+## Step 4: Validate Routing Output
+
+After conversion, verify the prd.json has routing metadata:
+
+```bash
+cat relentless/features/<feature>/prd.json | jq '.userStories[0].routing'
+```
+
+### Expected Routing Structure
+
+```json
+{
+  "complexity": "simple",
+  "harness": "claude",
+  "model": "haiku-4.5",
+  "mode": "good",
+  "estimatedCost": 0.0012,
+  "classificationReasoning": "Task classified as simple (confidence: 85%)..."
+}
+```
+
+**CRITICAL:** If routing is missing, the conversion was run with `--skip-routing`. Re-run without that flag.
+
+---
+
+## Step 5: Report Summary
+
+After successful conversion, provide this summary:
+
+```markdown
+## Conversion Complete
+
+**Feature:** NNN-feature-name
+**Stories:** 6 total
+
+### Routing Summary
+
+| Story  | Complexity | Harness/Model        | Est. Cost |
+|--------|------------|----------------------|-----------|
+| US-001 | simple     | claude/haiku-4.5     | $0.0012   |
+| US-002 | medium     | claude/sonnet-4.5    | $0.0034   |
+| US-003 | complex    | claude/opus-4.5      | $0.0156   |
+| US-004 | simple     | claude/haiku-4.5     | $0.0010   |
+| US-005 | medium     | claude/sonnet-4.5    | $0.0028   |
+| US-006 | expert     | claude/opus-4.5      | $0.0234   |
+
+**Total Estimated Cost:** $0.0474
+
+### Files Created
+
+- `relentless/features/<feature>/prd.json` - PRD with routing
+- `relentless/features/<feature>/prd.md` - Copy of tasks.md
+
+### Next Steps
+
+1. Review routing decisions (adjust mode if needed)
+2. Run `/relentless.analyze` to check consistency
+3. Run `relentless run --feature <name> --mode good`
+```
+
+---
+
+## Complexity Classification
+
+The classifier determines complexity based on:
+
+| Complexity | Indicators | Example |
+|------------|------------|---------|
+| **simple** | Basic CRUD, single file, straightforward | "Add logging to function" |
+| **medium** | Multiple files, some logic | "Create REST endpoint with validation" |
+| **complex** | Architecture changes, multiple systems | "Implement OAuth2 authentication" |
+| **expert** | Novel solutions, deep expertise | "Design event sourcing system" |
+
+---
+
+## Mode-Model Matrix
+
+| Mode | Simple | Medium | Complex | Expert |
+|------|--------|--------|---------|--------|
+| free | glm-4.7 | glm-4.7 | grok-code-fast-1 | grok-code-fast-1 |
+| cheap | haiku-4.5 | gemini-flash | gpt-5.2-low | gpt-5.2-low |
+| good | sonnet-4.5 | sonnet-4.5 | opus-4.5 | opus-4.5 |
+| genius | opus-4.5 | opus-4.5 | opus-4.5 | opus-4.5 |
+
+---
+
+## Troubleshooting
+
+### "Tasks.md not found"
+
+Run `/relentless.tasks` first to generate tasks.md from spec.md and plan.md.
+
+### "No routing metadata"
+
+The conversion was run with `--skip-routing`. Re-run:
+```bash
+relentless convert relentless/features/<feature>/tasks.md --feature <feature-name>
+```
+
+### "Invalid dependency"
+
+A story references a non-existent story ID. Check the `Dependencies:` line.
+
+### "Circular dependency detected"
+
+Stories reference each other in a cycle. Example: US-001 depends on US-002, and US-002 depends on US-001.
+
+---
+
+## Notes
+
+- Always run conversion WITH routing (default behavior)
+- Routing metadata enables intelligent cost optimization
+- Review complexity classifications before running
+- Use `--mode free` for testing/experimentation
+- Use `--mode good` (default) for production work
+- Use `--mode genius` for critical/complex features

package/.claude/skills/implement/SKILL.md

@@ -14,6 +14,22 @@ Guide systematic implementation of features using TDD and quality-first approach
 
 ---
 
+## SpecKit Workflow
+
+This skill is **Step 6 of 6** in the Relentless workflow:
+
+specify → plan → tasks → convert → analyze → **implement**
+
+Prerequisites:
+- `spec.md` - Feature specification
+- `plan.md` - Technical implementation plan
+- `tasks.md` - User stories with acceptance criteria
+- `prd.json` - Converted PRD with routing metadata
+- `checklist.md` - Quality validation checklist
+- Analysis must PASS (run `/relentless.analyze` first)
+
+---
+
 ## The Job
 
 Implement user stories one at a time, following strict TDD and updating all tracking files.
@@ -25,8 +41,10 @@ Implement user stories one at a time, following strict TDD and updating all trac
 1. **Read the Constitution** - Review your project's constitution (if exists) for governance principles
 2. **Read prompt.md** - Review workflow guidelines (if exists)
 3. **Read progress.txt** - Check learnings from previous iterations
-4. **Review artifacts** - Ensure spec.md, plan.md, tasks.md, checklist.md exist
-5. **Identify Quality Commands** - Find your project's typecheck, lint, and test commands
+4. **Review artifacts** - Ensure spec.md, plan.md, tasks.md, prd.json, checklist.md exist
+5. **Verify Analysis Passed** - Run `/relentless.analyze` if not already done
+6. **Identify Quality Commands** - Find your project's typecheck, lint, and test commands
+7. **Check Branch** - Verify you're on the correct branch from PRD `branchName`
 
 ---
 
@@ -50,6 +68,11 @@ go build ./... && golangci-lint run && go test ./...
 cargo check && cargo clippy && cargo test
 ```
 
+**Requirements:**
+- Typecheck: 0 errors
+- Lint: 0 errors AND 0 warnings
+- Tests: All pass
+
 **If ANY check fails, DO NOT mark the story as complete. Fix the issues first.**
 
 ---
@@ -81,6 +104,22 @@ For EVERY story, follow strict Test-Driven Development:
 
 ---
 
+## Research Phase (if story has `research: true`)
+
+If the current story has `research: true` in prd.json and no research file exists yet:
+
+1. **Explore the codebase** - Find relevant files, patterns, and dependencies
+2. **Document findings** in `relentless/features/<feature>/research/<story-id>.md`:
+   - Existing patterns that should be followed
+   - Files that will likely need modification
+   - Dependencies and integration points
+   - Potential gotchas or edge cases
+   - Recommended implementation approach
+3. **Do NOT implement** - only research and document
+4. Save your findings to the research file and end your turn
+
+---
+
 ## Per-Story Implementation Flow
 
 For each story (in dependency order):
@@ -89,11 +128,13 @@ For each story (in dependency order):
 - Read `prd.json` to find the next story where `passes: false`
 - Check dependencies are met (dependent stories have `passes: true`)
 - Read the story's acceptance criteria
+- Check routing metadata (complexity, model assigned)
 
 ### 2. Find Relevant Checklist Items
 - Open `checklist.md`
 - Find items tagged with `[US-XXX]` for this story
 - Note any governance/compliance items
+- **Ensure Quality Gates and TDD items are included**
 
 ### 3. Implement with TDD
 Follow the TDD workflow above for each acceptance criterion.
@@ -160,39 +201,22 @@ Append progress entry:
 - Patterns discovered
 - Gotchas encountered
 
+**Constitution Compliance:**
+- [list principles followed]
+
 ---
 ```
 
 ---
 
-## Example Per-Story Workflow
+## Check for Queued Prompts
 
-```markdown
-**Current:** US-001: Test Infrastructure Setup
-
-**Acceptance Criteria:**
-- [ ] Test command runs successfully
-- [ ] Test files are auto-discovered
-- [ ] Coverage report available
-- [ ] Type checking passes
-- [ ] Linting passes
-
-**Relevant Checklist Items:**
-- [ ] CHK-001 [US-001] Test command executes successfully
-- [ ] CHK-002 [US-001] Test files are auto-discovered
-- [ ] CHK-007 Tests written BEFORE implementation
-
-**Implementation Steps:**
-1. Write a simple failing test first
-2. Configure test runner for your project
-3. Verify test discovery works
-4. Run type checking - must pass
-5. Run linting - must pass with 0 warnings
-6. Update tasks.md - check off completed criteria
-7. Update checklist.md - mark verified items
-8. Commit: "feat: US-001 - Test Infrastructure Setup"
-9. Update prd.json: set passes: true
-10. Update progress.txt with learnings
+Between iterations, check `.queue.txt` for user input:
+
+```bash
+# If .queue.txt exists, read and process it
+# Acknowledge in progress.txt
+# Process in FIFO order
 ```
 
 ---
@@ -232,6 +256,32 @@ After completing each story, these files MUST be updated:
 
 ---
 
+## Stop Condition
+
+After completing a user story, check if ALL stories have `passes: true`.
+
+**If ALL stories are complete and passing, output:**
+```
+<promise>COMPLETE</promise>
+```
+
+**If there are still stories with `passes: false`, end your response normally** (another iteration will pick up the next story).
+
+---
+
+## Common Pitfalls to Avoid
+
+1. **Skipping TDD** - Never implement without tests first
+2. **Suppressing lints** - Fix issues properly, don't disable rules
+3. **Large commits** - Keep commits focused and atomic
+4. **Missing typecheck** - Always run typecheck before commit
+5. **Ignoring progress.txt** - Read learnings from previous iterations
+6. **Not checking queue** - Always check `.queue.txt` for user input
+7. **Skipping analysis** - Run `/relentless.analyze` before implementing
+8. **Ignoring routing metadata** - Check story complexity and model assignment
+
+---
+
 ## Notes
 
 - Work on ONE story at a time
@@ -240,8 +290,6 @@ After completing each story, these files MUST be updated:
 - Never skip quality checks
 - Commit after each story
 - Update ALL tracking files
-- This is a guided workflow for manual implementation
-
----
-
-*Adapt all commands and paths to your project's specific setup*
+- Check `.queue.txt` for mid-run input
+- This is a guided workflow for systematic implementation
+- **Adapt all commands and paths to your project's specific setup**

package/.claude/skills/plan/SKILL.md

@@ -9,12 +9,46 @@ Create detailed technical plans that translate feature specifications into imple
 
 ---
 
+## SpecKit Workflow
+
+This skill is **Step 2 of 6** in the Relentless workflow:
+
+specify → **plan** → tasks → convert → analyze → implement
+
+What flows from spec:
+- User requirements → technical approach
+- Routing preference → carried forward
+- Acceptance criteria → test specifications
+
+What flows to tasks:
+- Technical approach → implementation breakdown
+- Test specifications → TDD acceptance criteria
+
+---
+
+## TDD is MANDATORY
+
+The technical plan MUST include concrete test specifications:
+- **Test file locations** (where tests will live)
+- **Test class/function names** (what to create)
+- **Mock/fixture requirements** (what test data needed)
+- **Coverage targets** per component
+
+**The agent MUST write tests BEFORE implementation code.**
+
+This is non-negotiable. Plans without test specifications are incomplete.
+
+---
+
 ## The Job
 
 1. Read the feature specification (`spec.md`)
-2. Read project constitution for technical constraints
-3. Generate technical architecture and implementation plan
-4. Save to `plan.md` in the feature directory
+2. **Extract and validate routing preference (Step 2)**
+3. Read project constitution for technical constraints
+4. Generate technical architecture and implementation plan
+5. **Include complete test specifications**
+6. **Validate against quality gates**
+7. Save to `plan.md` in the feature directory
 
 ---
 
@@ -27,16 +61,34 @@ Find the current feature directory:
 
 ---
 
-## Step 2: Load Context
+## Step 2: Extract Routing Preference
+
+1. Read `spec.md` and extract routing preference
+2. If missing, DEFAULT to: `auto: good | allow free: yes`
+3. Validate format is correct
+4. Carry forward to plan.md metadata
+5. Update progress.txt with routing decision
+
+Example:
+```
+Spec says: **Routing Preference**: auto: genius | allow free: no
+Plan carries: **Routing Preference**: auto: genius | allow free: no
+```
+
+---
+
+## Step 3: Load Context
 
 Read these files:
 1. **relentless/constitution.md** - Project governance and technical standards
 2. **relentless/features/NNN-feature/spec.md** - Feature requirements
 3. Project README or docs for tech stack information
 
+Note all MUST and SHOULD rules from constitution - these are quality gates.
+
 ---
 
-## Step 3: Generate Technical Plan
+## Step 4: Generate Technical Plan
 
 Using the template at `templates/plan.md`, create a plan with:
 
@@ -46,6 +98,7 @@ Using the template at `templates/plan.md`, create a plan with:
 - Architecture approach
 - Key technologies to use (from constitution/existing stack)
 - Integration points
+- Routing preference carried from spec (auto mode or harness/model)
 
 **2. Data Models**
 - Database schemas
@@ -64,11 +117,12 @@ Using the template at `templates/plan.md`, create a plan with:
 - Dependencies between components
 - Integration approach
 
-**5. Testing Strategy**
-- Unit test approach
-- Integration test scenarios
-- E2E test cases
-- Test data requirements
+**5. Test Specifications (MANDATORY)**
+- Test file structure
+- Unit test table (component → test file → functions)
+- Integration test table (flow → test file → scenarios)
+- Mock requirements
+- Coverage targets (minimum 80%)
 
 **6. Security Considerations**
 - Authentication/authorization
@@ -84,24 +138,37 @@ Using the template at `templates/plan.md`, create a plan with:
 
 ---
 
-## Step 4: Ensure Constitution Compliance
+## Step 5: Ensure Constitution Compliance
 
 Validate the plan against constitution:
-- **MUST** rules: Required, plan must follow these
-- **SHOULD** rules: Best practices, document any deviations
+
+### Quality Gates Check
+
+Before completing the plan, validate:
+- [ ] **TDD approach defined** - test specs with file locations
+- [ ] **Quality commands identified** - typecheck, lint, test
+- [ ] **Routing preference carried** from spec
+- [ ] **All MUST rules** from constitution addressed
+- [ ] **No `any` types** planned in TypeScript
+- [ ] **Error handling strategy** defined
+
+**MUST** rules: Required, plan must follow these
+**SHOULD** rules: Best practices, document any deviations
 
 If plan violates MUST rules, revise until compliant.
 
 ---
 
-## Step 5: Save & Report
+## Step 6: Save & Report
 
 1. Save plan to `relentless/features/NNN-feature/plan.md`
-2. Update progress.txt with plan creation timestamp
+2. Update progress.txt with plan creation timestamp and routing info
 3. Report:
    - Plan location
    - Key technical decisions
+   - Test specifications summary
    - Constitution compliance: PASS/FAIL
+   - Routing preference: [carried value]
    - Next step: `/relentless.tasks`
 
 ---
@@ -111,6 +178,8 @@ If plan violates MUST rules, revise until compliant.
 ```markdown
 # Technical Implementation Plan: User Authentication
 
+**Routing Preference**: auto: good | allow free: yes
+
 ## Technical Overview
 
 **Architecture:** Three-tier (API, Service, Data)
@@ -153,20 +222,58 @@ CREATE INDEX idx_users_email ON users(email);
 }
 \`\`\`
 
-## Testing Strategy
+## Test Specifications (MANDATORY)
 
-**Unit Tests:**
-- Password hashing utility
-- Email validation
-- Token generation/verification
-
-**Integration Tests:**
-- Full registration flow
-- Email sending
-- Database operations
+### Test File Structure
+\`\`\`
+tests/
+├── unit/
+│   ├── auth/
+│   │   ├── password.test.ts
+│   │   └── email-validation.test.ts
+│   └── token/
+│       └── jwt.test.ts
+├── integration/
+│   └── auth/
+│       ├── register.test.ts
+│       └── login.test.ts
+└── e2e/
+    └── auth-flow.test.ts
+\`\`\`
 
-**E2E Tests:**
-- Complete user journey from signup to login
+### Unit Tests
+| Component | Test File | Functions to Test |
+|-----------|-----------|-------------------|
+| Password | `tests/unit/auth/password.test.ts` | hashPassword, verifyPassword |
+| Email | `tests/unit/auth/email-validation.test.ts` | validateEmail |
+| JWT | `tests/unit/token/jwt.test.ts` | generateToken, verifyToken |
+
+### Integration Tests
+| Flow | Test File | Scenarios |
+|------|-----------|-----------|
+| Register | `tests/integration/auth/register.test.ts` | success, duplicate email, invalid input |
+| Login | `tests/integration/auth/login.test.ts` | success, wrong password, unconfirmed |
+
+### Mock Requirements
+- Database mock (in-memory or test container)
+- Email service mock (no actual sends)
+- Time mock for token expiration tests
+
+### Coverage Targets
+- Unit: 90% minimum (critical auth code)
+- Integration: All happy paths + error paths
+- E2E: Complete registration and login flow
+
+## Constitution Compliance
+
+**MUST Rules Checked:**
+- [x] TDD is mandatory - test specs defined above
+- [x] Quality gates defined - typecheck, lint, test commands
+- [x] Routing preference carried from spec
+- [x] No `any` types planned
+- [x] Error handling strategy defined
+
+**If any MUST rule cannot be satisfied, document the exception and remediation plan.**
 ```
 
 ---
@@ -177,3 +284,5 @@ CREATE INDEX idx_users_email ON users(email);
 - Include specific technologies and patterns
 - Must comply with constitution
 - Detailed enough for task generation
+- **Test specifications are mandatory** - no tests = incomplete plan
+- **Routing preference must be carried forward** from spec