spec-guard 0.2.5

Validation-first workflow for AI-assisted development.

SpecGuard

SpecGuard blocks weak specs before AI coding agents turn them into defective code.

SpecGuard is a Validation-First Workflow (VFW) for AI-assisted development. It turns specs into reviewed, testable, implementation-ready packages before AI coding begins.

It is not a prompt-to-code generator. SpecGuard helps you prepare an approved spec package before an external Codex, Claude Code, or another coding agent writes application code.

Discovery -> Spec Package -> Technical Design -> SpecGuard Review
-> Test -> Contract -> Implementation Handoff
-> External AI Implementation -> Pull Request -> SpecGuard PR Review

Core Reviews

SpecGuard centers on two review steps:

• SpecGuard Review runs before code generation. It checks whether the spec package has important gaps in product behavior, contracts, data ownership, authorization, state transitions, error cases, or executable verification before an implementation agent starts coding.
• SpecGuard PR Review runs after code is implemented. It compares the approved spec package, implementation handoff, and pull request diff, then posts an advisory PR comment when the implementation appears to drift from the spec, tests, contracts, security expectations, or operational requirements.

Current Support Status

Currently, local Codex mode is the recommended and release-tested path for live SpecGuard Review. OpenAI Platform mode is implemented for the Responses API, including PR Review execution, but the clean end-to-end release test has not been completed yet. Treat OpenAI Platform mode as experimental until published-install validation is finished.

Setup To User Flow

This is the shortest path from installation to a reviewed implementation PR.

1. Install

SpecGuard expects Python 3.11 or newer.

pip install spec-guard
specguard --help

2. Configure Codex

Then configure SpecGuard to use local Codex:

specguard auth setup --mode codex --model gpt-5.4
specguard auth status

Codex mode uses a 600-second request timeout by default because run can ask Codex to review the full spec package. auth status confirms the saved configuration and local Codex command availability; the first full provider request happens during init, run, or follow-up regeneration.

For a faster local review profile, configure an explicit Codex reasoning effort or a Codex profile:

specguard auth setup --mode codex --model gpt-5.4 --codex-reasoning-effort medium --skip-login
specguard auth status

Lower reasoning effort can reduce latency, while higher effort may improve review depth. SpecGuard keeps Codex defaults unless you opt in.

If Codex is already logged in and you do not want setup to offer codex login:

specguard auth setup --mode codex --model gpt-5.4 --skip-login

3. Create A Feature Spec

specguard init your-feature-name

SpecGuard writes draft artifacts and the default readiness workflow:

specs/your-feature-name/
|-- discovery.md
|-- spec.md
|-- plan.md
|-- tasks.md
|-- constitution.md
`-- checklists/spec-readiness.md
.github/
`-- workflows/specguard-readiness-gate.yml

For real work, this is where the user writes the actual development spec. Strengthen specs/your-feature-name/ with product behavior, API or UI expectations, data ownership, authorization rules, state transitions, error cases, and acceptance criteria before running validation.

init installs the default SpecGuard Readiness Gate GitHub Actions workflow so changed spec packages can be checked on pull requests. Use --no-actions when you do not want SpecGuard to write .github/workflows.

4. Write Specs Or Try The Example Package

After init, either replace the draft with your real feature spec or copy the packaged authored example into the same feature package:

specguard example copy your-feature-name --force

The example is for trying the full run pipeline before authoring your own production spec. It replaces the init draft with a complete sample package under specs/your-feature-name/.

5. Run And Iterate Until READY

specguard run specs/your-feature-name

run builds and validates the implementation basis:

Technical Design -> Initial SpecGuard Review -> Test -> Contract -> Implementation Handoff

run also prints per-feature performance timings and records SpecGuard Review input size so slow stages and oversized review contexts can be diagnosed without exposing artifact contents.

If SpecGuard returns NOT READY, use the continuation menu:

[1] View Readiness Findings
[2] Regenerate spec from Readiness Findings (auto-runs SpecGuard Review after)
[q] Exit

Repeat until SpecGuard reports READY or READY_WITH_WARNINGS. Critical findings always require revision before implementation.

Spec regeneration is guarded by an Intent Preservation Check. If the proposed spec.md appears to drop existing acceptance coverage, change the original problem intent, or move out-of-scope work into implementation scope, SpecGuard still updates the working spec.md for in-place review, writes the original spec and unified diff under .specguard/spec-revisions/, and stops before Verification Review.

For LLM-enabled strict automation:

specguard run specs/your-feature-name --strict-e2e --strict-max-iterations 3

Strict E2E runs Initial SpecGuard Review first, regenerates spec.md from blockers, runs the same Intent Preservation Check, reruns Verification Review, and stops only when READY or when the iteration limit is exhausted. It writes strict-e2e-trace.json for traceability.

6. Implement With An External AI Coding Agent

When READY, SpecGuard writes:

specs/your-feature-name/implementation-output.md

SpecGuard stops here. It does not invoke Codex, Claude Code, or another coding agent as an internal implementation stage.

Give the approved spec package and implementation-output.md to your external coding agent. The generated application code should live under develop/<stack>/, for example:

develop/spring/
develop/react/
develop/fastapi/

7. Open A Pull Request And Run SpecGuard PR Review

After implementation, open a PR in your GitHub repository with the completed code.

The optional SpecGuard PR Review workflow compares the approved spec package to the PR diff and posts one advisory PR comment headed SpecGuard PR Reviewer.

