cc-devflow 4.2.0 → 4.3.0

package/.claude/docs/templates/DESIGN_TEMPLATE.md

@@ -0,0 +1,157 @@
+# design.md Template
+
+> **Purpose**: 技术设计文档模板，描述怎么做
+> **Location**: `devflow/requirements/${REQ_ID}/design.md`
+> **Version**: v4.3.0
+
+---
+
+```markdown
+---
+req_id: "${REQ_ID}"
+title: "${TITLE}"
+created_at: "${CREATED_AT}"
+updated_at: "${UPDATED_AT}"
+version: "1.0.0"
+status: "draft"
+---
+
+# ${TITLE} - Technical Design
+
+## How（怎么做）
+
+[NEEDS CLARIFICATION: 技术方案是什么？如何实现？]
+
+### Architecture Overview
+
+${架构概述}
+
+### Technology Stack
+
+- **Frontend**: ${前端技术栈}
+- **Backend**: ${后端技术栈}
+- **Database**: ${数据库选型}
+- **Infrastructure**: ${基础设施}
+
+### Module Changes
+
+${受影响的模块列表}
+
+- `${MODULE_1}`: ${变更说明}
+- `${MODULE_2}`: ${变更说明}
+
+## Implementation（实现细节）
+
+[NEEDS CLARIFICATION: 具体实现步骤是什么？]
+
+### API Design
+
+#### Endpoints
+
+- `${METHOD} ${PATH}` - ${描述}
+  - Request: `${REQUEST_SCHEMA}`
+  - Response: `${RESPONSE_SCHEMA}`
+
+### Data Model
+
+```sql
+${数据库 Schema 变更}
+```
+
+### File Structure
+
+```
+${受影响的文件列表}
+├── ${FILE_1}  # ${说明}
+├── ${FILE_2}  # ${说明}
+└── ${FILE_3}  # ${说明}
+```
+
+### Dependencies
+
+${新增或更新的依赖}
+
+- `${PACKAGE_1}@${VERSION}` - ${用途}
+- `${PACKAGE_2}@${VERSION}` - ${用途}
+
+## Testing Strategy
+
+### Test Coverage
+
+- [ ] Unit Tests: ${覆盖范围}
+- [ ] Integration Tests: ${覆盖范围}
+- [ ] E2E Tests: ${覆盖范围}
+
+### Test Scenarios
+
+1. **${SCENARIO_1}**: ${测试描述}
+2. **${SCENARIO_2}**: ${测试描述}
+
+## Security Considerations
+
+${安全考虑}
+
+- **Authentication**: ${认证方案}
+- **Authorization**: ${授权方案}
+- **Data Protection**: ${数据保护措施}
+
+## Performance Considerations
+
+${性能考虑}
+
+- **Expected Load**: ${预期负载}
+- **Optimization Strategy**: ${优化策略}
+- **Caching**: ${缓存策略}
+
+## Rollout Plan
+
+### Phase 1: ${阶段 1 名称}
+${阶段 1 描述}
+
+### Phase 2: ${阶段 2 名称}
+${阶段 2 描述}
+
+## Risks & Mitigation
+
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| ${风险 1} | ${影响} | ${缓解措施} |
+| ${风险 2} | ${影响} | ${缓解措施} |
+
+---
+
+## Constitutional Constraints
+
+- **Article I: Quality First** - 完整实现或不实现，禁止部分实现
+- **Article VI: Test-First Development** - 测试必须在实现之前
+- **Article X: Requirement Boundary** - 只实现明确请求的功能
+
+详见 `.claude/rules/project-constitution.md`
+```
+
+---
+
+## Field Descriptions
+
+| Field | Description | Example |
+|-------|-------------|---------|
+| `req_id` | 需求 ID | "REQ-123" |
+| `title` | 需求标题 | "添加用户认证" |
+| `created_at` | 创建时间 (ISO 8601) | "2026-03-12T10:00:00Z" |
+| `updated_at` | 更新时间 (ISO 8601) | "2026-03-12T15:30:00Z" |
+| `version` | 文档版本 | "1.0.0" |
+| `status` | 状态 | "draft", "approved", "implemented" |
+
+## How vs Implementation
+
+- **How**: 回答"技术方案是什么"，聚焦架构和选型
+- **Implementation**: 回答"具体怎么实现"，聚焦细节和步骤
+
+## [NEEDS CLARIFICATION] 标记
+
+所有模糊点必须标记为 `[NEEDS CLARIFICATION: 具体问题]`，等待用户澄清。
+
+---
+
+**Version**: v4.3.0
+**Related**: SPEC_TEMPLATE_DELTA.md（Delta specs 生成）

package/.claude/docs/templates/PROPOSAL_TEMPLATE.md

