sdd-mcp-server 2.1.0 → 2.2.1

package/dist/utils/atomicWrite.js

@@ -0,0 +1,84 @@
+/**
+ * Atomic file write utility
+ * 原子性檔案寫入工具
+ *
+ * Prevents file corruption when write operations are interrupted (crash, kill signal).
+ * Uses the temp-file + rename pattern which is atomic on POSIX systems.
+ * 防止寫入操作被中斷時（crash、kill signal）造成檔案損壞。
+ * 使用 temp-file + rename 模式，在 POSIX 系統上是原子操作。
+ *
+ * @note Windows Limitation / Windows 限制:
+ *   On Windows, fs.rename() may fail with EEXIST if target exists.
+ *   For Windows production use, consider using 'write-file-atomic' package.
+ *   在 Windows 上，若目標檔案存在，fs.rename() 可能會失敗。
+ *   若需在 Windows 生產環境使用，建議改用 'write-file-atomic' 套件。
+ *
+ * @module utils/atomicWrite
+ */
+import * as fs from "fs/promises";
+import * as path from "path";
+/**
+ * Write content to a file atomically.
+ *
+ * This function writes to a temporary file first, then renames it to the target path.
+ * The rename operation is atomic on POSIX systems, ensuring the file is never left
+ * in a corrupted state.
+ *
+ * @param filePath - The target file path
+ * @param content - The content to write
+ * @param options - Optional write options
+ * @returns Promise that resolves when write is complete
+ *
+ * @example
+ * ```typescript
+ * await atomicWriteFile('/path/to/spec.json', JSON.stringify(data, null, 2));
+ * ```
+ */
+export async function atomicWriteFile(filePath, content, options) {
+    const encoding = options?.encoding ?? "utf8";
+    const dir = path.dirname(filePath);
+    const filename = path.basename(filePath);
+    // Create temp file path with process ID, timestamp, and random suffix for uniqueness
+    // Random suffix prevents collisions when multiple writes occur within the same millisecond
+    const uniqueSuffix = `${Date.now()}.${Math.random().toString(36).slice(2, 10)}`;
+    const tempPath = path.join(dir, `.${filename}.${process.pid}.${uniqueSuffix}.tmp`);
+    try {
+        // Ensure directory exists
+        await fs.mkdir(dir, { recursive: true });
+        // Write to temp file
+        await fs.writeFile(tempPath, content, encoding);
+        // Atomic rename (on POSIX systems)
+        await fs.rename(tempPath, filePath);
+    }
+    catch (error) {
+        // Clean up temp file if it exists
+        try {
+            await fs.unlink(tempPath);
+        }
+        catch {
+            // Ignore cleanup errors
+        }
+        throw error;
+    }
+}
+/**
+ * Write JSON content to a file atomically.
+ *
+ * Convenience wrapper that handles JSON serialization with pretty printing.
+ *
+ * @param filePath - The target file path
+ * @param data - The data to serialize and write
+ * @param options - Optional options (indent spaces, default 2)
+ * @returns Promise that resolves when write is complete
+ *
+ * @example
+ * ```typescript
+ * await atomicWriteJSON('/path/to/spec.json', specData);
+ * ```
+ */
+export async function atomicWriteJSON(filePath, data, options) {
+    const indent = options?.indent ?? 2;
+    const content = JSON.stringify(data, null, indent);
+    await atomicWriteFile(filePath, content);
+}
+//# sourceMappingURL=atomicWrite.js.map

