@arvorco/relentless 0.3.0 → 0.4.2

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

@@ -1,228 +1,309 @@
+<!-- TEMPLATE_VERSION: 2.1.0 -->
+<!-- LAST_UPDATED: 2026-01-20 -->
+
 # Project Constitution
 
+**Version:** 1.0.0
+**Ratified:** [DATE]
+**Last Amended:** [DATE]
+
+---
+
 ## Overview
 
-This document defines the governing principles, patterns, and constraints for this project. All agents and developers MUST follow these guidelines when working on the codebase.
+This document defines the governing principles, patterns, and constraints for this project. All AI agents and developers MUST follow these guidelines when working on the codebase.
+
+**This is a generic template.** Customize it for your project using `/relentless.constitution`.
+
+---
 
 ## Core Principles
 
-### Architecture
+### 1. Test-Driven Development (TDD)
+
+**MUST:**
+- Write tests BEFORE implementation code
+- Verify tests FAIL before writing implementation
+- All new features MUST have test coverage
+- All bug fixes MUST include regression tests
+- Tests MUST be part of acceptance criteria
+
+**SHOULD:**
+- Aim for >80% code coverage on critical paths
+- Write integration tests for API endpoints
+- Write E2E tests for user-facing flows
+- Use descriptive test names that document behavior
+
+**Rationale:** TDD ensures code correctness, documents behavior, and prevents regressions. Tests written first force clear thinking about requirements.
+
+---
+
+### 2. Quality Gates
+
+**MUST:**
+- All commits MUST pass typecheck with 0 errors
+- All commits MUST pass lint with 0 errors AND 0 warnings
+- All commits MUST pass tests
+- No debug code in production (console.log, debugger)
+- No unused imports or variables
+
+**SHOULD:**
+- Run quality checks locally before pushing
+- Fix lint warnings immediately, don't accumulate debt
+- Keep build times under reasonable limits
+
+**Rationale:** Quality gates catch issues early and maintain codebase health over time.
+
+---
+
+### 3. Code Architecture
 
-**MUST** follow these architectural patterns:
+**MUST:**
 - Follow existing code structure and organization patterns
 - Keep modules focused and single-purpose
-- Use dependency injection where appropriate
+- Avoid circular dependencies
+- Export types alongside implementations
 
-**SHOULD** consider these best practices:
+**SHOULD:**
 - Prefer composition over inheritance
-- Keep functions small and focused
+- Keep functions small and focused (<50 lines)
 - Write self-documenting code
+- Use meaningful names (no abbreviations)
 
-### Code Quality
-
-**MUST** maintain these quality standards:
-- All commits MUST pass typecheck with 0 errors
-- All commits MUST pass lint with 0 warnings
-- All new features MUST include appropriate tests
-- All code MUST be formatted consistently
+**Rationale:** Consistent architecture makes code predictable and maintainable.
 
-**SHOULD** strive for:
-- High test coverage (aim for >80%)
-- Clear, descriptive variable and function names
-- Comprehensive error handling
+---
 
-### Version Control
+### 4. Type Safety
 
-**MUST** follow these Git practices:
-- Write clear, descriptive commit messages
-- Reference user story IDs in commits: `feat: [US-XXX] - Description`
-- Keep commits focused and atomic
-- Do not commit broken code
+**MUST:**
+- Use strict TypeScript mode
+- No `any` type except in documented exceptional cases
+- Validate external input at system boundaries
+- Export type definitions for public APIs
 
-**SHOULD** maintain:
-- Clean commit history
-- Meaningful branch names
-- Updated documentation with code changes
+**SHOULD:**
+- Use Zod or similar for runtime validation
+- Prefer type inference over explicit annotations
+- Use discriminated unions for state machines
+- Document complex type constraints
 
-## Technology Stack
+**Rationale:** Type safety prevents runtime errors and improves developer experience.
 
-### Language & Runtime
+---
 
-- **TypeScript** - Primary language
-- **Bun** - Runtime environment (not Node.js)
-- **Zod** - Schema validation
+### 5. Version Control
 
-### Key Libraries
+**MUST:**
+- Write clear, descriptive commit messages
+- Reference user story IDs: `feat: [US-XXX] - Description`
+- Keep commits focused and atomic
+- Never commit broken code
+- Never commit secrets or credentials
 
