Structured Prompt-Driven Development — Transform AI coding prompts into executable design contracts
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.
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".
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.
┌─────────────────────────────────────────────────────────────────────┐
│ 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."
- 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
brew install gszhangwei/tools/openspddOr:
brew tap gszhangwei/tools
brew install openspddgo install github.com/gszhangwei/open-spdd/cmd/openspdd@latestThe 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 ~/.bashrcThe first time openspdd runs, it will also detect this and print a one-time hint with the exact command for your shell.
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 tagDownload from GitHub Releases.
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 --yesFor 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 tapgszhangwei/toolsis also left in place.
# 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 --allThen 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.mdFor simpler features, you can skip Step 1 and provide requirements directly:
/spdd-reasons-canvas Implement user registration with email verification# Auto-detect and initialize
openspdd init
# Specify tool manually
openspdd --tool cursor init# 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 all default commands
openspdd generate --all
# Interactive selection
openspdd generate
# Generate specific command
openspdd generate spdd-generate
# Force overwrite
openspdd generate --force spdd-generateopenspdd --tool cursor <command>
openspdd --tool claude-code <command>
openspdd --tool antigravity <command>
openspdd --tool github-copilot <command>
openspdd --tool opencode <command>
openspdd --tool codex <command>| 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 generates project-scoped skill bundles under .agents/skills/<id>/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-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
| 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 | Command | Description |
|---|---|---|
| GitHub Copilot | copilot-instructions |
Main instruction file for Copilot |
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-reverseScenario: 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".
| 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 is needed |
| One-off scripts | Not recommended | ROI too low |
git clone https://github.com/gszhangwei/open-spdd.git
cd open-spdd
go build -o openspdd ./cmd/openspdd
go install ./cmd/openspdd# 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/...
