@arvorco/relentless 0.1.0

package/prompt.md

@@ -0,0 +1,108 @@
+# Ralph Agent Instructions
+
+You are an autonomous coding agent working on a software project.
+
+## Your Task
+
+1. Read the PRD at `prd.json` (in the same directory as this file)
+2. Read the progress log at `progress.txt` (check Codebase Patterns section first)
+3. Check you're on the correct branch from PRD `branchName`. If not, check it out or create from main.
+4. Pick the **highest priority** user story where `passes: false`
+5. Implement that single user story
+6. Run quality checks (e.g., typecheck, lint, test - use whatever your project requires)
+7. Update AGENTS.md files if you discover reusable patterns (see below)
+8. If checks pass, commit ALL changes with message: `feat: [Story ID] - [Story Title]`
+9. Update the PRD to set `passes: true` for the completed story
+10. Append your progress to `progress.txt`
+
+## Progress Report Format
+
+APPEND to progress.txt (never replace, always append):
+```
+## [Date/Time] - [Story ID]
+Thread: https://ampcode.com/threads/$AMP_CURRENT_THREAD_ID
+- What was implemented
+- Files changed
+- **Learnings for future iterations:**
+  - Patterns discovered (e.g., "this codebase uses X for Y")
+  - Gotchas encountered (e.g., "don't forget to update Z when changing W")
+  - Useful context (e.g., "the evaluation panel is in component X")
+---
+```
+
+Include the thread URL so future iterations can use the `read_thread` tool to reference previous work if needed.
+
+The learnings section is critical - it helps future iterations avoid repeating mistakes and understand the codebase better.
+
+## Consolidate Patterns
+
+If you discover a **reusable pattern** that future iterations should know, add it to the `## Codebase Patterns` section at the TOP of progress.txt (create it if it doesn't exist). This section should consolidate the most important learnings:
+
+```
+## Codebase Patterns
+- Example: Use `sql<number>` template for aggregations
+- Example: Always use `IF NOT EXISTS` for migrations
+- Example: Export types from actions.ts for UI components
+```
+
+Only add patterns that are **general and reusable**, not story-specific details.
+
+## Update AGENTS.md Files
+
+Before committing, check if any edited files have learnings worth preserving in nearby AGENTS.md files:
+
+1. **Identify directories with edited files** - Look at which directories you modified
+2. **Check for existing AGENTS.md** - Look for AGENTS.md in those directories or parent directories
+3. **Add valuable learnings** - If you discovered something future developers/agents should know:
+   - API patterns or conventions specific to that module
+   - Gotchas or non-obvious requirements
+   - Dependencies between files
+   - Testing approaches for that area
+   - Configuration or environment requirements
+
+**Examples of good AGENTS.md additions:**
+- "When modifying X, also update Y to keep them in sync"
+- "This module uses pattern Z for all API calls"
+- "Tests require the dev server running on PORT 3000"
+- "Field names must match the template exactly"
+
+**Do NOT add:**
+- Story-specific implementation details
+- Temporary debugging notes
+- Information already in progress.txt
+
+Only update AGENTS.md if you have **genuinely reusable knowledge** that would help future work in that directory.
+
+## Quality Requirements
+
+- ALL commits must pass your project's quality checks (typecheck, lint, test)
+- Do NOT commit broken code
+- Keep changes focused and minimal
+- Follow existing code patterns
+
+## Browser Testing (Required for Frontend Stories)
+
+For any story that changes UI, you MUST verify it works in the browser:
+
+1. Load the `dev-browser` skill
+2. Navigate to the relevant page
+3. Verify the UI changes work as expected
+4. Take a screenshot if helpful for the progress log
+
+A frontend story is NOT complete until browser verification passes.
+
+## Stop Condition
+
+After completing a user story, check if ALL stories have `passes: true`.
+
+If ALL stories are complete and passing, reply with:
+<promise>COMPLETE</promise>
+
+If there are still stories with `passes: false`, end your response normally (another iteration will pick up the next story).
+
+## Important
+
+- Work on ONE story per iteration
+- Commit frequently
+- Keep CI green
+- Read the Codebase Patterns section in progress.txt before starting

package/ralph.sh

@@ -0,0 +1,80 @@
+#!/bin/bash
+# Ralph Wiggum - Long-running AI agent loop
+# Usage: ./ralph.sh [max_iterations]
+
+set -e
+
+MAX_ITERATIONS=${1:-10}
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PRD_FILE="$SCRIPT_DIR/prd.json"
+PROGRESS_FILE="$SCRIPT_DIR/progress.txt"
+ARCHIVE_DIR="$SCRIPT_DIR/archive"
+LAST_BRANCH_FILE="$SCRIPT_DIR/.last-branch"
+
+# Archive previous run if branch changed
+if [ -f "$PRD_FILE" ] && [ -f "$LAST_BRANCH_FILE" ]; then
+  CURRENT_BRANCH=$(jq -r '.branchName // empty' "$PRD_FILE" 2>/dev/null || echo "")
+  LAST_BRANCH=$(cat "$LAST_BRANCH_FILE" 2>/dev/null || echo "")
+  
+  if [ -n "$CURRENT_BRANCH" ] && [ -n "$LAST_BRANCH" ] && [ "$CURRENT_BRANCH" != "$LAST_BRANCH" ]; then
+    # Archive the previous run
+    DATE=$(date +%Y-%m-%d)
+    # Strip "ralph/" prefix from branch name for folder
+    FOLDER_NAME=$(echo "$LAST_BRANCH" | sed 's|^ralph/||')
+    ARCHIVE_FOLDER="$ARCHIVE_DIR/$DATE-$FOLDER_NAME"
+    
+    echo "Archiving previous run: $LAST_BRANCH"
+    mkdir -p "$ARCHIVE_FOLDER"
+    [ -f "$PRD_FILE" ] && cp "$PRD_FILE" "$ARCHIVE_FOLDER/"
+    [ -f "$PROGRESS_FILE" ] && cp "$PROGRESS_FILE" "$ARCHIVE_FOLDER/"
+    echo "   Archived to: $ARCHIVE_FOLDER"
+    
+    # Reset progress file for new run
+    echo "# Ralph Progress Log" > "$PROGRESS_FILE"
+    echo "Started: $(date)" >> "$PROGRESS_FILE"
+    echo "---" >> "$PROGRESS_FILE"
+  fi
+fi
+
+# Track current branch
+if [ -f "$PRD_FILE" ]; then
+  CURRENT_BRANCH=$(jq -r '.branchName // empty' "$PRD_FILE" 2>/dev/null || echo "")
+  if [ -n "$CURRENT_BRANCH" ]; then
+    echo "$CURRENT_BRANCH" > "$LAST_BRANCH_FILE"
+  fi
+fi
+
+# Initialize progress file if it doesn't exist
+if [ ! -f "$PROGRESS_FILE" ]; then
+  echo "# Ralph Progress Log" > "$PROGRESS_FILE"
+  echo "Started: $(date)" >> "$PROGRESS_FILE"
+  echo "---" >> "$PROGRESS_FILE"
+fi
+
+echo "Starting Ralph - Max iterations: $MAX_ITERATIONS"
+
+for i in $(seq 1 $MAX_ITERATIONS); do
+  echo ""
+  echo "═══════════════════════════════════════════════════════"
+  echo "  Ralph Iteration $i of $MAX_ITERATIONS"
+  echo "═══════════════════════════════════════════════════════"
+  
+  # Run amp with the ralph prompt
+  OUTPUT=$(cat "$SCRIPT_DIR/prompt.md" | amp --dangerously-allow-all 2>&1 | tee /dev/stderr) || true
+  
+  # Check for completion signal
+  if echo "$OUTPUT" | grep -q "<promise>COMPLETE</promise>"; then
+    echo ""
+    echo "Ralph completed all tasks!"
+    echo "Completed at iteration $i of $MAX_ITERATIONS"
+    exit 0
+  fi
+  
+  echo "Iteration $i complete. Continuing..."
+  sleep 2
+done
+
+echo ""
+echo "Ralph reached max iterations ($MAX_ITERATIONS) without completing all tasks."
+echo "Check $PROGRESS_FILE for status."
+exit 1

package/relentless/config.json

@@ -0,0 +1,38 @@
+{
+  "defaultAgent": "claude",
+  "agents": {
+    "claude": {
+      "dangerouslyAllowAll": true
+    },
+    "amp": {
+      "dangerouslyAllowAll": true
+    },
+    "gemini": {
+      "dangerouslyAllowAll": true
+    }
+  },
+  "routing": {
+    "rules": [],
+    "default": "claude"
+  },
+  "fallback": {
+    "enabled": true,
+    "priority": [
+      "claude",
+      "codex",
+      "amp",
+      "opencode",
+      "gemini"
+    ],
+    "autoRecovery": true,
+    "retryDelay": 2000
+  },
+  "execution": {
+    "maxIterations": 20,
+    "iterationDelay": 2000,
+    "timeout": 600000
+  },
+  "prompt": {
+    "path": "prompt.md"
+  }
+}

package/relentless/features/ghsk-ideas/prd.json

@@ -0,0 +1,229 @@
+{
+  "project": "GitHub Spec Kit Ideas Integration",
+  "branchName": "ralph/github-spec-kit-ideas-integration",
+  "description": "This feature integrates sophisticated specification-driven development capabilities from speckit into relentless while maintaining its agent-agnostic simplicity. The integration creates a professional, globally-installed binary with powerful enhancements for dependency-ordered tasks, constitution-based governance, quality checklists, consistency analysis, and enhanced orchestration.",
+  "userStories": [
+    {
+      "id": "US-000",
+      "title": "Single Binary with PATH Installation",
+      "description": "As a relentless user, I want relentless installed as a global binary in my PATH so that I can call it from anywhere without dealing with shell scripts.",
+      "acceptanceCriteria": [
+        "package.json has \"bin\" field pointing to bin/relentless.ts",
+        "bin/relentless.ts has #!/usr/bin/env bun shebang",
+        "Binary can be installed globally via `bun install -g`",
+        "relentless command available in PATH after install",
+        "All commands work: init, run, convert, analyze, features, status, reset",
+        "Shell script (bin/relentless.sh) completely removed",
+        "Scaffolder no longer copies shell script",
+        "Can call `relentless init` from any directory",
+        "Can call `relentless run --feature <name>` from project root",
+        "README.md fully reviewed and all shell script references replaced with binary commands",
+        "CLAUDE.md reviewed and updated with new CLI usage patterns",
+        "All documentation files searched and updated: replace ./relentless/bin/relentless.sh with relentless",
+        "Scaffolder output messages updated to remove all shell script references",
+        "All code comments reviewed and updated to remove shell script mentions",
+        "Template files reviewed: prompt.md and other templates use binary commands",
+        "All example commands updated to use relentless <action> --params format",
+        "Installation instructions complete: document bun install -g and bunx relentless",
+        "Skills documentation updated: prd and relentless skills reference binary",
+        "Typecheck passes",
+        "Linter passes (0 warnings)",
+        "Verify in terminal: `which relentless` shows installed binary",
+        "Verify documentation: grep for .sh and relentless.sh returns no results in docs"
+      ],
+      "priority": 1,
+      "passes": true,
+      "notes": ""
+    },
+    {
+      "id": "US-001",
+      "title": "Dependency-Ordered Task Schema",
+      "description": "As a developer, I want user stories to support dependencies, phases, and parallel execution markers so that I can express complex relationships between tasks.",
+      "acceptanceCriteria": [
+        "UserStory schema extended with dependencies, parallel, phase fields",
+        "getNextStory() respects dependencies and only returns stories with completed prerequisites",
+        "validateDependencies() detects circular dependencies and throws error",
+        "Parser extracts \"Dependencies: US-001, US-002\" from PRD markdown",
+        "Typecheck passes",
+        "Linter passes (0 warnings)"
+      ],
+      "priority": 2,
+      "passes": true,
+      "notes": ""
+    },
+    {
+      "id": "US-002",
+      "title": "Constitution Management System",
+      "description": "As a project lead, I want a constitution.md file containing project principles, patterns, and constraints so that all agents follow consistent guidelines.",
+      "acceptanceCriteria": [
+        "Template created at /templates/constitution.md with clear structure",
+        "Loader.ts reads and parses constitution.md",
+        "Runner.ts includes constitution in prompt context",
+        "Scaffolder copies constitution template during init",
+        "Constitution validates principles (MUST/SHOULD format)",
+        "Typecheck passes",
+        "Linter passes (0 warnings)"
+      ],
+      "priority": 3,
+      "passes": true,
+      "notes": ""
+    },
+    {
+      "id": "US-003",
+      "title": "Enhanced Progress Tracking with Metadata",
+      "description": "As an agent, I want progress.txt to have structured YAML frontmatter so that I can access machine-readable context about patterns and blockers.",
+      "acceptanceCriteria": [
+        "Progress.txt created with YAML frontmatter",
+        "Runner updates frontmatter after each iteration (last_updated, stories_completed)",
+        "Patterns array updated with learnings from progress log",
+        "Prompt context includes parsed frontmatter patterns",
+        "Typecheck passes",
+        "Linter passes (0 warnings)"
+      ],
+      "priority": 4,
+      "passes": true,
+      "notes": ""
+    },
+    {
+      "id": "US-004",
+      "title": "Technical Planning Template",
+      "description": "As a developer, I want an optional plan.md template so that I can document technical design decisions before implementation.",
+      "acceptanceCriteria": [
+        "Template created at /templates/plan.md with all sections",
+        "Scaffolder supports `createFeature(name, {withPlan: true})`",
+        "Plan.md copied to feature directory when flag enabled",
+        "Prompt references plan.md if present in feature directory",
+        "Typecheck passes",
+        "Linter passes (0 warnings)"
+      ],
+      "priority": 5,
+      "passes": true,
+      "notes": ""
+    },
+    {
+      "id": "US-005",
+      "title": "Quality Checklist Generator Skill",
+      "description": "As a quality-focused developer, I want a skill that generates custom quality checklists based on my PRD so that I can ensure comprehensive requirement validation.",
+      "acceptanceCriteria": [
+        "SKILL.md created with clear instructions for checklist generation",
+        "Skill analyzes PRD and infers appropriate checklist domain",
+        "Checklist has 20-40 items across 5-7 categories",
+        "80% of items reference specific spec sections or have [Gap]/[Ambiguity] markers",
+        "Checklist saved to feature directory",
+        "Skill works with Claude Code, Amp, Gemini",
+        "Typecheck passes",
+        "Linter passes (0 warnings)"
+      ],
+      "priority": 6,
+      "passes": true,
+      "notes": ""
+    },
+    {
+      "id": "US-006",
+      "title": "Cross-Artifact Consistency Analysis Command",
+      "description": "As a developer, I want an analyze command that checks consistency across PRD, JSON, and code so that I can catch errors early.",
+      "acceptanceCriteria": [
+        "Command added to bin/relentless.ts with analyze subcommand",
+        "Analyzer checks all 5 consistency categories",
+        "Output includes severity ratings and recommendations",
+        "Report includes coverage summary (stories completed/total per requirement)",
+        "Analyzer handles missing files gracefully",
+        "Typecheck passes",
+        "Linter passes (0 warnings)",
+        "Verify in terminal: Run analyze command and review output"
+      ],
+      "priority": 7,
+      "passes": true,
+      "notes": ""
+    },
+    {
+      "id": "US-007",
+      "title": "Interactive Clarification Skill",
+      "description": "As a PRD author, I want an interactive clarification skill that asks targeted questions about ambiguities so that I can create clearer specifications.",
+      "acceptanceCriteria": [
+        "SKILL.md created with clarification workflow",
+        "Skill scans PRD across 9 ambiguity categories",
+        "Generates max 5 questions with multiple-choice options",
+        "Adds [NEEDS CLARIFICATION] markers (max 3 per spec)",
+        "Saves clarification-log.md with questions and answers",
+        "Updates PRD in-place after each clarification",
+        "Typecheck passes",
+        "Linter passes (0 warnings)"
+      ],
+      "priority": 8,
+      "passes": true,
+      "notes": ""
+    },
+    {
+      "id": "US-008",
+      "title": "Dependency-Ordered Task Breakdown Skill",
+      "description": "As a developer, I want a skill that generates dependency-ordered task breakdowns with phase structure so that I can visualize implementation order.",
+      "acceptanceCriteria": [
+        "SKILL.md created with task breakdown instructions",
+        "Skill generates phase structure (Setup → Foundation → Stories → Polish)",
+        "Tasks include IDs (T001+), phase markers, story labels [US1]",
+        "Parallel tasks marked with [P]",
+        "Each story independently testable",
+        "Saves to tasks.md in feature directory",
+        "Typecheck passes",
+        "Linter passes (0 warnings)"
+      ],
+      "priority": 9,
+      "passes": true,
+      "notes": ""
+    },
+    {
+      "id": "US-009",
+      "title": "Research Phase Support",
+      "description": "As an agent, I want an optional research phase before implementation so that I can explore existing patterns and make better decisions.",
+      "acceptanceCriteria": [
+        "UserStory schema has optional research field",
+        "Runner detects research flag and runs two-phase execution",
+        "Research phase saves findings to research/<story-id>.md",
+        "Second phase includes research findings in prompt",
+        "Prompt template updated with research instructions",
+        "Typecheck passes",
+        "Linter passes (0 warnings)"
+      ],
+      "priority": 10,
+      "passes": true,
+      "notes": ""
+    },
+    {
+      "id": "US-010",
+      "title": "Branch Management with Auto-Numbering",
+      "description": "As a developer, I want features to have auto-generated numbers (001-feature-name) so that I can track them in order.",
+      "acceptanceCriteria": [
+        "Scaffolder supports createFeature with autoNumber option",
+        "Feature directories created with 001- prefix when enabled",
+        "PRD branchName auto-generated with number prefix",
+        "listFeatures() returns numbered features correctly",
+        "Existing features without numbers still work",
+        "Typecheck passes",
+        "Linter passes (0 warnings)"
+      ],
+      "priority": 11,
+      "passes": true,
+      "notes": ""
+    },
+    {
+      "id": "US-011",
+      "title": "GitHub Issues Generator",
+      "description": "As a team lead, I want to convert user stories to GitHub issues so that I can track work in GitHub Projects.",
+      "acceptanceCriteria": [
+        "Command added to bin/relentless.ts",
+        "Issues.ts creates GitHub issues via gh CLI",
+        "Each story mapped to issue with proper formatting",
+        "Labels inferred from story type (database, ui, api, etc.)",
+        "Dependencies mapped to issue relationships",
+        "Safety: validates git remote matches before creating issues",
+        "Typecheck passes",
+        "Linter passes (0 warnings)",
+        "Verify in browser: Check created issues on GitHub"
+      ],
+      "priority": 12,
+      "passes": true,
+      "notes": ""
+    }
+  ]
+}

package/relentless/features/ghsk-ideas/prd.md

@@ -0,0 +1,191 @@
+# PRD: GitHub Spec Kit Ideas Integration
+
+## Introduction
+
+This feature integrates sophisticated specification-driven development capabilities inspired by GitHub's Spec Kit into relentless while maintaining its agent-agnostic simplicity. We're forking and adapting these concepts as relentless-native commands (relentless.plan, relentless.constitution, etc.) to create a professional, globally-installed binary with powerful enhancements for dependency-ordered tasks, constitution-based governance, quality checklists, consistency analysis, and enhanced orchestration.
+
+## User Stories
+
+### US-000: Single Binary with PATH Installation
+**Description:** As a relentless user, I want relentless installed as a global binary in my PATH so that I can call it from anywhere without dealing with shell scripts.
+
+**Acceptance Criteria:**
+- [ ] package.json has "bin" field pointing to bin/relentless.ts
+- [ ] bin/relentless.ts has #!/usr/bin/env bun shebang
+- [ ] Binary can be installed globally via `bun install -g`
+- [ ] relentless command available in PATH after install
+- [ ] All commands work: init, run, convert, analyze, features, status, reset
+- [ ] Shell script (bin/relentless.sh) completely removed
+- [ ] Scaffolder no longer copies shell script
+- [ ] Can call `relentless init` from any directory
+- [ ] Can call `relentless run --feature <name>` from project root
+- [ ] README.md fully reviewed and all shell script references replaced with binary commands
+- [ ] CLAUDE.md reviewed and updated with new CLI usage patterns
+- [ ] All documentation files searched and updated: replace ./relentless/bin/relentless.sh with relentless
+- [ ] Scaffolder output messages updated to remove all shell script references
+- [ ] All code comments reviewed and updated to remove shell script mentions
+- [ ] Template files reviewed: prompt.md and other templates use binary commands
+- [ ] All example commands updated to use relentless <action> --params format
+- [ ] Installation instructions complete: document bun install -g and bunx relentless
+- [ ] Skills documentation updated: prd and relentless skills reference binary
+- [ ] Typecheck passes
+- [ ] Linter passes (0 warnings)
+- [ ] Verify in terminal: `which relentless` shows installed binary
+- [ ] Verify documentation: grep for .sh and relentless.sh returns no results in docs
+
+---
+
+### US-001: Dependency-Ordered Task Schema
+**Description:** As a developer, I want user stories to support dependencies, phases, and parallel execution markers so that I can express complex relationships between tasks.
+
+**Acceptance Criteria:**
+- [ ] UserStory schema extended with dependencies, parallel, phase fields
+- [ ] getNextStory() respects dependencies and only returns stories with completed prerequisites
+- [ ] validateDependencies() detects circular dependencies and throws error
+- [ ] Parser extracts "Dependencies: US-001, US-002" from PRD markdown
+- [ ] Typecheck passes
+- [ ] Linter passes (0 warnings)
+
+---
+
+### US-002: Constitution Management System
+**Description:** As a project lead, I want a constitution.md file containing project principles, patterns, and constraints so that all agents follow consistent guidelines.
+
+**Acceptance Criteria:**
+- [ ] Template created at /templates/constitution.md with clear structure
+- [ ] Loader.ts reads and parses constitution.md
+- [ ] Runner.ts includes constitution in prompt context
+- [ ] Scaffolder copies constitution template during init
+- [ ] Constitution validates principles (MUST/SHOULD format)
+- [ ] Typecheck passes
+- [ ] Linter passes (0 warnings)
+
+---
+
+### US-003: Enhanced Progress Tracking with Metadata
+**Description:** As an agent, I want progress.txt to have structured YAML frontmatter so that I can access machine-readable context about patterns and blockers.
+
+**Acceptance Criteria:**
+- [ ] Progress.txt created with YAML frontmatter
+- [ ] Runner updates frontmatter after each iteration (last_updated, stories_completed)
+- [ ] Patterns array updated with learnings from progress log
+- [ ] Prompt context includes parsed frontmatter patterns
+- [ ] Typecheck passes
+- [ ] Linter passes (0 warnings)
+
+---
+
+### US-004: Technical Planning Template
+**Description:** As a developer, I want an optional plan.md template so that I can document technical design decisions before implementation.
+
+**Acceptance Criteria:**
+- [ ] Template created at /templates/plan.md with all sections
+- [ ] Scaffolder supports `createFeature(name, {withPlan: true})`
+- [ ] Plan.md copied to feature directory when flag enabled
+- [ ] Prompt references plan.md if present in feature directory
+- [ ] Typecheck passes
+- [ ] Linter passes (0 warnings)
+
+---
+
+### US-005: Quality Checklist Generator Skill
+**Description:** As a quality-focused developer, I want a skill that generates custom quality checklists based on my PRD so that I can ensure comprehensive requirement validation.
+
+**Acceptance Criteria:**
+- [ ] SKILL.md created with clear instructions for checklist generation
+- [ ] Skill analyzes PRD and infers appropriate checklist domain
+- [ ] Checklist has 20-40 items across 5-7 categories
+- [ ] 80% of items reference specific spec sections or have [Gap]/[Ambiguity] markers
+- [ ] Checklist saved to feature directory
+- [ ] Skill works with Claude Code, Amp, Gemini
+- [ ] Typecheck passes
+- [ ] Linter passes (0 warnings)
+
+---
+
+### US-006: Cross-Artifact Consistency Analysis Command
+**Description:** As a developer, I want an analyze command that checks consistency across PRD, JSON, and code so that I can catch errors early.
+
+**Acceptance Criteria:**
+- [ ] Command added to bin/relentless.ts with analyze subcommand
+- [ ] Analyzer checks all 5 consistency categories
+- [ ] Output includes severity ratings and recommendations
+- [ ] Report includes coverage summary (stories completed/total per requirement)
+- [ ] Analyzer handles missing files gracefully
+- [ ] Typecheck passes
+- [ ] Linter passes (0 warnings)
+- [ ] Verify in terminal: Run analyze command and review output
+
+---
+
+### US-007: Interactive Clarification Skill
+**Description:** As a PRD author, I want an interactive clarification skill that asks targeted questions about ambiguities so that I can create clearer specifications.
+
+**Acceptance Criteria:**
+- [ ] SKILL.md created with clarification workflow
+- [ ] Skill scans PRD across 9 ambiguity categories
+- [ ] Generates max 5 questions with multiple-choice options
+- [ ] Adds [NEEDS CLARIFICATION] markers (max 3 per spec)
+- [ ] Saves clarification-log.md with questions and answers
+- [ ] Updates PRD in-place after each clarification
+- [ ] Typecheck passes
+- [ ] Linter passes (0 warnings)
+
+---
+
+### US-008: Dependency-Ordered Task Breakdown Skill
+**Description:** As a developer, I want a skill that generates dependency-ordered task breakdowns with phase structure so that I can visualize implementation order.
+
+**Acceptance Criteria:**
+- [ ] SKILL.md created with task breakdown instructions
+- [ ] Skill generates phase structure (Setup → Foundation → Stories → Polish)
+- [ ] Tasks include IDs (T001+), phase markers, story labels [US1]
+- [ ] Parallel tasks marked with [P]
+- [ ] Each story independently testable
+- [ ] Saves to tasks.md in feature directory
+- [ ] Typecheck passes
+- [ ] Linter passes (0 warnings)
+
+---
+
+### US-009: Research Phase Support
+**Description:** As an agent, I want an optional research phase before implementation so that I can explore existing patterns and make better decisions.
+
+**Acceptance Criteria:**
+- [ ] UserStory schema has optional research field
+- [ ] Runner detects research flag and runs two-phase execution
+- [ ] Research phase saves findings to research/<story-id>.md
+- [ ] Second phase includes research findings in prompt
+- [ ] Prompt template updated with research instructions
+- [ ] Typecheck passes
+- [ ] Linter passes (0 warnings)
+
+---
+
+### US-010: Branch Management with Auto-Numbering
+**Description:** As a developer, I want features to have auto-generated numbers (001-feature-name) so that I can track them in order.
+
+**Acceptance Criteria:**
+- [ ] Scaffolder supports createFeature with autoNumber option
+- [ ] Feature directories created with 001- prefix when enabled
+- [ ] PRD branchName auto-generated with number prefix
+- [ ] listFeatures() returns numbered features correctly
+- [ ] Existing features without numbers still work
+- [ ] Typecheck passes
+- [ ] Linter passes (0 warnings)
+
+---
+
+### US-011: GitHub Issues Generator
+**Description:** As a team lead, I want to convert user stories to GitHub issues so that I can track work in GitHub Projects.
+
+**Acceptance Criteria:**
+- [ ] Command added to bin/relentless.ts
+- [ ] Issues.ts creates GitHub issues via gh CLI
+- [ ] Each story mapped to issue with proper formatting
+- [ ] Labels inferred from story type (database, ui, api, etc.)
+- [ ] Dependencies mapped to issue relationships
+- [ ] Safety: validates git remote matches before creating issues
+- [ ] Typecheck passes
+- [ ] Linter passes (0 warnings)
+- [ ] Verify in browser: Check created issues on GitHub