specwright

AI agents optimise for done. Specwright optimises for works.

---

Project status: unmaintained

Specwright is no longer under active development. The concepts — spec-driven flow, quality gates, auditable evidence, and learning capture — validated well in practice, but the plugin/skills implementation hit structural limits that prevented taking them further. Subsequent work on auditability, gating, and guardrails has moved into a purpose-built harness rather than a plugin.

The repository remains public as a reference. Occasional minor fixes may still land, and the project could be revived in the future, but no roadmap work, feature requests, or support should be expected. Issues and pull requests may not receive a response.

---

Why Specwright?

AI agents optimise for "done." That's the problem. Code compiles, tests pass, CI is green — and three days later you find an export nobody imports, a handler that's never called, a validation rule that exists in the spec but not in the code. The hard part isn't writing code. It's proving it works.

Specwright closes the entire loop — design, plan, build, verify, ship, learn. Every requirement is tracked to implementation evidence. Every PR ships with proof, not promises.

Without Specwright

• AI optimises for "task done" not "feature works"
• Fast delivery of broken, unwired code
• Tests pass but features aren't connected
• Context loss during long sessions causes drift
• No evidence trail for what was verified
• Every project re-invents the same workflow

With Specwright

• Specs before implementation, always
• Wiring verification catches orphaned code and broken connections
• Evidence-based PRs with gate proof for every acceptance criterion
• Compaction recovery reloads full context automatically
• Learning system captures failures and promotes patterns across sessions
• Codebase knowledge persists across sessions — no re-discovering the same architecture
• Periodic health checks find systemic debt that per-change gates miss
• One install, configure once, works with any language or framework
• Cross-platform: works with Claude Code, Opencode, Codex CLI, and any agent that reads AGENTS.md

How It Compares

Capability	Specwright	Spec Kit	Oh-My-ClaudeCode	Superpowers	Manual workflows
Structured spec writing	Yes	Yes — core strength	Yes	Yes	DIY
Adversarial TDD (separate tester/executor)	Yes	No	Yes	Yes	No
Wiring verification (orphaned code, layer violations)	Yes	No	No	No	No
Evidence-based PRs (criterion → code + test)	Yes	No	No	No	No
Quality gates with findings (not just badges)	Yes	Partial	Yes	Partial	DIY
Compaction recovery	Yes	No	Yes	No	No
Learning system (patterns promoted across sessions)	Yes	No	Yes	Yes	No
Codebase knowledge persistence	Yes	No	Yes	No	No

Every tool in this space pushes AI-assisted development forward. Specwright's focus is the verification and evidence gap — the part between "tests pass" and "it actually works."

What Makes This Different

Other tools in this space tend to focus on the front half of the loop — specification authoring, agent orchestration, or planning scaffolds — then hand off to the AI. The hard part isn't planning or delegation. It's everything after: does the code actually do what was asked? Is it wired up? Is it secure? Can you prove it?

Specwright focuses on the verification and evidence side — the part where AI agents actually fail.

Autonomous Gated Engineering — Skills operate autonomously between human gates, applying a decision protocol grounded in Amazon's Type 1/Type 2 framework, Google's SRE heuristics, and the Principle of Least Surprise. Every autonomous decision is recorded in decisions.md and surfaced at the gate handoff. Humans review at skill transitions — like reviewing a PR, not like pair programming. 64 intervention points reduced to 5 human gates.

Tiered Test Execution — gate-build runs four test tiers in order: build → unit → integration → smoke. Integration tests validate against real infrastructure (databases, clusters, APIs). Smoke tests verify critical paths end-to-end. The inner-loop in sw-build runs integration tests after TDD — catching runtime issues while the build-fixer is still in context, just like a real engineer who starts the app and checks it works before submitting a PR.

Evidence Pipeline — Six sequential gates capture proof into structured reports. PRs ship with a compliance matrix mapping every acceptance criterion to code and test evidence. Reviewers don't have to trust — they can verify.

Wiring Verification — Static analysis catches orphaned files, unused exports, layer violations, and circular dependencies. Other tools check if code compiles and tests pass. Specwright checks if the code is actually connected.

Learning System — Failures are captured, patterns are promoted, and learnings compact into tiered memory (index, themes, raw data). The system gets smarter with every session. Knowledge survives context windows.

Codebase Knowledge — During init, Specwright surveys your codebase and builds a persistent knowledge document (LANDSCAPE.md) covering architecture, modules, conventions, and gotchas. Design phases load this instantly instead of re-scanning. It stays current — refreshed when stale, incrementally updated after every shipped work unit.

