cc-devflow 2.4.6 → 4.1.0

package/.claude/agents/dev-implementer.md

@@ -0,0 +1,195 @@
+---
+name: dev-implementer
+description: Execute development tasks following TDD Iron Law with implementation planning.
+tools: Read, Write, Grep, Glob
+model: inherit
+---
+
+You are a development implementation specialist with **MANDATORY TDD IRON LAW ENFORCEMENT**.
+
+## ⚠️ CRITICAL: TDD IRON LAW
+
+```
+NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
+```
+
+### TDD Checkpoint
+
+```yaml
+⚠️ TEST VERIFICATION CHECKPOINT:
+  1. 运行所有 Phase 2 测试
+  2. 验证所有新测试 FAIL
+  3. 只有全部 FAIL 后才能进入 Phase 3
+  4. 如果已经写了实现代码 → DELETE 重来
+```
+
+## Your Role
+
+- **Primary**: Execute individual tasks from TASKS.md following TDD sequence
+- **Output**: Implementation code + IMPLEMENTATION_PLAN.md for each task
+- **Enforce**: TDD Iron Law - tests MUST fail before implementation
+- **Track**: Update task status and log progress
+
+## Rules Integration
+
+You MUST follow these rules during implementation:
+
+1. **TDD Sequence**:
+   - Read task DoD (Definition of Done)
+   - Write failing test FIRST
+   - Verify test fails
+   - Write minimal implementation to pass
+   - Refactor while keeping tests green
+   - Commit
+
+2. **Code Quality**:
+   - No partial implementations (Article I)
+   - Reuse existing code (Article II)
+   - No hardcoded secrets (Article III)
+   - Proper resource cleanup (Article IV)
+   - No dead code (Article V)
+
+3. **File Operations**:
+   - Use exact file paths from TASKS.md
+   - Follow existing code patterns
+   - Maintain consistent naming conventions
+
+## Input Context
+
+When executing a task, you receive:
+- **REQ_ID**: Requirement identifier
+- **TASK_ID**: Task identifier (T001, T002, etc.)
+- **TASKS.md**: Full task list with DoD
+- **TECH_DESIGN.md**: Technical design reference
+- **PRD.md**: Product requirements reference
+
+## Execution Flow
+
+### Stage 1: Task Analysis
+
+```yaml
+1. Read TASKS.md and locate task by TASK_ID
+2. Extract:
+   - Task description
+   - File paths
+   - DoD criteria
+   - Dependencies
+   - [P] parallel flag
+   - [US#] user story reference
+3. Read related context:
+   - TECH_DESIGN.md for technical details
+   - PRD.md for acceptance criteria
+   - Existing code for patterns
+```
+
+### Stage 2: Implementation Planning
+
+```yaml
+1. Create IMPLEMENTATION_PLAN.md in tasks/ directory
+2. Document:
+   - Approach
+   - Files to modify
+   - Test strategy
+   - Implementation steps
+   - Verification commands
+```
+
+### Stage 3: TDD Execution
+
+```yaml
+Phase 2 (Tests First):
+  1. Write test file
+  2. Run test → MUST FAIL
+  3. If test passes → ERROR (invalid test)
+  4. Log test creation
+
+Phase 3 (Implementation):
+  1. Write minimal code to pass test
+  2. Run test → MUST PASS
+  3. Refactor if needed
+  4. Run test again → MUST PASS
+  5. Log implementation
+```
+
+### Stage 4: Verification
+
+```yaml
+1. Run all related tests
+2. Check coverage
+3. Verify DoD criteria met
+4. Update TASKS.md (mark [x])
+5. Log completion
+```
+
+## Output Structure
+
+```
+devflow/requirements/${REQ_ID}/tasks/
+├── IMPLEMENTATION_PLAN.md      # Overall implementation plan
+├── T001_plan.md                # Task-specific plan
+├── T002_plan.md
+└── ...
+```
+
+## Error Handling
+
+```yaml
+Test Failure:
+  1. Log error to ERROR_LOG.md
+  2. Analyze root cause
+  3. Fix and retry
+  4. If persistent → escalate
+
+Implementation Failure:
+  1. Log error with full context
+  2. Check dependencies
+  3. Review TECH_DESIGN.md
+  4. Retry with adjusted approach
+```
+
+## Constitution Compliance
+
+For each task, verify:
+- [ ] Article I: Complete implementation, no placeholders
+- [ ] Article II: Reused existing code where possible
+- [ ] Article III: No hardcoded secrets
+- [ ] Article IV: Resources properly managed
+- [ ] Article V: No dead code introduced
+- [ ] Article VI: TDD sequence followed
+
+## Attention Refresh Protocols
+
+| Protocol | Trigger | Action |
+|----------|---------|--------|
+| Protocol 2 | Task start | Read TASKS.md T### + DoD |
+| Protocol 3 | Iteration start | Read TASKS.md + ERROR_LOG |
+| Protocol 4 | After error | Read ERROR_LOG.md |
+
+## Quality Criteria
+
+- **TDD Compliance**: Tests written and failing before implementation
+- **Code Coverage**: ≥80% for new code
+- **No Placeholders**: All code complete and functional
+- **Documentation**: Implementation plan documented
+- **Verification**: All DoD criteria met
+
+## Process Summary
+
+```
+1. Read task from TASKS.md
+2. Create implementation plan
+3. Write failing test (Phase 2)
+4. Verify test fails
+5. Write implementation (Phase 3)
+6. Verify test passes
+7. Update task status
+8. Log completion
+```
+
+## Context Requirements
+
+- Read `orchestration_status.json` for project state
+- Read `TECH_DESIGN.md` for technical specifications
+- Read `PRD.md` for acceptance criteria
+- Read existing code for patterns and conventions
+- Update `EXECUTION_LOG.md` with progress

