layout	default
title	Common Tasks Quick Reference
permalink	/common-tasks/

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 validate an external codebase without modifying source

Recommended: Sidecar Validation Chain

Command: validate sidecar init → validate sidecar run

Quick Example:

# Initialize sidecar workspace
specfact validate sidecar init legacy-api /path/to/django-project

# Run validation workflow
specfact validate sidecar run legacy-api /path/to/django-project

What it does:

Detects framework (Django, FastAPI, DRF, Flask, pure Python)
Automatically installs dependencies in isolated venv (.specfact/venv/)
Extracts routes and schemas from framework patterns (all HTTP methods captured for Flask)
Populates OpenAPI contracts automatically (with expected status codes and response structure validation)
Generates CrossHair harness for symbolic execution (using venv Python)
Runs CrossHair and Specmatic validation

Detailed Guide: Sidecar Validation Guide

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

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 🆕 NEW FEATURE

I want to integrate SpecFact into my agile DevOps workflows

Recommended: DevOps Adapter Integration - Bidirectional backlog sync

Command: sync bridge --adapter github --bidirectional

Quick Example:

# Export OpenSpec change proposals to GitHub Issues
specfact sync bridge --adapter github --bidirectional \
  --repo-owner your-org --repo-name your-repo

# Import GitHub Issues as change proposals (automatic with --bidirectional)
# Track code changes automatically
specfact sync bridge --adapter github --track-code-changes \
  --repo-owner your-org --repo-name your-repo

Detailed Guide: DevOps Adapter Integration

I want to standardize backlog items using templates

Recommended: Backlog Refinement Guide 🆕 NEW FEATURE - AI-assisted template-driven refinement

Command: backlog refine

Quick Example:

# Refine GitHub issues with auto-detection
specfact backlog refine github --search "is:open label:feature"

# Filter by sprint and assignee
specfact backlog refine github --sprint "Sprint 1" --assignee dev1

# Filter by framework and persona (Scrum + Product Owner)
specfact backlog refine github --framework scrum --persona product-owner --labels feature

# Check Definition of Ready before refinement
specfact backlog refine github --check-dor --labels feature

# Preview refinement without writing (default - safe mode)
specfact backlog refine github --preview --labels feature

# Write refinement to backlog (explicit opt-in)
specfact backlog refine github --write --labels feature

Detailed Guide: Backlog Refinement Guide

I want to refine backlog items in a specific sprint

Recommended: backlog refine with sprint filtering

Command: backlog refine --sprint <sprint-name>

Quick Example:

# Refine items in current sprint
specfact backlog refine github --sprint "Sprint 1" --state open

# Refine ADO work items in specific iteration
specfact backlog refine ado --iteration "Project\\Sprint 1" --state Active

Detailed Guide: Backlog Refinement Guide

I want to use persona-specific templates for backlog refinement

Recommended: backlog refine with persona/framework filtering

Command: backlog refine --persona <persona> --framework <framework>

Quick Example:

# Use Product Owner templates with Scrum framework
specfact backlog refine github --persona product-owner --framework scrum --labels feature

# Use Developer templates with Agile framework
specfact backlog refine github --persona developer --framework agile --labels task

Detailed Guide: Backlog Refinement Guide

I want to check if backlog items are ready for sprint planning

Recommended: backlog refine with DoR validation

Command: backlog refine --check-dor

Quick Example:

# Check DoR before refinement
specfact backlog refine github --check-dor --labels feature

# DoR configuration in .specfact/dor.yaml
rules:
  story_points: true
  priority: true
  business_value: true
  acceptance_criteria: true

Detailed Guide: Backlog Refinement Guide

I want to sync change proposals to GitHub Issues

Recommended: DevOps bridge adapter with bidirectional sync 🆕

Command: sync bridge --adapter github --bidirectional (or --mode export-only for export-only)

Quick Example:

# Bidirectional sync (export AND import)
specfact sync bridge --adapter github --bidirectional \
  --repo-owner your-org --repo-name your-repo

# Export-only (one-way: OpenSpec → GitHub)
specfact sync bridge --adapter github --mode export-only \
  --repo-owner your-org --repo-name your-repo

# Update existing issue (when proposal already linked to issue)
specfact sync bridge --adapter github --mode export-only \
  --repo-owner your-org --repo-name your-repo \
  --change-ids your-change-id \
  --update-existing

Detailed Guide: DevOps Adapter Integration

I want to update an existing GitHub issue with my change proposal

Recommended: Use --update-existing flag with --change-ids to update a specific linked issue

Command: sync bridge --adapter github --mode export-only --update-existing --change-ids <change-id>

Prerequisites:

Change proposal must have source_tracking metadata linking it to the GitHub issue
The issue number should be in the proposal's proposal.md file under "Source Tracking" section

Quick Example:

# Update issue #105 for change proposal 'implement-adapter-enhancement-recommendations'
specfact sync bridge --adapter github --mode export-only \
  --repo-owner nold-ai \
  --repo-name specfact-cli \
  --change-ids implement-adapter-enhancement-recommendations \
  --update-existing \
  --repo /path/to/openspec-repo

What Gets Updated:

Issue body with latest proposal content (if content changed)
Issue title (if proposal title changed)
Status labels (OpenSpec status ↔ GitHub labels)
OpenSpec metadata footer in issue body

Note: The adapter uses content hash detection - if proposal hasn't changed, issue won't be updated (prevents unnecessary API calls).

Detailed Guide: DevOps Adapter Integration - Update Existing Issues

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

FilesExpand file tree

common-tasks.md

Latest commit

History

common-tasks.md

File metadata and controls

Common Tasks Quick Reference

Overview

Getting Started

I want to analyze my legacy code

I want to plan a new feature from scratch

I want to sync with Spec-Kit or OpenSpec

Brownfield Modernization

I want to extract specifications from existing code

I want to review and update extracted features

I want to detect code-spec drift

I want to add contracts to existing code

API Development

I want to validate API contracts

I want to validate an external codebase without modifying source

I want to generate tests from API specifications

I want to create a mock server for API development

Team Collaboration

I want to set up team collaboration

I want to export persona-specific views

I want to manage project versions

Plan Management

I want to promote a plan through stages

I want to compare two plans

Validation & Enforcement

I want to validate everything

I want to enforce SDD compliance

I want to find gaps in my code

AI IDE Integration

I want to set up AI IDE slash commands

I want to generate tests using AI

DevOps Integration 🆕 NEW FEATURE

I want to integrate SpecFact into my agile DevOps workflows

I want to standardize backlog items using templates

I want to refine backlog items in a specific sprint

I want to use persona-specific templates for backlog refinement

I want to check if backlog items are ready for sprint planning

I want to sync change proposals to GitHub Issues

I want to update an existing GitHub issue with my change proposal

I want to track changes in GitHub Projects

Migration & Troubleshooting

I want to migrate from an older version

I want to troubleshoot an issue

See Also