GuDaStudio/commands
1
0
Fork 0
mirror of https://github.com/GuDaStudio/commands.git synced 2026-03-22 19:18:52 +08:00
Code Issues Packages Projects Releases Wiki Activity

v0.0：初始版本

Browse Source
This commit is contained in:
GuDaStudio
2026-01-22 17:31:11 +08:00
commit 743c8a48fc
26 changed files with 992 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

29
gudaspec/implementation.md Normal file
View File

@@ -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 -->

59
gudaspec/init.md Normal file
View File

@@ -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 -->

81
gudaspec/plan.md Normal file
View File

@@ -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 -->

106
gudaspec/research.md Normal file
View File

@@ -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 -->