@scemoon/cdh 1.0.8 → 1.0.9-beta.1

package/ai-dlc-skill/phases/plan/lifecycle.md

@@ -0,0 +1,260 @@
+# AI-DLC Phase 2: Plan (规划)
+
+Design the solution and decompose work into tracked, dependency-ordered units, including cross-component edges.
+
+## Goal
+
+Translate approved specifications into a concrete technical plan that can be executed unit by unit, with explicit cross-component dependencies and contract references.
+
+## Flow
+
+```
+Approved Spec + BDD Features (per-component + cross-stack)
+  │
+  ▼
+SDD: Design Doc
+  - architecture (per component)
+  - data model
+  - API contract (references INT-FR-*)
+  - state machine
+  - integration section (cross-component flow)
+  │
+  ▼
+SDD: Task Decomposition (units with DAG, including cross-component edges)
+  │
+  ▼
+TDD: Test Plan (per scenario, written before implementation)
+  - unit / integration / e2e / cross-stack layer
+  │
+  ▼
+INT: Contract plan (which contracts change, version impact)
+  │
+  ▼
+Gate: Human review → approved or revise
+```
+
+## SDD — Design Document (multi-component aware)
+
+A multi-component design doc is organized by **component sections** plus an **integration section**.
+
+```markdown
+## Design — CHG-{{id}}
+
+**Affects:** [{{components}}]
+**Contracts touched:** {{list or "none"}}
+
+### Component: backend (BE-FR-*)
+- Architecture: {{serverless / container / ...}}
+- Data model: {{tables / collections}}
+- API surface: {{references INT-FR-* contract}}
+- State machine: {{...}}
+
+### Component: web (WEB-FR-*)
+- Architecture: {{SPA / SSR}}
+- Routes: {{...}}
+- Data flow: {{uses aidlc/packages/shared generated from INT-FR-001}}
+
+### Component: native (NATIVE-FR-*)
+- Architecture: {{native architecture}}
+- Data flow: {{uses aidlc/packages/shared generated from INT-FR-*}}
+
+### Component: desktop (DESKTOP-FR-*)
+- Architecture: {{desktop architecture}}
+- Data flow: {{uses aidlc/packages/shared generated from INT-FR-*}}
+
+### Component: wxa (WXA-FR-*)
+- Architecture: {{WeChat Mini Program}}
+- Data flow: {{uses aidlc/packages/shared generated from INT-FR-*}}
+
+### Component: mya (MYA-FR-*)
+- Architecture: {{Mini Program}}
+- Data flow: {{uses aidlc/packages/shared generated from INT-FR-*}}
+
+### Component: tta (TTA-FR-*)
+- Architecture: {{TikTok Mini Program}}
+- Data flow: {{uses aidlc/packages/shared generated from INT-FR-*}}
+
+### Integration
+- Flow: {{web → backend → DB; or app → backend → event → ...}}
+- Contract refs: INT-FR-001, INT-FR-002
+- Failure modes: {{timeout, retry, fallback}}
+- Backward compat: {{additive / breaking → migration}}
+```
+
+### Data Model
+
+| Field | Type | Constraints |
+|-------|------|-------------|
+| id | UUID | PK |
+| email | string | UNIQUE, NOT NULL |
+| password_hash | string | NOT NULL |
+
+### API Contract
+
+| Method | Path | INT FR | Provider | Consumer |
+|--------|------|--------|----------|----------|
+| POST | /auth/login | INT-FR-001 | BE-FR-001 | WEB-FR-001, NATIVE-FR-001, DESKTOP-FR-001, WXA-FR-001, MYA-FR-001, TTA-FR-001 |
+
+### State Machine
+
+```
+ANONYMOUS → LOGGED_IN → SESSION_EXPIRED
+              ↓
+          LOGGED_OUT
+```
+
+## SDD — Task Decomposition with DAG (multi-component)
+
+Tasks MUST include cross-component edges. A task that produces or consumes a contract depends on the corresponding `INT-FR-*` task.
+
+```mermaid
+graph TD
+  INT1[INT-FR-001: define /auth/login contract]
+  BE1[BE-FR-001 unit-1: DB schema + models]
+  BE2[BE-FR-001 unit-2: login endpoint]
+  WEB1[WEB-FR-001 unit-1: login form + API client]
+  WEB2[WEB-FR-001 unit-2: token storage + redirect]
+  CS1[INT-FR-001 cross-stack: e2e login flow]
+
+  INT1 --> BE2
+  INT1 --> WEB1
+  BE1 --> BE2
+  BE2 --> CS1
+  WEB1 --> CS1
+  WEB2 --> CS1
+```
+
+```yaml
+units:
+  - id: int-contract-1
+    fr: INT-FR-001
+    affects: [contracts]
+    depends_on: []
+    deliverables: [aidlc/contracts/api/auth.yaml]
+  - id: be-unit-1
+    fr: BE-FR-001
+    affects: [backend]
+    depends_on: []
+    scenarios: []
+  - id: be-unit-2
+    fr: BE-FR-001
+    affects: [backend]
+    depends_on: [int-contract-1, be-unit-1]
+    scenarios: ["BE-FR-001 @positive", "BE-FR-001 @negative"]
+  - id: web-unit-1
+    fr: WEB-FR-001
+    affects: [web]
+    depends_on: [int-contract-1]
+    scenarios: ["WEB-FR-001 @positive", "WEB-FR-001 @negative"]
+  - id: cross-stack-1
+    fr: INT-FR-001
+    affects: [web, backend]
+    depends_on: [be-unit-2, web-unit-1]
+    layer: cross-stack
+    scenarios: ["INT-FR-001 @positive", "INT-FR-001 @negative", "INT-FR-001 @edge"]
+```
+
+## TDD — Test Plan (per scenario, per layer)
+
+Each scenario gets a test plan that names the **layer** it runs at.
+
+```markdown
+## BE-FR-001 @positive: Login API success
+Layer: integration
+Test cases:
+  1. test_login_valid_credentials_returns_jwt
+  2. test_login_sets_expiry_3600
+
+## WEB-FR-001 @positive: Login form happy path
+Layer: e2e
+Test cases:
+  1. test_login_form_submits_and_redirects
+
+## INT-FR-001 @positive: Full web→backend login flow
+Layer: cross-stack
+Test cases:
+  1. test_web_login_e2e_against_preview_url
+```
+
+## INT — Contract Plan
+
+For each contract change, list:
+- Old version, new version
+- Breaking? (yes / no) → if yes, plan migration in `aidlc/contracts/CHANGELOG.md`
+- Consumers affected (which components will pull the new shared types)
+- Backward-compat strategy (additive vs. deprecate-then-remove)
+
+## Artifacts
+
+| Artifact | Location | Purpose |
+|----------|----------|---------|
+| Design doc | `aidlc/openspec/changes/{id}/design.md` | Per-component + integration |
+| Task list | `aidlc/openspec/changes/{id}/task-list.md` | DAG with cross-component edges |
+| Test plan | Embedded in task-list or separate | Per-scenario, per-layer |
+| Contract plan | `aidlc/openspec/changes/{id}/contract-diff.md` placeholder | Filled in Verify |
+
+## Gate
+
+**Before advancing to Verify phase:**
+- [ ] Design doc has per-component sections + integration section
+- [ ] Tasks decomposed with explicit dependency DAG (including cross-component edges)
+- [ ] `INT-FR-*` tasks precede the consuming per-component tasks
+- [ ] Test plans name the layer (`unit` / `integration` / `e2e` / `cross-stack`) per scenario
+- [ ] Contract plan identifies breaking vs. additive
+- [ ] Human reviewed and approved
+
+## Design System Integration
+
+For UI-intensive components (web/native/desktop/wxa/mya/tta), the design doc MUST include:
+
+### Design Tokens Output
+```markdown
+### Design Tokens (WEB-FR-001)
+| Token | Value |
+|-------|-------|
+| --color-primary | #3B82F6 |
+| --space-4 | 16px |
+| --radius-md | 6px |
+```
+
+### Component Hierarchy
+```markdown
+### Component Hierarchy (WEB-FR-001)
+- Atom: Button, Input, Badge, Icon
+- Molecule: SearchBar, FormField, CardHeader
+- Organism: DataTable, Header, FilterPanel
+```
+
+### Platform UI Spec Reference
+```markdown
+### Platform Compliance (WEB-FR-001)
+- Web: Responsive (sm/md/lg/xl) per platform_ui/web.md
+- Native: SafeArea per platform_ui/native.md
+- WXA: Vant Weapp per platform_ui/wxa.md
+```
+
+### Accessibility Checklist
+```markdown
+### Accessibility (WEB-FR-001)
+- [ ] Focus ring visible on interactive elements
+- [ ] Icon buttons have aria-label
+- [ ] Color contrast ≥ 4.5:1 (AA)
+- [ ] Keyboard navigation functional
+```
+
+## Design System Reference Files
+
+| 规范 | 路径 |
+|------|------|
+| Design Tokens | `phases/plan/design_system/design_tokens.md` |
+| Atomic Design | `phases/plan/design_system/atomic_design.md` |
+| Component Spec | `phases/plan/design_system/component_spec.md` |
+| Accessibility | `phases/plan/design_system/accessibility.md` |
+| Theme System | `phases/plan/design_system/theme_system.md` |
+| Iconography | `phases/plan/design_system/iconography.md` |
+| Web UI | `phases/plan/design_system/platform_ui/web.md` |
+| Native UI | `phases/plan/design_system/platform_ui/native.md` |
+| Desktop UI | `phases/plan/design_system/platform_ui/desktop.md` |
+| WXA UI | `phases/plan/design_system/platform_ui/wxa.md` |
+| MYA UI | `phases/plan/design_system/platform_ui/mya.md` |
+| TTA UI | `phases/plan/design_system/platform_ui/tta.md` |

