@intentsolutionsio/sprint 1.0.0

package/commands/generate-map.md

@@ -0,0 +1,160 @@
+---
+name: generate-map
+description: Analyze codebase and generate a comprehensive project-map.md overview
+argument-hint: "[--force]"
+---
+
+# Generate Project Map Command
+
+You are generating a comprehensive `.claude/project-map.md` file for this codebase.
+
+## Your Task
+
+Analyze the entire codebase and create a clear, concise project map that a new developer can read in a few minutes to understand the system.
+
+## Workflow
+
+1. **Scan the codebase structure**
+   - List all top-level directories
+   - Identify the main technology stack
+   - Find configuration files (package.json, pyproject.toml, docker-compose.yml, etc.)
+
+2. **Identify the tech stack**
+   - Backend framework and language
+   - Frontend framework (if any)
+   - Database(s)
+   - Infrastructure (Docker, K8s, cloud services)
+   - Key libraries and dependencies
+
+3. **Map the project structure**
+   - Main folders and their responsibilities
+   - Entry points and important files
+   - Configuration locations
+
+4. **Document the API surface** (if applicable)
+   - Main endpoints grouped by domain
+   - Authentication method
+   - Link to OpenAPI/Swagger if available
+
+5. **Document the database** (if applicable)
+   - Main entities and relationships
+   - Migration tool and location
+
+6. **Document the frontend** (if applicable)
+   - Main pages/routes
+   - Component organization
+   - State management approach
+
+7. **Document infrastructure**
+   - How to run the project locally
+   - Docker services and ports
+   - Environment variables needed
+
+8. **Document testing**
+   - Test frameworks in use
+   - How to run tests
+
+## Output Format
+
+Create/overwrite `.claude/project-map.md` with this structure:
+
+```markdown
+# Project Map
+
+> Auto-generated overview of the codebase. Last updated: [date]
+
+## Tech Stack
+
+- **Backend:** [framework, language, version]
+- **Frontend:** [framework, language, version]
+- **Database:** [type, version]
+- **Infrastructure:** [Docker, etc.]
+- **Key Libraries:** [list]
+
+## Project Structure
+
+```
+/
+├── backend/          # [description]
+├── frontend/         # [description]
+├── ...
+```
+
+## API Surface
+
+### [Domain 1]
+- `GET /api/...` - [description]
+- `POST /api/...` - [description]
+
+### [Domain 2]
+...
+
+## Database Schema
+
+Main entities:
+- **Entity1** - [description, key fields]
+- **Entity2** - [description, key fields]
+
+Relationships: [brief description]
+
+## Frontend Architecture
+
+Main routes:
+- `/` - [description]
+- `/dashboard` - [description]
+
+Key components: [list]
+
+## Infrastructure
+
+### Local Development
+```bash
+# Commands to run the project
+```
+
+### Docker Services
+| Service | Port | Description |
+|---------|------|-------------|
+| ...     | ...  | ...         |
+
+### Environment Variables
+| Variable | Purpose | Required |
+|----------|---------|----------|
+| ...      | ...     | ...      |
+
+## Testing
+
+- **Framework:** [pytest/jest/etc.]
+- **Run tests:** `[command]`
+
+## Development Workflow
+
+1. [Setup step]
+2. [Run step]
+3. [Test step]
+
+## Current Features
+
+- [Feature 1]
+- [Feature 2]
+
+## Known Limitations
+
+- [Limitation 1]
+- [Limitation 2]
+```
+
+## Guidelines
+
+- Keep it concise - aim for a document readable in 5 minutes
+- Use bullet points and tables
+- Link to detailed docs rather than copying content
+- Remove any sections that don't apply
+- Be accurate - verify information from actual files
+
+## After Generation
+
+Report to the user:
+- Summary of what was documented
+- Any areas that need manual review
+- Suggestions for missing documentation

package/commands/new.md

