@arvorco/relentless 0.3.1 → 0.4.3

package/.claude/skills/plan/templates/plan.md

@@ -1,6 +1,8 @@
 # Implementation Plan: [FEATURE]
 
 **Branch**: `[###-feature-name]` | **Date**: [DATE] | **Spec**: [link]
+**Routing Preference**: auto: good | allow free: yes
+<!-- Options: auto: free|cheap|good|genius | allow free: yes|no | OR specific: harness/model -->
 **Input**: Feature specification from `/specs/[###-feature-name]/spec.md`
 
 **Note**: This template is filled in by the `/relentless.plan` command. See `.claude/skills/plan/SKILL.md` for the execution workflow.
@@ -17,21 +19,29 @@
   the iteration process.
 -->
 
-**Language/Version**: [e.g., Python 3.11, Swift 5.9, Rust 1.75 or NEEDS CLARIFICATION]  
-**Primary Dependencies**: [e.g., FastAPI, UIKit, LLVM or NEEDS CLARIFICATION]  
-**Storage**: [if applicable, e.g., PostgreSQL, CoreData, files or N/A]  
-**Testing**: [e.g., pytest, XCTest, cargo test or NEEDS CLARIFICATION]  
+**Language/Version**: [e.g., Python 3.11, Swift 5.9, Rust 1.75 or NEEDS CLARIFICATION]
+**Primary Dependencies**: [e.g., FastAPI, UIKit, LLVM or NEEDS CLARIFICATION]
+**Storage**: [if applicable, e.g., PostgreSQL, CoreData, files or N/A]
+**Testing**: [e.g., pytest, XCTest, cargo test or NEEDS CLARIFICATION]
 **Target Platform**: [e.g., Linux server, iOS 15+, WASM or NEEDS CLARIFICATION]
-**Project Type**: [single/web/mobile - determines source structure]  
-**Performance Goals**: [domain-specific, e.g., 1000 req/s, 10k lines/sec, 60 fps or NEEDS CLARIFICATION]  
-**Constraints**: [domain-specific, e.g., <200ms p95, <100MB memory, offline-capable or NEEDS CLARIFICATION]  
+**Project Type**: [single/web/mobile - determines source structure]
+**Performance Goals**: [domain-specific, e.g., 1000 req/s, 10k lines/sec, 60 fps or NEEDS CLARIFICATION]
+**Constraints**: [domain-specific, e.g., <200ms p95, <100MB memory, offline-capable or NEEDS CLARIFICATION]
 **Scale/Scope**: [domain-specific, e.g., 10k users, 1M LOC, 50 screens or NEEDS CLARIFICATION]
 
-## Constitution Check
+## Constitution Compliance
 
 *GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
 
-[Gates determined based on constitution file]
+**MUST Rules Checked:**
+- [ ] TDD is mandatory - test specs defined in this plan
+- [ ] Quality gates defined - typecheck, lint, test commands
+- [ ] Routing preference carried from spec
+- [ ] No `any` types planned (TypeScript)
+- [ ] Error handling strategy defined
+- [ ] Zero lint warnings policy enforced
+
+**If any MUST rule cannot be satisfied, document the exception and remediation plan.**
 
 ## Project Structure
 
@@ -94,6 +104,49 @@ ios/ or android/
 **Structure Decision**: [Document the selected structure and reference the real
 directories captured above]
 
