@arvorco/relentless 0.1.0

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

@@ -0,0 +1,228 @@
+# Project Constitution
+
+## 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.
+
+## Core Principles
+
+### Architecture
+
+**MUST** follow these architectural patterns:
+- Follow existing code structure and organization patterns
+- Keep modules focused and single-purpose
+- Use dependency injection where appropriate
+
+**SHOULD** consider these best practices:
+- Prefer composition over inheritance
+- Keep functions small and focused
+- Write self-documenting code
+
+### 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
+
+**SHOULD** strive for:
+- High test coverage (aim for >80%)
+- Clear, descriptive variable and function names
+- Comprehensive error handling
+
+### Version Control
+
+**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
+
+**SHOULD** maintain:
+- Clean commit history
+- Meaningful branch names
+- Updated documentation with code changes
+
+## Technology Stack
+
+### Language & Runtime
+
+- **TypeScript** - Primary language
+- **Bun** - Runtime environment (not Node.js)
+- **Zod** - Schema validation
+
+### Key Libraries
+
+- Commander - CLI parsing
+- Chalk - Terminal formatting
+- Execa - Process execution
+
+## File Organization
+
+```
+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
+
+### TypeScript
+
+**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** prefer:
+- Interface for public APIs
+- Type for unions and intersections
+- Explicit return types on public functions
+
+### 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
+
+### Testing
+
+**MUST** test:
+- Core business logic
+- Edge cases and error conditions
+- Integration points
+- CLI commands
+
+**SHOULD** test:
+- Helper functions
+- Utilities
+- Type guards
+
+## Documentation
+
+**MUST** document:
+- Public APIs and interfaces
+- Complex algorithms or logic
+- Breaking changes in commits
+- Setup and installation steps
+
+**SHOULD** document:
+- Configuration options
+- Architecture decisions
+- Common workflows
+- Troubleshooting steps
+
+## Security
+
+**MUST** ensure:
+- No secrets committed to git
+- Proper input validation
+- Safe file system operations
+- Minimal permissions required
+
+**SHOULD** consider:
+- Rate limiting where appropriate
+- Audit logs for sensitive operations
+- Security updates for dependencies
+
+## Performance
+
+**MUST** maintain:
+- Fast startup time (<1s)
+- Responsive CLI commands
+- Efficient file operations
+- Minimal memory footprint
+
+**SHOULD** optimize:
+- Parallel operations where safe
+- Caching for repeated operations
+- Lazy loading of heavy modules
+
+## Constraints
+
+### Dependencies
+
+**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
+
+### Backwards Compatibility
+
+**MUST**:
+- Maintain compatibility with existing PRDs
+- Provide migration paths for breaking changes
+- Version configuration formats
+
+**SHOULD**:
+- Deprecate features before removal
+- Provide clear upgrade documentation
+- Support at least 2 major versions
+
+## Agent-Specific Guidelines
+
+### For All Agents
+
+**MUST**:
+- Read progress.txt before starting work
+- Work on ONE story per iteration
+- 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
+- Document non-obvious decisions
+
+### Iteration Workflow
+
+1. Read PRD to find next incomplete story
+2. Read progress.txt for context and patterns
+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
+
+## Review and Updates
+
+This constitution should be:
+- **Reviewed** at project milestones
+- **Updated** when patterns emerge
+- **Referenced** in code reviews
+- **Enforced** in CI/CD pipelines
+
+---
+
+Last Updated: YYYY-MM-DD
+Version: 1.0.0

package/.claude/skills/implement/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: implement
+description: "Execute implementation workflow phase by phase. Use after analysis passes. Triggers on: start implementation, implement feature, begin coding."
+---
+
+# Implementation Workflow Executor
+
+Guide systematic implementation of features using the task breakdown.
+
+---
+
+## The Job
+
+Guide user through implementing tasks in correct order following dependencies.
+
+---
+
+## Prerequisites
+
+Before starting:
+- `/relentless.analyze` must pass (no CRITICAL issues)
+- All artifacts exist (spec, plan, tasks, checklist)
+- Constitution reviewed
+
+---
+
+## Implementation Flow
+
+### Phase 0: Setup
+1. Review `tasks.md` for setup tasks
+2. Install dependencies
+3. Create directory structure
+4. Initialize configuration
+
+### Phase 1: Foundation
+1. Implement data models
+2. Create base utilities
+3. Set up infrastructure
+4. Tests for foundation
+
+### Phase 2: User Stories
+For each story in dependency order:
+1. Read story acceptance criteria
+2. Implement functionality
+3. Write tests
+4. Run quality checks (typecheck, lint)
+5. Verify against checklist
+6. Commit changes
+7. Mark story complete in prd.json
+
+### Phase 3: Polish
+1. Performance optimization
+2. Error handling improvements
+3. Documentation
+4. Final quality checks
+
+---
+
+## Per-Story Workflow
+
+```markdown
+**Current:** US-001: Create User Registration Endpoint
+
+**Acceptance Criteria:**
+- [ ] POST /api/auth/register endpoint exists
+- [ ] Email validation works
+- [ ] Password requirements enforced
+- [ ] Password hashed before storage
+- [ ] Confirmation email sent
+- [ ] Returns 201 with user ID
+- [ ] Returns 400 for invalid input
+- [ ] Typecheck passes
+- [ ] Tests pass
+
+**Checklist Items:**
+- CHK-001: User table created
+- CHK-006: Password hashing uses bcrypt
+- CHK-011: Returns correct status codes
+
+**Steps:**
+1. Create endpoint handler
+2. Implement validation
+3. Add password hashing
+4. Integrate email service
+5. Write unit tests
+6. Write integration tests
+7. Run typecheck
+8. Run tests
+9. Verify checklist items
+10. Commit with message: "feat: US-001 - Create User Registration Endpoint"
+```
+
+---
+
+## Quality Gates
+
+Before marking story complete:
+- [ ] All acceptance criteria checked
+- [ ] Typecheck passes
+- [ ] Linter passes
+- [ ] Tests pass
+- [ ] Relevant checklist items verified
+- [ ] Code committed
+
+---
+
+## Progress Tracking
+
+Update `progress.txt` after each story:
+
+```markdown
+## 2026-01-11 - US-001
+- Implemented user registration endpoint
+- Added email validation and password hashing
+- Email service integration working
+- All tests passing
+
+**Learnings:**
+- Bcrypt cost factor 12 provides good balance
+- Email validation regex from validator.js works well
+- Nodemailer setup straightforward
+
+**Files Changed:**
+- src/api/auth/register.ts (new)
+- src/services/user.service.ts (new)
+- src/utils/password.ts (new)
+- tests/auth/register.test.ts (new)
+
+---
+```
+
+---
+
+## Notes
+
+- Work on ONE story at a time
+- Follow dependency order
+- Don't skip quality checks
+- Commit frequently
+- Update progress after each story
+- This is a guided workflow, not automated

package/.claude/skills/plan/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: plan
+description: "Generate technical implementation plan from feature specification. Use after creating spec. Triggers on: create plan, technical plan, implementation design."
+---
+
+# Technical Implementation Plan Generator
+
+Create detailed technical plans that translate feature specifications into implementation designs.
+
+---
+
+## The Job
+
+1. Read the feature specification (`spec.md`)
+2. Read project constitution for technical constraints
+3. Generate technical architecture and implementation plan
+4. Save to `plan.md` in the feature directory
+
+---
+
+## Step 1: Locate Feature Files
+
+Find the current feature directory:
+- Look in `relentless/features/` for the most recent feature
+- Or ask user which feature to plan
+- Verify `spec.md` exists
+
+---
+
+## Step 2: Load Context
+
+Read these files:
+1. **relentless/constitution.md** - Project governance and technical standards
+2. **relentless/features/NNN-feature/spec.md** - Feature requirements
+3. Project README or docs for tech stack information
+
+---
+
+## Step 3: Generate Technical Plan
+
+Using the template at `templates/plan-template.md`, create a plan with:
+
+### Required Sections:
+
+**1. Technical Overview**
+- Architecture approach
+- Key technologies to use (from constitution/existing stack)
+- Integration points
+
+**2. Data Models**
+- Database schemas
+- Entity relationships
+- Field definitions with types
+- Indexes and constraints
+
+**3. API Contracts**
+- Endpoints and methods
+- Request/response formats
+- Authentication requirements
+- Error responses
+
+**4. Implementation Strategy**
+- Phase breakdown
+- Dependencies between components
+- Integration approach
+
+**5. Testing Strategy**
+- Unit test approach
+- Integration test scenarios
+- E2E test cases
+- Test data requirements
+
+**6. Security Considerations**
+- Authentication/authorization
+- Data validation
+- Security best practices
+- Compliance requirements
+
+**7. Rollout Plan**
+- Deployment strategy
+- Migration requirements (if any)
+- Monitoring and observability
+- Rollback plan
+
+---
+
+## Step 4: Ensure Constitution Compliance
+
+Validate the plan against constitution:
+- **MUST** rules: Required, plan must follow these
+- **SHOULD** rules: Best practices, document any deviations
+
+If plan violates MUST rules, revise until compliant.
+
+---
+
+## Step 5: Save & Report
+
+1. Save plan to `relentless/features/NNN-feature/plan.md`
+2. Update progress.txt with plan creation timestamp
+3. Report:
+   - Plan location
+   - Key technical decisions
+   - Constitution compliance: PASS/FAIL
+   - Next step: `/relentless.tasks`
+
+---
+
+## Example Sections
+
+```markdown
+# Technical Implementation Plan: User Authentication
+
+## Technical Overview
+
+**Architecture:** Three-tier (API, Service, Data)
+**Stack:** Node.js, TypeScript, PostgreSQL
+**Authentication:** JWT tokens with refresh mechanism
+
+## Data Models
+
+### User Table
+\`\`\`sql
+CREATE TABLE users (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  email VARCHAR(255) UNIQUE NOT NULL,
+  password_hash VARCHAR(255) NOT NULL,
+  confirmed BOOLEAN DEFAULT FALSE,
+  created_at TIMESTAMP DEFAULT NOW(),
+  updated_at TIMESTAMP DEFAULT NOW()
+);
+
+CREATE INDEX idx_users_email ON users(email);
+\`\`\`
+
+## API Contracts
+
+### POST /api/auth/register
+**Request:**
+\`\`\`json
+{
+  "email": "user@example.com",
+  "password": "password123"
+}
+\`\`\`
+
+**Response (201):**
+\`\`\`json
+{
+  "id": "uuid",
+  "email": "user@example.com",
+  "message": "Confirmation email sent"
+}
+\`\`\`
+
+## Testing Strategy
+
+**Unit Tests:**
+- Password hashing utility
+- Email validation
+- Token generation/verification
+
+**Integration Tests:**
+- Full registration flow
+- Email sending
+- Database operations
+
+**E2E Tests:**
+- Complete user journey from signup to login
+```
+
+---
+
+## Notes
+
+- Plan bridges WHAT (spec) to HOW (implementation)
+- Include specific technologies and patterns
+- Must comply with constitution
+- Detailed enough for task generation

