Command Chains Reference

Complete guide to SpecFact CLI command chains and workflows

Overview

Command chains are sequences of SpecFact CLI commands that work together to achieve specific goals. Each chain represents a complete workflow from start to finish, with decision points and expected outcomes documented.

Why use command chains? Instead of learning individual commands in isolation, command chains show you how to combine commands to solve real-world problems. They provide context, decision points, and links to detailed guides.

Module System Context

These chains run on SpecFact’s module-first architecture:

  • Core runtime handles lifecycle, registry, contracts, and orchestration.
  • Feature command logic is implemented in module-local command groups.
  • Legacy command paths are compatibility shims during migration windows.

This keeps chains stable while modules evolve independently.

This document covers all 10 identified command chains:

  • 7 Mature Chains: Well-established workflows with comprehensive documentation
  • 3 Emerging Chains: AI-assisted workflows that integrate with IDE slash commands

When to Use Which Chain?

Use this decision tree to find the right chain for your use case:

Start: What do you want to accomplish?

├─ Modernize existing legacy code?
│  └─ → Brownfield Modernization Chain
│
├─ Plan a new feature from scratch?
│  └─ → Greenfield Planning Chain
│
├─ Integrate with Spec-Kit, OpenSpec, or other tools?
│  └─ → External Tool Integration Chain
│
├─ Develop or validate API contracts?
│  └─ → API Contract Development Chain
│
├─ Validate external codebase without modifying source?
│  └─ → Sidecar Validation Chain
│
├─ Promote a plan through stages to release?
│  └─ → Plan Promotion & Release Chain
│
├─ Compare code against specifications?
│  └─ → Code-to-Plan Comparison Chain
│
├─ Use AI to enhance code with contracts?
│  └─ → AI-Assisted Code Enhancement Chain (Emerging)
│
├─ Generate tests from specifications?
│  └─ → Test Generation from Specifications Chain (Emerging)
│
└─ Fix gaps discovered during analysis?
   └─ → Gap Discovery & Fixing Chain (Emerging)

1. Brownfield Modernization Chain

Goal: Modernize legacy code safely by extracting specifications, creating plans, and enforcing contracts.

When to use: You have existing code that needs modernization, refactoring, or migration.

Command Sequence:

# Step 1: Extract specifications from legacy code
specfact code import legacy-api --repo .

# Step 2: Review the extracted plan
specfact project snapshot legacy-api

# Step 3: Update features based on review findings
specfact project devops-flow --stage plan --action update-feature --bundle legacy-api --feature <feature-id>

# Step 4: Enforce SDD (Spec-Driven Development) compliance
specfact govern enforce sdd --bundle legacy-api

# Step 5: Run full validation suite
specfact code repro --verbose

Workflow Diagram:

graph TD
    A[Legacy Codebase] -->|import from-code| B[Extract Specifications]
    B --> C[Plan Review]
    C -->|Issues Found| D[Update Features]
    C -->|No Issues| E[Enforce SDD]
    D --> E
    E --> F[Run Validation]
    F -->|Pass| G[Modernized Code]
    F -->|Fail| D

Decision Points:

  • After import from-code: Review the extracted plan. If features are incomplete or incorrect, use project devops-flow --stage plan --action update-feature to refine them.
  • After project snapshot: If ambiguities are found, resolve them before proceeding to enforcement.
  • After enforce sdd: If compliance fails, update the plan and re-run enforcement.
  • After repro: If validation fails, fix issues and re-run the chain from the appropriate step.

Expected Outcomes:

  • Complete specification extracted from legacy code
  • Plan bundle with features, stories, and acceptance criteria
  • SDD-compliant codebase
  • Validated contracts and tests

Related Guides:

2. Greenfield Planning Chain

Goal: Plan new features from scratch using Spec-Driven Development principles.

When to use: You’re starting a new feature or project and want to plan it properly before coding.

Command Sequence:

