@arvorco/relentless 0.3.1 → 0.4.2

package/.claude/skills/checklist/templates/checklist.md

@@ -6,31 +6,60 @@
 
 **Note**: This checklist is generated by the `/relentless.checklist` command based on feature context and requirements.
 
-<!-- 
+<!--
   ============================================================================
   IMPORTANT: The checklist items below are SAMPLE ITEMS for illustration only.
-  
+
   The /relentless.checklist command MUST replace these with actual items based on:
   - User's specific checklist request
   - Feature requirements from spec.md
   - Technical context from plan.md
   - Implementation details from tasks.md
-  
+
+  MANDATORY SECTIONS (must always be included):
+  - 0. Quality Gates - typecheck, lint, test
+  - 1. TDD Compliance - tests before code
+  - 2. Routing Compliance - metadata validation
+
   DO NOT keep these sample items in the generated checklist file.
   ============================================================================
 -->
 
-## [Category 1]
+## 0. Quality Gates (MANDATORY - Every Story)
+
+- [ ] CHK-001 `bun run typecheck` passes with 0 errors
+- [ ] CHK-002 `bun run lint` passes with 0 errors AND 0 warnings
+- [ ] CHK-003 `bun test` passes
+- [ ] CHK-004 No debug code (console.log, debugger statements)
+- [ ] CHK-005 No unused imports or variables
+
+## 1. TDD Compliance (MANDATORY)
+
+- [ ] CHK-006 Tests written BEFORE implementation code
+- [ ] CHK-007 Tests verified to FAIL before writing implementation
+- [ ] CHK-008 Unit test coverage ≥80%
+- [ ] CHK-009 Integration tests for all API endpoints
+- [ ] CHK-010 E2E tests for complete user flows
+
+## 2. Routing Compliance (MANDATORY)
+
+- [ ] CHK-011 Routing preference documented in spec.md
+- [ ] CHK-012 prd.json has routing metadata for all stories
+- [ ] CHK-013 Complexity classifications correct for story scope
+- [ ] CHK-014 Estimated costs are reasonable
+- [ ] CHK-015 Mode selection appropriate for complexity
+
+## [Category 3]
 
-- [ ] CHK001 First checklist item with clear action
-- [ ] CHK002 Second checklist item
-- [ ] CHK003 Third checklist item
+- [ ] CHK-016 First checklist item with clear action [US-XXX]
+- [ ] CHK-017 Second checklist item [US-XXX]
+- [ ] CHK-018 Third checklist item [US-XXX]
 
-## [Category 2]
+## [Category 4]
 
-- [ ] CHK004 Another category item
-- [ ] CHK005 Item with specific criteria
-- [ ] CHK006 Final item in this category
+- [ ] CHK-019 Another category item [US-XXX]
+- [ ] CHK-020 Item with specific criteria [US-XXX]
+- [ ] CHK-021 Final item in this category [US-XXX]
 
 ## Notes
 
@@ -38,3 +67,6 @@
 - Add comments or findings inline
 - Link to relevant resources or documentation
 - Items are numbered sequentially for easy reference
+- **Quality Gates, TDD, and Routing sections are mandatory**
+- Reference user stories with `[US-XXX]` tags
+- Mark gaps with `[Gap]` and ambiguities with `[Ambiguity]`

package/.claude/skills/clarify/SKILL.md

@@ -9,10 +9,42 @@ Systematically identify and resolve ambiguities in feature specifications.
 
 ---
 
+## SpecKit Workflow
+
+Clarify can be invoked at any stage when ambiguities arise:
+
+specify ↔ **clarify** ↔ plan ↔ **clarify** ↔ tasks
+
+The skill helps resolve ambiguities that could affect:
+- **Test design** (unclear acceptance criteria)
+- **Routing decisions** (unclear complexity)
+- **Implementation choices** (unclear requirements)
+
+---
+
+## Testability Requirements
+
+When clarifying requirements, ensure answers are:
+- **Specific enough to write tests against**
+- **Measurable** (can verify with automated tests)
+- **Unambiguous** (no multiple interpretations)
+
+### Good vs Bad Clarifications
+
+| Bad (vague) | Good (testable) |
+|-------------|-----------------|
+| "How should validation work?" | "Should email validation reject 'user@localhost'?" |
+| "What about error handling?" | "Should invalid password show 'Invalid credentials' or 'Password too short'?" |
+| "How secure should it be?" | "Should we require 2FA for admin users?" |
+
+**Every clarification should result in a testable requirement.**
+
+---
+
 ## The Job
 
 1. Read spec.md
