musubi-sdd 0.8.1 → 0.8.2

package/README.ja.md

@@ -14,6 +14,7 @@ MUSUBIは、6つの主要フレームワークのベスト機能を統合した
   - その他4エージェント: AGENTS.md（互換形式）
 - 📋 **憲法ガバナンス** - 9つの不変条項 + フェーズ-1ゲートによる品質保証
 - 📝 **EARS要件ジェネレーター** - 5つのEARSパターンで明確な要件を作成（v0.8.0）
+- 🏗️ **設計ドキュメントジェネレーター** - トレーサビリティ付きC4モデルとADRを作成（v0.8.2）
 - 🔄 **差分仕様** - ブラウンフィールドおよびグリーンフィールドプロジェクト対応
 - 🧭 **自動更新プロジェクトメモリ** - ステアリングシステムがアーキテクチャ、技術スタック、製品コンテキストを維持
 - 🚀 **自動オンボーディング** - `musubi-onboard` が既存プロジェクトを分析し、ステアリングドキュメントを生成（2-5分）
@@ -105,12 +106,20 @@ musubi-validate gates               # フェーズ-1ゲートを検証
 musubi-validate complexity          # 複雑度制限をチェック
 musubi-validate all -v              # 詳細付き完全検証
 
-# EARS要件の作成（v0.8.0）
+# EARS要件ドキュメント生成（v0.8.0）
 musubi-requirements init "ユーザー認証"  # 要件ドキュメント初期化
 musubi-requirements add                 # インタラクティブに要件追加
 musubi-requirements list                # 全要件リスト表示
-musubi-requirements validate            # EARS形式検証
+musubi-requirements validate            # EARS形式を検証
 musubi-requirements trace               # トレーサビリティマトリクス表示
+
+# 設計ドキュメント生成（v0.8.2）
+musubi-design init "ユーザー認証"       # 設計ドキュメント初期化
+musubi-design add-c4 context            # C4コンテキスト図を追加
+musubi-design add-c4 container --format plantuml  # PlantUMLでコンテナ図追加
+musubi-design add-adr "JWTトークン使用" # アーキテクチャ決定記録追加
+musubi-design validate                  # 設計完全性を検証
+musubi-design trace                     # 要件トレーサビリティ表示
 ```
 
 ### プロジェクトタイプ

package/README.md

@@ -18,6 +18,7 @@ MUSUBI is a comprehensive SDD (Specification Driven Development) framework that
   - Other 4 agents: AGENTS.md (compatible format)
 - 📋 **Constitutional Governance** - 9 immutable articles + Phase -1 Gates for quality enforcement
 - 📝 **EARS Requirements Generator** - Create unambiguous requirements with 5 EARS patterns (v0.8.0)
+- 🏗️ **Design Document Generator** - Create C4 models and ADRs with traceability (v0.8.2)
 - 🔄 **Delta Specifications** - Brownfield and greenfield project support
 - 🧭 **Auto-Updating Project Memory** - Steering system maintains architecture, tech stack, and product context
 - 🚀 **Automatic Onboarding** - `musubi-onboard` analyzes existing projects and generates steering docs (2-5 minutes)
@@ -109,12 +110,20 @@ musubi-validate gates               # Validate Phase -1 Gates
 musubi-validate complexity          # Check complexity limits
 musubi-validate all -v              # Full validation with details
 
-# Create EARS requirements (v0.8.0)
+# Generate EARS requirements documents (v0.8.0)
 musubi-requirements init "User Authentication"  # Initialize requirements doc
 musubi-requirements add                         # Add requirement interactively
 musubi-requirements list                        # List all requirements
 musubi-requirements validate                    # Validate EARS format
 musubi-requirements trace                       # Show traceability matrix
+
+# Generate design documents (v0.8.2)
+musubi-design init "User Authentication"        # Initialize design document
+musubi-design add-c4 context                    # Add C4 Context diagram
+musubi-design add-c4 container --format plantuml # Add Container with PlantUML
+musubi-design add-adr "Use JWT for tokens"      # Add Architecture Decision
+musubi-design validate                          # Validate design completeness
+musubi-design trace                             # Show requirements traceability
 ```
 
 ### Project Types

package/bin/musubi-design.js

