@arvorco/relentless 0.4.5 → 0.5.0

package/.claude/skills/constitution/templates/prompt.md

@@ -1,6 +1,3 @@
-<!-- TEMPLATE_VERSION: 2.1.0 -->
-<!-- LAST_UPDATED: 2026-01-20 -->
-
 # Relentless Agent Instructions
 
 You are an autonomous coding agent orchestrated by Relentless. Follow these instructions exactly.
@@ -12,34 +9,47 @@ You are an autonomous coding agent orchestrated by Relentless. Follow these inst
 
 ---
 
-## Before Starting ANY Story
+## Context Already Provided
+
+The orchestrator sends you optimized context in each prompt:
+
+- **Constitution** - Project principles and governance (full)
+- **spec.md** - Feature specification (full)
+- **plan.md** - Technical implementation plan (full)
+- **Current story** - Your assigned story from tasks.md with dependencies
+- **Relevant checklist** - Filtered checklist items for your story
+
+**You do NOT need to read these files separately** - they're already in your context.
+
+Only read files if you need additional details not provided (e.g., examining existing code patterns).
+
+---
+
+## ONE Story Per Iteration (CRITICAL)
 
-**CRITICAL:** Read the feature artifacts in this order:
+**You MUST work on exactly ONE user story per iteration.**
 
-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
+- Do NOT try to complete multiple stories in a single pass
+- Do NOT batch stories together for "efficiency"
+- Do NOT skip ahead to other stories after completing one
 
-This context is essential. Do NOT skip reading these files.
+After completing ONE story, end your turn. The orchestrator will assign the next story.
 
 ---
 
 ## 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 existing code to understand patterns
-6. **Write tests FIRST** (TDD is mandatory)
-7. Verify tests FAIL before implementation
-8. Implement the story to make tests PASS
-9. Run ALL quality checks (typecheck, lint, test)
-10. If ALL checks pass, commit: `feat: [Story ID] - [Story Title]`
-11. Update PRD: set `passes: true`
-12. Append progress to `progress.txt`
+2. Review the story context already provided in this prompt
+3. Review existing code to understand patterns
+4. **Write tests FIRST** (TDD is mandatory)
+5. Verify tests FAIL before implementation
+6. Implement the story to make tests PASS
+7. Run ALL quality checks (typecheck, lint, test)
+8. If ALL checks pass, commit: `feat: [Story ID] - [Story Title]`
+9. Update prd.json: set `passes: true`
+10. Append progress to `progress.txt`
+11. **STOP** - Do not continue to next story
 
 ---
 
@@ -140,9 +150,6 @@ APPEND to `progress.txt` after each story:
 - Patterns discovered
 - Gotchas for future iterations
 
----
-```
-
 ---
 
 ## Stop Condition
@@ -158,26 +165,9 @@ Otherwise, end normally (next iteration continues with next story).
 
 ---
 
-## SpecKit Workflow Reference
-
-The full Relentless workflow is:
-
-```
-/relentless.specify → /relentless.plan → /relentless.tasks → /relentless.convert → /relentless.analyze → /relentless.implement
-```
-
-Each step generates an artifact in `relentless/features/<feature>/`:
-- `spec.md` - Feature specification
-- `plan.md` - Technical implementation plan
-- `tasks.md` - User stories with acceptance criteria
-- `checklist.md` - Quality validation checklist
-- `prd.json` - Machine-readable PRD with routing
-
----
-
 ## Common Mistakes to Avoid
 
-1. **Skipping spec/plan reading** - You MUST read context before coding
+1. **Doing multiple stories** - Complete exactly ONE story, then STOP
 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
@@ -198,5 +188,5 @@ Run `/relentless.constitution` to generate a personalized prompt.
 
 ---
 
-**Template Version:** 2.0.0
-**Compatible with:** Relentless v0.2.0+
+**Template Version:** 2.1.0
+**Compatible with:** Relentless v0.5.0+

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

@@ -58,16 +58,27 @@ If tasks.md doesn't exist, suggest running `/relentless.tasks` first.
 
 ## Step 2: Validate tasks.md Structure
 
-Before conversion, validate the tasks.md file:
+The CLI now **automatically validates** tasks.md before conversion. You can also validate manually:
 
-### Required Elements
+```bash
+relentless validate relentless/features/NNN-feature/tasks.md
+```
+
+### Validation Checks
 
+The validator checks for:
 - [ ] 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
+- [ ] Each story has acceptance criteria (after filtering)
+- [ ] Dependencies reference existing stories
 - [ ] No circular dependencies
-- [ ] Routing Preference line present (recommended)
+- [ ] No underscore format in dependencies (US_001 should be US-001)
+
+### Automatic Filtering (with Warnings)
+
+The following criteria are automatically filtered during conversion:
+- **Standalone file paths**: `` `src/file.ts` `` → Add context: "`src/file.ts` contains X"
+- **Section markers**: `**Files:**` → Move outside acceptance criteria section
+- **Short text**: Less than 3 characters
 
 ### Example Valid Story
 
@@ -80,6 +91,7 @@ Before conversion, validate the tasks.md file:
 - [ ] POST /api/register endpoint exists
 - [ ] Email validation works
 - [ ] Password is hashed
+- [ ] `src/auth/register.ts` contains the registration handler
 - [ ] Unit tests pass
 - [ ] Integration test passes
 
@@ -88,6 +100,20 @@ Before conversion, validate the tasks.md file:
 **Priority:** 1
 ```
 