-2. Scan for 9 types of ambiguities
+2. Scan for 10 types of ambiguities (including testability)
 3. Present clarification questions to user
 4. Update spec with answers
 5. Save clarification log
@@ -27,7 +59,7 @@ Read `relentless/features/NNN-feature/spec.md`
 
 ## Step 2: Scan for Ambiguities
 
-Check for these 9 types:
+Check for these 10 types:
 
 **1. Behavioral Ambiguities**
 - What happens when [action]?
@@ -75,6 +107,24 @@ Check for these 9 types:
 - Race conditions?
 - Example: "What if two users register with same email simultaneously?"
 
+**10. Testability Ambiguities (NEW)**
+- Are acceptance criteria specific enough to test?
+- What edge cases need test coverage?
+- What test data/fixtures are required?
+- What should unit vs integration tests cover?
+- Example: "Should we test with unicode characters in email addresses?"
+
+---
+
+## Optional: Clarify Routing Preference
+
+If routing preference is unclear or missing from spec, ask:
+- "Is this feature simple, medium, complex, or expert-level?"
+- "Should it use free/cheap/good/genius models?"
+- "Any specific AI model requirements?"
+
+Record the answer and update spec.md metadata.
+
 ---
 
 ## Step 3: Present Questions
@@ -88,10 +138,12 @@ For each ambiguity found (max 5 most critical):
 
 **What we need to know:** [Specific question]
 
+**Testability Impact:** [How this affects test design]
+
 **Options:**
-A. [Option 1] - [Implications]
-B. [Option 2] - [Implications]
-C. [Option 3] - [Implications]
+A. [Option 1] - [Implications + how to test]
+B. [Option 2] - [Implications + how to test]
+C. [Option 3] - [Implications + how to test]
 D. Custom - [Your answer]
 
 **Your choice:** _
@@ -105,6 +157,7 @@ After receiving answers:
 1. Update spec.md with clarifications
 2. Remove `[NEEDS CLARIFICATION]` markers
 3. Add concrete details based on answers
+4. **Ensure updated requirements are testable (Given/When/Then)**
 
 ---
 
