ai-sprint-kit 1.1.0

package/templates/.claude/skills/codebase-context/references/reading-context.md

@@ -0,0 +1,68 @@
+# Reading Codebase Context
+
+## Recommended Order
+
+### 1. structure.md (Quick - <1 min)
+- Understand project layout
+- Identify key directories (src/, lib/, api/)
+- Find configuration files
+- Note test file locations
+
+### 2. overview.md (Comprehensive - 5-10 min)
+- Markdown format, human-readable
+- Contains all source code compressed
+- Files sorted by Git change frequency
+- Good for understanding patterns
+
+### 3. repomix-output.xml (As needed)
+- XML format optimized for AI parsing
+- Most token-efficient for large queries
+- Use for specific file searches
+- Best for detailed code analysis
+
+## Token Efficiency Tips
+
+| Need | Do This |
+|------|---------|
+| Quick overview | Read structure.md only |
+| Understand feature | Read overview.md section |
+| Find specific code | Grep in overview.md |
+| Exact line numbers | Read source file directly |
+
+## Understanding Compression
+
+Repomix uses Tree-sitter AST compression:
+- Removes unnecessary whitespace
+- Uses delimiter `⋮----` between sections
+- Files sorted by Git change frequency (most active first)
+- ~70% token reduction from raw code
+
+## When to Read Files Directly
+
+Use Read tool instead of context when:
+- Need exact line numbers for editing
+- File was modified after last scan
+- Debugging specific issue
+- File excluded from scan (in .repomixignore)
+
+## Example Workflow
+
+```
+1. Check structure.md
+   → Identify: src/auth/, src/api/
+
+2. Read overview.md section on auth
+   → Understand: JWT strategy, middleware pattern
+
+3. Read src/auth/jwt.ts directly
+   → Get: exact code for modification
+```
+
+## Integration with Agents
+
+| Agent | Context Usage |
+|-------|---------------|
+| Planner | Read structure + overview before designing |
+| Implementer | Check patterns in overview, then read specific files |
+| Reviewer | Reference overview for consistency checks |
+| Tester | Find test patterns from overview |

package/templates/.claude/skills/codebase-context/references/refresh-triggers.md

@@ -0,0 +1,82 @@
+# When to Refresh Codebase Context
+
+## Refresh Triggers
+
+Run `/scan` command when:
+
+### 1. After Major Changes
+- New features added
+- Architecture refactored
+- Multiple files modified
+- New directories created
+
+### 2. Stale Context Detected
+- scan-metadata.json > 1 day old
+- New files not in structure.md
+- Code behavior differs from overview.md
+- Team members made changes
+
+### 3. Before Major Work
+- Starting new feature implementation
+- Beginning architecture planning
+- Before comprehensive code review
+
+## How to Check Freshness
+
+```bash
+# Check when last scanned
+cat ai_context/codebase/scan-metadata.json
+
+# Look for scanDate field
+# Compare with today's date
+```
+
+## What Gets Scanned
+
+**Included by default:**
+- Source code directories (src/, lib/, app/, pages/, components/)
+- Configuration files (*.json, *.yaml, *.toml)
+- Test files (unless ignored)
+
+**Excluded by default:**
+- node_modules/
+- .git/
+- dist/, build/, .next/
+- .env files (security)
+- Lock files (package-lock.json, yarn.lock)
+- Coverage reports
+
+## Custom Ignore
+
+Create `.repomixignore` in project root:
+
+```
+# Custom ignores
+*.log
+temp/
+*.generated.ts
+large-data/
+```
+
+## Refresh Commands
+
+```bash
+# Using Claude command
+/scan
+
+# Using CLI directly
+ai-sprint scan
+
+# Specific directory
+ai-sprint scan --dir /path/to/project
+```
+
+## Refresh Frequency Guidelines
+
+| Situation | Recommendation |
+|-----------|----------------|
+| Active development | Daily |
+| Stable codebase | Weekly |
+| Before major feature | Always |
+| After team changes | Always |
+| Quick bug fix | Skip if <1 day old |

