ai-sprint-kit 1.2.1 → 1.3.1

package/lib/installer.js

@@ -17,64 +17,72 @@ async function checkExisting(targetDir) {
  */
 async function install(targetDir, options = {}) {
   const { force = false, skipInstall = false } = options;
-
   const templateDir = path.join(__dirname, '../templates');
   const claudeDir = path.join(targetDir, '.claude');
 
-  // Remove existing if force flag
-  if (force && await fs.pathExists(claudeDir)) {
-    const spinner = ora('Removing existing .claude/ directory...').start();
-    await fs.remove(claudeDir);
-    spinner.succeed('Removed existing .claude/ directory');
-  }
+  await removeExistingIfForce(claudeDir, force);
 
-  // Copy template directory
   const spinner = ora('Installing framework...').start();
-
   try {
-    // Copy .claude/ directory
-    await fs.copy(
-      path.join(templateDir, '.claude'),
-      claudeDir,
-      { overwrite: force }
-    );
-
-    // Copy root files (including MCP config template)
-    const rootFiles = ['CLAUDE.md', 'README.md', '.mcp.json.example'];
-    for (const file of rootFiles) {
-      const srcPath = path.join(templateDir, file);
-      const destPath = path.join(targetDir, file);
-
-      if (await fs.pathExists(srcPath)) {
-        // Only copy if doesn't exist or force flag
-        if (!await fs.pathExists(destPath) || force) {
-          await fs.copy(srcPath, destPath);
-        }
-      }
-    }
-
-    // Copy docs directory (user guide)
-    const docsDir = path.join(templateDir, 'docs');
-    if (await fs.pathExists(docsDir)) {
-      await fs.copy(docsDir, path.join(targetDir, 'docs'), { overwrite: force });
-    }
-
+    await copyTemplateFiles(templateDir, targetDir, claudeDir, force);
     spinner.succeed('Framework installed');
 
-    // Install skill dependencies
     if (!skipInstall) {
       await installSkillDependencies(claudeDir);
     }
-
-    // Create initial directories
     await createInitialDirs(targetDir);
-
   } catch (error) {
     spinner.fail('Installation failed');
     throw error;
   }
 }
 
+/**
+ * Remove existing .claude/ directory if force flag is set
+ */
+async function removeExistingIfForce(claudeDir, force) {
+  if (force && await fs.pathExists(claudeDir)) {
+    const spinner = ora('Removing existing .claude/ directory...').start();
+    await fs.remove(claudeDir);
+    spinner.succeed('Removed existing .claude/ directory');
+  }
+}
+
+/**
+ * Copy template files to target directory
+ */
+async function copyTemplateFiles(templateDir, targetDir, claudeDir, force) {
+  // Copy .claude/ directory
+  await fs.copy(path.join(templateDir, '.claude'), claudeDir, { overwrite: force });
+
+  // Copy root files
+  await copyRootFiles(templateDir, targetDir, force);
+
+  // Copy user guide to .claude/docs (avoid overwriting user's docs/)
+  const docsDir = path.join(templateDir, 'docs');
+  if (await fs.pathExists(docsDir)) {
+    await fs.copy(docsDir, path.join(claudeDir, 'docs'), { overwrite: force });
+  }
+}
+
+/**
+ * Copy root template files (CLAUDE.md, README.md, etc.)
+ */
+async function copyRootFiles(templateDir, targetDir, force) {
+  const rootFiles = ['CLAUDE.md', 'README.md', '.mcp.json.example'];
+
+  for (const file of rootFiles) {
+    const srcPath = path.join(templateDir, file);
+    const destPath = path.join(targetDir, file);
+
+    if (await fs.pathExists(srcPath)) {
+      if (!await fs.pathExists(destPath) || force) {
+        await fs.copy(srcPath, destPath);
+      }
+    }
+  }
+}
+
 /**
  * Install Python dependencies for skills
  */
@@ -129,19 +137,42 @@ async function createInitialDirs(targetDir) {
     'ai_context/plans',
     'ai_context/docs',
     'ai_context/reports',
-    'ai_context/memory',
-    'docs',
-    'plans',
-    'plans/reports'
+    'ai_context/reports/research',
+    'ai_context/reports/review',
+    'ai_context/reports/security',
+    'ai_context/reports/test',
+    'ai_context/reports/debug',
+    'ai_context/reports/deploy',
+    'ai_context/reports/docs',
+    'ai_context/memory'
   ];
 
   for (const dir of dirs) {
-    const dirPath = path.join(targetDir, dir);
-    await fs.ensureDir(dirPath);
+    await fs.ensureDir(path.join(targetDir, dir));
+  }
+
+  await createMemoryFiles(targetDir);
+}
+
+/**
+ * Create initial memory template files
+ */
+async function createMemoryFiles(targetDir) {
+  const memoryFiles = getMemoryFileTemplates();
+
+  for (const [file, content] of Object.entries(memoryFiles)) {
+    const filePath = path.join(targetDir, file);
+    if (!await fs.pathExists(filePath)) {
+      await fs.writeFile(filePath, content);
+    }
   }
+}
 
