--- name: GudaSpec: Init description: Initialize GudaSpec environment with directory structure and MCP tools validation. category: GudaSpec tags: [gudaspec, init, setup, mcp, rpi] --- ## Purpose 初始化GudaSpec环境，创建目录结构，验证MCP工具可用性，输出GudaSpec简介。 ## Guardrails - Detect the current operating system and adapt commands accordingly. - Do not proceed to the next step until the current step completes successfully. - Provide clear, actionable error messages when a step fails. - Respect user's existing configurations and avoid overwriting without confirmation. --- ## Steps ### Step 1: Detect Environment ```bash # 检测操作系统 uname -s 2>/dev/null || echo "Windows" # 检测当前目录 pwd ``` Report detected environment: ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 🔍 环境检测 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ | 项目 | 检测结果 | |------|----------| | 操作系统 | | | 当前目录 | | | Git仓库 | | ``` --- ### Step 2: Check Existing GudaSpec Installation ```bash # 检查是否已存在gudaspec目录 if [ -d "gudaspec" ]; then echo "GUDASPEC_EXISTS=true" ls -la gudaspec/ else echo "GUDASPEC_EXISTS=false" fi ``` **If gudaspec/ exists:** ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ⚠️ 检测到已有GudaSpec安装 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 现有目录结构: gudaspec/ ├── research/ (个需求) ├── plans/ (个计划) └── archive/ (个归档) ``` Use `AskUserQuestions`: ``` question: "如何处理现有安装？" options: [ "保留现有数据，仅验证MCP工具", "重新初始化（现有数据将移动到backup/）", "取消初始化" ] ``` --- ### Step 3: Create GudaSpec Directory Structure ```bash # 创建目录结构 mkdir -p gudaspec/{research,plans,archive} # 创建初始化标记文件 cat > gudaspec/.gudaspec.json << 'EOF' { "version": "1.0.0", "initialized_at": "", "initialized_by": "claude", "test_level_default": 1 } EOF ``` Verify creation: ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 📁 目录结构创建 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ gudaspec/ ├── .gudaspec.json ✅ 配置文件 ├── research/ ✅ 研究文档目录 ├── plans/ ✅ 计划文档目录 └── archive/ ✅ 归档目录 目录结构创建: ✅ 完成 ``` --- ### Step 4: Validate MCP Tools Availability Check each required MCP tool: ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 🔧 MCP工具验证 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` **Check Codex MCP:** - Attempt to invoke `mcp__codex__codex` with a simple test query - Record availability status **Check Gemini MCP:** - Attempt to invoke `mcp__gemini__gemini` with a simple test query - Record availability status **Check Grok Search MCP:** - Attempt to invoke `mcp__grok-search` with a simple test query - Record availability status **Display results:** ``` | MCP工具 | 状态 | 用途 | |---------|------|------| | mcp__codex__codex | ✅ / ❌ | 后端逻辑实现与审查 | | mcp__gemini__gemini | ✅ / ❌ | 前端UI实现与审查 | | mcp__grok-search | ✅ / ❌ | 实时在线搜索 | ``` **For each unavailable tool, display installation instructions:** ``` 【缺失工具安装指南】 ❌ mcp__codex__codex 不可用 用途: GudaSpec使用Codex作为后端逻辑实现引擎和代码审查器 安装: https://github.com/GuDaStudio/codexmcp ❌ mcp__gemini__gemini 不可用 用途: GudaSpec使用Gemini作为前端UI设计引擎和代码审查器 安装: https://github.com/GuDaStudio/geminimcp ❌ mcp__grok-search 不可用 用途: GudaSpec使用Grok Search进行实时在线文档搜索 安装: https://github.com/GuDaStudio/GrokSearch ``` --- ### Step 5: Summary Report ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 📊 初始化总结 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 【环境状态】 | 项目 | 状态 | |------|------| | GudaSpec目录 | ✅ 已创建 | | mcp__codex__codex | ✅ / ❌ | | mcp__gemini__gemini | ✅ / ❌ | | mcp__grok-search | ✅ / ❌ | 【功能可用性】 | 功能 | 状态 | 依赖 | |------|------|------| | 内部研究 (Research) | ✅ | - | | 外部调研 (Deep Research) | ✅ / ⚠️ | Grok Search | | 计划制定 (Plan) | ✅ | - | | 后端实现 | ✅ / ⚠️ | Codex | | 前端实现 | ✅ / ⚠️ | Gemini | | 多模型审查 | ✅ / ⚠️ | Codex + Gemini | ⚠️ = 功能可用但体验受限（缺少对应MCP工具） ``` **If any tools missing:** ``` 【待处理事项】 请安装缺失的MCP工具以获得完整功能： 1. — 2. ... ``` --- ### Step 7: Output GudaSpec Introduction ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GudaSpec 简介 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GudaSpec 是基于 RPI (Research-Plan-Implementation) 编码理论的 Claude Code 自定义命令集，融合多模型协作与TDD测试驱动开发，专为复杂场景设计。 ┌─────────────────────────────────────────────────────────────────────────────┐ │ 核心理念 │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ 📊 RPI工作流 │ │ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │ │ │ RESEARCH │───▶│ PLAN │───▶│ IMPLEMENT │ │ │ │ 需求研究 │ │ 计划制定 │ │ 代码实现 │ │ │ └───────────────┘ └───────────────┘ └───────────────┘ │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ 约束集文档 规格文档 可运行代码 │ │ │ │ 🎯 核心原则 │ │ • 有效上下文专注 — 通过阶段分离极致利用上下文窗口（保持40-60%利用率） │ │ • 频繁意向压缩 — 每阶段产出紧凑文档，/clear后作为下阶段种子 │ │ • 高杠杆审查点 — 审查规格而非代码，一行错误规格=百行错误代码 │ │ │ │ 🔧 多模型协作 │ │ • Codex — 后端逻辑实现与审查 │ │ • Gemini — 前端UI实现与审查 │ │ • Grok — 实时在线搜索与文档查询 │ │ • 双模型LGTM — 交叉审查确保代码质量 │ │ │ │ 🧪 TDD测试驱动（可选） │ │ • Level 0: 标准验证（Success Criteria） │ │ • Level 1: TDD模式（Red-Green-Refactor） │ │ • Level 2: TDD + Property Testing（发现边界情况） │ │ │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────┐ │ 命令速查 │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ 【Research阶段】将需求转化为约束集 │ │ ┌─────────────────────────────────────────────────────────────────────────┐│ │ │ /gudaspec:research │ 内部研究：分析代码库约束 ││ │ │ /gudaspec:research-review │ 内部审查：确认约束，判断是否需外部 ││ │ │ /gudaspec:deepresearch │ 外部研究：调研技术选型与最佳实践 ││ │ │ /gudaspec:deep-research-review │ 外部审查：确认选型，生成需求文档 ││ │ └─────────────────────────────────────────────────────────────────────────┘│ │ ↓ /clear │ │ 【Plan阶段】将需求转化为零决策规格 │ │ ┌─────────────────────────────────────────────────────────────────────────┐│ │ │ /gudaspec:plan │ 结构设计：Phase划分，测试策略选择 ││ │ │ /gudaspec:plan-review │ 详细规格：接口定义，测试规格，审批 ││ │ └─────────────────────────────────────────────────────────────────────────┘│ │ ↓ /clear │ │ 【Implementation阶段】执行规格产出代码 │ │ ┌─────────────────────────────────────────────────────────────────────────┐│ │ │ /gudaspec:implementation [Phase N] ││ │ │ • TDD循环：RED（写测试）→ GREEN（写实现）→ REFACTOR（审查优化） ││ │ │ • 多模型协作：Codex实现后端，Gemini实现前端，交叉审查 ││ │ │ • 逐Phase执行，每Phase后暂停等待人工确认 ││ │ └─────────────────────────────────────────────────────────────────────────┘│ │ │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────┐ │ 目录结构 │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ gudaspec/ │ │ ├── research/ # 研究文档 │ │ │ └── / │ │ │ ├── internal.md # 内部研究（代码库约束） │ │ │ ├── external.md # 外部研究（技术选型） │ │ │ └── requirement.md # 最终需求文档 │ │ ├── plans/ # 计划文档 │ │ │ └── / │ │ │ ├── structure.md # 计划结构 │ │ │ ├── plan.md # 详细计划 │ │ │ └── tests/ # 测试规格 │ │ └── archive/ # 已完成需求归档 │ │ └── -/ │ │ │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────┐ │ 典型工作流 │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ 简单需求（Bug修复、小改动）: │ │ /gudaspec:research → 描述需求 │ │ /clear → /gudaspec:research-review → 跳过外部 → requirement.md │ │ /clear → /gudaspec:plan │ │ /clear → /gudaspec:plan-review │ │ /clear → /gudaspec:implementation │ │ │ │ 复杂需求（新功能、新技术）: │ │ /gudaspec:research → 描述需求 │ │ /clear → /gudaspec:research-review → 需要外部 │ │ /clear → /gudaspec:deepresearch │ │ /clear → /gudaspec:deep-research-review → requirement.md │ │ /clear → /gudaspec:plan │ │ /clear → /gudaspec:plan-review │ │ /clear → /gudaspec:implementation │ │ │ └─────────────────────────────────────────────────────────────────────────────┘ ``` --- ### Step 8: Next Steps ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ✅ GudaSpec 初始化完成 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 📋 下一步操作: 1. 输入 /clear 清空当前上下文 （初始化信息较多，清空后开始新任务更高效） 2. 开始您的第一个需求: 输入 /gudaspec:research 然后描述您的需求 💡 提示: • 每个阶段完成后记得 /clear 保持上下文干净 • 简单需求可跳过外部研究阶段 • 使用 Level 1 TDD模式可获得更高代码质量 • 多模型审查会自动进行，无需手动触发 📚 参考资源: • RPI理论: https://github.com/humanlayer/humanlayer • GudaSpec命令集: https://github.com/GuDaStudio/commands • Codex MCP: https://github.com/GuDaStudio/codexmcp • Gemini MCP: https://github.com/GuDaStudio/geminimcp • Grok Search: https://github.com/GuDaStudio/GrokSearch ``` --- ## Exit Criteria - [ ] Operating system detected - [ ] gudaspec/ directory structure created - [ ] .gudaspec.json configuration file created - [ ] All MCP tools checked and status reported - [ ] Summary report displayed - [ ] GudaSpec introduction output - [ ] User directed to /clear and /gudaspec:research --- ## Reference - GudaSpec Commands: https://github.com/GuDaStudio/commands - HumanLayer RPI: https://github.com/humanlayer/humanlayer - Codex MCP: https://github.com/GuDaStudio/codexmcp - Gemini MCP: https://github.com/GuDaStudio/geminimcp - Grok Search: https://github.com/GuDaStudio/GrokSearch