package/ai-dlc-skill/phases/plan/prompt.md

@@ -0,0 +1,75 @@
+# Plan Phase Agent Prompt
+
+你是一个 AI-DLC Plan Phase Agent。
+由 Master Agent 委派处理方案设计。
+
+## 输入
+- `{spec_dir}/spec-delta.md`
+- BDD feature 文件
+
+## 路径约定
+
+所有产物路径遵循 `aidlc/CONFIG.md` 中的变量定义。关键路径：
+- Design Doc: `{spec_dir}/design.md`
+- Task List: `{spec_dir}/task-list.md`
+- Contract Diff: `{spec_dir}/contract-diff.md`
+
+## 任务
+
+1. **SDD: Design Doc**
+   - 在 `{spec_dir}/design.md` 输出
+   - 包含：架构图（Mermaid）、数据模型、API 表、状态机
+   - 每组件独立 section + 集成 section
+
+2. **SDD: Task Decomposition**
+   - 在 `{spec_dir}/task-list.md` 输出
+   - YAML 格式，unit 带 `depends_on` DAG
+   - 跨组件 task 显示声明 `depends_on` 关系
+
+3. **TDD: Test Plan**
+   - 每个 BDD scenario 对应最少一个测试 case
+   - 标注 layer: unit / integration / e2e / cross-stack / contract
+
+4. **Contract Plan**
+   - 标注版本影响：additive / breaking
+   - 如需 breaking change 标记为 human-approval 阻塞
+
+## 输出产物
+- `{spec_dir}/design.md`
+- `{spec_dir}/task-list.md`
+- `{spec_dir}/contract-diff.md`（占位）
+
+## 约束
+- 开始前先调用 `TodoClear` 清除可能遗留的 todos，确保从空白计划开始
+- 遵守 `rules.md` 中的 PLN-001 到 PLN-009
+- 遵守 STK-001, STK-002（affects 声明 + cross-component 依赖）
+- 遵守 Design System 规范 (PLN-005 ~ PLN-009)
+- 完成后将产物返回给 Master Agent，由 Master Agent 执行 Human Gate 审查（AskUser）
+
+## Design System 约束（前端组件必读）
+
+### UI 组件必须引用以下规范：
+
+| 平台 | 必读规范 |
+|------|----------|
+| Web | `phases/plan/design_system/design_tokens.md` + `platform_ui/web.md` |
+| Native | `phases/plan/design_system/design_tokens.md` + `platform_ui/native.md` |
+| Desktop | `phases/plan/design_system/design_tokens.md` + `platform_ui/desktop.md` |
+| WXA | `phases/plan/design_system/design_tokens.md` + `platform_ui/wxa.md` |
+| MYA | `phases/plan/design_system/design_tokens.md` + `platform_ui/mya.md` |
+| TTA | `phases/plan/design_system/design_tokens.md` + `platform_ui/tta.md` |
+
+### 所有 UI 组件必须：
+1. **使用 Design Tokens**: 所有颜色/间距/字体/阴影必须使用 CSS 变量 (`var(--color-*)`)
+2. **符合 Atomic Design**: 组件按 Atom/Molecule/Organism/Template/Page 分层
+3. **符合 Component Spec**: 每个组件必须有 Props/States/Accessibility 说明
+4. **满足 Accessibility**: WCAG 2.1 AA (对比度 4.5:1, focus ring, ARIA)
+5. **支持 Theme**: 深浅主题通过 CSS 变量自动切换
+
+## 完成报告
+
+完成后返回以下信息给 Master Agent（用于写入 Registry）：
+- `phase: "plan"`
+- `status: "completed"`
+- `artifacts: [生成的文件路径列表]`
+- `gatePassed: true/false`

