cc-devflow 4.2.0 → 4.3.0

package/.claude/hooks/inject-agent-context.ts

@@ -57,15 +57,15 @@ const AGENT_SKILL_MAP: Record<string, string> = {
 
 // Agent type to JSONL filename mapping
 const AGENT_JSONL_MAP: Record<string, string> = {
-  'flow-researcher': 'researcher.jsonl',
-  'prd-writer': 'prd-writer.jsonl',
-  'tech-architect': 'tech-architect.jsonl',
-  'ui-designer': 'ui-designer.jsonl',
-  'planner': 'planner.jsonl',
-  'dev-implementer': 'dev-implementer.jsonl',
-  'qa-tester': 'qa-tester.jsonl',
-  'security-reviewer': 'security-reviewer.jsonl',
-  'release-manager': 'release-manager.jsonl',
+  'flow-researcher': 'brainstorm.jsonl',
+  'prd-writer': 'spec.jsonl',
+  'tech-architect': 'spec.jsonl',
+  'ui-designer': 'spec.jsonl',
+  'planner': 'spec.jsonl',
+  'dev-implementer': 'dev.jsonl',
+  'qa-tester': 'dev.jsonl',
+  'security-reviewer': 'dev.jsonl',
+  'release-manager': 'dev.jsonl',
 };
 
 const MAX_FILE_SIZE = 50000; // 50KB per file

package/.claude/scripts/.claude/commands/flow/export-openspec.md

@@ -0,0 +1,221 @@
+---
+name: flow:export-openspec
+description: Export CC-DevFlow spec.md to OpenSpec format (pure requirements, no metadata)
+---
+
+# /flow:export-openspec - OpenSpec 导出命令
+
+## Purpose
+
+将 CC-DevFlow 的 spec.md 导出为 OpenSpec 格式，移除 CC-DevFlow 特定的元数据和实现细节。
+
+## Usage
+
+```bash
+/flow:export-openspec "REQ-123" --output "<openspec-path>"
+```
+
+## Parameters
+
+- `REQ-123`: CC-DevFlow 需求 ID (必需)
+- `--output`: OpenSpec spec.md 输出路径 (必需)
+
+## Examples
+
+```bash
+# 导出到 OpenSpec 项目
+/flow:export-openspec "REQ-123" \
+  --output "/path/to/openspec/changes/add-auth/specs/auth/spec.md"
+
+# 导出到当前目录
+/flow:export-openspec "REQ-124" \
+  --output "./openspec-export/payments/spec.md"
+```
+
+## Workflow
+
+```
+1. 读取 devflow/requirements/{REQ-ID}/spec.md
+   ↓
+2. 解析 CC-DevFlow 格式
+   - 跳过 YAML frontmatter
+   - 提取 Purpose
+   - 提取 Requirements (with BDD scenarios)
+   - 忽略 Design / Tasks / Verification
+   ↓
+3. 转换为 OpenSpec 格式
+   - 移除所有元数据
+   - 移除 [NEEDS CLARIFICATION] 标记
+   - 保留纯 Requirements
+   ↓
+4. 写入 OpenSpec spec.md
+   ↓
+5. 输出转换结果
+```
+
+## CC-DevFlow Format (Input)
+
+```markdown
+---
+req_id: "REQ-123"
+title: "用户认证系统"
+created_at: "2026-03-13T10:00:00Z"
+version: "1.0.0"
+---
+
+# Authentication Module
+
+## Purpose
+Provides secure authentication.
+
+## Requirements
+
+### Requirement: User Login
+The system SHALL allow login.
+
+#### Scenario: Valid credentials
+- GIVEN a registered user
+- WHEN the user submits credentials
+- THEN a JWT token is issued
+
+## Design
+[NEEDS CLARIFICATION: Implementation details]
+
+## Tasks
+- [ ] T001 [TEST] User Login - 测试
+- [ ] T002 [IMPL] User Login - 实现
+```
+
+## OpenSpec Format (Output)
+
+```markdown
+# Authentication Module
+
+## Purpose
+Provides secure authentication.
+
+## Requirements
+
+### Requirement: User Login
+The system SHALL allow login.
+
+#### Scenario: Valid credentials
+- GIVEN a registered user
+- WHEN the user submits credentials
+- THEN a JWT token is issued
+```
+
+## What Gets Removed
+
+- ❌ YAML frontmatter (req_id, title, version, etc.)
+- ❌ `## Design` section
+- ❌ `## Tasks` section
+- ❌ `## Verification` section
+- ❌ `[NEEDS CLARIFICATION]` markers
+- ❌ TDD task annotations ([TEST], [IMPL])
+- ❌ CC-DevFlow specific metadata
+
+## What Gets Preserved
+
+- ✅ Module name (# heading)
+- ✅ `## Purpose` section
+- ✅ `## Requirements` section
+- ✅ Requirement names and descriptions
+- ✅ BDD scenarios (Given-When-Then)
+- ✅ RFC 2119 keywords (SHALL, MUST, SHOULD, MAY)
+
+## Error Handling
+
+```bash
+# REQ-ID 不存在
+Error: REQ-123 not found in devflow/requirements/
+
+# spec.md 不存在
+Error: spec.md not found for REQ-123
+
+# 输出目录不可写
+Error: Cannot write to /path/to/openspec/
+```
+
+## Output
+
+```json
+{
+  "success": true,
+  "outputPath": "/path/to/openspec/changes/add-auth/specs/auth/spec.md",
+  "requirementsCount": 3
+}
+```
+
+## Implementation
+
+```bash
+node .claude/scripts/export-openspec.js \
+  "devflow/requirements/<req-id>/spec.md" \
+  "<output-path>"
+```
+
+## Use Cases
+
+### 1. 贡献到 OpenSpec 项目
+
+```bash
+# 在 CC-DevFlow 中开发完成
+/flow:dev "REQ-123"
+/flow:verify "REQ-123"
+
+# 导出为 OpenSpec 格式
+/flow:export-openspec "REQ-123" \
+  --output "/path/to/openspec/changes/add-feature/specs/module/spec.md"
+
+# 提交到 OpenSpec 项目
+cd /path/to/openspec
+git add changes/add-feature/
+git commit -m "Add feature specification"
+```
+
+### 2. 共享需求规格
+
+```bash
+# 导出纯需求文档（无实现细节）
+/flow:export-openspec "REQ-124" \
+  --output "./shared-specs/payments.md"
+
+# 分享给产品团队或其他项目
+```
+
+### 3. 需求归档
+
+```bash
+# 导出为标准格式归档
+/flow:export-openspec "REQ-125" \
+  --output "./archive/specs/feature-v1.0.md"
+```
+
+## Round-Trip Compatibility
+
+OpenSpec ↔ CC-DevFlow 双向转换保持需求完整性：
+
+```bash
+# Import: OpenSpec → CC-DevFlow
+/flow:import-openspec "openspec/spec.md" --req-id "REQ-123" --title "Feature"
+  → 生成 spec.md + 自动补充 TDD 任务
+
+# Develop in CC-DevFlow
+/flow:spec "REQ-123"
+/flow:dev "REQ-123"
+
+# Export: CC-DevFlow → OpenSpec
+/flow:export-openspec "REQ-123" --output "openspec/spec.md"
+  → 移除实现细节，保留纯需求
+```
+
+## Related Commands
+
+- `/flow:import-openspec` - Import OpenSpec spec to CC-DevFlow
+- `/flow:spec` - Generate task-manifest from spec.md
+- `/flow:archive` - Archive completed requirements
+
+---
+
+**[PROTOCOL]**: 变更时更新此头部，然后检查 CLAUDE.md

package/.claude/scripts/.claude/commands/flow/import-openspec.md

@@ -0,0 +1,171 @@
+---
+name: flow:import-openspec
+description: Import OpenSpec spec.md and convert to CC-DevFlow format with TDD tasks
+---
+
+# /flow:import-openspec - OpenSpec 导入命令
+
+## Purpose
+
+从 OpenSpec 项目导入 spec.md 文件，转换为 CC-DevFlow 格式，自动补充 TDD 任务。
+
+## Usage
+
+```bash
+/flow:import-openspec "<openspec-path>" --req-id "REQ-123" --title "功能标题"
+```
+
+## Parameters
+
+- `<openspec-path>`: OpenSpec spec.md 文件的绝对路径或相对路径
+- `--req-id`: CC-DevFlow 需求 ID (必需)
+- `--title`: 需求标题 (必需)
+
+## Examples
+
+```bash
+# 导入 OpenSpec 认证模块
+/flow:import-openspec "/path/to/openspec/changes/add-auth/specs/auth/spec.md" \
+  --req-id "REQ-123" \
+  --title "用户认证系统"
+
+# 导入支付模块
+/flow:import-openspec "./openspec/specs/payments/spec.md" \
+  --req-id "REQ-124" \
+  --title "支付功能"
+```
+
+## Workflow
+
+```
+1. 读取 OpenSpec spec.md
+   ↓
+2. 解析 OpenSpec 格式
+   - Purpose
+   - Requirements (with BDD scenarios)
+   ↓
+3. 转换为 CC-DevFlow 格式
+   - 添加 YAML frontmatter
+   - 保留 Purpose + Requirements
+   - 添加 Design 部分 (标记 [NEEDS CLARIFICATION])
+   - 自动生成 TDD 任务 (TEST + IMPL)
+   - 生成 Verification 清单
+   ↓
+4. 写入 devflow/requirements/{REQ-ID}/spec.md
+   ↓
+5. 输出转换结果
+```
+
+## OpenSpec Format (Input)
+
+```markdown
+# Module Name
+
+## Purpose
+High-level description of the module.
+
+## Requirements
+
+### Requirement: Feature Name
+The system SHALL/MUST/SHOULD/MAY do something.
+
+#### Scenario: Case Name
+- GIVEN precondition
+- WHEN action
+- THEN expected result
+- AND additional assertion
+```
+
+## CC-DevFlow Format (Output)
+
+```markdown
+---
+req_id: "REQ-123"
+title: "功能标题"
+created_at: "2026-03-13T10:00:00Z"
+updated_at: "2026-03-13T10:00:00Z"
+version: "1.0.0"
+status: "draft"
+source: "openspec"
+---
+
+# Module Name
+
+## Purpose
+[Preserved from OpenSpec]
+
+## Requirements
+[Preserved from OpenSpec with BDD scenarios]
+
+## Design
+[NEEDS CLARIFICATION: 技术实现方案]
+
+## Tasks
+- [ ] T001 [TEST] Feature Name - 测试
+- [ ] T002 [IMPL] Feature Name - 实现 (dependsOn:T001)
+
+## Verification
+- [ ] Feature Name
+  - [ ] Scenario 1
+  - [ ] Scenario 2
+```
+
+## Auto-Generated TDD Tasks
+
+For each Requirement in OpenSpec:
+1. **TEST task** (T001, T003, T005...)
+2. **IMPL task** (T002, T004, T006...) with `dependsOn` to TEST
+
+This ensures Constitution Article VI compliance (Test-First Development).
+
+## Error Handling
+
+```bash
+# OpenSpec 文件不存在
+Error: OpenSpec file not found: /path/to/spec.md
+
+# REQ-ID 格式错误
+Error: Invalid REQ-ID format. Expected: REQ-\d+
+
+# REQ-ID 已存在
+Error: REQ-123 already exists in devflow/requirements/
+```
+
+## Output
+
+```json
+{
+  "success": true,
+  "outputPath": "devflow/requirements/REQ-123/spec.md",
+  "requirementsCount": 3,
+  "tasksCount": 6
+}
+```
+
+## Implementation
+
+```bash
+node .claude/scripts/import-openspec.js \
+  "<openspec-path>" \
+  "<req-id>" \
+  "<title>" \
+  "devflow/requirements/<req-id>/spec.md"
+```
+
+## Next Steps
+
+After import:
+1. Review generated spec.md
+2. Fill in `[NEEDS CLARIFICATION]` sections in Design
+3. Run `/flow:spec "REQ-123"` to generate task-manifest.json
+4. Proceed with `/flow:dev "REQ-123"`
+
+## Related Commands
+
+- `/flow:export-openspec` - Export CC-DevFlow spec to OpenSpec format
+- `/flow:spec` - Generate task-manifest from spec.md
+- `/flow:init` - Initialize new requirement (alternative to import)
+
+---
+
+**[PROTOCOL]**: 变更时更新此头部，然后检查 CLAUDE.md

package/.claude/scripts/__tests__/openspec.test.js

@@ -0,0 +1,212 @@
+/**
+ * OpenSpec 互操作测试
+ */
+
+const { parseOpenSpecMarkdown, convertToDevFlowSpec } = require('../import-openspec');
+const { parseDevFlowSpec, convertToOpenSpec } = require('../export-openspec');
+
+describe('OpenSpec Import', () => {
+  test('should parse OpenSpec format correctly', () => {
+    const openspecContent = `# Authentication Module
+
+## Purpose
+Provides secure authentication and session management.
+
+## Requirements
+
+### Requirement: User Login
+The system SHALL allow users to log in with email and password.
+
+#### Scenario: Valid credentials
+- GIVEN a registered user
+- WHEN the user submits valid email and password
+- THEN a JWT token is issued
+- AND the user is redirected to dashboard
+
+#### Scenario: Invalid credentials
+- GIVEN a registered user
+- WHEN the user submits invalid password
+- THEN an error message is displayed
+- AND no token is issued
+
+### Requirement: Session Management
+The system MUST expire sessions after 30 minutes of inactivity.
+
+#### Scenario: Idle timeout
+- GIVEN an authenticated session
+- WHEN 30 minutes pass without activity
+- THEN the session is invalidated
+- AND the user must re-authenticate
+`;
+
+    const result = parseOpenSpecMarkdown(openspecContent);
+
+    expect(result.moduleName).toBe('Authentication Module');
+    expect(result.purpose).toContain('secure authentication');
+    expect(result.requirements).toHaveLength(2);
+    expect(result.requirements[0].name).toBe('User Login');
+    expect(result.requirements[0].scenarios).toHaveLength(2);
+    expect(result.requirements[0].scenarios[0].name).toBe('Valid credentials');
+    expect(result.requirements[0].scenarios[0].steps).toHaveLength(4);
+  });
+
+  test('should convert to DevFlow spec with TDD tasks', () => {
+    const openspecData = {
+      moduleName: 'Auth Module',
+      purpose: 'Authentication',
+      requirements: [
+        {
+          name: 'User Login',
+          description: 'Login functionality',
+          scenarios: [
+            {
+              name: 'Valid credentials',
+              steps: ['GIVEN a user', 'WHEN login', 'THEN success']
+            }
+          ]
+        },
+        {
+          name: 'Session Management',
+          description: 'Session handling',
+          scenarios: [
+            {
+              name: 'Timeout',
+              steps: ['GIVEN session', 'WHEN timeout', 'THEN invalidate']
+            }
+          ]
+        }
+      ]
+    };
+
+    const devflowSpec = convertToDevFlowSpec(openspecData, 'REQ-123', 'Auth System');
+
+    expect(devflowSpec).toContain('req_id: "REQ-123"');
+    expect(devflowSpec).toContain('title: "Auth System"');
+    expect(devflowSpec).toContain('## Purpose');
+    expect(devflowSpec).toContain('## Requirements');
+    expect(devflowSpec).toContain('## Design');
+    expect(devflowSpec).toContain('## Tasks');
+    expect(devflowSpec).toContain('[TEST] User Login - 测试');
+    expect(devflowSpec).toContain('[IMPL] User Login - 实现 (dependsOn:T001)');
+    expect(devflowSpec).toContain('[TEST] Session Management - 测试');
+    expect(devflowSpec).toContain('[IMPL] Session Management - 实现 (dependsOn:T003)');
+  });
+});
+
+describe('OpenSpec Export', () => {
+  test('should parse DevFlow spec correctly', () => {
+    const devflowContent = `---
+req_id: "REQ-123"
+title: "Auth System"
+---
+
+# Authentication Module
+
+## Purpose
+
+Provides secure authentication.
+
+## Requirements
+
+### Requirement: User Login
+
+The system SHALL allow login.
+
+#### Scenario: Valid credentials
+- GIVEN a registered user
+- WHEN the user submits credentials
+- THEN a JWT token is issued
+
+### Requirement: Session Management
+
+The system MUST expire sessions.
+
+## Design
+
+[NEEDS CLARIFICATION: Implementation details]
+
+## Tasks
+
+- [ ] T001 [TEST] User Login - 测试
+- [ ] T002 [IMPL] User Login - 实现 (dependsOn:T001)
+`;
+
+    const result = parseDevFlowSpec(devflowContent);
+
+    expect(result.moduleName).toBe('Authentication Module');
+    expect(result.purpose).toContain('secure authentication');
+    expect(result.requirements).toHaveLength(2);
+    expect(result.requirements[0].name).toBe('User Login');
+    expect(result.requirements[0].scenarios).toHaveLength(1);
+  });
+
+  test('should convert to OpenSpec format without metadata', () => {
+    const devflowData = {
+      moduleName: 'Auth Module',
+      purpose: 'Authentication',
+      requirements: [
+        {
+          name: 'User Login',
+          description: 'Login functionality',
+          scenarios: [
+            {
+              name: 'Valid credentials',
+              steps: ['GIVEN a user', 'WHEN login', 'THEN success']
+            }
+          ]
+        }
+      ]
+    };
+
+    const openspecContent = convertToOpenSpec(devflowData);
+
+    expect(openspecContent).toContain('# Auth Module');
+    expect(openspecContent).toContain('## Purpose');
+    expect(openspecContent).toContain('## Requirements');
+    expect(openspecContent).toContain('### Requirement: User Login');
+    expect(openspecContent).toContain('#### Scenario: Valid credentials');
+    expect(openspecContent).not.toContain('req_id');
+    expect(openspecContent).not.toContain('---');
+    expect(openspecContent).not.toContain('[NEEDS CLARIFICATION');
+    expect(openspecContent).not.toContain('## Design');
+    expect(openspecContent).not.toContain('## Tasks');
+  });
+});
+
+describe('Round-trip conversion', () => {
+  test('should preserve requirements through import-export cycle', () => {
+    const originalOpenSpec = `# Test Module
+
+## Purpose
+Test purpose
+
+## Requirements
+
+### Requirement: Feature A
+Description A
+
+#### Scenario: Case 1
+- GIVEN condition
+- WHEN action
+- THEN result
+`;
+
+    // Import to DevFlow
+    const openspecData = parseOpenSpecMarkdown(originalOpenSpec);
+    const devflowSpec = convertToDevFlowSpec(openspecData, 'REQ-001', 'Test');
+
+    // Export back to OpenSpec
+    const devflowData = parseDevFlowSpec(devflowSpec);
+    const exportedOpenSpec = convertToOpenSpec(devflowData);
+
+    // Verify requirements preserved
+    expect(exportedOpenSpec).toContain('# Test Module');
+    expect(exportedOpenSpec).toContain('## Purpose');
+    expect(exportedOpenSpec).toContain('Test purpose');
+    expect(exportedOpenSpec).toContain('### Requirement: Feature A');
+    expect(exportedOpenSpec).toContain('#### Scenario: Case 1');
+    expect(exportedOpenSpec).toContain('- GIVEN condition');
+    expect(exportedOpenSpec).toContain('- WHEN action');
+    expect(exportedOpenSpec).toContain('- THEN result');
+  });
+});