ai-dev-requirements 0.1.2 → 0.1.4

package/skills/dev-workflow/references/service-transform.md

@@ -1,109 +1,109 @@
-# Service Layer Transform
-
-## Problem
-
-Frontend uses Mock data during development. On integration, backend fields differ in three ways:
-
-| Difference | Mock (Frontend) | Backend (Actual) |
-|-----------|----------------|-----------------|
-| Field name | `orderNo` | `order_id` |
-| Structure | `{ carrier: "UPS" }` | `{ carrier: { code: "UPS", name: "..." } }` |
-| Data format | `status: "Canceled"` | `status: 3` |
-
-## Solution: Transform in Service Layer
-
-**No separate `adapters/` directory.** Transform functions live inside service files. Components never change.
-
-```
-Component → FrontendType ← service function return type
-                ↑
-                │ transform
-                │
-          BackendType
-```
-
-**Core principle:** `FrontendType` is the contract between service and component layers. Components only know the contract.
-
-## File Structure
-
-```
-src/api/{module}/
-├── types.ts       # FrontendType + BackendType + transform functions
-├── mock.ts        # Mock data (dev phase)
-└── {module}.ts    # API functions (with .then(transform))
-```
-
-## Implementation Pattern
-
-```typescript
-// ① Frontend type (component contract, never changes)
-export interface OrderInfo {
-  orderId: string
-  carrier: string
-  amount: number
-  status: string
-}
-
-// ② Backend type (added during integration)
-interface BackendOrderInfo {
-  order_id: string
-  carrier_info: { code: string; name: string }
-  amount: string       // cents as string
-  status: number       // numeric enum
-}
-
-// ③ Transform function
-const STATUS_MAP: Record<number, string> = {
-  1: 'Pending', 2: 'Shipped', 3: 'Canceled',
-}
-
-function transformOrder(raw: BackendOrderInfo): OrderInfo {
-  return {
-    orderId: raw.order_id,                       // field rename
-    carrier: raw.carrier_info.code,              // flatten structure
-    amount: Number(raw.amount) / 100,            // format conversion
-    status: STATUS_MAP[raw.status] ?? 'Unknown', // enum mapping
-  }
-}
-
-// ④ Query: backend → frontend
-export function getOrderList(query: PageParams) {
-  return request<PageResponse<BackendOrderInfo>>({
-    url: '/api/order/page',
-    params: query,
-  }).then(res => ({
-    ...res,
-    rows: res.rows.map(transformOrder),
-  }))
-}
-
-// ⑤ Submit: frontend → backend
-function toBackendParams(form: OrderForm): BackendOrderForm {
-  return {
-    order_id: form.orderId,
-    amount: String(form.amount * 100),
-  }
-}
-
-export function createOrder(form: OrderForm) {
-  return request({
-    url: '/api/order/create',
-    method: 'post',
-    data: toBackendParams(form),
-  })
-}
-```
-
-## Integration Flow
-
-```
-Backend ready → Add BackendType → Write transform → Add .then(transform) → Components unchanged ✅
-```
-
-## When Components Must Change
-
-| Scenario | Handling |
-|----------|---------|
-| Backend adds field that UI needs to show | Extend FrontendType + component |
-| Business semantics change | Update transform + component logic |
-| Pagination structure differs (`rows` → `records`) | Handle in transform |
+# Service Layer Transform
+
+## Problem
+
+Frontend uses Mock data during development. On integration, backend fields differ in three ways:
+
+| Difference | Mock (Frontend) | Backend (Actual) |
+|-----------|----------------|-----------------|
+| Field name | `orderNo` | `order_id` |
+| Structure | `{ carrier: "UPS" }` | `{ carrier: { code: "UPS", name: "..." } }` |
+| Data format | `status: "Canceled"` | `status: 3` |
+
+## Solution: Transform in Service Layer
+
+**No separate `adapters/` directory.** Transform functions live inside service files. Components never change.
+
+```
+Component → FrontendType ← service function return type
+                ↑
+                │ transform
+                │
+          BackendType
+```
+
+**Core principle:** `FrontendType` is the contract between service and component layers. Components only know the contract.
+
+## File Structure
+
+```
+src/api/{module}/
+├── types.ts       # FrontendType + BackendType + transform functions
+├── mock.ts        # Mock data (dev phase)
+└── {module}.ts    # API functions (with .then(transform))
+```
+
+## Implementation Pattern
+
+```typescript
+// ① Frontend type (component contract, never changes)
+export interface OrderInfo {
+  orderId: string
+  carrier: string
+  amount: number
+  status: string
+}
+
+// ② Backend type (added during integration)
+interface BackendOrderInfo {
+  order_id: string
+  carrier_info: { code: string; name: string }
+  amount: string       // cents as string
+  status: number       // numeric enum
+}
+
+// ③ Transform function
+const STATUS_MAP: Record<number, string> = {
+  1: 'Pending', 2: 'Shipped', 3: 'Canceled',
+}
+
+function transformOrder(raw: BackendOrderInfo): OrderInfo {
+  return {
+    orderId: raw.order_id,                       // field rename
+    carrier: raw.carrier_info.code,              // flatten structure
+    amount: Number(raw.amount) / 100,            // format conversion
+    status: STATUS_MAP[raw.status] ?? 'Unknown', // enum mapping
+  }
+}
+
+// ④ Query: backend → frontend
+export function getOrderList(query: PageParams) {
+  return request<PageResponse<BackendOrderInfo>>({
+    url: '/api/order/page',
+    params: query,
+  }).then(res => ({
+    ...res,
+    rows: res.rows.map(transformOrder),
+  }))
+}
+
+// ⑤ Submit: frontend → backend
+function toBackendParams(form: OrderForm): BackendOrderForm {
+  return {
+    order_id: form.orderId,
+    amount: String(form.amount * 100),
+  }
+}
+
+export function createOrder(form: OrderForm) {
+  return request({
+    url: '/api/order/create',
+    method: 'post',
+    data: toBackendParams(form),
+  })
+}
+```
+
+## Integration Flow
+
+```
+Backend ready → Add BackendType → Write transform → Add .then(transform) → Components unchanged ✅
+```
+
+## When Components Must Change
+
+| Scenario | Handling |
+|----------|---------|
+| Backend adds field that UI needs to show | Extend FrontendType + component |
+| Business semantics change | Update transform + component logic |
+| Pagination structure differs (`rows` → `records`) | Handle in transform |

