ironweave 1.0.1 → 1.1.1

package/.claude-plugin/plugin.json

@@ -12,5 +12,6 @@
     "architecture",
     "quality-gates",
     "workflows"
-  ]
+  ],
+  "hooks": "./hooks/hooks.json"
 }

package/.cursor-plugin/plugin.json

@@ -15,5 +15,5 @@
     "workflows"
   ],
   "skills": "./skills/",
-  "agents": "./agents/"
+  "hooks": "./hooks/hooks-cursor.json"
 }

package/AGENTS.md

@@ -1 +1,22 @@
-CLAUDE.md
+# Ironweave
+
+You have access to the Ironweave skills library — a complete software development workflow with built-in quality gates.
+
+## How to use
+
+The **orchestrator** skill (`skills/orchestrator/SKILL.md`) is the main entry point. It automatically:
+- Senses project context and scores task difficulty
+- Selects the right route (new project / new feature / bug fix / refactoring)
+- Runs Plan → Execute → Validate → Deliver with quality gates per slice
+
+For any development task, start by reading the orchestrator skill. It will guide which other skills to invoke.
+
+## Skills available
+
+All skills are in `skills/`. Each has a `SKILL.md` with YAML frontmatter (`name`, `description`).
+
+Key skills: `orchestrator`, `requirement-qa`, `brainstorm`, `spec-writing`, `tech-stack`, `engineering-principles`, `api-contract-design`, `code-scaffold`, `error-handling-strategy`, `performance-arch-design`, `observability-design`, `integration-test-design`, `implementation-complexity-analysis`, `task-difficulty`, `project-context`, `docs-output`.
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md).

package/CLAUDE.md

@@ -15,7 +15,7 @@ For any development task, start by reading the orchestrator skill. It will guide
 
 All skills are in `skills/`. Each has a `SKILL.md` with YAML frontmatter (`name`, `description`).
 
-Key skills: `orchestrator`, `requirement-qa`, `brainstorm`, `spec-writing`, `tech-stack`, `engineering-principles`, `api-contract-design`, `code-scaffold`, `error-handling-strategy`, `performance-arch-design`, `observability-design`, `integration-test-design`, `implementation-complexity-analysis`, `task-difficulty`, `project-context`, `docs-output`, `skill-creator`.
+Key skills: `orchestrator`, `requirement-qa`, `brainstorm`, `spec-writing`, `tech-stack`, `engineering-principles`, `api-contract-design`, `code-scaffold`, `error-handling-strategy`, `performance-arch-design`, `observability-design`, `integration-test-design`, `implementation-complexity-analysis`, `task-difficulty`, `project-context`, `docs-output`.
 
 ## Contributing
 

package/README.md

@@ -95,16 +95,18 @@ User Request
 - `task-difficulty` — Multi-dimensional difficulty scoring (1-10)
 - `project-context` — Project structure awareness & cross-session persistence
 - `docs-output` — Document output management (modular docs/ organization)
-- `skill-creator` — Create, modify, and evaluate agent skills
 
 ## Installation
 
 ### Via skills.sh (Recommended)
 
 ```bash
-# Install all skills
+# Install all skills (Chinese, default)
 npx skills add YuluoY/ironware
 
+# Install English skills
+npx skills add YuluoY/ironware --lang en
+
 # Install specific skills
 npx skills add YuluoY/ironware --skill orchestrator --skill brainstorm
 
@@ -112,6 +114,16 @@ npx skills add YuluoY/ironware --skill orchestrator --skill brainstorm
 npx skills add YuluoY/ironware --list
 ```
 
+Or via npm:
+
+```bash
+# Install with Chinese skills (default)
+npx ironweave init
+
+# Install with English skills
+npx ironweave init --lang en
+```
+
 Supports **40+ agents**: Claude Code, GitHub Copilot, Cursor, Codex, Windsurf, Cline, OpenCode, Gemini CLI, Trae, CodeBuddy, and more.
 
 ### Per-Agent Manual Installation