-- Commander - CLI parsing
-- Chalk - Terminal formatting
-- Execa - Process execution
+**SHOULD:**
+- Use conventional commit format
+- Keep PR/MR size manageable (<500 lines)
+- Update documentation with code changes
+- Squash fixup commits before merge
 
-## File Organization
+**Rationale:** Good version control practices enable collaboration and debugging.
 
-```
-project/
-├── bin/              # CLI entry points
-├── src/              # Source code
-│   ├── agents/       # Agent adapters
-│   ├── config/       # Configuration
-│   ├── execution/    # Orchestration
-│   ├── init/         # Project scaffolding
-│   └── prd/          # PRD handling
-├── templates/        # Template files
-├── skills/           # Agent skills
-└── relentless/       # Relentless workspace
-    ├── config.json
-    ├── prompt.md
-    └── features/
-```
+---
 
-## Coding Standards
+### 6. Error Handling
 
-### TypeScript
+**MUST:**
+- Handle all error cases explicitly
+- Provide descriptive error messages
+- Validate input at system boundaries
+- Never swallow errors silently
 
-**MUST** follow:
-- Use strict TypeScript mode
-- Avoid `any` type - use `unknown` or proper types
-- Export types alongside implementations
-- Use Zod schemas for runtime validation
+**SHOULD:**
+- Include context in error messages
+- Use typed error classes
+- Provide recovery suggestions
+- Log errors with appropriate levels
 
-**SHOULD** prefer:
-- Interface for public APIs
-- Type for unions and intersections
-- Explicit return types on public functions
+**Rationale:** Proper error handling improves debugging and user experience.
 
-### Error Handling
-
-**MUST** implement:
-- Descriptive error messages
-- Proper error types
-- Validation at system boundaries
-- Graceful degradation where appropriate
+---
 
-**SHOULD** include:
-- Context in error messages
-- Recovery suggestions
-- Logging for debugging
+### 7. Documentation
 
-### Testing
+**MUST:**
+- Document public APIs and interfaces
+- Document breaking changes in commits
+- Keep README updated with setup instructions
+- Document non-obvious design decisions
 
-**MUST** test:
-- Core business logic
-- Edge cases and error conditions
-- Integration points
-- CLI commands
+**SHOULD:**
+- Document configuration options
+- Include usage examples
+- Document troubleshooting steps
+- Keep inline comments minimal but meaningful
 
-**SHOULD** test:
-- Helper functions
-- Utilities
-- Type guards
+**Rationale:** Documentation reduces onboarding time and prevents knowledge loss.
 
-## Documentation
+---
 
-**MUST** document:
-- Public APIs and interfaces
-- Complex algorithms or logic
-- Breaking changes in commits
-- Setup and installation steps
+### 8. Security
 
-**SHOULD** document:
-- Configuration options
-- Architecture decisions
-- Common workflows
-- Troubleshooting steps
+**MUST:**
+- Never commit secrets or credentials
+- Validate and sanitize user input
+- Use parameterized queries (no SQL injection)
+- Follow principle of least privilege
 
-## Security
+**SHOULD:**
+- Keep dependencies updated
+- Run security audits periodically
+- Use environment variables for configuration
+- Implement rate limiting for APIs
 
-**MUST** ensure:
-- No secrets committed to git
-- Proper input validation
-- Safe file system operations
-- Minimal permissions required
+**Rationale:** Security is non-negotiable and must be built in from the start.
 
-**SHOULD** consider:
-- Rate limiting where appropriate
-- Audit logs for sensitive operations
-- Security updates for dependencies
+---
 
-## Performance
+## Technology Stack
 
-**MUST** maintain:
-- Fast startup time (<1s)
-- Responsive CLI commands
-- Efficient file operations
-- Minimal memory footprint
+**Customize this section for your project:**
 
-**SHOULD** optimize:
-- Parallel operations where safe
-- Caching for repeated operations
-- Lazy loading of heavy modules
+### Language & Runtime
+- [Language] - Primary language
+- [Runtime] - Runtime environment
 
-## Constraints
+### Key Libraries
+- [Library 1] - Purpose
+- [Library 2] - Purpose
+- [Library 3] - Purpose
 
-### Dependencies
+### Quality Tools
+- [Linter] - Code linting
+- [Formatter] - Code formatting
+- [Test Framework] - Testing
 
-**MUST NOT**:
-- Add dependencies without justification
-- Include deprecated packages
-- Use packages with known security issues
+---
 