package/skills/dev-workflow/references/task-types.md

@@ -1,123 +1,123 @@
-# Task Types & Scheduling
-
-## Task Types
-
-| Type | ID | Strategy | Review Level | Description |
-|------|-----|---------|------------|------|
-| Code Development | `code:dev` | `isolated` | strict | Serial within module, parallel across modules |
-| Code Fix | `code:fix` | `isolated` | standard | Serial within file |
-| Code Refactor | `code:refactor` | `serial` | strict | Global serial, large impact |
-| Doc Writing | `doc:write` | `parallel` | light | Fully parallel |
-| Doc Translation | `doc:translate` | `parallel` | light | Fully parallel |
-| Research | `research` | `parallel` | light | Fully parallel, supports caching |
-| Data Processing | `data` | `isolated` | standard | Isolated by data source |
-| Testing | `test` | `parallel` | standard | Fully parallel |
-
-## Scheduling Strategies
-
-- **parallel** — Fully parallel, no restrictions (bounded by parallel_limit)
-- **isolated** — Group by isolation key; serial within group, parallel between groups
-- **serial** — Global lock, one task at a time
-
-## Max Parallelism: 5
-
-## Task Declaration Syntax
-
-```markdown
-## TaskGroup: <group name>
-
-### Meta
-- parallel_limit: 5
-- review_level: standard
-- on_failure: continue | stop
-
-### Tasks
-1. [code:dev] Implement auth module @isolated(auth/)
-2. [code:dev] Implement order module @isolated(order/)
-3. [doc:write] Write API docs
-4. [research] Research payment gateway @cache(7d)
-```
-
-| Element | Format | Description |
-|---------|--------|-------------|
-| Task type | `[type:subtype]` | Type identifier in brackets |
-| Isolation key | `@isolated(key)` | Grouping key for isolation |
-| Cache | `@cache(duration)` | Cache TTL for research tasks |
-| Dependency | `@depends(task_id)` | Prerequisite task dependency |
-
-## Fullstack Parallel Strategy
-
-```
-     ┌─────────────┐
-     │ API Contract │
-     └──────┬──────┘
-            ↓
-  ┌─────────┴─────────┐
-  ↓                   ↓
-┌─────────┐     ┌─────────┐
-│ Frontend │     │ Backend │
-│ (Mock)  │     │ (API)   │
-└────┬────┘     └────┬────┘
-     └────────┬──────┘
-              ↓
-       ┌─────────────┐
-       │ Integration  │
-       └─────────────┘
-```
-
-## Templates
-
-### Code Development
-```markdown
-## TaskGroup: [Feature Name]
-### Meta
-- parallel_limit: 5
-- review_level: strict
-- on_failure: continue
-### Tasks
-1. [code:dev] Implement [module] core logic @isolated([module]/)
-2. [code:dev] Implement [module] UI components @isolated([module]/)
-3. [code:dev] Implement [module] API layer @isolated([module]/api/)
-4. [test] Write [module] unit tests @isolated([module]/)
-```
-
-### Code Fix
-```markdown
-## TaskGroup: [Bug Description]
-### Meta
-- parallel_limit: 3
-- review_level: standard
-- on_failure: stop
-### Tasks
-1. [research] Root cause analysis @cache(1d)
-2. [code:fix] Fix [bug] @isolated([file_path])
-3. [test] Add regression tests @isolated([file_path])
-```
-
-### Code Refactor
-```markdown
-## TaskGroup: [Refactor Goal]
-### Meta
-- parallel_limit: 1
-- review_level: strict
-- on_failure: stop
-### Tasks
-1. [research] Analyze dependencies
-2. [code:refactor] Refactor core structure
-3. [code:fix] Fix type errors from refactoring
-4. [test] Run full test suite
-```
-
-### Research
-```markdown
-## TaskGroup: [Research Topic]
-### Meta
-- parallel_limit: 5
-- review_level: light
-- on_failure: continue
-### Tasks
-1. [research] Research [option A] @cache(7d)
-2. [research] Research [option B] @cache(7d)
-3. [research] Compare A and B @depends(1,2)
-4. [doc:write] Write conclusion document
-```
+# Task Types & Scheduling
+
+## Task Types
+
+| Type | ID | Strategy | Review Level | Description |
+|------|-----|---------|------------|------|
+| Code Development | `code:dev` | `isolated` | strict | Serial within module, parallel across modules |
+| Code Fix | `code:fix` | `isolated` | standard | Serial within file |
+| Code Refactor | `code:refactor` | `serial` | strict | Global serial, large impact |
+| Doc Writing | `doc:write` | `parallel` | light | Fully parallel |
+| Doc Translation | `doc:translate` | `parallel` | light | Fully parallel |
+| Research | `research` | `parallel` | light | Fully parallel, supports caching |
+| Data Processing | `data` | `isolated` | standard | Isolated by data source |
+| Testing | `test` | `parallel` | standard | Fully parallel |
+
+## Scheduling Strategies
+
+- **parallel** — Fully parallel, no restrictions (bounded by parallel_limit)
+- **isolated** — Group by isolation key; serial within group, parallel between groups
+- **serial** — Global lock, one task at a time
+
+## Max Parallelism: 5
+
+## Task Declaration Syntax
+
+```markdown
+## TaskGroup: <group name>
+
+### Meta
+- parallel_limit: 5
+- review_level: standard
+- on_failure: continue | stop
+
+### Tasks
+1. [code:dev] Implement auth module @isolated(auth/)
+2. [code:dev] Implement order module @isolated(order/)
+3. [doc:write] Write API docs
+4. [research] Research payment gateway @cache(7d)
+```
+
+| Element | Format | Description |
+|---------|--------|-------------|
+| Task type | `[type:subtype]` | Type identifier in brackets |
+| Isolation key | `@isolated(key)` | Grouping key for isolation |
+| Cache | `@cache(duration)` | Cache TTL for research tasks |
+| Dependency | `@depends(task_id)` | Prerequisite task dependency |
+
+## Fullstack Parallel Strategy
+
+```
+     ┌─────────────┐
+     │ API Contract │
+     └──────┬──────┘
+            ↓
+  ┌─────────┴─────────┐
+  ↓                   ↓
+┌─────────┐     ┌─────────┐
+│ Frontend │     │ Backend │
+│ (Mock)  │     │ (API)   │
+└────┬────┘     └────┬────┘
+     └────────┬──────┘
+              ↓
+       ┌─────────────┐
+       │ Integration  │
+       └─────────────┘
+```
+
+## Templates
+
+### Code Development
+```markdown
+## TaskGroup: [Feature Name]
+### Meta
+- parallel_limit: 5
+- review_level: strict
+- on_failure: continue
+### Tasks
+1. [code:dev] Implement [module] core logic @isolated([module]/)
+2. [code:dev] Implement [module] UI components @isolated([module]/)
+3. [code:dev] Implement [module] API layer @isolated([module]/api/)
+4. [test] Write [module] unit tests @isolated([module]/)
+```
+
+### Code Fix
+```markdown
+## TaskGroup: [Bug Description]
+### Meta
+- parallel_limit: 3
+- review_level: standard
+- on_failure: stop
+### Tasks
+1. [research] Root cause analysis @cache(1d)
+2. [code:fix] Fix [bug] @isolated([file_path])
+3. [test] Add regression tests @isolated([file_path])
+```
+
+### Code Refactor
+```markdown
+## TaskGroup: [Refactor Goal]
+### Meta
+- parallel_limit: 1
+- review_level: strict
+- on_failure: stop
+### Tasks
+1. [research] Analyze dependencies
+2. [code:refactor] Refactor core structure
+3. [code:fix] Fix type errors from refactoring
+4. [test] Run full test suite
+```
+
+### Research
+```markdown
+## TaskGroup: [Research Topic]
+### Meta
+- parallel_limit: 5
+- review_level: light
+- on_failure: continue
+### Tasks
+1. [research] Research [option A] @cache(7d)
+2. [research] Research [option B] @cache(7d)
+3. [research] Compare A and B @depends(1,2)
+4. [doc:write] Write conclusion document
+```

