ironweave 1.0.0

package/README_CN.md

@@ -0,0 +1,248 @@
+<p align="center">
+  <h1 align="center">Ironweave</h1>
+  <p align="center">
+    面向 AI 编程 Agent 的技能框架与软件开发方法论。
+  </p>
+  <p align="center">
+    <a href="./README.md">English</a> · <a href="https://skills.sh">skills.sh</a> · <a href="#安装">安装</a> · <a href="./LICENSE">MIT 许可证</a>
+  </p>
+</p>
+
+---
+
+Ironweave 是一套完整的软件开发工作流，由一组可自由组合的 **技能（Skills）** 构建而成。它不只是写代码 — 它会先理解你要构建什么，制定计划，将工作拆分为切片，然后通过内置质量卡点逐一执行每个切片。而且这些技能会自动触发，你不需要做任何特殊操作。你的 Agent 拥有 Ironweave 就够了。
+
+## 工作原理
+
+从你给 Agent 一个任务开始，**orchestrator** 技能自动激活：
+
+1. **感知上下文** — 通过 `project-context` 检测项目类型（新项目、新功能、Bug 修复、重构）
+2. **评估难度** — 通过 `task-difficulty` 进行 1-10 评分，选择变体（lite / standard / plus）
+3. **澄清需求** — 对于模糊或复杂的任务，使用 `requirement-qa` 和 `brainstorm` 在编码前明确范围
+4. **范围切片** — 将大任务按模块依赖拆分为有序切片，每个切片可独立交付
+5. **选择路径** — 从四条路径（A: 新项目、B: 新功能、C: Bug 修复、D: 重构）中选择，使用对应的技能链
+6. **逐切片执行** — 每个切片经历 Plan → Execute → Validate → Deliver，每个阶段转换处都有质量卡点
+
+如果验证失败，工作会**回流**到正确的层级 — 代码级问题回到 Execute，设计级回到 Plan，需求级回到 scope。不会盲目重试。
+
+## 工作流
+
+```
+用户请求
+    │
+    ▼
+  上下文感知 → 难度评估 → 澄清（如需） → 范围切片
+    │
+    ▼
+  ┌──────────────────────────────────┐
+  │  逐切片循环                       │
+  │                                  │
+  │  路径选择（A/B/C/D）              │
+  │       │                          │
+  │       ▼                          │
+  │  Plan ──── 卡点 ──── Execute     │
+  │                        │         │
+  │                      卡点        │
+  │                        │         │
+  │                    Validate      │
+  │                        │         │
+  │                    Deliver       │
+  └──────────────────────────────────┘
+    │
+    ▼
+  完成（或进入下一切片）
+```
+
+### 三级变体
+
+| 难度 | 变体 | 差异 |
+|------|------|------|
+| L1-L2（简单） | **lite** | 跳过可选技能，快速自检，不强制 TDD |
+| L3（中等） | **standard** | 完整技能链，强制 TDD，标准审查 |
+| L4-L5（困难） | **plus** | SubAgent 隔离执行，严格 TDD，两阶段审查，并行策略 |
+
+## 技能库
+
+**编排**
+
+- `orchestrator` — 全生命周期流程编排器（路由、质量卡点、回流、切片迭代）
+
+**需求与设计**
+
+- `requirement-qa` — 多轮 QA 引导用户明确需求
+- `brainstorm` — 多视角头脑风暴，专家 SubAgent 独立分析
+- `spec-writing` — 结构化功能需求文档撰写
+- `tech-stack` — 全栈技术选型与决策文档
+
+**架构与工程**
+
+- `engineering-principles` — 上下文感知的工程原则匹配器（SOLID、DDD、TDD、设计模式）
+- `api-contract-design` — RESTful/GraphQL API 契约、DTO、OpenAPI
+- `error-handling-strategy` — 异常体系、错误码、重试、熔断、降级
+- `performance-arch-design` — 缓存分层、异步处理、索引策略、限流
+- `observability-design` — 链路追踪、结构化日志、指标、告警
+
+**实现**
+
+- `code-scaffold` — 从领域模型 + 设计文档生成项目代码骨架
+- `implementation-complexity-analysis` — 技术风险识别、复杂度分解
+- `integration-test-design` — TestContainers、契约测试、Mock 策略
+
+**元技能**
+
+- `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 --skill orchestrator --skill brainstorm
+
+# 列出可用技能
+npx skills add YuluoY/ironware --list
+```
+
+支持 **40+ 个 Agent**：Claude Code、GitHub Copilot、Cursor、Codex、Windsurf、Cline、OpenCode、Gemini CLI、Trae、CodeBuddy 等。
+
+### 各 Agent 手动安装
+
+<details>
+<summary><b>Claude Code</b></summary>
+
+```bash
+git clone https://github.com/YuluoY/ironware.git ~/.claude/ironweave
+mkdir -p ~/.claude/skills
+ln -s ~/.claude/ironweave/skills ~/.claude/skills/ironweave
+```
+
+也可使用 Claude 插件系统 — Ironweave 自带 `.claude-plugin/plugin.json`。
+
+</details>
+
+<details>
+<summary><b>VS Code GitHub Copilot</b></summary>
+
+将 `skills/` 目录复制到你的项目中，然后在 `.github/copilot-instructions.md` 中添加：
+
+```markdown
+The orchestrator skill (skills/orchestrator/SKILL.md) is the main entry point.
+For any development task, start by reading it.
+```
+
+或直接克隆 Ironweave — 已预配置 `.github/copilot-instructions.md`。
+
+</details>
+
+<details>
+<summary><b>Cursor</b></summary>
+
+```bash
+git clone https://github.com/YuluoY/ironware.git
+```
+
+Ironweave 自带 `.cursorrules` 和 `.cursor-plugin/plugin.json`，可自动发现。
+
+</details>
+
+<details>
+<summary><b>Codex (OpenAI)</b></summary>
+
+```bash
+git clone https://github.com/YuluoY/ironware.git ~/.codex/ironweave
+mkdir -p ~/.agents/skills
+ln -s ~/.codex/ironweave/skills ~/.agents/skills/ironweave
+```
+
+详见 [.codex/INSTALL.md](./.codex/INSTALL.md)。
+
+</details>
+
+<details>
+<summary><b>OpenCode</b></summary>
+
+在 `opencode.json` 中添加：
+
+```json
+{
+  "plugin": ["ironweave@git+https://github.com/YuluoY/ironware.git"]
+}
+```
+
+详见 [.opencode/INSTALL.md](./.opencode/INSTALL.md)。
+
+</details>
+
+<details>
+<summary><b>Windsurf / Cline / Gemini CLI</b></summary>
+
+Ironweave 分别自带 `.windsurfrules`、`.clinerules`、`GEMINI.md`。克隆仓库后 Agent 自动发现规则。
+
+```bash
+git clone https://github.com/YuluoY/ironware.git
+```
+
+</details>
+
+<details>
+<summary><b>Trae / CodeBuddy / 其他 Agent</b></summary>
+
+将 `skills/` 目录复制到你的项目中，然后在 Agent 的自定义指令中添加：
+
+> The orchestrator skill (`skills/orchestrator/SKILL.md`) is the main entry point. For any development task, start by reading it. All skills are in `skills/`, each with a `SKILL.md` containing instructions.
+
+</details>
+
+## 项目结构
+
+```
+ironweave/
+├── skills/
+│   ├── orchestrator/              # 流程编排器
+│   │   ├── SKILL.md              # 编排器逻辑
+│   │   └── references/           # 方法论文档
+│   ├── brainstorm/
+│   ├── spec-writing/
+│   ├── code-scaffold/
+│   ├── ...                        # 另外 16 个技能
+│   └── skill-creator/
+├── CLAUDE.md                      # Claude Code 指令
+├── AGENTS.md                      # Codex 指令
+├── GEMINI.md                      # Gemini CLI 指令
+├── .github/copilot-instructions.md  # VS Code Copilot
+├── .cursorrules                   # Cursor 规则
+├── .windsurfrules                 # Windsurf 规则
+├── .clinerules                    # Cline 规则
+├── .claude-plugin/plugin.json     # Claude 插件清单
+├── .cursor-plugin/plugin.json     # Cursor 插件清单
+├── .codex/INSTALL.md              # Codex 安装指南
+├── .opencode/INSTALL.md           # OpenCode 安装指南
+├── README.md
+├── README_CN.md
+├── CONTRIBUTING.md
+├── LICENSE
+└── package.json
+```
+
+## 设计理念
+
+- **自适应路由** 而非线性工作流 — 不同任务类型需要不同的流程
+- **质量卡点 + 回流** 而非通过/失败 — 失败回流到正确的阶段
+- **执行前范围切片** — 大任务拆分为有序切片，每个独立可交付
+- **开销随复杂度缩放** — 简单任务保持快速（lite），困难任务获得完整保障（plus）
+- **技能即方法论** — 每个技能编码了决策树，不只是模板
+
+## 贡献
+
+请参阅 [CONTRIBUTING.md](./CONTRIBUTING.md)。技能直接存放在本仓库中。创建和测试新技能请参考 `skills/skill-creator`。
+
+## 许可证
+
+[MIT](./LICENSE) © Ironweave Contributors

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "ironweave",
+  "version": "1.0.0",
+  "description": "Agentic skills framework for AI coding agents — orchestrated workflows with adaptive routing, quality gates, and 17 composable skills.",
+  "keywords": [
+    "agent-skills",
+    "ai-coding",
+    "flow-orchestrator",
+    "skills",
+    "claude-code",
+    "copilot",
+    "cursor",
+    "codex",
+    "tdd",
+    "software-engineering",
+    "orchestrator",
+    "quality-gates",
+    "skills-sh"
+  ],
+  "homepage": "https://github.com/YuluoY/ironware",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/YuluoY/ironware.git"
+  },
+  "bugs": {
+    "url": "https://github.com/YuluoY/ironware/issues"
+  },
+  "license": "MIT",
+  "author": "YuluoY",
+  "files": [
+    "skills/",
+    "CLAUDE.md",
+    "AGENTS.md",
+    "GEMINI.md",
+    ".cursorrules",
+    ".windsurfrules",
+    ".clinerules",
+    ".github/",
+    ".claude-plugin/",
+    ".cursor-plugin/",
+    ".codex/",
+    ".opencode/",
+    "README.md",
+    "README_CN.md",
+    "CONTRIBUTING.md",
+    "LICENSE"
+  ]
+}

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

