cc-devflow 4.3.0 → 4.5.0

package/.claude/commands/core/architecture.md

@@ -1,459 +0,0 @@
----
-name: core-architecture
-description: 'Generate or update ARCHITECTURE.md with 4 architecture diagrams. Usage: /core-architecture'
-scripts:
-  sync_progress: .claude/scripts/sync-roadmap-progress.sh
----
-
-# Flow-Architecture - 架构文档生成命令
-
-## 命令格式
-```text
-/core-architecture              # Generate or update architecture documentation
-/core-architecture --force      # Force regenerate even if ARCHITECTURE.md exists
-```
-
-## 核心原则
-
-**这是一个简化的命令，专注于架构文档生成。**
-**适用场景**: ROADMAP.md 已存在，需要生成或更新架构图。
-
-### 架构模式
-```
-用户
-  ↓
-core-architecture (minimal interaction)
-  ↓
-architecture-designer (research, no dialogue)
-  ↓
-ARCHITECTURE.md (4 diagrams)
-```
-
-## Harness Engineering 增强（Long-running Session Protocol）
-
-为防止跨上下文窗口后出现“图表半生成、ADR 丢失、误判已完成”，执行分为 Initializer 与 Worker 两类会话。
-
-### Phase 0: Initializer Session（首次或 --force）
-
-先建立/刷新架构任务工件（不要一次性生成整份文档）：
-- `devflow/.core-harness/architecture/checklist.json`
-  - 列出 4 张图、ADR、NFR、演进路径等验收项，默认 `passes=false`
-- `devflow/.core-harness/architecture/progress.md`
-  - 记录本次修改、风险、下一步
-- `devflow/.core-harness/architecture/init.md`
-  - 固定启动流程（读取 ROADMAP、读取最近进展、执行 Mermaid 冒烟验证）
-
-### Worker Session（增量交付）
-
-每个窗口只处理一个子目标，例如：
-- 只完成一张 Mermaid 图并自检语法
-- 只补齐 ADR 与对应图表映射
-- 只修复依赖图节点/边一致性问题
-
-会话收尾要求：
-1. 运行当前文档校验（占位符、图表数量、语法）
-2. 更新 checklist 的 `passes` 字段
-3. 写入 progress/handoff，明确下一窗口优先任务
-
-### Done Gate
-
-`checklist.json` 全绿 + Phase 4 校验通过，才可输出成功报告。
-
-## 执行流程
-
-### Phase 1: Prerequisites Check
-
-**目标**: 确保有足够的上下文生成架构文档
-
-```
-1. 检查 devflow/ROADMAP.md 是否存在
-   → 不存在:
-      ERROR: "ROADMAP.md not found at: devflow/ROADMAP.md"
-      ""
-      "Architecture generation requires a roadmap first."
-      "Please run /core-roadmap to create a roadmap."
-      ""
-      EXIT
-
-   → 存在:
-      ✓ 继续
-
-2. 检查 devflow/ARCHITECTURE.md 是否存在
-   → 存在且未使用 --force:
-      PROMPT: "ARCHITECTURE.md already exists."
-      "Do you want to regenerate it? (yes/no)"
-      "This will overwrite the existing file."
-      ""
-      用户输入 'no' → EXIT
-      用户输入 'yes' → 继续
-
-   → 不存在或使用 --force:
-      ✓ 继续
-
-3. 扫描项目结构
-   → 检查 devflow/requirements/ 目录
-   → 至少有 1 个需求目录推荐（不强制）
-   → 如果没有: WARN "No requirements found. Architecture will be basic."
-
-4. 检查 devflow/project.md
-   → 存在: ✓ 将用于提取项目信息
-   → 不存在: WARN "project.md not found. Will infer from requirements."
-```
-
-### Phase 2: Context Summary
-
-**目标**: 向用户展示将要使用的上下文
-
-```
-展示上下文摘要:
-
-"==================================================================="
-"Architecture Documentation Generation"
-"==================================================================="
-""
-"📊 Context Analysis:"
-""
-"✓ ROADMAP.md found"
-"  - Roadmap Items: {rm_count} (RM-IDs)"
-"  - Milestones: {milestone_count}"
-"  - Dependencies: {dependency_count}"
-""
-If project.md exists:
-  "✓ project.md found"
-  "  - Project: {project_name}"
-  "  - Tech Stack: {tech_stack_summary}"
-Else:
-  "⚠ project.md not found (will infer from requirements)"
-""
-If requirements exist:
-  "✓ Requirements found: {req_count}"
-  "  - Completed: {completed_count}"
-  "  - In Progress: {in_progress_count}"
-  "  - Planned: {planned_count}"
-Else:
-  "⚠ No requirements found"
-""
-"📐 Diagrams to Generate:"
-"  1. Feature Architecture (功能架构图)"
-"  2. Technical Architecture (技术架构图)"
-"  3. Module Structure (模块划分图)"
-"  4. Requirement Dependency (需求依赖图)"
-""
-"Ready to generate? (yes/no)"
-
-用户输入 'yes' → Phase 3
-用户输入 'no' → EXIT
-```
-
-### Phase 3: Call architecture-designer Agent
-
-**目标**: 调用 Agent 生成架构文档
-
-```
-🤖 Agent 调用:
-
-1. 提示:
-   "Generating architecture documentation..."
-   ""
-   "This may take a moment as we analyze:"
-   "  - ROADMAP.md content"
-   "  - Requirements and tech designs"
-   "  - Codebase structure"
-   ""
-
-2. 使用 Task tool 调用 architecture-designer:
-   description: "Generate ARCHITECTURE.md with 4 diagrams"
-   subagent_type: "architecture-designer"
-   model: "sonnet" (或 inherit)
-   prompt: "生成完整的项目架构文档。
-
-   数据源:
-   - devflow/ROADMAP.md (必须)
-   - devflow/requirements/REQ-*/TECH_DESIGN.md (如果存在)
-   - devflow/project.md (如果存在)
-   - src/, .claude/, devflow/ 目录结构
-
-   请按照 .claude/docs/templates/ARCHITECTURE_TEMPLATE.md 的 Execution Flow 执行。
-
-   生成完整的 devflow/ARCHITECTURE.md 文件，包含:
-   1. Feature Architecture (功能架构图) - 基于 ROADMAP.md 的 RM-IDs
-   2. Technical Architecture (技术架构图) - 基于技术栈分析
-   3. Module Structure (模块划分图) - 基于实际目录结构
-   4. Requirement Dependency (需求依赖图) - 基于依赖关系
-
-   所有 Mermaid 图表必须语法正确，node IDs 不能包含空格或破折号。
-
-   至少提供 1 条 Architecture Decision Record (ADR)。"
-
-3. 等待 Agent 完成
-   → 显示进度提示 (可选):
-      "Analyzing project structure..."
-      "Extracting tech stack..."
-      "Generating diagrams..."
-      "Validating Mermaid syntax..."
-
-4. Agent 返回后，检查结果
-```
-
-### Phase 4: Validation
-
-**目标**: 验证生成的架构文档质量
-
-```
-📋 文件验证:
-
-1. 检查文件存在
-   → devflow/ARCHITECTURE.md 必须存在
-   → 否则: ERROR "Architecture file was not generated"
-
-2. 检查文件大小
-   → 文件大小 > 1000 bytes (合理的最小值)
-   → 否则: WARN "Generated file seems too small, may be incomplete"
-
-3. 检查占位符
-   → 搜索 {{PLACEHOLDER}} 或 {{...}}
-   → 如果找到: ERROR "Generated file contains placeholders: {list}"
-
-4. 检查 Mermaid 图表
-   → 搜索 ```mermaid 代码块
-   → 应该有 4 个 Mermaid 代码块
-   → 如果少于 4: WARN "Expected 4 diagrams, found {count}"
-
-5. 基本语法检查 (可选，简单验证)
-   → 检查每个 Mermaid 块:
-      • 是否包含 graph 或 flowchart 声明
-      • 是否有明显的语法错误 (未闭合括号等)
-   → 如果发现问题: WARN "Potential syntax issues in diagrams"
-
-验证通过 → Phase 5
-验证失败 → 显示错误并建议手动检查
-```
-
-### Phase 5: Success Report
-
-**目标**: 向用户报告成功并提供后续步骤
-
-```
-🎉 成功报告:
-
-"==================================================================="
-"Architecture Documentation Generated Successfully!"
-"==================================================================="
-""
-"📁 Output File:"
-"  ✓ devflow/ARCHITECTURE.md ({file_size} bytes)"
-""
-"📐 Diagrams Generated:"
-"  ✓ 1. Feature Architecture (功能架构图)"
-"     - Core modules: {core_count}"
-"     - Business modules: {business_count}"
-"     - Support modules: {support_count}"
-""
-"  ✓ 2. Technical Architecture (技术架构图)"
-"     - Layers: {layer_count}"
-"     - Technologies: {tech_count}"
-""
-"  ✓ 3. Module Structure (模块划分图)"
-"     - Directories: {dir_count}"
-"     - Key modules: {module_list}"
-""
-"  ✓ 4. Requirement Dependency (需求依赖图)"
-"     - Total nodes: {node_count}"
-"     - Completed REQs: {completed_count}"
-"     - Planned RMs: {planned_count}"
-""
-"📊 Additional Content:"
-"  ✓ Architecture Decision Records: {adr_count}"
-"  ✓ Non-Functional Requirements: {nfr_sections}"
-"  ✓ Architecture Evolution Path: {evolution_phases}"
-""
-"🎯 Next Steps:"
-"  1. Open devflow/ARCHITECTURE.md in your editor"
-"  2. Verify all Mermaid diagrams render correctly"
-"  3. Review Architecture Decision Records (ADRs)"
-"  4. Update ADRs when making architectural changes"
-""
-"💡 Tips:"
-"  - Use a Markdown viewer with Mermaid support to preview diagrams"
-"  - Regenerate architecture when:"
-"    • New requirements are added to roadmap"
-"    • Major tech stack changes occur"
-"    • Module structure changes significantly"
-"  - Keep ADRs up-to-date for team alignment"
-""
-"To regenerate: /core-architecture --force"
-""
-"==================================================================="
-```
-
-## 错误处理
-
-### 常见错误及处理
-
-1. **ROADMAP.md 不存在**:
-   ```
-   ERROR: "ROADMAP.md not found at: devflow/ROADMAP.md"
-   ""
-   "Architecture generation requires a roadmap first."
-   "Please run /core-roadmap to create a roadmap."
-   ""
-   "If you want to create a basic architecture without a roadmap,"
-   "consider creating a minimal ROADMAP.md manually or using /core-roadmap."
-   ```
-
-2. **Agent 调用失败**:
-   ```
-   ERROR: "Architecture generation failed: {error_message}"
-   ""
-   "Possible causes:"
-   "  - Insufficient context (no requirements or tech designs)"
-   "  - Invalid ROADMAP.md format"
-   "  - File system permissions"
-   ""
-   "Please check the error message above and:"
-   "  1. Verify ROADMAP.md is valid"
-   "  2. Ensure at least 1 requirement exists (recommended)"
-   "  3. Check file permissions"
-   ""
-   "Retry with: /core-architecture --force"
-   ```
-
-3. **生成文件包含占位符**:
-   ```
-   ERROR: "Generated ARCHITECTURE.md contains placeholders"
-   ""
-   "Found: {list_of_placeholders}"
-   ""
-   "This indicates incomplete generation. Possible causes:"
-   "  - Missing required context"
-   "  - Agent execution error"
-   ""
-   "Please report this issue and include:"
-   "  - Contents of devflow/ROADMAP.md"
-   "  - Number of requirements in devflow/requirements/"
-   "  - Whether project.md exists"
-   ```
-
-4. **Mermaid 语法错误** (如果能检测到):
-   ```
-   WARN: "Potential Mermaid syntax errors detected"
-   ""
-   "Diagram: {diagram_name}"
-   "Issue: {description}"
-   ""
-   "The file has been generated, but please manually review:"
-   "  {line_number}: {problematic_line}"
-   ""
-   "Common fixes:"
-   "  - Ensure node IDs have no spaces (use camelCase)"
-   "  - Check all brackets are closed"
-   "  - Verify arrow syntax (use --> not ->)"
-   ```
-
-## 与其他命令的集成
-
-### 在 /core-roadmap 中的调用
-```
-/core-roadmap 在 Stage 7 会自动调用 architecture-designer
-无需单独运行 /core-architecture
-```
-
-### 在 /flow:init 中的使用
-```
-/flow:init 可以读取 ARCHITECTURE.md 获取上下文:
-  - 查看需求在架构中的位置
-  - 了解相关模块和依赖
-  - 参考 ADR 做技术决策
-```
-
-### 手动更新架构
-```
-When to run /core-architecture manually:
-  - ROADMAP.md 更新后
-  - 新增重要需求后
-  - 技术栈变化后
-  - 模块结构调整后
-```
-
-## 输出
-
-### 文件输出
-- `devflow/ARCHITECTURE.md`: 完整架构文档（含 4 种架构图和 ADRs）
-
-### 不更新的文件
-- `devflow/ROADMAP.md`: 不变
-- `devflow/BACKLOG.md`: 不变
-- 需求目录: 不变
-
-## 性能考虑
-
-- **执行时间**: 通常 30-60 秒（取决于项目规模）
-- **Agent 使用**: architecture-designer（研究型，sonnet 模型）
-- **文件读取**: ROADMAP.md, project.md, TECH_DESIGN.md 文件, 目录结构
-- **文件写入**: 仅 ARCHITECTURE.md
-
-## 高级功能
-
-### --force 模式
-```
-/core-architecture --force
-
-行为:
-  - 跳过 "文件已存在" 确认
-  - 直接覆盖现有 ARCHITECTURE.md
-  - 适用于 CI/CD 或自动化场景
-```
-
-### 可能的未来扩展
-```
-1. --diagrams-only: 只更新图表部分，保留 ADRs
-2. --validate-only: 只验证现有 ARCHITECTURE.md，不生成
-3. --export-diagrams: 导出 Mermaid 图表为独立文件
-```
-
-## 使用场景
-
-### 场景 1: 首次生成架构文档
-```
-前提: 已完成 /core-roadmap
-操作: /core-architecture
-结果: 生成包含 4 种架构图的完整文档
-```
-
-### 场景 2: 更新现有架构文档
-```
-前提: ARCHITECTURE.md 已存在，ROADMAP 有更新
-操作: /core-architecture
-提示: 确认覆盖
-结果: 重新生成架构文档，反映最新状态
-```
-
-### 场景 3: 自动化/CI 场景
-```
-前提: 在 CI pipeline 中
-操作: /core-architecture --force
-结果: 无交互，直接生成/覆盖
-```
-
-## 最佳实践
-
-1. **何时生成架构文档**:
-   - 创建路线图后立即生成（/core-roadmap 会自动调用）
-   - 每个季度开始时更新
-   - 重大架构决策后更新
-
-2. **如何维护架构文档**:
-   - 保持 ADRs 更新
-   - 新增重要技术决策时补充 ADR
-   - 定期验证图表与实际代码一致性
-
-3. **如何审查架构文档**:
-   - 用 Markdown 预览器查看
-   - 确认 4 种图表都能正确渲染
-   - 检查依赖关系是否准确
-   - 验证技术栈描述与实际一致
-
-4. **团队协作**:
-   - 架构文档入版本库
-   - 架构变更需要团队 review
-   - ADRs 作为技术决策的记录和沟通工具