package/skills/dev-workflow/references/templates/code-dev-task.md

@@ -1,29 +1,29 @@
-# 代码开发任务模板
-
-```markdown
-## TaskGroup: [功能名称]
-
-### Meta
-- parallel_limit: 5
-- review_level: strict
-- on_failure: continue
-
-### Tasks
-1. [code:dev] 实现 [模块名] 核心逻辑 @isolated([module]/)
-2. [code:dev] 实现 [模块名] UI 组件 @isolated([module]/)
-3. [code:dev] 实现 [模块名] API 接口层 @isolated([module]/api/)
-4. [test] 编写 [模块名] 单元测试 @isolated([module]/)
-```
-
-## 使用说明
-
-- **并行策略**: `isolated` — 同模块内串行执行，跨模块并行
-- **Review 级别**: `strict` — 新功能需严格审查
-- **隔离键**: 使用模块路径作为隔离键，如 `@isolated(auth/)`
-
-## 注意事项
-
-- 同一模块的 UI 和逻辑建议串行（共享隔离键）
-- 不同模块可并行开发
-- 确保接口契约在实现前确定
-- 新功能必须附带测试任务
+# 代码开发任务模板
+
+```markdown
+## TaskGroup: [功能名称]
+
+### Meta
+- parallel_limit: 5
+- review_level: strict
+- on_failure: continue
+
+### Tasks
+1. [code:dev] 实现 [模块名] 核心逻辑 @isolated([module]/)
+2. [code:dev] 实现 [模块名] UI 组件 @isolated([module]/)
+3. [code:dev] 实现 [模块名] API 接口层 @isolated([module]/api/)
+4. [test] 编写 [模块名] 单元测试 @isolated([module]/)
+```
+
+## 使用说明
+
+- **并行策略**: `isolated` — 同模块内串行执行，跨模块并行
+- **Review 级别**: `strict` — 新功能需严格审查
+- **隔离键**: 使用模块路径作为隔离键，如 `@isolated(auth/)`
+
+## 注意事项
+
+- 同一模块的 UI 和逻辑建议串行（共享隔离键）
+- 不同模块可并行开发
+- 确保接口契约在实现前确定
+- 新功能必须附带测试任务