+## Test Specifications (MANDATORY)
+
+<!--
+  TDD REQUIREMENT: This section is mandatory. Tests are written BEFORE implementation.
+  The agent must create these test files first, verify they fail, then implement.
+-->
+
+### Test File Structure
+
+```text
+tests/
+├── unit/
+│   └── [component].test.ts
+├── integration/
+│   └── [feature].test.ts
+└── e2e/
+    └── [flow].test.ts
+```
+
+### Unit Tests
+
+| Component | Test File | Functions to Test |
+|-----------|-----------|-------------------|
+| [Name] | `tests/unit/[name].test.ts` | [functions] |
+
+### Integration Tests
+
+| Flow | Test File | Scenarios |
+|------|-----------|-----------|
+| [Name] | `tests/integration/[name].test.ts` | [scenarios] |
+
+### Mock Requirements
+
+- [List mocks/fixtures needed]
+- [Database mock approach]
+- [External service mocks]
+
+### Coverage Targets
+
+- **Unit**: 80% minimum
+- **Integration**: Key flows covered (happy path + error paths)
+- **E2E**: Happy path + critical error scenarios
+
 ## Complexity Tracking
 
 > **Fill ONLY if Constitution Check has violations that must be justified**
@@ -102,3 +155,33 @@ directories captured above]
 |-----------|------------|-------------------------------------|
 | [e.g., 4th project] | [current need] | [why 3 projects insufficient] |
 | [e.g., Repository pattern] | [specific problem] | [why direct DB access insufficient] |
+
+## Quality Gates
+
+<!--
+  These commands must pass before any story is considered complete.
+  All three are mandatory - no exceptions.
+-->
+
+### Required Commands
+
+```bash
+# Type checking - 0 errors required
+bun run typecheck
+
+# Linting - 0 errors AND 0 warnings required
+bun run lint
+
+# Tests - all must pass
+bun test
+```
+
+### Per-Story Checklist
+
+Every story implementation must:
+- [ ] Pass typecheck with 0 errors
+- [ ] Pass lint with 0 errors AND 0 warnings
+- [ ] Pass all existing tests
+- [ ] Include new tests (written first, TDD style)
+- [ ] Have no debug code (console.log, debugger)
+- [ ] Have no unused imports or variables

package/.claude/skills/specify/SKILL.md

@@ -9,14 +9,55 @@ Create structured feature specifications from natural language descriptions.
 
 ---
 
+## SpecKit Workflow
+
+This skill is **Step 1 of 6** in the Relentless workflow:
+
+**specify** → plan → tasks → analyze → implement (task by task) or relentless run --feature [FEATURE NAME] --tui
+
+What flows to next step:
+- User requirements → plan will create technical approach
+- Routing preference → carried through all artifacts
+- Acceptance criteria → basis for TDD in implementation
+
+---
+
+## TDD is MANDATORY
+
+The specification MUST include testable acceptance criteria:
+- Every user requirement should be verifiable with tests
+- Test scenarios should be part of each story
+- Edge cases should be documented for test coverage
+
+**All acceptance criteria must be written in Given/When/Then format** to enable direct test implementation.
+
+---
+
 ## The Job
 
 1. Receive feature description from user
-2. Generate short name and feature number
-3. Create branch and feature directory in `relentless/features/NNN-feature-name/`
-4. Generate specification using template
-5. Validate specification quality
-6. Save to `spec.md`
+2. **Confirm routing preference (Step 0)**
+3. Generate short name and feature number
+4. Create branch and feature directory in `relentless/features/NNN-feature-name/`
+5. Generate specification using template
+6. Validate specification quality (including TDD readiness)
+7. Save to `spec.md`
+
+---
+
+## Step 0: Confirm Routing Preference (BEFORE generating spec)
+
+Ask the user these specific questions:
+
+1. **"Which routing mode?"** (free/cheap/good/genius) - Default: `good`
+2. **"Allow free models in fallback?"** - Default: `yes`
+3. **"Specific harness/model preference?"** - Default: `auto`
+
+Record the answer in spec.md metadata:
+```
+**Routing Preference**: auto: good | allow free: yes
+<!-- Options: auto: free|cheap|good|genius | allow free: yes|no | OR specific: harness/model -->
+```
 
 ---
 
@@ -43,6 +84,7 @@ This will output JSON with:
 1. Read `relentless/constitution.md` for project governance
 2. Note any MUST/SHOULD rules that apply to specifications
 3. Keep these principles in mind while generating the spec