package/dist/utils/atomicWrite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomicWrite.js","sourceRoot":"","sources":["../../src/utils/atomicWrite.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,MAAM,aAAa,CAAC;AAClC,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAE7B;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,QAAgB,EAChB,OAAe,EACf,OAAuC;IAEvC,MAAM,QAAQ,GAAG,OAAO,EAAE,QAAQ,IAAI,MAAM,CAAC;IAC7C,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACnC,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAEzC,qFAAqF;IACrF,2FAA2F;IAC3F,MAAM,YAAY,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC;IAChF,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,QAAQ,IAAI,OAAO,CAAC,GAAG,IAAI,YAAY,MAAM,CAAC,CAAC;IAEnF,IAAI,CAAC;QACH,0BAA0B;QAC1B,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAEzC,qBAAqB;QACrB,MAAM,EAAE,CAAC,SAAS,CAAC,QAAQ,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;QAEhD,mCAAmC;QACnC,MAAM,EAAE,CAAC,MAAM,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IACtC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,kCAAkC;QAClC,IAAI,CAAC;YACH,MAAM,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC5B,CAAC;QAAC,MAAM,CAAC;YACP,wBAAwB;QAC1B,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,QAAgB,EAChB,IAAa,EACb,OAA6B;IAE7B,MAAM,MAAM,GAAG,OAAO,EAAE,MAAM,IAAI,CAAC,CAAC;IACpC,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IACnD,MAAM,eAAe,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;AAC3C,CAAC"}

package/mcp-server.js

@@ -10,6 +10,7 @@ import {
   generateTechDocument,
   generateStructureDocument,
 } from "./documentGenerator.js";