@@ -120,6 +173,7 @@ Create `relentless/features/NNN-feature/clarification-log.md`:
 **Question:** [Question]
 **Answer:** [User's choice]
 **Updated Sections:** [List spec sections updated]
+**Test Impact:** [What tests can now be written]
 
 ## Q2: [Topic] - DEFERRED
 **Date:** 2026-01-11
@@ -138,10 +192,12 @@ Create `relentless/features/NNN-feature/clarification-log.md`:
 
 **What we need to know:** What are the specific password requirements?
 
+**Testability Impact:** Need exact rules to write validation tests.
+
 **Options:**
-A. Basic (min 8 characters) - Simple, user-friendly
-B. Moderate (min 8 chars + number + symbol) - Balanced security
-C. Strict (min 12 chars + number + symbol + upper/lower) - High security
+A. Basic (min 8 characters) - Simple, user-friendly. Test: reject 7 chars, accept 8.
+B. Moderate (min 8 chars + number + symbol) - Balanced security. Test: reject "password", accept "Pass1!"
+C. Strict (min 12 chars + number + symbol + upper/lower) - High security. Test: comprehensive regex.
 D. Custom - Define your own rules
 
 **Your choice:** B
@@ -154,10 +210,12 @@ D. Custom - Define your own rules
 
 **What we need to know:** How should we handle repeated failed logins?
 
+**Testability Impact:** Need exact limits to write rate limiting tests.
+
 **Options:**
-A. No limit - Allow unlimited attempts
-B. Rate limit - Max 5 attempts per minute per IP
-C. Account lockout - Lock account after 5 failed attempts for 30 minutes
+A. No limit - Allow unlimited attempts. Test: N/A (no limit to test)
+B. Rate limit - Max 5 attempts per minute per IP. Test: 6th attempt in 60s fails.
+C. Account lockout - Lock account after 5 failed attempts for 30 minutes. Test: verify lockout and unlock timing.
 D. Custom - Define your own approach
 
 **Your choice:** C
@@ -172,3 +230,4 @@ D. Custom - Define your own approach
 - Some ambiguities can be deferred to implementation
 - Update spec immediately after clarification
 - Keep clarification log for future reference
+- **Every resolved ambiguity should enable writing tests**

package/.claude/skills/constitution/SKILL.md

@@ -21,6 +21,52 @@ Create a personalized project constitution that defines your team's coding princ
 
 ---
 
+## Upgrade Detection (For Existing Users)
+
+If `relentless/constitution.md` and/or `relentless/prompt.md` already exist:
+
+### Step 0: Check for Template Updates
+
+1. **Read current files:**
+   - Check version in existing constitution.md (look for `<!-- TEMPLATE_VERSION: X.Y.Z -->` or `**Template Version:**`)
+   - Check generated date in existing prompt.md
+
+2. **Compare with templates:**
+   - Read `.claude/skills/constitution/templates/constitution.md`
+   - Read `.claude/skills/constitution/templates/prompt.md`
+   - Check template VERSION comments for changes
+
+3. **Detect changes:**
+   - If template version > existing version → Offer upgrade
+   - If template has new sections → Offer selective merge
+   - If quality commands changed → Offer prompt.md refresh
+
+4. **Offer upgrade options:**
+   ```markdown
+   ## Upgrade Available
+
+   Your constitution.md is v2.0.0, template is v2.1.0.
+
+   Changes in v2.1.0:
+   - Added SpecKit workflow documentation
+   - Enhanced TDD requirements
+   - Added quality gates section
+
+   Options:
+   A. Full upgrade (backup existing, apply template changes)
+   B. Selective merge (show diff, choose sections)
+   C. Skip upgrade (keep existing)
+   D. Regenerate from scratch (lose customizations)
+   ```
+
+5. **If upgrading:**
+   - Backup existing files to `*.backup`
+   - Apply template changes preserving customizations
+   - Update version number
+   - Update `LAST_AMENDED_DATE` to today
+
+---
+
 ## Step 1: Gather Project Information
 
 Ask essential questions about the project:
@@ -92,6 +138,8 @@ Read and analyze project documentation:
 
 Load the base template from `templates/prompt.md` and personalize it:
 
+**Must include spec/plan/tasks awareness** so the agent reads `spec.md` and `plan.md` in full before execution, and reads only the relevant user story section from `tasks.md` for the current story.
+
 **Base Template Location:** `templates/prompt.md`
 
 Create a personalized `prompt.md` with:
@@ -123,12 +171,22 @@ Before marking ANY story as complete:
 - Database/backend info
 - Styling approach
 
-**Section 3: TDD Workflow** (if tests exist)
-- Test-first workflow
+**Section 3: TDD Workflow** (MANDATORY)
+- Test-first workflow (write tests BEFORE implementation)
 - Test location patterns
 - Test commands
+- Verification that tests FAIL before implementation
+
+**Section 4: Routing Awareness**
+- Explanation of routing metadata in prd.json
+- Complexity levels (simple/medium/complex/expert)
+- Cost optimization modes (free/cheap/good/genius)
+
+**Section 5: SpecKit Workflow**
+- Full workflow: specify → plan → tasks → convert → analyze → implement
+- Artifact awareness: spec.md, plan.md, tasks.md, checklist.md, prd.json
 
-**Section 4: Common Pitfalls** (from AGENTS.md/docs)
+**Section 6: Common Pitfalls** (from AGENTS.md/docs)
 - Project-specific gotchas
 - Known issues
 - Best practices