+4. **Pay special attention to TDD requirements** - all features must be testable
 
 ---
 
@@ -58,30 +100,38 @@ Using the template at `templates/spec.md`, create a specification with:
 - Problem being solved
 
 **2. User Scenarios & Testing**
-- Concrete user stories
+- Concrete user stories with priorities (P1, P2, P3...)
 - Step-by-step flows
 - Expected outcomes
+- **Given/When/Then acceptance scenarios (MANDATORY)**
+- **Independent testability explanation for each story**
 
 **3. Functional Requirements**
 - What the system must do
 - Testable requirements (no implementation details)
 - Clear success criteria
 
-**4. Success Criteria**
+**4. Test Strategy (MANDATORY)**
+- Unit test approach
+- Integration test scenarios
+- Edge case tests
+- Test data requirements
+
+**5. Success Criteria**
 - Measurable, technology-agnostic outcomes
 - Quantitative metrics (time, performance, volume)
 - Qualitative measures (user satisfaction, task completion)
 
-**5. Key Entities (if applicable)**
+**6. Key Entities (if applicable)**
 - Data models and relationships
 - Fields and types (logical, not implementation)
 
-**6. Dependencies & Assumptions**
+**7. Dependencies & Assumptions**
 - External systems required
 - Prerequisites
 - Assumptions made
 
-**7. Out of Scope**
+**8. Out of Scope**
 - What this feature explicitly does NOT include
 - Future considerations
 
@@ -90,11 +140,12 @@ Using the template at `templates/spec.md`, create a specification with:
 ## Step 4: Handle Ambiguities
 
 If aspects are unclear:
-- Make informed guesses based on context
+- Interview the user first with questions to clarify any doubts, concerns or about his opinion on eventual ideas to improve the feature.
 - Only mark `[NEEDS CLARIFICATION: specific question]` if:
   - Choice significantly impacts scope or UX
   - Multiple reasonable interpretations exist
   - No reasonable default exists
+  - Question not already solved by interview
 - **LIMIT: Maximum 3 clarifications**
 
 If clarifications needed, present to user:
@@ -120,6 +171,7 @@ Your choice: _
 
 Check the specification against:
 
+### General Quality
 - [ ] No implementation details (languages, frameworks, APIs)
 - [ ] Focused on user value and business needs
 - [ ] All requirements are testable
@@ -129,6 +181,16 @@ Check the specification against:
 - [ ] Scope clearly bounded
 - [ ] No more than 3 `[NEEDS CLARIFICATION]` markers
 
+### TDD Readiness (MANDATORY)
+- [ ] Every user story has Given/When/Then acceptance criteria
+- [ ] Acceptance criteria are specific enough to write tests against
+- [ ] Edge cases are documented for test coverage
+- [ ] Test strategy section is complete
+
+### Routing Compliance
+- [ ] Routing preference is recorded in metadata
+- [ ] Routing choice is reasonable for feature complexity
+
 If validation fails, revise and re-check (max 3 iterations).
 
 ---
@@ -143,8 +205,9 @@ If validation fails, revise and re-check (max 3 iterations).
    started: DATE
    last_updated: DATE
    stories_completed: 0
+   routing_preference: [auto: mode | allow free: yes/no]
    ---
-   
+
    # Progress Log: FEATURE_NAME
    ```
 
@@ -152,6 +215,8 @@ If validation fails, revise and re-check (max 3 iterations).
    - Branch created: `BRANCH_NAME`
    - Spec saved: `SPEC_FILE`
    - Quality validation: PASSED/FAILED
+   - TDD readiness: PASSED/FAILED
+   - Routing preference: [recorded value]
    - Next step: `/relentless.plan` or `/relentless.clarify`
 
 ---
@@ -161,20 +226,25 @@ If validation fails, revise and re-check (max 3 iterations).
 ```markdown
 # Feature: User Authentication
 