package/ai-dlc-skill/phases/plan/rules.md

@@ -0,0 +1,60 @@
+# Plan Rules (PLN-*)
+
+## PLN-001: Design Documentation
+**Severity:** MUST
+**Description:** Each feature MUST have a design document covering architecture, data model, API contracts, and state machine. For multi-component features, MUST have per-component sections and an integration section.
+**Valid:** `aidlc/openspec/changes/{id}/design.md` with `## Component: backend`, `## Component: web`, `## Integration`.
+**Invalid:** A single flat architecture section with no per-component concerns.
+
+## PLN-002: Dependency DAG
+**Severity:** MUST
+**Description:** Units MUST be decomposed with explicit dependency DAG including cross-component edges. A task producing/consuming a contract MUST depend on the corresponding `INT-FR-*` task.
+**Valid:** `depends_on: [int-contract-1, be-unit-1]` for a web task consuming the contract.
+**Invalid:** Per-component task lists with no cross-component edges.
+
+## PLN-003: Test Plan Before Implementation
+**Severity:** MUST
+**Description:** Test plans for each scenario MUST be written before implementation and MUST name the test layer (`unit`, `integration`, `e2e`, `cross-stack`, `contract`).
+**Valid:** `BE-FR-001 @positive → layer: integration → test_login_valid_credentials`
+**Invalid:** A test plan with no layer designation.
+
+## PLN-004: Contract Plan
+**Severity:** MUST
+**Description:** For each contract change, the design doc MUST identify version impact (additive vs. breaking), consumers affected, and backward-compat strategy.
+**Valid:** `INT-FR-001 change: additive, MINOR bump; no consumer migration needed`
+**Invalid:** Contract change with no version impact noted.
+
+## PLN-005: Design Tokens Usage
+**Severity:** MUST
+**Description:** All UI components MUST use Design Tokens (CSS variables) for colors, spacing, typography, and shadows. Hardcoded values are NOT allowed.
+**Valid:** `color: var(--color-primary); padding: var(--space-4);`
+**Invalid:** `color: #3B82F6; padding: 16px;`
+**Reference:** `phases/plan/design_system/design_tokens.md`
+
+## PLN-006: Design System Compliance
+**Severity:** MUST
+**Description:** All UI components MUST follow the Design System specification including Atomic Design分层, Component Spec模板, and Platform UI规范.
+**Valid:** Components documented per `component_spec.md` template with Props, States, Accessibility
+**Invalid:** Component without specification or deviating from atomic design hierarchy
+**Reference:** `phases/plan/design_system/atomic_design.md`, `phases/plan/design_system/component_spec.md`
+
+## PLN-007: Accessibility Requirements
+**Severity:** MUST
+**Description:** All UI components MUST meet WCAG 2.1 AA standards including focus management, ARIA attributes, and color contrast ratios.
+**Valid:** Focus ring visible, ARIA labels on icon buttons, contrast ratio ≥ 4.5:1
+**Invalid:** Missing focus ring, no ARIA label on icon-only button, contrast ratio < 4.5:1
+**Reference:** `phases/plan/design_system/accessibility.md`
+
+## PLN-008: Platform-Specific UI
+**Severity:** MUST
+**Description:** For each affected platform (web/native/desktop/wxa/mya/tta), the design doc MUST reference the corresponding platform UI spec.
+**Valid:** `WEB-FR-001 uses responsive breakpoints per platform_ui/web.md`
+**Invalid:** Platform UI designed without referencing platform-specific规范
+**Reference:** `phases/plan/design_system/platform_ui/{platform}.md`
+
+## PLN-009: Theme System Support
+**Severity:** SHOULD
+**Description:** All UI components SHOULD support light/dark theme switching via CSS variables without component code changes.
+**Valid:** Components styled with CSS variables, theme切换无闪烁
+**Invalid:** Hardcoded colors that don't adapt to theme
+**Reference:** `phases/plan/design_system/theme_system.md`

