@arvorco/relentless 0.1.0

package/.claude/skills/specify/templates/spec-template.md

@@ -0,0 +1,115 @@
+# Feature Specification: [FEATURE NAME]
+
+**Feature Branch**: `[###-feature-name]`  
+**Created**: [DATE]  
+**Status**: Draft  
+**Input**: User description: "$ARGUMENTS"
+
+## User Scenarios & Testing *(mandatory)*
+
+<!--
+  IMPORTANT: User stories should be PRIORITIZED as user journeys ordered by importance.
+  Each user story/journey must be INDEPENDENTLY TESTABLE - meaning if you implement just ONE of them,
+  you should still have a viable MVP (Minimum Viable Product) that delivers value.
+  
+  Assign priorities (P1, P2, P3, etc.) to each story, where P1 is the most critical.
+  Think of each story as a standalone slice of functionality that can be:
+  - Developed independently
+  - Tested independently
+  - Deployed independently
+  - Demonstrated to users independently
+-->
+
+### User Story 1 - [Brief Title] (Priority: P1)
+
+[Describe this user journey in plain language]
+
+**Why this priority**: [Explain the value and why it has this priority level]
+
+**Independent Test**: [Describe how this can be tested independently - e.g., "Can be fully tested by [specific action] and delivers [specific value]"]
+
+**Acceptance Scenarios**:
+
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+2. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+---
+
+### User Story 2 - [Brief Title] (Priority: P2)
+
+[Describe this user journey in plain language]
+
+**Why this priority**: [Explain the value and why it has this priority level]
+
+**Independent Test**: [Describe how this can be tested independently]
+
+**Acceptance Scenarios**:
+
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+---
+
+### User Story 3 - [Brief Title] (Priority: P3)
+
+[Describe this user journey in plain language]
+
+**Why this priority**: [Explain the value and why it has this priority level]
+
+**Independent Test**: [Describe how this can be tested independently]
+
+**Acceptance Scenarios**:
+
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+---
+
+[Add more user stories as needed, each with an assigned priority]
+
+### Edge Cases
+
+<!--
+  ACTION REQUIRED: The content in this section represents placeholders.
+  Fill them out with the right edge cases.
+-->
+
+- What happens when [boundary condition]?
+- How does system handle [error scenario]?
+
+## Requirements *(mandatory)*
+
+<!--
+  ACTION REQUIRED: The content in this section represents placeholders.
+  Fill them out with the right functional requirements.
+-->
+
+### Functional Requirements
+
+- **FR-001**: System MUST [specific capability, e.g., "allow users to create accounts"]
+- **FR-002**: System MUST [specific capability, e.g., "validate email addresses"]  
+- **FR-003**: Users MUST be able to [key interaction, e.g., "reset their password"]
+- **FR-004**: System MUST [data requirement, e.g., "persist user preferences"]
+- **FR-005**: System MUST [behavior, e.g., "log all security events"]
+
+*Example of marking unclear requirements:*
+
+- **FR-006**: System MUST authenticate users via [NEEDS CLARIFICATION: auth method not specified - email/password, SSO, OAuth?]
+- **FR-007**: System MUST retain user data for [NEEDS CLARIFICATION: retention period not specified]
+
+### Key Entities *(include if feature involves data)*
+
+- **[Entity 1]**: [What it represents, key attributes without implementation]
+- **[Entity 2]**: [What it represents, relationships to other entities]
+
+## Success Criteria *(mandatory)*
+
+<!--
+  ACTION REQUIRED: Define measurable success criteria.
+  These must be technology-agnostic and measurable.
+-->
+
+### Measurable Outcomes
+
+- **SC-001**: [Measurable metric, e.g., "Users can complete account creation in under 2 minutes"]
+- **SC-002**: [Measurable metric, e.g., "System handles 1000 concurrent users without degradation"]
+- **SC-003**: [User satisfaction metric, e.g., "90% of users successfully complete primary task on first attempt"]
+- **SC-004**: [Business metric, e.g., "Reduce support tickets related to [X] by 50%"]