package/.claude/skills/plan/templates/plan-template.md

@@ -0,0 +1,104 @@
+# Implementation Plan: [FEATURE]
+
+**Branch**: `[###-feature-name]` | **Date**: [DATE] | **Spec**: [link]
+**Input**: Feature specification from `/specs/[###-feature-name]/spec.md`
+
+**Note**: This template is filled in by the `/relentless.plan` command. See `.specify/templates/commands/plan.md` for the execution workflow.
+
+## Summary
+
+[Extract from feature spec: primary requirement + technical approach from research]
+
+## Technical Context
+
+<!--
+  ACTION REQUIRED: Replace the content in this section with the technical details
+  for the project. The structure here is presented in advisory capacity to guide
+  the iteration process.
+-->
+
+**Language/Version**: [e.g., Python 3.11, Swift 5.9, Rust 1.75 or NEEDS CLARIFICATION]  
+**Primary Dependencies**: [e.g., FastAPI, UIKit, LLVM or NEEDS CLARIFICATION]  
+**Storage**: [if applicable, e.g., PostgreSQL, CoreData, files or N/A]  
+**Testing**: [e.g., pytest, XCTest, cargo test or NEEDS CLARIFICATION]  
+**Target Platform**: [e.g., Linux server, iOS 15+, WASM or NEEDS CLARIFICATION]
+**Project Type**: [single/web/mobile - determines source structure]  
+**Performance Goals**: [domain-specific, e.g., 1000 req/s, 10k lines/sec, 60 fps or NEEDS CLARIFICATION]  
+**Constraints**: [domain-specific, e.g., <200ms p95, <100MB memory, offline-capable or NEEDS CLARIFICATION]  
+**Scale/Scope**: [domain-specific, e.g., 10k users, 1M LOC, 50 screens or NEEDS CLARIFICATION]
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+[Gates determined based on constitution file]
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/[###-feature]/
+├── plan.md              # This file (/relentless.plan command output)
+├── research.md          # Phase 0 output (/relentless.plan command)
+├── data-model.md        # Phase 1 output (/relentless.plan command)
+├── quickstart.md        # Phase 1 output (/relentless.plan command)
+├── contracts/           # Phase 1 output (/relentless.plan command)
+└── tasks.md             # Phase 2 output (/relentless.tasks command - NOT created by /relentless.plan)
+```
+
+### Source Code (repository root)
+<!--
+  ACTION REQUIRED: Replace the placeholder tree below with the concrete layout
+  for this feature. Delete unused options and expand the chosen structure with
+  real paths (e.g., apps/admin, packages/something). The delivered plan must
+  not include Option labels.
+-->
+
+```text
+# [REMOVE IF UNUSED] Option 1: Single project (DEFAULT)
+src/
+├── models/
+├── services/
+├── cli/
+└── lib/
+
+tests/
+├── contract/
+├── integration/
+└── unit/
+
+# [REMOVE IF UNUSED] Option 2: Web application (when "frontend" + "backend" detected)
+backend/
+├── src/
+│   ├── models/
+│   ├── services/
+│   └── api/
+└── tests/
+
+frontend/
+├── src/
+│   ├── components/
+│   ├── pages/
+│   └── services/
+└── tests/
+
+# [REMOVE IF UNUSED] Option 3: Mobile + API (when "iOS/Android" detected)
+api/
+└── [same as backend above]
+
+ios/ or android/
+└── [platform-specific structure: feature modules, UI flows, platform tests]
+```
+
+**Structure Decision**: [Document the selected structure and reference the real
+directories captured above]
+
+## Complexity Tracking
+
+> **Fill ONLY if Constitution Check has violations that must be justified**
+
+| Violation | Why Needed | Simpler Alternative Rejected Because |
+|-----------|------------|-------------------------------------|
+| [e.g., 4th project] | [current need] | [why 3 projects insufficient] |
+| [e.g., Repository pattern] | [specific problem] | [why direct DB access insufficient] |