package/skills/dev-workflow/references/templates/code-fix-task.md

@@ -1,28 +1,28 @@
-# 代码修复任务模板
-
-```markdown
-## TaskGroup: [Bug 描述]
-
-### Meta
-- parallel_limit: 3
-- review_level: standard
-- on_failure: stop
-
-### Tasks
-1. [research] 定位 [Bug 描述] 根因 @cache(1d)
-2. [code:fix] 修复 [Bug 描述] @isolated([file_path])
-3. [test] 补充回归测试 @isolated([file_path])
-```
-
-## 使用说明
-
-- **并行策略**: `isolated` — 同文件串行
-- **Review 级别**: `standard`
-- **on_failure**: `stop` — 修复失败应立即停止
-
-## 注意事项
-
-- 先调研再修复，避免盲目改代码
-- 修复和测试使用相同隔离键（同文件）
-- 修复后必须补充回归测试
-- 如涉及多文件，每个文件用独立隔离键
+# 代码修复任务模板
+
+```markdown
+## TaskGroup: [Bug 描述]
+
+### Meta
+- parallel_limit: 3
+- review_level: standard
+- on_failure: stop
+
+### Tasks
+1. [research] 定位 [Bug 描述] 根因 @cache(1d)
+2. [code:fix] 修复 [Bug 描述] @isolated([file_path])
+3. [test] 补充回归测试 @isolated([file_path])
+```
+
+## 使用说明
+
+- **并行策略**: `isolated` — 同文件串行
+- **Review 级别**: `standard`
+- **on_failure**: `stop` — 修复失败应立即停止
+
+## 注意事项
+
+- 先调研再修复，避免盲目改代码
+- 修复和测试使用相同隔离键（同文件）
+- 修复后必须补充回归测试
+- 如涉及多文件，每个文件用独立隔离键

