open-spdd

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:

Problem	Typical Plan Documents	REASONS Canvas
Nature	Task list	Design contract
Constraints	None — AI improvises freely	Explicit — Norms define "how", Safeguards define "what not to do"
Detail Level	High-level: "Create BillingService"	Precise: method signatures, parameters, error handling, DI patterns
Traceability	None — docs don't update with code	Yes — /spdd-sync enables reverse sync
Validation	Vague — "done when complete"	Explicit — exact error messages, HTTP status codes in Safeguards
Dependencies	Implicit — AI infers	Explicit — Operations define strict execution order

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

The REASONS Canvas Framework

REASONS Canvas is a 7-dimensional structured design framework:

…

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

…

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

Tool	Detection	Config Directory
Cursor	.cursor/, .cursorrules	.cursor/commands/
Claude Code	.claude/, CLAUDE.md	.claude/commands/
Antigravity	.antigravity/	.antigravity/commands/
GitHub Copilot	.github/copilot-instructions.md, .github/copilot-prompts/	.github/copilot-prompts/
OpenCode	.opencode/, opencode.json	.opencode/commands/
Codex	.codex/, .codex/config.toml	.agents/skills/

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.

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

Command	Description
spdd-analysis	Strategic analysis of requirements
spdd-reasons-canvas	Generate REASONS-Canvas structured prompts
spdd-generate	Generate code from structured SPDD prompt files
spdd-prompt-update	Update existing SPDD prompt with new requirements
spdd-sync	Sync code changes back to SPDD prompt files

Tool-Specific Commands

Tool	Command	Description
GitHub Copilot	copilot-instructions	Main instruction file for Copilot

Optional Commands (Beta)

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

Command	Description
spdd-story	Decompose feature requirements into INVEST-compliant stories with acceptance criteria
spdd-code-review	Review code against REASONS-Canvas, detecting intent drift and violations
spdd-api-test	Generate self-contained shell scripts with cURL commands for API testing
spdd-reverse	Reverse-engineer existing code into a REASONS-Canvas prompt for legacy onboarding

# 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):

…

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

When to Use OpenSPDD

Scenario	Recommendation	Reason
Enterprise feature development	Highly recommended	Design-implementation traceability, long-term maintainability
Team collaboration	Highly recommended	Unified AI coding standards, reduced style conflicts
Complex refactoring	Recommended	Strict Operations order prevents dependency chaos
Cross-tool workflows	Recommended	Same REASONS Canvas works across different AI tools
Quick prototypes	Consider	May be overhead, but valuable if maintenance i