@arvorco/relentless 0.4.2 → 0.4.3

package/.claude/skills/checklist/SKILL.md

@@ -13,7 +13,7 @@ Generate domain-specific quality checklists to validate implementation completen
 
 This skill runs **after tasks, before analyze**:
 
-specify → plan → tasks → convert → **checklist** → analyze → implement
+specify → plan → tasks → **checklist** → analyze → implement
 
 Purpose:
 - Generate validation checklist from spec/plan/tasks
@@ -118,6 +118,7 @@ Create 7-10 categories based on feature domain:
 - Performance & UX
 - Documentation
 
+If you have any doubts or suggestions about the checklist, please, interview the user.
 ---
 
 ## Step 4: Generate Checklist Items

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

@@ -13,7 +13,7 @@ Create detailed technical plans that translate feature specifications into imple
 
 This skill is **Step 2 of 6** in the Relentless workflow:
 
-specify → **plan** → tasks → convert → analyze → implement
+specify → **plan** → tasks → analyze → implement
 
 What flows from spec:
 - User requirements → technical approach
@@ -157,6 +157,8 @@ Before completing the plan, validate:
 
 If plan violates MUST rules, revise until compliant.
 
+If plan generates any doubts, interview the user about them with insightful questions to improve the plan.
+
 ---
 
 ## Step 6: Save & Report
@@ -284,5 +286,6 @@ tests/
 - Include specific technologies and patterns
 - Must comply with constitution
 - Detailed enough for task generation
+- Interview user if you have any doubts or suggestions
 - **Test specifications are mandatory** - no tests = incomplete plan
 - **Routing preference must be carried forward** from spec

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

@@ -13,7 +13,7 @@ Create structured feature specifications from natural language descriptions.
 
 This skill is **Step 1 of 6** in the Relentless workflow:
 
-**specify** → plan → tasks → convert → analyze → implement
+**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
@@ -140,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:

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

@@ -151,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.
 
 ---
 

package/CHANGELOG.md

