Skip to content

QUICKSTART.md

Latest commit

 

History

History
311 lines (219 loc) · 7.57 KB

QUICKSTART.md

File metadata and controls

311 lines (219 loc) · 7.57 KB
Raw

GSI-Protocol Quick Start Guide

Language: English | 繁體中文

This guide will help you get started with GSI-Protocol in minutes.

Prerequisites

Before you begin, ensure you have:

  • Python 3.10+ installed on your system
  • Git installed
  • One of the supported AI platforms:
    • Claude Code CLI
    • Codex (OpenAI)
    • GitHub Copilot

Installation

Step 1: Install GSI-Protocol

Choose one of the following methods:

Using uvx (Recommended)

uvx --from gsi-protocol-installer gsi-install

Using pipx

pipx run gsi-protocol-installer

Step 2: Follow the Interactive Installer

The installer will ask you several questions:

  1. Select AI Platform(s)

    • Choose one or more: Claude Code, Codex, GitHub Copilot
    • Default: All platforms

  2. Choose Installation Type

    • Project: Install to current project (.claude/, .github/)
    • Global: Install to home directory (~/.claude/, ~/.codex/, ~/.github/)
    • Note: Codex only supports global installation

Step 3: Verify Installation

After installation, you should see:

✓ Installation complete! Total files installed: X

Claude Code / Codex usage:
  /sdd-auto <requirement>
  /sdd-spec <requirement>
  /sdd-arch <feature.feature>
  /sdd-impl <feature.feature>
  /sdd-verify <feature.feature>

Your First Workflow

Let's create a simple user authentication feature using GSI-Protocol.

Example: User Authentication

Option 1: Automatic Mode (Fastest)

Run the complete workflow with a single command:

/sdd-auto Add user authentication with email and password, including login and registration

This will automatically:

  1. Generate a Gherkin specification
  2. Design the architecture
  3. Implement the code
  4. Verify the implementation

Option 2: Manual Mode (More Control)

Execute each phase step-by-step:

Phase 1: Generate Specification

/sdd-spec Add user authentication with email and password, including login and registration

Output: features/user_authentication.feature

Phase 2: Design Architecture

/sdd-arch features/user_authentication.feature

Output: docs/features/user_authentication/architecture.md

Phase 3: Implement Code

/sdd-impl features/user_authentication.feature

Output: Source code files (location specified in architecture.md)

Phase 4: Verify Implementation

/sdd-verify features/user_authentication.feature

Output: docs/features/user_authentication/conclusion.md

Optional: Generate Unit Test Shells

/sdd-test features/user_authentication.feature

Output: Test method shells (methods with TODO comments only)

Understanding the Output

After running the workflow, you'll have:

1. Gherkin Specification (features/user_authentication.feature)

Feature: User Authentication
  Scenario: User registers successfully
    Given the user provides valid email and password
    When the user submits registration
    Then the account is created
    And the user receives confirmation

2. Architecture Document (docs/features/user_authentication/architecture.md)

Contains:

  • Project context (tech stack, frameworks)
  • Feature overview
  • Data models (User, Credentials, etc.)
  • Service interfaces (AuthService, UserRepository)
  • Architecture decisions
  • File structure planning

3. Implementation Files

Generated in your project's structure:

  • Model files (e.g., models/User.ts)
  • Service files (e.g., services/AuthService.ts)

4. Verification Report (docs/features/user_authentication/conclusion.md)

Contains:

  • Architecture compliance check
  • Scenario verification (Given-When-Then)
  • Summary (passed/failed)
  • Feedback for improvements

Platform-Specific Usage

Claude Code

/sdd-auto <requirement>

Codex (OpenAI)

/sdd-auto <requirement>
/sdd-spec <requirement>

GitHub Copilot

Prefix all commands with @workspace:

@workspace /sdd-auto <requirement>
@workspace /sdd-spec <requirement>

Tips and Best Practices

1. Write Clear Requirements

Good:

/sdd-auto Add user authentication with email/password, including registration, login, and password reset

Not optimal:

/sdd-auto auth stuff

2. Review Architecture Before Implementation

When using manual mode, review the generated architecture document before proceeding to implementation.

3. Iterate on Failed Verifications

If Phase 4 verification fails, review the conclusion report and re-run Phase 3 with corrections.

4. Use Unit Tests for TDD

For test-driven development, use this workflow:

/sdd-spec <requirement>
/sdd-arch features/your_feature.feature
/sdd-test features/your_feature.feature  # Create unit test shells
# Fill in unit test implementations
/sdd-impl features/your_feature.feature
/sdd-verify features/your_feature.feature

Note: /sdd-test filters scenarios suitable for unit testing and creates test method shells. You need to implement the test logic yourself.

5. Project-Aware Development

GSI-Protocol automatically detects:

  • Your tech stack (package.json, requirements.txt, go.mod, etc.)
  • Project structure (src/, models/, services/)
  • Code samples (*.ts, *.py, *.go)
  • Naming conventions

Common Workflows

Workflow 1: Quick Feature Addition

/sdd-auto Add pagination support to the product listing API

Workflow 2: Test-Driven Development

/sdd-spec Add product search with filters
/sdd-arch features/product_search.feature
/sdd-test features/product_search.feature  # Create unit test shells
# Fill in unit tests
/sdd-impl features/product_search.feature
/sdd-verify features/product_search.feature

Workflow 3: Architecture Review

/sdd-spec Implement shopping cart functionality
/sdd-arch features/shopping_cart.feature
# Review docs/features/shopping_cart/architecture.md
# Discuss with team
/sdd-impl features/shopping_cart.feature
/sdd-verify features/shopping_cart.feature

Troubleshooting

Installation Issues

Problem: "Git is not installed"

# Install git first
# macOS: brew install git
# Ubuntu: sudo apt-get install git
# Windows: Download from https://git-scm.com/downloads

Problem: "Command not found: /sdd-auto"

  • Ensure you selected the correct platform during installation
  • Check that commands are installed in the right directory
  • For Claude Code: ls ~/.claude/commands/ or ls .claude/commands/

Workflow Issues

Problem: Architecture doesn't match project structure

  • Review docs/features/{feature}/architecture.md
  • Re-run /sdd-arch with clearer requirements
  • Provide more context about your project structure

Problem: Verification fails

  • Read the conclusion report: docs/features/{feature}/conclusion.md
  • Check which scenarios failed
  • Re-run /sdd-impl with corrections

Next Steps

  1. Explore the generated files to understand the workflow
  2. Customize the architecture design for your needs
  3. Integrate with CI/CD by running verification in your pipeline
  4. Share specifications with your team using Gherkin files

Getting Help

What's Next?

Now that you've completed your first workflow, you can:

  • Explore advanced features and custom templates
  • Integrate with your existing CI/CD pipeline
  • Collaborate with your team using Gherkin specifications
  • Build complex features using the multi-phase workflow

Happy coding with GSI-Protocol!