-  // Create initial memory files
-  const memoryFiles = {
+/**
+ * Get memory file templates
+ */
+function getMemoryFileTemplates() {
+  return {
     'ai_context/memory/learning.md': `# Learning Log
 
 Lessons learned from past development sessions.
@@ -190,13 +221,6 @@ _None_
 _None_
 `
   };
-
-  for (const [file, content] of Object.entries(memoryFiles)) {
-    const filePath = path.join(targetDir, file);
-    if (!await fs.pathExists(filePath)) {
-      await fs.writeFile(filePath, content);
-    }
-  }
 }
 
 module.exports = {

package/lib/scanner.js

@@ -65,60 +65,43 @@ async function checkRepomix() {
 
 /**
  * Run repomix scan on target directory
- * @param {string} targetDir - Directory to scan
- * @param {string} outputDir - Output directory for scan results
- * @param {object} options - Scan options
- * @returns {Promise<object>} - Scan results
  */
 async function runRepomixScan(targetDir, outputDir, options = {}) {
   const { useNpx = false } = options;
-
-  // Create output directory
   await fs.ensureDir(outputDir);
 
   const xmlOutput = path.join(outputDir, 'repomix-output.xml');
   const mdOutput = path.join(outputDir, 'overview.md');
 
-  // Build base command
-  const baseCmd = useNpx ? 'npx' : 'repomix';
-  const baseArgs = useNpx ? ['repomix'] : [];
+  await runRepomixCommand(targetDir, xmlOutput, 'xml', useNpx);
+  await runRepomixCommand(targetDir, mdOutput, 'markdown', useNpx);
 
-  // Generate XML output (for AI consumption)
-  const xmlArgs = [
-    ...baseArgs,
-    '--compress',
-    '--style', 'xml',
-    '-o', xmlOutput
-  ];
+  return parseRepomixStats(xmlOutput);
+}
 
-  await execa(baseCmd, xmlArgs, {
-    cwd: targetDir,
-    timeout: 300000 // 5 minute timeout
-  });
+/**
+ * Execute repomix command with specified style
+ */
+async function runRepomixCommand(targetDir, outputPath, style, useNpx) {
+  const baseCmd = useNpx ? 'npx' : 'repomix';
+  const baseArgs = useNpx ? ['repomix'] : [];
 
-  // Generate Markdown output (for human reading)
-  const mdArgs = [
-    ...baseArgs,
-    '--compress',
-    '--style', 'markdown',
-    '-o', mdOutput
-  ];
+  const args = [...baseArgs, '--compress', '--style', style, '-o', outputPath];
 
-  await execa(baseCmd, mdArgs, {
+  await execa(baseCmd, args, {
     cwd: targetDir,
     timeout: 300000
   });
+}
 
-  // Parse XML to get stats
-  let stats = {
-    totalFiles: 0,
-    totalTokens: 0,
-    compressedTokens: 0
-  };
+/**
+ * Parse repomix XML output for statistics
+ */
+async function parseRepomixStats(xmlPath) {
+  const stats = { totalFiles: 0, totalTokens: 0, compressedTokens: 0 };
 
   try {
-    const xmlContent = await fs.readFile(xmlOutput, 'utf-8');
-    // Count file entries in XML
+    const xmlContent = await fs.readFile(xmlPath, 'utf-8');
     const fileMatches = xmlContent.match(/<file path="/g);
     if (fileMatches) {
       stats.totalFiles = fileMatches.length;
@@ -256,25 +239,36 @@ async function writeMetadata(outputDir, stats) {
 
 /**
  * Main entry point for codebase scanning
- * @param {string} targetDir - Directory to scan
- * @param {object} options - Scan options
- * @returns {Promise<object>} - Scan results
  */
 async function scanCodebase(targetDir, options = {}) {
   const { silent = false } = options;
   const outputDir = path.join(targetDir, 'ai_context', 'codebase');
-  const startTime = Date.now();
 
-  // Check for source code
+  // Pre-flight checks
+  const preflight = await runPreflightChecks(targetDir, silent);
+  if (preflight.skipped) return preflight;
+
+  const spinner = silent ? null : ora('Scanning codebase...').start();
+
+  try {
+    const result = await executeScan(targetDir, outputDir, preflight.command, spinner);
+    if (spinner) spinner.succeed(`Codebase scanned (${result.stats.totalFiles} files, ${result.stats.duration}s)`);
+    return result;
+  } catch (error) {
+    return handleScanError(error, spinner, silent);
+  }
+}
+
+/**
+ * Run pre-flight checks before scanning
+ */
+async function runPreflightChecks(targetDir, silent) {
   const hasSource = await detectSourceCode(targetDir);
   if (!hasSource) {
-    if (!silent) {
-      console.log(chalk.gray('   No source code detected. Skipping scan.'));
-    }
+    if (!silent) console.log(chalk.gray('   No source code detected. Skipping scan.'));
     return { skipped: true, reason: 'no-source' };
   }
 
-  // Check repomix availability
   const { available, command } = await checkRepomix();
   if (!available) {
     if (!silent) {
@@ -284,54 +278,40 @@ async function scanCodebase(targetDir, options = {}) {
     return { skipped: true, reason: 'no-repomix' };
   }
 
-  const spinner = silent ? null : ora('Scanning codebase...').start();
-
-  try {
-    // Create output directory
-    await fs.ensureDir(outputDir);
-
-    // Create default ignore file
-    await createRepomixIgnore(outputDir);
-
-    // Run repomix scan
-    const useNpx = command.includes('npx');
-    const stats = await runRepomixScan(targetDir, outputDir, { useNpx });
-
-    // Generate structure
-    if (spinner) spinner.text = 'Generating structure...';
-    await generateStructure(targetDir, outputDir);
+  return { skipped: false, command };
+}
 
-    // Calculate duration
-    stats.duration = Math.round((Date.now() - startTime) / 1000 * 10) / 10;
+/**
+ * Execute the actual scan operation
+ */
+async function executeScan(targetDir, outputDir, command, spinner) {
+  const startTime = Date.now();
 
-    // Write metadata
-    const metadata = await writeMetadata(outputDir, stats);
+  await fs.ensureDir(outputDir);
+  await createRepomixIgnore(outputDir);
 
-    if (spinner) {
-      spinner.succeed(`Codebase scanned (${stats.totalFiles} files, ${stats.duration}s)`);
-    }
+  const useNpx = command.includes('npx');
+  const stats = await runRepomixScan(targetDir, outputDir, { useNpx });
 
-    return {
-      success: true,
-      outputDir,
-      stats: metadata
-    };
+  if (spinner) spinner.text = 'Generating structure...';
+  await generateStructure(targetDir, outputDir);
 
-  } catch (error) {
-    if (spinner) {
-      spinner.fail('Codebase scan failed');
-    }
+  stats.duration = Math.round((Date.now() - startTime) / 1000 * 10) / 10;
+  const metadata = await writeMetadata(outputDir, stats);
 
-    if (!silent) {
-      console.log(chalk.yellow(`   ⚠️  ${error.message}`));
-      console.log(chalk.gray('   Run /scan manually after fixing the issue.'));
-    }
+  return { success: true, outputDir, stats: metadata };
+}
 
-    return {
-      success: false,
-      error: error.message
-    };
+/**
+ * Handle scan errors
+ */
+function handleScanError(error, spinner, silent) {
+  if (spinner) spinner.fail('Codebase scan failed');
+  if (!silent) {
+    console.log(chalk.yellow(`   ⚠️  ${error.message}`));
+    console.log(chalk.gray('   Run /scan manually after fixing the issue.'));
   }
+  return { success: false, error: error.message };
 }
 
 module.exports = {

package/package.json

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

package/templates/.claude/agents/debugger.md

@@ -80,7 +80,8 @@ ai_context/
 │   ├── learning.md  # Bug patterns to watch for
 │   └── decisions.md # Fix decisions log
 └── reports/
-    └── debug-251224-login-bug.md
+    └── debug/
+        └── debug-251224-login-bug.md
 ```
 
 ## Workflow
@@ -111,7 +112,7 @@ ai_context/
 
 ### Phase 4: Document
 ```
-1. Call Write: ai_context/reports/ai-sprint-debug-{timestamp}-{slug}.md
+1. Call Write: ai_context/reports/debug/ai-sprint-debug-{timestamp}-{slug}.md
 2. Update ai_context/memory/learning.md with new pattern
 ```
 

package/templates/.claude/agents/devops.md

@@ -76,7 +76,8 @@ ai_context/
 │   ├── learning.md  # DevOps lessons learned
 │   └── decisions.md # Infrastructure decisions
 └── reports/
-    └── deploy-251224.md
+    └── deploy/
+        └── deploy-251224.md
 ```
 
 ## Workflow
@@ -108,7 +109,7 @@ ai_context/
 
 ### Phase 4: Documentation
 ```
-1. Call Write: ai_context/reports/ai-sprint-deploy-{timestamp}.md
+1. Call Write: ai_context/reports/deploy/ai-sprint-deploy-{timestamp}.md
 2. Document rollback procedures
 3. Update ai_context/memory/decisions.md
 ```

package/templates/.claude/agents/docs.md

@@ -77,7 +77,8 @@ ai_context/
 ├── memory/
 │   └── learning.md # Documentation lessons
 └── reports/
-    └── docs-audit-251224.md
+    └── docs/
+        └── docs-audit-251224.md
 ```
 
 ## Workflow
@@ -107,7 +108,7 @@ ai_context/
 
 ### Phase 4: Report
 ```
-1. Call Write: ai_context/reports/ai-sprint-docs-audit-{timestamp}.md
+1. Call Write: ai_context/reports/docs/ai-sprint-docs-audit-{timestamp}.md
 2. Document what was updated
 ```
 

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/researcher.md

@@ -82,7 +82,8 @@ ai_context/
 ├── memory/
 │   └── learning.md # Research lessons learned
 └── reports/
-    └── research-{topic}-251224.md
+    └── research/
+        └── research-{topic}-251224.md
 ```
 
 ## Workflow
@@ -110,7 +111,7 @@ ai_context/
 
 ### Phase 4: Report
 ```
-1. Call Write: ai_context/reports/research-{topic}-{timestamp}.md
+1. Call Write: ai_context/reports/research/research-{topic}-{timestamp}.md
 2. Include all citations with links
 3. Provide actionable recommendations
 ```

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
@@ -74,7 +107,8 @@ ai_context/
 │   ├── learning.md  # Review lessons learned
 │   └── decisions.md # Code decisions log
 └── reports/
-    └── review-251224.md
+    └── review/
+        └── review-251224.md
 ```
 
 ## Workflow
@@ -98,7 +132,7 @@ ai_context/
 
 ### Phase 3: Reporting
 ```
-1. Call Write: ai_context/reports/ai-sprint-review-{timestamp}.md
+1. Call Write: ai_context/reports/review/ai-sprint-review-{timestamp}.md
 2. Categorize by severity (Critical/High/Medium/Low)
 3. Provide before/after code examples
 4. Include rationale for each suggestion

package/templates/.claude/agents/security.md

@@ -77,7 +77,8 @@ ai_context/
 │   ├── learning.md   # Past security issues to watch for
 │   └── decisions.md  # Security decisions log
 └── reports/
-    └── security-251224-2115.md  # Security scan results
+    └── security/
+        └── security-251224-2115.md  # Security scan results
 ```
 
 ## Workflow
@@ -100,7 +101,7 @@ ai_context/
 
 ### Phase 3: Reporting
 ```
-1. Call Write: ai_context/reports/security-{timestamp}.md
+1. Call Write: ai_context/reports/security/security-{timestamp}.md
 2. Include severity ratings and fixes
 3. Update ai_context/memory/learning.md if new patterns found
 ```

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
 
@@ -77,7 +119,8 @@ ai_context/
 ├── memory/
 │   └── learning.md # Testing lessons learned
 └── reports/
-    └── test-coverage-251224.md
+    └── test/
+        └── test-coverage-251224.md
 ```
 
 ## Workflow
@@ -108,7 +151,7 @@ ai_context/
 
 ### Phase 4: Reporting
 ```
-1. Call Write: ai_context/reports/ai-sprint-test-coverage-{timestamp}.md
+1. Call Write: ai_context/reports/test/ai-sprint-test-coverage-{timestamp}.md
 2. Document coverage metrics
 3. Note gaps and recommendations
 ```

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

@@ -252,11 +252,11 @@ Before debugging:
 
 After debugging:
 - Update `ai_context/memory/learning.md` with new bug pattern
-- Save report to `ai_context/reports/ai-sprint-debug-{timestamp}-{slug}.md`
+- Save report to `ai_context/reports/debug/ai-sprint-debug-{timestamp}-{slug}.md`
 
 ## Debug Report
 
-Save to: `ai_context/reports/ai-sprint-debug-YYMMDD-slug.md`
+Save to: `ai_context/reports/debug/ai-sprint-debug-YYMMDD-slug.md`
 
 ```markdown
 # Bug Fix Report

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
 

package/templates/CLAUDE.md

@@ -118,11 +118,14 @@ project/
 ├── ai_context/              # AI artifacts (not project code)
 │   ├── plans/               # Implementation plans
 │   ├── docs/                # AI-generated documentation
-│   ├── reports/             # Agent outputs
-│   │   ├── review-*.md      # Code review reports
-│   │   ├── test-*.md        # Test coverage reports
-│   │   ├── security-*.md    # Security scan results
-│   │   └── debug-*.md       # Debugging analysis
+│   ├── reports/             # Agent outputs (organized by type)
+│   │   ├── research/        # Research reports
+│   │   ├── review/          # Code review reports
+│   │   ├── security/        # Security scan results
+│   │   ├── test/            # Test coverage reports
+│   │   ├── debug/           # Debugging analysis
+│   │   ├── deploy/          # Deployment reports
+│   │   └── docs/            # Documentation audit reports
 │   └── memory/
 │   │   ├── learning.md      # Lessons learned
 │   │   ├── decisions.md     # Key decisions

package/templates/docs/user-guide-th.md

@@ -337,11 +337,11 @@ git commit -m "เพิ่มฟีเจอร์ใหม่"
 
 ### 3. อ่านรายงานที่ AI สร้าง
 
-AI จะบันทึกผลการทำงานไว้ใน `ai_context/reports/`
+AI จะบันทึกผลการทำงานไว้ใน `ai_context/reports/` (แยกโฟลเดอร์ตามประเภท)
 
 ```bash
 # ดูรายงานความปลอดภัย
-cat ai_context/reports/security-*.md
+cat ai_context/reports/security/
 ```
 
 ### 4. ใช้ /ai-sprint-auto สำหรับงานง่ายๆ
@@ -391,7 +391,7 @@ cat ai_context/reports/security-*.md
 
 ```bash
 # ดูรายงาน
-cat ai_context/reports/security-*.md
+cat ai_context/reports/security/
 
 # แก้ไข
 /ai-sprint-code "แก้ไขปัญหาความปลอดภัยตามรายงาน"

package/templates/docs/user-guide.md

@@ -105,7 +105,7 @@ For more control over each phase:
 ```bash
 # Step 1: Investigate the issue
 /ai-sprint-debug "users getting 500 error when submitting registration form"
-# Review the analysis in ai_context/reports/
+# Review the analysis in ai_context/reports/debug/
 
 # Step 2: Implement the fix
 /ai-sprint-code "fix the registration error based on debug analysis"
@@ -124,7 +124,7 @@ For more control over each phase:
 # Scan specific directory
 /ai-sprint-secure src/auth/
 
-# Review findings in ai_context/reports/security-*.md
+# Review findings in ai_context/reports/security/
 ```
 
 ### Tutorial 5: Pre-Commit Validation
@@ -211,7 +211,7 @@ Generates tests and runs them with coverage.
 /ai-sprint-test "add integration tests for payment API"
 ```
 
-**Output:** `ai_context/reports/test-*.md`
+**Output:** `ai_context/reports/test/`
 
 **Requirements:** 80%+ coverage required.
 
@@ -230,7 +230,7 @@ Analyzes code quality and best practices.
 /ai-sprint-review src/auth/login.ts
 ```
 
-**Output:** `ai_context/reports/review-*.md`
+**Output:** `ai_context/reports/review/`
 
 **Checks:**
 - Code quality and patterns
@@ -254,7 +254,7 @@ Comprehensive security analysis.
 /ai-sprint-secure src/auth/
 ```
 
-**Output:** `ai_context/reports/security-*.md`
+**Output:** `ai_context/reports/security/`
 
 **Scans:**
 - SAST (static analysis)
@@ -310,7 +310,7 @@ Investigates issues and bugs.
 /ai-sprint-debug "slow API response times on /users endpoint"
 ```
 
-**Output:** `ai_context/reports/debug-*.md`
+**Output:** `ai_context/reports/debug/`
 
 **Provides:**
 - Root cause analysis
@@ -475,8 +475,8 @@ After every `/ai-sprint-secure` scan:
 
 ```bash
 # Check reports
-ls ai_context/reports/security-*.md
-cat ai_context/reports/security-latest.md
+ls ai_context/reports/security/
+cat ai_context/reports/security/security-*.md
 ```
 
 ### 5. Configure MCP Tools
@@ -532,7 +532,7 @@ For complex features, maintain control:
 
 ```bash
 # View the report
-cat ai_context/reports/security-*.md
+cat ai_context/reports/security/
 
 # Fix issues
 /ai-sprint-code "fix security issues from the security scan"