@@ -0,0 +1,91 @@
+# proposal.md Template
+
+> **Purpose**: 需求提议模板，描述为什么需要和要做什么
+> **Location**: `devflow/requirements/${REQ_ID}/proposal.md`
+> **Version**: v4.3.0
+
+---
+
+```markdown
+---
+req_id: "${REQ_ID}"
+title: "${TITLE}"
+created_at: "${CREATED_AT}"
+status: "draft"
+---
+
+# ${TITLE}
+
+## Why（为什么需要）
+
+[NEEDS CLARIFICATION: 为什么需要这个功能？解决什么问题？]
+
+### Background
+${背景描述}
+
+### Problem Statement
+${问题陈述}
+
+### Business Value
+${商业价值}
+
+## What（要做什么）
+
+[NEEDS CLARIFICATION: 具体要做什么？核心功能是什么？]
+
+### Core Features
+- ${核心功能 1}
+- ${核心功能 2}
+- ${核心功能 3}
+
+### Scope
+**In Scope**:
+- ${包含的功能}
+
+**Out of Scope**:
+- ${不包含的功能}
+
+### Success Criteria
+- ${成功标准 1}
+- ${成功标准 2}
+
+## References
+
+${如果有 PLAN_URLS，列在这里}
+- [External Doc 1](${URL})
+- [External Doc 2](${URL})
+
+---
+
+## Constitutional Constraints
+
+- **Article X: Requirement Boundary** - 只实现明确请求的功能，不添加推测性特性
+- **Article I: Quality First** - 完整实现或不实现，禁止部分实现
+
+详见 `.claude/rules/project-constitution.md`
+```
+
+---
+
+## Field Descriptions
+
+| Field | Description | Example |
+|-------|-------------|---------|
+| `req_id` | 需求 ID | "REQ-123" |
+| `title` | 需求标题 | "添加用户认证" |
+| `created_at` | 创建时间 (ISO 8601) | "2026-03-12T10:00:00Z" |
+| `status` | 状态 | "draft", "approved", "implemented" |
+
+## Why vs What
+
+- **Why**: 回答"为什么需要"，聚焦问题和价值
+- **What**: 回答"要做什么"，聚焦功能和范围
+
+## [NEEDS CLARIFICATION] 标记
+
+所有模糊点必须标记为 `[NEEDS CLARIFICATION: 具体问题]`，等待用户澄清。
+
+---
+
+**Version**: v4.3.0
+**Related**: SPEC_TEMPLATE_DELTA.md（下一阶段生成）

package/.claude/docs/templates/SPEC_TEMPLATE_DELTA.md

@@ -0,0 +1,139 @@
+# spec.md Template - Delta (Requirement Level)
+
+> **Purpose**: 需求级 Delta spec.md 模板，只包含变更
+> **Location**: `devflow/requirements/${REQ_ID}/specs/{module}/spec.md`
+
+---
+
+```markdown
+---
+delta_id: "${REQ_ID}"
+module: "${MODULE_NAME}"
+title: "${CHANGE_TITLE}"
+created_at: "${CREATED_AT}"
+status: "draft"
+---
+
+# Delta: ${变更标题}
+
+## Summary
+${为什么需要这个变更？简短说明}
+
+## ADDED Requirements
+
+### Requirement: ${New Requirement Name}
+The system ${SHALL|MUST|SHOULD|MAY} ${new behavior}.
+
+#### Scenario: ${New Scenario}
+- GIVEN ${precondition}
+- WHEN ${action}
+- THEN ${expected result}
+- AND ${additional assertion}
+
+## MODIFIED Requirements
+
+### Requirement: ${Existing Requirement Name}
+The system ${SHALL|MUST|SHOULD|MAY} ${modified behavior}.
+(Previously: ${old behavior})
+
+**Rationale**: ${说明为什么修改}
+
+## REMOVED Requirements
+
+### Requirement: ${Removed Requirement Name}
+**Rationale**: ${说明为什么移除}
+
+## RENAMED Requirements
+
+### Requirement: ${Old Name} → ${New Name}
+**Rationale**: ${说明为什么重命名}
+```
+
+---
+
+## Delta Operations
+
+| Operation | Description | When to Use |
+|-----------|-------------|-------------|
+| **ADDED** | 新增需求 | 添加新功能、新场景 |
+| **MODIFIED** | 修改现有需求 | 改变行为、更新约束 |
+| **REMOVED** | 删除需求 | 废弃功能、移除特性 |
+| **RENAMED** | 重命名需求 | 改进命名、统一术语 |
+
+## Status Values
+
+- `draft` - 草稿状态，等待审批
+- `approved` - 已审批，等待实施
+- `applied` - 已应用到项目级 spec
+
+## Merge Rules
+
+归档时 (`/flow:release`)，`delta-parser.ts` 自动执行：
+
+1. **ADDED**: 追加到项目级 spec.md 的 Requirements 章节
+2. **MODIFIED**: 替换项目级 spec.md 中对应的 Requirement
+3. **REMOVED**: 从项目级 spec.md 中删除对应的 Requirement
+4. **RENAMED**: 重命名项目级 spec.md 中的 Requirement 标题
+5. **Version Bump**: 更新项目级 spec.md 的 version 字段
+
+## Version Bump Strategy
+
+- **ADDED** 新功能 → MINOR +1 (1.0.0 → 1.1.0)
+- **MODIFIED** 现有功能 → PATCH +1 (1.0.0 → 1.0.1)
+- **REMOVED** 功能 → MAJOR +1 (1.0.0 → 2.0.0) - 破坏性变更
+
+---
+
+## Example
+
+```markdown
+---
+delta_id: "REQ-123"
+module: "auth"
+title: "添加 2FA 支持"
+created_at: "2026-03-12T10:00:00Z"
+status: "draft"
+---
+
+# Delta: 添加 2FA 支持
+
+## Summary
+为提高安全性，添加两因素认证支持。用户可选择启用 2FA，登录时需要输入 OTP 验证码。
+
+## ADDED Requirements
+
+### Requirement: Two-Factor Authentication
+The system MUST require a second factor during login for users with 2FA enabled.
+
+#### Scenario: OTP required
+- GIVEN a user with 2FA enabled
+- WHEN the user submits valid credentials
+- THEN an OTP challenge is presented
+- AND the user must enter a valid OTP code
+
+#### Scenario: OTP validation
+- GIVEN a user has entered valid credentials
+- WHEN the user submits a valid OTP code
+- THEN a JWT token is issued
+- AND the user is redirected to dashboard
+
+## MODIFIED Requirements
+
+### Requirement: Session Management
+The system SHALL expire sessions after 30 minutes of inactivity.
+(Previously: 60 minutes)
+
+**Rationale**: 缩短超时时间以提高安全性，配合 2FA 使用。
+
+## REMOVED Requirements
+
+None
+
+## RENAMED Requirements
+
+None
+```
+
+---
+
+**Version**: v4.3.0

