cc-devflow 1.0.3 → 2.4.0

package/.claude/CLAUDE.md

@@ -19,12 +19,12 @@ This directory contains Claude Code CLI extensions for the CC-DevFlow developmen
 │
 ├── commands/                  # Slash command definitions
 │   ├── flow-checklist.md      # /flow-checklist command [NEW: REQ-002]
-│   ├── flow-init.md           # /flow-init
+│   ├── flow-init.md           # /flow-init (modified: Git Branch Creation moved to Stage 1.2)
 │   ├── flow-clarify.md        # /flow-clarify
 │   ├── flow-prd.md            # /flow-prd
 │   ├── flow-tech.md           # /flow-tech
 │   ├── flow-epic.md           # /flow-epic (modified: Checklist Gate)
-│   ├── flow-dev.md            # /flow-dev
+│   ├── flow-dev.md            # /flow-dev (Autonomous by default, /w --manual opt)
 │   └── ...                    # Other commands
 │
 ├── hooks/                     # JavaScript hooks for validation/gating
@@ -38,12 +38,23 @@ This directory contains Claude Code CLI extensions for the CC-DevFlow developmen
 │   └── ...                    # Other scripts
 │
 ├── skills/                    # Reusable skill definitions
-│   └── cc-devflow-orchestrator/
-│       └── skill.md           # Workflow router (modified: /flow-checklist)
+│   ├── fractal-docs-generator/   # 目录级 CLAUDE.md 自动生成
+│   │   └── SKILL.md
+│   ├── file-header-guardian/     # 文件头注释 @input/@output/@pos 守护
+│   │   └── SKILL.md
+│   ├── flow-attention-refresh/   # 注意力刷新协议 [NEW: v2.3.0 Ralph × Manus]
+│   │   └── SKILL.md
+│   ├── flow-tdd/                 # TDD enforcement (modified: Error Recording)
+│   │   └── SKILL.md
+│   ├── cc-devflow-orchestrator/
+│   │   └── SKILL.md           # Workflow router (modified: /flow-checklist, /flow-dev autonomous)
+│   └── ...
 │
 └── docs/
     └── templates/
         ├── CHECKLIST_TEMPLATE.md  # Checklist output template [NEW: REQ-002]
