{"id":49680184,"url":"https://github.com/koreanirsa/spec-guard","last_synced_at":"2026-05-07T06:01:53.092Z","repository":{"id":355604174,"uuid":"1228410867","full_name":"KoreaNirsa/spec-guard","owner":"KoreaNirsa","description":"Spec-driven guardrails for AI-assisted development.","archived":false,"fork":false,"pushed_at":"2026-05-04T12:33:09.000Z","size":5848,"stargazers_count":1,"open_issues_count":7,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-04T13:34:36.862Z","etag":null,"topics":["ai-assisted-development","cli","codex","developer-tools","llm","openapi","python","requirements-engineering","spec-driven-development","validation"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/KoreaNirsa.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-04T01:40:03.000Z","updated_at":"2026-05-04T12:19:44.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/KoreaNirsa/spec-guard","commit_stats":null,"previous_names":["koreanirsa/spec-guard"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/KoreaNirsa/spec-guard","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KoreaNirsa%2Fspec-guard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KoreaNirsa%2Fspec-guard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KoreaNirsa%2Fspec-guard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KoreaNirsa%2Fspec-guard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KoreaNirsa","download_url":"https://codeload.github.com/KoreaNirsa/spec-guard/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KoreaNirsa%2Fspec-guard/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32725216,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-07T02:14:30.463Z","status":"ssl_error","status_checked_at":"2026-05-07T02:14:29.405Z","response_time":62,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-assisted-development","cli","codex","developer-tools","llm","openapi","python","requirements-engineering","spec-driven-development","validation"],"created_at":"2026-05-07T06:01:14.876Z","updated_at":"2026-05-07T06:01:53.083Z","avatar_url":"https://github.com/KoreaNirsa.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"![SpecGuard banner](assets/spec_guard_banner.png)\n\n# SpecGuard\n\n**SpecGuard blocks weak specs before AI coding agents turn them into defective code.**\n\nSpecGuard is a Validation-First Workflow (VFW) for AI-assisted development.\nIt turns specs into reviewed, testable, implementation-ready packages before AI coding begins.\n\nIt 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.\n\n```text\nDiscovery -\u003e Spec Package -\u003e Technical Design -\u003e SpecGuard Review\n-\u003e Test -\u003e Contract -\u003e Implementation Handoff\n-\u003e External AI Implementation -\u003e Pull Request -\u003e SpecGuard PR Review\n```\n\n## Core Reviews\n\nSpecGuard centers on two review steps:\n\n- 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.\n- 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.\n\n## Current Support Status\n\nCurrently, 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.\n\n## Setup To User Flow\n\nThis is the shortest path from installation to a reviewed implementation PR.\n\n### 1. Install\n\nSpecGuard expects Python 3.11 or newer.\n\n```bash\npip install spec-guard\nspecguard --help\n```\n\n### 2. Configure Codex\n\nThen configure SpecGuard to use local Codex:\n\n```bash\nspecguard auth setup --mode codex --model gpt-5.4\nspecguard auth status\n```\n\nCodex 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.\n\nIf Codex is already logged in and you do not want setup to offer `codex login`:\n\n```bash\nspecguard auth setup --mode codex --model gpt-5.4 --skip-login\n```\n\n\n### 3. Create A Feature Spec\n\n```bash\nspecguard init your-feature-name\n```\n\nSpecGuard writes draft artifacts and the default readiness workflow:\n\n```text\nspecs/your-feature-name/\n|-- discovery.md\n|-- spec.md\n|-- plan.md\n|-- tasks.md\n|-- constitution.md\n`-- checklists/spec-readiness.md\n.github/\n`-- workflows/specguard-readiness-gate.yml\n```\n\nFor 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.\n\n`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`.\n\n### 4. Write Specs Or Try The Example Package\n\nAfter `init`, either replace the draft with your real feature spec or copy the packaged authored example into the same feature package:\n\n```bash\nspecguard example copy your-feature-name --force\n```\n\nThe 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/`.\n\n### 5. Run And Iterate Until READY\n\n```bash\nspecguard run specs/your-feature-name\n```\n\n`run` builds and validates the implementation basis:\n\n```text\nTechnical Design -\u003e Initial SpecGuard Review -\u003e Test -\u003e Contract -\u003e Implementation Handoff\n```\n\n`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.\n\nIf SpecGuard returns NOT READY, use the continuation menu:\n\n```text\n[1] View Readiness Findings\n[2] Regenerate spec from Readiness Findings (auto-runs SpecGuard Review after)\n[q] Exit\n```\n\nRepeat until SpecGuard reports READY or READY_WITH_WARNINGS. Critical findings always require revision before implementation.\n\nSpec 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.\n\nFor LLM-enabled strict automation:\n\n```bash\nspecguard run specs/your-feature-name --strict-e2e --strict-max-iterations 3\n```\n\nStrict 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.\n\n### 6. Implement With An External AI Coding Agent\n\nWhen READY, SpecGuard writes:\n\n```text\nspecs/your-feature-name/implementation-output.md\n```\n\nSpecGuard stops here. It does not invoke Codex, Claude Code, or another coding agent as an internal implementation stage.\n\nGive the approved spec package and `implementation-output.md` to your external coding agent. The generated application code should live under `develop/\u003cstack\u003e/`, for example:\n\n```text\ndevelop/spring/\ndevelop/react/\ndevelop/fastapi/\n```\n\n### 7. Open A Pull Request And Run SpecGuard PR Review\n\nAfter implementation, open a PR in your GitHub repository with the completed code.\n\nThe optional `SpecGuard PR Review` workflow compares the approved spec package to the PR diff and posts one advisory PR comment headed `SpecGuard PR Reviewer`.\n\nInstall it explicitly when you want AI-assisted review comments:\n\n```bash\nspecguard actions install-pr-review\n```\n\nAfter the command completes, commit and push the workflow file, then add this repository secret in GitHub repository settings:\n\n```text\nSPECGUARD_OPENAI_API_KEY=sk-...\n```\n\nAdd optional repository variables when you want to choose the review model or force the reviewer to use a specific spec package:\n\n```text\nSPECGUARD_PR_REVIEW_MODEL=gpt-5.4-nano\nSPECGUARD_REVIEW_SPEC_PATHS=specs/your-feature-name\n```\n\n`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/\u003cstack\u003e/` files and does not modify files under `specs/`.\n\nThe 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.\n\n## Benchmark Summary\n\nA controlled benchmark used Codex `gpt-5.5` for code generation and SpecGuard's local no-LLM gate for weak-spec blocking.\n\nWith 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.\n\n| Workflow | Generated code from defective specs | Average exposed contract defect rate | Blocked before implementation |\n| --- | ---: | ---: | ---: |\n| Spec Kit | 6 | 77.2% | 0/6 |\n| OpenSpec | 6 | 63.6% | 0/6 |\n| SpecGuard | 0 | 0% exposed | 6/6 |\n\n### Weak-Spec Before And After\n\nBefore 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.\n\nAfter 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.\n\nFull methodology, case breakdown, version metadata, and limitations are available in the [Spec-Driven Benchmark](docs/spec-driven-benchmark.md).\n\n## Core Value\n\nAI coding works best when the implementation input is explicit. SpecGuard focuses on the parts that often fail before code is written:\n\n- unclear requirements\n- hidden assumptions\n- missing authorization or ownership rules\n- weak acceptance criteria\n- undefined errors, retries, timeouts, and state transitions\n- contracts that do not match the intended behavior\n\nThe user owns the spec. SpecGuard drafts, challenges, and validates the implementation basis around it.\n\n## Readiness Rules\n\nSpecGuard uses three readiness states:\n\n- READY: Critical=0, Major=0, Minor\u003c=5.\n- READY_WITH_WARNINGS: Critical=0, Major\u003c=2, Minor\u003c=10.\n- NOT_READY: Critical\u003e=1, Major\u003e=3, or Minor\u003e10.\n\nCritical 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.\n\nFor 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.\n\nStrict 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.\n\n## CI And PR Gates\n\nPull 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`.\n\n`specguard init \u003cfeature\u003e` installs `.github/workflows/specguard-readiness-gate.yml` by default. Use `specguard init \u003cfeature\u003e --no-actions` to opt out, or `specguard actions install-readiness-gate` to install the workflow later.\n\nRepositories that want merge-time enforcement should add `SpecGuard Readiness Gate` to branch protection or ruleset required status checks.\n\n`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.\n\n## CLI Reference\n\n```bash\nspecguard init \u003cspec-name\u003e\nspecguard example copy \u003cspec-name\u003e --force\nspecguard actions install-pr-review\nspecguard run specs/\u003cspec-name\u003e\nspecguard auth status\n```\n\nUseful `run` options:\n\n- `--force`: regenerate derived artifacts such as technical design.\n- `--follow-up`: force the interactive continuation menu.\n- `--no-follow-up`: exit immediately after the pipeline.\n- `--no-llm`: use local deterministic checks and heuristic SpecGuard Review.\n- `--strict-e2e`: use an LLM to automatically regenerate blocked specs and rerun Verification Review.\n- `--strict-max-iterations`: bound the number of strict E2E verification iterations.\n\nCI or scripted example:\n\n```bash\nspecguard init billing-export --non-interactive --no-llm\nspecguard example copy billing-export --force\nspecguard run specs/billing-export --no-llm --no-follow-up\n```\n\n## Development\n\nFor contributors or local source testing:\n\n```bash\ngit clone https://github.com/KoreaNirsa/spec-guard.git\ncd spec-guard\npython -m pip install -e \".[test]\"\n```\n\nRun tests:\n\n```bash\npython -m pytest\n```\n\nUse the packaged example when you want to exercise SpecGuard without authoring a new spec first:\n\n```bash\nspecguard init sample-run --non-interactive --no-llm\nspecguard example copy sample-run --force\nspecguard run specs/sample-run --no-llm --no-follow-up\n```\n\n## Documentation\n\n- [Workflow Guide](docs/workflow.md)\n- [Discovery Guide](docs/deep-discovery.md)\n- [Spec-Driven Benchmark](docs/spec-driven-benchmark.md)\n- [Contributing](CONTRIBUTING.md)\n\n## License\n\nApache License 2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkoreanirsa%2Fspec-guard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkoreanirsa%2Fspec-guard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkoreanirsa%2Fspec-guard/lists"}