mirror of
https://github.com/GuDaStudio/commands.git
synced 2026-03-22 19:18:52 +08:00
v1.0：gudaspec正式版，不再依赖于openspec
This commit is contained in:
GuDaStudio
409
gudaspec/init.md
409
gudaspec/init.md
@@ -1,59 +1,376 @@
|
||||
---
|
||||
name: GudaSpec: Init
|
||||
description: Initialize OpenSpec environment with MCP tools validation for the current project.
|
||||
description: Initialize GudaSpec environment with directory structure and MCP tools validation.
|
||||
category: GudaSpec
|
||||
tags: [openspec, init, setup, mcp]
|
||||
tags: [gudaspec, init, setup, mcp, rpi]
|
||||
---
|
||||
<!-- GUDASPEC:START -->
|
||||
**Guardrails**
|
||||
- Detect the current operating system (Linux, macOS, Windows) and adjust shell commands accordingly.
|
||||
- All example commands below assume a Linux/Unix environment; adapt syntax for PowerShell on Windows if detected.
|
||||
|
||||
<!-- GUDASPEC:INIT:START -->
|
||||
|
||||
## 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**
|
||||
1. **Detect Operating System**
|
||||
- Identify the current OS using appropriate methods (`uname -s` on Unix-like systems, or environment variables on Windows).
|
||||
- Inform the user which OS was detected and note any command adaptations that will be made.
|
||||
---
|
||||
|
||||
2. **Check and Install OpenSpec**
|
||||
- Verify if `openspec` CLI is installed by running `openspec --version` or `which openspec` (Linux/macOS) / `where openspec` (Windows).
|
||||
- If not installed, install globally using:
|
||||
```bash
|
||||
npm install -g @fission-ai/openspec@latest
|
||||
```
|
||||
- On Windows, use the same npm command in PowerShell or Command Prompt.
|
||||
- Confirm installation success by running `openspec --version` after installation.
|
||||
## Steps
|
||||
|
||||
3. **Initialize OpenSpec for Current Project**
|
||||
- Run the initialization command:
|
||||
```bash
|
||||
openspec init --tools claude
|
||||
```
|
||||
- Verify that `openspec/` directory structure is created successfully.
|
||||
- Report any initialization errors and suggest remediation steps.
|
||||
### Step 1: Detect Environment
|
||||
|
||||
4. **Validate MCP Tools Availability**
|
||||
- Check if `mcp__codex__codex` tool is available and responsive.
|
||||
- Check if `mcp__gemini__gemini` tool is available and responsive.
|
||||
- For each unavailable tool, display a clear warning message with installation instructions:
|
||||
- **Codex MCP**: "The `mcp__codex__codex` tool is not available. Please install it from: https://github.com/GuDaStudio/codexmcp"
|
||||
- **Gemini MCP**: "The `mcp__gemini__gemini` tool is not available. Please install it from: https://github.com/GuDaStudio/geminimcp"
|
||||
- Explain that these MCP tools will be required for subsequent GudaSpec workflows.
|
||||
```bash
|
||||
# 检测操作系统
|
||||
uname -s 2>/dev/null || echo "Windows"
|
||||
|
||||
5. **Summary Report**
|
||||
- Display a summary of the initialization status:
|
||||
- OpenSpec installation: ✓/✗
|
||||
- Project initialization: ✓/✗
|
||||
- `mcp__codex__codex` availability: ✓/✗
|
||||
- `mcp__gemini__gemini` availability: ✓/✗
|
||||
- If any components are missing, list the required actions before proceeding with other GudaSpec commands.
|
||||
# 检测当前目录
|
||||
pwd
|
||||
```
|
||||
|
||||
**Reference**
|
||||
- OpenSpec CLI documentation: Run `openspec --help` for available commands.
|
||||
- Codex MCP installation: https://github.com/GuDaStudio/codexmcp
|
||||
- Gemini MCP installation: https://github.com/GuDaStudio/geminimcp
|
||||
- For Node.js/npm issues, ensure Node.js >= 18.x is installed.
|
||||
- On permission errors during global npm install, consider using `sudo` (Linux/macOS) or running terminal as Administrator (Windows), or configure npm to use a user-writable directory.
|
||||
<!-- GUDASPEC:END -->
|
||||
Report detected environment:
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
🔍 环境检测
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
| 项目 | 检测结果 |
|
||||
|------|----------|
|
||||
| 操作系统 | <OS> |
|
||||
| 当前目录 | <path> |
|
||||
| Git仓库 | <yes/no> |
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 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/ (<N>个需求)
|
||||
├── plans/ (<N>个计划)
|
||||
└── archive/ (<N>个归档)
|
||||
```
|
||||
|
||||
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": "<ISO timestamp>",
|
||||
"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. <missing tool> — <installation url>
|
||||
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 <id> │ 内部审查：确认约束，判断是否需外部 ││
|
||||
│ │ /gudaspec:deepresearch <id> │ 外部研究：调研技术选型与最佳实践 ││
|
||||
│ │ /gudaspec:deep-research-review <id> │ 外部审查：确认选型，生成需求文档 ││
|
||||
│ └─────────────────────────────────────────────────────────────────────────┘│
|
||||
│ ↓ /clear │
|
||||
│ 【Plan阶段】将需求转化为零决策规格 │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────────┐│
|
||||
│ │ /gudaspec:plan <requirement.md> │ 结构设计：Phase划分，测试策略选择 ││
|
||||
│ │ /gudaspec:plan-review <id> │ 详细规格：接口定义，测试规格，审批 ││
|
||||
│ └─────────────────────────────────────────────────────────────────────────┘│
|
||||
│ ↓ /clear │
|
||||
│ 【Implementation阶段】执行规格产出代码 │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────────┐│
|
||||
│ │ /gudaspec:implementation <plan.md> [Phase N] ││
|
||||
│ │ • TDD循环：RED（写测试）→ GREEN（写实现）→ REFACTOR（审查优化） ││
|
||||
│ │ • 多模型协作：Codex实现后端，Gemini实现前端，交叉审查 ││
|
||||
│ │ • 逐Phase执行，每Phase后暂停等待人工确认 ││
|
||||
│ └─────────────────────────────────────────────────────────────────────────┘│
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────────────────┘
|
||||
|
||||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||||
│ 目录结构 │
|
||||
├─────────────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ gudaspec/ │
|
||||
│ ├── research/ # 研究文档 │
|
||||
│ │ └── <requirement-id>/ │
|
||||
│ │ ├── internal.md # 内部研究（代码库约束） │
|
||||
│ │ ├── external.md # 外部研究（技术选型） │
|
||||
│ │ └── requirement.md # 最终需求文档 │
|
||||
│ ├── plans/ # 计划文档 │
|
||||
│ │ └── <requirement-id>/ │
|
||||
│ │ ├── structure.md # 计划结构 │
|
||||
│ │ ├── plan.md # 详细计划 │
|
||||
│ │ └── tests/ # 测试规格 │
|
||||
│ └── archive/ # 已完成需求归档 │
|
||||
│ └── <date>-<requirement-id>/ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────────────────┘
|
||||
|
||||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||||
│ 典型工作流 │
|
||||
├─────────────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ 简单需求（Bug修复、小改动）: │
|
||||
│ /gudaspec:research → 描述需求 │
|
||||
│ /clear → /gudaspec:research-review <id> → 跳过外部 → requirement.md │
|
||||
│ /clear → /gudaspec:plan <req.md> │
|
||||
│ /clear → /gudaspec:plan-review <id> │
|
||||
│ /clear → /gudaspec:implementation <plan.md> │
|
||||
│ │
|
||||
│ 复杂需求（新功能、新技术）: │
|
||||
│ /gudaspec:research → 描述需求 │
|
||||
│ /clear → /gudaspec:research-review <id> → 需要外部 │
|
||||
│ /clear → /gudaspec:deepresearch <id> │
|
||||
│ /clear → /gudaspec:deep-research-review <id> → requirement.md │
|
||||
│ /clear → /gudaspec:plan <req.md> │
|
||||
│ /clear → /gudaspec:plan-review <id> │
|
||||
│ /clear → /gudaspec:implementation <plan.md> │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 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
|
||||
|
||||
<!-- GUDASPEC:INIT:END -->
|
||||
|
||||
Reference in New Issue
Block a user