+import { atomicWriteJSON } from "./atomicWrite.js";
 
 // Best-effort dynamic loader for spec generators (requirements/design/tasks)
 async function loadSpecGenerator() {
@@ -551,7 +552,7 @@ server.registerTool(
       spec.approvals.requirements.generated = true;
       spec.updated_at = await getCurrentTimestamp();
 
-      await fs.writeFile(specPath, JSON.stringify(spec, null, 2));
+      await atomicWriteJSON(specPath, spec);
 
       return {
         content: [
@@ -633,7 +634,7 @@ server.registerTool(
       spec.approvals.design.generated = true;
       spec.updated_at = await getCurrentTimestamp();
 
-      await fs.writeFile(specPath, JSON.stringify(spec, null, 2));
+      await atomicWriteJSON(specPath, spec);
 
       return {
         content: [
@@ -771,7 +772,7 @@ ${designContext.substring(0, 1000)}${designContext.length > 1000 ? "...\n[Design
       spec.ready_for_implementation = true;
       spec.updated_at = await getCurrentTimestamp();
 
-      await fs.writeFile(specPath, JSON.stringify(spec, null, 2));
+      await atomicWriteJSON(specPath, spec);
 
       return {
         content: [
@@ -1034,7 +1035,7 @@ server.registerTool(
       spec.approvals[phase].approved = true;
       spec.updated_at = await getCurrentTimestamp();
 
-      await fs.writeFile(specPath, JSON.stringify(spec, null, 2));
+      await atomicWriteJSON(specPath, spec);
 
       return {
         content: [

package/package.json

@@ -1,18 +1,20 @@
 {
   "name": "sdd-mcp-server",
-  "version": "2.1.0",
+  "version": "2.2.1",
   "description": "MCP server for spec-driven development workflows across AI-agent CLIs and IDEs",
   "main": "dist/index.js",
   "bin": {
-    "sdd-mcp-server": "mcp-server.js",
-    "sdd-mcp": "dist/cli/sdd-mcp-cli.js",
+    "sdd-mcp-server": "sdd-entry.js",
     "sdd-install-skills": "dist/cli/install-skills.js"
   },
   "type": "module",
   "files": [
     "dist/**/*",
     "skills/**/*",
+    "steering/**/*",
+    "sdd-entry.js",
     "mcp-server.js",
+    "atomicWrite.js",
     "documentGenerator.js",
     "specGenerator.js",
     "README.md",

package/sdd-entry.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+/**
+ * Unified entry point for sdd-mcp-server
+ *
+ * Handles both:
+ * - CLI commands (install, install-skills, migrate-kiro)
+ * - MCP server mode (default)
+ *
+ * Usage:
+ *   npx sdd-mcp-server install --list      # CLI: List available skills
+ *   npx sdd-mcp-server install             # CLI: Install skills and steering
+ *   npx sdd-mcp-server                     # MCP: Start MCP server
+ */
+
+const CLI_COMMANDS = ['install', 'install-skills', 'migrate-kiro'];
+const args = process.argv.slice(2);
+const command = args[0];
+
+if (command && (CLI_COMMANDS.includes(command) || command === '--help' || command === '-h')) {
+  // CLI mode - import and run CLI module
+  import('./dist/cli/sdd-mcp-cli.js').catch(err => {
+    console.error('Failed to load CLI:', err.message);
+    process.exit(1);
+  });
+} else {
+  // MCP server mode - import and run the MCP server
+  import('./mcp-server.js').catch(err => {
+    console.error('Failed to start MCP server:', err.message);
+    process.exit(1);
+  });
+}

package/skills/sdd-commit/SKILL.md

@@ -271,6 +271,20 @@ git rebase origin/main
 git push origin feature/AUTH-123-jwt-auth
 ```
 
+## Steering Document References
+
+Apply these steering documents for commits and PRs:
+
+| Document | Purpose | Key Application |
+|----------|---------|-----------------|
+| `.spec/steering/commit.md` | Commit message conventions | Follow type prefixes, scope, and format guidelines |
+
+**Key Commit Rules:**
+1. Use type prefixes: `feat`, `fix`, `docs`, `refactor`, `test`, etc.
+2. Keep subject line under 72 characters
+3. Use imperative mood ("add" not "added")
+4. Reference issues in footer
+
 ## Quality Checklist
 
 - [ ] Commit message follows format

package/skills/sdd-design/SKILL.md

@@ -248,6 +248,21 @@ Before finalizing, validate against these principles:
 | `sdd-validate-design` | Perform GO/NO-GO review |
 | `sdd-approve` | Mark design phase as approved |
 
+## Steering Document References
+
+Apply these steering documents during design:
+
+| Document | Purpose | Key Application |
+|----------|---------|-----------------|
+| `.spec/steering/principles.md` | SOLID, DRY, KISS, YAGNI | Apply SOLID principles to component design, ensure interfaces follow ISP and DIP |
+| `.spec/steering/linus-review.md` | Code quality, data structures | Focus on data structures first, eliminate special cases, ensure backward compatibility |
+
+**Key Linus Principles for Design:**
+1. **Data Structures First**: "Bad programmers worry about the code. Good programmers worry about data structures."
+2. **Eliminate Special Cases**: "Good code has no special cases"
+3. **Simplicity**: "If implementation needs more than 3 levels of indentation, redesign it"
+4. **Never Break Userspace**: Ensure backward compatibility
+
 ## Quality Checklist
 
 - [ ] All FR-* requirements have corresponding components

package/skills/sdd-implement/SKILL.md

@@ -269,6 +269,21 @@ After implementing each task:
 - [ ] SOLID principles applied
 - [ ] Code self-documenting or commented where needed
 
+## Steering Document References
+
+Apply these steering documents during implementation:
+
+| Document | Purpose | Key Application |
+|----------|---------|-----------------|
+| `.spec/steering/tdd-guideline.md` | Test-Driven Development | Follow Red-Green-Refactor cycle for all code |
+| `.spec/steering/principles.md` | SOLID, DRY, KISS, YAGNI | Apply SOLID principles, keep code simple and focused |
+| `.spec/steering/owasp-top10-check.md` | Security checklist | Verify all OWASP Top 10 security requirements before completion |
+
+**Critical Implementation Rules:**
+1. **TDD First**: Never write production code without a failing test
+2. **SOLID Always**: Apply all five principles (SRP, OCP, LSP, ISP, DIP)
+3. **Security Required**: Complete OWASP checklist before marking done
+
 ## Common Anti-Patterns to Avoid
 
 | Anti-Pattern | Problem | Solution |

package/skills/sdd-requirements/SKILL.md

@@ -133,8 +133,15 @@ Before completing requirements:
 - [ ] No ambiguous terms (avoid "should", "may", "might")
 - [ ] Each FR has clear acceptance criteria
 
-## Coding Principles Applied
+## Steering Document References
 
-- **SOLID**: Single Responsibility - each requirement addresses one concern
+Apply these steering documents during requirements generation:
+
+| Document | Purpose | Key Application |
+|----------|---------|-----------------|
+| `.spec/steering/principles.md` | SOLID, DRY, KISS, YAGNI | Ensure requirements follow KISS (simple, unambiguous) and YAGNI (only what's needed now) |
+
+**Key Principles for Requirements:**
 - **KISS**: Keep requirements simple and unambiguous
 - **YAGNI**: Only specify what's actually needed now
+- **Single Responsibility**: Each requirement addresses one concern

package/skills/sdd-tasks/SKILL.md

@@ -222,6 +222,20 @@ describe('{Component}', () => {
 - [ ] Implementation order respects dependencies
 - [ ] Definition of Done is clear
 
+## Steering Document References
+
+Apply these steering documents during task breakdown:
+
+| Document | Purpose | Key Application |
+|----------|---------|-----------------|
+| `.spec/steering/tdd-guideline.md` | Test-Driven Development | Structure all tasks using Red-Green-Refactor cycle, follow test pyramid (70/20/10) |
+
+**Key TDD Principles for Tasks:**
+1. **RED**: Every task starts with writing a failing test
+2. **GREEN**: Implement minimal code to pass the test
+3. **REFACTOR**: Clean up while keeping tests green
+4. **Test Pyramid**: 70% unit, 20% integration, 10% E2E
+
 ## Common Anti-Patterns to Avoid
 
 | Anti-Pattern | Problem | Solution |

package/steering/AGENTS.md

@@ -0,0 +1,281 @@
+# AI Agents Integration Guide
+
+## Purpose
+This document defines how AI agents should interact with the SDD workflow and provides guidelines for effective agent collaboration in spec-driven development.
+
+## Agent Types and Roles
+
+### Development Agents
+AI agents that assist with code implementation, testing, and documentation.
+
+**Primary Tools**: Claude Code, Cursor, GitHub Copilot, and similar AI development assistants.
+
+**Responsibilities**:
+- Follow SDD workflow phases strictly
+- Generate code based on approved specifications
+- Maintain consistency with project steering documents
+- Ensure quality through automated testing
+
+### Review Agents
+AI agents specialized in code review, quality analysis, and security validation.
+
+**Primary Focus**:
+- Apply Linus-style code review principles
+- Validate implementation against requirements
+- Check for security vulnerabilities
+- Ensure performance standards
+
+### Planning Agents
+AI agents that help with requirements gathering, design decisions, and task breakdown.
+
+**Primary Activities**:
+- Analyze project requirements using EARS format
+- Generate technical design documents
+- Create implementation task breakdowns
+- Validate workflow phase transitions
+
+## Agent Communication Protocol
+
+### Context Sharing
+All agents must:
+1. Load project steering documents at interaction start:
+   - `product.md` - Product context and business objectives
+   - `tech.md` - Technology stack and architectural decisions
+   - `structure.md` - File organization and code patterns
+   - `linus-review.md` - Code quality review principles
+   - `commit.md` - Commit message standards
+   - **`owasp-top10-check.md` - OWASP Top 10 security checklist (REQUIRED for code generation and review)**
+   - **`tdd-guideline.md` - Test-Driven Development workflow (REQUIRED for all new features)**
+   - **`principles.md` - Core coding principles (SOLID, DRY, KISS, YAGNI, Separation of Concerns, Modularity)**
+2. Check current workflow phase before proceeding
+3. Validate approvals before phase transitions
+4. Update spec.json with progress tracking
+
+### Information Flow
+```
+User Request → Agent Analysis → SDD Tool Invocation → Result Validation → User Response
+```
+
+### State Management
+- Agents must maintain awareness of current project state
+- Phase transitions require explicit approval tracking
+- All changes must be logged in spec.json metadata
+
+## Agent Tool Usage
+
+### Required Tools for All Agents
+- `sdd-status`: Check current workflow state
+- `sdd-context-load`: Load project context
+- `sdd-quality-check`: Validate code quality
+
+### Phase-Specific Tools
+
+**Initialization Phase**:
+- `sdd-init`: Create new project structure
+- `sdd-steering`: Generate steering documents
+
+**Requirements Phase**:
+- `sdd-requirements`: Generate requirements document
+- `sdd-validate-gap`: Analyze implementation gaps
+
+**Design Phase**:
+- `sdd-design`: Create technical design
+- `sdd-validate-design`: Review design quality
+
+**Tasks Phase**:
+- `sdd-tasks`: Generate task breakdown
+- `sdd-spec-impl`: Execute tasks with TDD
+
+**Implementation Phase**:
+- `sdd-implement`: Get implementation guidelines
+- `sdd-quality-check`: Continuous quality validation
+
+## Agent Collaboration Patterns
+
+### Sequential Collaboration
+Agents work in sequence through workflow phases:
+```
+Planning Agent → Design Agent → Implementation Agent → Review Agent
+```
+
+### Parallel Collaboration
+Multiple agents work on different aspects simultaneously:
+- Frontend Agent handles UI tasks
+- Backend Agent handles API tasks
+- Test Agent creates test suites
+- Documentation Agent updates docs
+
+### Feedback Loops
+Agents provide feedback to improve specifications:
+- Implementation issues feed back to design
+- Test failures inform requirement updates
+- Performance problems trigger architecture reviews
+
+## Quality Standards for Agents
+
+### Code Generation Standards
+- Follow project coding conventions from structure.md
+- Implement comprehensive error handling
+- Include appropriate logging and monitoring
+- Write self-documenting code with clear naming
+
+### Testing Requirements
+- Generate unit tests for all new functions
+- Create integration tests for workflows
+- Implement performance benchmarks
+- Ensure test coverage meets project standards
+
+### Documentation Expectations
+- Update relevant documentation with changes
+- Maintain clear commit messages following commit.md
+- Document design decisions and trade-offs
+- Keep README and API docs current
+
+## Agent Configuration
+
+### Environment Setup
+Agents should configure their environment with:
+```bash
+# Load SDD MCP server
+npx sdd-mcp-server
+
+# Initialize project context
+sdd-context-load [feature-name]
+
+# Check current status
+sdd-status [feature-name]
+```
+
+### Steering Document Loading
+Agents must respect steering document modes:
+- **Always**: Load for every interaction
+- **Conditional**: Load based on file patterns
+- **Manual**: Load when explicitly requested
+
+### Tool Invocation Patterns
+```javascript
+// Check phase before proceeding
+const status = await sdd-status(featureName);
+
+// Validate requirements exist
+if (!status.requirements.generated) {
+  await sdd-requirements(featureName);
+}
+
+// Proceed with implementation
+await sdd-implement(featureName);
+```
+
+## Best Practices for AI Agents
+
+### 1. Context Awareness
+- Always load full project context before making changes
+- Understand the current workflow phase and requirements
+- Check for existing implementations before creating new ones
+
+### 2. Incremental Progress
+- Complete one task fully before moving to the next
+- Update task checkboxes in tasks.md as work progresses
+- Commit changes frequently with clear messages
+
+### 3. Quality Focus
+- Run quality checks after each significant change
+- Address issues immediately rather than accumulating debt
+- **Follow TDD principles strictly: Red → Green → Refactor**
+  - **RED**: Write failing tests BEFORE any implementation
+  - **GREEN**: Write minimal code to make tests pass
+  - **REFACTOR**: Improve code quality while keeping tests green
+  - Refer to `.spec/steering/tdd-guideline.md` for complete TDD workflow
+
+### 4. Communication Clarity
+- Provide clear explanations for design decisions
+- Document assumptions and constraints
+- Report blockers and issues promptly
+
+### 5. Workflow Compliance
+- Never skip workflow phases
+- Ensure approvals are in place before proceeding
+- Maintain traceability from requirements to implementation
+
+## Error Handling for Agents
+
+### Common Issues and Solutions
+
+**Phase Violation**: Attempting to skip workflow phases
+- Solution: Follow the prescribed phase sequence
+- Use `sdd-status` to check current phase
+
+**Missing Context**: Operating without project understanding
+- Solution: Load context with `sdd-context-load`
+- Review steering documents before proceeding
+
+**Quality Failures**: Code doesn't meet standards
+- Solution: Run `sdd-quality-check` regularly
+- Apply Linus-style review principles
+
+**Integration Conflicts**: Changes break existing functionality
+- Solution: Run comprehensive tests before committing
+- Ensure backward compatibility
+
+## Performance Guidelines
+
+### Efficiency Standards
+- Minimize redundant tool invocations
+- Cache project context when possible
+- Batch related operations together
+
+### Resource Management
+- Clean up temporary files after operations
+- Limit concurrent file operations
+- Optimize for large codebases
+
+## Security Considerations
+
+### Code Review Security
+- Check for credential exposure
+- Validate input sanitization
+- Review authentication/authorization logic
+- Identify potential injection vulnerabilities
+
+### Data Handling
+- Never commit sensitive data
+- Use environment variables for configuration
+- Implement proper encryption for sensitive operations
+- Follow least privilege principles
+
+## Integration with CI/CD
+
+### Automated Workflows
+Agents should support CI/CD integration:
+- Trigger quality checks on commits
+- Validate phase requirements in pipelines
+- Generate reports for review processes
+- Update documentation automatically
+
+### Deployment Readiness
+Before deployment, agents must ensure:
+- All tests pass successfully
+- Documentation is complete and current
+- Quality standards are met
+- Security scans show no critical issues
+
+## Continuous Improvement
+
+### Learning from Feedback
+- Analyze failed implementations
+- Update patterns based on successes
+- Refine task estimation accuracy
+- Improve requirement interpretation
+
+### Metrics and Monitoring
+Track agent performance metrics:
+- Task completion accuracy
+- Code quality scores
+- Time to implementation
+- Defect rates post-deployment
+
+## Conclusion
+
+AI agents are integral to the SDD workflow, providing automation and intelligence throughout the development lifecycle. By following these guidelines, agents can effectively collaborate to deliver high-quality, specification-compliant software while maintaining the rigor and discipline of spec-driven development.
+
+Remember: Agents augment human decision-making but don't replace it. Critical decisions, approvals, and architectural choices should always involve human oversight.

package/steering/commit.md

@@ -0,0 +1,59 @@
+# Commit Message Guidelines
+
+Commit messages should follow a consistent format to improve readability and provide clear context about changes. Each commit message should start with a type prefix that indicates the nature of the change.
+
+## Format
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+## Type Prefixes
+
+All commit messages must begin with one of these type prefixes:
+
+- **docs**: Documentation changes (README, comments, etc.)
+- **chore**: Maintenance tasks, dependency updates, etc.
+- **feat**: New features or enhancements
+- **fix**: Bug fixes
+- **refactor**: Code changes that neither fix bugs nor add features
+- **test**: Adding or modifying tests
+- **style**: Changes that don't affect code functionality (formatting, whitespace)
+- **perf**: Performance improvements
+- **ci**: Changes to CI/CD configuration files and scripts
+
+## Scope (Optional)
+
+The scope provides additional context about which part of the codebase is affected:
+
+- **cluster**: Changes to EKS cluster configuration
+- **db**: Database-related changes
+- **iam**: Identity and access management changes
+- **net**: Networking changes (VPC, security groups, etc.)
+- **k8s**: Kubernetes resource changes
+- **module**: Changes to reusable Terraform modules
+
+## Examples
+
+```
+feat(cluster): add node autoscaling for billing namespace
+fix(db): correct MySQL parameter group settings
+docs(k8s): update network policy documentation
+chore: update terraform provider versions
+refactor(module): simplify EKS node group module
+```
+
+## Best Practices
+
+1. Keep the subject line under 72 characters
+2. Use imperative mood in the subject line ("add" not "added")
+3. Don't end the subject line with a period
+4. Separate subject from body with a blank line
+5. Use the body to explain what and why, not how
+6. Reference issues and pull requests in the footer
+
+These guidelines help maintain a clean and useful git history that makes it easier to track changes and understand the project's evolution.