commit 743c8a48fcc1ca9f86a8ed9414f6029506d7fa6f Author: GuDaStudio Date: Thu Jan 22 17:31:11 2026 +0800 v0.0：初始版本 diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..6de1997 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 guda.studio + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..6ed85db --- /dev/null +++ b/README.md @@ -0,0 +1,236 @@ +
+ +![](./images/title.png) + +**基于RPI和有效上下文理论，让Claude Code一次只专注于一件事** + +[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![Claude Code](https://img.shields.io/badge/Claude%20Code-Compatible-green.svg)](https://claude.ai/code) [![Share](https://img.shields.io/badge/share-000000?logo=x&logoColor=white)](https://x.com/intent/tweet?text=GudaStudio%20Commands：Claude%20Code%20多模型协作工作流%20https://github.com/GuDaStudio/commands%20%23AI%20%23Coding%20%23ClaudeCode) + +⭐ 在 GitHub 上给我们点星~您的支持对我们意义重大！🙏😊 + +[English](./docs/README_EN.md) | 简体中文 + +
+ +--- + +## 一、项目简介 + +**GudaStudio Commands** 收录了 **GudaStudio** 开发的 Claude Code 自定义命令集合。核心命令 `gudaspec` 实现了基于**RPI(Research-Plan-Implementation)编码理论**的完整流程，并融合openspec和多模型协作以让claued code**更适用于复杂场景、长时间编码任务**。同时，本项目引入了 *以人为本* 的操作理念，允许用户通过多阶段手动分割上下文，**让claude code的有效上下文（约80K）被极致利用**！完整功能请查看使用示例！ + +### gudaspec 命令集 + +| 命令 | 功能 | +|------|------| +| `/gudaspec:init` | 初始化 OpenSpec 环境，验证 MCP 工具可用性 | +| `/gudaspec:research` | 并行探索代码库，将需求转化为约束集 | +| `/gudaspec:plan` | 多模型分析，生成零决策执行计划与 PBT 属性 | +| `/gudaspec:implementation` | 多模型协作实现，原型重构为生产级代码 | + +--- + +## 二、快速开始 + +### 0. 前置要求 + +- [Claude Code](https://docs.claude.com/docs/claude-code) (v2.1.15+) +- [Auggie MCP](https://docs.augmentcode.com/context-services/mcp/quickstart-claude-code) + + +### 1. 获取仓库 + +```bash +git clone https://github.com/GuDaStudio/commands +cd commands +``` + +### 2. 安装命令 + +
+Linux / macOS + +```bash +# 用户级安装（所有项目生效） +./install.sh --user + +# 项目级安装（仅当前项目生效） +./install.sh --project + +# 自定义路径 +./install.sh --target /your/custom/path +``` + +
+ +
+Windows (PowerShell) + +```powershell +# 用户级安装（所有项目生效） +.\install.ps1 -User + +# 项目级安装（仅当前项目生效） +.\install.ps1 -Project + +# 自定义路径 +.\install.ps1 -Target C:\your\custom\path +``` + +
+ +
+参数说明 + +| 参数 (Bash) | 参数 (PowerShell) | 简写 | 说明 | +|-------------|-------------------|------|------| +| `--user` | `-User` | `-u` | 安装到用户级目录 (`~/.claude/commands/`) | +| `--project` | `-Project` | `-p` | 安装到项目级目录 (`./.claude/commands/`) | +| `--target ` | `-Target ` | `-t` | 安装到自定义路径 | +| `--help` | `-Help` | `-h` | 显示帮助信息 | + +
+ +### 3. 验证安装 + +启动 Claude Code 后输入 `/gudaspec` 即可查看可用命令。 + +### 4. 配置全局提示词🎊 +在 `~/.claude/CLAUDE.md` 中使用以下提示词。 +````markdown +# CLAUDE.md + +## 0. Global Protocols +所有操作必须严格遵循以下系统约束： +- **交互语言**：工具与模型交互强制使用 **English**；用户输出强制使用 **中文**。 +- **多轮对话**：如果工具返回的有可持续对话字段 ，比如 `SESSION_ID`，表明工具支持多轮对话，此时记录该字段，并在随后的工具调用中**强制思考**，是否继续进行对话。例如， Codex/Gemini有时会因工具调用中断会话，若没有得到需要的回复，则应继续对话。 +- **沙箱安全**：严禁 Codex/Gemini 对文件系统进行写操作。所有代码获取必须请求 `unified diff patch` 格式。 +- **代码主权**：外部模型生成的代码仅作为逻辑参考（Prototype），最终交付代码**必须经过重构**，确保无冗余、企业级标准。 +- **风格定义**：整体代码风格**始终定位**为，精简高效、毫无冗余。该要求同样适用于注释与文档，且对于这两者，严格遵循**非必要不形成**的核心原则。 +- **仅对需求做针对性改动**：严禁影响用户现有的其他功能。 +- **上下文检索**： 调用 `mcp__auggie-mcp__codebase-retrieval`，必须减少search/find/grep的次数。 +- **判断依据**：始终以项目代码、grok的搜索结果作为判断依据，严禁使用一般知识进行猜测，允许向用户表明自己的不确定性。 + +```` + +--- + +## 三、使用示例 +本项目的核心观念是**将有效的上下文专注于一件事**，本节将会以 `从零生成一个可视化天气页面` 为例，带您感受本项目的独特魅力！😀 +>以下示例均使用**claude opus 4.5**进行，并强烈建议您**开启推理模式以加强claude的指令服从能力**！ + +### 0. Init 项目初始化 +**0.1** 进入项目，打开claude code，键入 `/gudaspec:init`，为该项目进行gudaspec初始化。 +![](./images/init0.png) + +**0.2** claude会为您自动安装`openspec`，并检测`Codex-MCP` 和 `Gemini-MCP`是否可用。 +![](./images/init1.png) + +**0.3** 本阶段任务已完成，键入`/clear`，清空当前上下文并新开对话。 + +### 1. Research 需求研究 +该阶段旨在根据项目的已有代码/掌握的初步信息，对用户的需求进行初步理解，并形成标准OpenSpec文档。 + +**1.1** 在新的会话窗口中输入以下内容： +``` +/gudaspec:research +我需要生成一个美观的实时天气展示页面。要求： + 1. 实时天气信息必须为真实信息，包含温度、湿度等 + 2. 用户可以选择北京、上海、深圳三个城市 + 3. 四种不同的基础天气（大风、降雨、晴天、下雪），有不同的页面展示。 + 4. UI设计极具美感，参考苹果公司的顶级前端设计。 +``` +claude会帮您自动调研并生成openspec格式的初步提案。 +![](./images/research0.png) +![](./images/research1.png) + +**1.2** 当您的需求中含有明显歧义时，claude会主动征求您的意见。 +![](./images/research3.png) + +**1.3** 最终claude会为您生成初步的spec文档，此时只用了*59.5K*上下文，距离**claude的最专注上下文长度80K**还有不少距离。🥳 +![](./images/research4.png) + +### 2. Plan 计划制定 +本阶段的任务是彻底消除用户需求中的不确定性，并生成可执行计划。同时为计划提供可验证属性。 + +**2.1** 在新的会话窗口中输入以下内容，claude会自动帮您找到待完成的需求。 +``` +/gudaspec:plan +``` +![](./images/plan0.png) + +**2.2** claude会启动多模型（codex/gemini）协作，来对初步需求报告中的实现方案进行分析细化。 +![](./images/plan1.png) + +**2.3** 获取到多模型的分析方案后，claude会进一步细化需求，彻底消除技术上的模糊性。 +![](./images/plan2.png) + +**2.4** 在所有决策项完成后，claude会提取 Property-Based Testing 属性，供后续阶段验证使用。 +![](./images/plan3.png) + +**2.5** 直至计划方案变成后续可零决策顺序执行的pipeline，claude会生成完整的spec文档，该阶段任务完成，输入`/clear`，清空当前上下文，新开会话窗口。 +![](./images/plan4.png) + +### 3. Implementation 代码实现 +本阶段的目标是执行具体的代码实现，直至完成用户需求。 + +**3.1** 在新会话窗口中，执行以下命令，claude会自动帮您识别待完成的需求提案。 +``` +/gudaspec:implementation +``` +![](./images/imp0.png) + +**3.2** claude会自动识别最小可验证任务来进行逐步实现，以更好的**帮助您控制上下文！** +![](./images/imp1.png) + +**3.3** 在完成一阶段任务后，claude会暂停询问您是否继续的意见，此时我们**强烈建议**您关注上下文窗口，**若小于80k则可以继续下一阶段的实现**；反之，可以输入`/clear`新开会话窗口，从**3.1**继续实现。 +![](./images/imp2.png) + +**3.4** 过程中，claude会自动启用多模型代码原型获取（前端/UI → Gemini | 后端/逻辑 → Codex），并在每完成一阶段任务后启用多模型review来保证代码可靠性。 +![](./images/imp3.png) + +**3.5** 成果展示。直至所有任务完成，我们就可以获得一个拥有真实数据的天气系统啦！😀(左侧为系统截图，右侧为中央气象台截图) +![](./images/result.png) + + + +--- + +## FAQ + +
+Q1: 什么是 OpenSpec？ + +OpenSpec 是一个规范化的需求-实现工作流框架，通过结构化的约束集管理，确保从需求到代码的可追溯性和一致性。 + +
+ +
+Q2: 必须安装 Codex/Gemini MCP 吗？ + +不是必须的。但若要使用完整的多模型协作功能，需要安装对应的 MCP 工具。运行 `/gudaspec:init` 会检测并提示安装。 + +
+ +
+Q3: 约束集有什么作用？ + +约束集将需求转化为具体的技术限制条件，消除实现阶段的决策点。每个约束都缩小解空间，使实现阶段成为纯机械执行，无需即时判断。 + +
+ +--- + +## 许可证 + +本项目采用 [MIT License](LICENSE) 开源协议。 + +Copyright (c) 2025 [guda.studio](mailto:gudaclaude@gmail.com) + +--- + +
+ +## 用 🌟 为本项目助力~ + +
+ diff --git a/docs/README_EN.md b/docs/README_EN.md new file mode 100644 index 0000000..451fd19 --- /dev/null +++ b/docs/README_EN.md @@ -0,0 +1,235 @@ +
+ +![](../images/title.png) + +**Based on RPI and Effective Context Theory, Let Claude Code Focus on One Thing at a Time** + +[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![Claude Code](https://img.shields.io/badge/Claude%20Code-Compatible-green.svg)](https://claude.ai/code) [![Share](https://img.shields.io/badge/share-000000?logo=x&logoColor=white)](https://x.com/intent/tweet?text=GudaStudio%20Commands：Claude%20Code%20Multi-Model%20Collaborative%20Workflow%20https://github.com/GuDaStudio/commands%20%23AI%20%23Coding%20%23ClaudeCode) + +⭐ Star us on GitHub ~ Your support means a lot to us! 🙏😊 + +English | [简体中文](../README.md) + +
+ +--- + +## 1. Introduction + +**GudaStudio Commands** is a collection of Claude Code custom commands developed by **GudaStudio**. The core command `gudaspec` implements a complete workflow based on **RPI (Research-Plan-Implementation) Coding Theory**, integrating OpenSpec and multi-model collaboration to make Claude Code **more suitable for complex scenarios and long-duration coding tasks**. Additionally, this project introduces a *human-centric* operational philosophy, allowing users to manually segment context across multiple phases, **maximizing Claude Code's effective context window (~80K)!** Check out the usage examples for full features! + +### gudaspec Command Set + +| Command | Function | +|---------|----------| +| `/gudaspec:init` | Initialize OpenSpec environment, verify MCP tool availability | +| `/gudaspec:research` | Parallel codebase exploration, transform requirements into constraint sets | +| `/gudaspec:plan` | Multi-model analysis, generate zero-decision execution plans with PBT properties | +| `/gudaspec:implementation` | Multi-model collaborative implementation, refactor prototypes into production-grade code | + +--- + +## 2. Quick Start + +### 0. Prerequisites + +- [Claude Code](https://docs.claude.com/docs/claude-code) (v2.1.15+) +- [Auggie MCP](https://docs.augmentcode.com/context-services/mcp/quickstart-claude-code) + + +### 1. Clone the Repository + +```bash +git clone https://github.com/GuDaStudio/commands +cd commands +``` + +### 2. Install Commands + +
+Linux / macOS + +```bash +# User-level installation (applies to all projects) +./install.sh --user + +# Project-level installation (applies to current project only) +./install.sh --project + +# Custom path +./install.sh --target /your/custom/path +``` + +
+ +
+Windows (PowerShell) + +```powershell +# User-level installation (applies to all projects) +.\install.ps1 -User + +# Project-level installation (applies to current project only) +.\install.ps1 -Project + +# Custom path +.\install.ps1 -Target C:\your\custom\path +``` + +
+ +
+Parameter Reference + +| Bash | PowerShell | Short | Description | +|------|------------|-------|-------------| +| `--user` | `-User` | `-u` | Install to user-level directory (`~/.claude/commands/`) | +| `--project` | `-Project` | `-p` | Install to project-level directory (`./.claude/commands/`) | +| `--target ` | `-Target ` | `-t` | Install to custom path | +| `--help` | `-Help` | `-h` | Show help information | + +
+ +### 3. Verify Installation + +After launching Claude Code, type `/gudaspec` to view available commands. + +### 4. Configure Global Prompt 🎊 +Add the following prompt to `~/.claude/CLAUDE.md`: +````markdown +# CLAUDE.md + +## 0. Global Protocols +All operations must strictly follow these system constraints: +- **Interaction Language**: Tool-model interactions MUST use **English**; user output MUST use **English**. +- **Multi-turn Conversations**: If a tool returns a persistent conversation field like `SESSION_ID`, it indicates the tool supports multi-turn conversations. Record this field and **force deliberation** in subsequent tool calls on whether to continue the conversation. For example, Codex/Gemini sometimes interrupt sessions during tool calls; if you don't get the needed response, continue the conversation. +- **Sandbox Security**: Codex/Gemini are PROHIBITED from performing write operations to the filesystem. All code retrieval must request `unified diff patch` format. +- **Code Sovereignty**: Code generated by external models serves only as logical reference (Prototype). Final delivered code **MUST be refactored** to ensure no redundancy and enterprise-grade standards. +- **Style Definition**: Overall code style is **always positioned** as lean, efficient, with zero redundancy. This requirement also applies to comments and documentation, and for these two, strictly follow the core principle of **form only when necessary**. +- **Targeted Changes Only**: PROHIBITED from affecting user's existing other functionalities. +- **Context Retrieval**: When calling `mcp__auggie-mcp__codebase-retrieval`, minimize the number of search/find/grep operations. +- **Judgment Basis**: Always use project code and grok search results as the basis for judgment. PROHIBITED from guessing based on general knowledge. Expressing uncertainty to users is allowed. + +```` + +--- + +## 3. Usage Examples +The core philosophy of this project is **focusing effective context on one thing at a time**. This section will demonstrate the unique charm of this project using `Building a Visual Weather Page from Scratch` as an example! 😀 +> All examples below use **Claude Opus 4.5**, and we **strongly recommend enabling reasoning mode to enhance Claude's instruction-following capability**! + +### 0. Init - Project Initialization +**0.1** Enter the project, open Claude Code, and type `/gudaspec:init` to initialize gudaspec for this project. +![](../images/init0.png) + +**0.2** Claude will automatically install `openspec` for you and detect whether `Codex-MCP` and `Gemini-MCP` are available. +![](../images/init1.png) + +**0.3** This phase's task is complete. Type `/clear` to clear the current context and start a new conversation. + +### 1. Research - Requirements Research +This phase aims to develop a preliminary understanding of user requirements based on existing code/initial information, and form a standard OpenSpec document. + +**1.1** In the new conversation window, enter the following: +``` +/gudaspec:research +I need to create a beautiful real-time weather display page. Requirements: + 1. Real-time weather info must be real data, including temperature, humidity, etc. + 2. Users can select from three cities: Beijing, Shanghai, Shenzhen + 3. Four different basic weather conditions (windy, rainy, sunny, snowy) have different page displays + 4. UI design is highly aesthetic, referencing Apple's top-tier frontend design +``` +Claude will automatically research and generate a preliminary proposal in OpenSpec format. +![](../images/research0.png) +![](../images/research1.png) + +**1.2** When your requirements contain obvious ambiguities, Claude will proactively seek your opinion. +![](../images/research3.png) + +**1.3** Finally, Claude will generate a preliminary spec document for you. At this point, only *59.5K* of context has been used, still well within **Claude's most focused context length of 80K**. 🥳 +![](../images/research4.png) + +### 2. Plan - Planning +This phase's task is to completely eliminate uncertainty in user requirements and generate an executable plan, while providing verifiable properties for the plan. + +**2.1** In a new conversation window, enter the following. Claude will automatically find the pending requirements for you. +``` +/gudaspec:plan +``` +![](../images/plan0.png) + +**2.2** Claude will launch multi-model (Codex/Gemini) collaboration to analyze and refine the implementation approach in the preliminary requirements report. +![](../images/plan1.png) + +**2.3** After obtaining analysis from multiple models, Claude will further refine the requirements to completely eliminate technical ambiguity. +![](../images/plan2.png) + +**2.4** After all decision items are completed, Claude will extract Property-Based Testing properties for verification in subsequent phases. +![](../images/plan3.png) + +**2.5** Until the plan becomes a zero-decision sequentially executable pipeline, Claude will generate the complete spec document. This phase's task is complete. Type `/clear` to clear the current context and start a new conversation window. +![](../images/plan4.png) + +### 3. Implementation - Code Implementation +This phase's goal is to execute specific code implementation until user requirements are fulfilled. + +**3.1** In a new conversation window, execute the following command. Claude will automatically identify pending requirement proposals for you. +``` +/gudaspec:implementation +``` +![](../images/imp0.png) + +**3.2** Claude will automatically identify minimal verifiable tasks for incremental implementation, **helping you control context better!** +![](../images/imp1.png) + +**3.3** After completing a phase task, Claude will pause and ask for your opinion on whether to continue. At this point, we **strongly recommend** you pay attention to the context window. **If it's less than 80K, you can continue to the next phase of implementation**; otherwise, you can type `/clear` to start a new conversation window and continue implementation from **3.1**. +![](../images/imp2.png) + +**3.4** During the process, Claude will automatically enable multi-model code prototype retrieval (Frontend/UI → Gemini | Backend/Logic → Codex), and enable multi-model review after completing each phase task to ensure code reliability. +![](../images/imp3.png) + +**3.5** Result showcase. Once all tasks are completed, we get a weather system with real data! 😀 (Left: system screenshot, Right: China Meteorological Administration screenshot) +![](../images/result.png) + + + +--- + +## FAQ + +
+Q1: What is OpenSpec? + +OpenSpec is a standardized requirements-to-implementation workflow framework that ensures traceability and consistency from requirements to code through structured constraint set management. + +
+ +
+Q2: Is Codex/Gemini MCP required? + +No, it's not mandatory. However, to use the complete multi-model collaboration features, you need to install the corresponding MCP tools. Running `/gudaspec:init` will detect and prompt for installation. + +
+ +
+Q3: What is the purpose of constraint sets? + +Constraint sets transform requirements into specific technical constraints, eliminating decision points during implementation. Each constraint narrows the solution space, making the implementation phase pure mechanical execution without real-time judgment needed. + +
+ +--- + +## License + +This project is open-sourced under the [MIT License](../LICENSE). + +Copyright (c) 2025 [guda.studio](mailto:gudaclaude@gmail.com) + +--- + +
+ +## Power This Project with 🌟 + +
diff --git a/gudaspec/implementation.md b/gudaspec/implementation.md new file mode 100644 index 0000000..7c7b9d0 --- /dev/null +++ b/gudaspec/implementation.md @@ -0,0 +1,29 @@ +--- +name: GudaSpec: Implementation +description: Execute approved OpenSpec changes via multi-model collaboration with Codex/Gemini. +category: GudaSpec +tags: [openspec, implementation, multi-model, codex, gemini] +--- + +**Guardrails** +- Never apply external model prototypes directly—all Codex/Gemini outputs serve as reference only and must be rewritten into readable, maintainable, production-grade code. +- Keep changes tightly scoped to the requested outcome; enforce side-effect review before applying any modification. +- Minimize documentation—avoid unnecessary comments; prefer self-explanatory code. +- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) for additional OpenSpec conventions or clarifications. + +**Steps** +Track these steps as TODOs and complete them one by one. + +1. Run `openspec view` to inspect current project status and review `Active Changes`; ask the user to confirm which proposal ID they want to implement and wait for explicit confirmation before proceeding. +2. Run `/openspec:apply `. +3. Work through tasks sequentially as defined in `tasks.md`; but Don't complete all tasks in `tasks.md` at once. Just identify **the smallest verifiable phase** that can be quickly accomplished this time, and strictly control the context window for a single implementation. +4. Analyze each task in `tasks.md` and route to the appropriate model kernel: + - **Route A: Gemini Kernel** — for frontend/UI/styling tasks (CSS, React, Vue, HTML, component design). + - **Route B: Codex Kernel** — for backend/logic/algorithm tasks (API, data processing, business logic, debugging). + - **Mandatory constraint**: When communicating with Codex/Gemini, the prompt **must explicitly require** returning a `Unified Diff Patch` only; external models are strictly forbidden from making any real file modifications. +5. Upon receiving the diff patch from Codex/Gemini, **never apply it directly**; rewrite the prototype by removing redundancy, ensuring clear naming and simple structure, aligning with project style, and eliminating unnecessary comments. +6. Before applying any change, perform a mandatory side-effect review: verify the change does not exceed `tasks.md` scope, does not affect unrelated modules, and does not introduce new dependencies or break existing interfaces; make targeted corrections if issues are found. +7. After completing the task, run **multi-model review** to verify. +8. After corrections are completed, mark the task item as `- [x]` in `tasks.md`. +9. Once all tasks are confirmed complete, run `/openspec:archive`. + diff --git a/gudaspec/init.md b/gudaspec/init.md new file mode 100644 index 0000000..3bb5924 --- /dev/null +++ b/gudaspec/init.md @@ -0,0 +1,59 @@ +--- +name: GudaSpec: Init +description: Initialize OpenSpec environment with MCP tools validation for the current project. +category: GudaSpec +tags: [openspec, init, setup, mcp] +--- + +**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. +- 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. + +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. + +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. + +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. + +**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. + diff --git a/gudaspec/plan.md b/gudaspec/plan.md new file mode 100644 index 0000000..2d8ab92 --- /dev/null +++ b/gudaspec/plan.md @@ -0,0 +1,81 @@ +--- +name: GudaSpec: Plan +description: Refine proposals into zero-decision executable task flows via multi-model analysis. +category: GudaSpec +tags: [gudaspec, plan, multi-model, pbt] +allowed-tools: Bash(openspec:*), mcp__codex__codex, mcp__gemini__gemini +argument-hint: [proposal_id] +--- + +**Guardrails** +- Strictly adhere to **OpenSpec** rules when writing **standardized spec-structured projects**. +- The goal of this phase is to eliminate ALL decision points from the task flow—implementation should be pure mechanical execution. +- Do not proceed to implementation until every ambiguity is resolved and every constraint is explicitly documented. +- Multi-model collaboration is mandatory: use both `mcp__codex__codex` and `mcp__gemini__gemini` to surface blind spots and conflicting assumptions. +- Every requirement must have Property-Based Testing (PBT) properties defined—focus on invariants, not just example-based tests. +- If constraints cannot be fully specified, escalate back to the user or return to the research phase rather than making assumptions. +- Refer to `openspec/AGENTS.md` for additional conventions; run `openspec update` if the file is missing. + +**Steps** +1. Run `openspec view` to display all **Active Changes**, then confirm with the user which proposal ID (``) they wish to refine into a zero-decision plan. + +2. Run `/openspec:proposal `. + +3. **Multi-Model Implementation Analysis**: Invoke both MCP tools to provide diverse implementation perspectives: + ``` + mcp__codex__codex: "Analyze proposal : Provide implementation approach, identify technical risks, and suggest alternative architectures. Focus on edge cases and failure modes." + + mcp__gemini__gemini: "Analyze proposal : Evaluate from maintainability, scalability, and integration perspectives. Highlight potential conflicts with existing systems." + ``` + Synthesize responses and present consolidated options to the user for constraint selection. + +4. **Multi-Model Uncertainty Elimination Audit**: Invoke both MCP tools to detect remaining ambiguities: + ``` + mcp__codex__codex: "Review proposal for decision points that remain unspecified. List each as: [AMBIGUITY] → [REQUIRED CONSTRAINT] ." + + mcp__gemini__gemini: "Identify implicit assumptions in proposal . For each assumption, specify: [ASSUMPTION] → [EXPLICIT CONSTRAINT NEEDED] ." + ``` + + **Anti-Pattern Detection** (flag and reject): + - Information collection without decision boundaries (e.g., "JWT vs OAuth2 vs session—all viable") + - Technical comparisons without selection criteria + - Deferred decisions marked as "to be determined during implementation" + + **Target Pattern** (required for approval): + - Explicit technology choices with parameters (e.g., "JWT with accessToken TTL=15min, refreshToken TTL=7days") + - Concrete algorithm selections with configurations (e.g., "bcrypt with cost factor=12") + - Precise behavioral rules (e.g., "Lock account for 30min after 5 failed login attempts") + + Iterate with user until ALL ambiguities are resolved into explicit constraints. + +5. **Multi-Model PBT Property Extraction**: Invoke both MCP tools to derive testable invariants: + ``` + mcp__codex__codex: "Extract Property-Based Testing properties from proposal . For each requirement, identify: [INVARIANT] → [FALSIFICATION STRATEGY] ." + + mcp__gemini__gemini: "Analyze proposal for system properties. Define: [PROPERTY] | [DEFINITION] | [BOUNDARY CONDITIONS] | [COUNTEREXAMPLE GENERATION] ." + ``` + + **PBT Property Categories to Extract**: + - **Commutativity/Associativity**: Order-independent operations + - **Idempotency**: Repeated operations yield same result + - **Round-trip**: Encode→Decode returns original + - **Invariant Preservation**: State constraints maintained across operations + - **Monotonicity**: Ordering guarantees (e.g., timestamps always increase) + - **Bounds**: Value ranges, size limits, rate constraints + +**Reference** +- Use `openspec show --json --deltas-only` to inspect proposal structure when validation fails. +- Use `openspec list --specs` to check for conflicts with existing specifications. +- Search existing patterns with `rg -n "INVARIANT:|PROPERTY:|Constraint:" openspec/` before defining new ones. +- If MCP tools are unavailable, run `/mcp` to check connection status and authenticate if needed. +- For complex proposals, consider running steps 2-4 iteratively on sub-components rather than the entire proposal at once. +- Use `AskUserQuestions` for ANY ambiguity—do not assume or guess. + +**Exit Criteria** +A proposal is ready to exit the Plan phase only when: +- [ ] All multi-model analyses completed and synthesized +- [ ] Zero ambiguities remain (verified by step 3 audit) +- [ ] All PBT properties documented with falsification strategies +- [ ] `openspec validate --strict` returns zero issues +- [ ] User has explicitly approved all constraint decisions + diff --git a/gudaspec/research.md b/gudaspec/research.md new file mode 100644 index 0000000..bcc4549 --- /dev/null +++ b/gudaspec/research.md @@ -0,0 +1,106 @@ +--- +name: GudaSpec Research +description: Transform user requirements into constraint sets through parallel exploration and analysis +category: GudaSpec +tags: [gudaspec, research, constraints, exploration, subagents] +--- + + +**Core Philosophy** +- Research produces **constraint sets**, not information dumps. Each constraint narrows the solution space. +- Constraints tell subsequent stages "don't consider this direction," enabling mechanical execution without decisions. +- The output is "約束集合 + 可验证的成功判据" (constraint sets + verifiable success criteria). +- Eliminate ambiguity through structured exploration and user interaction. +- Strictly adhere to **OpenSpec** rules when writing **standardized spec-structured projects**. + +**Guardrails** +- **NEVER** divide subagent tasks by roles (e.g., "架构师agent", "安全专家agent"). +- **ALWAYS** divide by context boundaries (e.g., "user-related code", "authentication logic", "infrastructure config"). +- Each subagent context must be self-contained with independent output. +- **MANDATORY**: Use `mcp__auggie-mcp__codebase-retrieval` to minimize search/grep/find operations. +- All subagents must follow the same structured output template for aggregation. +- Do not make architectural decisions—surface constraints that guide decisions. + +**Steps** +0. **Generate OpenSpec Proposal** + - Run `/openspec:proposal` + +1. **Initial Codebase Assessment** + - Combine user requirements with quick codebase scan using `mcp__auggie-mcp__codebase-retrieval`. + - Determine project scale: single directory vs. multi-directory structure. + - **Decision point**: If code spans multiple subdirectories or modules → enable parallel Explore subagents. + - Document finding: "Single agent serial exploration is inefficient; parallel subagents required." + +2. **Define Exploration Boundaries (Context-Based Division)** + - Identify natural context boundaries in the codebase (NOT functional roles). + - Example divisions: + * Subagent 1: User domain code (user models, user services, user UI) + * Subagent 2: Authentication & authorization code (auth middleware, session, tokens) + * Subagent 3: Configuration & infrastructure (configs, deployments, build scripts) + - Each boundary should be self-contained: no cross-communication needed between subagents. + - Define exploration scope and expected output for each subagent. + +3. **Prepare Standardized Output Template** + - Define a unified JSON schema that all Explore subagents must follow: + ```json + { + "module_name": "string - context boundary explored", + "existing_structures": ["list of key structures/patterns found"], + "existing_conventions": ["list of conventions/standards in use"], + "constraints_discovered": ["list of hard constraints that limit solution space"], + "open_questions": ["list of ambiguities requiring user input"], + "dependencies": ["list of dependencies on other modules/systems"], + "risks": ["list of potential risks or blockers"], + "success_criteria_hints": ["observable behaviors that indicate success"] + } + ``` + - Communicate template to all subagents for consistency. + +4. **Parallel Subagent Dispatch** + - For each defined context boundary, spawn an Explore subagent with: + * **Explicit instruction**: "You MUST use `mcp__auggie-mcp__codebase-retrieval` to reduce search operations." + * Defined scope and context boundary. + * Required output template (from Step 3). + * Clear success criteria: complete analysis of assigned boundary. + - Monitor subagent execution and collect structured reports. + +5. **Aggregate and Synthesize Reports** + - Collect all subagent JSON outputs. + - Merge findings into unified constraint sets: + * **Hard constraints**: Technical limitations, existing patterns that cannot be violated. + * **Soft constraints**: Conventions, preferences, style guides. + * **Dependencies**: Cross-module relationships that affect implementation order. + * **Risks**: Potential blockers that need mitigation. + - Identify **open questions** from all reports that require user clarification. + - Synthesize **success criteria** from scenario hints across all contexts. + +6. **User Interaction for Ambiguity Resolution** + - Compile prioritized list of open questions from aggregated reports. + - Use `AskUserQuestions` tool to present questions systematically: + * Group related questions together. + * Provide context for each question. + * Suggest default answers when applicable. + - Capture user responses as additional constraints. + - Update constraint sets with confirmed decisions. + +7. **Generate OpenSpec Proposal** + - Run `/openspec:proposal ` to scaffold formal spec. + - Transform finalized constraint sets into requirements format. + - Structure as: + * **Context**: User need + discovered constraints + * **Requirements**: Each constraint becomes a requirement with scenario + * **Success Criteria**: Derived from aggregated hints and user confirmations + - Ensure proposal includes: + * All discovered constraints as requirements. + * Verifiable scenarios for each requirement. + * Clear dependencies and sequencing. + * Risk mitigation strategies. + +**Reference** +- Review existing constraints: `rg -n "Constraint:|MUST|MUST NOT" openspec/specs` +- Inspect codebase structure: `ls -R` or `mcp__auggie-mcp__codebase-retrieval` +- Check prior research outputs: `ls openspec/changes/*/research-output.md` +- Validate subagent outputs conform to template before aggregation. +- Use `AskUserQuestions` for ANY ambiguity—do not assume or guess. + + diff --git a/images/imp0.png b/images/imp0.png new file mode 100644 index 0000000..ad943a7 Binary files /dev/null and b/images/imp0.png differ diff --git a/images/imp1.png b/images/imp1.png new file mode 100644 index 0000000..ba23db0 Binary files /dev/null and b/images/imp1.png differ diff --git a/images/imp2.png b/images/imp2.png new file mode 100644 index 0000000..bc1c2fc Binary files /dev/null and b/images/imp2.png differ diff --git a/images/imp3.png b/images/imp3.png new file mode 100644 index 0000000..3fdfa57 Binary files /dev/null and b/images/imp3.png differ diff --git a/images/init0.png b/images/init0.png new file mode 100644 index 0000000..e746e20 Binary files /dev/null and b/images/init0.png differ diff --git a/images/init1.png b/images/init1.png new file mode 100644 index 0000000..1d1bf8f Binary files /dev/null and b/images/init1.png differ diff --git a/images/plan0.png b/images/plan0.png new file mode 100644 index 0000000..6b22c99 Binary files /dev/null and b/images/plan0.png differ diff --git a/images/plan1.png b/images/plan1.png new file mode 100644 index 0000000..56f0b6c Binary files /dev/null and b/images/plan1.png differ diff --git a/images/plan2.png b/images/plan2.png new file mode 100644 index 0000000..7760b69 Binary files /dev/null and b/images/plan2.png differ diff --git a/images/plan3.png b/images/plan3.png new file mode 100644 index 0000000..ec25275 Binary files /dev/null and b/images/plan3.png differ diff --git a/images/plan4.png b/images/plan4.png new file mode 100644 index 0000000..9c1b1fa Binary files /dev/null and b/images/plan4.png differ diff --git a/images/research0.png b/images/research0.png new file mode 100644 index 0000000..dd68e73 Binary files /dev/null and b/images/research0.png differ diff --git a/images/research1.png b/images/research1.png new file mode 100644 index 0000000..834227f Binary files /dev/null and b/images/research1.png differ diff --git a/images/research3.png b/images/research3.png new file mode 100644 index 0000000..d882404 Binary files /dev/null and b/images/research3.png differ diff --git a/images/research4.png b/images/research4.png new file mode 100644 index 0000000..1154e1b Binary files /dev/null and b/images/research4.png differ diff --git a/images/result.png b/images/result.png new file mode 100644 index 0000000..538f798 Binary files /dev/null and b/images/result.png differ diff --git a/images/title.png b/images/title.png new file mode 100644 index 0000000..ed51d87 Binary files /dev/null and b/images/title.png differ diff --git a/install.ps1 b/install.ps1 new file mode 100644 index 0000000..5396bc1 --- /dev/null +++ b/install.ps1 @@ -0,0 +1,116 @@ +# GudaCC Commands Installer for Windows +# https://github.com/GuDaStudio/commands + +param( + [Alias("u")][switch]$User, + [Alias("p")][switch]$Project, + [Alias("t")][string]$Target, + [Alias("h")][switch]$Help +) + +$ErrorActionPreference = "Stop" +$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path +$CommandName = "gudaspec" + +function Write-ColorOutput { + param( + [string]$Text, + [string]$Color = "White", + [switch]$NoNewline + ) + if ($NoNewline) { + Write-Host $Text -ForegroundColor $Color -NoNewline + } else { + Write-Host $Text -ForegroundColor $Color + } +} + +function Show-Usage { + Write-ColorOutput "GudaCC Commands Installer" "Blue" + Write-Host "" + Write-Host "Usage: .\install.ps1 [OPTIONS]" + Write-Host "" + Write-Host "Options:" + Write-Host " -User, -u Install to user-level (~\.claude\commands\)" + Write-Host " -Project, -p Install to project-level (.\.claude\commands\)" + Write-Host " -Target, -t Install to custom target path" + Write-Host " -Help, -h Show this help message" + Write-Host "" + Write-Host "Examples:" + Write-Host " .\install.ps1 -User" + Write-Host " .\install.ps1 -Project" + Write-Host " .\install.ps1 -Target C:\custom\path" +} + +function Install-Command { + param([string]$TargetDir) + + $sourceDir = Join-Path $ScriptDir $CommandName + $destDir = Join-Path $TargetDir $CommandName + + if (-not (Test-Path $sourceDir -PathType Container)) { + Write-ColorOutput "Error: '$CommandName' not found in source directory" "Red" + return $false + } + + Write-Host "Installing " -NoNewline + Write-ColorOutput "$CommandName" "Cyan" -NoNewline + Write-Host " -> $destDir" + + if (-not (Test-Path $TargetDir)) { + New-Item -ItemType Directory -Path $TargetDir -Force | Out-Null + } + + if (Test-Path $destDir) { + Write-ColorOutput " Removing existing installation..." "Yellow" + Remove-Item -Path $destDir -Recurse -Force + } + + Copy-Item -Path $sourceDir -Destination $destDir -Recurse + + $gitFile = Join-Path $destDir ".git" + if (Test-Path $gitFile -PathType Leaf) { + Remove-Item -Path $gitFile -Force + } + + Write-ColorOutput " ✓ Installed" "Green" + return $true +} + +if ($Help) { + Show-Usage + exit 0 +} + +$TargetPath = "" +if ($User) { + $TargetPath = Join-Path $env:USERPROFILE ".claude\commands" +} elseif ($Project) { + $TargetPath = ".\.claude\commands" +} elseif ($Target) { + $TargetPath = $Target +} + +if (-not $TargetPath) { + Write-ColorOutput "Error: Please specify installation target (-User, -Project, or -Target)" "Red" + Write-Host "" + Show-Usage + exit 1 +} + +Write-ColorOutput "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" "Blue" +Write-ColorOutput "GudaCC Commands Installer" "Blue" +Write-ColorOutput "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" "Blue" +Write-Host "" +Write-Host "Target: " -NoNewline +Write-ColorOutput $TargetPath "Green" +Write-Host "Command: " -NoNewline +Write-ColorOutput $CommandName "Green" +Write-Host "" + +Install-Command -TargetDir $TargetPath + +Write-Host "" +Write-ColorOutput "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" "Green" +Write-ColorOutput "Installation complete!" "Green" +Write-ColorOutput "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" "Green" diff --git a/install.sh b/install.sh new file mode 100644 index 0000000..1982154 --- /dev/null +++ b/install.sh @@ -0,0 +1,109 @@ +#!/bin/bash +# GudaCC Commands Installer +# https://github.com/GuDaStudio/commands + +set -e + +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +BLUE='\033[0;34m' +NC='\033[0m' + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +COMMAND_NAME="gudaspec" + +usage() { + echo -e "${BLUE}GudaCC Commands Installer${NC}" + echo "" + echo "Usage: $0 [OPTIONS]" + echo "" + echo "Options:" + echo " -u, --user Install to user-level (~/.claude/commands/)" + echo " -p, --project Install to project-level (./.claude/commands/)" + echo " -t, --target Install to custom target path" + echo " -h, --help Show this help message" + echo "" + echo "Examples:" + echo " $0 --user" + echo " $0 --project" + echo " $0 --target /custom/path" +} + +install_command() { + local target_dir=$1 + local source_dir="$SCRIPT_DIR/$COMMAND_NAME" + local dest_dir="$target_dir/$COMMAND_NAME" + + if [ ! -d "$source_dir" ]; then + echo -e "${RED}Error: '$COMMAND_NAME' not found in source directory${NC}" + return 1 + fi + + echo -e "${BLUE}Installing${NC} $COMMAND_NAME -> $dest_dir" + + mkdir -p "$target_dir" + + if [ -d "$dest_dir" ]; then + echo -e "${YELLOW} Removing existing installation...${NC}" + rm -rf "$dest_dir" + fi + + cp -r "$source_dir" "$dest_dir" + + if [ -f "$dest_dir/.git" ]; then + rm "$dest_dir/.git" + fi + + echo -e "${GREEN} ✓ Installed${NC}" +} + +TARGET_PATH="" + +while [[ $# -gt 0 ]]; do + case $1 in + -u|--user) + TARGET_PATH="$HOME/.claude/commands" + shift + ;; + -p|--project) + TARGET_PATH="./.claude/commands" + shift + ;; + -t|--target) + TARGET_PATH="$2" + shift 2 + ;; + -h|--help) + usage + exit 0 + ;; + *) + echo -e "${RED}Unknown option: $1${NC}" + usage + exit 1 + ;; + esac +done + +if [ -z "$TARGET_PATH" ]; then + echo -e "${RED}Error: Please specify installation target (-u, -p, or -t)${NC}" + echo "" + usage + exit 1 +fi + +echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}" +echo -e "${BLUE}GudaCC Commands Installer${NC}" +echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}" +echo "" +echo -e "Target: ${GREEN}$TARGET_PATH${NC}" +echo -e "Command: ${GREEN}$COMMAND_NAME${NC}" +echo "" + +install_command "$TARGET_PATH" + +echo "" +echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}" +echo -e "${GREEN}Installation complete!${NC}" +echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"