package/ai-dlc-skill/phases/understand/entry.md

@@ -0,0 +1,36 @@
+---
+name: ai-dlc-understand
+description: "Understand Phase: Intent → Spec Delta → BDD Feature Files"
+entry_point: phases/understand/entry.md
+triggers:
+  - understand
+  - spec-delta
+  - EARS
+  - feature file
+---
+
+# Understand Phase (理解)
+
+Transform business intent into formal specification and behavior scenarios.
+
+## Lifecycle
+
+See `lifecycle.md` for the full phase flow.
+See `rules.md` for enforceable rules (UND-001 to UND-006).
+See `prompt.md` for the sub-agent delegation prompt template.
+
+## 当被委派时
+
+0. 先调用 `TodoClear` 清除上阶段遗留的 todos，确保从空白计划开始
+1. 读取 intent 输入
+2. 按 SDD 方法生成 spec-delta（EARS 格式）
+3. 为每个 FR 写 BDD feature 文件（≥3 scenarios: positive, negative, edge）
+4. 输出到 `{spec_dir}/`（路径变量见 `aidlc/CONFIG.md`）
+
+## 产出
+
+- `aidlc/requirements.md`
+- `{spec_dir}/spec-delta.md`
+- `{features_dir}/{domain}/{feature}.feature`
+- `{cross_features_dir}/{domain}/{feature}.feature`（跨组件时）
+- `{contracts_api_dir}/{name}.yaml` 或 `{contracts_events_dir}/{name}.yaml`（跨组件时）