@@ -0,0 +1,173 @@
+---
+name: new
+description: Create a new sprint directory with specs.md template
+argument-hint: "[goal description]"
+---
+
+# New Sprint Command
+
+You are bootstrapping a new sprint for the user.
+
+## Workflow
+
+### Step 1: Determine Sprint Index
+
+Find the next sprint number:
+```bash
+# Get current highest sprint number
+LAST=$(ls -d .claude/sprint/*/ 2>/dev/null | sort -V | tail -1 | grep -oE '[0-9]+' | tail -1)
+if [ -z "$LAST" ]; then
+  NEXT=1
+else
+  NEXT=$((LAST + 1))
+fi
+echo $NEXT
+```
+
+### Step 2: Create Sprint Directory
+
+```bash
+mkdir -p .claude/sprint/[NEXT]
+```
+
+### Step 3: Gather Sprint Information
+
+Ask the user for sprint details. Present this as a structured question:
+
+**What would you like to build in this sprint?**
+
+Options to clarify:
+1. **Goal**: What's the main objective? (1-2 sentences)
+2. **Scope**: What specific features or fixes?
+3. **Testing**:
+   - QA testing: required / optional / skip
+   - UI testing: required / optional / skip
+   - UI testing mode: automated / manual
+
+### Step 4: Create specs.md
+
+Based on user input, create `.claude/sprint/[NEXT]/specs.md`:
+
+```markdown
+# Sprint [NEXT] Specifications
+
+## Goal
+[User's goal description]
+
+## Scope
+[List of features/tasks]
+
+## Testing
+- QA: [required/optional/skip]
+- UI Testing: [required/optional/skip]
+- UI Testing Mode: [automated/manual]
+
+## Notes
+[Any additional context]
+```
+
+### Step 5: Suggest Next Steps
+
+After creating the sprint, suggest:
+
+```
+Sprint [NEXT] created at .claude/sprint/[NEXT]/
+
+Next steps:
+1. Review and edit .claude/sprint/[NEXT]/specs.md if needed
+2. Run /sprint to start the sprint workflow
+3. The architect will analyze specs and create detailed specifications
+
+Tip: For detailed specs, you can add:
+- API endpoint details
+- UI mockup descriptions
+- Database schema changes
+- Specific test scenarios
+```
+
+## Quick Mode
+
+If the user provides a one-liner goal, create the sprint immediately:
+
+Example: `/sprint:new Add user authentication with OAuth`
+
+Creates:
+```markdown
+# Sprint [N] Specifications
+
+## Goal
+Add user authentication with OAuth
+
+## Scope
+- To be analyzed by architect
+
+## Testing
+- QA: required
+- UI Testing: required
+- UI Testing Mode: automated
+```
+
+## Templates
+
+Offer templates for common sprint types:
+
+### Feature Sprint
+```markdown
+# Sprint [N] Specifications
+
+## Goal
+[New feature description]
+
+## Scope
+- Backend API endpoints
+- Frontend UI components
+- Database migrations
+- Tests
+
+## Testing
+- QA: required
+- UI Testing: required
+- UI Testing Mode: automated
+```
+
+### Bug Fix Sprint
+```markdown
+# Sprint [N] Specifications
+
+## Goal
+Fix [bug description]
+
+## Scope
+- Root cause analysis
+- Fix implementation
+- Regression tests
+
+## Testing
+- QA: required
+- UI Testing: optional
+- UI Testing Mode: automated
+```
+
+### Refactoring Sprint
+```markdown
+# Sprint [N] Specifications
+
+## Goal
+Refactor [component/system]
+
+## Scope
+- Code restructuring
+- No functional changes
+- Update tests if needed
+
+## Testing
+- QA: required
+- UI Testing: skip
+```
+
+## Output
+
+Report to user:
+- Sprint number and directory created
+- Summary of specs.md content
+- Next steps to proceed

package/commands/setup.md

