@arvorco/relentless 0.1.20 → 0.1.22

package/relentless/constitution.md

@@ -0,0 +1,393 @@
+# Relentless Project Constitution
+
+**Version:** 2.0.0
+**Ratified:** 2026-01-13
+**Last Amended:** 2026-01-13
+
+---
+
+## Preamble
+
+Relentless is a universal AI agent orchestrator that empowers developers to run any AI coding agent autonomously until all tasks are complete. This constitution establishes the governing principles, patterns, and constraints that guide development and ensure Relentless remains performant, reliable, and cost-effective.
+
+Our mission is to build one of the best AI orchestration tools in the world - simple, genius, and efficient.
+
+---
+
+## Core Identity
+
+**Project:** Relentless
+**Organization:** Arvor
+**Purpose:** Universal AI Agent Orchestrator
+**Languages:** TypeScript (strict mode)
+**Runtime:** Bun (not Node.js)
+**License:** MIT
+
+---
+
+## Part I: Foundational Principles
+
+### Principle 1: Test-Driven Development (TDD)
+
+**MUST:**
+- All new features MUST have tests written BEFORE implementation begins
+- Tests MUST define expected behavior with clear assertions
+- Implementation MUST NOT proceed until failing tests exist
+- All tests MUST pass before any story is marked complete
+- E2E tests MUST exist for critical user workflows
+
+**SHOULD:**
+- Aim for >80% code coverage on new features
+- Write tests that serve as living documentation
+- Use property-based testing for complex logic
+- Include edge case tests for all boundary conditions
+
+**Rationale:** TDD prevents regressions in long autonomous runs where agents may introduce subtle bugs. Tests serve as contracts that agents must satisfy, providing fast feedback loops essential for AI-driven development. Reference: [Test-Driven Development with AI](https://www.builder.io/blog/test-driven-development-ai)
+
+---
+
+### Principle 2: Smart Model Routing
+
+**MUST:**
+- Planning phase MUST evaluate task complexity before assigning models
+- Each specification MUST ask user whether smart routing is desired
+- Routing decisions MUST be made at planning time, not runtime
+- Model/harness performance history MUST be tracked for future planning
+- Simple tasks MUST be routable to cheaper/free models when user opts in
+- Complex tasks and final reviews MUST use SOTA models (Opus 4.5, GPT-5-2, etc.)
+
+**SHOULD:**
+- Maintain a knowledge base of model/harness capabilities and strengths
+- Update routing heuristics based on observed task outcomes
+- Consider task dependencies when routing parallel work
+- Balance cost optimization with quality requirements
+
+**Rationale:** Different models excel at different tasks. Strategic routing saves costs (up to 75% reduction) while maintaining quality. SOTA models handle complex reasoning; lighter models handle boilerplate. Reference: [MasRouter](https://aclanthology.org/2025.acl-long.757.pdf), [Dynamic LLM Routing](https://arxiv.org/abs/2502.16696)
+
+---
+
+### Principle 3: Parallel Execution with Git Worktrees
+
+**MUST:**
+- Parallel tasks MUST use git worktrees for clean isolation
+- Each worktree MUST be on an independent branch
+- Merge strategy MUST be defined before parallel execution begins
+- Post-merge testing MUST validate combined implementations
+- Worktrees MUST be cleaned up after successful merge
+- Circular dependencies MUST be detected and prevented before parallelization
+
+**SHOULD:**
+- Limit parallel worktrees to prevent resource exhaustion
+- Prefer parallel execution for independent tasks only
+- Run integration tests after merging worktrees
+- Log all worktree operations for debugging
+
+**Rationale:** Git worktrees enable up to 50 agents working in parallel with clean isolation and easy merging. Cleanup prevents workspace pollution. Reference: [Parallelizing AI Coding Agents](https://ainativedev.io/news/how-to-parallelize-ai-coding-agents)
+
+---
+
+### Principle 4: Queued Prompts (Mid-Run Input)
+
+**MUST:**
+- Implement file-based queue (.queue.txt) for mid-run user input
+- Agents MUST check queue between iterations
+- Queued prompts MUST persist in memory for subsequent iterations
+- Queue MUST be processed in FIFO order
+- Acknowledge queued prompts in progress.txt
+
+**SHOULD:**
+- Support priority flags in queued messages
+- Allow queue inspection without modifying it
+- Clear processed items from queue after acknowledgment
+- Support structured commands (pause, skip, abort) in queue
+
+**Rationale:** Long autonomous runs need human intervention capability without interrupting the flow. File-based queues are simple, debuggable, and work across all agents. Reference: [Human-in-the-Loop Best Practices](https://learn.microsoft.com/en-us/azure/architecture/ai-ml/guide/ai-agent-design-patterns)
+
+---
+
+### Principle 5: Adaptive Final Review
+
+**MUST:**
+- Every feature MUST have a final review phase before completion
+- Review MUST be performed by SOTA model (Opus 4.5, GPT-5-2, or equivalent)
+- Review scope MUST adapt to feature size:
+  - Small features: Full codebase review in single context
+  - Large features: Multi-context review with summary aggregation
+- Review MUST check for: bugs, code quality, unnecessary artifacts, duplicate code, slop removal
+- Review findings MUST be documented and acted upon
+
+**SHOULD:**
+- Use automated pre-checks before SOTA review to optimize costs
+- Flag high-risk areas for deeper analysis
+- Generate review report with actionable items
+- Track review quality metrics over time
+
+**Rationale:** AI agents can produce "slop" - unnecessary code, duplications, or artifacts. A final expert review catches issues that accumulated over many iterations. Adaptive scoping ensures thoroughness without waste.
+
+---
+
+### Principle 6: Agent-Aware Best Practices
+
+**MUST:**
+- Maintain up-to-date knowledge of each agent's capabilities
+- Document agent-specific best practices and limitations
+- Respect agent rate limits with intelligent fallback
+- Use agent-appropriate prompting styles
+- Track agent performance for routing optimization
+
+**SHOULD:**
+- Auto-detect agent availability and health
+- Implement graceful degradation between agent tiers
+- Share learned patterns across agent runs via progress.txt
+- Monitor harness/model ecosystem for new capabilities
+
+**Rationale:** Each agent (Claude, Amp, OpenCode, Codex, Droid, Gemini) has unique strengths. Leveraging these differences maximizes effectiveness and minimizes costs. Reference: [AI Agent Orchestration Frameworks](https://blog.n8n.io/ai-agent-orchestration-frameworks/)
+
+---
+
+## Part II: Code Quality Standards
+
+### Principle 7: Zero-Lint Policy
+
+**MUST:**
+- All code MUST pass lint with zero warnings (not just errors)
+- All code MUST pass typecheck with zero errors
+- No subterfuges or workarounds to suppress legitimate lint issues
+- Fix lints properly as an expert developer (IQ 300 approach)
+- Run lint and typecheck before every commit
+
+**SHOULD:**
+- Configure strictest reasonable lint rules
+- Use automated formatting (Prettier, etc.)
+- Address lint issues immediately, not as technical debt
+
+**Rationale:** Clean code performs better and maintains clarity. Lint warnings often signal real issues that compound over time.
+
+---
+
+### Principle 8: TypeScript Strictness
+
+**MUST:**
+- Use TypeScript strict mode throughout
+- Avoid `any` type - use `unknown` or proper types
+- Export types alongside implementations
+- Use Zod schemas for runtime validation
+- Document complex type constraints
+
+**SHOULD:**
+- Prefer type inference where clear
+- Use interfaces for public APIs
+- Use types for unions/intersections
+- Add explicit return types on exported functions
+
+**Rationale:** Type safety prevents runtime errors and enables better tooling. Strict mode catches issues at compile time rather than production.
+
+---
+
+### Principle 9: Minimal Dependencies
+
+**MUST NOT:**
+- Add dependencies without clear justification
+- Include deprecated packages
+- Use packages with known security vulnerabilities
+
+**MUST:**
+- Prefer built-in solutions over external dependencies
+- Audit dependencies regularly
+- Pin versions for reproducibility
+
+**SHOULD:**
+- Consider bundle size impact
+- Evaluate maintenance status of dependencies
+- Prefer well-maintained, popular packages
+
+**Rationale:** Every dependency is a potential security risk, maintenance burden, and performance cost. Minimalism keeps the codebase lean and secure.
+
+---
+
+## Part III: Architecture Principles
+
+### Principle 10: Clean Architecture
+
+**MUST:**
+- Maintain clear separation of concerns
+- Keep modules focused and single-purpose
+- Use dependency injection for testability
+- Follow existing code structure patterns
+
+**SHOULD:**
+- Prefer composition over inheritance
+- Keep functions small and focused (<30 lines)
+- Write self-documenting code
+- Use meaningful names that reveal intent
+
+**Rationale:** Clean architecture enables parallel development, easier testing, and maintainable codebases. AI agents work better with well-organized code.
+
+---
+
+### Principle 11: Performance First
+
+**MUST:**
+- Maintain fast startup time (<1s)
+- Ensure responsive CLI commands
+- Optimize file operations for large codebases
+- Keep memory footprint minimal
+
+**SHOULD:**
+- Use lazy loading for heavy modules
+- Cache repeated operations
+- Profile performance regularly
+- Parallelize where safe
+
+**Rationale:** Performance directly impacts developer experience and agent efficiency. Slow tools waste time and money.
+
+---
+
+### Principle 12: Error Handling Excellence
+
+**MUST:**
+- Surface errors clearly - never hide failures
+- Provide descriptive error messages with context
+- Validate inputs at system boundaries
+- Implement graceful degradation
+
+**SHOULD:**
+- Include recovery suggestions in errors
+- Log errors with sufficient context for debugging
+- Use circuit breaker patterns for external dependencies
+- Consider error handling in design
+
+**Rationale:** Autonomous agents need clear error signals to self-correct. Hidden errors cause cascading failures in long runs. Reference: [AI Agent Error Handling](https://learn.microsoft.com/en-us/azure/architecture/ai-ml/guide/ai-agent-design-patterns)
+
+---
+
+## Part IV: Version Control & Documentation
+
+### Principle 13: Git Discipline
+
+**MUST:**
+- Write clear, descriptive commit messages
+- Reference story IDs: `feat: [US-XXX] - Description`
+- Keep commits focused and atomic
+- Never commit broken code
+- Never commit secrets
+
+**SHOULD:**
+- Maintain clean commit history
+- Use meaningful branch names
+- Squash WIP commits before merge
+- Update docs with code changes
+
+**Rationale:** Git history is memory for AI agents across iterations. Clean history enables better context and debugging.
+
+---
+
+### Principle 14: Documentation Standards
+
+**MUST:**
+- Document public APIs and interfaces
+- Document complex algorithms
+- Keep README up to date
+- Document breaking changes
+
+**SHOULD:**
+- Write self-documenting code first
+- Document "why" not just "what"
+- Keep docs in sync with code
+- Include troubleshooting guides
+
+**Rationale:** Documentation helps both humans and AI agents understand the codebase. Good docs reduce errors and speed up development.
+
+---
+
+## Part V: Security & Compliance
+
+### Principle 15: Security First
+
+**MUST:**
+- Never commit secrets to git
+- Validate all external inputs
+- Use safe file system operations
+- Follow principle of least privilege
+- Log sensitive operations
+
+**SHOULD:**
+- Regular dependency audits
+- Rate limiting where appropriate
+- Security-focused code review
+- Keep security patches current
+
+**Rationale:** Security vulnerabilities in orchestration tools can have wide-reaching impact. Proactive security prevents costly incidents.
+
+---
+
+## Part VI: Future Roadmap Principles
+
+The following are strategic directions that guide future development:
+
+### Cost & Metrics Dashboard
+- Investigate harness-specific methods for cost/usage tracking
+- Consider integration with existing tools like Claude Code's /status
+- Build unified dashboard when implementation path is clear
+
+### Enhanced Model Routing Intelligence
+- Build and maintain model capability knowledge base
+- Track task outcomes for routing optimization
+- Develop routing heuristics from empirical data
+
+### Extended Parallel Execution
+- Support for containerized agent isolation (future option)
+- Cross-worktree dependency management
+- Distributed execution across machines
+
+### Integration Ecosystem
+- GitHub Actions integration
+- CI/CD pipeline templates
+- IDE extensions for orchestration control
+
+---
+
+## Governance
+
+### Amendment Process
+
+1. **Propose:** Create PR with proposed changes
+2. **Discuss:** Gather feedback from team and community
+3. **Update:** Increment version semantically:
+   - **MAJOR:** Breaking changes to principles
+   - **MINOR:** New principles added
+   - **PATCH:** Clarifications, typo fixes
+4. **Document:** Record rationale for changes
+5. **Ratify:** Merge after approval
+
+### Compliance
+
+- Constitution checked before each feature implementation
+- Violations block story completion
+- Agents must reference constitution in progress.txt
+- Regular review at project milestones
+
+### Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 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 |
+
+---
+
+## References
+
+- [AI Agent Orchestration Frameworks](https://blog.n8n.io/ai-agent-orchestration-frameworks/)
+- [MasRouter: Learning to Route LLMs](https://aclanthology.org/2025.acl-long.757.pdf)
+- [Dynamic LLM Routing](https://arxiv.org/abs/2502.16696)
+- [Difficulty-Aware Agent Orchestration](https://arxiv.org/html/2509.11079v1)
+- [Parallelizing AI Coding Agents](https://ainativedev.io/news/how-to-parallelize-ai-coding-agents)
+- [Test-Driven Development with AI](https://www.builder.io/blog/test-driven-development-ai)
+- [TDD, AI agents and coding with Kent Beck](https://newsletter.pragmaticengineer.com/p/tdd-ai-agents-and-coding-with-kent)
+- [Azure AI Agent Design Patterns](https://learn.microsoft.com/en-us/azure/architecture/ai-ml/guide/ai-agent-design-patterns)
+- [LLM Cost Optimization Guide](https://futureagi.com/blogs/llm-cost-optimization-2025)
+
+---
+
+*This constitution is the foundation for all Relentless development. Reference it during specification, planning, and implementation.*

package/relentless/prompt.md

@@ -1,22 +1,76 @@
 # Relentless Agent Instructions
 
-You are an autonomous coding agent working on a software project.
+You are an autonomous coding agent working on the Relentless project - a universal AI agent orchestrator.
+
+---
+
+## CRITICAL: Quality Gates (Non-Negotiable)
+
+Before marking ANY story as complete, ALL checks must pass:
+
+```bash
+# TypeScript strict mode check
+bun run typecheck
+
+# ESLint with zero warnings policy
+bun run lint
+
+# All tests must pass
+bun test
+```
+
+**If ANY check fails, DO NOT mark the story as complete. Fix the issues first.**
+
+---
 
 ## Before You Start
 
-1. **Review the codebase** - Understand the current state, architecture, and patterns
-2. **Read progress.txt** - Check the Codebase Patterns section for learnings from previous iterations
-3. **Read the PRD** - Understand what needs to be done
+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 PRD** - Understand what needs to be done
+5. **Check the Queue** - Look for `.queue.txt` for any mid-run user input
+
+---
 
 ## Your Task
 
 1. Read the PRD at `relentless/features/<feature>/prd.json`
 2. Read the progress log at `relentless/features/<feature>/progress.txt`
 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`
+4. Pick the **highest priority** user story where `passes: false` and all dependencies are met
 5. **Review relevant code** before implementing - understand existing patterns
 
-### Research Phase (if story has `research: true`)
+---
+
+## TDD Workflow (MANDATORY)
+
+Relentless follows strict Test-Driven Development. For EVERY story:
+
+### Step 1: Write Failing Tests First
+```bash
+# Create test file if needed
+# Write tests that define expected behavior
+bun test  # Tests MUST fail (red phase)
+```
+
+### Step 2: Implement Minimum Code
+```bash
+# Write only enough code to pass tests
+bun test  # Tests MUST pass (green phase)
+```
+
+### Step 3: Refactor
+```bash
+# Clean up while keeping tests green
+bun test  # Tests MUST still pass
+```
+
+**Do NOT skip TDD. Tests are contracts that validate your implementation.**
+
+---
+
+## Research Phase (if story has `research: true`)
 
 If the current story has `research: true` and no research file exists yet:
 
@@ -30,50 +84,167 @@ If the current story has `research: true` and no research file exists yet:
 3. **Do NOT implement** - only research and document
 4. Save your findings to the research file and end your turn
 
-### Implementation Phase
+---
+
+## Implementation Phase
 
 If research findings exist (or research is not required):
 
-6. Implement that single user story (using research findings if available)
-7. Run quality checks (typecheck, lint, test - whatever your project requires)
-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 `relentless/features/<feature>/progress.txt`
+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 the PRD to set `passes: true` for the completed story
+6. Append your progress to `relentless/features/<feature>/progress.txt`
+
+---
+
+## Check for Queued Prompts
+
+Between iterations, check `.queue.txt` for user input:
+
+```bash
+# If .queue.txt exists, read and process it
+# Acknowledge in progress.txt
+# Process in FIFO order
+```
+
+---
 
 ## Progress Report Format
 
 APPEND to progress.txt (never replace, always append):
+
 ```
 ## [Date/Time] - [Story ID]
 - What was implemented
 - Files changed
+- Tests added/modified
 - **Learnings for future iterations:**
   - Patterns discovered
   - Gotchas encountered
   - Useful context
+- **Constitution compliance:** [list principles followed]
 ---
 ```
 
+---
+
 ## 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
-- Review code before modifying it
+### 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
+```
+relentless/
+├── bin/              # CLI entry point (relentless.ts)
+├── src/              # Core TypeScript implementation
+│   ├── agents/       # Agent adapters (claude, amp, opencode, codex, droid, gemini)
+│   ├── config/       # Configuration schema and loading
+│   ├── prd/          # PRD parsing and validation
+│   ├── execution/    # Orchestration loop and routing
+│   └── init/         # Project initialization scaffolder
+├── templates/        # Templates copied to projects on init
+├── .claude/          # Skills and commands
+│   ├── skills/       # Skill implementations
+│   └── commands/     # Command wrappers
+└── relentless/       # Relentless workspace
+    ├── config.json
+    ├── constitution.md
+    ├── prompt.md
+    └── features/
+```
+
+### Key Technologies
+- **Runtime:** Bun (NOT Node.js)
+- **Language:** TypeScript (strict mode)
+- **Validation:** Zod schemas
+- **CLI:** Commander
+- **Formatting:** Chalk
+- **UI:** Ink (React for CLI)
+
+### Test File Patterns
+- Unit tests: `*.test.ts` alongside source files
+- Integration tests: `tests/integration/`
+- E2E tests: `tests/e2e/`
+
+---
+
+## Agent-Specific Guidelines
+
+### Rate Limit Awareness
+- If you hit rate limits, note in progress.txt for future planning
+- Relentless will auto-fallback to other agents when limits hit
+
+### Model Routing Notes
+- Simple tasks: Cheaper models acceptable
+- Complex logic: Use capable models
+- Final reviews: Always use SOTA models (Opus 4.5, GPT-5-2)
+
+### Parallel Execution
+- Tasks marked `[P]` in tasks.md can run in parallel
+- Use git worktrees for parallel work
+- Clean up worktrees after merge
+- Run integration tests after merging parallel work
+
+---
+
+## Common Pitfalls 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
+7. **Using Node.js APIs** - Use Bun APIs instead
+8. **Adding unnecessary dependencies** - Prefer built-in solutions
+
+---
 
 ## 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>
+`<promise>COMPLETE</promise>`
 
 If there are still stories with `passes: false`, end your response normally (another iteration will pick up the next story).
 
-## Important
+---
+
+## Important Reminders
 
 - Work on ONE story per iteration
+- Write tests BEFORE implementation (TDD)
 - Review existing code before implementing
-- Commit frequently
-- Keep CI green
+- Commit frequently with proper message format
+- Keep all quality checks passing
+- Check `.queue.txt` for mid-run input
+- Reference constitution principles in progress.txt
+- Clean up any worktrees after merging
+
+---
+
+**Personalized for Relentless**
+**Generated:** 2026-01-13
+**Re-generate:** /relentless.constitution