{"id":34881996,"url":"https://github.com/nold-ai/specfact-cli","last_synced_at":"2026-04-17T01:01:58.530Z","repository":{"id":322538985,"uuid":"1085706003","full_name":"nold-ai/specfact-cli","owner":"nold-ai","description":"The Swiss-knife CLI for validation and alignment in software delivery. Keep backlog intent, specs, tests, and code in sync across AI-assisted and brownfield delivery.","archived":false,"fork":false,"pushed_at":"2026-04-10T22:19:15.000Z","size":11001,"stargazers_count":15,"open_issues_count":77,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-10T22:23:39.587Z","etag":null,"topics":["ai","backlog-refinement","brownfield","code2spec","context-engineering","contract-enforcement","contract-first","contract-testing","contracts","copilot","kanban","legacy-modernization","python","requirements-engineering","scrum","sdd","spec-driven-development","spec-first","testing","value-driven"],"latest_commit_sha":null,"homepage":"http://docs.specfact.io/","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/nold-ai.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"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":"AGENTS.md","dco":null,"cla":"CLA.md"}},"created_at":"2025-10-29T12:04:16.000Z","updated_at":"2026-04-08T21:58:16.000Z","dependencies_parsed_at":"2026-02-04T01:01:49.381Z","dependency_job_id":null,"html_url":"https://github.com/nold-ai/specfact-cli","commit_stats":null,"previous_names":["nold-ai/specfact-cli"],"tags_count":75,"template":false,"template_full_name":null,"purl":"pkg:github/nold-ai/specfact-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nold-ai%2Fspecfact-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nold-ai%2Fspecfact-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nold-ai%2Fspecfact-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nold-ai%2Fspecfact-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nold-ai","download_url":"https://codeload.github.com/nold-ai/specfact-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nold-ai%2Fspecfact-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31910585,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-16T18:22:33.417Z","status":"ssl_error","status_checked_at":"2026-04-16T18:21:47.142Z","response_time":69,"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","backlog-refinement","brownfield","code2spec","context-engineering","contract-enforcement","contract-first","contract-testing","contracts","copilot","kanban","legacy-modernization","python","requirements-engineering","scrum","sdd","spec-driven-development","spec-first","testing","value-driven"],"created_at":"2025-12-26T02:18:31.684Z","updated_at":"2026-04-17T01:01:58.434Z","avatar_url":"https://github.com/nold-ai.png","language":"Python","readme":"# SpecFact CLI\n\n\u003e **SpecFact is the validation and alignment layer for software delivery.**\n\u003e It adds the missing validation layer that keeps backlog intent, specifications, tests, and code\n\u003e from drifting apart across AI-assisted coding, brownfield systems, and governed delivery.\n\u003e Use it to move fast without losing rigor.\n\n**No API keys required. Works offline. Zero vendor lock-in.**\n\nSpecFact CLI does **not** include built-in AI. It is a deterministic local CLI\nthat can be paired with IDE slash-command prompts so your chosen AI copilot can\ninvoke SpecFact as part of a command chain.\n\n[![PyPI version](https://img.shields.io/pypi/v/specfact-cli.svg?color=22c55e)](https://pypi.org/project/specfact-cli/)\n[![Python versions](https://img.shields.io/pypi/pyversions/specfact-cli.svg)](https://pypi.org/project/specfact-cli/)\n[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)\n[![Status](https://img.shields.io/badge/status-beta-F59E0B.svg)](https://github.com/nold-ai/specfact-cli)\n\n\u003cdiv align=\"center\"\u003e\n\n**[specfact.com](https://specfact.com)** • **[specfact.io](https://specfact.io)** • **[specfact.dev](https://specfact.dev)** • **[Documentation](https://docs.specfact.io/)** • **[Support](mailto:hello@noldai.com)**\n\n\u003c/div\u003e\n\n---\n\n## What is SpecFact?\n\nSpecFact is the validation and alignment layer for software delivery.\n\nIt is a local CLI that helps you keep the intent behind a change aligned from\nbacklog or idea through specifications, implementation, and checks. The “Swiss-knife CLI” metaphor\nfits because SpecFact gives you a set of focused tools for specific delivery problems, not a vague\nbag of features.\n\nIn practice, SpecFact helps you:\n- add guardrails to AI-assisted and fast-moving greenfield work\n- reverse-engineer large brownfield codebases into trustworthy structured understanding\n- reduce the “I wanted X but got Y” drift between backlog, spec, and implementation\n- move from local rigor toward team and enterprise policy enforcement\n\n## Why does it exist?\n\nModern delivery drifts in predictable ways:\n- AI-generated quick wins often lack the validation layer needed for mid- and long-term reliability\n- brownfield systems often have missing or drifted specs, so teams need to reverse-engineer reality\n- backlog intent gets reinterpreted into something else before it reaches code\n- teams working with different skill levels, opinions, and AI IDE setups need consistent review and\n  policy enforcement\n\nSpecFact exists to reduce that drift. It helps teams understand what is really there, express what\nshould happen more accurately, and validate that the result still matches the original intent.\n\n## Why should I use it?\n\nUse SpecFact if you want one of these outcomes:\n- ship AI-assisted changes faster without accepting fragile “looks fine to me” quality\n- understand a legacy or unfamiliar codebase before changing it\n- hand brownfield insight into OpenSpec, Spec-Kit, or other spec-first workflows\n- keep backlog expectations, specifications, and implementation from silently diverging\n- enforce shared rules consistently across developers and CI/CD\n\n## What do I get?\n\nWith SpecFact, you get:\n- a deterministic local CLI instead of another opaque SaaS dependency\n- a validation layer around fast-moving implementation work\n- codebase analysis and sidecar flows for brownfield understanding\n- stronger backlog/spec/code alignment for real delivery workflows\n- a path from individual rigor to organization-level policy enforcement\n\n## How do I get started?\n\n### Start Here (about 2 minutes): scored code review — no `pip install`\n\n**Point SpecFact at your code.** From a **git repository** (any branch), run two commands:\n\n```bash\nuvx specfact-cli init --profile solo-developer\nuvx specfact-cli code review run --path . --scope full\n```\n\nYou should see a **Verdict** (PASS/FAIL), a **Score**, and categorized **findings** — the fastest way to see SpecFact on real code before you dive into backlog, specs, or CI.\n\n- **Command 1** installs the `solo-developer` bundles (including `specfact-codebase` and `specfact-code-review`) into your user module store so `code review` and related commands are available on the next invocation.\n- **Command 2** runs the clean-code review on the repo at `.`. Use **`--scope full`** on the first run so review does not depend on having local git changes.\n\n**Already installed the CLI?** Use the same flow with `specfact` instead of `uvx specfact-cli`:\n\n```bash\nspecfact init --profile solo-developer\nspecfact code review run --path . --scope full\n```\n\n**Read the canonical walkthrough:** **[Documentation — Quickstart](https://docs.specfact.io/getting-started/quickstart/)** · **[Installation](https://docs.specfact.io/getting-started/installation/)** (uvx-first, then persistent install).\n\n### Install (persistent CLI for daily use)\n\n```bash\npip install -U specfact-cli\n```\n\nYou can still use **`uvx specfact-cli@latest ...`** anytime without installing; it always fetches the latest published CLI.\n\n### After the wow path: deeper workflows\n\nWhen you want analysis, snapshots, or sidecar validation on top of the review layer:\n\n```bash\n# Analyze a codebase you care about\nspecfact code import my-project --repo .\n\n# Snapshot the project state for follow-up workflows\nspecfact project snapshot --bundle my-project\n\n# Validate external code without modifying the target repo\nspecfact code validate sidecar init my-project /path/to/repo\nspecfact code validate sidecar run my-project /path/to/repo\n```\n\n### AI IDE setup\n\n```bash\nspecfact init ide\nspecfact init ide --ide cursor\nspecfact init ide --ide vscode\n```\n\n`specfact init ide` discovers prompt resources from installed workflow modules and exports them to\nyour IDE. If module prompt payloads are not installed yet, the CLI uses packaged fallback resources.\n\n## Choose Your Path\n\n### Greenfield and AI-assisted delivery\n\nUse SpecFact as the validation layer around fast-moving implementation work.\n\nStart with:\n- `uvx specfact-cli init --profile solo-developer` then `uvx specfact-cli code review run --path . --scope full` (see **Start Here** above)\n- `specfact code validate sidecar init \u003cbundle\u003e /path/to/repo`\n- `specfact code validate sidecar run \u003cbundle\u003e /path/to/repo`\n\n### Brownfield and reverse engineering\n\nUse SpecFact to understand an existing system before you change it, then hand that understanding\ninto spec-first tools such as OpenSpec or Spec-Kit.\n\nStart with:\n- `specfact code import my-project --repo .`\n- `specfact project snapshot --bundle my-project`\n- `specfact code validate sidecar init my-project /path/to/repo`\n- `specfact code validate sidecar run my-project /path/to/repo`\n\n### Backlog to code alignment\n\nUse SpecFact when the problem is not only code quality, but drift between expectations and delivery.\nBacklog commands require a backlog-enabled profile or installed backlog bundle before the workflow\ncommands are available.\n\nStart with:\n- `specfact init --profile backlog-team`\n- `specfact backlog ceremony standup ...`\n- `specfact backlog ceremony refinement ...`\n- `specfact backlog verify-readiness --bundle \u003cbundle-name\u003e`\n\n### Team and policy enforcement\n\nUse SpecFact when multiple developers and AI IDEs need consistent checks and review behavior.\n\nStart with:\n- `specfact backlog verify-readiness --bundle \u003cbundle-name\u003e`\n- `specfact govern ...`\n- CI validation flows that keep the same rules active outside local development\n\n## How do I get started if I want more?\n\n**Next steps**\n\n- **[Core CLI docs](docs/index.md)** for the core runtime, bootstrap, validation, and command topology\n- **[Reference: command topology](docs/reference/commands.md)** for grouped command surfaces\n- **[Canonical modules docs site](https://modules.specfact.io/)** for bundle-deep workflows\n\n## Documentation Topology\n\n`docs.specfact.io` is the canonical starting point for SpecFact.\n\n- Core CLI/runtime/platform documentation remains owned by `specfact-cli`.\n- Module-specific deep docs are canonically owned by `specfact-cli-modules`.\n- The live modules docs site is published at `https://modules.specfact.io/`.\n\nUse this repository's docs for the overall product story, runtime lifecycle, command topology,\ntrust model, and getting-started flow. Use the modules docs site when you want deeper workflow,\nadapter, and module-authoring guidance.\n\n### Migration Note (Flat Commands Removed)\n\nAs of `0.40.0`, flat root commands are removed. Use grouped commands:\n\n- `specfact validate ...` -\u003e `specfact code validate ...`\n- `specfact plan ...` -\u003e removed; use `specfact project devops-flow` or `specfact project snapshot`\n- `specfact policy ...` -\u003e removed; use `specfact backlog verify-readiness`\n\n### Backlog Bridge (60 seconds)\n\nSpecFact's USP is closing the drift gap between **backlog -\u003e specs -\u003e code**.\nThese commands require the backlog bundle to be installed first, for example via\n`specfact init --profile backlog-team` or `specfact init --install backlog`.\n\n```bash\n# 1) Initialize backlog config + field mapping\nspecfact backlog init-config --force\nspecfact backlog map-fields --provider ado --ado-org \u003corg\u003e --ado-project \"\u003cproject\u003e\"\n\n# 2) Run ceremony workflows on real backlog scope\nspecfact backlog ceremony standup ado --ado-org \u003corg\u003e --ado-project \"\u003cproject\u003e\" --state any --assignee any --limit 5\nspecfact backlog ceremony refinement ado --ado-org \u003corg\u003e --ado-project \"\u003cproject\u003e\" --id \u003cwork-item-id\u003e --preview\n\n# 3) Keep backlog + spec intent aligned (avoid silent drift)\nspecfact backlog verify-readiness --bundle \u003cbundle-name\u003e\n```\n\nCompatibility note: `specfact backlog daily ...` and `specfact backlog refine ...` still exist, but the preferred entrypoints are `backlog ceremony standup` and `backlog ceremony refinement`.\n\nFor GitHub, replace adapter/org/project with:\n`specfact backlog ceremony standup github --repo-owner \u003cowner\u003e --repo-name \u003crepo\u003e --state any --assignee any --limit 5`\n\n**AI IDE quick start**\n\n```bash\n# In your IDE chat (Cursor, VS Code, Copilot, etc.)\n/specfact.01-import my-project --repo .\n```\n\n---\n\n## Who It Is For\n\n- **Vibe coders and new builders** who want to ship fast with guardrails and confidence.\n- **Legacy professionals** who want AI speed without lowering standards.\n- **DevOps and engineering leaders** who need evidence and repeatable workflows.\n\n---\n\n## The Missing Link (Coder + DevOps Bridge)\n\nMost tools help **either** coders **or** agile teams. SpecFact does both:\n\n- **Backlog sync that is actually strong**: round-trip sync + refinement with GitHub, Azure DevOps, Jira, Linear.\n- **Ceremony support teams can run**: standup, refinement, sprint planning, flow metrics (Scrum/Kanban/SAFe).\n- **Policy + validation**: DoR/DoD/flow checks plus contract enforcement for production-grade stability.\n\nRecommended command entrypoints:\n- `specfact backlog ceremony standup ...`\n- `specfact backlog ceremony refinement ...`\n- `specfact backlog verify-readiness --bundle \u003cbundle-name\u003e`\n- `specfact backlog analyze-deps --bundle \u003cbundle-name\u003e`\n\nWhat the backlog readiness and ceremony commands do in practice:\n- Turns team agreements (DoR, DoD, flow checks) into executable checks against your real backlog data.\n- Shows exactly what is missing per item (for example missing acceptance criteria or definition of done).\n- Runs structured ceremony workflows directly from the CLI.\n\nStart with:\n- `specfact backlog ceremony standup --help`\n- `specfact backlog verify-readiness --bundle \u003cbundle-name\u003e`\n- `specfact backlog refine --help`\n\n---\n\n## Core CLI Features\n\nThe `specfact-cli` repository owns the platform-level features that every workflow bundle depends on:\n\n- `specfact init` for first-run bootstrap and IDE setup.\n- `specfact module` for install/list/show/search/enable/disable/uninstall/upgrade lifecycle flows.\n- `specfact upgrade` for CLI upgrades.\n- Runtime contracts, registry bootstrapping, trust checks, logging, and shared orchestration.\n- The grouped command surface that mounts installed bundle families under `project`, `backlog`, `code`, `spec`, and `govern`.\n\n## Official Modules Integration\n\nOfficial workflow behavior now ships from `nold-ai/specfact-cli-modules`.\nThe core CLI discovers those bundle packages, mounts their command groups, and enforces compatibility, trust, and lifecycle rules.\n\nInstalled official bundles expose the current grouped surfaces:\n\n- `specfact project ...`\n- `specfact backlog ...`\n- `specfact code ...`\n- `specfact spec ...`\n- `specfact govern ...`\n\nInstall examples:\n\n```bash\nspecfact module install nold-ai/specfact-project\nspecfact module install nold-ai/specfact-backlog\nspecfact module install nold-ai/specfact-codebase\nspecfact module install nold-ai/specfact-spec\nspecfact module install nold-ai/specfact-govern\n```\n\nIf startup warns that bundled modules are missing or outdated, run:\n\n```bash\nspecfact module init --scope project\nspecfact module init\n```\n\nUse this repo's docs for the current CLI/runtime release branch and the overall process of how official modules plug into the core platform.\nUse `https://modules.specfact.io/` for the in-depth backlog, project, spec, govern, adapter, and module-authoring guides.\n\n---\n\n## How It Works (High Level)\n\n1. **Bootstrap**: use **uvx** or **pip**, then `init --profile` to install the bundles you need (for example `solo-developer` for a scored **code review** first).\n2. **Review or analyze**: run **`code review run`** on a repo, or import code and snapshot state for deeper workflows.\n3. **Sync**: connect backlog systems or sync external artifacts into project bundles when you are ready.\n4. **Validate**: run spec, governance, and sidecar validation flows before implementation or release.\n5. **Iterate safely**: use module-provided workflows while the core runtime keeps command mounting, trust, and lifecycle consistent.\n\n## Where SpecFact Fits\n\nSpecFact complements your stack rather than replacing it.\n\n- **Spec-Kit/OpenSpec** for authoring and change tracking\n- **Backlog tools** for planning and delivery\n- **CI/CD** for enforcement and regression prevention\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnold-ai%2Fspecfact-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnold-ai%2Fspecfact-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnold-ai%2Fspecfact-cli/lists"}