Common Tasks Quick Reference

Quick answers to “How do I X?” questions

Overview

This guide maps common user goals to recommended SpecFact CLI commands or command chains. Each entry includes a task description, recommended approach, link to detailed guide, and a quick example.

Not sure which task matches your goal? Use the Command Chains Decision Tree to find the right workflow.

Getting Started

I want to analyze my legacy code

Recommended: Brownfield Modernization Chain

Command: import from-code

Quick Example:

specfact import from-code --bundle legacy-api --repo .

Detailed Guide: Brownfield Engineer Guide

I want to plan a new feature from scratch

Recommended: Greenfield Planning Chain

Command: plan init → plan add-feature → plan add-story

Quick Example:

specfact plan init --bundle new-feature --interactive
specfact plan add-feature --bundle new-feature --name "User Authentication"
specfact plan add-story --bundle new-feature --feature <feature-id> --story "As a user, I want to log in"

Detailed Guide: Agile/Scrum Workflows

I want to sync with Spec-Kit or OpenSpec

Recommended: External Tool Integration Chain

Command: import from-bridge → sync bridge

Quick Example:

specfact import from-bridge --repo . --adapter speckit --write
specfact sync bridge --adapter speckit --bundle <bundle-name> --bidirectional --watch
Detailed Guide: Spec-Kit Journey OpenSpec Journey

Brownfield Modernization

I want to extract specifications from existing code

Recommended: import from-code

Quick Example:

specfact import from-code --bundle legacy-api --repo ./legacy-app

Detailed Guide: Brownfield Engineer Guide

I want to review and update extracted features

Recommended: plan review → plan update-feature

Quick Example:

specfact plan review --bundle legacy-api
specfact plan update-feature --bundle legacy-api --feature <feature-id>

Detailed Guide: Brownfield Engineer Guide

I want to detect code-spec drift

Recommended: Code-to-Plan Comparison Chain

Command: plan compare → drift detect

Quick Example:

specfact import from-code --bundle current-state --repo .
specfact plan compare --bundle <plan-bundle> --code-vs-plan
specfact drift detect --bundle <bundle-name>

Detailed Guide: Drift Detection

I want to add contracts to existing code

Recommended: AI-Assisted Code Enhancement Chain

Command: generate contracts-prompt → [AI IDE] → contracts-apply

Quick Example:

specfact generate contracts-prompt --bundle <bundle-name> --feature <feature-id>
# Then use AI IDE slash command: /specfact-cli/contracts-apply <prompt-file>
specfact contract coverage --bundle <bundle-name>

Detailed Guide: AI IDE Workflow

API Development

I want to validate API contracts

Recommended: API Contract Development Chain

Command: spec validate → spec backward-compat

Quick Example:

specfact spec validate --spec openapi.yaml
specfact spec backward-compat --spec openapi.yaml --previous-spec openapi-v1.yaml

Detailed Guide: Specmatic Integration

I want to generate tests from API specifications

Recommended: spec generate-tests

Quick Example:

specfact spec generate-tests --spec openapi.yaml --output tests/
pytest tests/

Detailed Guide: Contract Testing Workflow

I want to create a mock server for API development

Recommended: spec mock

Quick Example:

specfact spec mock --spec openapi.yaml --port 8080

Detailed Guide: Specmatic Integration

Team Collaboration

I want to set up team collaboration

Recommended: Team Collaboration Workflow

Command: project export → project import → project lock/unlock

Quick Example:

specfact project init-personas --bundle <bundle-name>
specfact project export --bundle <bundle-name> --persona product-owner
# Edit exported Markdown files
specfact project import --bundle <bundle-name> --persona product-owner --source exported-plan.md

Detailed Guide: Agile/Scrum Workflows

I want to export persona-specific views

Recommended: project export

Quick Example:

specfact project export --bundle <bundle-name> --persona product-owner
specfact project export --bundle <bundle-name> --persona architect
specfact project export --bundle <bundle-name> --persona developer

Detailed Guide: Agile/Scrum Workflows

I want to manage project versions

Recommended: project version check → project version bump

Quick Example:

specfact project version check --bundle <bundle-name>
specfact project version bump --bundle <bundle-name> --type minor

Detailed Guide: Project Version Management

Plan Management

I want to promote a plan through stages

Recommended: Plan Promotion & Release Chain

Command: plan review → enforce sdd → plan promote

Quick Example:

specfact plan review --bundle <bundle-name>
specfact enforce sdd --bundle <bundle-name>
specfact plan promote --bundle <bundle-name> --stage approved

Detailed Guide: Agile/Scrum Workflows

I want to compare two plans

Recommended: plan compare

Quick Example:

specfact plan compare --bundle plan-v1 plan-v2

Detailed Guide: Plan Comparison

Validation & Enforcement

I want to validate everything

Recommended: repro

Quick Example:

specfact repro --verbose

Detailed Guide: Validation Workflow

I want to enforce SDD compliance

Recommended: enforce sdd

Quick Example:

specfact enforce sdd --bundle <bundle-name>

Detailed Guide: SDD Enforcement

I want to find gaps in my code

Recommended: Gap Discovery & Fixing Chain

Command: repro --verbose → generate fix-prompt

Quick Example:

specfact repro --verbose
specfact generate fix-prompt --bundle <bundle-name> --gap <gap-id>
# Then use AI IDE to apply fixes

Detailed Guide: AI IDE Workflow

AI IDE Integration

I want to set up AI IDE slash commands

Recommended: init --ide cursor

Quick Example:

specfact init --ide cursor
Detailed Guide: AI IDE Workflow IDE Integration

I want to generate tests using AI

Recommended: Test Generation from Specifications Chain

Command: generate test-prompt → [AI IDE] → spec generate-tests

Quick Example:

specfact generate test-prompt --bundle <bundle-name> --feature <feature-id>
# Then use AI IDE slash command: /specfact-cli/test-generate <prompt-file>
specfact spec generate-tests --spec <spec-file> --output tests/

Detailed Guide: AI IDE Workflow

DevOps Integration

I want to sync change proposals to GitHub Issues

Recommended: sync bridge --mode export-only

Quick Example:

specfact sync bridge --adapter github --mode export-only --repo-owner owner --repo-name repo

Detailed Guide: DevOps Adapter Integration

I want to track changes in GitHub Projects

Recommended: DevOps bridge adapter with project linking

Quick Example:

specfact sync bridge --adapter github --mode export-only --project "SpecFact CLI Development Board"

Detailed Guide: DevOps Adapter Integration

Migration & Troubleshooting

I want to migrate from an older version

Recommended: Check migration guides

Quick Example:

# Check current version
specfact --version

# Review migration guide for your version
# See: guides/migration-*.md
Detailed Guide: Migration Guide Troubleshooting

I want to troubleshoot an issue

Recommended: Troubleshooting Guide

Quick Example:

# Run validation with verbose output
specfact repro --verbose

# Check plan for issues
specfact plan review --bundle <bundle-name>

Detailed Guide: Troubleshooting

See Also