@arvorco/relentless 0.1.8 → 0.1.10

package/.claude/skills/specify/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: specify
+description: "Create feature specification from natural language description. Use when starting a new feature or creating a spec. Triggers on: create spec, specify feature, new feature spec."
+---
+
+# Feature Specification Generator
+
+Create structured feature specifications from natural language descriptions.
+
+---
+
+## The Job
+
+1. Receive feature description from user
+2. Generate short name and feature number
+3. Create branch and feature directory in `relentless/features/NNN-feature-name/`
+4. Generate specification using template
+5. Validate specification quality
+6. Save to `spec.md`
+
+---
+
+## Step 1: Create Feature Structure
+
+Run the create-new-feature script to set up the branch and directory:
+
+```bash
+.claude/skills/specify/scripts/bash/create-new-feature.sh --json "FEATURE_DESCRIPTION"
+```
+
+This will output JSON with:
+- `BRANCH_NAME`: e.g., "003-user-auth"
+- `SPEC_FILE`: Full path to spec.md
+- `FEATURE_DIR`: Full path to feature directory
+- `FEATURE_NUM`: e.g., "003"
+
+**Important:** Parse this JSON and use these paths for all subsequent operations.
+
+---
+
+## Step 2: Load Constitution & Context
+
+1. Read `relentless/constitution.md` for project governance
+2. Note any MUST/SHOULD rules that apply to specifications
+3. Keep these principles in mind while generating the spec
+
+---
+
+## Step 3: Generate Specification
+
+Using the template at `templates/spec-template.md`, create a specification with:
+
+### Required Sections:
+
+**1. Feature Overview**
+- One-paragraph summary
+- User value proposition
+- Problem being solved
+
+**2. User Scenarios & Testing**
+- Concrete user stories
+- Step-by-step flows
+- Expected outcomes
+
+**3. Functional Requirements**
+- What the system must do
+- Testable requirements (no implementation details)
+- Clear success criteria
+
+**4. Success Criteria**
+- Measurable, technology-agnostic outcomes
+- Quantitative metrics (time, performance, volume)
+- Qualitative measures (user satisfaction, task completion)
+
+**5. Key Entities (if applicable)**
+- Data models and relationships
+- Fields and types (logical, not implementation)
+
+**6. Dependencies & Assumptions**
+- External systems required
+- Prerequisites
+- Assumptions made
+
+**7. Out of Scope**
+- What this feature explicitly does NOT include
+- Future considerations
+
+---
+
+## Step 4: Handle Ambiguities
+
+If aspects are unclear:
+- Make informed guesses based on context
+- Only mark `[NEEDS CLARIFICATION: specific question]` if:
+  - Choice significantly impacts scope or UX
+  - Multiple reasonable interpretations exist
+  - No reasonable default exists
+- **LIMIT: Maximum 3 clarifications**
+
+If clarifications needed, present to user:
+
+```markdown
+## Clarification Needed
+
+**Q1: [Topic]**
+Context: [Quote spec section]
+Question: [Specific question]
+
+Options:
+A. [Option 1] - [Implications]
+B. [Option 2] - [Implications]
+C. Custom - [Your answer]
+
+Your choice: _
+```
+
+---
+
+## Step 5: Validate Quality
+
+Check the specification against:
+
+- [ ] No implementation details (languages, frameworks, APIs)
+- [ ] Focused on user value and business needs
+- [ ] All requirements are testable
+- [ ] Success criteria are measurable
+- [ ] User scenarios cover primary flows
+- [ ] Dependencies identified
+- [ ] Scope clearly bounded
+- [ ] No more than 3 `[NEEDS CLARIFICATION]` markers
+
+If validation fails, revise and re-check (max 3 iterations).
+
+---
+
+## Step 6: Save & Report
+
+1. Write complete specification to `SPEC_FILE` from JSON output
+2. Create progress.txt if it doesn't exist:
+   ```markdown
+   ---
+   feature: FEATURE_NAME
+   started: DATE
+   last_updated: DATE
+   stories_completed: 0
+   ---
+   
+   # Progress Log: FEATURE_NAME
+   ```
+
+3. Report to user:
+   - Branch created: `BRANCH_NAME`
+   - Spec saved: `SPEC_FILE`
+   - Quality validation: PASSED/FAILED
+   - Next step: `/relentless.plan` or `/relentless.clarify`
+
+---
+
+## Example Output
+
+```markdown
+# Feature: User Authentication
+
+## Overview
+Enable users to create accounts and log in securely using email/password.
+
+## User Scenarios
+
+### Scenario 1: New User Registration
+1. User visits signup page
+2. Enters email and password
+3. Submits form
+4. Receives confirmation email
+5. Clicks confirmation link
+6. Account is activated
+
+**Expected Outcome:** User has active account and can log in.
+
+## Functional Requirements
+
+**REQ-1:** System must validate email format
+**REQ-2:** System must require passwords ≥ 8 characters
+**REQ-3:** System must send confirmation email within 1 minute
+**REQ-4:** System must hash passwords before storage
+
+## Success Criteria
+
+1. 95% of signups complete within 60 seconds
+2. Zero plaintext passwords in database
+3. Email confirmation rate > 80%
+
+## Key Entities
+
+**User**
+- email: string (unique)
+- password_hash: string
+- confirmed: boolean
+- created_at: timestamp
+
+## Dependencies
+
+- Email service provider (e.g., SendGrid, Mailgun)
+- Session management system
+
+## Out of Scope
+
+- Social login (OAuth)
+- Two-factor authentication
+- Password reset (separate feature)
+```
+
+---
+
+## Notes
+
+- Always run the script first to get proper paths
+- Use absolute paths from JSON output
+- Validate before marking complete
+- Keep specification technology-agnostic
+- Focus on WHAT, not HOW

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