+**Routing Preference**: auto: good | allow free: yes
+
 ## Overview
 Enable users to create accounts and log in securely using email/password.
 
 ## User Scenarios
 
-### Scenario 1: New User Registration
-1. User visits signup page
-2. Enters email and password
-3. Submits form
-4. Receives confirmation email
-5. Clicks confirmation link
-6. Account is activated
+### User Story 1: New User Registration (Priority: P1)
+
+User visits signup page, enters email and password, and creates an account.
 
-**Expected Outcome:** User has active account and can log in.
+**Why this priority**: Core functionality, blocks all other auth features.
+
+**Independent Test**: Can be fully tested by registering a new account and verifying the account exists.
+
+**Acceptance Scenarios**:
+
+1. **Given** a visitor on the signup page, **When** they submit valid email and password, **Then** the account is created and confirmation email sent
+2. **Given** an email already in use, **When** visitor tries to register, **Then** error message shown without revealing account exists
 
 ## Functional Requirements
 
@@ -183,6 +253,27 @@ Enable users to create accounts and log in securely using email/password.
 **REQ-3:** System must send confirmation email within 1 minute
 **REQ-4:** System must hash passwords before storage
 
+## Test Strategy (MANDATORY)
+
+### Unit Test Approach
+- Email validation logic
+- Password strength validation
+- Password hashing utility
+
+### Integration Test Scenarios
+- Full registration flow (submit form → create account → send email)
+- Duplicate email rejection
+
+### Edge Case Tests
+- Invalid email formats (missing @, invalid domain)
+- Password too short
+- Unicode in email/password
+
+### Test Data Requirements
+- Valid test email addresses
+- Various invalid email formats
+- Password examples at boundary conditions
+
 ## Success Criteria
 
 1. 95% of signups complete within 60 seconds
@@ -218,3 +309,4 @@ Enable users to create accounts and log in securely using email/password.
 - Validate before marking complete
 - Keep specification technology-agnostic
 - Focus on WHAT, not HOW
+- **TDD readiness is non-negotiable** - all acceptance criteria must be testable

package/.claude/skills/specify/templates/spec.md

@@ -1,9 +1,11 @@
 # Feature Specification: [FEATURE NAME]
 
-**Feature Branch**: `[###-feature-name]`  
-**Created**: [DATE]  
-**Status**: Draft  
+**Feature Branch**: `[###-feature-name]`
+**Created**: [DATE]
+**Status**: Draft
 **Input**: User description: "$ARGUMENTS"
+**Routing Preference**: auto: good | allow free: yes
+<!-- Options: auto: free|cheap|good|genius | allow free: yes|no | OR specific: harness/model -->
 
 ## User Scenarios & Testing *(mandatory)*
 
@@ -11,13 +13,16 @@
   IMPORTANT: User stories should be PRIORITIZED as user journeys ordered by importance.
   Each user story/journey must be INDEPENDENTLY TESTABLE - meaning if you implement just ONE of them,
   you should still have a viable MVP (Minimum Viable Product) that delivers value.
-  
+
   Assign priorities (P1, P2, P3, etc.) to each story, where P1 is the most critical.
   Think of each story as a standalone slice of functionality that can be:
   - Developed independently
   - Tested independently
   - Deployed independently
   - Demonstrated to users independently
+
+  TDD REQUIREMENT: All acceptance scenarios MUST be in Given/When/Then format
+  to enable direct test implementation.
 -->
 
 ### User Story 1 - [Brief Title] (Priority: P1)
@@ -70,6 +75,7 @@
 <!--
   ACTION REQUIRED: The content in this section represents placeholders.
   Fill them out with the right edge cases.
+  Edge cases are critical for TDD - they define boundary conditions to test.
 -->
 
 - What happens when [boundary condition]?