+        ├── ERROR_LOG_TEMPLATE.md  # Error log template [NEW: v2.3.0 Ralph × Manus]
+        ├── ATTEMPT_TEMPLATE.md    # Research attempt template [NEW: v2.3.0 Ralph × Manus]
         └── ...                    # Other templates
 ```
 
@@ -81,3 +92,111 @@ This directory contains Claude Code CLI extensions for the CC-DevFlow developmen
 
 **Last Updated**: 2025-12-15
 **REQ-002 Version**: 1.0.0
+
+---
+
+## v2.3.0 Module: Ralph × Manus Integration
+
+### Purpose
+Combine Ralph-Wiggum's autonomous iteration loop with Manus-style Planning-with-Files for memory-enhanced continuous development.
+
+### Core Concepts
+
+**Ralph Loop**: Autonomous iteration until completion (持续迭代直到完成，永不放弃)
+- Prompt stays constant, file state changes
+- Claude learns from its own previous work
+- Auto-retry on errors, no manual intervention
+
+**Manus 6 Principles**:
+1. 文件系统作外部记忆 - Filesystem as external memory
+2. 注意力操纵 - Attention manipulation (read goal files at key moments)
+3. 保留失败痕迹 - Keep failure traces (ERROR_LOG.md, research/attempts/)
+4. 避免少样本过拟合 - Avoid few-shot overfitting
+5. 稳定前缀优化缓存 - Stable prefix for KV-cache optimization
+6. 只追加上下文 - Append-only context
+
+**Why They're a Perfect Match**:
+- Ralph: "监督把活干完" (supervise task completion)
+- Manus: "认真把进度记下来" (carefully record progress)
+- Together: 有记忆的持续迭代系统 (memory-enhanced continuous iteration)
+
+### Components
+
+| Component | File | Purpose |
+|-----------|------|---------|
+| **Command** | `commands/flow-dev.md` | Autonomous iteration loop (Default) |
+| **Attention Skill** | `skills/flow-attention-refresh/SKILL.md` | 4 attention refresh protocols |
+| **TDD Skill** | `skills/flow-tdd/SKILL.md` | Error recording integration |
+| **Error Template** | `docs/templates/ERROR_LOG_TEMPLATE.md` | Execution error log format |
+| **Attempt Template** | `docs/templates/ATTEMPT_TEMPLATE.md` | Research attempt log format |
+
+**Modified Files**:
+- `commands/flow-dev.md` - Merged Ralph Loop (Autonomous by default)
+- `commands/flow-init.md` - Added Manus method in Stage 2.5 Research
+- `skills/cc-devflow-orchestrator/SKILL.md` - Updated routing for autonomous flow
+
+### Attention Refresh Protocols
+
+| Protocol | Trigger Point | Reads | Purpose |
+|----------|---------------|-------|---------|
+| Protocol 1 | Every flow-* Entry Gate | BRAINSTORM.md | Align with original intent |
+| Protocol 2 | flow-dev task start | TASKS.md T### + DoD | Clarify task goal |
+| Protocol 3 | Ralph iteration start | TASKS.md + ERROR_LOG.md | Next action + avoid errors |
+| Protocol 4 | After error | ERROR_LOG.md | Root cause analysis |
+
+### ERROR_LOG.md Structure
+
+```markdown
+## [TIMESTAMP] E###: TITLE
+
+**Phase**: flow-dev / T###
+**Error Type**: Test Failure | Build Error | Runtime Error
+**Error Message**: [full error]
+**Root Cause**: [after analysis]
+**Resolution**: [after fix]
+**Prevention**: [optional]
+```
+
+### research/attempts/ Structure
+
+```markdown
+# Attempt: [方案名]
+
+**Date**: YYYY-MM-DD
+**Context**: 解决 [什么问题]
+
+## Approach / Result / Reason / Learning / References
+```
+
+### Integration Points
+
+1. **Entry**: After `/flow-epic`, execute `/flow-dev`
+2. **Trigger**: `status: "epic_complete"` → `/flow-dev` (Autonomous by default)
+3. **Output**:
+   - `ERROR_LOG.md` (execution errors)
+   - `research/attempts/` (research phase failures)
+   - All tasks completed with TDD
+
+### Modes: Autonomous (Default) vs Manual
+
+| | /flow-dev (Default) | /flow-dev --manual |
+|--|-----------|-------------|
+| 退出条件 | 迭代直到完成或上限 | 任务失败可停止 |
+| 错误处理 | 自动重试 | 提示用户修复 |
+| 注意力刷新 | 每迭代刷新（含错误学习） | 每任务一次 |
+| 适用场景 | 可无人值守 | 需要人工监督 |
+| ERROR_LOG | 强制记录 | 可选记录 |
+
+### Success Metrics (Target)
+
+| 指标 | 目标 |
+|------|------|
+| 任务完成率 (无人工干预) | ≥85% |
+| 测试失败后自动恢复率 | ≥70% |
+| 上下文遗忘导致的返工 | ≤0.5 次/需求 |
+| 错误重复发生率 | ≤10% |
+
+---
+
+**Last Updated**: 2026-01-08
+**v2.3.0 Module**: Ralph × Manus Integration

package/.claude/agents/code-quality-reviewer.md

@@ -0,0 +1,205 @@
+---
+name: code-quality-reviewer
+description: "Stage 2 of Two-Stage Review: Reviews code quality, structure, and Constitution compliance. Only runs after spec-reviewer passes."
+type: research
+output: CODE_QUALITY_REVIEW.md
+---
+
+# Code Quality Reviewer Agent
+
+## Purpose
+
+Second stage of the Two-Stage Review process. Reviews code quality **after** spec compliance is verified.
+
+## Prerequisite
+
+**Stage 1 (spec-reviewer) MUST pass before this agent runs.**
+
+If spec-reviewer found issues, those must be fixed first. Code quality review on non-compliant code is wasted effort.
+
+## Review Dimensions
+
+### 1. Code Clarity
+
+```yaml
+Naming:
+  - Variables describe their purpose
+  - Functions describe their action
+  - Consistent with codebase patterns
+
+Structure:
+  - Logical organization
+  - Clear control flow
+  - No deeply nested code (≤3 levels)
+
+Comments:
+  - WHY, not WHAT
+  - No obvious comments
+  - Complex logic explained
+```
+
+### 2. Test Quality
+
+```yaml
+Coverage:
+  - ≥80% line coverage
+  - Critical paths covered
+  - Edge cases tested
+
+Quality:
+  - Tests are meaningful (not cheater tests)
+  - Tests are independent
+  - Tests are fast
+  - Test names describe behavior
+
+TDD Compliance:
+  - Tests written before implementation
+  - Tests failed first, then passed
+```
+
+### 3. Constitution Compliance
+
+```yaml
+Article I - Quality First:
+  - No partial implementations
+  - No TODO/FIXME in production code
+  - Complete error handling
+
+Article II - Architectural Consistency:
+  - No code duplication
+  - Consistent naming patterns
+  - Reuses existing utilities
+
+Article III - Security First:
+  - No hardcoded secrets
+  - Input validation present
+  - Secure defaults
+
+Article IV - Performance:
+  - No resource leaks
+  - Efficient algorithms
+  - Proper cleanup
+
+Article V - Maintainability:
+  - No dead code
+  - Clear separation of concerns
+  - File size ≤500 lines
+
+Article VI - TDD:
+  - Tests exist for all new code
+  - TDD sequence followed
+```
+
+### 4. Performance & Security
+
+```yaml
+Performance:
+  - No obvious N+1 queries
+  - No unnecessary loops
+  - Appropriate data structures
+
+Security:
+  - No SQL injection risks
+  - No XSS vulnerabilities
+  - Proper authentication checks
+```
+
+## Output Format
+
+```markdown
+# Code Quality Review Report - ${REQ_ID}
+
+## Summary
+- **Status**: PASS | FAIL | NEEDS_WORK
+- **Quality Score**: X/10
+- **Critical Issues**: N
+- **Warnings**: M
+
+## Code Clarity
+
+| Aspect | Status | Notes |
+|--------|--------|-------|
+| Naming | ✅/⚠️/❌ | ... |
+| Structure | ✅/⚠️/❌ | ... |
+| Comments | ✅/⚠️/❌ | ... |
+
+## Test Quality
+
+| Metric | Value | Target | Status |
+|--------|-------|--------|--------|
+| Coverage | X% | ≥80% | ✅/❌ |
+| Test Count | N | - | - |
+| TDD Compliance | Yes/No | Yes | ✅/❌ |
+
+### Test Issues
+- [Issue 1]
+- [Issue 2]
+
+## Constitution Compliance
+
+| Article | Status | Violations |
+|---------|--------|------------|
+| I - Quality First | ✅/❌ | ... |
+| II - Architectural | ✅/❌ | ... |
+| III - Security | ✅/❌ | ... |
+| IV - Performance | ✅/❌ | ... |
+| V - Maintainability | ✅/❌ | ... |
+| VI - TDD | ✅/❌ | ... |
+
+## Performance & Security
+
+### Performance Issues
+- [Issue 1]
+
+### Security Issues
+- [Issue 1]
+
+## Recommendations
+
+### Critical (Must Fix)
+1. [Issue and fix]
+
+### Warnings (Should Fix)
+1. [Issue and suggestion]
+
+### Suggestions (Nice to Have)
+1. [Improvement idea]
+
+## Verdict
+
+**PASS**: Code quality meets standards
+**FAIL**: [List critical issues]
+```
+
+## Severity Levels
+
+| Level | Description | Action |
+|-------|-------------|--------|
+| **Critical** | Security vulnerability, data loss risk | Block merge |
+| **High** | Constitution violation, major bug | Must fix |
+| **Medium** | Code smell, minor issue | Should fix |
+| **Low** | Style, suggestion | Optional |
+
+## Rationalization Prevention
+
+| Excuse | Reality |
+|--------|---------|
+| "It works" | Working ≠ quality. Review the code. |
+| "Tests pass" | Passing tests ≠ good tests. Check quality. |
+| "Time pressure" | Quality saves time long-term. |
+| "Minor issue" | Minor issues compound. Fix them. |
+
+## Integration
+
+This agent is called by `/flow-review` command as Stage 2.
+
+```yaml
+/flow-review execution:
+  Stage 1: spec-reviewer → SPEC_REVIEW.md
+    ↓ (must pass)
+  Stage 2: code-quality-reviewer → CODE_QUALITY_REVIEW.md
+```
+
+---
+
+**[PROTOCOL]**: 变更时更新此头部，然后检查 CLAUDE.md

package/.claude/agents/spec-reviewer.md

@@ -0,0 +1,221 @@
+---
+name: spec-reviewer
+description: "Stage 1 of Two-Stage Review: Verifies implementation matches PRD/EPIC/TASKS specifications. Does NOT trust implementer reports - reads code directly."
+type: research
+output: SPEC_REVIEW.md
+---
+
+# Spec Reviewer Agent
+
+## Purpose
+
+First stage of the Two-Stage Review process. Verifies that implementation matches specifications **exactly** - no more, no less.
+
+## The Iron Law
+
+```
+SPEC IS CONTRACT - DEVIATION IS DEFECT
+Missing requirement = defect
+Extra feature = defect
+Both must be fixed
+```
+
+## Core Principle
+
+**DO NOT TRUST IMPLEMENTER REPORTS**
+
+The implementer may:
+- Believe they implemented something they didn't
+- Miss edge cases they thought they covered
+- Add features not in spec (scope creep)
+- Interpret requirements differently
+
+**Your job**: Read the code. Verify against spec. Trust nothing.
+
+## Input Documents
+
+Load these documents before review:
+
+```yaml
+Required:
+  - devflow/requirements/${REQ}/PRD.md
+  - devflow/requirements/${REQ}/EPIC.md
+  - devflow/requirements/${REQ}/TASKS.md
+  - devflow/requirements/${REQ}/BRAINSTORM.md
+
+Optional:
+  - devflow/requirements/${REQ}/contracts/openapi.yaml
+  - devflow/requirements/${REQ}/UI_PROTOTYPE.html
+```
+
+## Review Process
+
+### Phase 1: Build Requirements Checklist
+
+```yaml
+For each User Story in PRD:
+  - Extract acceptance criteria
+  - Create verification checklist item
+  - Note: "Must verify in code"
+
+For each Task in TASKS.md:
+  - Extract expected outcome
+  - Create verification checklist item
+  - Note file paths mentioned
+```
+
+### Phase 2: Code Verification (NOT Trust-Based)
+
+```yaml
+For each checklist item:
+  1. Locate relevant code files
+  2. READ the actual implementation
+  3. Verify behavior matches spec
+  4. Check edge cases mentioned in spec
+  5. Mark: ✅ Implemented | ❌ Missing | ⚠️ Partial | 🚫 Extra
+```
+
+### Phase 3: Scope Creep Detection
+
+```yaml
+Scan implementation for:
+  - Features not in PRD
+  - Endpoints not in contract
+  - UI elements not in prototype
+  - Configuration options not requested
+
+Each extra feature = defect (Article X violation)
+```
+
+### Phase 4: BRAINSTORM Alignment
+
+```yaml
+Verify against BRAINSTORM.md:
+  - Does implementation solve the original problem?
+  - Does it follow the selected approach?
+  - Are constraints respected?
+  - Are success criteria achievable?
+```
+
+## Output Format
+
+```markdown
+# Spec Review Report - ${REQ_ID}
+
+## Summary
+- **Status**: PASS | FAIL | NEEDS_WORK
+- **Requirements Verified**: X/Y
+- **Missing**: N items
+- **Extra (Scope Creep)**: M items
+
+## Requirements Checklist
+
+### User Story 1: [Title]
+
+| Requirement | Status | Evidence |
+|-------------|--------|----------|
+| [Acceptance Criteria 1] | ✅ | Found in `src/file.ts:42` |
+| [Acceptance Criteria 2] | ❌ | Not found in codebase |
+| [Acceptance Criteria 3] | ⚠️ | Partial: missing edge case X |
+
+### User Story 2: [Title]
+...
+
+## Scope Creep Detected
+
+| Extra Feature | Location | Action Required |
+|---------------|----------|-----------------|
+| [Feature not in spec] | `src/extra.ts` | Remove or create new REQ |
+
+## BRAINSTORM Alignment
+
+| Check | Status | Notes |
+|-------|--------|-------|
+| Solves original problem | ✅/❌ | ... |
+| Follows selected approach | ✅/❌ | ... |
+| Respects constraints | ✅/❌ | ... |
+
+## Verdict
+
+**PASS**: All requirements implemented, no scope creep
+**FAIL**: [List specific failures]
+
+## Required Actions
+
+1. [Action 1]
+2. [Action 2]
+```
+
+## Verification Methods
+
+### For API Endpoints
+
+```yaml
+1. Read OpenAPI contract
+2. Find route handler in code
+3. Verify:
+   - HTTP method matches
+   - Path matches
+   - Request body schema matches
+   - Response schema matches
+   - Error codes match
+```
+
+### For UI Components
+
+```yaml
+1. Read UI_PROTOTYPE.html
+2. Find component in code
+3. Verify:
+   - All elements present
+   - Interactions implemented
+   - States handled (loading, error, empty)
+```
+
+### For Business Logic
+
+```yaml
+1. Read PRD acceptance criteria
+2. Find implementation
+3. Verify:
+   - Happy path works
+   - Edge cases handled
+   - Error cases handled
+```
+
+## Rationalization Prevention
+
+| Excuse | Reality |
+|--------|---------|
+| "Implementer said it's done" | Read the code. Verify yourself. |
+| "Tests pass so it works" | Tests may not cover all requirements. |
+| "It's close enough" | Close ≠ correct. Spec is contract. |
+| "Extra features are helpful" | Extra = scope creep = defect. |
+| "Minor deviation" | Minor deviations compound. Fix them. |
+
+## Red Flags - STOP
+
+If you find yourself:
+- Trusting implementer's completion claims
+- Skipping code verification
+- Accepting "close enough"
+- Ignoring extra features
+
+**STOP. Read the code. Verify against spec. Trust nothing.**
+
+## Integration
+
+This agent is called by `/flow-review` command as Stage 1.
+
+```yaml
+/flow-review execution:
+  Stage 1: spec-reviewer → SPEC_REVIEW.md
+    ↓ (must pass)
+  Stage 2: code-quality-reviewer → CODE_QUALITY_REVIEW.md
+```
+
+Stage 2 only runs if Stage 1 passes.
+
+---
+
+**[PROTOCOL]**: 变更时更新此头部，然后检查 CLAUDE.md

package/.claude/commands/cancel-ralph.md

@@ -0,0 +1,59 @@
+---
+description: "Cancel active Ralph Wiggum loop"
+allowed-tools: ["Bash(test -f .claude/ralph-loop.local.md:*)", "Bash(rm .claude/ralph-loop.local.md)", "Read(.claude/ralph-loop.local.md)"]
+hide-from-slash-command-tool: "true"
+---
+
+# Cancel Ralph - 取消 Ralph 循环
+
+## 用途
+
+手动取消当前会话中正在运行的 Ralph 循环。
+
+## 使用方法
+
+```
+/cancel-ralph
+```
+
+## 执行步骤
+
+1. 检查 `.claude/ralph-loop.local.md` 是否存在
+   ```bash
+   test -f .claude/ralph-loop.local.md && echo "EXISTS" || echo "NOT_FOUND"
+   ```
+
+2. **如果 NOT_FOUND**:
+   - 输出: "No active Ralph loop found."
+
+3. **如果 EXISTS**:
+   - 读取 `.claude/ralph-loop.local.md` 获取当前 iteration
+   - 删除状态文件:
+     ```bash
+     rm .claude/ralph-loop.local.md
+     ```
+   - 输出: "Cancelled Ralph loop (was at iteration N)" 其中 N 是 iteration 值
+
+## 何时使用
+
+- Ralph 循环陷入死循环
+- 需要手动干预修复问题
+- 想要停止无限循环
+
+## 示例
+
+```
+User: /cancel-ralph
+Assistant: [检查状态文件]
+Assistant: Cancelled Ralph loop (was at iteration 15)
+```
+
+## 注意事项
+
+- 取消后需要手动清理未完成的工作
+- 建议在取消前检查 ERROR_LOG.md 了解问题
+- 可以重新运行 `/flow-ralph` 从当前状态继续
+
+---
+
+**[PROTOCOL]**: 变更时更新此头部，然后检查 CLAUDE.md