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}"