package/templates/.claude/skills/implementation/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: implementation
+description: Secure coding standards and patterns. Activate when generating or refactoring code. Enforces security-first approach with proper error handling, input validation, and test coverage requirements.
+license: MIT
+---
+
+# Implementation Standards
+
+Production-grade coding patterns with security-first approach.
+
+## When to Use
+
+- Generating new code
+- Refactoring existing code
+- Fixing bugs
+- Adding features
+
+## Core Principles
+
+- **Security-First** - Every line considers security
+- **Test-Driven** - Write tests alongside code
+- **Clean Code** - Simple, readable, maintainable
+- **YAGNI/KISS/DRY** - No over-engineering
+
+## Before Implementing
+
+```
+1. Read ai_context/memory/learning.md (avoid past mistakes)
+2. Read relevant plan in ai_context/plans/
+3. Understand existing patterns in codebase
+4. Check ai_context/codebase/structure.md for project layout
+```
+
+## Security Requirements
+
+Load: `references/security-patterns.md`
+
+## Error Handling
+
+Load: `references/error-handling.md`
+
+## Validation Patterns
+
+Load: `references/validation-patterns.md`
+
+## Output Structure
+
+```
+ai_context/reports/
+└── YYMMDD-HHMM-implementation-{feature}.md
+```
+
+## Quality Gates
+
+Before completing:
+- [ ] Tests pass (>80% coverage)
+- [ ] Linting passes
+- [ ] Type checks pass
+- [ ] No security vulnerabilities
+- [ ] No hardcoded secrets
+- [ ] Error handling complete
+- [ ] Input validation on all boundaries
+
+## Date Handling
+
+Always use bash for timestamps:
+```bash
+date "+%y%m%d-%H%M"    # For filenames: 251225-1430
+date "+%Y-%m-%d"       # For docs: 2025-12-25
+```

package/templates/.claude/skills/implementation/references/error-handling.md

@@ -0,0 +1,106 @@
+# Error Handling
+
+## Principles
+
+1. **Fail Fast** - Validate early, fail clearly
+2. **Don't Swallow Errors** - Always handle or propagate
+3. **Log Context** - Include relevant debugging info
+4. **User-Friendly** - Generic messages to users, details in logs
+
+## Pattern: Specific Error Handling
+
+```typescript
+// GOOD - Specific error handling
+try {
+  await processPayment(amount);
+} catch (error) {
+  if (error instanceof PaymentDeclinedError) {
+    return { success: false, reason: 'Payment declined' };
+  }
+  if (error instanceof NetworkError) {
+    logger.error('Payment network error', { error, amount });
+    return { success: false, reason: 'Service unavailable' };
+  }
+  // Unexpected error - log and rethrow
+  logger.error('Unexpected payment error', { error, amount });
+  throw new InternalError('Payment processing failed');
+}
+
+// BAD - Generic handling
+try {
+  await processPayment(amount);
+} catch (error) {
+  console.log(error); // Exposes internals
+}
+```
+
+## Pattern: Error Hierarchy
+
+```typescript
+class AppError extends Error {
+  constructor(
+    message: string,
+    public code: string,
+    public statusCode: number = 500
+  ) {
+    super(message);
+    this.name = this.constructor.name;
+  }
+}
+
+class ValidationError extends AppError {
+  constructor(message: string) {
+    super(message, 'VALIDATION_ERROR', 400);
+  }
+}
+
+class NotFoundError extends AppError {
+  constructor(resource: string) {
+    super(`${resource} not found`, 'NOT_FOUND', 404);
+  }
+}
+
+class ForbiddenError extends AppError {
+  constructor(message = 'Access denied') {
+    super(message, 'FORBIDDEN', 403);
+  }
+}
+```
+
+## Logging Context
+
+```typescript
+// Include useful context
+logger.error('Operation failed', {
+  error: error.message,
+  stack: error.stack,
+  userId: user.id,
+  operation: 'createOrder',
+  input: { orderId, amount } // Sanitized input
+});
+
+// Never log sensitive data
+// BAD: logger.info('Login', { password: pwd });
+// GOOD: logger.info('Login attempt', { email, success: true });
+```
+
+## API Error Responses
+
+```typescript
+app.use((error, req, res, next) => {
+  const statusCode = error.statusCode || 500;
+  const message = statusCode === 500
+    ? 'Internal server error'
+    : error.message;
+
+  res.status(statusCode).json({
+    error: {
+      code: error.code || 'INTERNAL_ERROR',
+      message,
+      ...(process.env.NODE_ENV === 'development' && {
+        stack: error.stack
+      })
+    }
+  });
+});
+```