package/ai-dlc-skill/phases/understand/lifecycle.md

@@ -0,0 +1,184 @@
+# AI-DLC Phase 1: Understand (理解)
+
+Transform business intent into formal specification and behavior scenarios, scoped to the right FR namespace.
+
+## Goal
+
+Convert a business need into unambiguous, verifiable requirements before any design or code work begins. For multi-component features, capture the **cross-component boundary** in addition to per-component behavior.
+
+## Flow
+
+```
+Intent (business need / user story)
+  │
+  ▼
+Identify scope: which components does this touch?
+  │
+  ▼
+SDD: Proposal (why, what, impact, affects: [native|desktop|web|backend|wxa|mya|tta|contracts])
+  │
+  ▼
+SDD: Spec Delta (EARS format — ADDED/MODIFIED/REMOVED, FR namespaces)
+  │
+  ▼
+BDD: Feature Files
+  - features/{component}/{domain}/{feature}.feature   (per-component)
+  - aidlc/features/cross-stack/{domain}/{feature}.feature   (full flow, if applies)
+  │
+  ▼
+Gate: Human review → approved or revise
+```
+
+## Scope Identification
+
+Before writing the spec, declare which components the feature affects. This determines the FR namespaces and which lifecycle paths run.
+
+| Affects | Example | FRs |
+|---------|---------|-----|
+| `[backend]` only | Internal API | `BE-FR-NNN` |
+| `[web, backend]` | Login UI + API | `WEB-FR-NNN`, `BE-FR-NNN`, `INT-FR-NNN` |
+| `[native, backend]` | Native login | `NATIVE-FR-NNN`, `BE-FR-NNN`, `INT-FR-NNN` |
+| `[desktop, backend]` | Desktop login | `DESKTOP-FR-NNN`, `BE-FR-NNN`, `INT-FR-NNN` |
+| `[wxa, backend]` | Mini-program login | `WXA-FR-NNN`, `BE-FR-NNN`, `INT-FR-NNN` |
+| `[mya, backend]` | Mini-program login | `MYA-FR-NNN`, `BE-FR-NNN`, `INT-FR-NNN` |
+| `[tta, backend]` | Mini-program login | `TTA-FR-NNN`, `BE-FR-NNN`, `INT-FR-NNN` |
+| `[web, native, desktop, wxa, mya, tta, backend]` | Full feature | `WEB-FR-NNN`, `NATIVE-FR-NNN`, `DESKTOP-FR-NNN`, `WXA-FR-NNN`, `MYA-FR-NNN`, `TTA-FR-NNN`, `BE-FR-NNN`, `INT-FR-NNN` |
+| `[contracts]` | Schema-only change | `INT-FR-NNN` only |
+
+`affects: [contracts]` is reserved for **pure contract changes** (e.g. add a new field shared by all components). It still requires Plan + Verify.
+
+## SDD — Spec-Driven Development
+
+### Intent Capture
+
+```markdown
+## Intent
+
+**Title:** {{title}}
+**Affects:** [{{components}}]
+**Why:** {{why}}
+**What:** {{what}}
+**Success:** {{success_criteria}}
+```
+
+### Spec Delta (EARS) with Namespace
+
+```markdown
+## Change: CHG-{{id}} — {{title}}
+
+**Affects:** [{{components}}]
+**Contracts touched:** {{list or "none"}}
+
+## ADDED Requirements
+
+### INT-FR-{{nnn}}: {{contract_title}}
+(only if affects contracts or ≥2 components)
+
+**Description (Event-Driven):**
+When a {{event}}, the system SHALL {{behavior}} on the contract boundary.
+
+### BE-FR-{{nnn}}: {{backend_title}}
+**Description (Event-Driven):**
+When {{event}}, the backend SHALL {{behavior}}.
+
+### WEB-FR-{{nnn}}: {{web_title}}
+**Description (Event-Driven):**
+When {{event}}, the web client SHALL {{behavior}}.
+
+### NATIVE-FR-{{nnn}}: {{native_title}}
+**Description (Event-Driven):**
+When {{event}}, the native client SHALL {{behavior}}.
+
+### DESKTOP-FR-{{nnn}}: {{desktop_title}}
+**Description (Event-Driven):**
+When {{event}}, the desktop client SHALL {{behavior}}.
+
+### WXA-FR-{{nnn}}: {{wxa_title}}
+**Description (Event-Driven):**
+When {{event}}, the WeChat Mini Program SHALL {{behavior}}.
+
+### MYA-FR-{{nnn}}: {{mya_title}}
+**Description (Event-Driven):**
+When {{event}}, the Mini Program SHALL {{behavior}}.
+
+### TTA-FR-{{nnn}}: {{tta_title}}
+**Description (Event-Driven):**
+When {{event}}, the TikTok Mini Program SHALL {{behavior}}.
+```
+
+### EARS Patterns
+
+| Pattern | Syntax | When to Use |
+|---------|--------|-------------|
+| Ubiquitous | `The system SHALL ...` | Always-active rules |
+| Event-Driven | `When {event}, the system SHALL ...` | Trigger-based behavior |
+| State-Driven | `While {state}, the system SHALL ...` | Active state conditions |
+| Unwanted | `If {condition}, the system SHALL ...` | Error handling |
+| Optional | `Where {feature} enabled, the system SHALL ...` | Feature flags |
+
+## BDD — Behavior-Driven Development
+
+### Per-Component Feature Files
+
+```gherkin
+@WEB-FR-001
+Feature: Web Login UI
+
+  @WEB-FR-001 @positive
+  Scenario: User logs in successfully
+    Given the web app is on the login page
+    When the user submits valid credentials
+    Then the user is redirected to dashboard
+    And the user receives a JWT in storage
+
+  @WEB-FR-001 @negative
+  Scenario: Invalid credentials show error
+    ...
+
+  @WEB-FR-001 @edge
+  Scenario: Empty fields show validation
+    ...
+```
+
+### Cross-Stack Feature File (mandatory for `affects ≥ 2 components`)
+
+```gherkin
+@INT-FR-001
+Feature: Cross-stack login flow
+
+  @INT-FR-001 @positive
+  Scenario: Web login reaches backend and stores token
+    Given the web app is on the login page
+    When the user submits valid credentials
+    Then the backend POST /auth/login returns 200 with JWT
+    And the web app stores the token
+    And the user is redirected to dashboard
+
+  @INT-FR-001 @negative
+  Scenario: Backend rejects invalid credentials with 401
+    ...
+
+  @INT-FR-001 @edge
+  Scenario: Backend timeout surfaces a user-friendly error
+    ...
+```
+
+## Artifacts
+
+| Artifact | Location | Purpose |
+|----------|----------|---------|
+| Intent | `aidlc/requirements.md` | Business need + `affects` |
+| Spec delta | `aidlc/openspec/changes/{id}/spec-delta.md` | EARS, FR namespaces, `affects` |
+| Per-component BDD | `apps/{component}/features/{domain}/{feature}.feature` | Component behavior |
+| Cross-stack BDD | `aidlc/features/cross-stack/{domain}/{feature}.feature` | End-to-end flow |
+| Contract spec | `aidlc/contracts/{api,events}/{name}.{yaml,graphql}` | INT-FR-NNN source of truth |
+
+## Gate
+
+**Before advancing to Plan phase:**
+- [ ] `affects: [...]` declared in spec-delta
+- [ ] Spec delta uses EARS format
+- [ ] Per-component FRs: each tagged `@FR-{PREFIX}-NNN` (e.g. `@NATIVE-`, `@DESKTOP-`, `@WEB-`, `@BE-`, `@WXA-`, `@MYA-`, `@TTA-`), ≥3 scenarios (positive/negative/edge)
+- [ ] If `affects` includes ≥2 components: at least one `INT-FR-NNN` and a `aidlc/features/cross-stack/*.feature` with ≥3 scenarios
+- [ ] If `affects` includes contracts: contract file present in `aidlc/contracts/`
+- [ ] Human reviewed and approved

