Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/nold-ai/specfact-cli

The “swiss knife” CLI for agile DevOps teams. Keep backlog, specs, tests, and code in sync. Greenfield + brownfield with SDD/TDD/contracts.
https://github.com/nold-ai/specfact-cli

ai backlog-refinement brownfield code2spec context-engineering contract-enforcement contract-first contract-testing contracts copilot kanban legacy-modernization python scrum sdd spec-driven-development spec-first testing

Last synced: 1 day ago
JSON representation

The “swiss knife” CLI for agile DevOps teams. Keep backlog, specs, tests, and code in sync. Greenfield + brownfield with SDD/TDD/contracts.

Awesome Lists containing this project

README 

          
# SpecFact CLI



> **The "swiss knife" CLI that turns any codebase into a clear, safe, and shippable workflow.**

> Keep backlog, specs, tests, and code in sync so AI-assisted changes do not break production.

> Works for brand-new projects and long-lived codebases - even if you are new to coding.



**No API keys required. Works offline. Zero vendor lock-in.**



[![PyPI version](https://img.shields.io/pypi/v/specfact-cli.svg?color=22c55e)](https://pypi.org/project/specfact-cli/)

[![Python versions](https://img.shields.io/pypi/pyversions/specfact-cli.svg)](https://pypi.org/project/specfact-cli/)

[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)

[![Status](https://img.shields.io/badge/status-beta-F59E0B.svg)](https://github.com/nold-ai/specfact-cli)






**[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)**






---



## Start Here (60 seconds)



### Install



```bash

# Zero-install (recommended)

uvx specfact-cli@latest



# Or install globally

pip install -U specfact-cli

```



### Bootstrap and IDE Setup



```bash

# Bootstrap module registry and local config (~/.specfact)

specfact init



# Configure IDE prompts/templates (interactive selector by default)

specfact init ide

specfact init ide --ide cursor

specfact init ide --ide vscode

```



### Run Your First Flow



```bash

# Analyze an existing codebase

specfact import from-code my-project --repo .



# Validate external code without modifying source

specfact validate sidecar init my-project /path/to/repo

specfact validate sidecar run my-project /path/to/repo

```



### Backlog Bridge (60 seconds)



SpecFact's USP is closing the drift gap between **backlog -> specs -> code**.



```bash

# 1) Initialize backlog config + field mapping

specfact backlog init-config --force

specfact backlog map-fields --provider ado --ado-org  --ado-project ""



# 2) Run standup/refinement on real backlog scope

specfact backlog daily ado --ado-org  --ado-project "" --state any --assignee any --limit 5

specfact backlog refine ado --ado-org  --ado-project "" --id  --preview



# 3) Keep backlog + spec intent aligned (avoid silent drift)

specfact policy validate --group-by-item

```



For GitHub, replace adapter/org/project with:

`specfact backlog daily github --repo-owner  --repo-name  ...`



Deep dive:

- **[Backlog Quickstart Demo (GitHub + ADO)](docs/getting-started/tutorial-backlog-quickstart-demo.md)**



**AI IDE quick start**



```bash

# In your IDE chat (Cursor, VS Code, Copilot, etc.)

/specfact.01-import my-project --repo .

```



**Next steps**



- **[Getting Started](docs/getting-started/README.md)**

- **[AI IDE Workflow](docs/guides/ai-ide-workflow.md)**

- **[Command Chains](docs/guides/command-chains.md)**



---



## Proof and Expectations



- **Typical runtime**: 2-15 minutes depending on repo size and complexity.

- **Checkpointing**: Progress is saved during analysis so you can resume safely.

- **Performance**: Optimized for large codebases with cached parsing and file hashes.



---



## Why It Matters (Plain Language)



- **Clarity**: Turn messy code into clear specs your team can trust.

- **Safety**: Catch risky changes early with validation and contract checks.

- **Sync**: Keep backlog items, specs, tests, and code aligned end to end.

- **Adoption**: Simple CLI, no platform lock-in, works offline.



---



## Who It Is For



- **Vibe coders and new builders** who want to ship fast with guardrails and confidence.

- **Legacy professionals** who want AI speed without lowering standards.

- **DevOps and engineering leaders** who need evidence and repeatable workflows.



---



## How It Works (High Level)



1. **Analyze**: Read code and extract specs, gaps, and risks.

2. **Sync**: Connect specs, backlog items, and plans in one workflow.

3. **Validate**: Enforce contracts and block regressions before production.



---



## The Missing Link (Coder + DevOps Bridge)



Most tools help **either** coders **or** agile teams. SpecFact does both:



- **Backlog sync that is actually strong**: round-trip sync + refinement with GitHub, Azure DevOps, Jira, Linear.

- **Ceremony support teams can run**: standup, refinement, sprint planning, flow metrics (Scrum/Kanban/SAFe).

- **Policy + validation**: DoR/DoD/flow checks plus contract enforcement for production-grade stability.



Recommended command entrypoints:

- `specfact backlog ceremony standup ...`

- `specfact backlog ceremony refinement ...`

- `specfact policy validate ...`

- `specfact policy suggest ...`



What the Policy Engine does in practice:

- Turns team agreements (DoR, DoD, flow checks) into executable checks against your real backlog data.

- Shows exactly what is missing per item (for example missing acceptance criteria or definition of done).

- Generates patch-ready suggestions so teams can fix policy gaps quickly without guessing.



Start with:

- `specfact policy init --template scrum`

- `specfact policy validate --group-by-item`

- `specfact policy suggest --group-by-item --limit 5`



**Try it now**



- **Coders**: [AI IDE Workflow](docs/guides/ai-ide-workflow.md)

- **Agile teams**: [Agile/Scrum Workflows](docs/guides/agile-scrum-workflows.md)



---



## Modules and Capabilities



**Core modules**



- **Analyze**: Extract specs and plans from existing code.

- **Validate**: Enforce contracts, run reproducible checks, and block regressions.

- **Report**: CI/CD summaries and evidence outputs.



**Agile DevOps modules**



- **Backlog**: Refinement, dependency analysis, sprint summaries, risk rollups.

- **Ceremony**: Standup, refinement, and planning entry points.

- **Policy**: DoR, DoD, flow, PI readiness checks.

- **Patch**: Preview, apply, and write changes safely.



**Adapters and bridges**



- **Specs**: Spec-Kit and OpenSpec

- **Backlogs**: GitHub Issues, Azure DevOps, Jira, Linear

- **Contracts**: Specmatic, OpenAPI



For technical architecture details (module lifecycle, registry internals, adapters, and implementation status), use:



- [Architecture Reference](docs/reference/architecture.md)

- [Architecture Docs Index](docs/architecture/README.md)

- [Architecture Implementation Status](docs/architecture/implementation-status.md)



---



## Where SpecFact Fits



SpecFact complements your stack rather than replacing it.



- **Spec-Kit/OpenSpec** for authoring and change tracking

- **Backlog tools** for planning and delivery

- **CI/CD** for enforcement and regression prevention



**SpecFact connects them** with adapters, policy checks, and deterministic validation.



**Integrations snapshot**: GitHub, Azure DevOps, Jira, Linear, Spec-Kit, OpenSpec, Specmatic.



- **[Integrations Overview](docs/guides/integrations-overview.md)**

- **[DevOps Adapter Integration](docs/guides/devops-adapter-integration.md)**



---



## Recommended Paths



- **I want a quick win**: [Getting Started](docs/getting-started/README.md)

- **I use an AI IDE**: [AI IDE Workflow](docs/guides/ai-ide-workflow.md)

- **We have a team backlog**: [Agile/Scrum Workflows](docs/guides/agile-scrum-workflows.md)

- **We have a long-lived codebase**: [Working With Existing Code](docs/guides/brownfield-engineer.md)



---



## Documentation Map



- **[Documentation Index](docs/README.md)**

- **[Command Reference](docs/reference/commands.md)**

- **[Backlog Refinement](docs/guides/backlog-refinement.md)**

- **[Backlog Dependency Analysis](docs/guides/backlog-dependency-analysis.md)**

- **[Backlog Delta Commands](docs/guides/backlog-delta-commands.md)**

- **[Policy Engine Commands](docs/guides/policy-engine-commands.md)**

- **[Project DevOps Flow](docs/guides/project-devops-flow.md)**

- **[Sidecar Validation](docs/guides/sidecar-validation.md)**

- **[OpenSpec Journey](docs/guides/openspec-journey.md)**



---



## Contributing



We welcome contributions. See [CONTRIBUTING.md](CONTRIBUTING.md).



```bash

git clone https://github.com/nold-ai/specfact-cli.git

cd specfact-cli

pip install -e ".[dev]"

hatch run contract-test-full

```



---



## License



**Apache License 2.0** - Open source and enterprise-friendly.



[Full license](LICENSE)



---



## Support



- **GitHub Discussions**: https://github.com/nold-ai/specfact-cli/discussions

- **GitHub Issues**: https://github.com/nold-ai/specfact-cli/issues

- **Email**: hello@noldai.com

- **Debug logs**: Run with `--debug` and check `~/.specfact/logs/specfact-debug.log`.



---






**Built by [NOLD AI](https://noldai.com)**



Copyright © 2025-2026 Nold AI (Owner: Dominikus Nold)



**Trademarks**: NOLD AI (NOLDAI) is a registered trademark (wordmark) at the European Union Intellectual Property Office (EUIPO). All other trademarks mentioned in this project are the property of their respective owners. See [TRADEMARKS.md](TRADEMARKS.md) for more information.