@@ -0,0 +1,227 @@
+---
+name: api-contract-design
+description: >-
+  API 接口契约与类型系统的详细设计工具。从领域模型和需求文档出发，生成 RESTful/GraphQL API 端点定义、Request/Response DTO 结构、错误响应标准、OpenAPI 规范以及类型代码骨架。
+  务必在以下场景使用本 skill：用户需要设计 API 接口、定义数据传输对象(DTO)、编写接口文档、制定错误码规范，或者用户说"设计接口"、"定义 API"、"写接口契约"、"DTO 设计"、"接口规范"、"错误码"、"OpenAPI"、"Swagger"。
+  当用户的任务涉及从业务模型到技术接口的转化时使用本 skill。
+---
+
+# API 契约设计
+
+从领域模型 + 需求文档出发，产出完整的 API 接口契约。所有设计决策以 Mermaid 流程图表达。
+
+---
+
+## 设计流程
+
+```mermaid
+graph TB
+    INPUT["领域模型 + 需求文档"] --> RESOURCE["资源识别<br>名词提取"]
+    RESOURCE --> ENDPOINT["端点设计<br>RESTful 映射"]
+    ENDPOINT --> DTO["DTO 结构<br>Request/Response"]
+    DTO --> ERROR["错误响应<br>标准化设计"]
+    ERROR --> VERSION["版本策略"]
+    VERSION --> OUTPUT["输出 OpenAPI 规范"]
+
+    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. 资源识别
+
+从领域模型中提取 API 资源：
+
+| 领域概念 | API 资源 | 说明 |
+|--|--|--|
+| 聚合根 | 顶级资源 `/resources` | 直接暴露为 RESTful 资源 |
+| 实体(非聚合根) | 子资源 `/resources/{id}/sub` | 通过父资源访问 |
+| 值对象 | 内嵌在 DTO 中 | 不单独暴露 |
+| 领域服务 | 动作端点 `/resources/{id}/actions/do` | 非 CRUD 操作 |
+
+---
+
+## 2. 端点设计规范
+
+### RESTful 映射规则
+
+```mermaid
+graph LR
+    CRUD{"操作类型?"} -->|"创建"| POST["POST /resources"]
+    CRUD -->|"读取单个"| GET_ONE["GET /resources/{id}"]
+    CRUD -->|"读取列表"| GET_LIST["GET /resources?filter"]
+    CRUD -->|"全量更新"| PUT["PUT /resources/{id}"]
+    CRUD -->|"部分更新"| PATCH["PATCH /resources/{id}"]
+    CRUD -->|"删除"| DELETE["DELETE /resources/{id}"]
+    CRUD -->|"非 CRUD 动作"| 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
+```
+
+### 命名规范
+- 资源名：复数形式（`/users` 非 `/user`）
+- 路径：kebab-case（`/migration-tasks`）
+- 查询参数：camelCase（`?pageSize=20&sortBy=createdAt`）
+- 嵌套不超过 2 层：`/resources/{id}/sub-resources/{subId}`
+
+### 幂等性要求
+
+| 方法 | 幂等? | 安全? | 说明 |
+|--|--|--|--|
+| GET | 是 | 是 | 只读，无副作用 |
+| PUT | 是 | 否 | 全量替换，重复执行结果相同 |
+| DELETE | 是 | 否 | 删除后再删返回 404/204 |
+| POST | **否** | 否 | 需要额外机制保证幂等（Idempotency-Key） |
+| PATCH | **否** | 否 | 视具体操作 |
+
+---
+
+## 3. DTO 设计规范
+
+### 分层结构
+
+```mermaid
+graph LR
+    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 设计原则
+- **Request DTO ≠ Entity**：不暴露内部字段（如 id、createdAt 由服务端生成）
+- **Response DTO ≠ Entity**：按需裁剪字段，避免过度暴露
+- **列表 DTO 精简**：列表接口返回摘要，详情接口返回完整
+- **嵌套扁平化**：避免 > 3 层嵌套，可用 ID 引用代替
+
+### 分页标准
+
+```typescript
+// 请求
+interface PaginationQuery {
+  page?: number;       // 默认 1
+  pageSize?: number;   // 默认 20，最大 100
+  sortBy?: string;
+  sortOrder?: 'asc' | 'desc';
+}
+
+// 响应
+interface PaginatedResponse<T> {
+  data: T[];
+  pagination: {
+    page: number;
+    pageSize: number;
+    total: number;
+    totalPages: number;
+  };
+}
+```
+
+---
+
+## 4. 错误响应标准化
+
+### 统一错误格式
+
+```typescript
+interface ErrorResponse {
+  code: string;        // 业务错误码: "RESOURCE_NOT_FOUND"
+  message: string;     // 人类可读信息
+  details?: Array<{    // 字段级错误（验证失败时）
+    field: string;
+    message: string;
+  }>;
+  traceId?: string;    // 链路追踪 ID
+}
+```
+
+### HTTP 状态码映射
+
+```mermaid
+graph TB
+    ERR{"错误类型?"} -->|"参数校验失败"| E400["400 Bad Request<br>+ details 数组"]
+    ERR -->|"未认证"| E401["401 Unauthorized"]
+    ERR -->|"无权限"| E403["403 Forbidden"]
+    ERR -->|"资源不存在"| E404["404 Not Found"]
+    ERR -->|"业务规则冲突"| E409["409 Conflict"]
+    ERR -->|"请求过多"| E429["429 Too Many Requests"]
+    ERR -->|"服务器内部错误"| 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
+```
+
+### 错误码命名规范
+- 全大写 + 下划线：`RESOURCE_NOT_FOUND`
+- 前缀按模块：`USER_NOT_FOUND`、`ORDER_ALREADY_PAID`
+- 不用数字编码，用语义化字符串
+
+---
+
+## 5. 版本管理策略
+
+```mermaid
+graph TB
+    STRAT{"版本策略选择"} -->|"内部系统/MVP"| NO_V["不版本化<br>直接演进"]
+    STRAT -->|"公开 API"| URL_V["URL 版本<br>/api/v1/resources"]
+    STRAT -->|"微服务间"| HEADER_V["Header 版本<br>Accept: application/vnd.app.v2+json"]
+
+    NO_V --> COMPAT["向后兼容原则:<br>只加字段不删字段"]
+    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
+```
+
+### 弃用期管理
+- 新版本上线后，旧版本至少保留 **6 个月**
+- 响应头添加 `Deprecation: true` + `Sunset: <date>`
+- 文档标注弃用状态
+
+---
+
+## 6. 输出清单
+
+设计完成后产出以下制品：
+
+| 制品 | 格式 | 说明 |
+|--|--|--|
+| API 端点清单 | Markdown 表格 | 路径、方法、说明、是否幂等 |
+| Request/Response DTO | TypeScript/Java 接口定义 | 每个端点的 DTO |
+| 错误码目录 | Markdown 表格 | code + HTTP status + 使用场景 |
+| OpenAPI 规范 | YAML | 可导入 Swagger UI |
+| 契约测试用例 | 描述 | Consumer-Provider 验证点 |
+
+---
+
+## 参考
+
+详细规范参见 `references/` 目录：
+- `api-design-rules.md` — RESTful 设计详细规则与反模式