# Step 1: Initialize a new plan bundle
specfact project devops-flow --stage plan --action init --bundle new-feature --interactive

# Step 2: Add features to the plan
specfact project devops-flow --stage plan --action add-feature --bundle new-feature --name "User Authentication"

# Step 3: Add user stories to features
specfact project devops-flow --stage plan --action add-story --bundle new-feature --feature <feature-id> --story "As a user, I want to log in"

# Step 4: Review the plan for completeness
specfact project snapshot new-feature

# Step 5: Harden the plan (finalize before implementation)
specfact project devops-flow --stage plan --action harden --bundle new-feature

# Step 6: Use your AI IDE skill (/specfact.07-contracts) for contract enhancement workflows

# Step 7: Enforce SDD compliance
specfact govern enforce sdd --bundle new-feature

Workflow Diagram:

graph TD
    A[New Feature Idea] -->|plan init| B[Initialize Plan]
    B -->|plan add-feature| C[Add Features]
    C -->|plan add-story| D[Add User Stories]
    D -->|plan review| E[Review Plan]
    E -->|Issues| D
    E -->|Complete| F[plan harden]
    F -->|generate contracts| G[Generate Contracts]
    G -->|enforce sdd| H[SDD-Compliant Plan]

Decision Points:

  • After devops-flow plan init: Choose interactive mode to get guided prompts, or use flags for automation.
  • After devops-flow plan add-feature: Add multiple features before adding stories, or add stories immediately.
  • After project snapshot: If ambiguities are found, add more details or stories before hardening.
  • After devops-flow plan harden: Once hardened, the plan is locked. Use the AI IDE skill for contract enhancement before enforcement.

Expected Outcomes:

  • Complete plan bundle with features and stories
  • Generated contracts ready for implementation
  • SDD-compliant plan ready for development

Related Guides:

3. External Tool Integration Chain

Goal: Integrate SpecFact with external tools like Spec-Kit, OpenSpec, or DevOps backlog tools (GitHub Issues, Linear, Jira).

When to use: You want to sync specifications between SpecFact and other tools, import from external sources, or integrate SpecFact into your agile DevOps workflows.

Command Sequence:

# For Code/Spec Adapters (Spec-Kit, OpenSpec, generic-markdown):
# Step 1: Import from external tool via bridge adapter
specfact code import from-bridge --repo . --adapter speckit --write

# Step 2: Review the imported plan
specfact project snapshot <bundle-name>

# Step 3: Set up bidirectional sync (optional)
specfact project sync bridge --adapter speckit --bundle <bundle-name> --bidirectional --watch

# Step 4: Enforce SDD compliance
specfact govern enforce sdd --bundle <bundle-name>

# For Backlog Adapters (GitHub Issues, ADO, Linear, Jira) - NEW FEATURE:
# Step 1: Export OpenSpec change proposals to GitHub Issues
specfact project sync bridge --adapter github --bidirectional --repo-owner owner --repo-name repo

# Step 2: Import GitHub Issues as change proposals (if needed)
# (Automatic when using --bidirectional)

# Step 3: Track code changes automatically
specfact project sync bridge --adapter github --track-code-changes --repo-owner owner --repo-name repo

Workflow Diagram:

graph LR
    A[External Tool] -->|import from-bridge| B[SpecFact Plan]
    B -->|plan review| C[Review Import]
    C -->|sync bridge| D[Bidirectional Sync]
    D -->|enforce sdd| E[SDD-Compliant]
    E -.->|watch mode| D

Decision Points:

  • After import from-bridge: Review the imported plan. If it needs refinement, use project devops-flow --stage plan --action update-feature.
  • Bidirectional sync: Use --watch mode for continuous synchronization, or run sync manually as needed.
  • Adapter selection:
    • Code/Spec adapters (use import from-bridge): speckit, openspec, generic-markdown
    • Backlog adapters (use sync bridge): github, ado, linear, jira
    • Note: Backlog adapters (GitHub Issues, ADO, Linear, Jira) use sync bridge for bidirectional synchronization, not import from-bridge. The import from-bridge command is specifically for importing entire code/spec projects.

