ai-sprint-kit 1.2.1 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-sprint-kit",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "CLI installer for autonomous coding agent framework - security-first, production-grade Claude Code setup",
   "main": "lib/installer.js",
   "bin": {

package/templates/.claude/agents/implementer.md

@@ -20,9 +20,62 @@ You are an **expert software developer** specializing in production-grade code i
 - **YAGNI** - Don't build what you don't need
 - **KISS** - Simple solutions are better
 - **DRY** - Eliminate duplication
+- **SRP** - One function = one operation
 - **Security-First** - Validate all inputs, no secrets in code
 - **Test-Driven** - Write tests alongside code
 
+## Code Generation Rules
+
+### Size Limits (Warning thresholds)
+- **500 lines max per file** - Split if exceeded
+- **50 lines max per function** - Extract if exceeded
+- **4 parameters max per function** - Use object if exceeded
+- **3 levels max nesting** - Flatten with early returns
+
+### YAGNI Rules
+```typescript
+// ❌ Unused parameter "for future use"
+function createUser(name: string, options?: UserOptions) {}
+
+// ✅ Only what's needed now
+function createUser(name: string) {}
+
+// ❌ Abstract class with single implementation
+abstract class BaseRepository<T> { ... }
+class UserRepository extends BaseRepository<User> { ... }
+
+// ✅ Concrete implementation
+class UserRepository { ... }
+```
+
+### KISS Rules
+```typescript
+// ❌ Clever code
+const result = arr.reduce((a, b) => ({...a, [b.id]: b}), {});
+
+// ✅ Readable code
+const result = {};
+for (const item of arr) {
+  result[item.id] = item;
+}
+```
+
+### SRP Rules
+```typescript
+// ❌ Function does multiple things
+function processUserAndSendEmail(user: User) {
+  validateUser(user);
+  saveToDatabase(user);
+  sendWelcomeEmail(user);
+  logAnalytics(user);
+}
+
+// ✅ Single responsibility
+function validateUser(user: User): ValidationResult {}
+function saveUser(user: User): Promise<User> {}
+function sendWelcomeEmail(user: User): Promise<void> {}
+```
+
 ## Tool Usage
 
 ### Allowed Tools

package/templates/.claude/agents/planner.md

@@ -20,9 +20,39 @@ You are an **expert software architect** with deep expertise in system design, t
 - **YAGNI** - You Aren't Gonna Need It
 - **KISS** - Keep It Simple, Stupid
 - **DRY** - Don't Repeat Yourself
+- **SRP** - Single Responsibility Principle
 - **Security-First** - Security in every decision
 - **Token Efficiency** - Concise, actionable output
 
+## Design Principles Anti-Patterns
+
+**Reject these patterns during planning:**
+
+### YAGNI Violations
+- "We might need X later" → Don't plan for hypothetical requirements
+- "Let's add a config option" → Only if currently needed
+- "This should be extensible" → Extensibility isn't free
+- Abstract base classes for single implementation → Premature abstraction
+
+### KISS Violations
+- Abstractions before concrete use cases
+- Generic solutions for specific problems
+- Multiple inheritance hierarchies upfront
+- Over-engineered patterns (Factory of Factories)
+
+### SRP Violations
+- God modules handling multiple domains
+- Utility files with unrelated functions
+- Components mixing UI/logic/data access
+- Files planned to exceed 500 lines
+
+### Planning Checklist
+Before finalizing any plan, ask:
+1. Is this feature explicitly requested? (YAGNI)
+2. Does a simpler alternative exist? (KISS)
+3. Does each module have one clear purpose? (SRP)
+4. Will any file exceed 500 lines? (Split it)
+
 ## Tool Usage
 
 ### Allowed Tools

package/templates/.claude/agents/reviewer.md

@@ -18,10 +18,43 @@ You are an **expert code reviewer** specializing in code quality, security analy
 ## Core Principles
 
 - **Security-First** - Every review includes security analysis
-- **YAGNI, KISS, DRY** - Simplicity over complexity
+- **YAGNI, KISS, DRY, SRP** - Simplicity over complexity
 - **Constructive** - Specific, actionable suggestions
 - **No Nitpicking** - Focus on meaningful improvements
 
+## Design Principles Check
+
+### Size Limits (Warning level)
+- [ ] Files < 500 lines
+- [ ] Functions < 50 lines
+- [ ] Parameters < 5 per function
+- [ ] Nesting < 4 levels
+
+### YAGNI Violations to Flag
+- [ ] Unused function parameters
+- [ ] Abstract classes with single implementation
+- [ ] Commented-out code "for reference"
+- [ ] Configuration options without current use
+- [ ] Generic solutions without concrete requirements
+
+### KISS Violations to Flag
+- [ ] Deep inheritance hierarchies (>2 levels)
+- [ ] Overly abstract patterns (Factory of Factories)
+- [ ] Complex conditionals (>3 conditions)
+- [ ] Clever code over readable code
+
+### SRP Violations to Flag
+- [ ] Classes with >7 public methods
+- [ ] Functions with "and" in name/purpose
+- [ ] Mixed concerns (UI+logic, data+formatting)
+- [ ] Utility files with unrelated functions
+
+### Remediation Guidance
+When flagging violations, suggest:
+1. **YAGNI**: What to remove/simplify
+2. **KISS**: How to make it simpler
+3. **SRP**: How to split responsibilities
+
 ## Tool Usage
 
 ### Allowed Tools

package/templates/.claude/agents/tester.md

@@ -21,6 +21,48 @@ You are an **expert QA engineer** specializing in test generation, coverage anal
 - **Test Pyramid** - 70% unit, 20% integration, 10% E2E
 - **Security-Focused** - Test auth, input validation, XSS, SQL injection
 - **Fast Feedback** - Tests run quickly
+- **Test Simplicity** - Tests should be obvious, not clever
+
+## Test Simplicity Rules
+
+### Size Limits
+- **20 lines max per test function** - Split if exceeded
+- **One assertion concept per test** - Focus on single behavior
+- **Max 3 mocks per test** - Too many = testing wrong abstraction
+
+### YAGNI in Tests
+```typescript
+// ❌ Over-engineered test helper
+class TestUserFactory {
+  static create(overrides?: Partial<User>) { ... }
+  static createMany(count: number) { ... }
+  static createWithPermissions(...) { ... }
+}
+
+// ✅ Simple inline data
+const user = { id: 1, name: 'Test' };
+```
+
+### KISS in Tests
+```typescript
+// ❌ Clever shared setup
+beforeEach(() => {
+  jest.spyOn(module, 'method').mockImplementation(...)
+  // 20 lines of setup
+});
+
+// ✅ Explicit per-test setup
+it('does X', () => {
+  const mock = jest.fn().mockReturnValue('result');
+  expect(someFunction(mock)).toBe('expected');
+});
+```
+
+### Test Smells to Avoid
+- [ ] Tests longer than code they test
+- [ ] Complex test helpers that need tests
+- [ ] Shared mutable state between tests
+- [ ] Testing implementation details
 
 ## Tool Usage
 

package/templates/.claude/commands/ai-sprint-review.md

@@ -27,6 +27,17 @@ Perform comprehensive code quality review focusing on security, maintainability,
 - Identify security issues
 - Analyze performance
 
+### 1.5. Design Principles Check (Warning)
+Run size checker:
+```bash
+python3 .claude/skills/quality-assurance/scripts/check-size.py --path $SCOPE
+```
+Flag (warning only):
+- Files >500 lines
+- Functions >50 lines
+- YAGNI violations (unused abstractions)
+- SRP violations (mixed concerns)
+
 ### 2. Security Review (Critical)
 - OWASP Top 10 compliance
 - SQL injection vulnerabilities
@@ -73,6 +84,12 @@ Perform comprehensive code quality review focusing on security, maintainability,
 - Minor optimizations
 - Naming suggestions
 
+### 🟡 Design Principle Warnings
+- Files exceeding 500 lines
+- Functions exceeding 50 lines
+- Over-engineered abstractions
+- Mixed responsibilities (SRP)
+
 ## Example Review Report
 
 ```markdown

package/templates/.claude/commands/ai-sprint-validate.md

@@ -36,6 +36,15 @@ Check `ai_context/memory/learning.md` for known validation issues.
 - Analyze complexity
 - Identify code smells
 
+### 2.5. Design Principles Check (Warning)
+Run size checker:
+```bash
+python3 .claude/skills/quality-assurance/scripts/check-size.py
+```
+Flag as warnings (non-blocking):
+- Files >500 lines
+- Functions >50 lines
+
 ### 3. Security Scan
 - SAST scanning
 - Secret detection
@@ -57,10 +66,15 @@ Save to: `ai_context/reports/ai-sprint-validate-{timestamp}.md`
 ### Code Quality (Reviewer Agent)
 - [ ] No linting errors
 - [ ] Types complete
-- [ ] Functions < 50 lines
 - [ ] No code smells
 - [ ] Documentation present
 
+### Design Principles (Warning only)
+- [ ] Files < 500 lines
+- [ ] Functions < 50 lines
+- [ ] No YAGNI violations
+- [ ] No SRP violations
+
 ### Security (Security Agent)
 - [ ] No hardcoded secrets
 - [ ] Input validation present
@@ -85,6 +99,7 @@ Save to: `ai_context/reports/ai-sprint-validate-{timestamp}.md`
 | Tests    | ✅/❌   | X      |
 | Coverage | ✅/❌   | X%     |
 | Quality  | ✅/❌   | X      |
+| Design   | ⚠️/✅   | X      |
 | Security | ✅/❌   | X      |
 
 ## Test Results

package/templates/.claude/skills/quality-assurance/scripts/check-size.py

@@ -0,0 +1,333 @@
+#!/usr/bin/env python3
+"""
+Design principles size checker.
+Detects files >500 lines and functions >50 lines.
+Supports: Python, JavaScript, TypeScript, Go, Java, Rust
+Exit code: 0 = no violations (pass), 1 = violations found (warn only)
+"""
+
+import argparse
+import ast
+import os
+import re
+import sys
+from pathlib import Path
+from dataclasses import dataclass
+from typing import List
+
+@dataclass
+class Violation:
+    file: str
+    line: int
+    type: str  # 'file' or 'function'
+    name: str
+    actual: int
+    limit: int
+
+
+def count_file_lines(path: Path) -> int:
+    """Count non-empty, non-comment lines."""
+    try:
+        with open(path, 'r', encoding='utf-8', errors='ignore') as f:
+            lines = [l for l in f.readlines() if l.strip()
+                     and not l.strip().startswith(('#', '//', '--', '/*', '*'))]
+            return len(lines)
+    except Exception:
+        return 0
+
+
+def check_python_functions(path: Path, max_lines: int) -> List[Violation]:
+    """Check Python function lengths using AST."""
+    violations = []
+    try:
+        with open(path, 'r', encoding='utf-8') as f:
+            tree = ast.parse(f.read())
+        for node in ast.walk(tree):
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                length = (node.end_lineno or node.lineno) - node.lineno + 1
+                if length > max_lines:
+                    violations.append(Violation(
+                        file=str(path), line=node.lineno, type='function',
+                        name=node.name, actual=length, limit=max_lines
+                    ))
+    except (SyntaxError, Exception):
+        pass
+    return violations
+
+
+def check_js_functions(path: Path, max_lines: int) -> List[Violation]:
+    """Check JS/TS function lengths using brace counting."""
+    violations = []
+    try:
+        with open(path, 'r', encoding='utf-8') as f:
+            lines = f.readlines()
+
+        func_pattern = re.compile(
+            r'(function\s+(\w+)|(\w+)\s*=\s*(async\s+)?\([^)]*\)\s*=>|'
+            r'(async\s+)?(\w+)\s*\([^)]*\)\s*\{)'
+        )
+
+        in_func = False
+        func_start = 0
+        func_name = 'anonymous'
+        brace_count = 0
+
+        for i, line in enumerate(lines, 1):
+            if not in_func:
+                match = func_pattern.search(line)
+                if match and '{' in line:
+                    in_func = True
+                    func_start = i
+                    func_name = match.group(2) or match.group(3) or match.group(6) or 'anonymous'
+                    brace_count = line.count('{') - line.count('}')
+            else:
+                brace_count += line.count('{') - line.count('}')
+                if brace_count <= 0:
+                    length = i - func_start + 1
+                    if length > max_lines:
+                        violations.append(Violation(
+                            file=str(path), line=func_start, type='function',
+                            name=func_name, actual=length, limit=max_lines
+                        ))
+                    in_func = False
+                    brace_count = 0
+    except Exception:
+        pass
+    return violations
+
+
+def check_go_functions(path: Path, max_lines: int) -> List[Violation]:
+    """Check Go function lengths."""
+    violations = []
+    try:
+        with open(path, 'r', encoding='utf-8') as f:
+            lines = f.readlines()
+
+        func_pattern = re.compile(r'^func\s+(\w+|\([^)]+\)\s+\w+)\s*\(')
+        in_func = False
+        func_start = 0
+        func_name = ''
+        brace_count = 0
+
+        for i, line in enumerate(lines, 1):
+            if not in_func:
+                match = func_pattern.match(line)
+                if match:
+                    in_func = True
+                    func_start = i
+                    func_name = match.group(1).split()[-1]
+                    brace_count = line.count('{') - line.count('}')
+            else:
+                brace_count += line.count('{') - line.count('}')
+                if brace_count <= 0:
+                    length = i - func_start + 1
+                    if length > max_lines:
+                        violations.append(Violation(
+                            file=str(path), line=func_start, type='function',
+                            name=func_name, actual=length, limit=max_lines
+                        ))
+                    in_func = False
+    except Exception:
+        pass
+    return violations
+
+
+def check_java_functions(path: Path, max_lines: int) -> List[Violation]:
+    """Check Java method lengths."""
+    violations = []
+    try:
+        with open(path, 'r', encoding='utf-8') as f:
+            lines = f.readlines()
+
+        method_pattern = re.compile(
+            r'(public|private|protected|static|\s)+[\w<>\[\]]+\s+(\w+)\s*\([^)]*\)\s*(\{|throws)'
+        )
+        in_method = False
+        method_start = 0
+        method_name = ''
+        brace_count = 0
+
+        for i, line in enumerate(lines, 1):
+            if not in_method:
+                match = method_pattern.search(line)
+                if match and '{' in line:
+                    in_method = True
+                    method_start = i
+                    method_name = match.group(2)
+                    brace_count = line.count('{') - line.count('}')
+            else:
+                brace_count += line.count('{') - line.count('}')
+                if brace_count <= 0:
+                    length = i - method_start + 1
+                    if length > max_lines:
+                        violations.append(Violation(
+                            file=str(path), line=method_start, type='function',
+                            name=method_name, actual=length, limit=max_lines
+                        ))
+                    in_method = False
+    except Exception:
+        pass
+    return violations
+
+
+def check_rust_functions(path: Path, max_lines: int) -> List[Violation]:
+    """Check Rust function lengths."""
+    violations = []
+    try:
+        with open(path, 'r', encoding='utf-8') as f:
+            lines = f.readlines()
+
+        func_pattern = re.compile(r'^\s*(pub\s+)?(async\s+)?fn\s+(\w+)')
+        in_func = False
+        func_start = 0
+        func_name = ''
+        brace_count = 0
+
+        for i, line in enumerate(lines, 1):
+            if not in_func:
+                match = func_pattern.match(line)
+                if match and '{' in line:
+                    in_func = True
+                    func_start = i
+                    func_name = match.group(3)
+                    brace_count = line.count('{') - line.count('}')
+            else:
+                brace_count += line.count('{') - line.count('}')
+                if brace_count <= 0:
+                    length = i - func_start + 1
+                    if length > max_lines:
+                        violations.append(Violation(
+                            file=str(path), line=func_start, type='function',
+                            name=func_name, actual=length, limit=max_lines
+                        ))
+                    in_func = False
+    except Exception:
+        pass
+    return violations
+
+
+LANG_CHECKERS = {
+    '.py': check_python_functions,
+    '.js': check_js_functions,
+    '.ts': check_js_functions,
+    '.tsx': check_js_functions,
+    '.jsx': check_js_functions,
+    '.go': check_go_functions,
+    '.java': check_java_functions,
+    '.rs': check_rust_functions,
+}
+
+SKIP_DIRS = {'node_modules', '.git', 'dist', 'build', '__pycache__', '.venv',
+             'venv', 'vendor', 'target', '.next', 'coverage'}
+
+
+def scan_directory(path: Path, max_file: int, max_func: int) -> List[Violation]:
+    """Scan directory for size violations."""
+    violations = []
+
+    for root, dirs, files in os.walk(path):
+        dirs[:] = [d for d in dirs if d not in SKIP_DIRS]
+
+        for file in files:
+            filepath = Path(root) / file
+            ext = filepath.suffix.lower()
+
+            if ext not in LANG_CHECKERS:
+                continue
+
+            # Check file length
+            file_lines = count_file_lines(filepath)
+            if file_lines > max_file:
+                violations.append(Violation(
+                    file=str(filepath), line=1, type='file',
+                    name=file, actual=file_lines, limit=max_file
+                ))
+
+            # Check function lengths
+            checker = LANG_CHECKERS.get(ext)
+            if checker:
+                violations.extend(checker(filepath, max_func))
+
+    return violations
+
+
+def generate_report(violations: List[Violation]) -> str:
+    """Generate markdown report."""
+    if not violations:
+        return "# Size Check Report\n\n**Status:** ✅ PASS\n\nNo design principle violations found."
+
+    file_v = [v for v in violations if v.type == 'file']
+    func_v = [v for v in violations if v.type == 'function']
+
+    lines = [
+        "# Size Check Report",
+        "",
+        "**Status:** ⚠️ WARNING",
+        "",
+        f"**Total Violations:** {len(violations)}",
+        f"- Files exceeding limit: {len(file_v)}",
+        f"- Functions exceeding limit: {len(func_v)}",
+        ""
+    ]
+
+    if file_v:
+        lines.extend([
+            "## Files Exceeding 500 Lines",
+            "",
+            "| File | Lines | Limit |",
+            "|------|-------|-------|"
+        ])
+        for v in sorted(file_v, key=lambda x: -x.actual):
+            lines.append(f"| `{v.file}` | {v.actual} | {v.limit} |")
+        lines.append("")
+
+    if func_v:
+        lines.extend([
+            "## Functions Exceeding 50 Lines",
+            "",
+            "| File | Line | Function | Lines | Limit |",
+            "|------|------|----------|-------|-------|"
+        ])
+        for v in sorted(func_v, key=lambda x: -x.actual):
+            lines.append(f"| `{v.file}` | {v.line} | `{v.name}` | {v.actual} | {v.limit} |")
+        lines.append("")
+
+    lines.extend([
+        "## Remediation",
+        "",
+        "### Large Files",
+        "- Identify logical groupings",
+        "- Extract to separate modules",
+        "",
+        "### Long Functions",
+        "- Extract helper functions",
+        "- Apply single responsibility principle"
+    ])
+
+    return "\n".join(lines)
+
+
+def main():
+    parser = argparse.ArgumentParser(description='Check code size limits (warning only)')
+    parser.add_argument('--path', default='.', help='Directory to scan')
+    parser.add_argument('--max-file-lines', type=int, default=500)
+    parser.add_argument('--max-function-lines', type=int, default=50)
+    parser.add_argument('--output', help='Output file (default: stdout)')
+
+    args = parser.parse_args()
+    violations = scan_directory(Path(args.path), args.max_file_lines, args.max_function_lines)
+    report = generate_report(violations)
+
+    if args.output:
+        with open(args.output, 'w') as f:
+            f.write(report)
+        print(f"Report saved to {args.output}")
+    else:
+        print(report)
+
+    # Exit 1 if violations (for CI awareness), but documented as warning only
+    sys.exit(1 if violations else 0)
+
+
+if __name__ == '__main__':
+    main()

package/templates/.claude/workflows/development-rules.md

@@ -7,7 +7,43 @@ Core principles enforced across all agents and commands.
 1. **YAGNI** - You Aren't Gonna Need It
 2. **KISS** - Keep It Simple, Stupid
 3. **DRY** - Don't Repeat Yourself
-4. **Security-First** - Security in every layer
+4. **SRP** - Single Responsibility Principle
+5. **Security-First** - Security in every layer
+
+## Design Principles Enforcement
+
+### Size Limits (Warning level - non-blocking)
+| Metric | Limit | Action if Exceeded |
+|--------|-------|-------------------|
+| File lines | 500 | Split into modules |
+| Function lines | 50 | Extract helpers |
+| Parameters | 4 | Use options object |
+| Nesting levels | 3 | Use early returns |
+
+### YAGNI Checklist
+- Only build explicitly requested features
+- Delete unused code immediately
+- No "future-proofing" abstractions
+- No unused parameters "for later"
+
+### KISS Checklist
+- Prefer explicit over implicit
+- Prefer flat over nested
+- Prefer composition over inheritance
+- No clever code - readable > clever
+
+### SRP Checklist
+- One file = one concept
+- One function = one operation
+- If name needs "and" → split it
+
+### Automated Checking
+Run size checker (warning only):
+```bash
+python3 .claude/skills/quality-assurance/scripts/check-size.py
+```
+
+Included in `/ai-sprint-review` and `/ai-sprint-validate` workflows.
 
 ## Date Handling