GSI-Protocol

Specification-Driven Development (SDD) Workflow for AI-powered Development

Language: English | 繁體中文

GSI-Protocol is an automated Specification-Driven Development (SDD) workflow system that transforms user requirements into production-ready code through a structured 4-phase process: Specification → Architecture → Implementation → Verification.

Features

• Multi-Platform Support: Works with Claude Code, Codex (OpenAI), and GitHub Copilot
• Language Agnostic: Architecture design independent of programming language
• Automated Workflow: Execute complete development cycle with a single command
• BDD Integration: Built-in support for Gherkin specifications and integration tests
• Project-Aware: Automatically detects and adapts to your project's tech stack
• Role-Based Phases: PM → Architect → Engineer → QA workflow

📚 Learn More

New to GSI-Protocol? Start here:

• GSI Theory & Methodology - Deep dive into the Gherkin-Structure-Implement methodology
• Quick Start Guide - Step-by-step tutorial to build your first feature

Quick Start

Installation

Install using uvx (recommended):

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

Or using pipx:

pipx run gsi-protocol-installer

The installer will guide you through:

1. Selecting AI platform(s) (Claude Code, Codex, GitHub Copilot)
2. Choosing installation type (global or project-specific)
3. Installing workflow commands

Basic Usage

Automatic Mode (Recommended)

Execute the complete 4-phase workflow automatically:

# For Claude Code / Codex
/sdd-auto <your requirement>

# For GitHub Copilot
@workspace /sdd-auto <your requirement>

Example:

/sdd-auto Add user authentication with email and password

Manual Mode

For more control over each phase:

1. Generate Specification (PM Phase)

   /sdd-spec <requirement>

2. Design Architecture (Architect Phase)

   /sdd-arch <feature_file_path>

3. Implement Code (Engineer Phase)

   /sdd-impl <feature_file_path>

4. Verify Implementation (QA Phase)

   /sdd-verify <feature_file_path>

5. Generate Integration Tests (Optional)

   /sdd-integration-test <feature_file_path>

Workflow Overview

The GSI-Protocol follows a structured 4-phase process:

User Requirement
      ↓
[Phase 1: Specification (PM)]
   → features/{feature}.feature (Gherkin)
      ↓
[Phase 2: Architecture (Architect)]
   → docs/features/{feature}/architecture.md
      ↓
[Phase 3: Implementation (Engineer)]
   → Source code files
      ↓
[Phase 4: Verification (QA)]
   → docs/features/{feature}/conclusion.md

Learn the methodology: Read our GSI Theory & Methodology guide to understand how Gherkin (specification), Structure (architecture), and Implement (code) work together.

Available Commands

Command	Description	Phase
/sdd-auto	Execute complete workflow automatically	All
/sdd-spec	Generate Gherkin specification from requirements	1
/sdd-arch	Design architecture from specification	2
/sdd-impl	Implement code based on architecture	3
/sdd-verify	Verify implementation against spec	4
/sdd-integration-test	Generate BDD integration tests	Optional

Output Structure

After running the workflow, your project will have:

project_root/
├── features/
│   └── {feature_name}.feature          # Gherkin specifications
├── docs/
│   └── features/
│       └── {feature_name}/
│           ├── architecture.md         # Architecture design
│           └── conclusion.md           # Verification report
└── {your_project_structure}/
    ├── {model_files}                   # Generated models
    └── {service_files}                 # Generated services

Platform-Specific Usage

Claude Code

Commands are available directly in Claude Code CLI:

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

Codex (OpenAI)

Use prompts with argument placeholders:

/sdd-auto <requirement>

GitHub Copilot

Prefix commands with @workspace:

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

Requirements

• Python 3.10 or higher
• Git
• One of the supported AI platforms:
  • Claude Code CLI
  • Codex (OpenAI)
  • GitHub Copilot

Documentation

For detailed documentation, see the docs directory:

• GSI Theory & Methodology - Understand the G-S-I pillars
• Quick Start Guide - Get started in minutes

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

James Hsueh - [email protected]

Links

• Homepage
• Issues
• Repository

Changelog

See version history and updates in the project repository.