{"id":51107591,"url":"https://github.com/agent-quality-controls/specular","last_synced_at":"2026-06-24T15:01:30.007Z","repository":{"id":358043781,"uuid":"1239666832","full_name":"agent-quality-controls/specular","owner":"agent-quality-controls","description":"Deterministic spec-driven development CLI","archived":false,"fork":false,"pushed_at":"2026-06-11T17:12:34.000Z","size":258,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-11T19:07:37.285Z","etag":null,"topics":["agent-quality","cli","json","rust","spec-driven-development","static-analysis","verification"],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/agent-quality-controls.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","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-15T10:14:16.000Z","updated_at":"2026-06-11T17:12:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/agent-quality-controls/specular","commit_stats":null,"previous_names":["agent-quality-controls/spec3","agent-quality-controls/specular"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/agent-quality-controls/specular","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agent-quality-controls%2Fspecular","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agent-quality-controls%2Fspecular/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agent-quality-controls%2Fspecular/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agent-quality-controls%2Fspecular/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/agent-quality-controls","download_url":"https://codeload.github.com/agent-quality-controls/specular/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agent-quality-controls%2Fspecular/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34737398,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-24T02:00:07.484Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["agent-quality","cli","json","rust","spec-driven-development","static-analysis","verification"],"created_at":"2026-06-24T15:01:28.620Z","updated_at":"2026-06-24T15:01:29.989Z","avatar_url":"https://github.com/agent-quality-controls.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Specular\n\n[![ci](https://img.shields.io/github/actions/workflow/status/agent-quality-controls/specular/ci.yml?branch=main\u0026label=ci)](https://github.com/agent-quality-controls/specular/actions/workflows/ci.yml)\n[![codeql](https://img.shields.io/github/actions/workflow/status/agent-quality-controls/specular/codeql.yml?branch=main\u0026label=codeql)](https://github.com/agent-quality-controls/specular/actions/workflows/codeql.yml)\n[![license](https://img.shields.io/github/license/agent-quality-controls/specular)](LICENSE)\n[![rust](https://img.shields.io/badge/rust-1.85%2B-orange)](Cargo.toml)\n\nSpecular is a CLI for enforcing spec-driven development.\n\nIt turns a plan into JSON checks.\n\nUse it when an agent builds code from a plan and \"done\" is too weak.\n\nUse it for code, docs, deps, and checks.\n\nIt is strict. It prints JSON. It fails when work drifts from the spec.\n\nInstall with\n```bash\ncargo install --git https://github.com/agent-quality-controls/specular\n```\n\nTell your agent to use Specular. It should write the spec, add any scripts, and\nwork until verify exits `0`.\n\nTell it to use the least custom spec that works. It should use a predefined\ncategory when one fits, use that category's builtin when one exists, and use\ncustom only when no predefined category fits.\n\n## What it is\n\nSpecular uses JSON specs to check a plan. It gives an agent a test loop. The\nagent reads the plan, writes the spec, runs it, fixes the repo, and runs it\nagain.\n\nExit codes:\n\n- `0`: the spec is valid, or the repo matches it.\n- `1`: the repo does not match it.\n- `2`: the spec, verifier, call shape, timeout, or run failed.\n\nAgents can read the JSON result. Status is a pass or fail.\n\n## Why use it\n\nAn agent can say the plan is done. Specular makes it prove the work.\n\nUse this loop:\n\n1. Turn the plan into a typed JSON spec.\n2. Run the spec before coding.\n3. Confirm it fails where work is still missing.\n4. Build the code.\n5. Run `specular verify` until it exits `0`.\n\nUse it for plans with clear parts: files, text, exports, deps, named cases, or\nscript checks.\n\n## Tell your agent\n\nUse this prompt:\n\n```text\nUse Specular for this plan.\nMake a JSON spec.\nRun specular lint.\nWrite a coverage map.\nUse predefined categories first.\nUse built-in verifiers when they exist.\nAdd verifier scripts only when no built-in fits.\nUse custom only when no predefined category fits.\nRun specular verify before coding.\nKeep working until specular verify exits 0.\nUse specular --help for the spec shape and script calls.\n```\n\n## Spec patterns\n\nThere are three patterns:\n\n1. Predefined categories with built-ins: `tree`, `content`, Cargo\n   `dependencies`, and Rust `enumerations`. Use these first.\n2. Predefined categories with no built-in for your stack: `dependencies`,\n   `exports`, `enumerations`. Use one script per block.\n3. Custom categories: put any JSON under `custom`, then write the script. Use\n   this only when no predefined category fits.\n\nEvery non-empty block has one block-level verifier command. Built-ins are\nexplicit:\n\n```json\n{\n  \"version\": 4,\n  \"requirements\": {\n    \"tree\": {\n      \"verifier\": [\"builtin:tree\"],\n      \"required\": [\"src/lib.rs\"]\n    },\n    \"content\": [\n      {\n        \"verifier\": [\"builtin:content\"],\n        \"files\": [\"README.md\"],\n        \"required\": [\"Specular is a CLI\"]\n      }\n    ],\n    \"dependencies\": [\n      {\n        \"verifier\": [\"builtin:cargo-dependencies\"],\n        \"files\": [\"Cargo.toml\"],\n        \"required\": [\"serde\"],\n        \"forbidden\": [\"openssl\"],\n        \"forbiddenGlobs\": [\"g3*\"]\n      }\n    ],\n    \"enumerations\": [\n      {\n        \"verifier\": [\"builtin:rust-enumerations\"],\n        \"files\": [\"src/**/*.rs\"],\n        \"name\": \"Category\",\n        \"values\": [\"Tree\", \"Content\", \"Dependencies\"]\n      }\n    ]\n  }\n}\n```\n\nPredefined categories have fixed fields. Custom entries can hold any JSON except\n`verifier`, which Specular owns.\n\nDo not put tree, content, Cargo package, or Rust enum checks in `custom`. Do\nnot write a script for checks the built-ins can judge.\n\nFor `builtin:cargo-dependencies`, `required`, `exists`, and `forbidden` use\nexact Cargo package names. `forbiddenGlobs` uses package-name globs. Renamed\ndeps use Cargo package identity, so `serde_json = { package = \"serde-json\",\nversion = \"...\" }` is checked by `serde-json`.\n\nFor `builtin:rust-enumerations`, `files` selects Rust files, `name` is an enum\nname or an inline-module-qualified name such as `wire::Status`, and `values` is\nthe exact variant set.\n\nRun `specular --help` before writing a spec. It has full examples and script\ncall rules.\n\n## Verifier scripts\n\nA verifier is one command. It is encoded as argv, not as a shell string or a\nlist of verifiers. Scripts can use any language; examples use Python.\n\n```json\n\"verifier\": [\"python3\", \"scripts/verify_deps.py\", \"--workspace\"]\n```\n\nTyped script blocks are called once per block:\n\n```text\n\u003ccommand...\u003e \u003cspec.json\u003e \u003ccategory\u003e \u003cblockIndex\u003e\n```\n\nCustom scripts are called once per entry:\n\n```text\n\u003ccommand...\u003e \u003cspec.json\u003e custom \u003cblockIndex\u003e\n```\n\nVerifier scripts print JSON proof lines. Their exit code says whether the script\nran cleanly. The proof carries pass and fail.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagent-quality-controls%2Fspecular","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fagent-quality-controls%2Fspecular","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagent-quality-controls%2Fspecular/lists"}