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
• Project-Aware: Automatically detects and adapts to your project's tech stack
• Frontend/Backend Aware: Detects project type and picks the acceptance angle — API contract (backend) or UI feedback (frontend); full-stack gets both
• 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>

Workflow Overview

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

User Requirement
      ↓
[Phase 1: Specification (PM)]
   → .gsi/{feature}/PRD.md (business behaviour)
   → .gsi/{feature}/{feature}.feature (tagged @api or @ui;
     full-stack → {feature}.api.feature + {feature}.ui.feature)
      ↓
[Phase 2: Architecture (Architect)]
   → .gsi/{feature}/architecture.md
      ↓
[Phase 3: Implementation (Engineer)]
   → Source code + tests (TDD; @ui adds E2E/component tests)
      ↓
[Phase 4: Verification (QA)]
   → @api → specbridge verify;  @ui → E2E runner (Playwright/Cypress)
   → + unit tests
   → .gsi/{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 PRD + SpecBridge contract from requirements	1
/sdd-arch	Design architecture from specification	2
/sdd-impl	Implement code + unit tests (TDD)	3
/sdd-verify	Verify via specbridge + unit tests	4

Output Structure

After running the workflow, your project will have:

project_root/
├── .gsi/{feature_name}/
│   ├── PRD.md                          # Business behaviour spec
│   ├── {feature_name}.feature          # tagged @api or @ui (full-stack: .api/.ui.feature)
│   ├── architecture.md                 # Architecture design
│   └── conclusion.md                   # Verification report
└── {your_project_structure}/
    ├── {model_files}                   # Generated models
    ├── {service_files}                 # Generated services
    └── {unit_test_files}               # TDD-produced tests

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
• Node.js 18 or higher
• Git
• One of the supported AI platforms:
  • Claude Code CLI
  • Codex (OpenAI)
  • GitHub Copilot

SpecBridge (Required)

GSI-Protocol integrates SpecBridge in the Specification (/sdd-spec) and Verification (/sdd-verify) phases. SpecBridge is a contract testing CLI that validates live HTTP API behavior against Gherkin feature files.

Install it globally before using GSI-Protocol:

npm install -g @ksz54213/specbridge

Verify installation:

specbridge --version

SpecBridge covers the @api acceptance angle. For frontend (@ui) features, verification runs the feature file through Playwright (see below) instead.

Playwright + playwright-bdd (for frontend @ui features)

This is the frontend counterpart to SpecBridge: it makes the @ui feature file directly executable by compiling its Gherkin scenarios into Playwright tests via playwright-bdd — no per-scenario test code to write.

Unlike SpecBridge, these must be installed in the project as devDependencies — Playwright's test runner resolves @playwright/test and playwright-bdd from the project's local node_modules when running npx playwright test, so a global install won't be picked up:

npm install -D playwright @playwright/test playwright-bdd
npx playwright install   # download browsers (one-time)

Beyond the packages, the project gains test artifacts (a playwright.config.ts, the standard GSI step library, and a page→URL map under e2e/) — generated once by sdd-impl and reused by every @ui feature. If the project already has Playwright set up, GSI reuses it instead of installing.

Backend-only projects need nothing here — only SpecBridge. Playwright is only needed once a project has a @ui feature.

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 - asdfg55887@gmail.com

Links

• Landing Page
• Homepage
• Issues
• Repository

Changelog

See version history and updates in the project repository.