ai-sprint-kit 1.1.0

package/templates/.claude/commands/docs.md

@@ -0,0 +1,519 @@
+---
+description: Generate and update project documentation
+argument-hint: [optional: specific doc type (readme|api|architecture)]
+---
+
+## Command: /docs
+
+Generate comprehensive, up-to-date documentation including README, API docs, architecture diagrams, and inline code comments.
+
+## Usage
+
+```
+/docs
+/docs readme
+/docs api
+/docs architecture
+```
+
+## Workflow
+
+### 1. Audit Existing Docs
+- Check current documentation
+- Identify outdated sections
+- Find missing documentation
+- List undocumented code
+
+### 2. Generate Documentation
+- README.md (if missing/outdated)
+- API documentation (OpenAPI/GraphQL)
+- Architecture diagrams (Mermaid)
+- Code comments (TSDoc/JSDoc)
+
+### 3. Update Documentation
+- Sync with current codebase
+- Fix broken links
+- Update examples
+- Add missing sections
+
+### 4. Validate
+- Test all code examples
+- Check all links work
+- Verify accuracy
+- Ensure completeness
+
+## Documentation Types
+
+### README.md
+```markdown
+# Project Name
+
+Brief description (1-2 sentences)
+
+## Features
+- ✅ Feature 1
+- ✅ Feature 2
+- ✅ Feature 3
+
+## Quick Start
+\`\`\`bash
+npm install
+npm run dev
+\`\`\`
+
+## Installation
+
+### Prerequisites
+- Node.js 20+
+- PostgreSQL 16+
+
+### Steps
+1. Clone repository
+\`\`\`bash
+git clone https://github.com/org/repo
+cd repo
+\`\`\`
+
+2. Install dependencies
+\`\`\`bash
+npm install
+\`\`\`
+
+3. Configure environment
+\`\`\`bash
+cp .env.example .env
+# Edit .env with your values
+\`\`\`
+
+4. Run database migrations
+\`\`\`bash
+npm run db:migrate
+\`\`\`
+
+5. Start development server
+\`\`\`bash
+npm run dev
+\`\`\`
+
+Open [http://localhost:3000](http://localhost:3000)
+
+## Usage
+
+### Basic Example
+\`\`\`typescript
+import { feature } from 'package';
+
+const result = feature({ option: 'value' });
+\`\`\`
+
+### Advanced Example
+\`\`\`typescript
+// More complex usage
+\`\`\`
+
+## API Reference
+
+See [API.md](API.md)
+
+## Development
+
+### Project Structure
+\`\`\`
+app/          # Next.js app directory
+lib/          # Utilities
+components/   # React components
+tests/        # Tests
+\`\`\`
+
+### Commands
+\`\`\`bash
+npm run dev      # Development server
+npm run build    # Production build
+npm test         # Run tests
+npm run lint     # Lint code
+\`\`\`
+
+## Environment Variables
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `DATABASE_URL` | PostgreSQL connection | Yes |
+| `JWT_SECRET` | JWT signing secret | Yes |
+
+## Deployment
+
+See [DEPLOYMENT.md](DEPLOYMENT.md)
+
+## Contributing
+
+1. Fork repository
+2. Create feature branch
+3. Make changes
+4. Submit pull request
+
+## License
+
+MIT
+```
+
+### API Documentation (OpenAPI)
+```yaml
+openapi: 3.0.0
+info:
+  title: App API
+  version: 1.0.0
+  description: REST API for the application
+
+servers:
+  - url: https://api.example.com
+    description: Production
+  - url: http://localhost:3000
+    description: Development
+
+paths:
+  /api/users:
+    get:
+      summary: List users
+      description: Get paginated list of users
+      parameters:
+        - name: page
+          in: query
+          schema:
+            type: integer
+            default: 1
+        - name: limit
+          in: query
+          schema:
+            type: integer
+            default: 20
+      responses:
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  users:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/User'
+                  total:
+                    type: integer
+                  page:
+                    type: integer
+
+    post:
+      summary: Create user
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                email:
+                  type: string
+                  format: email
+                password:
+                  type: string
+                  minLength: 8
+      responses:
+        '201':
+          description: User created
+        '400':
+          description: Invalid input
+
+components:
+  schemas:
+    User:
+      type: object
+      properties:
+        id:
+          type: string
+        email:
+          type: string
+        createdAt:
+          type: string
+          format: date-time
+```
+
+### Architecture Documentation
+```markdown
+# System Architecture
+
+## Overview
+Modern full-stack application with Next.js frontend and Node.js backend.
+
+## Tech Stack
+
+### Frontend
+- Next.js 15 (React framework)
+- TypeScript
+- Tailwind CSS
+
+### Backend
+- Node.js REST API
+- PostgreSQL (database)
+- Redis (cache)
+
+### Infrastructure
+- Vercel (frontend hosting)
+- Railway (backend + DB)
+- Cloudflare (CDN)
+
+## Architecture Diagram
+
+\`\`\`mermaid
+graph TD
+    A[User] -->|HTTPS| B[Cloudflare CDN]
+    B -->|Static Assets| C[Vercel - Next.js]
+    C -->|API Calls| D[Railway - Node.js API]
+    D -->|Query| E[PostgreSQL]
+    D -->|Cache| F[Redis]
+\`\`\`
+
+## Database Schema
+
+\`\`\`mermaid
+erDiagram
+    USER ||--o{ ORDER : places
+    USER {
+        string id PK
+        string email UK
+        string password
+        datetime created_at
+    }
+    ORDER {
+        string id PK
+        string user_id FK
+        decimal amount
+        string status
+        datetime created_at
+    }
+\`\`\`
+
+## API Flow
+
+\`\`\`mermaid
+sequenceDiagram
+    User->>Frontend: Submit form
+    Frontend->>API: POST /api/orders
+    API->>DB: Create order
+    DB-->>API: Order created
+    API->>Queue: Add to processing
+    API-->>Frontend: Order ID
+    Frontend-->>User: Show confirmation
+\`\`\`
+
+## Security
+
+- JWT authentication
+- HTTPS only
+- Rate limiting (100 req/15min)
+- Input validation
+- SQL injection prevention (parameterized queries)
+- XSS prevention (output encoding)
+
+## Performance
+
+- Redis caching (1 hour TTL)
+- Database connection pooling
+- CDN for static assets
+- Image optimization (Next.js)
+- Code splitting (automatic)
+```
+
+### Code Comments (TSDoc)
+```typescript
+/**
+ * Calculate user's subscription tier based on usage
+ *
+ * Uses a sliding window of 30 days to prevent gaming.
+ * Tier upgrades are immediate, downgrades have 7-day grace period.
+ *
+ * @param userId - User identifier
+ * @returns Subscription tier (free|pro|enterprise)
+ * @throws {NotFoundError} If user doesn't exist
+ *
+ * @example
+ * ```typescript
+ * const tier = await calculateTier('user_123');
+ * console.log(tier); // 'pro'
+ * ```
+ */
+export async function calculateTier(userId: string): Promise<Tier> {
+  // Implementation
+}
+```
+
+## Generated Documentation
+
+### For Libraries/Packages
+```markdown
+# Package Name
+
+Brief description
+
+## Installation
+\`\`\`bash
+npm install package-name
+\`\`\`
+
+## Quick Start
+\`\`\`typescript
+import { feature } from 'package-name';
+
+feature({ option: 'value' });
+\`\`\`
+
+## API Reference
+
+### `feature(options)`
+
+**Parameters:**
+- `options.option` (string): Description
+
+**Returns:** Description
+
+**Example:**
+\`\`\`typescript
+const result = feature({ option: 'value' });
+\`\`\`
+
+## Advanced Usage
+
+### Custom Configuration
+\`\`\`typescript
+// Example
+\`\`\`
+
+## Contributing
+See [CONTRIBUTING.md](CONTRIBUTING.md)
+
+## License
+MIT
+```
+
+### For Applications
+```markdown
+# App Name
+
+What the app does in one sentence.
+
+## Demo
+[Live Demo](https://app.com) | [Video](https://youtube.com)
+
+## Features
+- ✅ Feature 1
+- ✅ Feature 2
+
+## Tech Stack
+**Frontend:** Next.js, TypeScript
+**Backend:** Node.js, PostgreSQL
+**Deployment:** Vercel, Railway
+
+## Getting Started
+[Installation instructions]
+
+## Development
+[Development guide]
+
+## Deployment
+See [DEPLOYMENT.md](DEPLOYMENT.md)
+
+## License
+MIT
+```
+
+## Documentation Tools
+
+### Generate OpenAPI Docs
+```bash
+# From OpenAPI spec
+npx @redocly/cli build-docs openapi.yaml
+
+# Or auto-generate from code
+npx swagger-jsdoc -d swaggerDef.js routes/*.js -o openapi.json
+```
+
+### Generate TypeDoc
+```bash
+# API docs from TypeScript
+npx typedoc --out docs src/
+```
+
+### Mermaid Diagrams
+```markdown
+\`\`\`mermaid
+graph TD
+    A[Start] --> B[Process]
+    B --> C[End]
+\`\`\`
+```
+
+## Documentation Checklist
+
+### Minimum Viable
+- ✅ README with quick start
+- ✅ Installation instructions
+- ✅ Basic usage examples
+- ✅ Environment variables
+- ✅ License
+
+### Complete
+- ✅ All above
+- ✅ API reference
+- ✅ Architecture diagram
+- ✅ Contributing guide
+- ✅ Deployment guide
+- ✅ Troubleshooting
+- ✅ Changelog
+
+## Common Issues
+
+### Outdated Docs
+- Set up automation to check docs
+- Update docs with code changes
+- Add docs to CI/CD checks
+
+### Broken Links
+- Use link checker in CI
+- Test all examples
+- Verify external links
+
+### Missing Examples
+- Add code examples to all functions
+- Include error handling examples
+- Show common use cases
+
+## Integration with Other Commands
+
+**/code** → **/docs**
+- After generating code, document it
+
+**/review** → **/docs**
+- Review identifies missing docs
+
+**/test** → **/docs**
+- Tests validate doc examples work
+
+## Success Criteria
+
+Documentation is successful when:
+- ✅ New users can start in <10 minutes
+- ✅ All code examples work
+- ✅ API is fully documented
+- ✅ No broken links
+- ✅ Architecture is clear
+- ✅ Updated with code
+
+## Remember
+
+**Good documentation:**
+- Helps users succeed
+- Saves support time
+- Onboards developers
+- Shows professionalism
+
+**Write docs your future self will thank you for.**

