OpenSPDD

Structured Prompt-Driven Development — Transform AI coding prompts into executable design contracts

Chinese | Design Philosophy

Star History

OpenSPDD is a methodology and cross-platform CLI tool for the AI coding era. It upgrades AI coding prompts from "disposable inputs" to "executable design contracts" with bidirectional synchronization between design and implementation.

Why OpenSPDD?

Existing AI coding tools generate plan documents, but these documents have fundamental limitations:

The core insight: Plans are "suggestions", REASONS Canvas is a "contract".

The REASONS Canvas Framework

REASONS Canvas is a 7-dimensional structured design framework:

┌─────────────────────────────────────────────────────────────────────┐
│                        REASONS Canvas                                │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  R - Requirements    The "why" — business goals and scope            │
│  E - Entities        Domain model (Mermaid class diagrams)           │
│  A - Approach        Solution strategy and trade-offs                │
│  S - Structure       Architecture, inheritance, dependencies         │
│  O - Operations      Precise implementation tasks in order           │
│  N - Norms           Coding standards and patterns                   │
│  S - Safeguards      Constraints and guardrails                      │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

Why 7 dimensions?

• R+E+A = Design decisions ("Why" and "What")
• S+O = Implementation path ("How")
• N+S = Quality guardrails

All three are essential: without N+S, AI improvises; without S+O, AI restructures arbitrarily; without R+E+A, AI lacks context.

Core Workflow

┌─────────────────────────────────────────────────────────────────────┐
│                         SPDD Workflow                                │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  Business Requirement                                                │
│      │                                                               │
│      ▼                                                               │
│  /spdd-analysis ──────→ Strategic analysis (concepts, risks)         │
│      │                                                               │
│      ▼                                                               │
│  /spdd-reasons-canvas ─→ REASONS Canvas design document              │
│      │                                                               │
│      ▼                                                               │
│  /spdd-generate ───────→ AI generates code per contract              │
│      │                                                               │
│      ▼                                                               │
│  Code Review / Refactoring                                           │
│      │                                                               │
│      ▼                                                               │
│  /spdd-sync ───────────→ Reverse sync changes back to design         │
│      │                                                               │
│      ▼                                                               │
│  Design stays in sync ─→ Next iteration builds on accurate design    │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

Key principle: "When reality diverges, fix the prompt first — then update the code."

Features

• Cross-platform: Supports Cursor, Claude Code, GitHub Copilot, Antigravity, OpenCode, and Codex
• Auto-detection: Automatically detects your AI coding environment
• Single Binary: All templates embedded via Go's embed directive
• Bidirectional Sync: Keep design documents and code in sync
• Interactive UI: Modern terminal UI for command selection

Installation

Homebrew (macOS/Linux)

brew install gszhangwei/tools/openspdd

Or:

brew tap gszhangwei/tools
brew install openspdd

Go Install

go install github.com/gszhangwei/open-spdd/cmd/openspdd@latest

The binary is installed to $(go env GOPATH)/bin/openspdd (typically ~/go/bin/openspdd). Make sure that directory is on your $PATH:

# zsh
echo 'export PATH="$(go env GOPATH)/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

# bash
echo 'export PATH="$(go env GOPATH)/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

The first time openspdd runs, it will also detect this and print a one-time hint with the exact command for your shell.

One-shot installer script

If you cloned the repo, the script scripts/install.sh runs go install and prints PATH instructions automatically:

./scripts/install.sh           # installs @latest
./scripts/install.sh v1.2.3    # installs a specific tag

Download Binary

Download from GitHub Releases.

Uninstall

openspdd uninstall detects how the binary was installed (Homebrew or go install) and runs the matching cleanup. The plan is printed before any change, and confirmation is required by default.

# Preview without changing anything
openspdd uninstall --dry-run

# Interactive (default): prints the plan, asks for confirmation
openspdd uninstall

# Non-interactive (e.g., for scripts): skip the confirmation prompt
openspdd uninstall --yes

For a Homebrew install, this is equivalent to running brew uninstall gszhangwei/tools/openspdd plus a small first-run-marker cleanup. For a go install install, it removes the binary at the resolved path. If the install method cannot be classified (e.g., a manually-copied binary), uninstall refuses to act and prints the resolved path so you can remove it manually.

Scope: Only the openspdd binary and openspdd's own first-run marker are removed. Generated SPDD command templates inside your projects (.cursor/commands/spdd-*.md, .claude/commands/spdd-*.md, etc.) are user files and are left untouched. The Homebrew tap gszhangwei/tools is also left in place.

Quick Start

# Print the installed version
openspdd -v

# Navigate to your project
cd your-project

# Initialize (auto-detects AI tool)
openspdd init

# Generate SPDD commands
openspdd generate --all

Then in your AI coding tool, follow the complete SPDD workflow:

# Step 1: Strategic analysis (recommended for complex features)
/spdd-analysis @requirements/user-registration.md

# Step 2: Generate REASONS Canvas from analysis
/spdd-reasons-canvas @spdd/analysis/xxx.md