Install it explicitly when you want AI-assisted review comments:

specguard actions install-pr-review

After the command completes, commit and push the workflow file, then add this repository secret in GitHub repository settings:

SPECGUARD_OPENAI_API_KEY=sk-...

Add optional repository variables when you want to choose the review model or force the reviewer to use a specific spec package:

SPECGUARD_PR_REVIEW_MODEL=gpt-5.4-nano
SPECGUARD_REVIEW_SPEC_PATHS=specs/your-feature-name

SPECGUARD_OPENAI_API_KEY must be stored as a GitHub Actions secret, not committed to the repository. Use SPECGUARD_REVIEW_SPEC_PATHS when an implementation PR changes only develop/<stack>/ files and does not modify files under specs/.

The workflow is advisory by default. If credentials are unavailable, if the selected spec package is NOT READY, or if the readiness report is stale, the workflow skips or reports the blocker instead of invoking the reviewer.

Benchmark Summary

A controlled benchmark used Codex gpt-5.5 for code generation and SpecGuard's local no-LLM gate for weak-spec blocking.

With a complete and explicit spec, all workflows generated code that passed the hidden contract checks. With defective or incomplete specs, Spec Kit and OpenSpec still generated runnable Codex code, but every generated implementation exposed contract defects. SpecGuard blocked the same defective inputs before implementation using local deterministic and heuristic validation.

Workflow	Generated code from defective specs	Average exposed contract defect rate	Blocked before implementation
Spec Kit	6	77.2%	0/6
OpenSpec	6	63.6%	0/6
SpecGuard	0	0% exposed	6/6

Weak-Spec Before And After

Before SpecGuard, the benchmark passed the same six defective or incomplete specs into Spec Kit and OpenSpec prompts. Both workflows still produced runnable Codex gpt-5.5 implementations, and every weak-spec case exposed hidden contract defects.

After SpecGuard, the same weak specs were checked by the local no-LLM gate before implementation. SpecGuard marked all six packages NOT READY, produced no implementation handoff, and blocked the bad inputs before an AI coding agent could turn them into code.

Full methodology, case breakdown, version metadata, and limitations are available in the Spec-Driven Benchmark.

Core Value

AI coding works best when the implementation input is explicit. SpecGuard focuses on the parts that often fail before code is written:

• unclear requirements
• hidden assumptions
• missing authorization or ownership rules
• weak acceptance criteria
• undefined errors, retries, timeouts, and state transitions
• contracts that do not match the intended behavior

The user owns the spec. SpecGuard drafts, challenges, and validates the implementation basis around it.

Readiness Rules

SpecGuard uses three readiness states:

• READY: Critical=0, Major=0, Minor<=5.
• READY_WITH_WARNINGS: Critical=0, Major<=2, Minor<=10.
• NOT_READY: Critical>=1, Major>=3, or Minor>10.

Critical findings always block implementation. Major findings should represent an implementation-critical product, security, state, contract, persistence, or ownership decision. Best-practice suggestions, optional hardening, future extensibility, broad reliability improvements, and weakly evidenced risks should be Minor or omitted.

For API features, contracts/openapi.yaml must define at least one concrete path before SpecGuard can produce an implementation handoff. paths: {} is treated as a blocker, not a ready contract. Generated contracts include spec-derived success and error responses, request and response schemas, and x-specguard-coverage links back to acceptance criteria and error cases.

Strict E2E also requires executable verification before handoff. Add tests such as tests/test_*.py, or document an accepted tests/verification-contract.md with the command or artifact that a coding agent must preserve.

CI And PR Gates

Pull request CI includes a stable required-check candidate named SpecGuard Readiness Gate. It inspects changed packages under specs/, fails when a changed package is NOT_READY, and fails when source artifacts are stale relative to readiness-review.json.

specguard init <feature> installs .github/workflows/specguard-readiness-gate.yml by default. Use specguard init <feature> --no-actions to opt out, or specguard actions install-readiness-gate to install the workflow later.

Repositories that want merge-time enforcement should add SpecGuard Readiness Gate to branch protection or ruleset required status checks.

SpecGuard PR Review is separate from the readiness gate. It is a post-implementation advisory review that checks whether code appears aligned with the approved spec package.

CLI Reference

specguard init <spec-name>
specguard example copy <spec-name> --force
specguard actions install-pr-review
specguard run specs/<spec-name>
specguard auth status

Useful run options:

• --force: regenerate derived artifacts such as technical design.
• --follow-up: force the interactive continuation menu.
• --no-follow-up: exit immediately after the pipeline.
• --no-llm: use local deterministic checks and heuristic SpecGuard Review.
• --strict-e2e: use an LLM to automatically regenerate blocked specs and rerun Verification Review.
• --strict-max-iterations: bound the number of strict E2E verification iterations.

CI or scripted example:

specguard init billing-export --non-interactive --no-llm
specguard example copy billing-export --force
specguard run specs/billing-export --no-llm --no-follow-up

Development

For contributors or local source testing:

git clone https://github.com/KoreaNirsa/spec-guard.git
cd spec-guard
python -m pip install -e ".[test]"

Run tests:

python -m pytest

Use the packaged example when you want to exercise SpecGuard without authoring a new spec first:

specguard init sample-run --non-interactive --no-llm
specguard example copy sample-run --force
specguard run specs/sample-run --no-llm --no-follow-up

Documentation

• Workflow Guide
• Discovery Guide
• Spec-Driven Benchmark
• Contributing

License

Apache License 2.0