-**SHOULD**:
-- Prefer built-in solutions over dependencies
-- Keep dependencies minimal and focused
-- Regularly update dependencies
+## File Organization
 
-### Backwards Compatibility
+**Customize this section for your project:**
 
-**MUST**:
-- Maintain compatibility with existing PRDs
-- Provide migration paths for breaking changes
-- Version configuration formats
+```
+project/
+├── src/              # Source code
+│   ├── components/   # UI components (if applicable)
+│   ├── services/     # Business logic
+│   ├── utils/        # Utilities
+│   └── types/        # Type definitions
+├── tests/            # Test files
+├── docs/             # Documentation
+└── relentless/       # Relentless workspace
+    ├── config.json   # Configuration
+    ├── constitution.md
+    ├── prompt.md
+    └── features/     # Feature workspaces
+```
 
-**SHOULD**:
-- Deprecate features before removal
-- Provide clear upgrade documentation
-- Support at least 2 major versions
+---
 
 ## Agent-Specific Guidelines
 
-### For All Agents
+### For All AI Agents
 
-**MUST**:
-- Read progress.txt before starting work
+**MUST:**
+- Read spec.md and plan.md BEFORE starting work
+- Read only the relevant story section from tasks.md
 - Work on ONE story per iteration
+- Follow TDD - write tests first
+- Run ALL quality checks before committing
 - Update PRD after completing a story
 - Append learnings to progress.txt
-- Run all quality checks before committing
 
-**SHOULD**:
-- Review existing code before modifying
-- Follow established patterns
-- Ask questions when unclear
+**SHOULD:**
+- Review existing code patterns before modifying
+- Ask questions when requirements are unclear
 - Document non-obvious decisions
+- Keep commits small and focused
 
 ### Iteration Workflow
 
-1. Read PRD to find next incomplete story
-2. Read progress.txt for context and patterns
+1. Read spec.md, plan.md, checklist.md
+2. Find your story in tasks.md (only read that section)
 3. Review relevant existing code
-4. Implement the single story
-5. Run typecheck and lint
-6. Run tests if applicable
-7. Commit with proper message format
-8. Update PRD passes: true
-9. Append to progress.txt
-10. Check if all stories complete
+4. Write tests FIRST (TDD)
+5. Verify tests FAIL
+6. Implement minimum code to pass tests
+7. Run typecheck, lint, test
+8. Commit with proper message format
+9. Update PRD: `passes: true`
+10. Append to progress.txt
+11. Check if all stories complete
+
+---
+
+## Routing and Cost Optimization
+
+When using Relentless Auto Mode:
+
+**MUST:**
+- Respect routing decisions in prd.json
+- Report actual costs vs estimated costs
+- Not override routing without explicit permission
+
+**SHOULD:**
+- Use appropriate model for task complexity
+- Consider cost when choosing approaches
+- Track and report token usage
+
+**Modes:**
+- `free` - Free tier models only (~95% savings)
+- `cheap` - Budget models (~75% savings)
+- `good` - Balanced quality/cost (~50% savings)
+- `genius` - Premium models (no savings)
+
+---
+
+## Governance
+
+### Amendment Process
+
+1. Propose changes via PR
+2. Discuss with team
+3. Update version semantically:
+   - **MAJOR**: Breaking changes to principles
+   - **MINOR**: New principles added
+   - **PATCH**: Clarifications, typo fixes
+4. Update `Last Amended` date
+5. Document rationale for change
+
+### Compliance
+
+- Constitution is checked before each feature implementation
+- Violations should be flagged in code review
+- Repeated violations require team discussion
+- Emergency exceptions require documentation
+
+### Review Schedule
+
+- **Quarterly**: Full constitution review
+- **Per Feature**: Relevance check
+- **On Issues**: Investigate if constitution gap
+
+---
+
+## Customization Notes
+
+This template should be customized with:
 
-## Review and Updates
+1. **Technology Stack** - Your specific languages, frameworks, tools
+2. **File Organization** - Your project structure
+3. **Quality Commands** - Your actual typecheck, lint, test commands
+4. **Additional Principles** - Domain-specific rules
 
-This constitution should be:
-- **Reviewed** at project milestones
-- **Updated** when patterns emerge
-- **Referenced** in code reviews
-- **Enforced** in CI/CD pipelines
+Run `/relentless.constitution` to generate a personalized version.
 
 ---
 