# Step 3: Generate code from REASONS Canvas
/spdd-generate @spdd/prompt/xxx.md

# Step 4: After code review/refactoring, sync changes back
/spdd-sync @spdd/prompt/xxx.md

For simpler features, you can skip Step 1 and provide requirements directly:

/spdd-reasons-canvas Implement user registration with email verification

Usage

Initialize Environment

# Auto-detect and initialize
openspdd init

# Specify tool manually
openspdd --tool cursor init

List Commands

# List available commands (core + tool-specific)
openspdd list

# List optional commands
openspdd list --optional

# List all commands
openspdd list --all

# Filter by category
openspdd list -c Development

Generate Commands

# Generate all default commands
openspdd generate --all

# Interactive selection
openspdd generate

# Generate specific command
openspdd generate spdd-generate

# Force overwrite
openspdd generate --force spdd-generate

Global Flags

openspdd --tool cursor 
openspdd --tool claude-code 
openspdd --tool antigravity 
openspdd --tool github-copilot 
openspdd --tool opencode 
openspdd --tool codex 

Supported Environments

OpenCode command naming follows the markdown filename (for example, spdd-analysis.md maps to /spdd-analysis). To avoid command alias conflicts in OpenCode, generated OpenCode command files intentionally omit frontmatter name.

Antigravity Skills

Antigravity generates project-scoped skill bundles under .agents/skills//SKILL.md adhering to the agentskills.io standard and Google Antigravity Customization Specification. Inside the Antigravity CLI (agy) or Antigravity IDE, invoke SPDD commands via /spdd-analysis, /spdd-reasons-canvas, etc., or rely on the agent's dynamic skill discovery based on task context. For global availability across all projects, skills can be symlinked into ~/.gemini/skills//.

Codex Skills

Codex generates project-scoped skill bundles under .agents/skills//SKILL.md (a cross-vendor open-standard directory; see agentskills.io) — not flat command files. Inside the Codex CLI / IDE extension, invoke SPDD commands with $spdd-analysis (etc.) Generated skills are configured for explicit-only invocation by default (agents/openai.yaml sets allow_implicit_invocation: false); pass --allow-implicit to opt into Codex's auto-invocation behavior. Trust-model note: on some Codex versions skills from untrusted projects are silently ignored — if the skills do not appear after generation, confirm the project is marked trusted in your ~/.codex/config.toml (see openai/codex#9752). If the skills still do not appear after a generate run, restart Codex (per official docs).

GitHub Copilot File Structure

.github/
├── copilot-instructions.md     # Main instruction file (auto-merged with markers)
└── copilot-prompts/
    ├── spdd-analysis.md
    ├── spdd-reasons-canvas.md
    ├── spdd-generate.md
    ├── spdd-prompt-update.md
    └── spdd-sync.md

Available Commands

Core Commands

Tool-Specific Commands

Optional Commands (Beta)

The following commands are available as beta — not installed by default, but can be installed manually:

# List all optional commands
openspdd list --optional

# Install a specific optional command
openspdd generate spdd-story
openspdd generate spdd-code-review
openspdd generate spdd-api-test
openspdd generate spdd-reverse

Plan vs REASONS Canvas: An Example

Scenario: Implement user registration

Typical Plan:

1. Create UserRegistrationController
2. Create UserRegistrationService
3. Create UserRegistrationRequest DTO
4. Implement email validation
5. Save user to database

REASONS Canvas (Operations excerpt):

### Create UserRegistrationService - `UserRegistrationServiceImpl`

1. **Responsibility**: Handle user registration business logic
2. **Package**: `com.example.user.service.impl`
3. **Implements**: `UserRegistrationService` interface
4. **Dependencies** (constructor injection):
   - `UserRepository userRepository`
   - `EmailValidator emailValidator`
   - `PasswordEncoder passwordEncoder`
5. **Methods**:
   - `register(UserRegistrationRequest request): UserRegistrationResponse`
     - **Input Validation**: Call `emailValidator.validate(request.getEmail())`
     - **Business Logic**:
       1. Check if email exists via `userRepository.existsByEmail()`
       2. If exists, throw `EmailAlreadyExistsException` with message "Email already registered"
       3. Encode password via `passwordEncoder.encode()`
       4. Create User entity with status `PENDING_VERIFICATION`
       5. Save via `userRepository.save()`
     - **Exception Handling**: Let exceptions propagate to GlobalExceptionHandler
6. **Annotations**: `@Service`, `@Transactional`

The difference: Plan says "what to do", REASONS Canvas specifies "exactly how to do it".

When to Use OpenSPDD

Building from Source

git clone https://github.com/gszhangwei/open-spdd.git
cd open-spdd
go build -o openspdd ./cmd/openspdd
go install ./cmd/openspdd

Testing

# Run all tests
go test ./tests/...

# Run with verbose output
go test ./tests/... -v

# Run specific module tests
go test ./tests/detector/...
go test ./tests/templates/...

CI runs gofmt, go vet and go test ./... on every push to main and every pull request (.github/workflows/ci.yaml).

License

MIT License