@arvorco/relentless 0.3.1 → 0.4.2

package/MANUAL.md

@@ -0,0 +1,40 @@
+# Manual
+
+## Introduction
+
+Relentless is a universal AI agent orchestrator that automates software development by running AI coding agents in a loop until all tasks are complete. It provides structured workflows for specification, planning, testing, and quality enforcement across multiple AI platforms including Claude, Amp, OpenCode, Codex, Droid, and Gemini. The system handles complexity classification, cost optimization through smart model routing, automatic fallback on rate limits, and maintains progress through git commits and persistent state files.
+
+## Quickstart
+
+- Read the README.md to understand the project overview and installation steps
+- Review the constitution.md file to learn about project governance principles
+- Explore the features directory to see existing example specifications and plans
+- Check the documentation in docs/ for detailed setup guides and agent-specific instructions
+- Review example test cases in the tests/ directory to understand testing patterns
+
+## Usage Examples
+
+- Authenticate users securely by implementing OAuth2 with proper token storage and refresh mechanisms
+- Migrate existing authentication systems by replacing hardcoded credentials with OAuth2 flows and updating authorization endpoints
+
+## Troubleshooting
+
+- Tasks are not starting despite configuration being correct
+- Agent stops mid-task without completing
+- Multiple agents hitting rate limits simultaneously
+- Progress file is not updating after iterations complete
+- Tests are failing but implementation appears correct
+- Concurrent tasks are conflicting or overwriting each other
+
+## Glossary
+
+- Auto Mode: Smart routing system that selects optimal models based on task complexity and cost settings
+- Escalation: Automatic retry with more capable models when tasks fail with smaller models
+- Fallback: Switching to alternative AI agents when current agent hits rate limits or becomes unavailable
+- Harness: The adapter layer that connects Relentless to specific AI agents like Claude, Amp, or Codex
+- Smoke Test: Simple validation tasks that verify basic functionality without requiring complex logic changes
+- Mode: Cost optimization preset that determines which models are used for different complexity levels
+
+## Support
+
+For questions, bug reports, or feature requests, please use the GitHub Issues page at https://github.com/ArvorCo/Relentless/issues. This is the primary support channel for the Relentless project where you can search existing discussions or create new issues to get help from the community and maintainers.

package/README.md