package/.claude/docs/templates/SPEC_TEMPLATE_PROJECT.md

@@ -0,0 +1,93 @@
+# spec.md Template - Project Level
+
+> **Purpose**: 项目级 spec.md 模板，描述当前系统状态
+> **Location**: `devflow/specs/{module}/spec.md`
+
+---
+
+```markdown
+---
+module: "${MODULE_NAME}"
+created_at: "${CREATED_AT}"
+updated_at: "${UPDATED_AT}"
+version: "1.0.0"
+---
+
+# ${Module Name}
+
+## Purpose
+${高层描述：这个模块是干什么的}
+
+## Requirements
+
+### Requirement: ${Requirement Name}
+The system ${SHALL|MUST|SHOULD|MAY} ${behavior description}.
+
+#### Scenario: ${Scenario Name}
+- GIVEN ${precondition}
+- WHEN ${action}
+- THEN ${expected result}
+- AND ${additional assertion}
+
+### Requirement: ${Another Requirement}
+The system ${SHALL|MUST|SHOULD|MAY} ${behavior description}.
+
+#### Scenario: ${Another Scenario}
+- GIVEN ${precondition}
+- WHEN ${action}
+- THEN ${expected result}
+
+## Implementation
+
+### API Endpoints
+- ${METHOD} ${PATH}
+- ${METHOD} ${PATH}
+
+### Data Model
+\`\`\`sql
+CREATE TABLE ${table_name} (
+  id UUID PRIMARY KEY,
+  ${field_name} ${field_type} ${constraints}
+);
+\`\`\`
+
+### Files
+- \`${file_path}\`
+- \`${file_path}\`
+
+---
+
+**Note**: This spec describes the current state of the system.
+```
+
+---
+
+## Field Descriptions
+
+| Field | Description | Example |
+|-------|-------------|---------|
+| `module` | 模块名称 | "auth", "payments", "ui" |
+| `created_at` | 创建时间 (ISO 8601) | "2026-01-01T10:00:00Z" |
+| `updated_at` | 最后更新时间 | "2026-03-12T15:30:00Z" |
+| `version` | 语义化版本号 | "2.1.0" |
+
+## RFC 2119 Keywords
+
+- **SHALL**: 必须实现（核心功能）
+- **MUST**: 强制要求（安全/合规）
+- **SHOULD**: 推荐实现（最佳实践）
+- **MAY**: 可选实现（增强功能）
+
+## BDD Scenario Format
+
+```
+#### Scenario: {场景名称}
+- GIVEN {前置条件}
+- WHEN {触发动作}
+- THEN {预期结果}
+- AND {额外断言}
+```
+
+---
+
+**Version**: v4.3.0