package/.claude/skills/tasks/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: tasks
+description: "Generate dependency-ordered user stories and tasks from plan. Use after creating plan. Triggers on: create tasks, generate user stories, break down implementation."
+---
+
+# User Story & Task Generator
+
+Generate actionable, dependency-ordered user stories from technical plans.
+
+---
+
+## The Job
+
+1. Read spec.md and plan.md
+2. Extract user stories from spec
+3. Break down into implementation tasks
+4. Order by dependencies
+5. Create tasks.md with structured user stories
+
+**Important:** tasks.md contains the actual user stories that convert to prd.json!
+
+---
+
+## Step 1: Locate Feature Files
+
+Find the current feature directory and verify:
+- `spec.md` exists
+- `plan.md` exists
+- Feature directory: `relentless/features/NNN-feature/`
+
+---
+
+## Step 2: Load Context
+
+Read:
+1. `relentless/constitution.md` - Testing and quality requirements
+2. `relentless/features/NNN-feature/spec.md` - User requirements
+3. `relentless/features/NNN-feature/plan.md` - Technical design
+
+---
+
+## Step 3: Extract User Stories
+
+From spec.md, identify distinct user stories:
+- Each major functional requirement becomes a user story
+- Group related functionality
+- Typical: 3-8 user stories per feature
+
+**User Story Format:**
+```markdown
+### US-001: [Title]
+**Description:** As a [user], I want [goal] so that [benefit].
+
+**Acceptance Criteria:**
+- [ ] Criterion 1 (testable, specific)
+- [ ] Criterion 2
+- [ ] Criterion 3
+- [ ] Typecheck passes
+- [ ] Tests pass
+
+**Dependencies:** (if any)
+**Phase:** Foundation / Stories / Polish
+```
+
+---
+
+## Step 4: Generate Tasks
+
+For each user story, create implementation tasks using format:
+
+```markdown
+## User Stories
+
+### US-001: Create User Registration Endpoint
+
+**Description:** As a new user, I want to register with email/password so that I can create an account.
+
+**Acceptance Criteria:**
+- [ ] POST /api/auth/register endpoint exists
+- [ ] Email validation works
+- [ ] Password requirements enforced (min 8 chars)
+- [ ] Password is hashed before storage
+- [ ] Confirmation email sent
+- [ ] Returns 201 with user ID
+- [ ] Returns 400 for invalid input
+- [ ] Typecheck passes
+- [ ] Unit tests pass
+- [ ] Integration test passes
+
+**Dependencies:** None
+**Phase:** Foundation
+**Priority:** 1
+
+---
+
+### US-002: Create User Login Endpoint
+
+**Description:** As a registered user, I want to log in with email/password so that I can access my account.
+
+**Acceptance Criteria:**
+- [ ] POST /api/auth/login endpoint exists
+- [ ] Validates credentials against database
+- [ ] Returns JWT token on success
+- [ ] Returns 401 for invalid credentials
+- [ ] Returns 403 for unconfirmed accounts
+- [ ] Token expires after 24 hours
+- [ ] Typecheck passes
+- [ ] Unit tests pass
+- [ ] Integration test passes
+
+**Dependencies:** US-001
+**Phase:** Stories
+**Priority:** 2
+
+---
+
+### US-003: Email Confirmation Flow
+
+**Description:** As a new user, I want to confirm my email so that my account is activated.
+
+**Acceptance Criteria:**
+- [ ] Confirmation email sent on registration
+- [ ] Email contains confirmation link
+- [ ] GET /api/auth/confirm/:token endpoint exists
+- [ ] Token validates and marks account as confirmed
+- [ ] Expired tokens return appropriate error
+- [ ] Confirmed users can log in
+- [ ] Typecheck passes
+- [ ] E2E test passes
+
+**Dependencies:** US-001
+**Phase:** Stories
+**Priority:** 3
+```
+
+---
+
+## Step 5: Order by Dependencies
+
+Ensure user stories are ordered so dependencies come first:
+1. **Phase 0: Setup** - Infrastructure, configuration
+2. **Phase 1: Foundation** - Core models, base functionality
+3. **Phase 2: Stories** - User-facing features (ordered by dependencies)
+4. **Phase 3: Polish** - Optimization, edge cases
+
+Mark parallel stories with:
+```markdown
+**Parallel:** Yes
+```
+
+---
+
+## Step 6: Validate Completeness
+
+Check that:
+- [ ] Every functional requirement from spec has a user story
+- [ ] Each user story has specific, testable acceptance criteria
+- [ ] Dependencies are valid (no circular references)
+- [ ] Each story is independently testable
+- [ ] Typecheck/test criteria included
+- [ ] Priority order makes sense
+
+---
+
+## Step 7: Save & Report
+
+1. Save to `relentless/features/NNN-feature/tasks.md`
+2. Update progress.txt
+3. Report:
+   - Total user stories: N
+   - Dependency order: [list]
+   - Parallel opportunities: N
+   - Next step: `/relentless.checklist` or `relentless convert tasks.md`
+
+---
+
+## Key Guidelines
+
+**User Story Size:**
+- Each story completable in one session
+- If too large, split into multiple stories
+- Typical: 30-90 minutes of work per story
+
+**Acceptance Criteria:**
+- Specific and testable
+- No vague terms ("works well", "good UX")
+- Include quality checks (typecheck, lint, test)
+- Verifiable in browser/tests
+
+**Dependencies:**
+- Only list direct dependencies
+- Ensure no circular dependencies
+- Consider data dependencies (user must exist before profile)
+
+---
+
+## Notes
+
+- tasks.md is the source of truth for user stories
+- This file will be converted to prd.json by `relentless convert`
+- Make acceptance criteria detailed and specific
+- Each story should be independently deployable and testable

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

