v0.0：初始版本

2026-03-22 19:18:52 +08:00 · 2026-01-22 17:31:11 +08:00
commit 743c8a48fc
26 changed files with 992 additions and 0 deletions
--- a/21
+++ b/21
@@ -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.
--- a/README.md
+++ b/README.md
@@ -0,0 +1,236 @@
 <div align="center">
 ![](./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) | 简体中文
 </div>
 ---
 ## 一、项目简介
 **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. 安装命令
 <details>
 <summary><b>Linux / macOS</b></summary>
 ```bash
 # 用户级安装（所有项目生效）
 ./install.sh --user
 # 项目级安装（仅当前项目生效）
 ./install.sh --project
 # 自定义路径
 ./install.sh --target /your/custom/path
 ```
 </details>
 <details>
 <summary><b>Windows (PowerShell)</b></summary>
 ```powershell
 # 用户级安装（所有项目生效）
 .\install.ps1 -User
 # 项目级安装（仅当前项目生效）
 .\install.ps1 -Project
 # 自定义路径
 .\install.ps1 -Target C:\your\custom\path
 ```
 </details>
 <details>
 <summary>参数说明</summary>
 | 参数 (Bash) | 参数 (PowerShell) | 简写 | 说明 |
 |-------------|-------------------|------|------|
 | `--user` | `-User` | `-u` | 安装到用户级目录 (`~/.claude/commands/`) |
 | `--project` | `-Project` | `-p` | 安装到项目级目录 (`./.claude/commands/`) |
 | `--target <path>` | `-Target <path>` | `-t` | 安装到自定义路径 |
 | `--help` | `-Help` | `-h` | 显示帮助信息 |
 </details>
 ### 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
 <details>
 <summary>Q1: 什么是 OpenSpec？</summary>
 OpenSpec 是一个规范化的需求-实现工作流框架，通过结构化的约束集管理，确保从需求到代码的可追溯性和一致性。
 </details>
 <details>
 <summary>Q2: 必须安装 Codex/Gemini MCP 吗？</summary>
 不是必须的。但若要使用完整的多模型协作功能，需要安装对应的 MCP 工具。运行 `/gudaspec:init` 会检测并提示安装。
 </details>
 <details>
 <summary>Q3: 约束集有什么作用？</summary>
 约束集将需求转化为具体的技术限制条件，消除实现阶段的决策点。每个约束都缩小解空间，使实现阶段成为纯机械执行，无需即时判断。
 </details>
 ---
 ## 许可证
 本项目采用 [MIT License](LICENSE) 开源协议。
 Copyright (c) 2025 [guda.studio](mailto:gudaclaude@gmail.com)
 ---
 <div align="center">
 ## 用 🌟 为本项目助力~
 </div>
--- a/docs/README_EN.md
+++ b/docs/README_EN.md
@@ -0,0 +1,235 @@
 <div align="center">
 ![](../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)
 </div>
 ---
 ## 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
 <details>
 <summary><b>Linux / macOS</b></summary>
 ```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
 ```
 </details>
 <details>
 <summary><b>Windows (PowerShell)</b></summary>
 ```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
 ```
 </details>
 <details>
 <summary>Parameter Reference</summary>
 | 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 <path>` | `-Target <path>` | `-t` | Install to custom path |
 | `--help` | `-Help` | `-h` | Show help information |
 </details>
 ### 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
 <details>
 <summary>Q1: What is OpenSpec?</summary>
 OpenSpec is a standardized requirements-to-implementation workflow framework that ensures traceability and consistency from requirements to code through structured constraint set management.
 </details>
 <details>
 <summary>Q2: Is Codex/Gemini MCP required?</summary>
 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.
 </details>
 <details>
 <summary>Q3: What is the purpose of constraint sets?</summary>
 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.
 </details>
 ---
 ## License
 This project is open-sourced under the [MIT License](../LICENSE).
 Copyright (c) 2025 [guda.studio](mailto:gudaclaude@gmail.com)
 ---
 <div align="center">
 ## Power This Project with 🌟
 </div>
--- a/gudaspec/implementation.md
+++ 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]
 ---
 <!-- GUDASPEC:START -->
 **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 <proposal_id>`.
 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`.
 <!-- GUDASPEC:END -->
--- a/gudaspec/init.md
+++ 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]
 ---
 <!-- 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.
 - 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.
 <!-- GUDASPEC:END -->
--- a/gudaspec/plan.md
+++ 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]
 ---
 <!-- GUDASPEC:START -->
 **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 (`<proposal_id>`) they wish to refine into a zero-decision plan.
 2. Run `/openspec:proposal <proposal_id>`.
 3. **Multi-Model Implementation Analysis**: Invoke both MCP tools to provide diverse implementation perspectives:
   ```
   mcp__codex__codex: "Analyze proposal <proposal_id>: Provide implementation approach, identify technical risks, and suggest alternative architectures. Focus on edge cases and failure modes."
   mcp__gemini__gemini: "Analyze proposal <proposal_id>: 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 <proposal_id> for decision points that remain unspecified. List each as: [AMBIGUITY] <description> → [REQUIRED CONSTRAINT] <what must be decided>."
   mcp__gemini__gemini: "Identify implicit assumptions in proposal <proposal_id>. For each assumption, specify: [ASSUMPTION] <description> → [EXPLICIT CONSTRAINT NEEDED] <concrete specification>."
   ```
   **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 <proposal_id>. For each requirement, identify: [INVARIANT] <mathematical property that must always hold> → [FALSIFICATION STRATEGY] <how to generate test cases that attempt to break it>."
   mcp__gemini__gemini: "Analyze proposal <proposal_id> for system properties. Define: [PROPERTY] <name> | [DEFINITION] <formal description> | [BOUNDARY CONDITIONS] <edge cases to test> | [COUNTEREXAMPLE GENERATION] <approach>."
   ```
   **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 <id> --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 <id> --strict` returns zero issues
 - [ ] User has explicitly approved all constraint decisions
 <!-- GUDASPEC:END -->
--- a/gudaspec/research.md
+++ 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]
 ---
 <!-- GUDASPEC:RESEARCH:START -->
 **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 <requirement-description>` 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.
 <!-- GUDASPEC:RESEARCH:END -->
--- a/images/imp0.png
+++ b/images/imp0.png
--- a/images/imp1.png
+++ b/images/imp1.png
--- a/images/imp2.png
+++ b/images/imp2.png
--- a/images/imp3.png
+++ b/images/imp3.png
--- a/images/init0.png
+++ b/images/init0.png
--- a/images/init1.png
+++ b/images/init1.png
--- a/images/plan0.png
+++ b/images/plan0.png
--- a/images/plan1.png
+++ b/images/plan1.png
--- a/images/plan2.png
+++ b/images/plan2.png
--- a/images/plan3.png
+++ b/images/plan3.png
--- a/images/plan4.png
+++ b/images/plan4.png
--- a/images/research0.png
+++ b/images/research0.png
--- a/images/research1.png
+++ b/images/research1.png
--- a/images/research3.png
+++ b/images/research3.png
--- a/images/research4.png
+++ b/images/research4.png
--- a/images/result.png
+++ b/images/result.png
--- a/images/title.png
+++ b/images/title.png
--- a/install.ps1
+++ 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 <path>     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"
--- a/install.sh
+++ 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 <path>     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}"