package/skills/dev-workflow/references/templates/code-refactor-task.md

@@ -1,30 +1,30 @@
-# 代码重构任务模板
-
-```markdown
-## TaskGroup: [重构目标]
-
-### Meta
-- parallel_limit: 1
-- review_level: strict
-- on_failure: stop
-
-### Tasks
-1. [research] 分析当前 [模块] 的问题和依赖关系
-2. [code:refactor] 重构 [模块] 核心结构
-3. [code:fix] 修复重构引入的类型错误
-4. [test] 运行全量测试确认无回归
-```
-
-## 使用说明
-
-- **并行策略**: `serial` — 强制串行，影响范围大
-- **Review 级别**: `strict` — 重构需严格审查
-- **on_failure**: `stop` — 重构出错应立即停止
-
-## 注意事项
-
-- 重构任务必须串行执行，避免冲突
-- 先分析依赖关系，确定影响范围
-- 重构后必须运行全量测试
-- 大范围重构建议拆分为多个小步骤
-- 每步重构后验证编译通过再继续
+# 代码重构任务模板
+
+```markdown
+## TaskGroup: [重构目标]
+
+### Meta
+- parallel_limit: 1
+- review_level: strict
+- on_failure: stop
+
+### Tasks
+1. [research] 分析当前 [模块] 的问题和依赖关系
+2. [code:refactor] 重构 [模块] 核心结构
+3. [code:fix] 修复重构引入的类型错误
+4. [test] 运行全量测试确认无回归
+```
+
+## 使用说明
+
+- **并行策略**: `serial` — 强制串行，影响范围大
+- **Review 级别**: `strict` — 重构需严格审查
+- **on_failure**: `stop` — 重构出错应立即停止
+
+## 注意事项
+
+- 重构任务必须串行执行，避免冲突
+- 先分析依赖关系，确定影响范围
+- 重构后必须运行全量测试
+- 大范围重构建议拆分为多个小步骤
+- 每步重构后验证编译通过再继续