Expected Outcomes:

  • Specifications imported from external tool
  • Bidirectional synchronization (if enabled)
  • SDD-compliant integrated workflow

Related Guides:

4. API Contract Development Chain

Goal: Develop, validate, and test API contracts using SpecFact and Specmatic integration.

When to use: You’re developing REST APIs and want to ensure contract compliance and backward compatibility.

Command Sequence:

# Step 1: Validate API specification
specfact spec validate --spec openapi.yaml

# Step 2: Check backward compatibility
specfact spec backward-compat --spec openapi.yaml --previous-spec openapi-v1.yaml

# Step 3: Generate tests from specification
specfact spec generate-tests --spec openapi.yaml --output tests/

# Step 4: Generate mock server (optional)
specfact spec mock --spec openapi.yaml --port 8080

# Step 5: Validate contracts at runtime
specfact spec validate --bundle api-bundle

Workflow Diagram:

graph TD
    A[API Specification] -->|spec validate| B[Validate Spec]
    B -->|spec backward-compat| C[Check Compatibility]
    C -->|spec generate-tests| D[Generate Tests]
    C -->|spec mock| E[Mock Server]
    D -->|contract verify| F[Verified Contracts]
    E --> F

Decision Points:

  • After spec validate: If validation fails, fix the specification before proceeding.
  • Backward compatibility: Check compatibility before releasing new API versions.
  • Mock server: Use mock server for testing clients before implementation is complete.
  • Contract verification: Run verification in CI/CD to catch contract violations early.

Expected Outcomes:

  • Validated API specification
  • Backward compatibility verified
  • Generated tests from specification
  • Runtime contract verification

Related Guides:

5. Sidecar Validation Chain

Goal: Validate external codebases (libraries, APIs, frameworks) without modifying source code.

When to use: You need to validate third-party libraries, legacy codebases, or APIs where you don’t control the implementation.

Command Sequence:

# Step 1: Initialize sidecar workspace
specfact code validate sidecar init <bundle-name> <repo-path>

# Step 2: Run sidecar validation workflow
specfact code validate sidecar run <bundle-name> <repo-path>

# Step 3: Review validation results
# Results are saved to .specfact/projects/<bundle>/reports/sidecar/

Workflow Diagram:

graph TD
    A[External Repository] -->|validate sidecar init| B[Initialize Workspace]
    B --> C[Detect Framework]
    C --> D[Extract Routes/Schemas]
    D --> E[Populate Contracts]
    E --> F[Generate Harness]
    F -->|CrossHair| G[Symbolic Execution]
    F -->|Specmatic| H[Contract Testing]
    G --> I[Validation Results]
    H --> I

Decision Points:

  • After validate sidecar init: Review detected framework and configuration. Adjust if needed.
  • Framework detection: System automatically detects Django, FastAPI, DRF, Flask, or pure Python. Verify detection is correct.
  • Tool execution: Use --no-run-crosshair or --no-run-specmatic to skip specific tools if not needed.
  • After validate sidecar run: Review validation results. Fix issues in contracts or harness if needed.

Expected Outcomes:

  • Sidecar workspace initialized with framework-specific configuration
  • Routes and schemas extracted from framework patterns
  • OpenAPI contracts populated with extracted data
  • CrossHair harness generated from contracts
  • Validation results (CrossHair analysis, Specmatic testing)
  • Reports saved to sidecar reports directory

Related Guides:

6. Plan Promotion & Release Chain

Goal: Promote a plan through stages (draft → review → approved → released) and manage versions.

When to use: You have a completed plan and want to promote it through your organization’s approval process.

Command Sequence:

# Step 1: Review the plan before promotion
specfact project snapshot <bundle-name>

# Step 2: Enforce SDD compliance
specfact govern enforce sdd --bundle <bundle-name>