@@ -0,0 +1,251 @@
+---
+
+description: "Task list template for feature implementation"
+---
+
+# Tasks: [FEATURE NAME]
+
+**Input**: Design documents from `/specs/[###-feature-name]/`
+**Prerequisites**: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/
+
+**Tests**: The examples below include test tasks. Tests are OPTIONAL - only include them if explicitly requested in the feature specification.
+
+**Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story.
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: Can run in parallel (different files, no dependencies)
+- **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3)
+- Include exact file paths in descriptions
+
+## Path Conventions
+
+- **Single project**: `src/`, `tests/` at repository root
+- **Web app**: `backend/src/`, `frontend/src/`
+- **Mobile**: `api/src/`, `ios/src/` or `android/src/`
+- Paths shown below assume single project - adjust based on plan.md structure
+
+<!-- 
+  ============================================================================
+  IMPORTANT: The tasks below are SAMPLE TASKS for illustration purposes only.
+  
+  The /relentless.tasks command MUST replace these with actual tasks based on:
+  - User stories from spec.md (with their priorities P1, P2, P3...)
+  - Feature requirements from plan.md
+  - Entities from data-model.md
+  - Endpoints from contracts/
+  
+  Tasks MUST be organized by user story so each story can be:
+  - Implemented independently
+  - Tested independently
+  - Delivered as an MVP increment
+  
+  DO NOT keep these sample tasks in the generated tasks.md file.
+  ============================================================================
+-->
+
+## Phase 1: Setup (Shared Infrastructure)
+
+**Purpose**: Project initialization and basic structure
+
+- [ ] T001 Create project structure per implementation plan
+- [ ] T002 Initialize [language] project with [framework] dependencies
+- [ ] T003 [P] Configure linting and formatting tools
+
+---
+
+## Phase 2: Foundational (Blocking Prerequisites)
+
+**Purpose**: Core infrastructure that MUST be complete before ANY user story can be implemented
+
+**⚠️ CRITICAL**: No user story work can begin until this phase is complete
+
+Examples of foundational tasks (adjust based on your project):
+
+- [ ] T004 Setup database schema and migrations framework
+- [ ] T005 [P] Implement authentication/authorization framework
+- [ ] T006 [P] Setup API routing and middleware structure
+- [ ] T007 Create base models/entities that all stories depend on
+- [ ] T008 Configure error handling and logging infrastructure
+- [ ] T009 Setup environment configuration management
+
+**Checkpoint**: Foundation ready - user story implementation can now begin in parallel
+
+---
+
+## Phase 3: User Story 1 - [Title] (Priority: P1) 🎯 MVP
+
+**Goal**: [Brief description of what this story delivers]
+
+**Independent Test**: [How to verify this story works on its own]
+
+### Tests for User Story 1 (OPTIONAL - only if tests requested) ⚠️
+
+> **NOTE: Write these tests FIRST, ensure they FAIL before implementation**
+
+- [ ] T010 [P] [US1] Contract test for [endpoint] in tests/contract/test_[name].py
+- [ ] T011 [P] [US1] Integration test for [user journey] in tests/integration/test_[name].py
+
+### Implementation for User Story 1
+
+- [ ] T012 [P] [US1] Create [Entity1] model in src/models/[entity1].py
+- [ ] T013 [P] [US1] Create [Entity2] model in src/models/[entity2].py
+- [ ] T014 [US1] Implement [Service] in src/services/[service].py (depends on T012, T013)
+- [ ] T015 [US1] Implement [endpoint/feature] in src/[location]/[file].py
+- [ ] T016 [US1] Add validation and error handling
+- [ ] T017 [US1] Add logging for user story 1 operations
+
+**Checkpoint**: At this point, User Story 1 should be fully functional and testable independently
+
+---
+
+## Phase 4: User Story 2 - [Title] (Priority: P2)
+
+**Goal**: [Brief description of what this story delivers]
+
+**Independent Test**: [How to verify this story works on its own]
+
+### Tests for User Story 2 (OPTIONAL - only if tests requested) ⚠️
+
+- [ ] T018 [P] [US2] Contract test for [endpoint] in tests/contract/test_[name].py
+- [ ] T019 [P] [US2] Integration test for [user journey] in tests/integration/test_[name].py
+
+### Implementation for User Story 2
+
+- [ ] T020 [P] [US2] Create [Entity] model in src/models/[entity].py
+- [ ] T021 [US2] Implement [Service] in src/services/[service].py
+- [ ] T022 [US2] Implement [endpoint/feature] in src/[location]/[file].py
+- [ ] T023 [US2] Integrate with User Story 1 components (if needed)
+
+**Checkpoint**: At this point, User Stories 1 AND 2 should both work independently
+
+---
+
+## Phase 5: User Story 3 - [Title] (Priority: P3)
+
+**Goal**: [Brief description of what this story delivers]
+
+**Independent Test**: [How to verify this story works on its own]
+
+### Tests for User Story 3 (OPTIONAL - only if tests requested) ⚠️
+
+- [ ] T024 [P] [US3] Contract test for [endpoint] in tests/contract/test_[name].py
+- [ ] T025 [P] [US3] Integration test for [user journey] in tests/integration/test_[name].py
+
+### Implementation for User Story 3
+
+- [ ] T026 [P] [US3] Create [Entity] model in src/models/[entity].py
+- [ ] T027 [US3] Implement [Service] in src/services/[service].py
+- [ ] T028 [US3] Implement [endpoint/feature] in src/[location]/[file].py
+
+**Checkpoint**: All user stories should now be independently functional
+
+---
+
+[Add more user story phases as needed, following the same pattern]
+
+---
+
+## Phase N: Polish & Cross-Cutting Concerns
+
+**Purpose**: Improvements that affect multiple user stories
+
+- [ ] TXXX [P] Documentation updates in docs/
+- [ ] TXXX Code cleanup and refactoring
+- [ ] TXXX Performance optimization across all stories
+- [ ] TXXX [P] Additional unit tests (if requested) in tests/unit/
+- [ ] TXXX Security hardening
+- [ ] TXXX Run quickstart.md validation
+
+---
+
+## Dependencies & Execution Order
+
+### Phase Dependencies
+
+- **Setup (Phase 1)**: No dependencies - can start immediately
+- **Foundational (Phase 2)**: Depends on Setup completion - BLOCKS all user stories
+- **User Stories (Phase 3+)**: All depend on Foundational phase completion
+  - User stories can then proceed in parallel (if staffed)
+  - Or sequentially in priority order (P1 → P2 → P3)
+- **Polish (Final Phase)**: Depends on all desired user stories being complete
+
+### User Story Dependencies
+
+- **User Story 1 (P1)**: Can start after Foundational (Phase 2) - No dependencies on other stories
+- **User Story 2 (P2)**: Can start after Foundational (Phase 2) - May integrate with US1 but should be independently testable
+- **User Story 3 (P3)**: Can start after Foundational (Phase 2) - May integrate with US1/US2 but should be independently testable
+
+### Within Each User Story
+
+- Tests (if included) MUST be written and FAIL before implementation
+- Models before services
+- Services before endpoints
+- Core implementation before integration
+- Story complete before moving to next priority
+
+### Parallel Opportunities
+
+- All Setup tasks marked [P] can run in parallel
+- All Foundational tasks marked [P] can run in parallel (within Phase 2)
+- Once Foundational phase completes, all user stories can start in parallel (if team capacity allows)
+- All tests for a user story marked [P] can run in parallel
+- Models within a story marked [P] can run in parallel
+- Different user stories can be worked on in parallel by different team members
+
+---
+
+## Parallel Example: User Story 1
+
+```bash
+# Launch all tests for User Story 1 together (if tests requested):
+Task: "Contract test for [endpoint] in tests/contract/test_[name].py"
+Task: "Integration test for [user journey] in tests/integration/test_[name].py"
+
+# Launch all models for User Story 1 together:
+Task: "Create [Entity1] model in src/models/[entity1].py"
+Task: "Create [Entity2] model in src/models/[entity2].py"
+```
+
+---
+
+## Implementation Strategy
+
+### MVP First (User Story 1 Only)
+
+1. Complete Phase 1: Setup
+2. Complete Phase 2: Foundational (CRITICAL - blocks all stories)
+3. Complete Phase 3: User Story 1
+4. **STOP and VALIDATE**: Test User Story 1 independently
+5. Deploy/demo if ready
+
+### Incremental Delivery
+
+1. Complete Setup + Foundational → Foundation ready
+2. Add User Story 1 → Test independently → Deploy/Demo (MVP!)
+3. Add User Story 2 → Test independently → Deploy/Demo
+4. Add User Story 3 → Test independently → Deploy/Demo
+5. Each story adds value without breaking previous stories
+
+### Parallel Team Strategy
+
+With multiple developers:
+
+1. Team completes Setup + Foundational together
+2. Once Foundational is done:
+   - Developer A: User Story 1
+   - Developer B: User Story 2
+   - Developer C: User Story 3
+3. Stories complete and integrate independently
+
+---
+
+## Notes
+
+- [P] tasks = different files, no dependencies
+- [Story] label maps task to specific user story for traceability
+- Each user story should be independently completable and testable
+- Verify tests fail before implementing
+- Commit after each task or logical group
+- Stop at any checkpoint to validate story independently
+- Avoid: vague tasks, same file conflicts, cross-story dependencies that break independence