+### Example Validation Output
+
+```
+Validating tasks.md...
+
+⚠️  2 validation warning(s):
+  [FILTERED_CRITERIA]
+    2 acceptance criteria will be filtered during conversion
+
+  📝 2 criteria will be filtered during conversion
+     US-003: "`src/queue/types.ts`"
+     US-004: "**"
+```
+
 ---
 
 ## Step 3: Run Conversion (with Routing)
@@ -232,6 +258,25 @@ The conversion was run with `--skip-routing`. Re-run:
 relentless convert relentless/features/<feature>/tasks.md --feature <feature-name>
 ```
 
+### "Validation failed"
+
+The tasks.md has format issues. Run validation to see details:
+```bash
+relentless validate relentless/features/<feature>/tasks.md
+```
+
+Common issues:
+- **DUPLICATE_STORY_ID**: Two stories have the same ID
+- **MISSING_DEPENDENCY**: A story depends on non-existent story ID
+- **CIRCULAR_DEPENDENCY**: Stories form a dependency loop
+
+### "Criteria will be filtered"
+
+Some acceptance criteria don't meet format requirements. Fix by:
+- Adding context to file paths: `` `src/file.ts` `` → "`src/file.ts` contains X"
+- Moving section markers outside acceptance criteria
+- Writing longer, more descriptive criteria
+
 ### "Invalid dependency"
 
 A story references a non-existent story ID. Check the `Dependencies:` line.
@@ -240,6 +285,10 @@ A story references a non-existent story ID. Check the `Dependencies:` line.
 
 Stories reference each other in a cycle. Example: US-001 depends on US-002, and US-002 depends on US-001.
 
+### "Dependency uses underscore format"
+
+Use dashes in story IDs: `US-001` not `US_001`.
+
 ---
 
 ## Notes

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

@@ -182,6 +182,32 @@ Check that:
 
 ---
 
+## Step 6.5: Pre-Conversion Validation
+
+Before saving and converting, validate the format manually:
+
+**Story ID Format:**
+- [ ] Every story uses `US-XXX` format (e.g., `US-001`, not `Story 1`)
+- [ ] Story IDs are unique and sequential
+
+**Acceptance Criteria Format:**
+- [ ] Criteria are full sentences, not just file paths
+- [ ] File paths include context (e.g., "`src/queue/types.ts` contains Zod schemas")
+- [ ] No standalone file paths like `` `src/file.ts` ``
+
+**Dependencies Format:**
+- [ ] Dependencies use `US-XXX` with dashes, not underscores
+- [ ] Example: `**Dependencies:** US-001, US-002` (correct)
+- [ ] Example: `**Dependencies:** US_001` (incorrect - will warn)
+
+**Common Mistakes to Avoid:**
+- ❌ `- [ ] \`src/file.ts\`` (file path only - will be filtered)
+- ✅ `- [ ] \`src/file.ts\` contains the queue interface`
+- ❌ `**Files:**` inside acceptance criteria (will end criteria parsing)
+- ✅ Put **Files:** section after acceptance criteria
+
+---
+
 ## Step 7: Save & Report
 
 1. Save to `relentless/features/NNN-feature/tasks.md`

package/CHANGELOG.md