@@ -7,7 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [0.4.0] - 2026-01-20
+## [0.4.3] - 2026-01-20
+
+### Fixed
+- **Parser**: Extract only valid story IDs (US-XXX) from dependency annotations (#4 - thanks @aruj0!)
+  - `"US-001 (auth must work first)"` now correctly extracts `US-001`
+  - `"None (foundational)"` and `"Phase 5"` no longer cause errors
+- **Parser**: Section boundary fix prevents content from `## Implementation Tasks` bleeding into last story
+
+### Changed
+- **Constitution v2.1.0**: Added SpecKit Workflow as Principle 1 (now 16 principles total)
+- **SpecKit Workflow**: Added user interview/feedback step for better requirement gathering
+- **Skills updated**: plan, tasks, specify, checklist - improved TDD and workflow guidance
+- **README**: Revised for clarity and updated command examples
+- **prompt.md**: Refreshed with template version tracking and improved structure
+
+### Documentation
+- Constitution now includes template version header for upgrade tracking
+- Added explicit 6-step workflow documentation: specify → plan → tasks → convert → analyze → implement
+
+## [0.4.2] - 2026-01-20
 
 ### Major Features
 
@@ -392,7 +411,9 @@ Relentless evolved from the [Ralph Wiggum Pattern](https://ghuntley.com/ralph/)
 - **License**: MIT
 - **Inspiration**: [Ralph Wiggum Pattern](https://ghuntley.com/ralph/) by Geoffrey Huntley
 
-[Unreleased]: https://github.com/ArvorCo/Relentless/compare/v0.4.0...HEAD
+[Unreleased]: https://github.com/ArvorCo/Relentless/compare/v0.4.3...HEAD
+[0.4.3]: https://github.com/ArvorCo/Relentless/compare/v0.4.2...v0.4.3
+[0.4.2]: https://github.com/ArvorCo/Relentless/compare/v0.4.0...v0.4.2
 [0.4.0]: https://github.com/ArvorCo/Relentless/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/ArvorCo/Relentless/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/ArvorCo/Relentless/compare/v0.1.27...v0.2.0

package/README.md

@@ -424,7 +424,7 @@ Relentless uses a simplified 5-step SpecKit workflow:
 ### Core Commands
 
 ```bash
-relentless init                              # Initialize project
+relentless init                              # Initialize project; -f if upgrading to force overwrite
 relentless run --feature <name> --tui        # Run orchestration
 relentless status --feature <name>           # Show progress
 relentless reset <story-id> --feature <name> # Re-run a story
@@ -460,7 +460,7 @@ relentless agents list                       # Show installed agents
 relentless agents doctor                     # Health check
 ```
 
-### Slash Commands (Claude/Amp/OpenCode)
+### Slash Commands (Claude/Amp/OpenCode/Codex/Droid)
 
 ```bash
 /relentless.constitution    # Create project rules + prompt.md
@@ -569,11 +569,12 @@ Each iteration has access to:
 - **progress.txt** — YAML metadata + learnings
 - **prd.json** — Task completion status
 - **constitution.md** — Project rules
+- **spec.md**, **plan.md** and **tasks.md** - Feature specification and task definition files
 - **checklist.md** — Quality validation (now included in prompts!)
 
 ---
 
-## Writing Good PRDs
+## Writing Good Specs
 
 ### Right-Sized Stories
 
@@ -597,6 +598,8 @@ Make criteria **verifiable**:
 - `Tests pass` in every story
 - `Verify in browser` for UI stories
 
+**ALWAYS REVIEW YOUR SPECS, PLANS AND PRD FILES!**
+
 ---
 
 ## Troubleshooting
@@ -624,7 +627,7 @@ A: Estimates include a 12% buffer for potential escalation. Actual costs may be
 A: Yes, set `autoMode.escalation.enabled: false` in config. Tasks will fail instead of escalating.
 
 **Q: Which mode should I use?**
-A: Start with `good` (default). Use `cheap` for well-defined tasks. Use `genius` for complex architecture. Use `free` only for experimentation.
+A: Start with `good` (default). Use `cheap` for well-defined tasks. Use `genius` for complex architecture. Use `free` only for experimentation and simple tasks, like translation, documentation, change variable names etc.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arvorco/relentless",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "Universal AI agent orchestrator - works with Claude Code, Amp, OpenCode, Codex, Droid, and Gemini",
   "type": "module",
   "publishConfig": {

package/relentless/config.json

@@ -36,7 +36,7 @@
     "path": "prompt.md"
   },
   "autoMode": {
-    "enabled": true,
+    "enabled": false,
     "defaultMode": "good",
     "fallbackOrder": [
       "claude",
@@ -79,4 +79,4 @@
       }
     }
   }
-}
+}

package/relentless/constitution.md

@@ -1,8 +1,11 @@
+<!-- TEMPLATE_VERSION: 2.1.0 -->
+<!-- LAST_UPDATED: 2026-01-20 -->
+
 # Relentless Project Constitution
 
-**Version:** 2.0.0
+**Version:** 2.1.0
 **Ratified:** 2026-01-13
-**Last Amended:** 2026-01-13
+**Last Amended:** 2026-01-20
 
 ---
 
@@ -27,7 +30,25 @@ Our mission is to build one of the best AI orchestration tools in the world - si
 
 ## Part I: Foundational Principles
 
-### Principle 1: Test-Driven Development (TDD)
+### Principle 1: SpecKit Workflow
+
+**MUST:**
+- All features MUST follow the 6-step workflow: specify → plan → tasks → convert → analyze → implement
+- Each step MUST produce its corresponding artifact before proceeding
+- Artifacts MUST be validated with `/relentless.analyze` before implementation begins
+- Implementation MUST NOT start without: spec.md, plan.md, tasks.md, checklist.md, prd.json
+
+**SHOULD:**
+- Run analysis after any manual artifact edits
+- Keep artifacts in sync throughout development
+- Document deviations from plan in progress.txt
+- Review checklist.md before completing each story
+
+**Rationale:** The SpecKit workflow ensures thorough planning, prevents scope creep, and provides structured guidance for AI agents. Each artifact serves a specific purpose in the autonomous execution pipeline.
+
+---
+
+### Principle 2: Test-Driven Development (TDD)
 
 **MUST:**
 - All new features MUST have tests written BEFORE implementation begins
@@ -46,7 +67,7 @@ Our mission is to build one of the best AI orchestration tools in the world - si
 
 ---
 
-### Principle 2: Smart Model Routing
+### Principle 3: Smart Model Routing
 
 **MUST:**
 - Planning phase MUST evaluate task complexity before assigning models
@@ -66,7 +87,7 @@ Our mission is to build one of the best AI orchestration tools in the world - si
 
 ---
 
-### Principle 3: Parallel Execution with Git Worktrees
+### Principle 4: Parallel Execution with Git Worktrees
 
 **MUST:**
 - Parallel tasks MUST use git worktrees for clean isolation
@@ -86,7 +107,7 @@ Our mission is to build one of the best AI orchestration tools in the world - si
 
 ---
 
-### Principle 4: Queued Prompts (Mid-Run Input)
+### Principle 5: Queued Prompts (Mid-Run Input)
 
 **MUST:**
 - Implement file-based queue (.queue.txt) for mid-run user input
@@ -105,7 +126,7 @@ Our mission is to build one of the best AI orchestration tools in the world - si
 
 ---
 
-### Principle 5: Adaptive Final Review
+### Principle 6: Adaptive Final Review
 
 **MUST:**
 - Every feature MUST have a final review phase before completion
@@ -126,7 +147,7 @@ Our mission is to build one of the best AI orchestration tools in the world - si
 
 ---
 
-### Principle 6: Agent-Aware Best Practices
+### Principle 7: Agent-Aware Best Practices
 
 **MUST:**
 - Maintain up-to-date knowledge of each agent's capabilities
@@ -147,7 +168,7 @@ Our mission is to build one of the best AI orchestration tools in the world - si
 
 ## Part II: Code Quality Standards
 
-### Principle 7: Zero-Lint Policy
+### Principle 8: Zero-Lint Policy
 
 **MUST:**
 - All code MUST pass lint with zero warnings (not just errors)
@@ -165,7 +186,7 @@ Our mission is to build one of the best AI orchestration tools in the world - si
 
 ---
 
-### Principle 8: TypeScript Strictness
+### Principle 9: TypeScript Strictness
 
 **MUST:**
 - Use TypeScript strict mode throughout
@@ -184,7 +205,7 @@ Our mission is to build one of the best AI orchestration tools in the world - si
 
 ---
 
-### Principle 9: Minimal Dependencies
+### Principle 10: Minimal Dependencies
 
 **MUST NOT:**
 - Add dependencies without clear justification
@@ -207,7 +228,7 @@ Our mission is to build one of the best AI orchestration tools in the world - si
 
 ## Part III: Architecture Principles
 
-### Principle 10: Clean Architecture
+### Principle 11: Clean Architecture
 
 **MUST:**
 - Maintain clear separation of concerns
@@ -225,7 +246,7 @@ Our mission is to build one of the best AI orchestration tools in the world - si
 
 ---
 
-### Principle 11: Performance First
+### Principle 12: Performance First
 
 **MUST:**
 - Maintain fast startup time (<1s)
@@ -243,7 +264,7 @@ Our mission is to build one of the best AI orchestration tools in the world - si
 
 ---
 
-### Principle 12: Error Handling Excellence
+### Principle 13: Error Handling Excellence
 
 **MUST:**
 - Surface errors clearly - never hide failures
@@ -263,7 +284,7 @@ Our mission is to build one of the best AI orchestration tools in the world - si
 
 ## Part IV: Version Control & Documentation
 
-### Principle 13: Git Discipline
+### Principle 14: Git Discipline
 
 **MUST:**
 - Write clear, descriptive commit messages
@@ -282,7 +303,7 @@ Our mission is to build one of the best AI orchestration tools in the world - si
 
 ---
 
-### Principle 14: Documentation Standards
+### Principle 15: Documentation Standards
 
 **MUST:**
 - Document public APIs and interfaces
@@ -302,7 +323,7 @@ Our mission is to build one of the best AI orchestration tools in the world - si
 
 ## Part V: Security & Compliance
 
-### Principle 15: Security First
+### Principle 16: Security First
 
 **MUST:**
 - Never commit secrets to git
@@ -371,6 +392,7 @@ The following are strategic directions that guide future development:
 
 | Version | Date | Changes |
 |---------|------|---------|
+| 2.1.0 | 2026-01-20 | Added SpecKit Workflow principle, template version tracking, renumbered principles (now 16 total), improved artifact consistency requirements |
 | 2.0.0 | 2026-01-13 | Major revision: Added smart routing, parallel execution, queued prompts, adaptive review, TDD requirements, agent-aware practices |
 | 1.0.0 | Previous | Initial constitution |
 

package/relentless/prompt.md

@@ -1,21 +1,40 @@
+<!-- TEMPLATE_VERSION: 2.1.0 -->
+<!-- LAST_UPDATED: 2026-01-20 -->
+
 # Relentless Agent Instructions
 
-You are an autonomous coding agent working on the Relentless project - a universal AI agent orchestrator.
+You are an autonomous coding agent orchestrated by Relentless - a universal AI agent orchestrator.
+
+---
+
+## Before Starting ANY Story
+
+**CRITICAL:** Read the feature artifacts in this order:
+
+1. **`spec.md`** - Read FULL file to understand requirements
+2. **`plan.md`** - Read FULL file to understand technical approach
+3. **`tasks.md`** - Read ONLY the section for your current story (US-XXX)
+4. **`checklist.md`** - Review quality criteria you must satisfy
+5. **`prd.json`** - Find your story and check routing metadata
+
+This context is essential. Do NOT skip reading these files.
 
 ---
 
-## SpecKit Workflow
+## SpecKit Workflow Reference
 
 Implementation is **Step 6 of 6** in the Relentless workflow:
 
-specify → plan → tasks → convert → analyze → **implement**
+```
+/relentless.specify → /relentless.plan → /relentless.tasks → /relentless.convert → /relentless.analyze → /relentless.implement
+```
 
-This prompt guides the implementation phase. Ensure all prerequisite artifacts exist:
+Each step generates an artifact in `relentless/features/<feature>/`:
 - `spec.md` - Feature specification (routing preference)
 - `plan.md` - Technical implementation plan (test specifications)
 - `tasks.md` - User stories with acceptance criteria
-- `prd.json` - Converted PRD with routing metadata
 - `checklist.md` - Quality validation checklist
+- `prd.json` - Machine-readable PRD with routing
 
 **Run `/relentless.analyze` before implementing to validate artifact consistency.**
 
@@ -45,34 +64,29 @@ bun test
 
 ---
 
-## Before You Start
-
-1. **Read the Constitution** - Review `relentless/constitution.md` for project principles
-2. **Review the Codebase** - Understand current state, architecture, and patterns
-3. **Read progress.txt** - Check the Codebase Patterns section for learnings from previous iterations
-4. **Read the spec/plan/tasks** - `spec.md`, `plan.md`, `tasks.md` for the feature
-5. **Read the PRD** - Understand what needs to be done
-6. **Check the Queue** - Look for `.queue.txt` for any mid-run user input
-7. **Verify Analysis Passed** - Run `/relentless.analyze` if not done
-
----
-
-## Your Task
-
-1. Read the PRD at `relentless/features/<feature>/prd.json`
-2. Read the progress log at `relentless/features/<feature>/progress.txt`
-3. Read `relentless/features/<feature>/spec.md`, `plan.md`, `tasks.md`, and `checklist.md` for full context
-4. Check you're on the correct branch from PRD `branchName`. If not, check it out or create from main.
-5. Pick the **highest priority** user story where `passes: false` and all dependencies are met
-6. **Review routing metadata** - Check story complexity and model assignment
-7. **Review relevant checklist items** - Find `[US-XXX]` tagged items for the story
-8. **Review relevant code** before implementing - understand existing patterns
+## Your Task (Per Iteration)
+
+1. Check you're on the correct branch from PRD `branchName`
+2. Read feature artifacts (spec.md, plan.md, your story in tasks.md)
+3. Pick the **highest priority** story where `passes: false` and dependencies met
+4. Check story routing metadata for complexity/model guidance
+5. Review checklist items tagged `[US-XXX]` for your story
+6. Review existing code to understand patterns
+7. **Write tests FIRST** (TDD is mandatory)
+8. Verify tests FAIL before implementation
+9. Implement the story to make tests PASS
+10. Run ALL quality checks (typecheck, lint, test)
+11. If ALL checks pass, commit: `feat: [Story ID] - [Story Title]`
+12. Update tasks.md: check off `- [x]` completed acceptance criteria
+13. Update checklist.md: check off `- [x]` verified items
+14. Update PRD: set `passes: true`
+15. Append progress to `progress.txt`
 
 ---
 
 ## TDD Workflow (MANDATORY)
 
-Relentless follows strict Test-Driven Development. For EVERY story:
+You MUST follow Test-Driven Development:
 
 ### Step 1: Write Failing Tests First (RED)
 ```bash
@@ -113,53 +127,42 @@ If the current story has `research: true` and no research file exists yet:
 
 ---
 
-## Implementation Phase
-
-If research findings exist (or research is not required):
+## Routing Awareness
 
-1. **Write tests first** (TDD - mandatory)
-2. Implement that single user story (using research findings if available)
-3. Run quality checks (typecheck, lint, test)
-4. If checks pass, commit ALL changes with message: `feat: [Story ID] - [Story Title]`
-5. Update `tasks.md` - check off completed acceptance criteria
-6. Update `checklist.md` - check off verified checklist items
-7. Update the PRD to set `passes: true` for the completed story
-8. Append your progress to `relentless/features/<feature>/progress.txt`
+Stories in `prd.json` may have routing metadata:
 
----
-
-## File Update Summary
+```json
+{
+  "routing": {
+    "complexity": "medium",
+    "harness": "claude",
+    "model": "sonnet-4.5",
+    "estimatedCost": 0.0034
+  }
+}
+```
 
-After completing each story, these files MUST be updated:
+**What this means:**
+- **complexity**: How hard the task is (simple/medium/complex/expert)
+- **harness/model**: Which AI was chosen for this task
+- **estimatedCost**: Pre-execution cost estimate
 
-| File | Update |
-|------|--------|
-| `tasks.md` | Check off `- [x]` completed acceptance criteria |
-| `checklist.md` | Check off `- [x]` verified checklist items |
-| `prd.json` | Set `"passes": true` for the story |
-| `progress.txt` | Append progress entry with learnings |
+After completion, execution history is saved for cost tracking.
 
 ---
 
-## Implementation Phases
-
-### Phase 0: Setup
-- Infrastructure, tooling, configuration
-- Usually US-001 type stories
+## Checklist Validation
 
-### Phase 1: Foundation
-- Data models, types, schemas
-- Base utilities and helpers
-- Core infrastructure
+Before completing a story, verify against `checklist.md`:
 
-### Phase 2: User Stories
-- Feature implementation
-- Follow dependency order strictly
-
-### Phase 3: Polish
-- E2E tests
-- Documentation
-- Performance optimization
+- [ ] All acceptance criteria from tasks.md satisfied
+- [ ] Tests written BEFORE implementation (TDD)
+- [ ] Tests passing
+- [ ] Typecheck passes (0 errors)
+- [ ] Lint passes (0 errors AND 0 warnings)
+- [ ] No debug code (console.log, debugger)
+- [ ] No unused imports or variables
+- [ ] Follows existing patterns
 
 ---
 
@@ -171,19 +174,20 @@ Between iterations, check `.queue.txt` for user input:
 # If .queue.txt exists, read and process it
 # Acknowledge in progress.txt
 # Process in FIFO order
+# Support commands: [PAUSE], [SKIP US-XXX], [ABORT]
 ```
 
 ---
 
 ## Progress Report Format
 
-APPEND to progress.txt (never replace, always append):
+APPEND to `progress.txt` after each story (never replace):
 
-```
-## [Date/Time] - [Story ID]
+```markdown
+## [Date] - [Story ID]: [Story Title]
 
-**Implemented:**
-- What was built
+**Completed:**
+- What was implemented
 - Key decisions made
 
 **Files Changed:**
@@ -194,7 +198,7 @@ APPEND to progress.txt (never replace, always append):
 
 **Learnings:**
 - Patterns discovered
-- Gotchas encountered
+- Gotchas for future iterations
 
 **Constitution Compliance:**
 - [list principles followed]
@@ -204,27 +208,6 @@ APPEND to progress.txt (never replace, always append):
 
 ---
 
-## Quality Requirements
-
-### Code Quality (Zero-Lint Policy)
-- All commits MUST pass typecheck with 0 errors
-- All commits MUST pass lint with 0 warnings (not just errors)
-- No subterfuges to escape linting - fix issues properly
-- All new features MUST include appropriate tests
-
-### Testing Requirements
-- Unit tests for all business logic
-- Integration tests for API endpoints
-- E2E tests for critical user workflows
-- Tests MUST be written BEFORE implementation (TDD)
-
-### TypeScript Strictness
-- Use strict mode throughout
-- Avoid `any` type - use `unknown` or proper types
-- Use Zod for runtime validation
-
----
-
 ## Project-Specific Patterns
 
 ### Directory Structure
@@ -236,8 +219,12 @@ relentless/
 │   ├── config/       # Configuration schema and loading
 │   ├── prd/          # PRD parsing and validation
 │   ├── execution/    # Orchestration loop and routing
+│   ├── routing/      # Auto mode routing module
 │   └── init/         # Project initialization scaffolder
-├── templates/        # Templates copied to projects on init
+├── tests/            # Test files
+│   ├── helpers/      # Shared test utilities
+│   ├── routing/      # Routing module tests
+│   └── integration/  # Integration tests
 ├── .claude/          # Skills and commands
 │   ├── skills/       # Skill implementations
 │   └── commands/     # Command wrappers
@@ -257,9 +244,10 @@ relentless/
 - **UI:** Ink (React for CLI)
 
 ### Test File Patterns
-- Unit tests: `*.test.ts` alongside source files
+- Unit tests: `tests/**/*.test.ts`
 - Integration tests: `tests/integration/`
 - E2E tests: `tests/e2e/`
+- Test helpers: `tests/helpers/`
 
 ---
 
@@ -283,29 +271,32 @@ relentless/
 
 ---
 
-## Common Pitfalls to Avoid
+## Common Mistakes 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 `bun run typecheck` before commit
-5. **Ignoring progress.txt** - Read learnings from previous iterations
-6. **Not checking queue** - Always check `.queue.txt` for user input
+1. **Skipping spec/plan reading** - You MUST read context before coding
+2. **Writing code before tests** - TDD is mandatory, tests come FIRST
+3. **Ignoring lint warnings** - Zero warnings required, not just zero errors
+4. **Marking incomplete stories done** - Only mark `passes: true` when ALL criteria met
+5. **Not updating progress.txt** - Document learnings for future iterations
+6. **Committing broken code** - All quality checks must pass before commit
 7. **Using Node.js APIs** - Use Bun APIs instead
 8. **Adding unnecessary dependencies** - Prefer built-in solutions
 9. **Skipping analysis** - Run `/relentless.analyze` before implementing
 10. **Ignoring checklist** - Update checklist.md after completing criteria
+11. **Not checking queue** - Always check `.queue.txt` for user input
 
 ---
 
 ## Stop Condition
 
-After completing a user story, check if ALL stories have `passes: true`.
+After completing a story, check if ALL stories have `passes: true`.
 
-If ALL stories are complete and passing, reply with:
-`<promise>COMPLETE</promise>`
+If ALL complete, output:
+```
+<promise>COMPLETE</promise>
+```
 
-If there are still stories with `passes: false`, end your response normally (another iteration will pick up the next story).
+Otherwise, end normally (next iteration continues with next story).
 
 ---
 
@@ -325,5 +316,5 @@ If there are still stories with `passes: false`, end your response normally (ano
 ---
 
 **Personalized for Relentless**
-**Generated:** 2026-01-13
+**Generated:** 2026-01-20
 **Re-generate:** /relentless.constitution

package/src/prd/parser.ts

@@ -81,7 +81,17 @@ export function parsePRDMarkdown(content: string): Partial<PRD> {
     }
 
     // Parse section headers (## Section)
+    // This ends the current story (if any) and starts a new section
     if (trimmed.startsWith("## ")) {
+      // Save current story before switching sections
+      if (currentStory && currentStory.id) {
+        if (descriptionLines.length > 0 && !currentStory.description) {
+          currentStory.description = descriptionLines.join(" ").trim();
+        }
+        prd.userStories!.push(currentStory as UserStory);
+        currentStory = null;
+        descriptionLines = [];
+      }
       currentSection = trimmed.replace("## ", "").toLowerCase();
       inAcceptanceCriteria = false;
       continue;
@@ -134,13 +144,17 @@ export function parsePRDMarkdown(content: string): Partial<PRD> {
     }
 
     // Parse dependencies (Dependencies: US-001, US-002)
+    // Extracts only valid story IDs (US-XXX pattern), ignoring annotations like "(foundational)"
     if (currentStory && trimmed.match(/^\*\*Dependencies:?\*\*/i)) {
-      const deps = trimmed
-        .replace(/^\*\*Dependencies:?\*\*/i, "")
-        .trim()
+      const depsText = trimmed.replace(/^\*\*Dependencies:?\*\*/i, "").trim();
+      const deps = depsText
         .split(/[,;]/)
-        .map((d) => d.trim())
-        .filter((d) => d && !["none", "n/a", "-", "na"].includes(d.toLowerCase()));
+        .map((d) => {
+          // Extract US-XXX pattern from strings like "US-001 (authentication must work first)"
+          const match = d.match(/US-\d+/i);
+          return match ? match[0].toUpperCase() : null;
+        })
+        .filter((d): d is string => d !== null);
       if (deps.length > 0) {
         currentStory.dependencies = deps;
       }