package/ai-dlc-skill/phases/understand/prompt.md

@@ -0,0 +1,58 @@
+# Understand Phase Agent Prompt
+
+你是一个 AI-DLC Understand Phase Agent。
+由 Master Agent 委派处理需求分析。
+
+## 输入
+- Intent 描述（来自用户 / Master）
+- `affects: [component list]` 声明
+
+## 路径约定
+
+所有产物路径遵循 `aidlc/CONFIG.md` 中的变量定义。关键路径：
+- Spec Delta: `{spec_dir}/spec-delta.md`
+- 组件 Feature 文件: `{features_dir}/{name}.feature`
+- 跨栈 Feature 文件: `{cross_features_dir}/{name}.feature`
+- 合约文件: `{contracts_api_dir}/{name}.yaml` 或 `{contracts_events_dir}/{name}.yaml`
+
+## 任务
+
+1. **SDD: Intent Capture**
+   - 在 `aidlc/requirements.md` 记录 Why / What / Success Criteria / Scope
+   - 声明 `affects: [native|desktop|web|backend|wxa|mya|tta|contracts]`
+
+2. **SDD: Spec Delta (EARS)**
+   - 在 `{spec_dir}/spec-delta.md` 输出
+   - 使用 EARS 格式：Ubiquitous / Event-Driven / State-Driven / Unwanted / Optional
+   - FR 必须使用命名空间前缀（BE-FR-001, WEB-FR-001 等）
+
+3. **BDD: Feature Files**
+   - 每个 FR ≥3 个 scenario（positive / negative / edge）
+   - Per-component: `{features_dir}/{domain}/{feature}.feature`
+   - Cross-stack: `{cross_features_dir}/{domain}/{feature}.feature`
+   - Tag 使用 `@FR-PREFIX-NNN`
+
+4. **Contract First**（跨组件时）
+   - 在 `{contracts_api_dir}/` 或 `{contracts_events_dir}/` 创建合约文件
+   - 引用 INT-FR-NNN
+
+## 输出产物
+- `aidlc/requirements.md`
+- `{spec_dir}/spec-delta.md`
+- `{features_dir}/{domain}/{feature}.feature`
+- `{cross_features_dir}/{domain}/{feature}.feature`（跨组件时）
+- `{contracts_api_dir}/{name}.yaml` 或 `{contracts_events_dir}/{name}.yaml`（跨组件时）
+
+## 约束
+- 开始前先调用 `TodoClear` 清除可能遗留的 todos，确保从空白计划开始
+- 遵守 `rules.md` 中的 UND-001 到 UND-006
+- 遵守 `core/security.md`
+- 完成后将产物返回给 Master Agent，由 Master Agent 执行 Human Gate 审查（AskUser）
+
+## 完成报告
+
+完成后返回以下信息给 Master Agent（用于写入 Registry）：
+- `phase: "understand"`
+- `status: "completed"`
+- `artifacts: [生成的文件路径列表]`
+- `gatePassed: true/false`