@@ -5,9 +5,35 @@ All notable changes to Relentless will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.5.0](https://github.com/ArvorCo/Relentless/releases/tag/v0.5.0) - 2026-01-23
 
-## [0.4.5] - 2026-01-21
+### Major Features
+
+#### Optimized Context Builder - Save ~40% Tokens Per Iteration
+- **Task-specific context extraction**: Instead of sending entire files, now extracts only relevant content
+  - `tasks.md`: Only current story + dependency sections (~84% reduction)
+  - `checklist.md`: Only story-specific + Constitution + general items (~80% reduction)
+- **New module**: `src/execution/context-builder.ts` with extraction functions:
+  - `extractStoryFromTasks()` - Extract current story and dependencies
+  - `filterChecklistForStory()` - Filter checklist by story ID
+  - `extractStoryMetadata()` - Extract story metadata from PRD
+  - `buildProgressSummary()` - Build concise progress summary
+  - `formatStoryContext()` / `formatFilteredChecklist()` - Formatters for prompt
+- **Token savings**: ~40% reduction in prompt size (from ~7,600 to ~4,500 tokens)
+- **Backward compatible**: Falls back to full file loading when no story context available
+
+### Changed
+- **prompt.md template v2.1.0**: Updated to reflect optimized context delivery
+  - Added "Context Already Provided" section explaining what's sent in prompts
+  - Added "ONE Story Per Iteration" critical rule to prevent over-eager agents
+  - Removed redundant "read these files" instructions (context is pre-loaded)
+  - Updated task workflow to emphasize STOP after one story
+
+### Added
+- 23 new unit tests for context-builder module
+- Integration with existing runner for seamless optimization
+
+## [0.4.5](https://github.com/ArvorCo/Relentless/releases/tag/v0.4.5) - 2026-01-21
 
 ### Fixed
 - **Registry**: Corrected Claude Sonnet 4.5 model ID from `claude-sonnet-4-5-20251020` to `claude-sonnet-4-5-20250929`
@@ -420,7 +446,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.3...HEAD
+[Unreleased]: https://github.com/ArvorCo/Relentless/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/ArvorCo/Relentless/compare/v0.4.5...v0.5.0
+[0.4.5]: https://github.com/ArvorCo/Relentless/compare/v0.4.3...v0.4.5
 [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

package/bin/relentless.ts

@@ -220,6 +220,7 @@ program
   .option("--auto-number", "Auto-number the feature directory (e.g., 001-feature-name)", false)
   .option("--with-checklist", "Merge checklist items into acceptance criteria", false)
   .option("--skip-routing", "Skip automatic routing classification (not recommended)", false)
+  .option("--skip-validation", "Skip validation before conversion (advanced users only)", false)
   .option("--mode <mode>", `Cost optimization mode for routing (${VALID_MODES.join(", ")})`, "good")
   .action(async (tasksMd, options) => {
     if (!existsSync(tasksMd)) {
@@ -233,6 +234,62 @@ program
       process.exit(1);
     }
 
+    // Read tasks.md content first (needed for validation)
+    const tasksContent = await Bun.file(tasksMd).text();
+
+    // VALIDATION PHASE (unless --skip-validation is set)
+    if (!options.skipValidation) {
+      const { validateTasksMarkdown } = await import("../src/prd/validator");
+
+      console.log(chalk.dim(`Validating ${tasksMd}...`));
+      const validationResult = validateTasksMarkdown(tasksContent);
+
+      // Show validation errors and abort if any
+      if (validationResult.errors.length > 0) {
+        console.log(chalk.red("\n❌ Validation failed:\n"));
+        for (const error of validationResult.errors) {
+          const location = error.line ? ` (line ${error.line})` : "";
+          console.log(chalk.red(`  [${error.code}]${location}`));
+          console.log(chalk.red(`    ${error.message}`));
+          if (error.suggestion) {
+            console.log(chalk.dim(`    💡 ${error.suggestion}`));
+          }
+        }
+        console.log("");
+        console.log(chalk.dim("Fix the errors above and try again."));
+        console.log(chalk.dim("Use --skip-validation to bypass (not recommended)."));
+        process.exit(1);
+      }
+
+      // Show warnings but continue
+      if (validationResult.warnings.length > 0) {
+        console.log(chalk.yellow(`\n⚠️  ${validationResult.warnings.length} validation warning(s):`));
+        for (const warning of validationResult.warnings) {
+          const location = warning.line ? ` (line ${warning.line})` : "";
+          console.log(chalk.yellow(`  [${warning.code}]${location}`));
+          console.log(chalk.dim(`    ${warning.message}`));
+        }
+        console.log("");
+      }
+
+      // Show filtered criteria summary
+      if (validationResult.filteredCriteria.length > 0) {
+        console.log(chalk.dim(`  📝 ${validationResult.filteredCriteria.length} criteria will be filtered during conversion`));
+        if (validationResult.filteredCriteria.length <= 5) {
+          for (const fc of validationResult.filteredCriteria) {
+            console.log(chalk.dim(`     ${fc.storyId}: "${fc.text.substring(0, 50)}${fc.text.length > 50 ? "..." : ""}"`));
+          }
+        }
+        console.log("");
+      }
+
+      // Show stories with no criteria warning
+      if (validationResult.summary.storiesWithNoCriteria.length > 0) {
+        console.log(chalk.yellow(`  ⚠️  Stories with no valid criteria: ${validationResult.summary.storiesWithNoCriteria.join(", ")}`));
+        console.log("");
+      }
+    }
+
     // Determine final feature name (with auto-number if requested)
     let finalFeatureName = options.feature;
     if (options.autoNumber) {
@@ -261,8 +318,7 @@ program
 
     console.log(chalk.dim(`Converting ${tasksMd}...`));
 
-    // Read tasks.md (primary source)
-    const tasksContent = await Bun.file(tasksMd).text();
+    // Parse the markdown (content already read above)
     const parsed = parsePRDMarkdown(tasksContent);
 
     // Optionally merge checklist items
@@ -725,6 +781,72 @@ program
     }
   });
 
+// Validate command - validate tasks.md before conversion
+program
+  .command("validate <tasksMd>")
+  .description("Validate tasks.md file before conversion to prd.json")
+  .option("-d, --dir <path>", "Project directory", process.cwd())
+  .option("--json", "Output validation results as JSON", false)
+  .option("--strict", "Treat warnings as errors", false)
+  .option("--verbose", "Show all filtered criteria details", false)
+  .action(async (tasksMd, options) => {
+    const { validateTasksMarkdown, formatValidationResult, formatValidationResultJSON } = await import("../src/prd/validator");
+
+    if (!existsSync(tasksMd)) {
+      console.error(chalk.red(`File not found: ${tasksMd}`));
+      process.exit(1);
+    }
+
+    const content = await Bun.file(tasksMd).text();
+    const result = validateTasksMarkdown(content);
+
+    // Check strict mode
+    const hasIssues = result.errors.length > 0 || (options.strict && result.warnings.length > 0);
+
+    if (options.json) {
+      console.log(formatValidationResultJSON(result));
+    } else {
+      console.log(chalk.bold("\n📋 Tasks.md Validation\n"));
+      console.log(chalk.dim(`File: ${tasksMd}`));
+      console.log("");
+
+      console.log(formatValidationResult(result));
+
+      // Show verbose filtered criteria if requested
+      if (options.verbose && result.filteredCriteria.length > 10) {
+        console.log("ALL FILTERED CRITERIA:");
+        for (const fc of result.filteredCriteria) {
+          const location = fc.line ? ` (line ${fc.line})` : "";
+          console.log(`  ${fc.storyId}${location}: "${fc.text}"`);
+          console.log(`    Reason: ${fc.reason}`);
+          if (fc.suggestion) {
+            console.log(`    💡 ${fc.suggestion}`);
+          }
+        }
+        console.log("");
+      }
+
+      // Final summary
+      if (hasIssues) {
+        if (options.strict && result.warnings.length > 0 && result.errors.length === 0) {
+          console.log(chalk.red(`❌ Validation failed (strict mode: ${result.warnings.length} warnings treated as errors)\n`));
+        } else {
+          console.log(chalk.red(`❌ Validation failed with ${result.errors.length} error(s)\n`));
+        }
+        console.log(chalk.dim("Fix the errors above before running: relentless convert"));
+      } else if (result.warnings.length > 0) {
+        console.log(chalk.yellow(`⚠️  Validation passed with ${result.warnings.length} warning(s)\n`));
+        console.log(chalk.dim("Warnings won't block conversion, but consider addressing them."));
+        console.log(chalk.dim("Next step: relentless convert " + tasksMd + " --feature <name>"));
+      } else {
+        console.log(chalk.green("✅ Validation passed - ready to convert\n"));
+        console.log(chalk.dim("Next step: relentless convert " + tasksMd + " --feature <name>"));
+      }
+    }
+
+    process.exit(hasIssues ? 1 : 0);
+  });
+
 // Issues command
 program
   .command("issues")

package/package.json

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