-Last Updated: YYYY-MM-DD
-Version: 1.0.0
+**Template Version:** 2.0.0
+**Compatible with:** Relentless v0.2.0+

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

@@ -1,6 +1,9 @@
+<!-- TEMPLATE_VERSION: 2.1.0 -->
+<!-- LAST_UPDATED: 2026-01-20 -->
+
 # Relentless Agent Instructions
 
-You are an autonomous coding agent. Follow these instructions exactly.
+You are an autonomous coding agent orchestrated by Relentless. Follow these instructions exactly.
 
 **This is a generic template. Personalize it for your project using:**
 ```bash
@@ -9,26 +12,110 @@ You are an autonomous coding agent. Follow these instructions exactly.
 
 ---
 
+## 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.
+
+---
+
 ## Your Task (Per Iteration)
 
-1. Read `relentless/features/<feature>/prd.json`
-2. Read `relentless/features/<feature>/progress.txt`
-3. Check you're on the correct branch from PRD `branchName`
-4. Pick the **highest priority** story where `passes: false`
+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. Implement the story
-7. Run quality checks (typecheck, lint, test)
-8. If ALL checks pass, commit: `feat: [Story ID] - [Story Title]`
-9. Update PRD: set `passes: true`
-10. Append progress to `progress.txt`
+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`
 
 ---
 
-## Quality Requirements
+## TDD Workflow (MANDATORY)
+
+You MUST follow Test-Driven Development:
+
+```
+1. Write test → 2. Run test (MUST FAIL) → 3. Implement → 4. Run test (MUST PASS)
+```
+
+**Before implementing ANY code:**
+- Write unit tests for the functionality
+- Run tests to verify they FAIL
+- Then implement the minimum code to make them PASS
+
+**Tests are NOT optional.** Every story must have test coverage.
+
+---
 
-Before marking a story complete:
-- [ ] All quality checks pass (typecheck, lint, test)
-- [ ] Zero errors and zero warnings
+## Quality Gates (Non-Negotiable)
+
+Before marking ANY story as complete, run these commands:
+
+```bash
+# TypeScript check (customize for your project)
+bun run typecheck   # or: npx tsc --noEmit
+
+# Linting (customize for your project)
+bun run lint        # or: npx eslint .
+
+# Tests (customize for your project)
+bun test            # or: npm test
+```
+
+**ALL checks must pass with ZERO errors and ZERO warnings.**
+
+If ANY check fails:
+1. Fix the issue
+2. Re-run all checks
+3. Only then mark the story complete
+
+---
+
+## Routing Awareness
+
+Stories in `prd.json` may have routing metadata:
+
+```json
+{
+  "routing": {
+    "complexity": "medium",
+    "harness": "claude",
+    "model": "sonnet-4.5",
+    "estimatedCost": 0.0034
+  }
+}
+```
+
+**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
+
+After completion, execution history is saved for cost tracking.
+
+---
+
+## Checklist Validation
+
+Before completing a story, verify against `checklist.md`:
+
+- [ ] All acceptance criteria from tasks.md satisfied
+- [ ] Tests written and passing
+- [ ] Typecheck passes
+- [ ] Lint passes
 - [ ] No debug code (console.log, debugger)
 - [ ] No unused imports or variables
 - [ ] Follows existing patterns
@@ -37,12 +124,22 @@ Before marking a story complete:
 
 ## Progress Report Format
 
-APPEND to progress.txt:
-```
-## [Date/Time] - [Story ID]
+APPEND to `progress.txt` after each story:
+
+```markdown
+## [Date] - [Story ID]: [Story Title]
+
+**Completed:**
 - What was implemented
 - Files changed
-- Learnings for future iterations
+
+**Tests:**
+- Tests written and passing
+
+**Learnings:**
+- Patterns discovered
+- Gotchas for future iterations
+
 ---
 ```
 
@@ -52,12 +149,40 @@ APPEND to progress.txt:
 
 After completing a story, check if ALL stories have `passes: true`.
 
-If ALL complete:
+If ALL complete, output:
 ```
 <promise>COMPLETE</promise>
 ```
 
-Otherwise, end normally (next iteration continues).
+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
+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
 
 ---
 
@@ -70,3 +195,8 @@ This is the default template. You should personalize `relentless/prompt.md` with
 - Project-specific gotchas
 
 Run `/relentless.constitution` to generate a personalized prompt.
+
+---
+
+**Template Version:** 2.0.0
+**Compatible with:** Relentless v0.2.0+