Codebase Health Checks — Run /sw-audit periodically to find systemic issues that per-change gates miss: architecture debt, complexity growth, convention drift, accumulated workarounds. Findings persist in AUDIT.md with stable IDs across re-runs. Design phases surface relevant findings. The learn phase resolves them when addressed.

Compaction Recovery — All stateful skills support resume-from-crash. When Claude's context window compacts, Specwright reloads full state from disk — including workflow stage, work unit queue, and gate progress — so no manual re-orientation is needed.

How It Works

graph LR
    A["/sw-init"] --> B["/sw-design"]
    B --> C["/sw-plan"]
    C --> D["/sw-build"]
    D --> E["/sw-verify"]
    E --> F["/sw-ship"]
    F -.->|next work unit| D
    F --> G["/sw-learn"]
    G -.->|patterns feed back| B
    H["/sw-audit"] -.->|findings feed into| B
    I["/sw-research"] -.->|briefs feed into| B

    style A fill:#1e293b,stroke:#f59e0b,color:#f8fafc
    style B fill:#1e293b,stroke:#f59e0b,color:#f8fafc
    style C fill:#1e293b,stroke:#f59e0b,color:#f8fafc
    style D fill:#1e293b,stroke:#f59e0b,color:#f8fafc
    style E fill:#1e293b,stroke:#f59e0b,color:#f8fafc
    style F fill:#1e293b,stroke:#f59e0b,color:#f8fafc
    style G fill:#1e293b,stroke:#f59e0b,color:#f8fafc
    style H fill:#1e293b,stroke:#f59e0b,color:#f8fafc
    style I fill:#1e293b,stroke:#f59e0b,color:#f8fafc

Phase	What Happens	Key Innovation
Init	Detect stack, configure gates, create anchor documents	Auto-detection — don't ask what you can infer
Research	Investigate external docs, APIs, patterns; produce validated briefs	Evidence-graded findings with confidence scoring
Design	Research codebase, design solution, adversarial critic — autonomously with gate handoff	Decisions recorded, human reviews at the gate
Plan	Decompose into work units, write testable acceptance criteria	Specs grounded in approved design artifacts
Build	TDD + inner-loop validation against real infrastructure. Optional parallel execution (experimental).	Integration tests run during build, not just at verify
Verify	6 quality gates with tiered test execution and evidence capture	Findings shown inline, not just pass/fail badges
Ship	PR with acceptance criteria mapped to evidence	Every requirement traceable to code + test
Learn	Capture patterns, auto-promote by objective criteria	Knowledge compounds across sessions
Audit	Periodic health check — architecture, complexity, consistency, debt	Finds systemic issues gates miss. Run anytime.

Quick Start

Claude Code

/plugin marketplace add Obsidian-Owl/specwright
/plugin install specwright@specwright

Opencode

Add the plugin to your opencode.json:

{
  "plugin": ["@obsidian-owl/opencode-specwright@latest"]
}

Opencode installs the package automatically on next startup — no manual npm install needed.

Codex CLI

Install for your user account:

curl -fsSL https://raw.githubusercontent.com/Obsidian-Owl/specwright/main/scripts/install-codex.sh | bash -s -- --user

Or install into the current repository:

curl -fsSL https://raw.githubusercontent.com/Obsidian-Owl/specwright/main/scripts/install-codex.sh | bash -s -- --repo

Then open Codex and enable the plugin from the plugin directory:

/plugins

The installer downloads the latest prebuilt Codex bundle from GitHub Releases, installs it into plugins/specwright under the selected scope, and updates the matching Codex marketplace manifest. It requires curl, tar, and python3.

To update later:

curl -fsSL https://raw.githubusercontent.com/Obsidian-Owl/specwright/main/scripts/install-codex.sh | bash -s -- --update --user

Manual install:

• Download specwright-codex.tar.gz from GitHub Releases.
• Extract it to ~/plugins/specwright for a user install or <repo>/plugins/specwright for a repo install.
• Add a specwright entry to ~/.agents/plugins/marketplace.json or <repo>/.agents/plugins/marketplace.json with source.path set to ./plugins/specwright.

Packaged Codex installs use the prebuilt plugin bundle and its bundled slash-command contract. If you are developing Specwright itself and only need repo-local skills-only mode, use the source tree directly instead of the packaged installer above.

This enables:

• /sw-* slash commands
• Session hooks (resume context + shipping guard + continuation snapshots)

Other Agents (AGENTS.md compatible)

Any AI coding agent that reads AGENTS.md can use Specwright's core skills directly. Copy or symlink the core/ directory into your project and point your agent at AGENTS.md.

Initialize your project:

/sw-init