@@ -0,0 +1,320 @@
+#!/usr/bin/env node
+
+/**
+ * MUSUBI Design Document Generator CLI
+ * 
+ * Generates technical design documents with C4 model and ADR
+ * Complies with Article V (Traceability) and steering context
+ * 
+ * Usage:
+ *   musubi-design init <feature>           # Initialize design document
+ *   musubi-design add-c4 <level>           # Add C4 diagram (context|container|component|code)
+ *   musubi-design add-adr <decision>       # Add Architecture Decision Record
+ *   musubi-design validate                 # Validate design completeness
+ *   musubi-design trace                    # Show requirement traceability
+ */
+
+const { Command } = require('commander');
+const chalk = require('chalk');
+const inquirer = require('inquirer');
+const DesignGenerator = require('../src/generators/design');
+
+const program = new Command();
+
+program
+  .name('musubi-design')
+  .description('Design Document Generator - Create C4 models and ADRs')
+  .version('0.8.2');
+
+// Initialize design document
+program
+  .command('init <feature>')
+  .description('Initialize design document for a feature')
+  .option('-o, --output <path>', 'Output directory', 'docs/design')
+  .option('-a, --author <name>', 'Author name')
+  .option('--project <name>', 'Project name')
+  .option('-r, --requirements <path>', 'Requirements file path')
+  .action(async (feature, options) => {
+    try {
+      console.log(chalk.bold(`\n🏗️  Initializing design for: ${feature}\n`));
+      
+      const generator = new DesignGenerator(process.cwd());
+      const result = await generator.init(feature, options);
+      
+      console.log(chalk.green('✓ Design document created'));
+      console.log(chalk.dim(`  ${result.path}`));
+      console.log();
+      console.log(chalk.bold('Next steps:'));
+      console.log(chalk.dim(`  1. Edit ${result.path}`));
+      console.log(chalk.dim('  2. Add C4 diagrams: musubi-design add-c4 <level>'));
+      console.log(chalk.dim('  3. Add ADRs: musubi-design add-adr <decision>'));
+      console.log(chalk.dim('  4. Validate: musubi-design validate'));
+      console.log();
+      
+      process.exit(0);
+    } catch (error) {
+      console.error(chalk.red('✗ Error:'), error.message);
+      process.exit(1);
+    }
+  });
+
+// Add C4 diagram
+program
+  .command('add-c4 <level>')
+  .description('Add C4 model diagram (context|container|component|code)')
+  .option('-f, --file <path>', 'Design file path')
+  .option('--format <type>', 'Diagram format (mermaid|plantuml)', 'mermaid')
+  .action(async (level, options) => {
+    try {
+      console.log(chalk.bold(`\n📊 Adding C4 ${level} diagram\n`));
+      
+      const generator = new DesignGenerator(process.cwd());
+      
+      // Find design file
+      let designFile = options.file;
+      if (!designFile) {
+        const files = await generator.findDesignFiles();
+        if (files.length === 0) {
+          console.error(chalk.red('✗ No design files found'));
+          console.log(chalk.dim('  Run: musubi-design init <feature>'));
+          process.exit(1);
+        }
+        
+        if (files.length === 1) {
+          designFile = files[0];
+        } else {
+          const answer = await inquirer.prompt([{
+            type: 'list',
+            name: 'file',
+            message: 'Select design file:',
+            choices: files
+          }]);
+          designFile = answer.file;
+        }
+      }
+      
+      // Interactive prompts for C4 diagram
+      const answers = await inquirer.prompt([
+        {
+          type: 'input',
+          name: 'title',
+          message: 'Diagram title:',
+          default: `${level.charAt(0).toUpperCase() + level.slice(1)} Diagram`,
+          validate: (input) => input.length > 0 || 'Title is required'
+        },
+        {
+          type: 'input',
+          name: 'description',
+          message: 'Diagram description:',
+          default: `Shows ${level}-level architecture`
+        }
+      ]);
+      
+      const diagram = {
+        level,
+        title: answers.title,
+        description: answers.description,
+        format: options.format
+      };
+      
+      const result = await generator.addC4Diagram(designFile, diagram);
+      
+      console.log(chalk.green('\n✓ C4 diagram added:'));
+      console.log(chalk.dim(`  ${result.level}: ${result.title}`));
+      console.log(chalk.bold('\n📝 Diagram Template:'));
+      console.log(chalk.cyan(result.template));
+      console.log();
+      
+      process.exit(0);
+    } catch (error) {
+      console.error(chalk.red('✗ Error:'), error.message);
+      process.exit(1);
+    }
+  });
+
+// Add Architecture Decision Record
+program
+  .command('add-adr <decision>')
+  .description('Add Architecture Decision Record')
+  .option('-f, --file <path>', 'Design file path')
+  .option('--status <status>', 'ADR status (proposed|accepted|rejected|deprecated)', 'proposed')
+  .action(async (decision, options) => {
+    try {
+      console.log(chalk.bold(`\n📜 Adding ADR: ${decision}\n`));
+      
+      const generator = new DesignGenerator(process.cwd());
+      
+      // Find design file
+      let designFile = options.file;
+      if (!designFile) {
+        const files = await generator.findDesignFiles();
+        if (files.length === 0) {
+          console.error(chalk.red('✗ No design files found'));
+          console.log(chalk.dim('  Run: musubi-design init <feature>'));
+          process.exit(1);
+        }
+        
+        if (files.length === 1) {
+          designFile = files[0];
+        } else {
+          const answer = await inquirer.prompt([{
+            type: 'list',
+            name: 'file',
+            message: 'Select design file:',
+            choices: files
+          }]);
+          designFile = answer.file;
+        }
+      }
+      
+      // Interactive prompts for ADR
+      const answers = await inquirer.prompt([
+        {
+          type: 'input',
+          name: 'context',
+          message: 'What is the context/problem?',
+          validate: (input) => input.length > 0 || 'Context is required'
+        },
+        {
+          type: 'input',
+          name: 'decision',
+          message: 'What is the decision?',
+          validate: (input) => input.length > 0 || 'Decision is required'
+        },
+        {
+          type: 'input',
+          name: 'consequences',
+          message: 'What are the consequences?',
+          validate: (input) => input.length > 0 || 'Consequences are required'
+        },
+        {
+          type: 'input',
+          name: 'alternatives',
+          message: 'Alternatives considered (comma-separated):',
+          filter: (input) => input.split(',').map(s => s.trim()).filter(s => s.length > 0)
+        }
+      ]);
+      
+      const adr = {
+        title: decision,
+        status: options.status,
+        context: answers.context,
+        decision: answers.decision,
+        consequences: answers.consequences,
+        alternatives: answers.alternatives
+      };
+      
+      const result = await generator.addADR(designFile, adr);
+      
+      console.log(chalk.green('\n✓ ADR added:'));
+      console.log(chalk.dim(`  ADR-${result.number}: ${result.title}`));
+      console.log(chalk.dim(`  Status: ${result.status}`));
+      console.log();
+      
+      process.exit(0);
+    } catch (error) {
+      console.error(chalk.red('✗ Error:'), error.message);
+      process.exit(1);
+    }
+  });
+
+// Validate design document
+program
+  .command('validate')
+  .description('Validate design document completeness')
+  .option('-f, --file <path>', 'Specific design file')
+  .option('-v, --verbose', 'Show detailed validation results')
+  .action(async (options) => {
+    try {
+      console.log(chalk.bold('\n🔍 Validating Design Documents\n'));
+      
+      const generator = new DesignGenerator(process.cwd());
+      const results = await generator.validate(options.file);
+      
+      if (results.passed) {
+        console.log(chalk.green('✓ All designs valid\n'));
+      } else {
+        console.log(chalk.red('✗ Validation failed\n'));
+      }
+      
+      console.log(chalk.bold('Summary:'));
+      console.log(chalk.dim(`  Total: ${results.total}`));
+      console.log(chalk.green(`  Valid: ${results.valid}`));
+      console.log(chalk.red(`  Invalid: ${results.invalid}`));
+      console.log();
+      
+      if (results.violations.length > 0) {
+        console.log(chalk.bold.red('Violations:'));
+        results.violations.forEach(v => {
+          console.log(chalk.red(`  • ${v}`));
+        });
+        console.log();
+      }
+      
+      if (options.verbose && results.details) {
+        console.log(chalk.bold('Details:'));
+        results.details.forEach(d => {
+          const icon = d.valid ? chalk.green('✓') : chalk.red('✗');
+          console.log(`  ${icon} ${d.file}: ${d.message}`);
+        });
+        console.log();
+      }
+      
+      process.exit(results.passed ? 0 : 1);
+    } catch (error) {
+      console.error(chalk.red('✗ Error:'), error.message);
+      process.exit(1);
+    }
+  });
+
+// Show requirement traceability
+program
+  .command('trace')
+  .description('Show requirement-to-design traceability')
+  .option('-f, --file <path>', 'Specific design file')
+  .option('--format <type>', 'Output format (table|json|markdown)', 'table')
+  .action(async (options) => {
+    try {
+      console.log(chalk.bold('\n🔗 Design Traceability Matrix\n'));
+      
+      const generator = new DesignGenerator(process.cwd());
+      const matrix = await generator.generateTraceabilityMatrix(options.file);
+      
+      if (options.format === 'json') {
+        console.log(JSON.stringify(matrix, null, 2));
+      } else {
+        console.log(chalk.bold('| Requirement | Design | Components | Status |'));
+        console.log('|-------------|--------|------------|--------|');
+        
+        matrix.forEach(row => {
+          const design = row.design ? '✓' : '-';
+          const components = row.components || 0;
+          const status = row.traced ? chalk.green('Traced') : chalk.yellow('Missing');
+          
+          console.log(`| ${row.requirement} | ${design} | ${components} | ${status} |`);
+        });
+        console.log();
+        
+        const traced = matrix.filter(r => r.traced).length;
+        const total = matrix.length;
+        const percentage = total > 0 ? Math.round((traced / total) * 100) : 0;
+        
+        console.log(chalk.bold('Coverage:'));
+        console.log(chalk.dim(`  ${traced}/${total} requirements traced (${percentage}%)`));
+        console.log();
+      }
+      
+      process.exit(0);
+    } catch (error) {
+      console.error(chalk.red('✗ Error:'), error.message);
+      process.exit(1);
+    }
+  });
+
+// Parse arguments
+program.parse(process.argv);
+
+// Show help if no command provided
+if (!process.argv.slice(2).length) {
+  program.outputHelp();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "musubi-sdd",
-  "version": "0.8.1",
+  "version": "0.8.2",
   "description": "Ultimate Specification Driven Development Tool with 25 Agents for 7 AI Coding Platforms (Claude Code, GitHub Copilot, Cursor, Gemini CLI, Windsurf, Codex, Qwen Code)",
   "main": "src/index.js",
   "bin": {
@@ -12,7 +12,8 @@
     "musubi-analyze": "bin/musubi-analyze.js",
     "musubi-share": "bin/musubi-share.js",
     "musubi-validate": "bin/musubi-validate.js",
-    "musubi-requirements": "bin/musubi-requirements.js"
+    "musubi-requirements": "bin/musubi-requirements.js",
+    "musubi-design": "bin/musubi-design.js"
   },
   "scripts": {
     "test": "jest",

package/src/generators/design.js

@@ -0,0 +1,662 @@
+/**
+ * MUSUBI Design Document Generator
+ * 
+ * Generates technical design documents with C4 model and ADR
+ * Complies with Article V (Traceability) and steering context
+ * 
+ * C4 Model Levels:
+ * 1. Context: System in its environment
+ * 2. Container: High-level technology choices
+ * 3. Component: Components within containers
+ * 4. Code: Class/component implementation details
+ * 
+ * ADR Format:
+ * - Title: Decision name
+ * - Status: proposed|accepted|rejected|deprecated
+ * - Context: Problem/situation
+ * - Decision: What we decided
+ * - Consequences: Positive and negative outcomes
+ * - Alternatives: Other options considered
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+const { glob } = require('glob');
+
+class DesignGenerator {
+  constructor(rootDir) {
+    this.rootDir = rootDir;
+    this.templatePath = path.join(__dirname, '../../src/templates/shared/documents/design.md');
+  }
+
+  /**
+   * Initialize design document for a feature
+   * @param {string} feature - Feature name
+   * @param {object} options - Options (output, author, project, requirements)
+   * @returns {Promise<object>} Result with path
+   */
+  async init(feature, options = {}) {
+    const outputDir = path.join(this.rootDir, options.output || 'docs/design');
+    await fs.ensureDir(outputDir);
+
+    const fileName = `${this.slugify(feature)}.md`;
+    const filePath = path.join(outputDir, fileName);
+
+    // Check if file exists
+    if (await fs.pathExists(filePath)) {
+      throw new Error(`Design file already exists: ${filePath}`);
+    }
+
+    // Load template
+    const template = await fs.readFile(this.templatePath, 'utf-8');
+
+    // Get project name from package.json
+    let projectName = options.project;
+    if (!projectName) {
+      try {
+        const pkg = await fs.readJSON(path.join(this.rootDir, 'package.json'));
+        projectName = pkg.name || 'Project';
+      } catch {
+        projectName = 'Project';
+      }
+    }
+
+    // Get author from git config or options
+    let author = options.author;
+    if (!author) {
+      try {
+        const { execSync } = require('child_process');
+        author = execSync('git config user.name', { encoding: 'utf-8' }).trim();
+      } catch {
+        author = 'Author';
+      }
+    }
+
+    // Replace template variables
+    const content = template
+      .replace(/\{\{FEATURE_NAME\}\}/g, feature)
+      .replace(/\{\{PROJECT_NAME\}\}/g, projectName)
+      .replace(/\{\{DATE\}\}/g, new Date().toISOString().split('T')[0])
+      .replace(/\{\{AUTHOR\}\}/g, author)
+      .replace(/\{\{SYSTEM\}\}/g, projectName);
+
+    await fs.writeFile(filePath, content, 'utf-8');
+
+    return { path: filePath };
+  }
+
+  /**
+   * Find all design files in the project
+   * @returns {Promise<string[]>} List of design file paths
+   */
+  async findDesignFiles() {
+    const patterns = [
+      'docs/design/**/*.md',
+      'docs/design/*.md',
+      'design/**/*.md',
+      'design/*.md'
+    ];
+
+    const files = [];
+    for (const pattern of patterns) {
+      const matches = await glob(pattern, { cwd: this.rootDir, absolute: true });
+      files.push(...matches);
+    }
+
+    return [...new Set(files)];
+  }
+
+  /**
+   * Add C4 diagram to design file
+   * @param {string} filePath - Design file path
+   * @param {object} diagram - Diagram data
+   * @returns {Promise<object>} Result with level and template
+   */
+  async addC4Diagram(filePath, diagram) {
+    const content = await fs.readFile(filePath, 'utf-8');
+
+    // Generate C4 diagram template
+    const template = this.generateC4Template(diagram);
+
+    // Find insertion point based on level
+    const insertionPoint = this.findC4InsertionPoint(content, diagram.level);
+    
+    const newContent = content.slice(0, insertionPoint) + template + '\n' + content.slice(insertionPoint);
+
+    await fs.writeFile(filePath, newContent, 'utf-8');
+
+    return { 
+      level: diagram.level, 
+      title: diagram.title,
+      template 
+    };
+  }
+
+  /**
+   * Generate C4 diagram template
+   * @param {object} diagram - Diagram data
+   * @returns {string} Mermaid or PlantUML template
+   */
+  generateC4Template(diagram) {
+    const { level, title, description, format } = diagram;
+
+    if (format === 'plantuml') {
+      return this.generatePlantUMLTemplate(level, title, description);
+    }
+
+    // Default: Mermaid
+    return this.generateMermaidTemplate(level, title, description);
+  }
+
+  /**
+   * Generate Mermaid C4 template
+   * @param {string} level - C4 level
+   * @param {string} title - Diagram title
+   * @param {string} description - Diagram description
+   * @returns {string} Mermaid template
+   */
+  generateMermaidTemplate(level, title, description) {
+    const templates = {
+      context: `### C4 Context: ${title}
+
+**${description}**
+
+\`\`\`mermaid
+C4Context
+  title ${title}
+
+  Person(user, "User", "End user of the system")
+  System(system, "System Name", "System description")
+  System_Ext(external, "External System", "External service")
+
+  Rel(user, system, "Uses", "HTTPS")
+  Rel(system, external, "Calls", "API")
+\`\`\`
+
+**Key Elements**:
+- **Users**: [List users/personas]
+- **System**: [System boundary]
+- **External Systems**: [External dependencies]
+`,
+      container: `### C4 Container: ${title}
+
+**${description}**
+
+\`\`\`mermaid
+C4Container
+  title ${title}
+
+  Person(user, "User")
+  
+  Container_Boundary(c1, "System Name") {
+    Container(web, "Web Application", "React", "User interface")
+    Container(api, "API", "Node.js", "Business logic")
+    ContainerDb(db, "Database", "PostgreSQL", "Data storage")
+  }
+
+  Rel(user, web, "Uses", "HTTPS")
+  Rel(web, api, "Calls", "REST/JSON")
+  Rel(api, db, "Reads/Writes", "SQL")
+\`\`\`
+
+**Containers**:
+- **Frontend**: [Technology and purpose]
+- **Backend**: [Technology and purpose]
+- **Database**: [Technology and purpose]
+`,
+      component: `### C4 Component: ${title}
+
+**${description}**
+
+\`\`\`mermaid
+C4Component
+  title ${title}
+
+  Container_Boundary(api, "API Container") {
+    Component(controller, "Controller", "Express", "Handles requests")
+    Component(service, "Service", "TypeScript", "Business logic")
+    Component(repository, "Repository", "TypeORM", "Data access")
+  }
+  
+  ContainerDb(db, "Database")
+
+  Rel(controller, service, "Uses")
+  Rel(service, repository, "Uses")
+  Rel(repository, db, "Queries")
+\`\`\`
+
+**Components**:
+- **Controller**: [Responsibility]
+- **Service**: [Responsibility]
+- **Repository**: [Responsibility]
+`,
+      code: `### C4 Code: ${title}
+
+**${description}**
+
+\`\`\`mermaid
+classDiagram
+  class Controller {
+    +handleRequest()
+    +validateInput()
+  }
+  
+  class Service {
+    +executeBusinessLogic()
+    +processData()
+  }
+  
+  class Repository {
+    +findById()
+    +save()
+    +delete()
+  }
+
+  Controller --> Service
+  Service --> Repository
+\`\`\`
+
+**Classes**:
+- **Controller**: [Purpose and key methods]
+- **Service**: [Purpose and key methods]
+- **Repository**: [Purpose and key methods]
+`
+    };
+
+    return templates[level] || templates.context;
+  }
+
+  /**
+   * Generate PlantUML C4 template
+   * @param {string} level - C4 level
+   * @param {string} title - Diagram title
+   * @param {string} description - Diagram description
+   * @returns {string} PlantUML template
+   */
+  generatePlantUMLTemplate(level, title, description) {
+    const templates = {
+      context: `### C4 Context: ${title}
+
+**${description}**
+
+\`\`\`plantuml
+@startuml
+!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml
+
+LAYOUT_WITH_LEGEND()
+
+title ${title}
+
+Person(user, "User", "End user")
+System(system, "System Name", "System description")
+System_Ext(external, "External System", "External service")
+
+Rel(user, system, "Uses", "HTTPS")
+Rel(system, external, "Calls", "API")
+
+@enduml
+\`\`\`
+`,
+      container: `### C4 Container: ${title}
+
+**${description}**
+
+\`\`\`plantuml
+@startuml
+!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
+
+LAYOUT_WITH_LEGEND()
+
+title ${title}
+
+Person(user, "User")
+
+System_Boundary(c1, "System Name") {
+  Container(web, "Web App", "React", "User interface")
+  Container(api, "API", "Node.js", "Business logic")
+  ContainerDb(db, "Database", "PostgreSQL", "Data storage")
+}
+
+Rel(user, web, "Uses", "HTTPS")
+Rel(web, api, "Calls", "REST/JSON")
+Rel(api, db, "Reads/Writes", "SQL")
+
+@enduml
+\`\`\`
+`,
+      component: `### C4 Component: ${title}
+
+**${description}**
+
+\`\`\`plantuml
+@startuml
+!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Component.puml
+
+LAYOUT_WITH_LEGEND()
+
+title ${title}
+
+Container_Boundary(api, "API Container") {
+  Component(controller, "Controller", "Express", "Handles requests")
+  Component(service, "Service", "TypeScript", "Business logic")
+  Component(repository, "Repository", "TypeORM", "Data access")
+}
+
+ContainerDb(db, "Database")
+
+Rel(controller, service, "Uses")
+Rel(service, repository, "Uses")
+Rel(repository, db, "Queries")
+
+@enduml
+\`\`\`
+`,
+      code: `### C4 Code: ${title}
+
+**${description}**
+
+\`\`\`plantuml
+@startuml
+title ${title}
+
+class Controller {
+  +handleRequest()
+  +validateInput()
+}
+
+class Service {
+  +executeBusinessLogic()
+  +processData()
+}
+
+class Repository {
+  +findById()
+  +save()
+  +delete()
+}
+
+Controller --> Service
+Service --> Repository
+
+@enduml
+\`\`\`
+`
+    };
+
+    return templates[level] || templates.context;
+  }
+
+  /**
+   * Get C4 section name
+   * @param {string} level - C4 level
+   * @returns {string} Section name
+   */
+  getC4SectionName(level) {
+    const names = {
+      context: 'C4 Model: Context Diagram',
+      container: 'C4 Model: Container Diagram',
+      component: 'C4 Model: Component Diagram',
+      code: 'C4 Model: Code Diagram'
+    };
+    return names[level] || 'Architecture Design';
+  }
+
+  /**
+   * Find C4 insertion point in document
+   * @param {string} content - Document content
+   * @param {string} _level - C4 level
+   * @returns {number} Insertion index
+   */
+  findC4InsertionPoint(content, _level) {
+    // Find Architecture Design section
+    const archMatch = content.match(/## Architecture Design/);
+    if (!archMatch) {
+      throw new Error('Architecture Design section not found');
+    }
+
+    // Find next section after Architecture Design
+    const afterArch = content.slice(archMatch.index + archMatch[0].length);
+    const nextSectionMatch = afterArch.match(/\n## [^#]/);
+
+    if (nextSectionMatch) {
+      return archMatch.index + archMatch[0].length + nextSectionMatch.index;
+    }
+
+    // If no next section, append at end
+    return content.length;
+  }
+
+  /**
+   * Add Architecture Decision Record
+   * @param {string} filePath - Design file path
+   * @param {object} adr - ADR data
+   * @returns {Promise<object>} Result with ADR number
+   */
+  async addADR(filePath, adr) {
+    const content = await fs.readFile(filePath, 'utf-8');
+
+    // Generate ADR number
+    const number = this.generateADRNumber(content);
+
+    // Format ADR section
+    const section = this.formatADRSection(number, adr);
+
+    // Find insertion point (Architecture Decisions section)
+    const insertionPoint = this.findADRInsertionPoint(content);
+    const newContent = content.slice(0, insertionPoint) + section + '\n' + content.slice(insertionPoint);
+
+    await fs.writeFile(filePath, newContent, 'utf-8');
+
+    return { 
+      number, 
+      title: adr.title,
+      status: adr.status
+    };
+  }
+
+  /**
+   * Generate ADR number
+   * @param {string} content - Document content
+   * @returns {string} ADR number (ADR-001, ADR-002, etc.)
+   */
+  generateADRNumber(content) {
+    const regex = /### ADR-(\d+):/g;
+    
+    let maxNum = 0;
+    let match;
+    while ((match = regex.exec(content)) !== null) {
+      const num = parseInt(match[1], 10);
+      if (num > maxNum) maxNum = num;
+    }
+
+    const nextNum = (maxNum + 1).toString().padStart(3, '0');
+    return `ADR-${nextNum}`;
+  }
+
+  /**
+   * Format ADR section
+   * @param {string} number - ADR number
+   * @param {object} adr - ADR data
+   * @returns {string} Formatted ADR section
+   */
+  formatADRSection(number, adr) {
+    const date = new Date().toISOString().split('T')[0];
+    
+    let section = `### ${number}: ${adr.title}\n\n`;
+    section += `**Status**: ${adr.status}\n`;
+    section += `**Date**: ${date}\n\n`;
+    section += `**Context**:\n\n${adr.context}\n\n`;
+    section += `**Decision**:\n\n${adr.decision}\n\n`;
+    section += `**Consequences**:\n\n${adr.consequences}\n\n`;
+    
+    if (adr.alternatives && adr.alternatives.length > 0) {
+      section += '**Alternatives Considered**:\n\n';
+      adr.alternatives.forEach(alt => {
+        section += `- ${alt}\n`;
+      });
+      section += '\n';
+    }
+
+    return section;
+  }
+
+  /**
+   * Find ADR insertion point in document
+   * @param {string} content - Document content
+   * @returns {number} Insertion index
+   */
+  findADRInsertionPoint(content) {
+    // Find Architecture Decisions section
+    const adrMatch = content.match(/## Architecture Decisions/);
+    if (!adrMatch) {
+      // If section doesn't exist, add it before next major section
+      const nextMatch = content.match(/\n## [^#]/);
+      if (nextMatch) {
+        return nextMatch.index;
+      }
+      return content.length;
+    }
+
+    // Find next section after Architecture Decisions
+    const afterADR = content.slice(adrMatch.index + adrMatch[0].length);
+    const nextSectionMatch = afterADR.match(/\n## [^#]/);
+
+    if (nextSectionMatch) {
+      return adrMatch.index + adrMatch[0].length + nextSectionMatch.index;
+    }
+
+    return content.length;
+  }
+
+  /**
+   * Validate design documents
+   * @param {string} [filePath] - Specific file path
+   * @returns {Promise<object>} Validation results
+   */
+  async validate(filePath = null) {
+    const files = filePath ? [filePath] : await this.findDesignFiles();
+    const violations = [];
+    const details = [];
+
+    for (const file of files) {
+      const content = await fs.readFile(file, 'utf-8');
+      const errors = this.validateDesignDocument(content);
+      
+      if (errors.length > 0) {
+        violations.push(`${path.basename(file)}: ${errors.join(', ')}`);
+        details.push({
+          file: path.basename(file),
+          valid: false,
+          message: errors.join(', ')
+        });
+      } else {
+        details.push({
+          file: path.basename(file),
+          valid: true,
+          message: 'Design document complete'
+        });
+      }
+    }
+
+    return {
+      passed: violations.length === 0,
+      total: files.length,
+      valid: files.length - violations.length,
+      invalid: violations.length,
+      violations,
+      details
+    };
+  }
+
+  /**
+   * Validate single design document
+   * @param {string} content - Document content
+   * @returns {string[]} List of errors
+   */
+  validateDesignDocument(content) {
+    const errors = [];
+
+    // Check for required sections
+    if (!content.includes('## Architecture Design')) {
+      errors.push('Missing Architecture Design section');
+    }
+
+    if (!content.includes('## Steering Context')) {
+      errors.push('Missing Steering Context section');
+    }
+
+    // Check for C4 diagrams (at least one level)
+    const hasC4 = content.includes('C4Context') || 
+                  content.includes('C4Container') ||
+                  content.includes('C4Component') ||
+                  content.includes('C4 Model');
+    
+    if (!hasC4) {
+      errors.push('Missing C4 model diagrams');
+    }
+
+    return errors;
+  }
+
+  /**
+   * Generate traceability matrix
+   * @param {string} [_filePath] - Specific file path
+   * @returns {Promise<object[]>} Traceability matrix
+   */
+  async generateTraceabilityMatrix(_filePath = null) {
+    const matrix = [];
+
+    // Find requirement files
+    const reqFiles = await glob('docs/requirements/**/*.md', { 
+      cwd: this.rootDir, 
+      absolute: true 
+    });
+
+    for (const reqFile of reqFiles) {
+      const content = await fs.readFile(reqFile, 'utf-8');
+      const requirements = this.parseRequirements(content);
+
+      for (const req of requirements) {
+        matrix.push({
+          requirement: req.id,
+          design: false,
+          components: 0,
+          traced: false
+        });
+      }
+    }
+
+    return matrix;
+  }
+
+  /**
+   * Parse requirements from content
+   * @param {string} content - File content
+   * @returns {object[]} List of requirements
+   */
+  parseRequirements(content) {
+    const requirements = [];
+    const reqRegex = /### (REQ-[A-Z]+-\d+):/g;
+
+    let match;
+    while ((match = reqRegex.exec(content)) !== null) {
+      requirements.push({ id: match[1] });
+    }
+
+    return requirements;
+  }
+
+  /**
+   * Convert string to slug
+   * @param {string} str - Input string
+   * @returns {string} Slug
+   */
+  slugify(str) {
+    return str
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-|-$/g, '');
+  }
+}
+
+module.exports = DesignGenerator;