https://github.com/nold-ai/specfact-cli
AI-bloat defense CLI for Python teams: deterministic code review, cleanup forecasts, and spec/contract evidence for AI-assisted and brownfield delivery.
https://github.com/nold-ai/specfact-cli
ai ai-assisted-development ai-bloat brownfield clean-code code-quality code-review code2spec contract-first contract-testing developer-tools legacy-modernization python requirements-engineering spec-driven-development spec-first static-analysis technical-debt testing vibe-coding
Last synced: 20 days ago
JSON representation
AI-bloat defense CLI for Python teams: deterministic code review, cleanup forecasts, and spec/contract evidence for AI-assisted and brownfield delivery.
- Host: GitHub
- URL: https://github.com/nold-ai/specfact-cli
- Owner: nold-ai
- License: apache-2.0
- Created: 2025-10-29T12:04:16.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2026-06-09T23:03:48.000Z (25 days ago)
- Last Synced: 2026-06-09T23:11:48.212Z (25 days ago)
- Topics: ai, ai-assisted-development, ai-bloat, brownfield, clean-code, code-quality, code-review, code2spec, contract-first, contract-testing, developer-tools, legacy-modernization, python, requirements-engineering, spec-driven-development, spec-first, static-analysis, technical-debt, testing, vibe-coding
- Language: Python
- Homepage: https://docs.specfact.io/
- Size: 11.4 MB
- Stars: 17
- Watchers: 0
- Forks: 1
- Open Issues: 44
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
- Agents: AGENTS.md
- Cla: CLA.md
Awesome Lists containing this project
README
# SpecFact CLI
> Defend AI-assisted Python code from bloat before it reaches PR.
> Run deterministic review, cleanup forecasts, and spec/contract evidence locally.
[](https://pypi.org/project/specfact-cli/)
[](https://pypi.org/project/specfact-cli/)
[](LICENSE)
[](https://github.com/nold-ai/specfact-cli)
**No API keys required. Works offline. Zero vendor lock-in.**
**[Documentation](https://docs.specfact.io/)** • **[Modules](https://modules.specfact.io/)** • **[Support](mailto:hello@noldai.com)**
## Command Overview
- [Generated command overview for humans](docs/reference/commands.generated.md)
- [AI-agent command overview](llms.txt)
## Try it in 60 seconds
```bash
# Zero-install, no API key, works offline
uvx specfact-cli init --profile solo-developer
uvx specfact-cli code review run --path . --scope full
```
**Sample output:**
```text
SpecFact CLI - v0.47.4
Running Ruff checks...
Running Radon complexity checks...
Running Semgrep rules...
Running AST clean-code checks...
Running basedpyright type checks...
Running pylint checks...
Running contract checks...
Running targeted tests and coverage...
Verdict: FAIL | CI exit: 1 | Score: 0 | Reward delta: -80
Findings:
- specfact_demo/enforcement.py:96 Cyclomatic complexity for run_enforcement is 16.
- specfact_demo/main.py:81 Avoid print() in source files; use structured logging instead.
- examples/buggy_math.py:4 Public function divide is missing @require/@ensure decorators.
Evidence bundle: docs/_support/readme-first-contact/sample-output/
```
⭐ **Star this repo if the output is useful.** Open an issue if you want the workflow adapted for your stack.
**Already installed the CLI?** Use:
```bash
specfact init --profile solo-developer
specfact code review run --path . --scope full
```
The sample output comes from a pinned capture against `nold-ai/specfact-demo-repo`. Reproduce it with `docs/_support/readme-first-contact/capture-readme-output.sh`; capture metadata lives alongside the raw logs in `docs/_support/readme-first-contact/sample-output/`.
## AI-bloat defense loop
SpecFact is the local AI-bloat defense CLI for Python-first teams using AI IDEs. The Code Review bundle reports `ai_bloat` advisories for code shapes that AI-assisted coding often amplifies: redundant wrappers, passthrough lambdas, identity `try`/`except` blocks, avoidable intermediate lists, and long low-branch functions.
For cleanup work, run a JSON review, inspect the cleanup forecast and AI-bloat index, hand remediation packets to your AI IDE, accept only safe changes, then re-run review for proof. The JSON report is the portable handoff artifact for Claude, Codex, Cursor, Copilot, or a headless agent.
These findings are bloat-shape detection and cleanup guidance, not AI-authorship detection. Exact simplify flags and report fields live in the [AI bloat quickstart](https://modules.specfact.io/quickstart-ai-bloat/) and [Code Review run guide](https://modules.specfact.io/bundles/code-review/run/) on the modules docs site.
## What SpecFact does
- **Defends against AI bloat deterministically** — forecast cleanup impact and route remediation packets to your AI IDE
- **Reviews AI-assisted changes against evidence** — compare code against contracts, clean-code rules, and policy gates
- **Extracts structure from existing code** — reverse-engineer brownfield repos before you change them
- **Blocks drift before merge** — use the same checks locally, in pre-commit, and in CI
- **Consumes upstream planning inputs** — treat Spec Kit, OpenSpec, backlog, specs, tests, and contracts as validation evidence
- **Stays local-first** — no cloud account, no vendor lock-in, no built-in model dependency
## What is SpecFact?
SpecFact is a local CLI for AI-bloat defense, deterministic code review, and backlog/spec/code drift control. It gives solo developers, legacy maintainers, and teams a validation layer around AI-assisted delivery, brownfield reverse engineering, and contract-first reviews.
It exists because delivery drifts in predictable ways:
- AI-assisted code lands faster than cleanup and validation catch up
- brownfield systems rarely have trustworthy up-to-date specs
- backlog intent gets reinterpreted before it reaches code
- teams need the same review rules across IDEs, CI, and pull requests
## Add SpecFact to your workflow
### Pre-commit hook
This repository uses a **modular** local hook layout (parity with `specfact-cli-modules`: `fail_fast`,
separate verify / format / YAML / Markdown / workflow / lint / Block 2 hooks). If you copy
[`.pre-commit-config.yaml`](.pre-commit-config.yaml) into another repo, you must also vendor the
referenced `scripts/*.sh` entrypoints (at minimum `scripts/pre-commit-quality-checks.sh`,
`scripts/pre-commit-verify-modules.sh`, `scripts/module-verify-policy.sh`, and
`scripts/git-branch-module-signature-flag.sh`) so hook
`entry:` paths resolve. Alternatively, skip vendoring the modular file and use the remote hook below.
For a **single-hook** setup in downstream repos, keep using the stable id and script shim:
```yaml
- repo: https://github.com/nold-ai/specfact-cli
rev: v0.47.4
hooks:
- id: specfact-smart-checks
```
The shim runs `scripts/pre-commit-quality-checks.sh all` (full pipeline including module verify).
### GitHub Actions
```yaml
- name: SpecFact Gate
run: uvx specfact-cli@latest govern enforce stage --preset minimal
```
## How SpecFact is built
SpecFact uses the same discipline it asks you to trust:
1. Outside-in research on the workflow or drift problem
2. Public **OpenSpec** proposal and spec deltas
3. TDD evidence before implementation
4. Dogfooding with `specfact code review`
5. Format, type-check, contract-test, and docs quality gates
6. PR review with evidence artifacts
7. Release through the same reproducible CLI paths
## For teams and organizations
SpecFact still scales beyond the solo-developer entry path, but validation stays
the center:
- **Upstream context adapters** for GitHub, Azure DevOps, Jira, Linear, OpenSpec, and Spec Kit inputs
- **DoR/DoD and policy enforcement** for teams that need repeatable gates
- **Evidence-backed PR review** with the same checks used locally
- **CI/CD adoption path** that keeps validation deterministic instead of model-driven
Optional module-deep paths include:
- `specfact project import ...`
- `specfact spec validate ...`
- `specfact backlog verify-readiness --bundle `
- `specfact govern ...`
## Module system
Official workflow behavior ships from `nold-ai/specfact-cli-modules`. The core CLI owns bootstrap, runtime contracts, trust checks, logging, and the grouped command surface. Installed modules add families such as `project`, `backlog`, `code`, `spec`, and `govern`.
Install examples:
```bash
specfact module install nold-ai/specfact-project
specfact module install nold-ai/specfact-backlog
specfact module install nold-ai/specfact-codebase
specfact module install nold-ai/specfact-code-review
specfact module install nold-ai/specfact-govern
```
If startup warns that modules are missing or outdated, run:
```bash
specfact module init --scope project
specfact module init
```
## Documentation topology
`docs.specfact.io` is the canonical starting point for SpecFact.
- Core CLI/runtime/platform documentation remains owned by `specfact-cli`
- Module-specific deep docs are canonically owned by `specfact-cli-modules`
- The live modules docs site is published at `https://modules.specfact.io/`
Use this repository's docs for the product story, runtime lifecycle, command topology, trust model, and getting-started flow. Use the modules docs site when you want deeper workflow, adapter, and module-authoring guidance.
## How do I get started if I want more?
Next steps:
- **[Core CLI docs](docs/index.md)** for the core runtime, bootstrap, and validation flow
- **[Installation guide](https://docs.specfact.io/getting-started/installation/)** for uvx-first and persistent CLI setup
- **[Quickstart](https://docs.specfact.io/getting-started/quickstart/)** for the first repo review path
- **[Reference: command topology](docs/reference/commands.md)** for grouped command surfaces
- **[Canonical modules docs site](https://modules.specfact.io/)** for bundle-deep workflows