# Step 3: Promote the plan to next stage
specfact project devops-flow --stage release --action promote --bundle <bundle-name> --stage <next-stage>

# Step 4: Bump version when releasing
specfact project version bump --bundle <bundle-name> --type <major|minor|patch>

Workflow Diagram:

graph LR
    A[Draft Plan] -->|plan review| B[Review]
    B -->|enforce sdd| C[SDD Compliant]
    C -->|plan promote| D[Next Stage]
    D -->|version bump| E[Released]

Decision Points:

  • After project snapshot: If issues are found, fix them before promotion.
  • SDD enforcement: Ensure compliance before promoting to production stages.
  • Version bumping: Choose appropriate version type (major/minor/patch) based on changes.

Expected Outcomes:

  • Plan promoted through approval stages
  • Version bumped appropriately
  • Release-ready plan bundle

Related Guides:

7. Code-to-Plan Comparison Chain

Goal: Detect and resolve drift between code and specifications.

When to use: You want to ensure your code matches your specifications, or detect when code has diverged.

Command Sequence:

# Step 1: Import current code state
specfact code import current-state --repo .

# Step 2: Compare code against plan
specfact project devops-flow --stage plan --action compare --bundle <plan-bundle> --code-vs-plan

# Step 3: Detect drift
specfact code drift detect --bundle <bundle-name>

# Step 4: Sync repository (if drift found)
specfact project sync repository --bundle <bundle-name> --direction <code-to-plan|plan-to-code>

Workflow Diagram:

graph TD
    A[Code Repository] -->|import from-code| B[Current State]
    B -->|plan compare| C[Compare]
    C -->|drift detect| D[Drift Found?]
    D -->|Yes| E[sync repository]
    D -->|No| F[In Sync]
    E --> F

Decision Points:

  • After devops-flow compare: Review the comparison results to understand differences.
  • Drift detection: If drift is detected, decide whether to sync code-to-plan or plan-to-code.
  • Sync direction: Choose code-to-plan to update plan from code, or plan-to-code to update code from plan.

Expected Outcomes:

  • Code and plan synchronized
  • Drift detected and resolved
  • Consistent state between code and specifications

Related Guides:

8. AI-Assisted Code Enhancement Chain (Emerging)

Goal: Use AI IDE integration to enhance code with contracts and validate them.

When to use: You want to add contracts to existing code using AI assistance in your IDE.

Command Sequence:

# Step 1: Use your AI IDE skill (/specfact.07-contracts) for contract enhancement workflows
# /specfact.07-contracts <bundle-name> <feature-id>

# Step 2: Validate spec compliance
specfact spec validate --bundle <bundle-name>

# Step 3: Run validation
specfact code repro --verbose

Workflow Diagram:

graph TD
    A[Code Without Contracts] -->|generate contracts-prompt| B[AI Prompt]
    B -->|AI IDE| C[Apply Contracts]
    C -->|contract coverage| D[Check Coverage]
    D -->|repro| E[Validated Code]

Decision Points:

  • After using AI IDE skill: Review the AI-generated contracts before applying.
  • Spec validation: Ensure coverage meets your requirements before validation.
  • Validation: If validation fails, review and fix contracts, then re-run.

Expected Outcomes:

  • Contracts added to code via AI assistance
  • Contract coverage verified
  • Validated enhanced code

Related Guides:

9. Test Generation from Specifications Chain (Emerging)

Goal: Generate tests from specifications using AI assistance.

When to use: You have specifications and want to generate comprehensive tests automatically.

Command Sequence:

# Step 1: Use your AI IDE skill (/specfact.07-contracts) for contract enhancement workflows
# /specfact.07-contracts <bundle-name> <feature-id>

# Step 2: Generate tests from specification
specfact spec generate-tests --spec <spec-file> --output tests/

# Step 3: Run tests
pytest tests/

Workflow Diagram:

graph TD
    A[Specification] -->|generate test-prompt| B[AI Prompt]
    B -->|AI IDE| C[Generate Tests]
    A -->|spec generate-tests| D[Spec-Based Tests]
    C --> E[Test Suite]
    D --> E
    E -->|pytest| F[Test Results]

Decision Points:

  • Test generation method: Use AI IDE skill /specfact.07-contracts for custom tests, or spec generate-tests for specification-based tests.
  • Test coverage: Review generated tests to ensure they cover all scenarios.
  • Test execution: Run tests in CI/CD for continuous validation.

Expected Outcomes:

  • Comprehensive test suite generated
  • Tests validated and passing
  • Specification coverage verified

Related Guides:

10. Gap Discovery & Fixing Chain (Emerging)

Goal: Discover gaps in specifications and fix them using AI assistance.

When to use: You want to find missing contracts or specifications and add them systematically.

Command Sequence:

# Step 1: Run validation with verbose output
specfact code repro --verbose

# Step 2: Use your AI IDE skill (/specfact.07-contracts) for contract enhancement workflows
# /specfact.07-contracts <bundle-name> <gap-id>

# Step 3: Enforce SDD compliance
specfact govern enforce sdd --bundle <bundle-name>

Workflow Diagram:

graph TD
    A[Codebase] -->|repro --verbose| B[Discover Gaps]
    B -->|generate fix-prompt| C[AI Fix Prompt]
    C -->|AI IDE| D[Apply Fixes]
    D -->|enforce sdd| E[SDD Compliant]
    E -->|repro| B

Decision Points:

  • After repro --verbose: Review discovered gaps and prioritize fixes.
  • Fix application: Review AI-suggested fixes from /specfact.07-contracts before applying.
  • SDD enforcement: Ensure compliance after fixes are applied.

Expected Outcomes:

  • Gaps discovered and documented
  • Fixes applied via AI assistance
  • SDD-compliant codebase

Related Guides:

11. SDD Constitution Management Chain

Goal: Manage Spec-Driven Development (SDD) constitutions for Spec-Kit compatibility.

When to use: You’re working with Spec-Kit format and need to bootstrap, enrich, or validate constitutions.

Command Sequence:

# Use specfact govern enforce sdd [BUNDLE] for SDD enforcement
specfact govern enforce sdd <bundle-name>

Workflow Diagram:

graph TD
    A[Repository] -->|govern enforce sdd| B[SDD Enforcement]
    B -->|Pass| C[SDD Compliant]
    B -->|Issues Found| D[Fix Issues]
    D --> B

Decision Points:

  • SDD Enforcement: Use specfact govern enforce sdd [BUNDLE] for all SDD enforcement workflows.
  • Spec-Kit Compatibility: SDD constitution commands are removed. SpecFact uses modular project bundles internally.

Expected Outcomes:

  • Complete SDD constitution for Spec-Kit compatibility
  • Validated constitution ready for use
  • List of SDD manifests in repository

Related Guides:

Orphaned Commands Integration

The following commands are now integrated into documented workflows:

plan update-idea

Integrated into: Greenfield Planning Chain

When to use: Update feature ideas during planning phase.

Workflow: Use as part of plan update-feature workflow in Greenfield Planning.

project export/import/lock/unlock

Integrated into: Team Collaboration Workflow and Plan Promotion & Release Chain

When to use: Team collaboration with persona-based workflows.

Workflow: See Team Collaboration Workflow for complete workflow.

migrate * Commands

Integrated into: Migration Guide

When to use: Migrating between versions or from other tools.

Workflow: See Migration Guide for decision tree and workflows.

govern enforce sdd

Integrated into: SDD Constitution Management Chain

When to use: Enforce SDD compliance for a bundle.

Workflow: Use after plan hardening to validate SDD compliance.

spec validate

Integrated into: API Contract Development Chain

When to use: Validate contracts at runtime.

Workflow: Use as final step in API Contract Development Chain.

See Also