package/skills/api-contract-design/references/api-design-rules.md

@@ -0,0 +1,106 @@
+# RESTful API 设计规则与反模式
+
+## 命名反模式
+
+| 反模式 | 正确写法 | 原因 |
+|--|--|--|
+| `/getUsers` | `GET /users` | 动词在方法中，不在路径中 |
+| `/user/list` | `GET /users` | 用复数名词 |
+| `/user_roles` | `/user-roles` | 路径用 kebab-case |
+| `/Users` | `/users` | 路径全小写 |
+| `/users/{id}/tasks/{taskId}/comments/{commentId}/replies` | 最多 2 层嵌套 | 过深嵌套降低可用性 |
+
+## 查询参数标准
+
+### 过滤
+```
+GET /users?status=active&role=admin
+GET /orders?createdAfter=2026-01-01&createdBefore=2026-12-31
+```
+
+### 排序
+```
+GET /users?sortBy=createdAt&sortOrder=desc
+GET /users?sort=-createdAt,+name  (简洁风格)
+```
+
+### 搜索
+```
+GET /users?q=keyword  (全文搜索)
+GET /users?name.contains=john  (字段搜索)
+```
+
+### 字段选择
+```
+GET /users?fields=id,name,email  (精简返回)
+```
+
+## 批量操作设计
+
+### 批量创建
+```
+POST /users/batch
+Body: { items: [...] }
+Response: { succeeded: [...], failed: [...] }
+```
+
+### 批量删除
+```
+DELETE /users/batch
+Body: { ids: [1, 2, 3] }
+```
+
+### 批量操作限制
+- 单次最大条目：**100**
+- 返回逐条结果（部分成功时返回 207 Multi-Status）
+
+## Idempotency-Key 机制
+
+对非幂等操作（POST），客户端发送 `Idempotency-Key` 请求头：
+
+```
+POST /orders
+Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
+```
+
+服务端流程：
+1. 收到请求 → 检查 Key 是否已处理
+2. 已处理 → 返回缓存结果（不重复执行）
+3. 未处理 → 执行 → 存储结果 → 返回
+4. Key 过期时间：**24 小时**
+
+## HATEOAS（可选）
+
+对公开 API 可添加超媒体链接：
+
+```json
+{
+  "id": 1,
+  "name": "Task 1",
+  "status": "pending",
+  "_links": {
+    "self": { "href": "/tasks/1" },
+    "approve": { "href": "/tasks/1/actions/approve", "method": "POST" },
+    "collection": { "href": "/tasks" }
+  }
+}
+```
+
+## 速率限制响应头
+
+```
+X-RateLimit-Limit: 100        # 窗口内最大请求数
+X-RateLimit-Remaining: 87     # 剩余可用次数
+X-RateLimit-Reset: 1619472000 # 窗口重置时间（Unix timestamp）
+```
+
+超出限制时返回 429 + `Retry-After` 头。
+
+## 安全要求
+
+- **认证**：Bearer Token（JWT / OAuth2）
+- **CORS**：明确列出允许的 Origin，不用 `*`
+- **输入验证**：所有输入在 Controller 层验证
+- **输出过滤**：不返回内部字段（数据库 ID 策略、密码哈希等）
+- **SQL 注入防护**：查询参数不拼接 SQL
+- **请求大小限制**：Body 最大 1MB（文件上传除外）