@@ -10,7 +10,9 @@
 [![GitHub](https://img.shields.io/badge/GitHub-ArvorCo%2FRelentless-blue?logo=github)](https://github.com/ArvorCo/Relentless)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-[Quick Start](#quick-start) · [Why Relentless?](#from-ralph-to-relentless) · [Supported Agents](#supported-agents) · [Documentation](#cli-reference)
+**🆕 Smart Auto Mode: Save 50-75% on AI costs by routing tasks to the right model**
+
+[Quick Start](#quick-start) · [Auto Mode](#auto-mode) · [Why Relentless?](#from-ralph-to-relentless) · [Supported Agents](#supported-agents) · [Documentation](#cli-reference)
 
 </div>
 
@@ -98,6 +100,26 @@ cd your-project
 relentless init
 ```
 
+After upgrading Relentless, rerun `/relentless.constitution` to refresh `relentless/prompt.md` with the latest instructions (including spec/plan/tasks awareness).
+
+### Upgrading from Previous Versions
+
+If you have Relentless installed from before v0.4.0:
+
+1. Update the package:
+   ```bash
+   bun install -g @arvorco/relentless
+   # or: npm install -g @arvorco/relentless
+   ```
+
+2. **Important:** Re-run the constitution command to get updated templates:
+   ```bash
+   /relentless.constitution
+   ```
+
+   This will detect changes and offer upgrade options for your
+   constitution.md and prompt.md files.
+
 ### 3. Create a Feature
 
 **With Claude Code, Amp, or OpenCode** (recommended):
@@ -105,11 +127,11 @@ relentless init
 # Create constitution + personalized prompt (do this once per project)
 /relentless.constitution
 
-# Create feature
+# Create feature (tasks now auto-generates prd.json!)
 /relentless.specify Add user authentication with OAuth2
 /relentless.plan I'm using React, TypeScript, PostgreSQL
-/relentless.tasks
-/relentless.checklist
+/relentless.tasks              # Auto-converts to prd.json
+/relentless.analyze            # Validate consistency
 ```
 
 **With Codex, Droid, or Gemini** (manual workflow):
@@ -117,12 +139,13 @@ relentless init
 relentless features create user-auth
 # Then prompt your agent to create spec.md, plan.md, tasks.md
 # Or reference .claude/skills/*/SKILL.md for format
+relentless convert relentless/features/001-user-auth/tasks.md --feature 001-user-auth
 ```
 
 ### 4. Run
 
 ```bash
-relentless convert relentless/features/001-user-auth/tasks.md --feature 001-user-auth
+# Auto mode is now the default (use --agent <harness> to opt out)
 relentless run --feature 001-user-auth --tui
 ```
 
@@ -130,6 +153,147 @@ Watch the beautiful TUI as your agent works through each task, commits code, and
 
 ---
 
+## CLI Reference
+
+### Run Command
+
+```bash
+relentless run --feature <name> [options]
+```
+
+Options:
+- `--agent <harness>`: Force a specific harness (`auto`, `claude`, `amp`, `opencode`, `codex`, `droid`, `gemini`).
+- `--mode <mode>`: Auto mode cost tier (`free`, `cheap`, `good`, `genius`).
+- `--fallback-order <list>`: Comma-separated harness order for auto fallback.
+- `--max-iterations <n>`: Limit loop iterations (default: 20).
+- `--skip-review`: Skip final review phase.
+- `--review-mode <mode>`: Review quality tier (`free`, `cheap`, `good`, `genius`).
+- `--dry-run`: Show routing and planning without executing agents.
+- `--tui`: Run the interactive terminal UI.
+- `--dir <path>`: Working directory for the run.
+
+### Estimate Command
+
+```bash
+relentless estimate --feature <name> [--mode <mode>] [--compare]
+```
+
+Options:
+- `--mode <mode>`: Cost tier for estimation (`free`, `cheap`, `good`, `genius`).
+- `--compare`: Compare all modes side by side.
+
+### Other Useful Commands
+
+```bash
+relentless init
+relentless convert <tasks.md> --feature <name>
+relentless agents list
+relentless agents doctor
+```
+
+## Auto Mode
+
+**Smart routing saves 50-75% on AI costs** by matching task complexity to the right model.
+Auto mode is now enabled by default and becomes the default agent. If you want to force a specific harness, pass `--agent` explicitly.
+
+Auto Mode is designed to keep you productive: simple tasks run fast on cheaper models, while hard problems automatically route to stronger models (or escalate when needed). That means fewer reruns, lower spend, and faster end-to-end throughput on real features.
+
+### Default Behavior
+
+- `relentless run` uses auto routing unless you pass `--agent <harness>`
+- Auto mode uses your `relentless/config.json` defaults for `defaultMode`, fallback order, and model overrides
+- You can still lock a harness per run (e.g., `--agent codex`)
+
+### Four Cost Modes
+
+| Mode | Model Selection | Best For |
+|------|-----------------|----------|
+| **free** | OpenCode free models | Maximum savings, simple tasks |
+| **cheap** | Haiku 4.5, Gemini Flash, GPT-5.2 (reasoning-effort low) | Good balance, most tasks |
+| **good** | Sonnet 4.5 (default) | Quality-focused development |
+| **genius** | Opus 4.5, GPT-5.2 (reasoning-effort xhigh) | Complex architecture, critical tasks |
+
+Notes:
+- Droid has no free-tier models, so it only appears in paid modes.
+
+### Cost Savings Example
+
+Running a 10-story feature with mixed complexity:
+
+| Mode | Estimated Cost | Savings |
+|------|----------------|---------|
+| genius | $2.50 | — |
+| good | $1.20 | 52% |
+| cheap | $0.60 | 76% |
+| free | $0.00 | 100% |
+
+### Usage
+
+```bash
+# Run with specific mode (auto routing)
+relentless run --feature my-feature --mode cheap
+
+# Force a specific harness (disables auto routing)
+relentless run --feature my-feature --agent claude
+
+# Override fallback order (auto mode only)
+relentless run --feature my-feature --fallback-order opencode,droid,claude
+
+# Skip final review (not recommended)
+relentless run --feature my-feature --skip-review
+
+# Custom review mode
+relentless run --feature my-feature --review-mode genius
+
+# Tune idle timeout (milliseconds) for stuck/quiet harnesses
+RELENTLESS_EXECUTION_TIMEOUT_MS=120000 relentless run --feature my-feature
+```
+
+### How It Works
+
+1. **Classification**: Each task is analyzed for complexity (simple, medium, complex, expert)
+2. **Routing**: Task is assigned to the optimal model for its complexity and selected mode
+3. **Execution**: Agent attempts the task with the assigned model
+4. **Escalation**: If the task fails, automatically escalate to a more capable model
+5. **Reporting**: Final cost report shows actual vs estimated costs
+
+### Escalation Path
+
+When a smaller model fails, Relentless automatically escalates:
+
+```
+haiku-4.5 → sonnet-4.5 → opus-4.5
+glm-4.7 → haiku-4.5 → sonnet-4.5
+gpt-5.2-low → gpt-5.2-medium → gpt-5.2-high → gpt-5.2-xhigh (maps to `--model gpt-5.2 -c reasoning_effort="low|medium|high|xhigh"` in Codex CLI)
+```
+
+The system tracks costs across all attempts and reports total spend.
+
+### Configuration (relentless/config.json)
+
+```json
+{
+  "defaultAgent": "auto",
+  "autoMode": {
+    "enabled": true,
+    "defaultMode": "good",
+    "fallbackOrder": ["claude", "codex", "droid", "opencode", "amp", "gemini"],
+    "modeModels": {
+      "simple": "haiku-4.5",
+      "medium": "sonnet-4.5",
+      "complex": "opus-4.5",
+      "expert": "opus-4.5"
+    }
+  }
+}
+```
+
+Notes:
+- `defaultAgent: "auto"` makes auto routing the default; set to `claude`, `codex`, etc. to opt out.
+- `autoMode.enabled` only affects auto routing; it does not force auto unless `defaultAgent` is `auto`.
+
+---
+
 ## Key Features
 
 ### 🔄 Universal Agent Orchestration
@@ -141,11 +305,11 @@ No more vague PRDs. Interactive `/relentless.specify` creates comprehensive spec
 ### 🧪 Quality Enforcement
 TDD is not optional. E2E tests are not optional. Every story must pass typecheck. Constitution rules (MUST/SHOULD) are enforced. Checklists are loaded into agent prompts.
 
-### 💰 Cost-Aware Routing
-Why use GPT-5-Pro or Opus 4.5 to rename a variable? Route tasks by complexity. Save money. Ship faster.
+### 💰 Smart Auto Mode — Save 50-75%
+Why use GPT-5-Pro or Opus 4.5 to rename a variable? Four cost modes (free, cheap, good, genius) route tasks by complexity. Automatic escalation when smaller models fail. Save money. Ship faster.
 
 ### 📊 Beautiful TUI
-Real-time progress bars, dynamic story grid that adapts to terminal size, priority badges, phase indicators, research markers. Know exactly what's happening.
+Real-time progress bars, dynamic story grid that adapts to terminal size, priority badges, phase indicators, research markers. Auto mode now shows the current routing decision and idle time per story.
 
 ### 🔀 Dependency Management
 Stories can depend on other stories. Relentless validates, detects circular dependencies, and executes in the correct order.
@@ -168,6 +332,13 @@ Stories can depend on other stories. Relentless validates, detects circular depe
 
 All agents get skills/instructions installed automatically via `relentless init`.
 
+### Harness Tips
+
+- OpenCode: we enable `--print-logs` by default to keep output flowing.
+- Codex: GPT-5.2 reasoning tiers map to `--model gpt-5.2 -c reasoning_effort="low|medium|high|xhigh"`.
+- Droid: supports `--reasoning-effort` and `--auto` autonomy levels; use `--agent droid` to force it.
+- Gemini: non-interactive runs use `--prompt`; set `GEMINI_API_KEY` (or Vertex/GCA flags) for auth.
+
 ```bash
 # Check what's installed
 relentless agents list
@@ -209,6 +380,23 @@ your-project/
 
 ## The Workflow
 
+Relentless uses a simplified 5-step SpecKit workflow:
+
+| Step | Command | Output |
+|------|---------|--------|
+| 1. Specify | `/relentless.specify` | spec.md |
+| 2. Plan | `/relentless.plan` | plan.md |
+| 3. Tasks | `/relentless.tasks` | tasks.md + prd.json (auto) |
+| 4. Analyze | `/relentless.analyze` | Validation report |
+| 5. Implement | `relentless run --tui` | Working code |
+
+**Optional:** `/relentless.checklist` (between tasks and analyze)
+- Generates validation checklist with quality gates
+- Recommended for complex features
+
+> **Note:** The `tasks` command now auto-runs `convert`.
+> Manual `relentless convert` is only needed if you edit tasks.md by hand.
+
 ```
 ┌─────────────────────────────────────────────────────────────┐
 │                                                             │
@@ -218,9 +406,9 @@ your-project/
 │            ↓                                                │
 │   /relentless.plan          →  Technical architecture       │
 │            ↓                                                │
-│   /relentless.tasks         →  Dependency-ordered stories   │
+│   /relentless.tasks         →  Stories + prd.json (auto)    │
 │            ↓                                                │
-│   /relentless.checklist     →  Quality validation items     │
+│   /relentless.analyze       →  Validate consistency         │
 │            ↓                                                │
 │   relentless run --tui      →  Agent loops until complete   │
 │            ↓                                                │
@@ -240,6 +428,12 @@ relentless init                              # Initialize project
 relentless run --feature <name> --tui        # Run orchestration
 relentless status --feature <name>           # Show progress
 relentless reset <story-id> --feature <name> # Re-run a story
+
+# Auto Mode options
+relentless run --feature <name> --mode <free|cheap|good|genius>
+relentless run --feature <name> --fallback-order claude,opencode,amp
+relentless run --feature <name> --skip-review
+relentless run --feature <name> --review-mode <free|cheap|good|genius>
 ```
 
 ### Feature Management
@@ -295,6 +489,34 @@ relentless agents doctor                     # Health check
       "dangerouslyAllowAll": true
     }
   },
+  "autoMode": {
+    "enabled": true,
+    "defaultMode": "good",
+    "fallbackOrder": ["claude", "codex", "droid", "opencode", "amp", "gemini"],
+    "modeModels": {
+      "simple": "haiku-4.5",
+      "medium": "sonnet-4.5",
+      "complex": "opus-4.5",
+      "expert": "opus-4.5"
+    },
+    "review": {
+      "promptUser": true,
+      "defaultMode": "good",
+      "microTasks": ["typecheck", "lint", "test", "security", "quality", "docs"],
+      "maxRetries": 3
+    },
+    "escalation": {
+      "enabled": true,
+      "maxAttempts": 3,
+      "escalationPath": {
+        "haiku-4.5": "sonnet-4.5",
+        "sonnet-4.5": "opus-4.5",
+        "gpt-5.2-low": "gpt-5.2-medium",
+        "gpt-5.2-medium": "gpt-5.2-high",
+        "gpt-5.2-high": "gpt-5.2-xhigh"
+      }
+    }
+  },
   "fallback": {
     "enabled": true,
     "priority": ["claude", "amp", "opencode", "codex", "gemini"],
@@ -312,6 +534,18 @@ relentless agents doctor                     # Health check
 }
 ```
 
+### Auto Mode Settings
+
+| Setting | Description | Default |
+|---------|-------------|---------|
+| `autoMode.enabled` | Enable smart routing | `true` |
+| `autoMode.defaultMode` | Default cost mode | `"good"` |
+| `autoMode.fallbackOrder` | Harness priority order | `["claude", "codex", ...]` |
+| `autoMode.modeModels` | Model per complexity | See above |
+| `autoMode.escalation.enabled` | Enable auto-escalation | `true` |
+| `autoMode.escalation.maxAttempts` | Max escalation attempts | `3` |
+| `autoMode.review.microTasks` | Review checks to run | `["typecheck", "lint", ...]` |
+
 ---
 
 ## How It Works
@@ -373,6 +607,24 @@ Make criteria **verifiable**:
 | PRD not found | `relentless convert <file> --feature <name>` |
 | Max iterations reached | Increase `--max-iterations` or split stories |
 | Skills not found | `relentless init --force` to reinstall |
+| High escalation rate | Tasks may be underclassified; try `--mode good` |
+| All harnesses rate limited | Wait for reset or add API keys for more harnesses |
+| Cost higher than expected | Check escalation history in `prd.json` |
+| Free mode failing | Some tasks require paid models; try `--mode cheap` |
+
+### Auto Mode FAQ
+
+**Q: Why did my task use Opus when I set `--mode cheap`?**
+A: Cheap mode assigns initial models, but escalation can upgrade to more capable models if the task fails repeatedly. Check `prd.json` for escalation history.
+
+**Q: How accurate are cost estimates?**
+A: Estimates include a 12% buffer for potential escalation. Actual costs may be lower if tasks succeed on first try.
+
+**Q: Can I disable escalation?**
+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.
 
 ---