package/.claude/skills/taskstoissues/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: taskstoissues
+description: "Convert user stories to GitHub issues. Use when ready to create issues. Triggers on: create github issues, export to github, generate issues."
+---
+
+# GitHub Issues Generator
+
+Convert user stories from tasks.md into GitHub issues.
+
+---
+
+## The Job
+
+1. Read tasks.md
+2. Parse user stories
+3. Generate GitHub issues with `gh` CLI
+4. Link dependencies
+
+---
+
+## Prerequisites
+
+- GitHub CLI (`gh`) installed and authenticated
+- Git repository with GitHub remote
+- tasks.md exists with user stories
+
+---
+
+## Issue Format
+
+For each user story, create issue with:
+
+**Title:** [US-XXX] Story Title
+
+**Body:**
+```markdown
+## Description
+[Story description]
+
+## Acceptance Criteria
+- [ ] Criterion 1
+- [ ] Criterion 2
+- [ ] Typecheck passes
+- [ ] Tests pass
+
+## Dependencies
+#123 (if US-001 already exists as issue #123)
+
+## Phase
+Foundation / Stories / Polish
+
+## Priority
+High / Medium / Low
+
+---
+From: tasks.md
+Story ID: US-XXX
+```
+
+**Labels:**
+- `user-story`
+- `priority-high` / `priority-medium` / `priority-low`
+- Domain-specific: `database`, `api`, `ui`, `security`, etc.
+
+---
+
+## Execution
+
+```bash
+# Dry run first
+relentless issues --feature NNN-feature --dry-run
+
+# Create issues
+relentless issues --feature NNN-feature
+
+# Create all issues (including completed)
+relentless issues --feature NNN-feature --all
+```
+
+---
+
+## Mapping
+
+- Extract story ID, title, description, acceptance criteria
+- Detect domain from description (api, database, ui, etc.)
+- Map priority from tasks.md
+- Create dependencies based on US dependencies
+
+---
+
+## Notes
+
+- Dry run first to preview
+- Issues created in dependency order
+- Issue numbers used for dependency linking
+- Only creates issues for incomplete stories (unless --all)
+- See relentless CLI for actual implementation