SpecFact CLI Documentation

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 don’t break production.

Built for both worlds

  • Vibe coders and new builders who want to ship fast with guardrails and confidence.
  • Legacy professionals who want AI speed without lowering standards, plus end-to-end spec -> backlog -> code sync.

Core promise: Works for new and long-lived projects with contract enforcement and validation.

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 ...

Try it now

🚀 Quick Start

New to SpecFact CLI?

Primary Use Case: Understanding and improving existing codebases (and new projects)

  1. Installation - Get started in 60 seconds
  2. First Steps - Run your first command
  3. Tutorial: Backlog Refine with AI IDE - Integrate backlog refinement with your AI IDE (agile DevOps)
  4. Tutorial: Daily Standup and Sprint Review - Daily standup view, post comments, and Copilot export (GitHub/ADO)
  5. Working With Existing Code ⭐ PRIMARY - Legacy-first guide
  6. The Existing Code Journey ⭐ - Complete modernization workflow

Using GitHub Spec-Kit or OpenSpec?

Secondary Use Case: Add automated enforcement to your Spec-Kit or OpenSpec projects

Module System Foundation

SpecFact now uses a module-first architecture to reduce hard-wired command coupling.

  • Core runtime handles lifecycle, registry, contracts, and orchestration.
  • Feature behavior lives in module-local command implementations.
  • Legacy command-path shims remain for compatibility during migration windows.

Implementation layout:

  • Primary module commands: src/specfact_cli/modules/<module>/src/commands.py
  • Legacy compatibility shims: src/specfact_cli/commands/*.py (only app re-export is guaranteed)

Why this matters:

  • Modules can evolve at different speeds without repeatedly changing CLI core wiring.
  • Interfaces and contracts keep feature development isolated and safer to iterate.
  • Pending OpenSpec-driven module changes can land incrementally with lower migration risk.

Module security and extensions:

📚 Documentation

Guides

DevOps & Backlog Sync 🚀

For Developers & DevOps Teams: Keep your backlogs in sync with feature branches, code changes, and validations.

  • DevOps Integration Guide ⭐ - Complete guide for GitHub Issues and Azure DevOps integration
    • Cross-Adapter Sync: Lossless round-trip migration between backlog tools (GitHub ↔ ADO)
    • Bidirectional Sync: Import backlog items as proposals, export proposals as backlog items
    • Code Change Tracking: Automatically detect commits and add progress comments
    • Status Synchronization: Keep OpenSpec and backlog status in sync
  • Backlog Refinement Guide 🆕 NEW - AI-assisted template-driven refinement for standardizing work items
    • Tutorial: Backlog Refine with AI IDE - End-to-end tutorial for agile DevOps teams (slash prompt, DoR, split stories, underspec/overspec)
    • Tutorial: Daily Standup and Sprint Review - Daily standup view, post yesterday/today/blockers, interactive mode, Copilot export (GitHub/ADO)
    • Template Detection: Automatically detect which template matches a backlog item with priority-based resolution
    • AI-Assisted Refinement: Generate prompts for IDE AI copilots to refine unstructured input
    • Confidence Scoring: Validate refined content and provide confidence scores
    • Lossless Preservation: Preserve original backlog data for round-trip synchronization
    • Agile Filtering 🆕: Filter by sprint, release, iteration, labels, state, assignee for agile workflows
    • Persona/Framework Support 🆕: Filter templates by persona (product-owner, architect, developer) and framework (scrum, safe, kanban)
    • Definition of Ready (DoR) 🆕: Validate sprint readiness with repo-level DoR configuration
    • Preview/Write Safety 🆕: Preview mode by default, explicit --write flag for writeback
    • OpenSpec Integration 🆕: Add OpenSpec reference comments with --openspec-comment flag (preserves original body)
    • Template Customization 🆕: Create custom templates for your team - see Template Customization Guide
  • Authentication - Device code auth for GitHub and Azure DevOps
  • GitHub Adapter - GitHub Issues adapter reference
  • Azure DevOps Adapter - Azure DevOps work items adapter reference
  • Backlog Adapter Patterns - Patterns for implementing backlog adapters

Quick Start for DevOps Teams:

# Export OpenSpec proposals to GitHub Issues
specfact sync bridge --adapter github --mode export-only \
  --repo-owner your-org --repo-name your-repo

# Export to Azure DevOps work items
specfact sync bridge --adapter ado --mode export-only \
  --ado-org your-org --ado-project your-project

# Cross-adapter sync: GitHub -> ADO (lossless round-trip)
specfact sync bridge --adapter github --mode bidirectional \
  --bundle main --backlog-ids 123
specfact sync bridge --adapter ado --mode export-only \
  --bundle main --change-ids <change-id>

Reference

Module Protocol Reporting

  • Lifecycle protocol compliance reporting now classifies modules using the effective runtime interface and emits a single aggregate summary line for full/partial/legacy status.

Examples

🆘 Getting Help

Documentation

You’re here! Browse the guides above.

Community

Direct Support

🤝 Contributing

Found an error or want to improve the docs?

  1. Fork the repository
  2. Edit the markdown files in docs/
  3. Submit a pull request

See CONTRIBUTING.md for guidelines.

Happy building! 🚀

Copyright © 2025 Nold AI (Owner: Dominikus Nold)

Trademarks: All product names, logos, and brands mentioned in this documentation are the property of their respective owners. NOLD AI (NOLDAI) is a registered trademark (wordmark) at the European Union Intellectual Property Office (EUIPO). See TRADEMARKS.md for more information.

License: See LICENSE for licensing information.