package/templates/.claude/skills/implementation/references/security-patterns.md

@@ -0,0 +1,73 @@
+# Security Patterns
+
+## Mandatory Checks
+
+### No Hardcoded Secrets
+```typescript
+// BAD
+const API_KEY = "sk_live_abc123";
+
+// GOOD
+const API_KEY = process.env.API_KEY;
+if (!API_KEY) throw new Error('API_KEY not configured');
+```
+
+### Input Validation
+```typescript
+// Validate ALL user inputs
+function createUser(email: string, password: string) {
+  if (!isValidEmail(email)) throw new ValidationError('Invalid email');
+  if (!isStrongPassword(password)) throw new ValidationError('Weak password');
+}
+```
+
+### Parameterized Queries
+```typescript
+// BAD - SQL Injection vulnerable
+const query = `SELECT * FROM users WHERE email = '${email}'`;
+
+// GOOD - Parameterized
+const query = `SELECT * FROM users WHERE email = $1`;
+const result = await db.query(query, [email]);
+```
+
+### Output Encoding
+```typescript
+// Escape user content before rendering
+const safeHtml = escapeHtml(userInput);
+```
+
+## OWASP Top 10 Checklist
+
+- [ ] Broken Access Control - Check auth on every endpoint
+- [ ] Cryptographic Failures - Use strong encryption
+- [ ] Injection - Parameterize all queries
+- [ ] Insecure Design - Threat model early
+- [ ] Security Misconfiguration - Secure defaults
+- [ ] Vulnerable Components - Update dependencies
+- [ ] Authentication Failures - Strong auth
+- [ ] Data Integrity Failures - Verify signatures
+- [ ] Logging Failures - Log security events
+- [ ] SSRF - Validate URLs
+
+## Authentication Pattern
+
+```typescript
+async function protectedRoute(req, res) {
+  const user = await verifyToken(req.headers.authorization);
+  if (!user) return res.status(401).json({ error: 'Unauthorized' });
+  // Continue with request
+}
+```
+
+## Authorization Pattern
+
+```typescript
+async function deleteResource(userId, resourceId) {
+  const resource = await getResource(resourceId);
+  if (resource.ownerId !== userId) {
+    throw new ForbiddenError('Not authorized');
+  }
+  await resource.delete();
+}
+```

package/templates/.claude/skills/implementation/references/validation-patterns.md

@@ -0,0 +1,107 @@
+# Validation Patterns
+
+## Input Validation Principles
+
+1. **Validate at Boundaries** - API endpoints, form handlers
+2. **Fail Fast** - Reject invalid input immediately
+3. **Whitelist** - Allow known-good, reject everything else
+4. **Type Safety** - Use TypeScript/schemas
+
+## Pattern: Schema Validation
+
+```typescript
+import { z } from 'zod';
+
+const createUserSchema = z.object({
+  email: z.string().email(),
+  password: z.string().min(8).regex(/[A-Z]/).regex(/[0-9]/),
+  name: z.string().min(1).max(100),
+});
+
+function createUser(input: unknown) {
+  const validated = createUserSchema.parse(input);
+  return db.users.create(validated);
+}
+```
+
+## Pattern: Sanitization
+
+```typescript
+import DOMPurify from 'dompurify';
+
+function saveComment(content: string) {
+  const sanitized = DOMPurify.sanitize(content, {
+    ALLOWED_TAGS: ['b', 'i', 'a'],
+    ALLOWED_ATTR: ['href']
+  });
+  return db.comments.create({ content: sanitized });
+}
+```
+
+## Pattern: Type Guards
+
+```typescript
+function isValidUser(user: unknown): user is User {
+  return (
+    typeof user === 'object' &&
+    user !== null &&
+    'id' in user &&
+    'email' in user &&
+    typeof user.email === 'string'
+  );
+}
+
+function processUser(user: unknown) {
+  if (!isValidUser(user)) {
+    throw new ValidationError('Invalid user data');
+  }
+  // user is now typed as User
+}
+```
+
+## Common Validations
+
+```typescript
+// Email
+const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+// URL
+function isValidUrl(url: string): boolean {
+  try {
+    new URL(url);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// UUID
+const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+// Phone (basic international)
+const phoneRegex = /^\+?[1-9]\d{1,14}$/;
+```
+
+## API Validation Middleware
+
+```typescript
+function validate(schema: z.ZodSchema) {
+  return (req, res, next) => {
+    try {
+      req.body = schema.parse(req.body);
+      next();
+    } catch (error) {
+      if (error instanceof z.ZodError) {
+        return res.status(400).json({
+          error: 'Validation failed',
+          details: error.errors
+        });
+      }
+      next(error);
+    }
+  };
+}
+
+// Usage
+app.post('/users', validate(createUserSchema), createUserHandler);
+```