@@ -206,7 +218,7 @@ Copy the `skills/` directory into your project. Then add the following to your a
 
 ```
 ironweave/
-├── skills/
+├── skills/                          # Skills (Chinese)
 │   ├── orchestrator/              # Flow orchestrator
 │   │   ├── SKILL.md              # Orchestrator logic
 │   │   └── references/           # Methodology docs
@@ -214,7 +226,8 @@ ironweave/
 │   ├── spec-writing/
 │   ├── code-scaffold/
 │   ├── ...                        # 16 more skills
-│   └── skill-creator/
+│   └── docs-output/
+├── skills-en/                       # Skills (English)
 ├── CLAUDE.md                      # Claude Code instructions
 ├── AGENTS.md                      # Codex instructions
 ├── GEMINI.md                      # Gemini CLI instructions
@@ -243,7 +256,7 @@ ironweave/
 
 ## Contributing
 
-See [CONTRIBUTING.md](./CONTRIBUTING.md). Skills live directly in this repository. Follow `skills/skill-creator` for creating and testing new skills.
+See [CONTRIBUTING.md](./CONTRIBUTING.md). Skills live directly in this repository.
 
 ## License
 

package/README_CN.md

@@ -93,16 +93,18 @@ Ironweave 是一套完整的软件开发工作流，由一组可自由组合的
 - `task-difficulty` — 多维度难度评分（1-10）
 - `project-context` — 项目结构感知与跨会话持久化
 - `docs-output` — 文档产出管理（模块化 docs/ 组织）
-- `skill-creator` — 创建、修改、评测 Agent Skills
 
 ## 安装
 
 ### 通过 skills.sh（推荐）
 
 ```bash
-# 安装全部技能
+# 安装全部技能（中文，默认）
 npx skills add YuluoY/ironware
 
+# 安装英文版技能
+npx skills add YuluoY/ironware --lang en
+
 # 安装指定技能
 npx skills add YuluoY/ironware --skill orchestrator --skill brainstorm
 
@@ -110,6 +112,16 @@ npx skills add YuluoY/ironware --skill orchestrator --skill brainstorm
 npx skills add YuluoY/ironware --list
 ```
 
+或通过 npm 安装：
+
+```bash
+# 安装中文技能（默认）
+npx ironweave init
+
+# 安装英文版技能
+npx ironweave init --lang en
+```
+
 支持 **40+ 个 Agent**：Claude Code、GitHub Copilot、Cursor、Codex、Windsurf、Cline、OpenCode、Gemini CLI、Trae、CodeBuddy 等。
 
 ### 各 Agent 手动安装
@@ -204,7 +216,7 @@ git clone https://github.com/YuluoY/ironware.git
 
 ```
 ironweave/
-├── skills/
+├── skills/                          # 技能（中文）
 │   ├── orchestrator/              # 流程编排器
 │   │   ├── SKILL.md              # 编排器逻辑
 │   │   └── references/           # 方法论文档
@@ -212,7 +224,8 @@ ironweave/
 │   ├── spec-writing/
 │   ├── code-scaffold/
 │   ├── ...                        # 另外 16 个技能
-│   └── skill-creator/
+│   └── docs-output/
+├── skills-en/                       # 技能（英文）
 ├── CLAUDE.md                      # Claude Code 指令
 ├── AGENTS.md                      # Codex 指令
 ├── GEMINI.md                      # Gemini CLI 指令
@@ -241,7 +254,7 @@ ironweave/
 
 ## 贡献
 
-请参阅 [CONTRIBUTING.md](./CONTRIBUTING.md)。技能直接存放在本仓库中。创建和测试新技能请参考 `skills/skill-creator`。
+请参阅 [CONTRIBUTING.md](./CONTRIBUTING.md)。技能直接存放在本仓库中。
 
 ## 许可证
 

package/bin/cli.js

@@ -18,18 +18,23 @@ Options:
   --agent <name>    Only install config for specific agent
                     (claude, copilot, cursor, windsurf, cline, codex, gemini, all)
                     Default: all
+  --lang <lang>     Language for skills: zh (Chinese, default) or en (English)
   --skills-only     Only copy skills/, skip agent config files