package/.claude/commands/{flow-archive.md → flow/archive.md}

@@ -1,11 +1,14 @@
 ---
 name: flow-archive
-description: 'Archive completed/deprecated requirements. Usage: /flow-archive "REQ-123" or /flow-archive --list'
+description: 'Archive completed/deprecated requirements with Delta Specs support. Usage: /flow:archive "REQ-123" or /flow:archive --list'
+version: 4.5.0
 scripts:
   archive: .claude/scripts/archive-requirement.sh
 ---
 
-# Flow-Archive - 需求归档命令
+# /flow:archive - 需求归档命令 (v4.5)
+
+> **[PROTOCOL]**: 变更时更新此头部，然后检查 CLAUDE.md
 
 ## User Input
 ```text
@@ -15,10 +18,10 @@ $ARGUMENTS = "REQ_ID?" | "--list" | "--restore REQ_ID"
 
 ## 命令格式
 ```text
-/flow-archive "REQ-123"                      # 归档已完成需求
-/flow-archive "REQ-123" --reason deprecated  # 标记为废弃归档
-/flow-archive --list                         # 列出所有归档
-/flow-archive "REQ-123" --restore            # 恢复归档需求
+/flow:archive "REQ-123"                      # 归档已完成需求
+/flow:archive "REQ-123" --reason deprecated  # 标记为废弃归档
+/flow:archive --list                         # 列出所有归档
+/flow:archive "REQ-123" --restore            # 恢复归档需求
 ```
 
 ### 参数说明
@@ -221,11 +224,43 @@ ERROR: 无效的归档原因: cancelled
 ## 与其他命令的关系
 
 ```text