package/templates/.claude/skills/memory/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: memory
+description: Cross-session learning and decision tracking. Activate when starting tasks (check past lessons) or after completing work (record learnings). Provides formats for learning.md, decisions.md, and active.md in ai_context/memory/.
+license: MIT
+---
+
+# Memory System
+
+Persistent learning across sessions via ai_context/memory/ files.
+
+## When to Use
+
+**Before starting work:**
+- Read `ai_context/memory/learning.md` to avoid past mistakes
+- Check `ai_context/memory/decisions.md` for architectural context
+
+**After completing work:**
+- Record new lessons in `learning.md`
+- Document key decisions in `decisions.md`
+- Update `active.md` with session context
+
+## Memory Files
+
+### learning.md
+Retrospective lessons to avoid repeating mistakes.
+Load: `references/learning-format.md`
+
+### decisions.md
+Key architectural and design decisions with rationale.
+Load: `references/decisions-format.md`
+
+### active.md
+Current session context (temporary, overwritten each session).
+
+Format:
+```markdown
+# Active Session Context
+
+## Current Focus
+[What you're working on]
+
+## Recent Changes
+[What was just modified]
+
+## Blockers
+[Any issues or questions]
+```
+
+## Quick Reference
+
+**Check before implementing:**
+```bash
+cat ai_context/memory/learning.md
+cat ai_context/memory/decisions.md
+```
+
+**Update after completing:**
+1. Append to learning.md if learned something new
+2. Append to decisions.md if made a key architectural choice
+3. Update active.md with current session state
+
+## Integration
+
+All agents should:
+1. Read memory files at task start
+2. Update memory files after significant work
+3. Reference past decisions when planning new features

package/templates/.claude/skills/memory/references/decisions-format.md

@@ -0,0 +1,68 @@
+# Decisions Log Format
+
+## Entry Structure
+
+```markdown
+## [YYYY-MM-DD] - [Decision Title]
+
+**Context**: Why this decision was needed
+**Options Considered**:
+1. Option A - [brief pros/cons]
+2. Option B - [brief pros/cons]
+
+**Decision**: What was chosen
+**Rationale**: Why this choice
+**Implications**: What this affects going forward
+```
+
+## When to Log Decisions
+
+Document choices about:
+- Architecture patterns (monolith vs microservices)
+- Technology stack (framework, database, etc.)
+- API design (REST vs GraphQL)
+- Authentication approach (JWT, sessions, OAuth)
+- Deployment strategy (serverless, containers)
+- Testing strategy (unit vs integration focus)
+- Third-party integrations
+
+## Example Entry
+
+```markdown
+## 2025-12-24 - Authentication Strategy
+
+**Context**: Need user authentication for the application
+
+**Options Considered**:
+1. Session-based - Simple, server-side state, harder to scale
+2. JWT - Stateless, scalable, more complex implementation
+3. OAuth only - Delegate to providers, limited control
+
+**Decision**: JWT with refresh tokens
+
+**Rationale**:
+- Stateless for horizontal scaling
+- Refresh tokens for security
+- Can add OAuth providers later
+
+**Implications**:
+- Need secure token storage (httpOnly cookies)
+- Implement refresh token rotation
+- Consider token blacklist for logout
+```
+
+## Best Practices
+
+- Record decision when made, not later
+- Include "why" not just "what"
+- List options even if choice was obvious
+- Note constraints that influenced the decision
+- Link to related plans if applicable
+- Keep entries self-contained (readable without context)
+
+## Reading Decisions
+
+Before planning new features:
+1. Check if related decisions exist
+2. Consider if constraints have changed
+3. Reference existing decisions in new plans