+  --force           Overwrite existing files (default: skip existing)
   --help            Show this help message
 `);
   process.exit(0);
 }
 
 if (command === 'list') {
-  const skillsDir = path.join(__dirname, '..', 'skills');
+  const langIdx = args.indexOf('--lang');
+  const listLang = langIdx !== -1 ? args[langIdx + 1] : 'zh';
+  const skillsSrc = listLang === 'en' ? 'skills-en' : 'skills';
+  const skillsDir = path.join(__dirname, '..', skillsSrc);
   const skills = fs.readdirSync(skillsDir).filter(f => {
     return fs.statSync(path.join(skillsDir, f)).isDirectory();
   });
-  console.log(`\nIronweave Skills (${skills.length}):\n`);
+  console.log(`\nIronweave Skills [${listLang}] (${skills.length}):\n`);
   skills.forEach(s => console.log(`  - ${s}`));
   console.log('');
   process.exit(0);
@@ -41,13 +46,22 @@ if (command === 'init') {
 
   const agentFlag = args.indexOf('--agent');
   const agent = agentFlag !== -1 ? args[agentFlag + 1] : 'all';
+  const langFlag = args.indexOf('--lang');
+  const lang = langFlag !== -1 ? args[langFlag + 1] : 'zh';
   const skillsOnly = args.includes('--skills-only');
+  const force = args.includes('--force');
 
-  // Copy skills/
-  const srcSkills = path.join(pkgDir, 'skills');
+  // Copy skills/ and hooks/
+  const skillsSrc = lang === 'en' ? 'skills-en' : 'skills';
+  const srcSkills = path.join(pkgDir, skillsSrc);
   const dstSkills = path.join(targetDir, 'skills');
-  copyDirRecursive(srcSkills, dstSkills);
-  console.log('✓ skills/ copied');
+  copyDirRecursive(srcSkills, dstSkills, force);
+  console.log(`✓ skills/ copied (${lang === 'en' ? 'English' : 'Chinese'})`);
+
+  const srcHooks = path.join(pkgDir, 'hooks');
+  const dstHooks = path.join(targetDir, 'hooks');
+  copyDirRecursive(srcHooks, dstHooks, force);
+  console.log('✓ hooks/ copied');
 
   if (!skillsOnly) {
     const agentFiles = {
@@ -73,7 +87,8 @@ if (command === 'init') {
         { src: '.codex', dst: '.codex', dir: true }
       ],
       gemini: [
-        { src: 'GEMINI.md', dst: 'GEMINI.md' }
+        { src: 'GEMINI.md', dst: 'GEMINI.md' },
+        { src: 'gemini-extension.json', dst: 'gemini-extension.json' }
       ]
     };
 
@@ -89,11 +104,11 @@ if (command === 'init') {
         const srcPath = path.join(pkgDir, f.src);
         const dstPath = path.join(targetDir, f.dst);
         if (f.dir) {
-          copyDirRecursive(srcPath, dstPath);
+          copyDirRecursive(srcPath, dstPath, force);
         } else {
           const dstDir = path.dirname(dstPath);
           if (!fs.existsSync(dstDir)) fs.mkdirSync(dstDir, { recursive: true });
-          if (!fs.existsSync(dstPath)) {
+          if (force || !fs.existsSync(dstPath)) {
             fs.copyFileSync(srcPath, dstPath);
           }
         }
@@ -109,7 +124,7 @@ if (command === 'init') {
 console.error(`Unknown command: ${command}. Run "npx ironweave --help" for usage.`);
 process.exit(1);
 
-function copyDirRecursive(src, dst) {
+function copyDirRecursive(src, dst, force) {
   if (!fs.existsSync(src)) return;
   if (!fs.existsSync(dst)) fs.mkdirSync(dst, { recursive: true });
   const entries = fs.readdirSync(src, { withFileTypes: true });
@@ -117,8 +132,8 @@ function copyDirRecursive(src, dst) {
     const srcPath = path.join(src, entry.name);
     const dstPath = path.join(dst, entry.name);
     if (entry.isDirectory()) {
-      copyDirRecursive(srcPath, dstPath);
-    } else if (!fs.existsSync(dstPath)) {
+      copyDirRecursive(srcPath, dstPath, force);
+    } else if (force || !fs.existsSync(dstPath)) {
       fs.copyFileSync(srcPath, dstPath);
     }
   }

package/gemini-extension.json

@@ -0,0 +1,6 @@
+{
+  "name": "ironweave",
+  "description": "Agentic skills framework for software development: orchestration, requirements, architecture, TDD, and quality gates",
+  "version": "1.0.0",
+  "contextFileName": "GEMINI.md"
+}

package/hooks/hooks-cursor.json

@@ -0,0 +1,10 @@
+{
+  "version": 1,
+  "hooks": {
+    "sessionStart": [
+      {
+        "command": "./hooks/session-start"
+      }
+    ]
+  }
+}

package/hooks/hooks.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start",
+            "async": false
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/run-hook.cmd

@@ -0,0 +1,5 @@
+@echo off
+setlocal
+set "SCRIPT_DIR=%~dp0"
+set "PLUGIN_ROOT=%SCRIPT_DIR%.."
+call "%PLUGIN_ROOT%\hooks\session-start"

package/hooks/session-start

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# SessionStart hook for Ironweave plugin
+
+set -euo pipefail
+
+# Determine plugin root directory
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
+
+# Read orchestrator skill content
+orchestrator_content=$(cat "${PLUGIN_ROOT}/skills/orchestrator/SKILL.md" 2>&1 || echo "Error reading orchestrator skill")
+
+# Escape string for JSON embedding
+escape_for_json() {
+    local s="$1"
+    s="${s//\\/\\\\}"
+    s="${s//\"/\\\"}"
+    s="${s//$'\n'/\\n}"
+    s="${s//$'\r'/\\r}"
+    s="${s//$'\t'/\\t}"
+    printf '%s' "$s"
+}
+
+orchestrator_escaped=$(escape_for_json "$orchestrator_content")
+session_context="<IMPORTANT>\nYou have Ironweave skills.\n\nIronweave is a complete software development workflow with built-in quality gates. The orchestrator skill is your main entry point — it auto-senses context, scores difficulty, selects the right route, and runs Plan > Execute > Validate > Deliver.\n\nAll skills are in the skills/ directory, each with a SKILL.md. For any development task, start by reading skills/orchestrator/SKILL.md.\n\nKey skills: orchestrator, requirement-qa, brainstorm, spec-writing, tech-stack, engineering-principles, api-contract-design, code-scaffold, error-handling-strategy, performance-arch-design, observability-design, integration-test-design, implementation-complexity-analysis, task-difficulty, project-context, docs-output.\n</IMPORTANT>"
+
+# Output context injection as JSON.
+# Cursor hooks expect additional_context (snake_case).
+# Claude Code hooks expect hookSpecificOutput.additionalContext (nested).
+# Copilot CLI and others expect additionalContext (top-level, SDK standard).
+if [ -n "${CURSOR_PLUGIN_ROOT:-}" ]; then
+  printf '{\n  "additional_context": "%s"\n}\n' "$session_context"
+elif [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && [ -z "${COPILOT_CLI:-}" ]; then
+  printf '{\n  "hookSpecificOutput": {\n    "hookEventName": "SessionStart",\n    "additionalContext": "%s"\n  }\n}\n' "$session_context"
+else
+  printf '{\n  "additionalContext": "%s"\n}\n' "$session_context"
+fi
+
+exit 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ironweave",
-  "version": "1.0.1",
+  "version": "1.1.1",
   "description": "Agentic skills framework for AI coding agents — orchestrated workflows with adaptive routing, quality gates, and 17 composable skills.",
   "keywords": [
     "agent-skills",
@@ -32,10 +32,13 @@
   },
   "files": [
     "skills/",
+    "skills-en/",
+    "hooks/",
     "bin/",
     "CLAUDE.md",
     "AGENTS.md",
     "GEMINI.md",
+    "gemini-extension.json",
     ".cursorrules",
     ".windsurfrules",
     ".clinerules",

package/skills-en/api-contract-design/SKILL.md

@@ -0,0 +1,227 @@
+---
+name: api-contract-design
+description: >-
+  A detailed design tool for API interface contracts and type systems. Starting from domain models and requirement documents, it generates RESTful/GraphQL API endpoint definitions, Request/Response DTO structures, error response standards, OpenAPI specifications, and type code scaffolds.
+  Use this skill in the following scenarios: when users need to design API interfaces, define Data Transfer Objects (DTOs), write interface documentation, establish error code standards, or when users say "design API", "define API", "write API contract", "DTO design", "API specification", "error codes", "OpenAPI", "Swagger".
+  Use this skill when the user's task involves transforming business models into technical interfaces.
+---
+
+# API Contract Design
+
+Starting from domain models + requirement documents, produce complete API interface contracts. All design decisions are expressed as Mermaid flowcharts.
+
+---
+
+## Design Flow
+
+```mermaid
+graph TB
+    INPUT["Domain Model + Requirements"] --> RESOURCE["Resource Identification<br>Noun Extraction"]
+    RESOURCE --> ENDPOINT["Endpoint Design<br>RESTful Mapping"]
+    ENDPOINT --> DTO["DTO Structure<br>Request/Response"]
+    DTO --> ERROR["Error Response<br>Standardized Design"]
+    ERROR --> VERSION["Versioning Strategy"]
+    VERSION --> OUTPUT["Output OpenAPI Spec"]
+
+    style INPUT fill:#e3f2fd,stroke:#1565c0,color:#0d47a1
+    style RESOURCE fill:#e8eaf6,stroke:#283593,color:#1a237e
+    style ENDPOINT fill:#e8eaf6,stroke:#283593,color:#1a237e
+    style DTO fill:#e8eaf6,stroke:#283593,color:#1a237e
+    style ERROR fill:#fff3e0,stroke:#e65100,color:#bf360c
+    style VERSION fill:#f5f5f5,stroke:#616161,color:#212121
+    style OUTPUT fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20
+```
+
+---
+
+## 1. Resource Identification
+
+Extract API resources from the domain model:
+
+| Domain Concept | API Resource | Notes |
+|--|--|--|
+| Aggregate Root | Top-level resource `/resources` | Directly exposed as RESTful resource |
+| Entity (non-root) | Sub-resource `/resources/{id}/sub` | Accessed through parent resource |
+| Value Object | Embedded in DTO | Not exposed independently |
+| Domain Service | Action endpoint `/resources/{id}/actions/do` | Non-CRUD operations |
+
+---
+
+## 2. Endpoint Design Standards
+
+### RESTful Mapping Rules
+
+```mermaid
+graph LR
+    CRUD{"Operation Type?"} -->|"Create"| POST["POST /resources"]
+    CRUD -->|"Read Single"| GET_ONE["GET /resources/{id}"]
+    CRUD -->|"Read List"| GET_LIST["GET /resources?filter"]
+    CRUD -->|"Full Update"| PUT["PUT /resources/{id}"]
+    CRUD -->|"Partial Update"| PATCH["PATCH /resources/{id}"]
+    CRUD -->|"Delete"| DELETE["DELETE /resources/{id}"]
+    CRUD -->|"Non-CRUD Action"| ACTION["POST /resources/{id}/actions/{verb}"]
+
+    style POST fill:#c8e6c9,stroke:#2e7d32,color:#1b5e20
+    style GET_ONE fill:#e3f2fd,stroke:#1565c0,color:#0d47a1
+    style GET_LIST fill:#e3f2fd,stroke:#1565c0,color:#0d47a1
+    style PUT fill:#fff9c4,stroke:#f9a825,color:#e65100
+    style PATCH fill:#fff9c4,stroke:#f9a825,color:#e65100
+    style DELETE fill:#ffcdd2,stroke:#c62828,color:#b71c1c
+    style ACTION fill:#f3e5f5,stroke:#6a1b9a,color:#4a148c
+```
+
+### Naming Conventions
+- Resource names: Plural form (`/users` not `/user`)
+- Paths: kebab-case (`/migration-tasks`)
+- Query parameters: camelCase (`?pageSize=20&sortBy=createdAt`)
+- Nesting max 2 levels: `/resources/{id}/sub-resources/{subId}`
+
+### Idempotency Requirements
+
+| Method | Idempotent? | Safe? | Notes |
+|--|--|--|--|
+| GET | Yes | Yes | Read-only, no side effects |
+| PUT | Yes | No | Full replacement, repeated execution yields same result |
+| DELETE | Yes | No | Delete again returns 404/204 |
+| POST | **No** | No | Requires additional mechanism for idempotency (Idempotency-Key) |
+| PATCH | **No** | No | Depends on the specific operation |
+
+---
+
+## 3. DTO Design Standards
+
+### Layered Structure
+
+```mermaid
+graph LR
+    CLIENT["Client"] -->|"Request DTO"| CONTROLLER["Controller"]
+    CONTROLLER -->|"Command/Query"| SERVICE["Service"]
+    SERVICE -->|"Entity"| REPO["Repository"]
+    REPO -->|"Entity"| SERVICE
+    SERVICE -->|"Response DTO"| CONTROLLER
+    CONTROLLER -->|"Response DTO"| CLIENT
+
+    style CLIENT fill:#f5f5f5,stroke:#616161,color:#212121
+    style CONTROLLER fill:#e3f2fd,stroke:#1565c0,color:#0d47a1
+    style SERVICE fill:#e8eaf6,stroke:#283593,color:#1a237e
+    style REPO fill:#ffe0b2,stroke:#e65100,color:#bf360c
+```
+
+### DTO Design Principles
+- **Request DTO ≠ Entity**: Don't expose internal fields (e.g., id, createdAt are server-generated)
+- **Response DTO ≠ Entity**: Trim fields as needed, avoid over-exposure
+- **List DTO is slim**: List endpoints return summaries, detail endpoints return full data
+- **Flatten nesting**: Avoid > 3 levels of nesting, use ID references instead
+
+### Pagination Standard
+
+```typescript
+// Request
+interface PaginationQuery {
+  page?: number;       // Default 1
+  pageSize?: number;   // Default 20, max 100
+  sortBy?: string;
+  sortOrder?: 'asc' | 'desc';
+}
+
+// Response
+interface PaginatedResponse<T> {
+  data: T[];
+  pagination: {
+    page: number;
+    pageSize: number;
+    total: number;
+    totalPages: number;
+  };
+}
+```
+
+---
+
+## 4. Error Response Standardization
+
+### Unified Error Format
+
+```typescript
+interface ErrorResponse {
+  code: string;        // Business error code: "RESOURCE_NOT_FOUND"
+  message: string;     // Human-readable message
+  details?: Array<{    // Field-level errors (on validation failure)
+    field: string;
+    message: string;
+  }>;
+  traceId?: string;    // Distributed trace ID
+}
+```
+
+### HTTP Status Code Mapping
+
+```mermaid
+graph TB
+    ERR{"Error Type?"} -->|"Validation Failure"| E400["400 Bad Request<br>+ details array"]
+    ERR -->|"Not Authenticated"| E401["401 Unauthorized"]
+    ERR -->|"No Permission"| E403["403 Forbidden"]
+    ERR -->|"Resource Not Found"| E404["404 Not Found"]
+    ERR -->|"Business Rule Conflict"| E409["409 Conflict"]
+    ERR -->|"Too Many Requests"| E429["429 Too Many Requests"]
+    ERR -->|"Internal Server Error"| E500["500 Internal Server Error"]
+
+    style E400 fill:#fff9c4,stroke:#f9a825,color:#e65100
+    style E401 fill:#ffcdd2,stroke:#c62828,color:#b71c1c
+    style E403 fill:#ffcdd2,stroke:#c62828,color:#b71c1c
+    style E404 fill:#ffe0b2,stroke:#e65100,color:#bf360c
+    style E409 fill:#ffe0b2,stroke:#e65100,color:#bf360c
+    style E429 fill:#f3e5f5,stroke:#6a1b9a,color:#4a148c
+    style E500 fill:#ffcdd2,stroke:#c62828,color:#b71c1c
+```
+
+### Error Code Naming Conventions
+- All uppercase + underscore: `RESOURCE_NOT_FOUND`
+- Prefix by module: `USER_NOT_FOUND`, `ORDER_ALREADY_PAID`
+- Use semantic strings, not numeric codes
+
+---
+
+## 5. Versioning Strategy
+
+```mermaid
+graph TB
+    STRAT{"Version Strategy?"} -->|"Internal System/MVP"| NO_V["No Versioning<br>Evolve Directly"]
+    STRAT -->|"Public API"| URL_V["URL Versioning<br>/api/v1/resources"]
+    STRAT -->|"Between Microservices"| HEADER_V["Header Versioning<br>Accept: application/vnd.app.v2+json"]
+
+    NO_V --> COMPAT["Backward Compatibility:<br>Only add fields, never remove"]
+    URL_V --> COMPAT
+    HEADER_V --> COMPAT
+
+    style NO_V fill:#c8e6c9,stroke:#2e7d32,color:#1b5e20
+    style URL_V fill:#e3f2fd,stroke:#1565c0,color:#0d47a1
+    style HEADER_V fill:#f3e5f5,stroke:#6a1b9a,color:#4a148c
+    style COMPAT fill:#fff3e0,stroke:#e65100,color:#bf360c
+```
+
+### Deprecation Management
+- After a new version launches, keep the old version for at least **6 months**
+- Add `Deprecation: true` + `Sunset: <date>` response headers
+- Mark deprecation status in documentation
+
+---
+
+## 6. Output Checklist
+
+After design is complete, produce the following artifacts:
+
+| Artifact | Format | Notes |
+|--|--|--|
+| API endpoint list | Markdown table | Path, method, description, idempotent? |
+| Request/Response DTOs | TypeScript/Java interface definitions | DTOs for each endpoint |
+| Error code catalog | Markdown table | code + HTTP status + usage scenario |
+| OpenAPI specification | YAML | Importable into Swagger UI |
+| Contract test cases | Description | Consumer-Provider verification points |
+
+---
+
+## Reference
+
+For detailed specifications, see the `references/` directory:
+- `api-design-rules.md` — Detailed RESTful design rules and anti-patterns