DOCSEARCHbyAlgolia
Submit Docs

GudaStudio Commands

repository·main·Indexed 21 days ago

https://github.com/gudastudio/commands

A specialized command set for Claude Code that implements the RPI (Research-Plan-Implementation) coding theory. It provides the `gudaspec` command set—including `/gudaspec:init`, `/gudaspec:research`, `/gudaspec:plan`, and `/gudaspec:implementation`—to manage complex tasks via OpenSpec and multi-model collaboration while optimizing the 80K context window.

Tokens
2.6K
Snippets
5
Records
9
Agent score
25%

What's inside gudastudio-commands

  1. The gudaspec command set

    main

    The gudaspec command set implements the RPI (Research-Plan-Implementation) coding theory. It is designed to help Claude Code handle complex, long-duration coding tasks by breaking them into stages and managing context effectively through OpenSpec and multi-model collaboration.

    Command Overview

    • /gudaspec:init: Initializes the OpenSpec environment and verifies MCP tool availability.
    • /gudaspec:research: Explores the codebase in parallel and converts requirements into a set of constraints.
    • /gudaspec:plan: Performs multi-model analysis to generate a zero-decision execution plan and PBT (Property-Based Testing) attributes.
    • /gudaspec:implementation: Executes multi-model collaboration to transform prototypes into production-grade code.

  2. What is OpenSpec?

    main
    OpenSpec is a standardized requirements-to-implementation workflow framework used by GudaStudio. It ensures traceability and consistency from initial requirements to final code through structured constraint set management. By transforming requirements into specific technical constraints, it eliminates decision points during the implementation phase, making coding a process of mechanical execution rather than real-time judgment.

  3. How the RPI Workflow works with gudaspec

    main

    GudaStudio uses the RPI (Research-Plan-Implementation) workflow to prevent context overflow and ensure high-quality code. The workflow is divided into four distinct phases:

    1. Initialization (/gudaspec:init): Sets up the openspec environment and detects available MCP tools (like Codex or Gemini).
    2. Research (/gudaspec:research): Transforms raw user requirements into a structured OpenSpec document. This phase explores the codebase and identifies technical constraints.
    3. Planning (/gudaspec:plan): Uses multi-model collaboration to analyze the requirements and generate a zero-decision execution plan. This plan includes Property-Based Testing (PBT) properties for verification.
    4. Implementation (/gudaspec:implementation): Executes the plan through incremental, verifiable tasks. It uses multi-model code prototype retrieval (e.g., Gemini for UI, Codex for Logic) and performs multi-model reviews.

    Best Practice: To keep Claude's focus sharp, use /clear to start a new conversation window between these phases, especially when the context approaches 80K tokens.

  4. Configure Global Protocols in CLAUDE.md

    main

    To ensure Claude Code follows the GudaStudio workflow (e.g., using English for tool interaction, Chinese for user output, and strict code sovereignty), add the following protocols to your ~/.claude/CLAUDE.md file.

    # CLAUDE.md

## 0. Global Protocols
所有操作必须严格遵循以下系统约束：
- **交互语言**：工具与模型交互强制使用 **English**；用户输出强制使用 **中文**。
- **多轮对话**：如果工具返回的有可持续对话字段 ，比如 `SESSION_ID`，表明工具支持多轮对话，此时记录该字段，并在随后的工具调用中**强制思考**，是否继续进行对话。
- **沙箱安全**：严禁 Codex/Gemini 对文件系统进行写操作。所有代码获取必须请求 `unified diff patch` 格式。
- **代码主权**：外部模型生成的代码仅作为逻辑参考（Prototype），最终交付代码**必须经过重构**，确保无冗余、企业级标准。
- **风格定义**：整体代码风格**始终定位**为，精简高效、毫无冗余。对于注释与文档，严格遵循**非必要不形成**的核心原则。
- **仅对需求做针对性改动**：严禁影响用户现有的其他功能。
- **上下文检索**： 调用 `mcp__auggie-mcp__codebase-retrieval`，必须减少search/find/grep的次数。
- **判断依据**：始终以项目代码、grok的搜索结果作为判断依据，严禁使用一般知识进行猜测。在调用编程语言的非内置库时，必须启用grok搜索。
- **MUST** ultrathink in English.

  5. Configure Global Prompt for GudaStudio

    main

    To ensure Claude Code follows the GudaStudio operational philosophy (such as English-only tool interactions, sandbox security, and code sovereignty), add the following protocol to your ~/.claude/CLAUDE.md file:

    # 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.
    # 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**: ... (see full content for details)

  6. How to use the RPI workflow with gudaspec

    main

    The GudaStudio workflow is divided into four distinct stages. It is highly recommended to use Claude Opus 4.5 with Reasoning Mode enabled and to use /clear between stages to manage the 80K context window.

    Stage 0: Initialization

    Run /gudaspec:init in your project to install openspec and detect MCP tools (Codex-MCP/Gemini-MCP). After initialization, use /clear to start fresh.

    Stage 1: Research

    Use /gudaspec:research <your_requirement> to have Claude explore the codebase and generate an OpenSpec proposal. This stage converts requirements into technical constraints.

    Stage 2: Plan

    Run /gudaspec:plan in a new session. Claude will use multi-model collaboration (Codex/Gemini) to refine the requirements, eliminate technical ambiguity, and generate a zero-decision execution pipeline with PBT attributes. Use /clear when finished.

    Stage 3: Implementation

    Run /gudaspec:implementation in a new session. Claude will identify the smallest verifiable tasks and implement them step-by-step.

    Context Management Tip: If the context window approaches 80K, use /clear and resume from /gudaspec:implementation to maintain high focus.

    # Example Workflow Summary
1. /gudaspec:init
2. /clear
3. /gudaspec:research [Requirement]
4. /clear
5. /gudaspec:plan
6. /clear
7. /gudaspec:implementation

  7. Install GudaStudio Commands

    main

    Install the gudaspec command set into your Claude Code environment. You can choose between a user-level installation (applies to all projects) or a project-level installation (applies only to the current directory).

    Prerequisites

    Installation Commands

    Linux / macOS

    # 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)

    # 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
    # User-level installation (applies to all projects)
./install.sh --user

  8. Use the gudaspec Command Set

    main

    The gudaspec command set implements the RPI (Research-Plan-Implementation) coding theory. Use these commands within Claude Code to manage complex coding tasks by segmenting context across different phases.

    CommandFunction
    /gudaspec:initInitialize OpenSpec environment, verify MCP tool availability
    /gudaspec:researchParallel codebase exploration, transform requirements into constraint sets
    /gudaspec:planMulti-model analysis, generate zero-decision execution plans with PBT properties
    /gudaspec:implementationMulti-model collaborative implementation, refactor prototypes into production-grade code

    Note: After each major phase (like init or plan), it is recommended to use /clear to reset the conversation context and maximize the effective context window (~80K).

  9. Reference: Installation Script Arguments

    main

    The following arguments are supported by the installation scripts for both Bash and PowerShell environments.

    |---|---|---|---|---|
|--user|-User|-u|Install to user directory (~/.claude/commands/)||
|--project|-Project|-p|Install to project directory (./.claude/commands/)||
|--target <path>|-Target <path>|-t|Install to custom path|
|--help|-Help|-h|Show help information|