package/templates/.claude/commands/plan.md

@@ -0,0 +1,57 @@
+---
+description: Create comprehensive implementation plan with research and architecture
+argument-hint: [feature or task description]
+---
+
+## Command: /plan
+
+Create a detailed implementation plan for the given feature or task.
+
+## Usage
+
+```
+/plan "implement user authentication with OAuth2"
+/plan "add real-time notifications"
+/plan "refactor database layer for PostgreSQL"
+```
+
+## Workflow
+
+1. **Get timestamp** - `date "+%y%m%d-%H%M"` (DO NOT guess dates)
+2. **Check memory** - Read `ai_context/memory/learning.md` for past lessons
+3. **Understand** the requirement
+4. **Ask** clarifying questions if needed
+5. **Delegate** to planner agent
+6. **Research** best practices and approaches
+7. **Create** comprehensive plan in `ai_context/plans/` directory
+8. **Update memory** - Record decisions in `ai_context/memory/decisions.md`
+
+## Plan Contents
+
+- **Overview** - Summary with phases
+- **Architecture** - Technical decisions
+- **Phases** - Step-by-step implementation
+- **Risks** - Potential issues and mitigation
+- **Security** - Security considerations
+- **Success Criteria** - Definition of done
+
+## Output
+
+Plan created at: `ai_context/plans/YYMMDD-HHMM-feature-name/`
+- `plan.md` - Main overview
+- `phase-*.md` - Detailed phases
+
+## Memory Integration
+
+Before planning:
+- Check `ai_context/memory/learning.md` for past mistakes to avoid
+
+After planning:
+- Update `ai_context/memory/decisions.md` with key decisions
+
+## Next Steps
+
+After plan creation:
+1. Review plan
+2. Approve or request changes
+3. Execute with `/code` or `/auto`