-/flow-init → /flow-prd → /flow-epic → /flow-dev → /flow-qa → /flow-release
-                                                                    ↓
-                                                            /flow-archive ← 工作流终点
-                                                                    ↓
-                                                            devflow/archive/{YYYY-MM}/
+/flow:init → /flow:spec → /flow:dev → /flow:quality → /flow:release
+                                                            ↓
+                                                    /flow:archive ← 工作流终点
+                                                            ↓
+                                                    devflow/archive/{YYYY-MM}/
+```
+
+## Delta Specs 集成 (v4.5)
+
+归档时自动处理 Delta Specs:
+
+### 归档前检查
+- 检测 `deltas/` 目录中的 Delta Specs
+- 警告未应用的 Delta Specs (status != "applied")
+- 建议先运行 `/flow:delta apply REQ-XXX --all`
+
+### 归档内容
+```
+devflow/archive/{YYYY-MM}/{REQ_ID}/
+├── PRD.md                    # 主规格文档
+├── deltas/                   # Delta Specs (完整保留)
+│   ├── 2026-02-01-add-2fa/
+│   │   ├── delta.md
+│   │   └── tasks.md
+│   └── ...
+├── orchestration_status.json # 包含 deltaCount 字段
+└── ...
+```
+
+### 状态文件增强
+```json
+{
+  "status": "archived",
+  "archivedReason": "completed",
+  "deltaCount": 3,
+  "archivedAt": "2026-02-07T10:00:00+08:00"
+}
 ```
 
 ## 脚本集成

package/.claude/commands/flow/context.md

@@ -0,0 +1,150 @@
+---
+name: flow-context
+description: Manage staged context injection for agents (RM-015)
+version: 3.0.0
+---
+
+# /flow-context
+
+> **[PROTOCOL]**: 变更时更新此头部，然后检查 CLAUDE.md
+
+## Purpose
+
+Manage context injection configuration for CC-DevFlow agents.
+Each agent type has a JSONL file defining what context to load.
+
+## Usage
+
+```bash
+# Initialize context directory for a requirement
+/flow-context init [REQ-ID] [--type backend|frontend|fullstack]
+
+# Add entry to context file
+/flow-context add [agent] [path] [purpose] [--optional]
+
+# List current context configuration
+/flow-context list [agent]
+
+# Validate context paths exist
+/flow-context validate [REQ-ID]
+```
+
+## Subcommands
+
+### init
+
+Initialize context directory with templates.
+
+```bash
+/flow-context init REQ-007 --type backend
+```
+
+Creates:
+- `devflow/requirements/REQ-007/context/`
+- Copies templates from `.claude/docs/templates/context/*.jsonl.template`
+- Customizes based on `--type` (backend removes frontend specs, etc.)
+
+### add
+
+Add an entry to a context JSONL file.
+
+```bash
+/flow-context add dev "src/utils/auth.ts" "Authentication utilities" --optional
+```
+
+Appends to `context/dev.jsonl`:
+```json
+{"type": "file", "path": "src/utils/auth.ts", "purpose": "Authentication utilities", "optional": true}
+```
+
+### list
+
+Show current context configuration.
+
+```bash
+/flow-context list dev
+```
+
+Output:
+```
+Context for 'dev' agent (REQ-007):
+
+  1. [file] TASKS.md - Current task list and progress
+  2. [file] EPIC.md - Epic overview and phases
+  3. [file] TECH_DESIGN.md - Technical implementation guide
+  4. [file] ERROR_LOG.md - Previous errors to avoid (optional)
+  5. [spec] devflow/spec/frontend/style.md - Frontend style guide (optional)
+
+Total: 5 entries (3 required, 2 optional)
+```
+
+### validate
+
+Validate all context paths exist.
+
+```bash
+/flow-context validate REQ-007
+```
+
+Output:
+```
+Validating context for REQ-007...
+
+  ✓ dev.jsonl: 5/5 paths valid
+  ✓ epic.jsonl: 4/4 paths valid
+  ✗ review.jsonl: 3/4 paths valid
+    - Missing: contracts/api.yaml
+
+Overall: 12/13 paths valid (92%)
+```
+
+## Integration
+
+### With flow-init
+
+When `/flow-init` creates a new requirement, it automatically runs:
+```bash
+/flow-context init {REQ-ID} --type {detected-type}
+```
+
+### With Agent Invocation
+
+The `inject-agent-context.ts` hook automatically:
+1. Detects current REQ-ID from environment or git branch
+2. Reads `context/{agent}.jsonl`
+3. Injects resolved content into agent prompt
+
+## Context Entry Format
+
+```jsonl
+{"type": "file", "path": "PRD.md", "purpose": "Product requirements"}
+{"type": "directory", "path": "contracts/", "purpose": "API contracts", "depth": 2}
+{"type": "spec", "path": "devflow/spec/backend/api.md", "purpose": "API conventions"}
+```
+
+### Entry Types
+
+| Type | Path Resolution | Use Case |
+|------|-----------------|----------|
+| `file` | Relative to requirement dir | Requirement-specific files |
+| `directory` | Relative to requirement dir | Load all files in directory |
+| `spec` | Relative to project root | Project-level specifications |
+
+### Optional Entries
+
+Add `"optional": true` for files that may not exist:
+```json
+{"type": "file", "path": "ERROR_LOG.md", "purpose": "Previous errors", "optional": true}
+```
+
+## Scripts
+
+- `.claude/scripts/flow-context-init.sh` - Initialize context directory
+- `.claude/scripts/flow-context-add.sh` - Add entry to JSONL
+- `.claude/scripts/flow-context-validate.sh` - Validate paths
+
+## Related
+
+- **Hook**: `.claude/hooks/inject-agent-context.ts`
+- **Types**: `.claude/hooks/types/context-injection.d.ts`
+- **Templates**: `.claude/docs/templates/context/*.jsonl.template`

package/.claude/commands/flow/delta.md

@@ -0,0 +1,245 @@
+---
+name: flow-delta
+description: Manage delta specs for incremental requirement tracking (RM-017)
+version: 4.0.0
+---
+
+# /flow:delta
+
+> **[PROTOCOL]**: 变更时更新此头部，然后检查 CLAUDE.md
+
+## Purpose
+
+Manage incremental specification changes (delta specs) for tracking requirement evolution.
+Delta specs capture ADDED/MODIFIED/REMOVED/RENAMED changes that are later applied to the SSOT.
+
+借鉴 OpenSpec 的 Delta Specs 设计，实现增量规格管理。
+
+## Usage
+
+```bash
+# Create a new delta spec
+/flow:delta create "REQ-123" "add-2fa"
+
+# List all deltas for a requirement
+/flow:delta list "REQ-123"
+
+# Apply delta to main specs (PRD.md)
+/flow:delta apply "REQ-123" "add-2fa"
+
+# Check delta status
+/flow:delta status "REQ-123" "add-2fa"
+```
+
+## Subcommands
+
+### create
+
+Create a new delta spec for a requirement.
+
+```bash
+/flow:delta create "REQ-123" "add-2fa"
+```
+
+Creates:
+```
+devflow/requirements/REQ-123/
+└── deltas/
+    └── {YYYY-MM-DD}-add-2fa/
+        ├── delta.md
+        └── tasks.md
+```
+
+**Process**:
+1. Validate REQ-ID exists
+2. Generate delta_id: `{YYYY-MM-DD}-{slug}`
+3. Create directory structure
+4. Generate delta.md from template
+5. Generate tasks.md for delta-specific tasks
+
+### list
+
+List all deltas for a requirement.
+
+```bash
+/flow:delta list "REQ-123"
+```
+
+**Output**:
+```
+Deltas for REQ-123:
+  1. 2026-02-01-add-2fa       [approved]  Add 2FA support
+  2. 2026-02-05-fix-login     [draft]     Fix login timeout
+  3. 2026-02-07-add-oauth     [review]    Add OAuth providers
+
+Total: 3 deltas (1 approved, 1 draft, 1 review)
+```
+
+### apply
+
+Apply a delta to the main PRD.md specification.
+
+```bash
+/flow:delta apply "REQ-123" "add-2fa"
+```
+
+**Process**:
+1. Parse delta.md using delta-parser.ts
+2. Validate delta status is "approved"
+3. Apply changes to PRD.md:
+   - RENAMED: Rename requirement headers
+   - REMOVED: Remove requirement blocks
+   - MODIFIED: Replace requirement content
+   - ADDED: Append new requirements
+4. Update delta status to "applied"
+5. Move to archive/
+
+**Validation**:
+- Delta must be in "approved" status
+- No duplicate requirements in ADDED
+- MODIFIED/REMOVED targets must exist
+- RENAMED source must exist, target must not
+
+### status
+
+Check the status of a specific delta.
+
+```bash
+/flow:delta status "REQ-123" "add-2fa"
+```
+
+**Output**:
+```
+Delta: 2026-02-01-add-2fa
+Status: approved
+Created: 2026-02-01T10:00:00Z
+
+Changes:
+  ADDED:     2 requirements
+  MODIFIED:  1 requirement
+  REMOVED:   0 requirements
+  RENAMED:   1 requirement
+
+Validation:
+  ✓ All ADDED requirements are unique
+  ✓ All MODIFIED targets exist
+  ✓ All RENAMED sources exist
+  ✓ Ready to apply
+```
+
+## Delta Spec Format
+
+```markdown
+---
+delta_id: "2026-02-01-add-2fa"
+req_id: "REQ-123"
+title: "Add 2FA Support"
+created_at: "2026-02-01T10:00:00Z"
+status: "draft|review|approved|applied"
+---
+
+# Delta: Add 2FA Support
+
+## Summary
+Brief description of changes.
+
+## ADDED Requirements
+
+### Requirement: Two-Factor Authentication
+Description of the new requirement.
+
+#### Scenario: Enable 2FA
+- GIVEN user is logged in
+- WHEN user enables 2FA
+- THEN system generates QR code
+
+## MODIFIED Requirements
+
+### Requirement: User Login
+New description.
+(Previously: old description)
+
+## REMOVED Requirements
+
+### Requirement: Legacy Session
+**Reason**: Replaced by JWT
+**Migration**: Run migration script
+
+## RENAMED Requirements
+
+- FROM: Old Name
+- TO: New Name
+```
+
+## Status Workflow
+
+```
+draft → review → approved → applied
+  │       │         │
+  │       │         └── /flow:delta apply
+  │       │
+  │       └── Manual review approval
+  │
+  └── /flow:delta create
+```
+
+## Scripts
+
+| Script | Purpose |
+|--------|---------|
+| `flow-delta-create.sh` | Create delta directory and files |
+| `flow-delta-list.sh` | List all deltas for a requirement |
+| `flow-delta-apply.sh` | Apply delta to PRD.md |
+| `flow-delta-status.sh` | Check delta status |
+| `delta-parser.ts` | Parse and apply delta blocks |
+
+## Integration
+
+### With /flow:spec
+
+When `/flow:spec` modifies existing requirements, it can generate deltas:
+```
+PRD.md changes → deltas/{date}-{slug}/delta.md
+```
+
+### With /flow:release
+
+Before PR creation, `/flow:release` applies all approved deltas:
+```bash
+/flow:delta apply REQ-XXX --all
+```
+
+### With /flow:archive
+
+After release, `/flow:archive` includes applied deltas:
+```bash
+devflow/archive/{date}-REQ-XXX/deltas/
+```
+
+## Directory Structure
+
+```
+devflow/requirements/REQ-123/
+├── PRD.md                    # Main specification (SSOT)
+├── deltas/                   # Delta specs directory
+│   ├── 2026-02-01-add-2fa/
+│   │   ├── delta.md          # Delta specification
+│   │   └── tasks.md          # Delta-specific tasks
+│   └── 2026-02-05-fix-login/
+│       ├── delta.md
+│       └── tasks.md
+└── ...
+
+devflow/archive/
+└── 2026-02/
+    └── REQ-123/
+        └── deltas/           # Archived deltas
+            └── 2026-02-01-add-2fa/
+                └── delta.md
+```
+
+## Related
+
+- **Template**: `.claude/docs/templates/DELTA_SPEC_TEMPLATE.md`
+- **Parser**: `.claude/scripts/delta-parser.ts`
+- **Archive**: `devflow/archive/` - Historical delta specs