OpenSPDD turns a coding prompt into a design contract you can sync back

The argument is that plans cannot be trusted and contracts can

OpenSPDD is described as a methodology and cross-platform CLI tool for the AI coding era, and it upgrades AI coding prompts from disposable inputs to executable design contracts with bidirectional synchronization between design and implementation. The problem it names is that existing AI coding tools generate plan documents, and the README tabulates what is wrong with them. A plan document is a task list, with no constraints, so the AI improvises freely. Its detail level is high level, on the model of create BillingService, rather than method signatures, parameters, error handling and dependency injection patterns. It has no traceability, because the documents do not update with the code. Its validation criteria are vague, on the model of done when complete. And its dependencies are implicit, left for the AI to infer. Against each of those, the REASONS Canvas is presented as a design contract with explicit constraints and explicit execution order. The core insight as the README puts it is that plans are suggestions while the canvas is a contract, and the underlying argument is that an AI without explicit constraints will improvise, and an AI without explicit ordering will restructure things arbitrarily.

Seven dimensions, grouped into three jobs

The REASONS Canvas is a seven dimensional structured design framework, and the letters spell out what each one holds. R is Requirements, the why, covering business goals and scope. E is Entities, the domain model, expressed as Mermaid class diagrams. A is Approach, the solution strategy and its trade-offs. S is Structure, the architecture, inheritance and dependencies. O is Operations, precise implementation tasks in order. N is Norms, the coding standards and patterns. And the second S is Safeguards, the constraints and guardrails. The README then explains why seven and not three, by grouping them into three roles. R plus E plus A are the design decisions, the why and the what. S plus O are the implementation path, the how. And N plus S are the quality guardrails. All three groups are described as essential, with the reasoning that without Norms and Safeguards the AI improvises, without Structure and Operations it restructures arbitrarily, and without Requirements, Entities and Approach it lacks context. The two S letters are the awkward part of the naming, since Structure and Safeguards share an initial, and anyone building tooling on top of the framework has to disambiguate them.

The workflow is four commands and a review step

The pipeline is presented as a diagram, and the shape is what matters. A business requirement goes into /spdd-analysis, which produces a strategic analysis covering concepts and risks. That feeds /spdd-reasons-canvas, which produces the design document. Then /spdd-generate produces code per the contract, followed by code review or refactoring, and then /spdd-sync performs a reverse sync that takes the changes back into the design.

/spdd-analysis
/spdd-reasons-canvas
/spdd-generate
/spdd-sync

The loop closes on itself, with the design staying in sync so the next iteration builds on an accurate design rather than an increasingly stale plan. The key principle the README states is that when reality diverges, you fix the prompt first and then update the code, which is the opposite of the usual reflex of patching the code and letting the document rot. The reverse sync is the mechanism that makes that principle enforceable, and the traceability claim in the comparison table depends entirely on it, so it is the command to test first if you are evaluating the tool rather than reading about it.

One binary that detects the environment you already have

The tool supports Cursor, Claude Code, GitHub Copilot, Antigravity, OpenCode and Codex, and it automatically detects which AI coding environment you are running in. The packaging is deliberately simple. All templates are embedded in the binary through Go's embed directive, so there is no template directory to keep in sync with the installation, and the interactive command selection uses a modern terminal UI. The go.mod shows a Go 1.23 module with a small direct dependency set, cobra for the command line and the charmbracelet huh library for the interactive forms, plus fatih/color for output, with the rest of the tree being the transitive dependencies of the terminal UI stack. The repository layout separates cmd/ for the entry point, internal/ for the implementation, spdd/ for the templates or command payloads, scripts/ for the install helper, tests/ and docs/, and there is a .cursor/ directory at the root, which is a hint about the environment the tool is built around.

Three ways to install it, and one detail that trips people up

Homebrew is the primary route, with a one-liner or a tap and install.

brew install gszhangwei/tools/openspdd

brew tap gszhangwei/tools
brew install openspdd

Or from source with the go tool.

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

The binary lands in the go bin directory, and the README is specific that it has to be on your PATH, giving the shell line for both zsh and bash.

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

The detail worth knowing is that the first run of openspdd detects the missing PATH entry and prints a one-time hint with the exact command for your shell, so the failure mode is self-correcting if you read the output. If you cloned the repository instead, scripts/install.sh runs go install and prints the PATH instructions automatically, and it accepts a tag argument to install a specific version.

Where the method is the wrong shape

The limitation is that a contract is only as good as the negotiation that produced it, and the negotiation is still done by a person. Filling in seven dimensions for a feature means writing the method signatures, the error messages, the HTTP status codes and the execution order before any code exists, which is a substantial amount of work, and for a small change it is a tax with no return. The second limit is the dependency on the model cooperating. The whole argument rests on the assumption that with Norms and Safeguards written down, the AI will not improvise, and that is an empirical claim about a system that is changing underneath the document. A design contract pins down the shape of the output, not the correctness of it, and nothing in the workflow described here tests the code against the contract, only syncs it. The third limit is the environment list. Six tools are supported, and a team on anything else falls back to whatever the auto-detection finds, which may be nothing. The last thing to weigh is that the project is young and pre-1.0, at v0.4.18, so the document format the reverse sync writes back is likely to move, and a team that adopts it should expect to migrate its design documents when it does.

Editorial conclusion

OpenSPDD suits a team that has tried prompt-driven development and found that the plan and the code drift apart within a sprint, since the reverse sync is the part that addresses the drift rather than the generation. It is the wrong tool for a solo developer on a small change, because filling in seven dimensions for a one line fix is pure overhead, and it is the wrong tool if your AI coding environment is not one of the six it detects. Before adopting it, install the binary, let the first run print its PATH hint, and check that the environment it auto-detects is the one you actually use, then try the workflow on a single feature rather than a whole service. The last push was on 2026-09-29 and the current release is v0.4.18 from 2026-07-02.

Frequently asked questions

Official sources

1. gszhangwei/open-spdd on GitHub
2. Issues
3. License: MIT
4. README
5. Releases