@@ -80,12 +86,13 @@
 <!--
   ACTION REQUIRED: The content in this section represents placeholders.
   Fill them out with the right functional requirements.
+  Each requirement must be TESTABLE - ask "how would I verify this?"
 -->
 
 ### Functional Requirements
 
 - **FR-001**: System MUST [specific capability, e.g., "allow users to create accounts"]
-- **FR-002**: System MUST [specific capability, e.g., "validate email addresses"]  
+- **FR-002**: System MUST [specific capability, e.g., "validate email addresses"]
 - **FR-003**: Users MUST be able to [key interaction, e.g., "reset their password"]
 - **FR-004**: System MUST [data requirement, e.g., "persist user preferences"]
 - **FR-005**: System MUST [behavior, e.g., "log all security events"]
@@ -100,6 +107,34 @@
 - **[Entity 1]**: [What it represents, key attributes without implementation]
 - **[Entity 2]**: [What it represents, relationships to other entities]
 
+## Test Strategy (MANDATORY)
+
+<!--
+  TDD REQUIREMENT: This section is mandatory and must be completed before implementation.
+  Tests are written BEFORE implementation code in Relentless.
+-->
+
+### Unit Test Approach
+
+- [Business logic to test - e.g., "validation functions", "calculations", "transformations"]
+- [Data processing to test - e.g., "parsers", "formatters", "serializers"]
+
+### Integration Test Scenarios
+
+- [API flow to test - e.g., "full registration flow", "checkout process"]
+- [Data flow to test - e.g., "database operations", "cache interactions"]
+
+### Edge Case Tests
+
+- [Boundary condition - e.g., "empty input", "maximum length"]
+- [Error condition - e.g., "network failure", "invalid format"]
+- [Race condition - e.g., "concurrent requests", "duplicate submissions"]
+
+### Test Data Requirements
+
+- [Fixtures needed - e.g., "sample users", "mock responses"]
+- [Edge case data - e.g., "unicode strings", "very long inputs"]
+
 ## Success Criteria *(mandatory)*
 
 <!--

package/.claude/skills/tasks/SKILL.md

@@ -16,11 +16,28 @@ Generate actionable, dependency-ordered user stories from technical plans.
 3. Break down into implementation tasks
 4. Order by dependencies
 5. Create tasks.md with structured user stories
+6. **Auto-convert to prd.json** with routing classification
 
 **Important:** tasks.md contains the actual user stories that convert to prd.json!
 
 ---
 
+## SpecKit Workflow
+
+This skill is **Step 3 of 5** in the Relentless workflow:
+
+```
+specify → plan → tasks → analyze → implement
+                   ↓
+            (optional: checklist)
+```
+
+This skill now **auto-runs convert** at the end, generating prd.json.
+Manual convert is only needed if tasks.md is edited manually.
+Checklist is optional but recommended for complex features.
+
+---
+
 ## Step 1: Locate Feature Files
 
 Find the current feature directory and verify:
@@ -37,6 +54,8 @@ Read:
 2. `relentless/features/NNN-feature/spec.md` - User requirements
 3. `relentless/features/NNN-feature/plan.md` - Technical design
 
+Extract **Routing Preference** from spec.md or plan.md (if present) and include it near the top of tasks.md so it can be carried into prd.json.
+
 ---
 
 ## Step 3: Extract User Stories