@@ -0,0 +1,239 @@
+---
+name: setup
+description: Interactive project onboarding - creates project-goals.md and project-map.md
+allowed-tools:
+  - Read
+  - Write
+  - Glob
+  - Grep
+  - Bash
+  - AskUserQuestion
+---
+
+# Setup Command - Interactive Project Onboarding
+
+Initialize a project for use with Sprint by creating the two "Second Brain" documents that guide all sprint work.
+
+## Overview
+
+This command interactively creates:
+1. `.claude/project-goals.md` - Business vision and objectives (user-maintained)
+2. `.claude/project-map.md` - Technical architecture (architect-maintained)
+
+## Workflow
+
+### Step 1: Check Existing Files
+
+Check if either file already exists:
+
+```bash
+test -f .claude/project-goals.md && echo "GOALS_EXISTS" || echo "NO_GOALS"
+test -f .claude/project-map.md && echo "MAP_EXISTS" || echo "NO_MAP"
+```
+
+If files exist, ask the user:
+- Overwrite existing files?
+- Skip existing and create only missing?
+- Abort setup?
+
+### Step 2: Create .claude Directory
+
+Ensure the directory exists:
+
+```bash
+mkdir -p .claude
+```
+
+### Step 3: Gather Project Goals (Interactive)
+
+Use AskUserQuestion to gather business context:
+
+**Question 1: Product Vision**
+- "What is this project? Describe it in 1-2 sentences."
+
+**Question 2: Target Users**
+- "Who are the target users?"
+- Options: "Developers", "End consumers", "Internal team", "Other"
+
+**Question 3: Key Features**
+- "What are the 3-5 most important features or capabilities?"
+
+**Question 4: Success Metrics**
+- "How will you measure success?"
+- Options: "User adoption", "Revenue", "Performance metrics", "Other"
+
+**Question 5: Constraints**
+- "Any important constraints or requirements?"
+- Examples: compliance, performance, technology restrictions
+
+### Step 4: Generate project-goals.md
+
+Write the gathered information to `.claude/project-goals.md`:
+
+```markdown
+# Project Goals
+
+## Vision
+[User's product vision]
+
+## Target Users
+[Target audience description]
+
+## Key Features
+- [Feature 1]
+- [Feature 2]
+- [Feature 3]
+
+## Success Metrics
+[How success is measured]
+
+## Constraints
+[Important constraints and requirements]
+
+---
+*This file is maintained by the user. Update it when business objectives change.*
+```
+
+### Step 5: Scan Codebase
+
+Analyze the project structure:
+
+```bash
+# List top-level structure
+ls -la
+
+# Find key configuration files
+find . -maxdepth 2 -name "package.json" -o -name "pyproject.toml" -o -name "Cargo.toml" -o -name "go.mod" -o -name "*.csproj" 2>/dev/null
+
+# Check for common frameworks
+test -f next.config.js -o -f next.config.ts && echo "NEXTJS"
+test -f nuxt.config.ts && echo "NUXT"
+test -f angular.json && echo "ANGULAR"
+test -f vite.config.ts && echo "VITE"
+test -d backend -o -f requirements.txt -o -f pyproject.toml && echo "PYTHON"
+test -f go.mod && echo "GO"
+test -f Cargo.toml && echo "RUST"
+```
+
+Read key files to understand the project:
+- README.md (if exists)
+- package.json / pyproject.toml / etc.
+- Docker configuration
+- CI/CD files
+
+### Step 6: Gather Technical Context (Interactive)
+
+Ask clarifying questions based on scan results:
+
+**Question: Tech Stack Confirmation**
+- "I detected [frameworks]. Is this correct?"
+- Allow corrections
+
+**Question: Architecture Style**
+- Options: "Monolith", "Microservices", "Serverless", "Monorepo", "Other"
+
+**Question: Database**
+- Options: "PostgreSQL", "MySQL", "MongoDB", "SQLite", "None/Other"
+
+**Question: Deployment**
+- Options: "Docker", "Kubernetes", "Serverless", "Traditional hosting", "Not yet decided"
+
+### Step 7: Generate project-map.md
+
+Create `.claude/project-map.md` with discovered and confirmed information:
+
+```markdown
+# Project Map
+
+## Tech Stack
+
+### Backend
+- Language: [detected/confirmed]
+- Framework: [detected/confirmed]
+- Database: [confirmed]
+
+### Frontend
+- Framework: [detected/confirmed]
+- Styling: [detected]
+
+### Infrastructure
+- Deployment: [confirmed]
+- CI/CD: [detected]
+
+## Project Structure
+
+```
+[directory tree of main folders]
+```
+
+## Key Components
+
+### [Component 1]
+- Location: [path]
+- Purpose: [description]
+
+### [Component 2]
+- Location: [path]
+- Purpose: [description]
+
+## Development Workflow
+
+### Running Locally
+[commands to start the project]
+
+### Running Tests
+[test commands]
+
+## Current Features
+- [Feature 1]
+- [Feature 2]
+
+## Known Limitations
+- [Any detected issues or TODOs]
+
+---
+*This file is maintained by the project-architect agent. Updated during sprints.*
+```
+
+### Step 8: Offer First Sprint
+
+Ask the user:
+- "Would you like to create your first sprint now?"
+
+If yes, prompt for sprint goal and run `/sprint:new` logic.
+
+If no, provide next steps:
+```
+Setup complete!
+
+Next steps:
+1. Review .claude/project-goals.md and adjust as needed
+2. Review .claude/project-map.md for accuracy
+3. Run /sprint:new to start your first sprint
+```
+
+## Error Handling
+
+### No Codebase Detected
+
+If the directory appears empty or has no recognizable project structure:
+- Ask if this is a new project
+- Offer to create a minimal project-map.md for greenfield development
+- Suggest running setup again after initial code is written
+
+### Permission Issues
+
+If unable to write to .claude/:
+- Report the error clearly
+- Suggest checking directory permissions
+
+## Output
+
+On completion, display:
+```
+✓ Created .claude/project-goals.md
+✓ Created .claude/project-map.md
+
+Your project is ready for Sprint!
+Run /sprint:new to begin.
+```