@@ -132,6 +151,7 @@ For each user story, create implementation tasks using format:
 **Phase:** Stories
 **Priority:** 3
 ```
+If you have any doubts or suggestions about any specific task, interview the user about them to improve your execution.
 
 ---
 
@@ -170,7 +190,61 @@ Check that:
    - Total user stories: N
    - Dependency order: [list]
    - Parallel opportunities: N
-   - Next step: `/relentless.checklist` or `relentless convert tasks.md`
+
+---
+
+## Step 8: Auto-Convert to prd.json
+
+After tasks.md is saved, automatically convert to prd.json with routing:
+
+```bash
+relentless convert relentless/features/NNN-feature/tasks.md --feature <feature-name>
+```
+
+This will:
+1. Parse tasks.md and validate structure
+2. Classify complexity for each story
+3. Route to optimal harness/model per story
+4. Generate prd.json with routing metadata
+5. Copy to prd.md for reference
+
+**Output Summary:**
+- Show routing table (story → complexity → harness/model → cost)
+- Show total estimated cost
+- Confirm prd.json saved
+
+**Optional but Recommended:** `/relentless.checklist`
+- Generates validation checklist with quality gates
+- Helps ensure nothing is missed during implementation
+- Especially useful for complex features
+
+**Next Step:** `/relentless.analyze` (or `/relentless.checklist` first if desired)
+
+---
+
+## TDD is MANDATORY
+
+Every user story MUST include test acceptance criteria:
+
+1. **Unit Tests** - For business logic and utilities
+2. **Integration Tests** - For API endpoints and data flows
+3. **E2E Tests** - For user-facing flows (use Playwright when applicable)
+
+### TDD Workflow
+
+The Relentless agent will verify:
+1. Tests are written FIRST (before implementation)
+2. Tests FAIL before implementation
+3. Implementation makes tests PASS
+4. Typecheck and lint pass
+
+### Required Test Criteria
+
+Every story acceptance criteria should include:
+- [ ] Unit tests pass
+- [ ] Integration test passes (for API stories)
+- [ ] Typecheck passes
+- [ ] Lint passes
 
 ---
 
@@ -186,6 +260,7 @@ Check that:
 - No vague terms ("works well", "good UX")
 - Include quality checks (typecheck, lint, test)
 - Verifiable in browser/tests
+- **MUST include test criteria**
 
 **Dependencies:**
 - Only list direct dependencies

package/.claude/skills/tasks/templates/tasks.md

@@ -7,8 +7,9 @@ description: "Task list template for feature implementation"
 
 **Input**: Design documents from `/specs/[###-feature-name]/`
 **Prerequisites**: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/
+**Routing Preference**: [auto: good | allow free: yes | harness/model]
 
-**Tests**: The examples below include test tasks. Tests are OPTIONAL - only include them if explicitly requested in the feature specification.
+**Tests**: Tests are MANDATORY. Every story MUST include test acceptance criteria. TDD is required - write tests FIRST, verify they FAIL, then implement.
 
 **Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story.
 
@@ -79,7 +80,7 @@ Examples of foundational tasks (adjust based on your project):
 
 **Independent Test**: [How to verify this story works on its own]
 
-### Tests for User Story 1 (OPTIONAL - only if tests requested) ⚠️
+### Tests for User Story 1 (MANDATORY - TDD Required)
 
 > **NOTE: Write these tests FIRST, ensure they FAIL before implementation**
 
@@ -105,7 +106,7 @@ Examples of foundational tasks (adjust based on your project):
 
 **Independent Test**: [How to verify this story works on its own]
 
-### Tests for User Story 2 (OPTIONAL - only if tests requested) ⚠️
+### Tests for User Story 2 (MANDATORY - TDD Required)
 
 - [ ] T018 [P] [US2] Contract test for [endpoint] in tests/contract/test_[name].py
 - [ ] T019 [P] [US2] Integration test for [user journey] in tests/integration/test_[name].py
@@ -127,7 +128,7 @@ Examples of foundational tasks (adjust based on your project):
 
 **Independent Test**: [How to verify this story works on its own]
 
-### Tests for User Story 3 (OPTIONAL - only if tests requested) ⚠️
+### Tests for User Story 3 (MANDATORY - TDD Required)
 
 - [ ] T024 [P] [US3] Contract test for [endpoint] in tests/contract/test_[name].py
 - [ ] T025 [P] [US3] Integration test for [user journey] in tests/integration/test_[name].py