From db990a13ad78a4a3c9802e13305464aec45dec19 Mon Sep 17 00:00:00 2001 From: Dominikus Nold Date: Wed, 18 Mar 2026 00:23:07 +0100 Subject: [PATCH 1/2] fix: align module docs with current CLI surface --- docs/adapters/azuredevops.md | 14 +- docs/adapters/github.md | 8 +- docs/getting-started/README.md | 18 +- docs/getting-started/first-steps.md | 409 +----- docs/getting-started/installation.md | 106 +- .../module-bootstrap-checklist.md | 10 +- .../tutorial-backlog-quickstart-demo.md | 4 +- .../tutorial-backlog-refine-ai-ide.md | 2 +- .../tutorial-daily-standup-sprint-review.md | 8 +- .../tutorial-openspec-speckit.md | 693 +--------- docs/guides/agile-scrum-workflows.md | 2 +- docs/guides/ai-ide-workflow.md | 278 +--- docs/guides/backlog-delta-commands.md | 2 +- docs/guides/backlog-refinement.md | 22 +- docs/guides/brownfield-engineer.md | 374 +----- docs/guides/brownfield-faq.md | 4 +- docs/guides/brownfield-journey.md | 453 +------ docs/guides/command-chains.md | 1116 ++++++----------- docs/guides/common-tasks.md | 632 +--------- docs/guides/competitive-analysis.md | 364 +----- docs/guides/contract-testing-workflow.md | 279 +---- docs/guides/copilot-mode.md | 200 +-- docs/guides/custom-registries.md | 2 +- docs/guides/devops-adapter-integration.md | 110 +- docs/guides/dual-stack-enrichment.md | 353 +----- docs/guides/ide-integration.md | 349 +----- docs/guides/import-features.md | 4 +- docs/guides/installing-modules.md | 28 +- docs/guides/integrations-overview.md | 4 +- docs/guides/migration-0.16-to-0.19.md | 181 +-- docs/guides/migration-cli-reorganization.md | 313 +---- docs/guides/migration-guide.md | 243 +--- docs/guides/module-marketplace.md | 4 +- docs/guides/openspec-journey.md | 24 +- docs/guides/policy-engine-commands.md | 2 +- docs/guides/sidecar-validation.md | 66 +- docs/guides/speckit-comparison.md | 12 +- docs/guides/speckit-journey.md | 548 +------- docs/guides/specmatic-integration.md | 653 +--------- docs/guides/troubleshooting.md | 857 +------------ docs/guides/use-cases.md | 666 +--------- .../using-module-security-and-extensions.md | 146 +-- docs/guides/ux-features.md | 318 +---- docs/guides/workflows.md | 563 +-------- docs/reference/README.md | 13 +- docs/reference/command-syntax-policy.md | 17 +- docs/reference/commands.md | 44 +- docs/reference/debug-logging.md | 191 +-- docs/reference/dependency-resolution.md | 4 +- docs/reference/directory-structure.md | 765 +---------- docs/reference/feature-keys.md | 257 +--- docs/reference/modes.md | 68 +- docs/reference/module-categories.md | 38 +- docs/reference/parameter-standard.md | 258 +--- docs/reference/specmatic.md | 2 +- docs/reference/telemetry.md | 2 +- .../reference/thorough-codebase-validation.md | 30 +- .../docs-cli-command-alignment/.openspec.yaml | 2 + .../TDD_EVIDENCE.md | 38 + .../docs-cli-command-alignment/design.md | 28 + .../docs-cli-command-alignment/proposal.md | 24 + .../specs/modules-docs-publishing/spec.md | 12 + .../docs-cli-command-alignment/tasks.md | 17 + 63 files changed, 1173 insertions(+), 11081 deletions(-) create mode 100644 openspec/changes/docs-cli-command-alignment/.openspec.yaml create mode 100644 openspec/changes/docs-cli-command-alignment/TDD_EVIDENCE.md create mode 100644 openspec/changes/docs-cli-command-alignment/design.md create mode 100644 openspec/changes/docs-cli-command-alignment/proposal.md create mode 100644 openspec/changes/docs-cli-command-alignment/specs/modules-docs-publishing/spec.md create mode 100644 openspec/changes/docs-cli-command-alignment/tasks.md diff --git a/docs/adapters/azuredevops.md b/docs/adapters/azuredevops.md index e765fc1..bd969a2 100644 --- a/docs/adapters/azuredevops.md +++ b/docs/adapters/azuredevops.md @@ -64,7 +64,7 @@ The adapter automatically derives work item type from your project's process tem You can override with `--ado-work-item-type`: ```bash -specfact sync bridge --adapter ado --mode export-only \ +specfact project sync bridge --adapter ado --mode export-only \ --ado-org your-org \ --ado-project your-project \ --ado-work-item-type "Bug" \ @@ -434,7 +434,7 @@ This handles cases where: ```bash # Export OpenSpec change proposals to Azure DevOps work items -specfact sync bridge --adapter ado --mode export-only \ +specfact project sync bridge --adapter ado --mode export-only \ --ado-org your-org \ --ado-project your-project \ --repo /path/to/openspec-repo @@ -444,7 +444,7 @@ specfact sync bridge --adapter ado --mode export-only \ ```bash # Import work items AND export proposals -specfact sync bridge --adapter ado --bidirectional \ +specfact project sync bridge --adapter ado --bidirectional \ --ado-org your-org \ --ado-project your-project \ --repo /path/to/openspec-repo @@ -454,7 +454,7 @@ specfact sync bridge --adapter ado --bidirectional \ ```bash # Import specific work items into bundle -specfact sync bridge --adapter ado --mode bidirectional \ +specfact project sync bridge --adapter ado --mode bidirectional \ --ado-org your-org \ --ado-project your-project \ --bundle main \ @@ -466,7 +466,7 @@ specfact sync bridge --adapter ado --mode bidirectional \ ```bash # Update existing work item with latest proposal content -specfact sync bridge --adapter ado --mode export-only \ +specfact project sync bridge --adapter ado --mode export-only \ --ado-org your-org \ --ado-project your-project \ --change-ids add-feature-x \ @@ -478,7 +478,7 @@ specfact sync bridge --adapter ado --mode export-only \ ```bash # Detect code changes and add progress comments -specfact sync bridge --adapter ado --mode export-only \ +specfact project sync bridge --adapter ado --mode export-only \ --ado-org your-org \ --ado-project your-project \ --track-code-changes \ @@ -490,7 +490,7 @@ specfact sync bridge --adapter ado --mode export-only \ ```bash # Export from bundle to ADO (uses stored lossless content) -specfact sync bridge --adapter ado --mode export-only \ +specfact project sync bridge --adapter ado --mode export-only \ --ado-org your-org \ --ado-project your-project \ --bundle main \ diff --git a/docs/adapters/github.md b/docs/adapters/github.md index c1b28b3..e49f04f 100644 --- a/docs/adapters/github.md +++ b/docs/adapters/github.md @@ -334,14 +334,14 @@ To create a GitHub issue from an OpenSpec change and have the issue number/URL w ```bash # Export one or more changes; creates issues and updates proposal.md Source Tracking -specfact sync bridge --adapter github --mode export-only \ +specfact project sync bridge --adapter github --mode export-only \ --repo . \ --repo-owner nold-ai \ --repo-name specfact-cli \ --change-ids # Example: export backlog-scrum-05-summarize-markdown-output -specfact sync bridge --adapter github --mode export-only \ +specfact project sync bridge --adapter github --mode export-only \ --repo . \ --repo-owner nold-ai \ --repo-name specfact-cli \ @@ -362,7 +362,7 @@ When you improve comment logic or branch detection, use `--include-archived` to ```bash # Update all archived proposals with new comment logic -specfact sync bridge --adapter github --mode export-only \ +specfact project sync bridge --adapter github --mode export-only \ --repo-owner your-org \ --repo-name your-repo \ --include-archived \ @@ -370,7 +370,7 @@ specfact sync bridge --adapter github --mode export-only \ --repo /path/to/openspec-repo # Update specific archived proposal -specfact sync bridge --adapter github --mode export-only \ +specfact project sync bridge --adapter github --mode export-only \ --repo-owner your-org \ --repo-name your-repo \ --change-ids add-code-change-tracking \ diff --git a/docs/getting-started/README.md b/docs/getting-started/README.md index 407a24a..5863369 100644 --- a/docs/getting-started/README.md +++ b/docs/getting-started/README.md @@ -25,7 +25,7 @@ SpecFact runs on a lifecycle-managed module system. ```bash # CLI-only mode (works with uvx, no installation needed) -uvx specfact-cli@latest code import my-project --repo . +uvx specfact-cli@latest code import --repo . my-project # Interactive AI Assistant mode (requires pip install + specfact init) # See First Steps guide for IDE integration setup @@ -34,21 +34,21 @@ uvx specfact-cli@latest code import my-project --repo . **For New Projects**: ```bash -# CLI-only mode (bundle name as positional argument) -uvx specfact-cli@latest plan init my-project --interactive - -# Interactive AI Assistant mode (recommended for better results) -# Requires: pip install specfact-cli && specfact init +# Install a project-oriented bundle first, then inspect the mounted workflow surface +specfact module install nold-ai/specfact-project +specfact project --help ``` **Note**: Interactive AI Assistant mode provides better feature detection and semantic understanding, but requires `pip install specfact-cli` and IDE setup. CLI-only mode works immediately with `uvx` but may show 0 features for simple test cases. ### Migration Note (0.40.0) -Flat root commands were removed. Use grouped command forms: +Flat root commands were removed. Use the mounted grouped command forms: -- `specfact validate ...` -> `specfact validate sidecar ...` -- `specfact plan ...` (old flat shim) -> `specfact plan ...` (project bundle commands) +- `specfact validate ...` -> `specfact code validate ...` +- `specfact code repro ...` -> `specfact code repro ...` +- `specfact sync ...` -> `specfact project sync ...` +- `specfact govern enforce ...` -> `specfact govern enforce ...` - `specfact policy ...` -> `specfact backlog policy ...` First-run bundle selection examples: diff --git a/docs/getting-started/first-steps.md b/docs/getting-started/first-steps.md index 1e45a86..ab95f76 100644 --- a/docs/getting-started/first-steps.md +++ b/docs/getting-started/first-steps.md @@ -4,402 +4,29 @@ title: Your First Steps with SpecFact CLI permalink: /getting-started/first-steps/ --- -# Your First Steps with SpecFact CLI +# Legacy Workflow Note -This guide walks you through your first commands with SpecFact CLI, with step-by-step explanations. +This page described older `specfact plan`, `specfact generate`, `specfact contract`, or `specfact sdd constitution` workflows that are not part of the current public mounted CLI in this repository. The detailed command examples previously documented here were removed because they no longer match the command surface exposed by `specfact --help`. -## Before You Start +Use the current mounted entrypoints instead: -- [Install SpecFact CLI](installation.md) (if not already installed) -- **Python 3.11+ required**: Check with `python3 --version` -- Choose your scenario below +- `specfact project --help` +- `specfact project sync --help` +- `specfact code --help` +- `specfact code review --help` +- `specfact spec --help` +- `specfact govern --help` +- `specfact backlog --help` +- `specfact module --help` -**Installation Options**: - -- **Quick start (CLI-only)**: `uvx specfact-cli@latest --help` (no installation needed) -- **Better results (Interactive)**: `pip install specfact-cli` + `specfact init` (recommended for legacy code) - ---- - -## Scenario 1: Modernizing Legacy Code โญ PRIMARY - -**Goal**: Reverse engineer existing code into documented specs - -**Time**: < 5 minutes - -### Step 1: Analyze Your Legacy Codebase - -**Option A: CLI-only Mode** (Quick start, works with uvx): - -```bash -uvx specfact-cli@latest code import my-project --repo . -``` - -**Option B: Interactive AI Assistant Mode** (Recommended for better results): - -```bash -# Step 1: Install SpecFact CLI -pip install specfact-cli - -# Step 2: Navigate to your project -cd /path/to/your/project - -# Step 3: Initialize IDE integration (one-time) -specfact init ide --ide cursor - -# This creates: -# - .specfact/ directory structure -# - .specfact/templates/backlog/field_mappings/ with default ADO field mapping templates -# - IDE-specific command files for your AI assistant (Cursor in this example) - -# Optional first-run profile for bundle selection -specfact init --profile solo-developer - -# Step 4: Use slash command in IDE chat -/specfact.01-import legacy-api --repo . -# Or let the AI assistant prompt you for bundle name -``` - -**What happens**: - -- **Auto-detects project context**: Language, framework, existing specs, and configuration -- Analyzes all Python files in your repository -- Extracts features, user stories, and business logic from code -- Generates dependency graphs -- Creates project bundle with extracted specs -- **Suggests next steps**: Provides actionable commands based on your project state - -**๐Ÿ’ก Tip**: Use `--help` or `-h` for standard help, or `--help-advanced` (alias: `-ha`) to see all options including advanced configuration. - -**Example output** (Interactive mode - better results): - -```bash -โœ… Analyzed 47 Python files -โœ… Extracted 23 features -โœ… Generated 112 user stories -โฑ๏ธ Completed in 8.2 seconds -``` - -**Example output** (CLI-only mode - may show 0 features for simple cases): - -```bash -โœ… Analyzed 3 Python files -โœ… Extracted 0 features # โš ๏ธ AST-based analysis may miss features in simple code -โœ… Generated 0 user stories -โฑ๏ธ Completed in 2.1 seconds -``` - -**Note**: CLI-only mode uses AST-based analysis which may show 0 features for simple test cases. Interactive AI Assistant mode provides better semantic understanding and feature detection. - -### Step 2: Review Extracted Specs - -```bash -# Review the extracted bundle using CLI commands -specfact plan select - -# Or get structured findings for analysis using the plan compare command -specfact plan compare --bundle my-project -``` - -Review the auto-generated plan to understand what SpecFact discovered about your codebase. - -**Note**: Use CLI commands to interact with bundles. The bundle structure is managed by SpecFact CLI - use commands like `plan review`, `plan add-feature`, `plan update-feature` to work with bundles, not direct file editing. - -**๐Ÿ’ก Tip**: If you plan to sync with Spec-Kit later, the import command will suggest generating a bootstrap constitution. You can also run it manually: - -```bash -specfact sdd constitution bootstrap --repo . -``` - -### Step 3: Find and Fix Gaps - -```bash -# First-time setup: Configure CrossHair for contract exploration -specfact repro setup - -# Analyze and validate your codebase -specfact repro --verbose -``` - -**What happens**: - -- `repro setup` configures CrossHair for contract exploration (one-time setup) -- `repro` runs the full validation suite (linting, type checking, contracts, tests) -- Identifies gaps and issues in your codebase -- Generates enforcement reports that downstream tools (like `generate fix-prompt`) can use - -### Step 4: Use AI to Fix Gaps (New in 0.17+) - -```bash -# Generate AI-ready prompt to fix a specific gap -specfact generate fix-prompt GAP-001 --bundle my-project - -# Generate AI-ready prompt to add tests -specfact generate test-prompt src/auth/login.py -``` - -**What happens**: - -- Creates structured prompt file in `.specfact/prompts/` -- Copy prompt to your AI IDE (Cursor, Copilot, Claude) -- AI generates the fix -- Validate with SpecFact enforcement - -### Step 5: Enforce Contracts - -```bash -# Start in shadow mode (observe only) -specfact enforce stage --preset minimal - -# Validate the codebase -specfact enforce sdd --bundle my-project -``` - -See [Brownfield Engineer Guide](../guides/brownfield-engineer.md) for complete workflow. - ---- - -## Scenario 2: Starting a New Project (Alternative) - -**Goal**: Create a plan before writing code - -**Time**: 5-10 minutes - -### Step 1: Initialize a Plan - -```bash -specfact plan init my-project --interactive -``` - -**What happens**: - -- Creates `.specfact/` directory structure -- Prompts you for project title and description -- Creates modular project bundle at `.specfact/projects/my-project/` -- Copies default ADO field mapping templates to `.specfact/templates/backlog/field_mappings/` for review and customization - -**Example output**: - -```bash -๐Ÿ“‹ Initializing new development plan... - -Enter project title: My Awesome Project -Enter project description: A project to demonstrate SpecFact CLI - -โœ… Plan initialized successfully! -๐Ÿ“ Project bundle: .specfact/projects/my-project/ -``` - -### Step 2: Add Your First Feature - -```bash -specfact plan add-feature \ - --bundle my-project \ - --key FEATURE-001 \ - --title "User Authentication" \ - --outcomes "Users can login securely" -``` - -**What happens**: - -- Adds a new feature to your project bundle -- Creates a feature with key `FEATURE-001` -- Sets the title and outcomes - -### Step 3: Add Stories to the Feature - -```bash -specfact plan add-story \ - --bundle my-project \ - --feature FEATURE-001 \ - --title "As a user, I can login with email and password" \ - --acceptance "Login form validates input" \ - --acceptance "User is redirected after successful login" -``` - -**What happens**: - -- Adds a user story to the feature -- Defines acceptance criteria -- Links the story to the feature - -### Step 4: Validate the Plan - -```bash -specfact repro -``` - -**What happens**: - -- Validates the project bundle structure -- Checks for required fields -- Reports any issues - -**Expected output**: - -```bash -โœ… Plan validation passed -๐Ÿ“Š Features: 1 -๐Ÿ“Š Stories: 1 -``` - -### Next Steps - -- [Use Cases](../guides/use-cases.md) - See real-world examples -- [Command Reference](../reference/commands.md) - Learn all commands -- [IDE Integration](../guides/ide-integration.md) - Set up slash commands - ---- - -## Scenario 3: Migrating from Spec-Kit (Secondary) - -**Goal**: Add automated enforcement to Spec-Kit project - -**Time**: 15-30 minutes - -### Step 1: Preview Migration - -```bash -specfact sync bridge \ - --repo ./my-speckit-project \ - --adapter speckit \ - --dry-run -``` - -**What happens**: - -- Analyzes your Spec-Kit project structure -- Detects Spec-Kit artifacts (specs, plans, tasks, constitution) -- Shows what will be imported -- **Does not modify anything** (dry-run mode) - -**Example output**: - -```bash -๐Ÿ” Analyzing Spec-Kit project... -โœ… Found .specify/ directory (modern format) -โœ… Found specs/001-user-authentication/spec.md -โœ… Found specs/001-user-authentication/plan.md -โœ… Found specs/001-user-authentication/tasks.md -โœ… Found .specify/memory/constitution.md - -๐Ÿ“Š Migration Preview: - - Will create: .specfact/projects// (modular project bundle) - - Will create: .specfact/protocols/workflow.protocol.yaml (if FSM detected) - - Will convert: Spec-Kit features โ†’ SpecFact Feature models - - Will convert: Spec-Kit user stories โ†’ SpecFact Story models - -๐Ÿš€ Ready to migrate (use --write to execute) -``` - -### Step 2: Execute Migration - -```bash -specfact sync bridge \ - --repo ./my-speckit-project \ - --adapter speckit \ - --write -``` - -**What happens**: - -- Imports Spec-Kit artifacts into SpecFact format using bridge architecture -- Creates `.specfact/` directory structure -- Converts Spec-Kit features and stories to SpecFact models -- Creates modular project bundle at `.specfact/projects//` -- Preserves all information - -### Step 3: Review Generated Bundle +When you need exact syntax, verify against live help in the current release, for example: ```bash -# Check bundle status and select active bundle -specfact plan select - -# Compare plan contents -specfact plan compare --bundle +specfact project sync bridge --help +specfact code repro --help +specfact code validate sidecar --help +specfact spec validate --help +specfact govern enforce --help ``` -**What was created**: - -- Modular project bundle at `.specfact/projects//` with multiple aspect files -- `.specfact/protocols/workflow.protocol.yaml` - FSM definition (if protocol detected) -- `.specfact/gates/config.yaml` - Quality gates configuration - -**Note**: Use CLI commands (`plan select`, `plan add-feature`, etc.) to interact with bundles. Do not edit `.specfact` files directly. - -### Step 4: Set Up Bidirectional Sync (Optional) - -Keep Spec-Kit and SpecFact synchronized: - -```bash -# Generate constitution if missing (auto-suggested during sync) -specfact sdd constitution bootstrap --repo . - -# One-time bidirectional sync -specfact sync bridge --adapter speckit --bundle --repo . --bidirectional - -# Continuous watch mode -specfact sync bridge --adapter speckit --bundle --repo . --bidirectional --watch --interval 5 -``` - -**What happens**: - -- **Constitution bootstrap**: Auto-generates constitution from repository analysis (if missing or minimal) -- Syncs changes between Spec-Kit and SpecFact -- Bidirectional: changes in either direction are synced -- Watch mode: continuously monitors for changes -- **Auto-generates all Spec-Kit fields**: When syncing from SpecFact to Spec-Kit, all required fields (frontmatter, INVSEST, Constitution Check, Phases, Technology Stack, Story mappings) are automatically generated - ready for `/speckit.analyze` without manual editing - -### Step 5: Enable Enforcement - -```bash -# Start in shadow mode (observe only) -specfact enforce stage --preset minimal - -# After stabilization, enable warnings -specfact enforce stage --preset balanced - -# For production, enable strict mode -specfact enforce stage --preset strict -``` - -**What happens**: - -- Configures enforcement rules -- Sets severity levels (HIGH, MEDIUM, LOW) -- Defines actions (BLOCK, WARN, LOG) - -### Next Steps for Scenario 3 (Secondary) - -- [The Journey: From Spec-Kit to SpecFact](../guides/speckit-journey.md) - Complete migration guide -- [Use Cases - Spec-Kit Migration](../guides/use-cases.md#use-case-1-github-spec-kit-migration) - Detailed migration workflow -- [Workflows - Bidirectional Sync](../guides/workflows.md#bidirectional-sync) - Keep both tools in sync - ---- - -## Common Questions - -### What if I make a mistake? - -All commands support `--dry-run` or `--shadow-only` flags to preview changes without modifying files. - -### Can I undo changes? - -Yes! SpecFact CLI creates backups and you can use Git to revert changes: - -```bash -git status -git diff -git restore .specfact/ -``` - -### How do I learn more? - -- [Command Reference](../reference/commands.md) - All commands with examples -- [Use Cases](../guides/use-cases.md) - Real-world scenarios -- [Workflows](../guides/workflows.md) - Common daily workflows -- [Troubleshooting](../guides/troubleshooting.md) - Common issues and solutions - ---- - -**Happy building!** ๐Ÿš€ +This page needs a full rewrite around the mounted command groups before task-level workflow examples can be published again. diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index 27ec012..565165a 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -142,10 +142,10 @@ jobs: run: pip install specfact-cli - name: Set up CrossHair Configuration - run: specfact repro setup + run: specfact code repro setup - name: Run Contract Validation - run: specfact repro --verbose --budget 90 + run: specfact code repro --verbose - name: Generate PR Comment if: github.event_name == 'pull_request' @@ -177,7 +177,7 @@ SpecFact CLI supports two operational modes: ```bash # CLI-only mode (uvx - no installation) -uvx specfact-cli@latest code import my-project --repo . +uvx specfact-cli@latest code import --repo . my-project # Interactive mode (pip + specfact init - recommended) # After: pip install specfact-cli && specfact init @@ -198,26 +198,23 @@ Fresh install exposes only core commands: Commands available after bundle installation: - `specfact project ...` -- `specfact plan ...` -- `specfact sync ...` +- `specfact project sync ...` - `specfact backlog ...` - `specfact code ...` -- `specfact analyze ...` -- `specfact drift ...` -- `specfact validate ...` -- `specfact repro ...` +- `specfact code analyze ...` +- `specfact code drift ...` +- `specfact code validate ...` +- `specfact code repro ...` - `specfact spec ...` -- `specfact contract ...` -- `specfact sdd ...` -- `specfact generate ...` -- `specfact enforce ...` +- `specfact govern ...` +- `specfact govern enforce ...` Profile outcomes: | Profile | Installed bundles | Available groups | |---|---|---| | `solo-developer` | `specfact-codebase` | `code` | -| `backlog-team` | `specfact-project`, `specfact-backlog`, `specfact-codebase` | `project`, `backlog`, `code` | +| `backlog-team` | `specfact-project`, `specfact-backlog`, `specfact-codebase` | `project`, `project sync`, `backlog`, `code` | | `api-first-team` | `specfact-spec`, `specfact-codebase` (+`specfact-project` dependency) | `project`, `code`, `spec` | | `enterprise-full-stack` | all five bundles | `project`, `backlog`, `code`, `spec`, `govern` | @@ -240,18 +237,15 @@ specfact init --install all ### For Greenfield Projects -Start a new contract-driven project: +Install the project bundle and inspect the currently mounted project workflow surface: ```bash -specfact plan init --interactive +specfact module install nold-ai/specfact-project +specfact project --help +specfact project sync --help ``` -This will guide you through creating: - -- Initial project idea and narrative -- Product themes and releases -- First features and stories -- Protocol state machine +The mounted `project` group contains the currently supported project-bundle workflows in this release. **With IDE Integration (Interactive AI Assistant Mode):** @@ -266,18 +260,17 @@ cd /path/to/your/project specfact init # Or specify IDE: specfact init ide --ide cursor -# Step 4: Use slash command in IDE chat -/specfact.02-plan init legacy-api -# Or use other plan operations: /specfact.02-plan add-feature --bundle legacy-api --key FEATURE-001 --title "User Auth" +# Step 4: Use the current mounted commands or repo-local slash workflows +specfact project --help +specfact project sync --help ``` **Important**: - Interactive mode automatically uses your IDE workspace -- Slash commands use numbered format: `/specfact.01-import`, `/specfact.02-plan`, etc. -- Commands are numbered for natural workflow progression (01-import โ†’ 02-plan โ†’ 03-review โ†’ 04-sdd โ†’ 05-enforce โ†’ 06-sync) +- Verify repo-local slash workflows against the generated IDE templates in your checkout - No `--repo .` parameter needed in interactive mode (uses workspace automatically) -- The AI assistant will prompt you for bundle names and other inputs if not provided +- Use `specfact project --help`, `specfact code --help`, and `specfact backlog --help` as the source of truth for mounted commands See [IDE Integration Guide](../guides/ide-integration.md) for detailed setup instructions. @@ -286,17 +279,13 @@ See [IDE Integration Guide](../guides/ide-integration.md) for detailed setup ins Convert an existing GitHub Spec-Kit project: ```bash -# Preview what will be migrated -specfact sync bridge --adapter speckit --repo ./my-speckit-project --dry-run - -# Execute migration (one-time import) -specfact sync bridge \ +# Start a one-time import +specfact project sync bridge \ --adapter speckit \ - --repo ./my-speckit-project \ - --write + --repo ./my-speckit-project # Ongoing bidirectional sync (after migration) -specfact sync bridge --adapter speckit --bundle --repo . --bidirectional --watch +specfact project sync bridge --adapter speckit --bundle --repo . --bidirectional --watch ``` **Bidirectional Sync:** @@ -305,13 +294,13 @@ Keep Spec-Kit and SpecFact artifacts synchronized: ```bash # One-time sync -specfact sync bridge --adapter speckit --bundle --repo . --bidirectional +specfact project sync bridge --adapter speckit --bundle --repo . --bidirectional # Continuous watch mode -specfact sync bridge --adapter speckit --bundle --repo . --bidirectional --watch +specfact project sync bridge --adapter speckit --bundle --repo . --bidirectional --watch ``` -**Note**: SpecFact CLI uses a plugin-based adapter registry pattern. All adapters (Spec-Kit, OpenSpec, GitHub, etc.) are registered in `AdapterRegistry` and accessed via `specfact sync bridge --adapter `, making the architecture extensible for future tool integrations. +**Note**: SpecFact CLI uses a plugin-based adapter registry pattern. All adapters (Spec-Kit, OpenSpec, GitHub, etc.) are registered in `AdapterRegistry` and accessed via `specfact project sync bridge --adapter `, making the architecture extensible for future tool integrations. ### For Brownfield Projects @@ -338,8 +327,7 @@ specfact init **Important for IDE Integration**: - Interactive mode automatically uses your IDE workspace (no `--repo .` needed in interactive mode) -- Slash commands use numbered format: `/specfact.01-import`, `/specfact.02-plan`, etc. (numbered for workflow ordering) -- Commands follow natural progression: 01-import โ†’ 02-plan โ†’ 03-review โ†’ 04-sdd โ†’ 05-enforce โ†’ 06-sync +- Verify repo-local slash workflows against the generated IDE templates in your checkout - The AI assistant will prompt you for bundle names and confidence thresholds if not provided - Better feature detection than CLI-only mode (semantic understanding vs AST-only) - **Do NOT use `--mode copilot` with IDE slash commands** - IDE integration automatically provides enhanced prompts @@ -354,9 +342,8 @@ specfact code import my-project \ --report analysis.md # Analyze with CoPilot mode (enhanced prompts - CLI only, not for IDE) -specfact --mode copilot import from-code my-project \ +specfact --mode copilot code import my-project \ --repo ./my-project \ - --confidence 0.7 \ --report analysis.md # Review generated plan @@ -373,10 +360,10 @@ Keep plan artifacts updated as code changes: ```bash # One-time sync -specfact sync repository --repo . --target .specfact +specfact project sync repository --repo . --target .specfact # Continuous watch mode -specfact sync repository --repo . --watch +specfact project sync repository --repo . --watch ``` ## Next Steps @@ -390,16 +377,15 @@ specfact sync repository --repo . --watch - **Python 3.11+ required**: SpecFact CLI requires Python 3.11 or higher - **Start in shadow mode**: Use `--shadow-only` to observe without blocking -- **Use dry-run**: Always preview with `--dry-run` before writing changes - **Check reports**: Generate reports with `--report ` for review - **Progressive enforcement**: Start with `minimal`, move to `balanced`, then `strict` - **CLI-only vs Interactive**: Use `uvx` for quick testing, `pip install + specfact init` for better results - **IDE integration**: Use `specfact init` to set up slash commands in IDE (requires pip install) -- **Slash commands**: Use numbered format `/specfact.01-import`, `/specfact.02-plan`, etc. (numbered for workflow ordering) +- **Slash commands**: Use the IDE templates generated for your checkout and keep them aligned with the mounted CLI surface - **Global flags**: Place `--no-banner` before the command: `specfact --no-banner ` -- **Bridge adapter sync**: Use `sync bridge --adapter ` for external tool integration (Spec-Kit, OpenSpec, GitHub, etc.) -- **Repository sync**: Use `sync repository` for code change tracking -- **Semgrep (optional)**: Install `pip install semgrep` for async pattern detection in `specfact repro` +- **Bridge adapter sync**: Use `project sync bridge --adapter ` for external tool integration (Spec-Kit, OpenSpec, GitHub, etc.) +- **Repository sync**: Use `project sync repository` for code change tracking +- **Semgrep (optional)**: Install `pip install semgrep` for async pattern detection in `specfact code repro` --- @@ -467,19 +453,19 @@ SpecFact CLI automatically detects source directories: ```bash # Hatch project cd /path/to/hatch-project -specfact repro --repo . # Automatically uses "hatch run" for tools +specfact code repro --repo . # Automatically uses "hatch run" for tools # Poetry project cd /path/to/poetry-project -specfact repro --repo . # Automatically uses "poetry run" for tools +specfact code repro --repo . # Automatically uses "poetry run" for tools # UV project cd /path/to/uv-project -specfact repro --repo . # Automatically uses "uv run" for tools +specfact code repro --repo . # Automatically uses "uv run" for tools # Pip project cd /path/to/pip-project -specfact repro --repo . # Uses direct tool invocation +specfact code repro --repo . # Uses direct tool invocation ``` ### External Repository Support @@ -509,17 +495,15 @@ specfact --version specfact --help specfact --help -# Initialize plan (bundle name as positional argument) -specfact plan init my-project --interactive - -# Add feature -specfact plan add-feature --key FEATURE-001 --title "My Feature" +# Inspect currently mounted project workflows +specfact project --help +specfact project sync --help # Validate everything -specfact repro +specfact code repro # Set enforcement level -specfact enforce stage --preset balanced +specfact govern enforce stage --help ``` ## Getting Help diff --git a/docs/getting-started/module-bootstrap-checklist.md b/docs/getting-started/module-bootstrap-checklist.md index f3735a5..c4f8fd8 100644 --- a/docs/getting-started/module-bootstrap-checklist.md +++ b/docs/getting-started/module-bootstrap-checklist.md @@ -55,27 +55,27 @@ This prints a separate bundled table plus install guidance. Install from bundled sources only: ```bash -specfact module install backlog-core --source bundled +specfact module install nold-ai/specfact-backlog --source bundled ``` Install from marketplace only: ```bash -specfact module install specfact/backlog --source marketplace +specfact module install nold-ai/specfact-backlog --source marketplace ``` Install with automatic source resolution (`bundled` first, then marketplace): ```bash -specfact module install backlog +specfact module install nold-ai/specfact-backlog ``` ## 5. Scope-Safe Uninstall ```bash -specfact module uninstall backlog-core --scope user +specfact module uninstall nold-ai/specfact-backlog --scope user # or -specfact module uninstall backlog-core --scope project --repo . +specfact module uninstall nold-ai/specfact-backlog --scope project --repo . ``` If the same module exists in both user and project scope, SpecFact requires explicit `--scope` to prevent accidental removal. diff --git a/docs/getting-started/tutorial-backlog-quickstart-demo.md b/docs/getting-started/tutorial-backlog-quickstart-demo.md index ac38c6c..f305bb0 100644 --- a/docs/getting-started/tutorial-backlog-quickstart-demo.md +++ b/docs/getting-started/tutorial-backlog-quickstart-demo.md @@ -45,7 +45,7 @@ Expected status should show both providers as valid. specfact backlog init-config --force ``` -This creates `.specfact/backlog-config.yaml`. +This creates `.nold-ai/specfact-backlog-config.yaml`. ## 2) Map Fields (ADO) @@ -63,7 +63,7 @@ Notes: - Select the process style intentionally (`--ado-framework scrum|agile|safe|kanban|default`). - Mapping is written to `.specfact/templates/backlog/field_mappings/ado_custom.yaml`. -- Provider context is updated in `.specfact/backlog.yaml`. +- Provider context is updated in `.nold-ai/specfact-backlog.yaml`. Optional reset: diff --git a/docs/getting-started/tutorial-backlog-refine-ai-ide.md b/docs/getting-started/tutorial-backlog-refine-ai-ide.md index 7335eab..c157444 100644 --- a/docs/getting-started/tutorial-backlog-refine-ai-ide.md +++ b/docs/getting-started/tutorial-backlog-refine-ai-ide.md @@ -48,7 +48,7 @@ specfact backlog ceremony refinement github --search "is:open label:feature" --l specfact backlog ceremony refinement github --export-to-tmp --search "is:open label:feature" --limit 5 ``` -**Auto-detect from clone**: When you run from a **GitHub** clone (e.g. `https://github.com/owner/repo` or `git@github.com:owner/repo.git`), SpecFact infers `repo_owner` and `repo_name` from `git remote get-url origin`โ€”no `--repo-owner`/`--repo-name` needed. When you run from an **Azure DevOps** clone (e.g. `https://dev.azure.com/org/project/_git/repo`; SSH keys: `git@ssh.dev.azure.com:v3/org/project/repo`; other SSH: `user@dev.azure.com:v3/org/project/repo`), org and project are inferred. Override with `.specfact/backlog.yaml`, env vars (`SPECFACT_GITHUB_REPO_OWNER`, `SPECFACT_ADO_ORG`, etc.), or CLI options when not in the repo or to override. +**Auto-detect from clone**: When you run from a **GitHub** clone (e.g. `https://github.com/owner/repo` or `git@github.com:owner/repo.git`), SpecFact infers `repo_owner` and `repo_name` from `git remote get-url origin`โ€”no `--repo-owner`/`--repo-name` needed. When you run from an **Azure DevOps** clone (e.g. `https://dev.azure.com/org/project/_git/repo`; SSH keys: `git@ssh.dev.azure.com:v3/org/project/repo`; other SSH: `user@dev.azure.com:v3/org/project/repo`), org and project are inferred. Override with `.nold-ai/specfact-backlog.yaml`, env vars (`SPECFACT_GITHUB_REPO_OWNER`, `SPECFACT_ADO_ORG`, etc.), or CLI options when not in the repo or to override. If you're **not** in a clone, pass adapter context explicitly: diff --git a/docs/getting-started/tutorial-daily-standup-sprint-review.md b/docs/getting-started/tutorial-daily-standup-sprint-review.md index 1ec9746..368f6eb 100644 --- a/docs/getting-started/tutorial-daily-standup-sprint-review.md +++ b/docs/getting-started/tutorial-daily-standup-sprint-review.md @@ -19,7 +19,7 @@ Preferred command path is `specfact backlog ceremony standup ...`. The legacy `s ## What You'll Learn - Run **`specfact backlog ceremony standup`** and see your standup table (assigned + unassigned items) with **auto-detected** GitHub org/repo or Azure DevOps org/project from the git remote -- Use **`.specfact/backlog.yaml`** or environment variables when you're not in the repo (e.g. CI) or to override +- Use **`.nold-ai/specfact-backlog.yaml`** or environment variables when you're not in the repo (e.g. CI) or to override - **Post a standup comment** to the first (or selected) item with `--yesterday`, `--today`, `--blockers` and `--post` - Use **`--interactive`** for step-by-step story review (arrow-key selection, full detail, latest comment + hidden-count hint, and optional in-flow posting on the selected story) - Use **`--copilot-export `** to write a Markdown summary for Copilot slash-command during standup; @@ -65,7 +65,7 @@ specfact backlog ceremony standup ado If you're **not** in a clone (e.g. different directory), use one of: -- **`.specfact/backlog.yaml`** in the project (see [Project backlog context](../guides/devops-adapter-integration.md#project-backlog-context-specfactbacklogyaml)) +- **`.nold-ai/specfact-backlog.yaml`** in the project (see [Project backlog context](../guides/devops-adapter-integration.md#project-backlog-context-specfactbacklogyaml)) - **Environment variables**: `SPECFACT_GITHUB_REPO_OWNER`, `SPECFACT_GITHUB_REPO_NAME` or `SPECFACT_ADO_ORG`, `SPECFACT_ADO_PROJECT` - **CLI options**: `--repo-owner` / `--repo-name` or `--ado-org` / `--ado-project` @@ -202,7 +202,7 @@ supported. Use it with the **`specfact.backlog-daily`** slash prompt for interac | Goal | How | |------|-----| | View standup without typing org/repo | Run `specfact backlog ceremony standup github` or `ado` from **repo root**; org/repo or org/project are **auto-detected** from git remote. | -| Override or use outside repo | Use `.specfact/backlog.yaml`, env vars (`SPECFACT_GITHUB_REPO_OWNER`, etc.), or CLI `--repo-owner`/`--repo-name` or `--ado-org`/`--ado-project`. | +| Override or use outside repo | Use `.nold-ai/specfact-backlog.yaml`, env vars (`SPECFACT_GITHUB_REPO_OWNER`, etc.), or CLI `--repo-owner`/`--repo-name` or `--ado-org`/`--ado-project`. | | Post standup to first item | Use `--yesterday "..."` `--today "..."` `--blockers "..."` and `--post` (values required). | | Post standup while reviewing selected story | Use `--interactive` and choose **Post standup update** from navigation. | | Step through stories with readable comment context | Use `--interactive`; it shows latest comment + hidden-count hint. Use `--first-comments`/`--last-comments` to tune comment density. | @@ -214,5 +214,5 @@ supported. Use it with the **`specfact.backlog-daily`** slash prompt for interac ## Related Documentation - **[Agile/Scrum Workflows](../guides/agile-scrum-workflows.md)** โ€” Daily standup, iteration/sprint, unassigned items, blockers-first -- **[DevOps Adapter Integration](../guides/devops-adapter-integration.md)** โ€” Project backlog context (`.specfact/backlog.yaml`), env vars, **Git fallback (auto-detect from clone)** for GitHub and Azure DevOps +- **[DevOps Adapter Integration](../guides/devops-adapter-integration.md)** โ€” Project backlog context (`.nold-ai/specfact-backlog.yaml`), env vars, **Git fallback (auto-detect from clone)** for GitHub and Azure DevOps - **[Backlog Refinement Guide](../guides/backlog-refinement.md)** โ€” Template-driven refinement (complementary to daily standup) diff --git a/docs/getting-started/tutorial-openspec-speckit.md b/docs/getting-started/tutorial-openspec-speckit.md index 7b79cd1..ee01927 100644 --- a/docs/getting-started/tutorial-openspec-speckit.md +++ b/docs/getting-started/tutorial-openspec-speckit.md @@ -1,686 +1,15 @@ -# Tutorial: Using SpecFact with OpenSpec or Spec-Kit +# Legacy Workflow Note -> **Complete step-by-step guide for new users** -> Learn how to use SpecFact CLI with OpenSpec or Spec-Kit for brownfield code modernization +This page referenced command groups or workflow steps that are no longer part of the current public mounted CLI in this repository. The old examples were removed to avoid directing readers to unavailable commands. -**Time**: 15-30 minutes | **Prerequisites**: Python 3.11+, basic command-line knowledge +Use the current mounted entrypoints instead: -**Note**: This tutorial assumes you're using `specfact` command directly. +- `specfact project --help` +- `specfact project sync --help` +- `specfact code --help` +- `specfact code review --help` +- `specfact spec --help` +- `specfact govern --help` +- `specfact backlog --help` ---- - -## ๐ŸŽฏ What You'll Learn - -By the end of this tutorial, you'll know how to: - -- โœ… Install and set up SpecFact CLI -- โœ… Use SpecFact with OpenSpec for change tracking and DevOps integration -- โœ… Use SpecFact with Spec-Kit for greenfield + brownfield workflows -- โœ… Sync between tools using bridge adapters -- โœ… Export change proposals to GitHub Issues -- โœ… Track implementation progress automatically - ---- - -## ๐Ÿ“‹ Prerequisites - -Before starting, ensure you have: - -- **Python 3.11+** installed (`python3 --version`) -- **Git** installed (`git --version`) -- **Command-line access** (Terminal, PowerShell, or WSL) -- **A GitHub account** (for DevOps integration examples) - -**Optional but recommended:** - -- **OpenSpec CLI** installed (`npm install -g @fission-ai/openspec@latest`) - for OpenSpec workflows -- **VS Code or Cursor** - for IDE integration - ---- - -## ๐Ÿš€ Quick Start: Choose Your Path - -### Path A: Using SpecFact with OpenSpec - -**Best for**: Teams using OpenSpec for specification management and change tracking - -**Use case**: You have OpenSpec change proposals and want to: - -- Export them to GitHub Issues -- Track implementation progress -- Sync OpenSpec specs with code analysis - -๐Ÿ‘‰ **[Jump to OpenSpec Tutorial](#path-a-using-specfact-with-openspec)** - -### Path B: Using SpecFact with Spec-Kit - -**Best for**: Teams using GitHub Spec-Kit for interactive specification authoring - -**Use case**: You have Spec-Kit specs and want to: - -- Add runtime contract enforcement -- Enable team collaboration with shared plans -- Sync Spec-Kit artifacts with SpecFact bundles - -๐Ÿ‘‰ **[Jump to Spec-Kit Tutorial](#path-b-using-specfact-with-spec-kit)** - ---- - -## Path A: Using SpecFact with OpenSpec - -### Step 1: Install SpecFact CLI - -**Option 1: Quick Start (CLI-only)** - -```bash -# No installation needed - works immediately -uvx specfact-cli@latest --help -``` - -**Option 2: Full Installation (Recommended)** - -```bash -# Install SpecFact CLI -pip install specfact-cli - -# Verify installation -specfact --version -``` - -**Expected output**: `specfact-cli, version 0.22.0` - -### Step 2: Set Up Your Project - -**If you already have an OpenSpec project:** - -```bash -# Navigate to your OpenSpec project -cd /path/to/your-openspec-project - -# Verify OpenSpec structure exists -ls openspec/ -# Should show: specs/, changes/, and config.yaml (OPSX); project.md and AGENTS.md are legacy (optional) -``` - -**If you don't have OpenSpec yet:** - -```bash -# Install OpenSpec CLI -npm install -g @fission-ai/openspec@latest - -# Initialize OpenSpec in your project -cd /path/to/your-project -openspec init - -# This creates openspec/ directory structure -``` - -### Step 3: Analyze Your Legacy Code with SpecFact - -**First, extract specs from your existing code:** - -```bash -# Analyze legacy codebase -cd /path/to/your-openspec-project -specfact code import legacy-api --repo . - -# Expected output: -# ๐Ÿ” Analyzing codebase... -# โœ… Analyzed X Python files -# โœ… Extracted Y features -# โœ… Generated Z user stories -# โฑ๏ธ Completed in X seconds -# ๐Ÿ“ Project bundle: .specfact/projects/legacy-api/ -# โœ… Import complete! -``` - -**What this does:** - -- Analyzes your Python codebase -- Extracts features and user stories automatically -- Creates a SpecFact project bundle (`.specfact/projects/legacy-api/`) - -**Note**: If using `hatch run specfact`, run from the specfact-cli directory: -```bash -cd /path/to/specfact-cli -hatch run specfact code import legacy-api --repo /path/to/your-openspec-project -``` - -### Step 4: Create an OpenSpec Change Proposal - -**Create a change proposal in OpenSpec:** - -```bash -# Create change proposal directory -mkdir -p openspec/changes/modernize-api - -# Create proposal.md -cat > openspec/changes/modernize-api/proposal.md << 'EOF' -# Change: Modernize Legacy API - -## Why -Legacy API needs modernization for better performance and maintainability. - -## What Changes -- Refactor API endpoints -- Add contract validation -- Update database schema - -## Impact -- Affected specs: api, database -- Affected code: src/api/, src/db/ -EOF - -# Create tasks.md -cat > openspec/changes/modernize-api/tasks.md << 'EOF' -## Implementation Tasks - -- [ ] Refactor API endpoints -- [ ] Add contract validation -- [ ] Update database schema -- [ ] Add tests -EOF -``` - -### Step 5: Export OpenSpec Proposal to GitHub Issues - -**Export your change proposal to GitHub Issues:** - -```bash -# Export OpenSpec change proposal to GitHub Issues -specfact sync bridge --adapter github --mode export-only \ - --repo-owner your-org \ - --repo-name your-repo \ - --repo /path/to/openspec-repo - -# Expected output: -# โœ… Found change proposal: modernize-api -# โœ… Created GitHub Issue #123: Modernize Legacy API -# โœ… Updated proposal.md with issue tracking -``` - -**What this does:** - -- Reads your OpenSpec change proposal -- Creates a GitHub Issue from the proposal -- Updates the proposal with issue tracking information -- Enables progress tracking - -### Step 6: Track Implementation Progress - -**As you implement changes, track progress automatically:** - -```bash -# Make commits with change ID in commit message -cd /path/to/source-code-repo -git commit -m "feat: modernize-api - refactor endpoints [change:modernize-api]" - -# Track progress (detects commits and adds comments to GitHub Issue) -cd /path/to/openspec-repo -specfact sync bridge --adapter github --mode export-only \ - --repo-owner your-org \ - --repo-name your-repo \ - --track-code-changes \ - --repo . \ - --code-repo /path/to/source-code-repo - -# Expected output: -# โœ… Detected commit: feat: modernize-api - refactor endpoints -# โœ… Added progress comment to Issue #123 -``` - -**Note**: Use `--track-code-changes` flag to enable automatic code change detection. The `--code-repo` option specifies where the source code repository is located (if different from the OpenSpec repo). - -### Step 7: Sync OpenSpec Change Proposals to SpecFact - -**Import OpenSpec change proposals into SpecFact:** - -```bash -# Sync OpenSpec change proposals to SpecFact (read-only) -cd /path/to/openspec-repo -specfact sync bridge --adapter openspec --mode read-only \ - --bundle legacy-api \ - --repo . - -# Expected output: -# โœ… Syncing OpenSpec artifacts (read-only) -# โœ… Found 1 change proposal: modernize-api -# โœ… Synced to SpecFact bundle: legacy-api -# โœ… Change tracking updated -``` - -**What this does:** - -- Reads OpenSpec change proposals from `openspec/changes/` -- Syncs them to SpecFact change tracking -- Enables alignment reports (planned feature) - -**Note**: Currently, OpenSpec adapter sync may show an error about `discover_features` method. This is a known limitation in v0.22.0. The adapter successfully loads change proposals, but alignment report generation may fail. This will be fixed in a future release. - -### Step 8: Add Runtime Contract Enforcement - -**Add contracts to prevent regressions:** - -```bash -# Configure enforcement (global setting, no --bundle or --repo needed) -cd /path/to/your-project -specfact enforce stage --preset balanced - -# Expected output: -# Setting enforcement mode: balanced -# Enforcement Mode: BALANCED -# โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”ณโ”โ”โ”โ”โ”โ”โ”โ”โ”“ -# โ”ƒ Severity โ”ƒ Action โ”ƒ -# โ”กโ”โ”โ”โ”โ”โ”โ”โ”โ•‡โ”โ”โ”โ”โ”โ”โ”โ”โ”ฉ -# โ”‚ HIGH โ”‚ BLOCK โ”‚ -# โ”‚ MEDIUM โ”‚ WARN โ”‚ -# โ”‚ LOW โ”‚ LOG โ”‚ -# โœ… Quality gates configured -``` - -**What this does:** - -- Configures quality gates (global setting for the repository) -- Enables contract enforcement -- Prepares CI/CD integration - -**Note**: `enforce stage` is a global setting and doesn't take `--bundle` or `--repo` options. It configures enforcement for the current repository. - -### Step 9: Archive Completed Change - -**When implementation is complete, archive the change:** - -```bash -# Archive completed change in OpenSpec -openspec archive modernize-api --yes - -# Expected output: -# โœ… Change archived successfully -# โœ… Specs updated in openspec/specs/ -``` - ---- - -## Path B: Using SpecFact with Spec-Kit - -### Step 1: Install SpecFact CLI - -**Option 1: Quick Start (CLI-only)** - -```bash -# No installation needed -uvx specfact-cli@latest --help -``` - -**Option 2: Full Installation (Recommended)** - -```bash -# Install SpecFact CLI -pip install specfact-cli - -# Verify installation -specfact --version -``` - -### Step 2: Set Up Your Spec-Kit Project - -**If you already have a Spec-Kit project:** - -```bash -# Navigate to your Spec-Kit project -cd /path/to/your-speckit-project - -# Verify Spec-Kit structure exists -ls specs/ -# Should show: [###-feature-name]/ directories with spec.md, plan.md, tasks.md -``` - -**If you don't have Spec-Kit yet:** - -```bash -# Spec-Kit is integrated into GitHub Copilot -# Use slash commands in Copilot chat: -# /speckit.specify --feature "User Authentication" -# /speckit.plan --feature "User Authentication" -# /speckit.tasks --feature "User Authentication" -``` - -### Step 3: Preview Spec-Kit Import - -**See what will be imported (safe - no changes):** - -```bash -# Preview import -specfact sync bridge --adapter speckit --repo ./my-speckit-project --dry-run - -# Expected output: -# ๐Ÿ” Analyzing Spec-Kit project via bridge adapter... -# โœ… Found .specify/ directory (modern format) -# โœ… Found specs/001-user-authentication/spec.md -# โœ… Found specs/001-user-authentication/plan.md -# โœ… Found specs/001-user-authentication/tasks.md -# โœ… Found .specify/memory/constitution.md -# -# ๐Ÿ“Š Migration Preview: -# - Will create: .specfact/projects// (modular project bundle) -# - Will create: .specfact/protocols/workflow.protocol.yaml (if FSM detected) -# - Will create: .specfact/gates/config.yaml -# - Will convert: Spec-Kit features โ†’ SpecFact Feature models -# - Will convert: Spec-Kit user stories โ†’ SpecFact Story models -# -# ๐Ÿš€ Ready to migrate (use --write to execute) -``` - -### Step 4: Import Spec-Kit Project - -**Import your Spec-Kit project to SpecFact:** - -```bash -# Execute import -specfact sync bridge \ - --adapter speckit \ - --repo ./my-speckit-project \ - --write - -# Expected output: -# โœ… Parsed Spec-Kit artifacts -# โœ… Generated SpecFact bundle: .specfact/projects// -# โœ… Created quality gates config -# โœ… Preserved Spec-Kit artifacts (original files untouched) -``` - -**What this does:** - -- Parses Spec-Kit artifacts (spec.md, plan.md, tasks.md, constitution.md) -- Generates SpecFact project bundle -- Creates quality gates configuration -- Preserves your original Spec-Kit files - -### Step 5: Review Generated Bundle - -**Review what was created:** - -```bash -# Compare and review project bundle contents -# IMPORTANT: Must be in the project directory where .specfact/ exists -cd /path/to/your-speckit-project -specfact plan compare --bundle - -# Note: Bundle name is typically "main" for Spec-Kit imports -# Check actual bundle name: ls .specfact/projects/ - -# Expected output: -# โœ… Features: 5 -# โœ… Stories: 23 -# โœ… Project bundle compared successfully -``` - -**Note**: -- `plan compare` shows the project bundle summary -- It uses the current directory to find `.specfact/projects/` (no `--repo` option) -- You must be in the project directory where the bundle was created - -### Step 6: Enable Bidirectional Sync - -**Keep Spec-Kit and SpecFact in sync:** - -```bash -# One-time sync (bundle name is typically "main" for Spec-Kit imports) -cd /path/to/my-speckit-project -specfact sync bridge --adapter speckit --bundle main --repo . --bidirectional - -# Continuous watch mode (recommended for team collaboration) -specfact sync bridge --adapter speckit --bundle main --repo . --bidirectional --watch --interval 5 - -# Expected output: -# โœ… Detected speckit repository -# โœ… Constitution found and validated -# โœ… Detected SpecFact structure -# โœ… No conflicts detected -# Sync Summary (Bidirectional): -# - speckit โ†’ SpecFact: Updated 0, Added 0 features -# - SpecFact โ†’ speckit: No features to convert -``` - -**What this does:** - -- **Spec-Kit โ†’ SpecFact**: New specs automatically imported -- **SpecFact โ†’ Spec-Kit**: Changes synced back to Spec-Kit format -- **Team collaboration**: Multiple developers can work together - -**Note**: Replace `main` with your actual bundle name if different. Check with `ls .specfact/projects/` after import. - -### Step 7: Continue Using Spec-Kit Interactively - -**Keep using Spec-Kit slash commands - sync happens automatically:** - -```bash -# In GitHub Copilot chat: -/speckit.specify --feature "Payment Processing" -/speckit.plan --feature "Payment Processing" -/speckit.tasks --feature "Payment Processing" - -# SpecFact automatically syncs (if watch mode enabled) -# โ†’ Detects changes in specs/[###-feature-name]/ -# โ†’ Imports new spec.md, plan.md, tasks.md -# โ†’ Updates .specfact/projects// aspect files -``` - -### Step 8: Add Runtime Contract Enforcement - -**Add contracts to prevent regressions:** - -```bash -# Configure enforcement (global setting, no --bundle or --repo needed) -cd /path/to/my-speckit-project -specfact enforce stage --preset balanced - -# Expected output: -# Setting enforcement mode: balanced -# Enforcement Mode: BALANCED -# โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”ณโ”โ”โ”โ”โ”โ”โ”โ”โ”“ -# โ”ƒ Severity โ”ƒ Action โ”ƒ -# โ”กโ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ•‡โ”โ”โ”โ”โ”โ”โ”โ”โ”ฉ -# โ”‚ HIGH โ”‚ BLOCK โ”‚ -# โ”‚ MEDIUM โ”‚ WARN โ”‚ -# โ”‚ LOW โ”‚ LOG โ”‚ -# โœ… Quality gates configured -``` - -**Note**: `enforce stage` is a global setting and doesn't take `--bundle` or `--repo` options. - -### Step 9: Detect Code vs Plan Drift - -**Compare intended design vs actual implementation:** - -```bash -# Compare code vs plan (use --bundle to specify bundle name) -# IMPORTANT: Must be in the project directory where .specfact/ exists -cd /path/to/my-speckit-project -specfact plan compare --code-vs-plan --bundle - -# Note: Bundle name is typically "main" for Spec-Kit imports -# Check actual bundle name: ls .specfact/projects/ - -# Expected output: -# โœ… Comparing intended design vs actual implementation -# โœ… Found 3 deviations -# โœ… Auto-derived plans from code analysis -``` - -**What this does:** - -- Compares Spec-Kit plans (what you planned) vs code (what's implemented) -- Identifies deviations automatically -- Helps catch drift between design and code - -**Note**: -- `plan compare` takes `--bundle` as an option (not positional) -- It uses the current directory to find bundles (no `--repo` option) -- You must be in the project directory where the bundle was created - ---- - -## ๐ŸŽ“ Key Concepts - -### Bridge Adapters - -**What are bridge adapters?** - -Bridge adapters are plugin-based connectors that sync between SpecFact and external tools (OpenSpec, Spec-Kit, GitHub Issues, etc.). - -**Available adapters:** - -- `openspec` - OpenSpec integration (read-only sync, v0.22.0+) -- `speckit` - Spec-Kit integration (bidirectional sync) -- `github` - GitHub Issues integration (export-only) - -**How to use:** - -```bash -# View available adapters (shown in help text) -specfact sync bridge --help - -# Use an adapter -specfact sync bridge --adapter --mode --bundle --repo . -``` - -**Note**: Adapters are listed in the help text. There's no `--list-adapters` option, but adapters are shown when you use `--help` or when an adapter is not found (error message shows available adapters). - -### Sync Modes - -**Available sync modes:** - -- `read-only` - Import from external tool (no modifications) -- `export-only` - Export to external tool (no imports) -- `bidirectional` - Two-way sync (read and write) -- `unidirectional` - One-way sync (Spec-Kit โ†’ SpecFact only) - -**Which mode to use:** - -- **OpenSpec**: Use `read-only` (v0.22.0+) or `export-only` (GitHub Issues) -- **Spec-Kit**: Use `bidirectional` for team collaboration -- **GitHub Issues**: Use `export-only` for DevOps integration - ---- - -## ๐Ÿ› Troubleshooting - -### Issue: "Adapter not found" - -**Solution:** - -```bash -# View available adapters in help text -specfact sync bridge --help - -# Or check error message when adapter is not found (shows available adapters) -# Should show: openspec, speckit, github, generic-markdown -``` - -### Issue: "No change proposals found" - -**Solution:** - -```bash -# Verify OpenSpec structure -ls openspec/changes/ -# Should show change proposal directories - -# Check proposal.md exists -cat openspec/changes//proposal.md -``` - -### Issue: "Spec-Kit artifacts not found" - -**Solution:** - -```bash -# Verify Spec-Kit structure -ls specs/ -# Should show: [###-feature-name]/ directories - -# Check spec.md exists -cat specs/001-user-authentication/spec.md -``` - -### Issue: "GitHub Issues export failed" - -**Solution:** - -```bash -# Verify GitHub token -export GITHUB_TOKEN=your-token - -# Or use GitHub CLI -gh auth login - -# Verify repository access -gh repo view your-org/your-repo -``` - ---- - -## ๐Ÿ“š Next Steps - -### For OpenSpec Users - -1. **[OpenSpec Journey Guide](../guides/openspec-journey.md)** - Complete integration guide -2. **[DevOps Adapter Integration](../guides/devops-adapter-integration.md)** - GitHub Issues and backlog tracking -3. **[Commands Reference](../reference/commands.md#sync-bridge)** - Complete `sync bridge` documentation - -### For Spec-Kit Users - -1. **[Spec-Kit Journey Guide](../guides/speckit-journey.md)** - Complete integration guide -2. **[Spec-Kit Comparison](../guides/speckit-comparison.md)** - Understand when to use each tool -3. **[Commands Reference](../reference/commands.md#sync-bridge)** - Complete `sync bridge` documentation - -### General Resources - -1. **[Getting Started Guide](README.md)** - Installation and first commands -2. **[Brownfield Engineer Guide](../guides/brownfield-engineer.md)** - Complete brownfield modernization workflow -3. **[Use Cases](../guides/use-cases.md)** - Real-world scenarios - ---- - -## ๐Ÿ’ก Tips & Best Practices - -### For OpenSpec Integration - -- โœ… **Separate repositories**: Keep OpenSpec specs in a separate repo from code -- โœ… **Change proposals**: Use OpenSpec for structured change proposals -- โœ… **DevOps export**: Export proposals to GitHub Issues for team visibility -- โœ… **Progress tracking**: Use `--track-code-changes` to auto-track implementation - -### For Spec-Kit Integration - -- โœ… **Bidirectional sync**: Use `--bidirectional --watch` for team collaboration -- โœ… **Interactive authoring**: Keep using Spec-Kit slash commands -- โœ… **Contract enforcement**: Add SpecFact contracts to critical paths -- โœ… **Drift detection**: Regularly run `plan compare` to catch deviations - -### General Tips - -- โœ… **Start small**: Begin with one feature or change proposal -- โœ… **Use watch mode**: Enable `--watch` for automatic synchronization -- โœ… **Review before sync**: Use `--dry-run` to preview changes -- โœ… **Version control**: Commit SpecFact bundles to version control - ---- - -## ๐Ÿ†˜ Need Help? - -- ๐Ÿ’ฌ [GitHub Discussions](https://github.com/nold-ai/specfact-cli/discussions) -- ๐Ÿ› [GitHub Issues](https://github.com/nold-ai/specfact-cli/issues) -- ๐Ÿ“ง [hello@noldai.com](mailto:hello@noldai.com) -- ๐Ÿ“– [Full Documentation](../README.md) - ---- - -**Happy building!** ๐Ÿš€ - ---- - -Copyright ยฉ 2025-2026 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](../../TRADEMARKS.md) for more information. +For exact syntax, verify against live help in the current release before copying examples. diff --git a/docs/guides/agile-scrum-workflows.md b/docs/guides/agile-scrum-workflows.md index 8a39a0c..0d9db58 100644 --- a/docs/guides/agile-scrum-workflows.md +++ b/docs/guides/agile-scrum-workflows.md @@ -136,7 +136,7 @@ Use **`specfact backlog ceremony standup `** to list your standup items - **GitHub**: When run from a **GitHub** clone (e.g. `https://github.com/owner/repo` or `git@github.com:owner/repo.git`), SpecFact infers `repo_owner` and `repo_name` from `git remote get-url origin`. - **Azure DevOps**: When run from an **ADO** clone (e.g. `https://dev.azure.com/org/project/_git/repo`; SSH keys: `git@ssh.dev.azure.com:v3/org/project/repo`; other SSH: `user@dev.azure.com:v3/org/project/repo`), SpecFact infers `org` and `project` from the remote URL. -Override with `.specfact/backlog.yaml`, environment variables (`SPECFACT_GITHUB_REPO_OWNER`, `SPECFACT_ADO_ORG`, etc.), or CLI options when not in the repo or to override. See [Project backlog context](../guides/devops-adapter-integration.md#project-backlog-context-specfactbacklogyaml). +Override with `.nold-ai/specfact-backlog.yaml`, environment variables (`SPECFACT_GITHUB_REPO_OWNER`, `SPECFACT_ADO_ORG`, etc.), or CLI options when not in the repo or to override. See [Project backlog context](../guides/devops-adapter-integration.md#project-backlog-context-specfactbacklogyaml). ### End-to-End Example: One Standup Session diff --git a/docs/guides/ai-ide-workflow.md b/docs/guides/ai-ide-workflow.md index 196d55b..bae3bb0 100644 --- a/docs/guides/ai-ide-workflow.md +++ b/docs/guides/ai-ide-workflow.md @@ -4,271 +4,29 @@ title: AI IDE Workflow Guide permalink: /ai-ide-workflow/ --- -# AI IDE Workflow Guide +# Legacy Workflow Note -> **Complete guide to using SpecFact CLI with AI IDEs (Cursor, VS Code + Copilot, Claude Code, etc.)** +This page described older `specfact plan`, `specfact generate`, `specfact contract`, or `specfact sdd constitution` workflows that are not part of the current public mounted CLI in this repository. The detailed command examples previously documented here were removed because they no longer match the command surface exposed by `specfact --help`. ---- - -## Overview - -SpecFact CLI integrates with AI-assisted IDEs through slash commands that enable a seamless workflow: **SpecFact finds gaps โ†’ AI IDE fixes them โ†’ SpecFact validates**. This guide explains the complete workflow from setup to validation. - -**Key Benefits**: - -- โœ… **You control the AI** - Use your preferred AI model -- โœ… **SpecFact validates** - Ensure AI-generated code meets contracts -- โœ… **No lock-in** - Works with any AI IDE -- โœ… **CLI-first** - Works offline, no account required - ---- - -## Setup Process - -### Step 1: Initialize IDE Integration - -Run the `init ide` command in your repository: - -```bash -# Auto-detect IDE -specfact init - -# Or specify IDE explicitly -specfact init ide --ide cursor -specfact init ide --ide vscode -specfact init ide --ide copilot - -# Install required packages for contract enhancement -specfact init ide --ide cursor --install-deps -``` - -**What it does**: - -1. Detects your IDE (or uses `--ide` flag) -2. Copies prompt templates from `resources/prompts/` to IDE-specific location -3. Creates/updates IDE settings if needed -4. Makes slash commands available in your IDE -5. Optionally installs required packages (`beartype`, `icontract`, `crosshair-tool`, `pytest`) - -**Related**: [IDE Integration Guide](ide-integration.md) - Complete setup instructions - ---- - -## Available Slash Commands - -Once initialized, the following slash commands are available in your IDE: - -### Core Workflow Commands - -| Slash Command | Purpose | Equivalent CLI Command | -|---------------|---------|------------------------| -| `/specfact.01-import` | Import from codebase | `specfact code import` | -| `/specfact.02-plan` | Plan management | `specfact plan init/add-feature/add-story` | -| `/specfact.03-review` | Review plan | `specfact plan compare` | -| `/specfact.04-sdd` | Create SDD manifest | `specfact enforce sdd` | -| `/specfact.05-enforce` | SDD enforcement | `specfact enforce sdd` | -| `/specfact.06-sync` | Sync operations | `specfact sync bridge` | -| `/specfact.07-contracts` | Contract management | `specfact generate contracts-prompt` | - -### Advanced Commands - -| Slash Command | Purpose | Equivalent CLI Command | -|---------------|---------|------------------------| -| `/specfact.compare` | Compare plans | `specfact plan compare` | -| `/specfact.validate` | Validation suite | `specfact repro` | -| `/specfact.backlog-refine` | Backlog refinement (AI IDE interactive loop) | `specfact backlog refine github \| ado` | - -For an end-to-end tutorial on backlog refine with your AI IDE (story quality, underspecification, DoR, custom templates), see **[Tutorial: Backlog Refine with AI IDE](../getting-started/tutorial-backlog-refine-ai-ide.md)**. - -**Related**: [IDE Integration - Available Slash Commands](ide-integration.md#available-slash-commands) - ---- - -## Complete Workflow: Prompt Generation โ†’ AI IDE โ†’ Validation Loop - -### Workflow Overview - -```mermaid -graph TD - A[SpecFact Analysis] -->|Find Gaps| B[Generate Prompt] - B -->|Copy to IDE| C[AI IDE] - C -->|Generate Fix| D[Apply Changes] - D -->|SpecFact Validate| E[Validation] - E -->|Pass| F[Complete] - E -->|Fail| B -``` - -### Step-by-Step Workflow - -#### 1. Run SpecFact Analysis - -```bash -# Import from codebase -specfact code import my-project --repo . - -# Run validation to find gaps -specfact repro --verbose -``` - -#### 2. Generate AI-Ready Prompt - -```bash -# Generate fix prompt for a specific gap -specfact generate fix-prompt GAP-001 --bundle my-project - -# Or generate contract prompt -specfact generate contracts-prompt --bundle my-project --feature FEATURE-001 - -# Or generate test prompt -specfact generate test-prompt src/auth/login.py --bundle my-project -``` - -#### 3. Use AI IDE to Apply Fixes - -**In Cursor / VS Code / Copilot**: - -1. Open the generated prompt file -2. Copy the prompt content -3. Paste into AI IDE chat -4. AI generates the fix -5. Review and apply the changes - -**Example**: - -```bash -# After generating prompt -cat .specfact/prompts/fix-prompt-GAP-001.md - -# Copy content to AI IDE chat -# AI generates fix -# Apply changes to code -``` - -#### 4. Validate with SpecFact - -```bash -# Check contract coverage -specfact contract coverage --bundle my-project - -# Run validation -specfact repro --verbose - -# Enforce SDD compliance -specfact enforce sdd --bundle my-project -``` - -#### 5. Iterate if Needed - -If validation fails, return to step 2 and generate a new prompt for the remaining issues. - ---- - -## Integration with Command Chains - -The AI IDE workflow integrates with several command chains: - -### AI-Assisted Code Enhancement Chain +Use the current mounted entrypoints instead: -**Workflow**: `generate contracts-prompt` โ†’ [AI IDE] โ†’ `contracts-apply` โ†’ `contract coverage` โ†’ `code repro` +- `specfact project --help` +- `specfact project sync --help` +- `specfact code --help` +- `specfact code review --help` +- `specfact spec --help` +- `specfact govern --help` +- `specfact backlog --help` +- `specfact module --help` -**Related**: [AI-Assisted Code Enhancement Chain](command-chains.md#7-ai-assisted-code-enhancement-chain-emerging) - -### Test Generation from Specifications Chain - -**Workflow**: `generate test-prompt` โ†’ [AI IDE] โ†’ `spec generate-tests` โ†’ `pytest` - -**Related**: [Test Generation from Specifications Chain](command-chains.md#8-test-generation-from-specifications-chain-emerging) - -### Gap Discovery & Fixing Chain - -**Workflow**: `code repro --verbose` โ†’ `generate fix-prompt` โ†’ [AI IDE] โ†’ `govern enforce sdd` - -**Related**: [Gap Discovery & Fixing Chain](command-chains.md#9-gap-discovery--fixing-chain-emerging) - ---- - -## Example: Complete AI IDE Workflow - -### Scenario: Add Contracts to Existing Code +When you need exact syntax, verify against live help in the current release, for example: ```bash -# 1. Analyze codebase -specfact code import legacy-api --repo . - -# 2. Find gaps -specfact repro --verbose - -# 3. Generate contract prompt -specfact generate contracts-prompt --bundle legacy-api --feature FEATURE-001 - -# 4. [In AI IDE] Use slash command or paste prompt -# /specfact.generate-contracts-prompt legacy-api FEATURE-001 -# AI generates contracts -# Apply contracts to code - -# 5. Validate -specfact contract coverage --bundle legacy-api -specfact repro --verbose -specfact enforce sdd --bundle legacy-api -``` - ---- - -## Supported IDEs - -SpecFact CLI supports the following AI IDEs: - -- โœ… **Cursor** - `.cursor/commands/` -- โœ… **VS Code / GitHub Copilot** - `.github/prompts/` + `.vscode/settings.json` -- โœ… **Claude Code** - `.claude/commands/` -- โœ… **Gemini CLI** - `.gemini/commands/` -- โœ… **Qwen Code** - `.qwen/commands/` -- โœ… **opencode** - `.opencode/command/` -- โœ… **Windsurf** - `.windsurf/workflows/` -- โœ… **Kilo Code** - `.kilocode/workflows/` -- โœ… **Auggie** - `.augment/commands/` -- โœ… **Roo Code** - `.roo/commands/` -- โœ… **CodeBuddy** - `.codebuddy/commands/` -- โœ… **Amp** - `.agents/commands/` -- โœ… **Amazon Q Developer** - `.amazonq/prompts/` - -**Related**: [IDE Integration - Supported IDEs](ide-integration.md#supported-ides) - ---- - -## Troubleshooting - -### Slash Commands Not Showing - -**Issue**: Slash commands don't appear in IDE - -**Solution**: - -```bash -# Re-initialize with force -specfact init ide --ide cursor --force +specfact project sync bridge --help +specfact code repro --help +specfact code validate sidecar --help +specfact spec validate --help +specfact govern enforce --help ``` -**Related**: [IDE Integration - Troubleshooting](ide-integration.md#troubleshooting) - ---- - -### AI-Generated Code Fails Validation - -**Issue**: AI-generated code doesn't pass SpecFact validation - -**Solution**: - -1. Review validation errors -2. Generate a new prompt with more specific requirements -3. Re-run AI generation -4. Validate again - ---- - -## See Also - -- [IDE Integration Guide](ide-integration.md) - Complete setup and configuration -- [Command Chains Reference](command-chains.md) - Complete workflows -- [Common Tasks Index](common-tasks.md) - Quick reference -- [Generate Commands Reference](../reference/commands.md#generate---generate-artifacts) - Command documentation +This page needs a full rewrite around the mounted command groups before task-level workflow examples can be published again. diff --git a/docs/guides/backlog-delta-commands.md b/docs/guides/backlog-delta-commands.md index 8850509..b2b484c 100644 --- a/docs/guides/backlog-delta-commands.md +++ b/docs/guides/backlog-delta-commands.md @@ -26,7 +26,7 @@ specfact backlog delta rollback-analysis --project-id --adapter ``` @@ -936,11 +936,11 @@ If adapter search methods are not available: # "Note: GitHub issue fetching requires adapter.search_issues() implementation" ``` -**Workaround**: Use `specfact sync bridge` to import backlog items first, then refine: +**Workaround**: Use `specfact project sync bridge` to import backlog items first, then refine: ```bash # 1. Import backlog items -specfact sync bridge --adapter github --mode bidirectional \ +specfact project sync bridge --adapter github --mode bidirectional \ --backlog-ids 123,456 # 2. Refine imported items from bundle diff --git a/docs/guides/brownfield-engineer.md b/docs/guides/brownfield-engineer.md index 2892782..85301b8 100644 --- a/docs/guides/brownfield-engineer.md +++ b/docs/guides/brownfield-engineer.md @@ -4,370 +4,18 @@ title: Modernizing Legacy Code (Brownfield Engineer Guide) permalink: /brownfield-engineer/ --- -# Guide for Legacy Modernization Engineers +# Legacy Workflow Note -> **Complete walkthrough for modernizing legacy Python code with SpecFact CLI** +This page referenced command groups or workflow steps that are no longer part of the current public mounted CLI in this repository. The old examples were removed to avoid directing readers to unavailable commands. ---- - -## Your Challenge - -You're responsible for modernizing a legacy Python system that: - -- Has minimal or no documentation -- Was built by developers who have left -- Contains critical business logic you can't risk breaking -- Needs migration to modern Python, cloud infrastructure, or microservices - -**Sound familiar?** You're not alone. 70% of IT budgets are consumed by legacy maintenance, and the legacy modernization market is $25B+ and growing. - ---- - -## SpecFact for Brownfield: Your Safety Net - -SpecFact CLI is designed specifically for your situation. It provides: - -1. **Automated spec extraction** (code2spec) - Understand what your code does in < 10 seconds -2. **Runtime contract enforcement** - Prevent regressions during modernization -3. **Symbolic execution** - Discover hidden edge cases with CrossHair -4. **Formal guarantees** - Mathematical verification, not probabilistic LLM suggestions -5. **CLI-first integration** - Works with VS Code, Cursor, GitHub Actions, pre-commit hooks, or any IDE. Works offline, no account required, no vendor lock-in. - ---- - -## Step 1: Understand What You Have - -**CLI-First Approach**: SpecFact works offline, requires no account, and integrates with your existing workflow. Works with VS Code, Cursor, GitHub Actions, pre-commit hooks, or any IDE. No platform to learn, no vendor lock-in. - -### Extract Specs from Legacy Code - -```bash -# Analyze your legacy codebase -specfact code import legacy-api --repo ./legacy-app - -# For large codebases or multi-project repos, analyze specific modules: -specfact code import core-module --repo ./legacy-app --entry-point src/core -specfact code import api-module --repo ./legacy-app --entry-point src/api -``` - -**What you get:** - -- โœ… Auto-generated feature map of existing functionality -- โœ… Extracted user stories from code patterns -- โœ… Dependency graph showing module relationships -- โœ… Business logic documentation from function signatures -- โœ… Edge cases discovered via symbolic execution - -**Example output:** - -```text -โœ… Analyzed 47 Python files -โœ… Extracted 23 features: - - - FEATURE-001: User Authentication (95% confidence) - - FEATURE-002: Payment Processing (92% confidence) - - FEATURE-003: Order Management (88% confidence) - ... -โœ… Generated 112 user stories from existing code patterns -โœ… Detected 6 edge cases with CrossHair symbolic execution -โฑ๏ธ Completed in 8.2 seconds -``` - -**Time saved:** 60-120 hours of manual documentation work โ†’ **8 seconds** - -**๐Ÿ’ก Partial Repository Coverage:** - -For large codebases or monorepos with multiple projects, you can analyze specific subdirectories using `--entry-point`: - -```bash -# Analyze only the core module -specfact code import core-module --repo . --entry-point src/core - -# Analyze only the API service -specfact code import api-service --repo . --entry-point projects/api-service -``` - -This enables: - -- **Faster analysis** - Focus on specific modules for quicker feedback -- **Incremental modernization** - Modernize one module at a time -- **Multi-plan support** - Create separate project bundles for different projects/modules -- **Better organization** - Keep plans organized by project boundaries - -**๐Ÿ’ก Tip**: After importing, the CLI may suggest generating a bootstrap constitution for Spec-Kit integration. This auto-generates a constitution from your repository analysis: - -```bash -# If suggested, accept to auto-generate -# Or run manually: -specfact sdd constitution bootstrap --repo . -``` - -This is especially useful if you plan to sync with Spec-Kit later. - ---- - -## Step 2: Add Contracts to Critical Paths - -### Identify Critical Functions - -SpecFact helps you identify which functions are critical (high risk, high business value): - -```bash -# Review extracted plan to identify critical paths -cat .specfact/projects//bundle.manifest.yaml -``` - -### Add Runtime Contracts - -Add contract decorators to critical functions: - -```python -# Before: Undocumented legacy function -def process_payment(user_id, amount, currency): - # 80 lines of legacy code with hidden business rules - ... - -# After: Contract-enforced function -import icontract - -@icontract.require(lambda amount: amount > 0, "Payment amount must be positive") -@icontract.require(lambda currency: currency in ['USD', 'EUR', 'GBP']) -@icontract.ensure(lambda result: result.status in ['SUCCESS', 'FAILED']) -def process_payment(user_id, amount, currency): - # Same 80 lines of legacy code - # Now with runtime enforcement - ... -``` - -**What this gives you:** - -- โœ… Runtime validation catches invalid inputs immediately -- โœ… Prevents regressions during refactoring -- โœ… Documents expected behavior (executable documentation) -- โœ… CrossHair discovers edge cases automatically - ---- - -## Step 3: Modernize with Confidence - -### Refactor Safely - -With contracts in place, you can refactor knowing that violations will be caught: - -```python -# Refactored version (same contracts) -@icontract.require(lambda amount: amount > 0, "Payment amount must be positive") -@icontract.require(lambda currency: currency in ['USD', 'EUR', 'GBP']) -@icontract.ensure(lambda result: result.status in ['SUCCESS', 'FAILED']) -def process_payment(user_id, amount, currency): - # Modernized implementation - # If contract violated โ†’ exception raised immediately - ... - -``` - -### Catch Regressions Automatically - -```python -# During modernization, accidentally break contract: -process_payment(user_id=-1, amount=-50, currency="XYZ") - -# Runtime enforcement catches it: -# โŒ ContractViolation: Payment amount must be positive (got -50) -# at process_payment() call from refactored checkout.py:142 -# โ†’ Prevented production bug during modernization! -``` - ---- - -## Step 4: Discover Hidden Edge Cases - -### CrossHair Symbolic Execution - -SpecFact uses CrossHair to discover edge cases that manual testing misses: - -```python -# Legacy function with hidden edge case -@icontract.require(lambda numbers: len(numbers) > 0) -@icontract.ensure(lambda numbers, result: len(numbers) == 0 or min(numbers) > result) -def remove_smallest(numbers: List[int]) -> int: - """Remove and return smallest number from list""" - smallest = min(numbers) - numbers.remove(smallest) - return smallest - -# CrossHair finds counterexample: -# Input: [3, 3, 5] โ†’ After removal: [3, 5], min=3, returned=3 -# โŒ Postcondition violated: min(numbers) > result fails when duplicates exist! -# CrossHair generates concrete failing input: [3, 3, 5] -``` - -**Why this matters:** +Use the current mounted entrypoints instead: -- โœ… Discovers edge cases LLMs miss -- โœ… Mathematical proof of violations (not probabilistic) -- โœ… Generates concrete test inputs automatically -- โœ… Prevents production bugs before they happen - ---- - -## Real-World Example: Django Legacy App - -### The Problem - -You inherited a 3-year-old Django app with: - -- No documentation -- No type hints -- No tests -- 15 undocumented API endpoints -- Business logic buried in views - -### The Solution - -```bash -# Step 1: Extract specs -specfact code import customer-portal --repo ./legacy-django-app - -# Output: -โœ… Analyzed 47 Python files -โœ… Extracted 23 features (API endpoints, background jobs, integrations) -โœ… Generated 112 user stories from existing code patterns -โœ… Time: 8 seconds -``` - -### The Results - -- โœ… Legacy app fully documented in < 10 minutes -- โœ… Prevented 4 production bugs during refactoring -- โœ… New developers onboard 60% faster -- โœ… CrossHair discovered 6 hidden edge cases - ---- - -## ROI: Time and Cost Savings - -### Manual Approach - -| Task | Time Investment | Cost (@$150/hr) | -|------|----------------|-----------------| -| Manually document 50-file legacy app | 80-120 hours | $12,000-$18,000 | -| Write tests for undocumented code | 100-150 hours | $15,000-$22,500 | -| Debug regression during refactor | 40-80 hours | $6,000-$12,000 | -| **TOTAL** | **220-350 hours** | **$33,000-$52,500** | - -### SpecFact Automated Approach - -| Task | Time Investment | Cost (@$150/hr) | -|------|----------------|-----------------| -| Run code2spec extraction | 10 minutes | $25 | -| Review and refine extracted specs | 8-16 hours | $1,200-$2,400 | -| Add contracts to critical paths | 16-24 hours | $2,400-$3,600 | -| CrossHair edge case discovery | 2-4 hours | $300-$600 | -| **TOTAL** | **26-44 hours** | **$3,925-$6,625** | - -### ROI: **87% time saved, $26,000-$45,000 cost avoided** - ---- - -## Integration with Your Workflow - -SpecFact CLI integrates seamlessly with your existing tools: - -- **VS Code**: Use pre-commit hooks to catch breaking changes before commit -- **Cursor**: AI assistant workflows catch regressions during refactoring -- **GitHub Actions**: CI/CD integration blocks bad code from merging -- **Pre-commit hooks**: Local validation prevents breaking changes -- **Any IDE**: Pure CLI-first approachโ€”works with any editor - -**See real examples**: [Integration Showcases](../examples/integration-showcases/) - 5 complete examples showing bugs fixed via integrations - -## Best Practices - -### 1. Start with Shadow Mode - -Begin in shadow mode to observe without blocking: - -```bash -specfact code import legacy-api --repo . --shadow-only -``` - -### 2. Add Contracts Incrementally - -Don't try to contract everything at once: - -1. **Week 1**: Add contracts to 3-5 critical functions -2. **Week 2**: Expand to 10-15 functions -3. **Week 3**: Add contracts to all public APIs -4. **Week 4+**: Add contracts to internal functions as needed - -### 3. Use CrossHair for Edge Case Discovery - -Run CrossHair on critical functions before refactoring: - -```bash -hatch run contract-explore src/payment.py -``` - -### 4. Document Your Findings - -Keep notes on: - -- Edge cases discovered -- Contract violations caught -- Time saved on documentation -- Bugs prevented during modernization - ---- - -## Common Questions - -### Can SpecFact analyze code with no docstrings? - -**Yes.** code2spec analyzes: - -- Function signatures and type hints -- Code patterns and control flow -- Existing validation logic -- Module dependencies - -No docstrings needed. - -### What if the legacy code has no type hints? - -**SpecFact infers types** from usage patterns and generates specs. You can add type hints incrementally as part of modernization. - -### Can SpecFact handle obfuscated or minified code? - -**Limited.** SpecFact works best with: - -- Source code (not compiled bytecode) -- Readable variable names - -For heavily obfuscated code, consider deobfuscation first. - -### Will contracts slow down my code? - -**Minimal impact.** Contract checks are fast (microseconds per call). For high-performance code, you can disable contracts in production while keeping them in tests. - ---- - -## Next Steps - -1. **[Integration Showcases](../examples/integration-showcases/)** - See real bugs fixed via VS Code, Cursor, GitHub Actions integrations -2. **[ROI Calculator](brownfield-roi.md)** - Calculate your time and cost savings -3. **[Brownfield Journey](brownfield-journey.md)** - Complete modernization workflow -4. **[Examples](../examples/)** - Real-world brownfield examples -5. **[FAQ](brownfield-faq.md)** - More brownfield-specific questions - ---- - -## Support - -- ๐Ÿ’ฌ [GitHub Discussions](https://github.com/nold-ai/specfact-cli/discussions) -- ๐Ÿ› [GitHub Issues](https://github.com/nold-ai/specfact-cli/issues) -- ๐Ÿ“ง [hello@noldai.com](mailto:hello@noldai.com) - ---- +- `specfact project --help` +- `specfact project sync --help` +- `specfact code --help` +- `specfact code review --help` +- `specfact spec --help` +- `specfact govern --help` +- `specfact backlog --help` -**Happy modernizing!** ๐Ÿš€ +For exact syntax, verify against live help in the current release before copying examples. diff --git a/docs/guides/brownfield-faq.md b/docs/guides/brownfield-faq.md index 25ca714..e0f57d5 100644 --- a/docs/guides/brownfield-faq.md +++ b/docs/guides/brownfield-faq.md @@ -254,7 +254,7 @@ See [Spec-Kit Comparison Guide](speckit-comparison.md) for details. - **GitHub Actions:** PR annotations, contract validation - **GitLab CI:** Pipeline integration - **Jenkins:** Plugin support (planned) -- **Local CI:** Run `specfact enforce` in your pipeline +- **Local CI:** Run `specfact govern enforce` in your pipeline Contracts can block merges if violations are detected (configurable). @@ -272,7 +272,7 @@ Contracts can block merges if violations are detected (configurable). ```bash # .git/hooks/pre-commit #!/bin/sh -uvx specfact-cli@latest enforce stage --preset balanced +uvx specfact-cli@latest govern enforce stage --preset balanced ``` **Example Cursor integration:** diff --git a/docs/guides/brownfield-journey.md b/docs/guides/brownfield-journey.md index 69f2f69..37b13df 100644 --- a/docs/guides/brownfield-journey.md +++ b/docs/guides/brownfield-journey.md @@ -4,449 +4,18 @@ title: Brownfield Modernization Journey permalink: /brownfield-journey/ --- -# Brownfield Modernization Journey +# Legacy Workflow Note -> **Complete step-by-step workflow for modernizing legacy Python code with SpecFact CLI** +This page referenced command groups or workflow steps that are no longer part of the current public mounted CLI in this repository. The old examples were removed to avoid directing readers to unavailable commands. -**CLI-First Approach**: SpecFact works offline, requires no account, and integrates with your existing workflow. Works with VS Code, Cursor, GitHub Actions, pre-commit hooks, or any IDE. No platform to learn, no vendor lock-in. +Use the current mounted entrypoints instead: ---- - -## Overview - -This guide walks you through the complete brownfield modernization journey: - -1. **Understand** - Extract specs from legacy code -2. **Protect** - Add contracts to critical paths -3. **Discover** - Find hidden edge cases -4. **Modernize** - Refactor safely with contract safety net -5. **Validate** - Verify modernization success - -**Time investment:** 26-44 hours (vs. 220-350 hours manual) -**ROI:** 87% time saved, $26,000-$45,000 cost avoided - ---- - -## Phase 1: Understand Your Legacy Code - -### Step 1.1: Extract Specs Automatically - -**CLI-First Integration**: Works with VS Code, Cursor, GitHub Actions, pre-commit hooks, or any IDE. See [Integration Showcases](../examples/integration-showcases/) for real examples. - -```bash -# Analyze your legacy codebase -specfact code import legacy-api --repo ./legacy-app -``` - -**What happens:** - -- SpecFact analyzes all Python files -- Extracts features, user stories, and business logic -- Generates dependency graphs -- Creates project bundle with extracted specs - -**Output:** - -```text -โœ… Analyzed 47 Python files -โœ… Extracted 23 features -โœ… Generated 112 user stories -โฑ๏ธ Completed in 8.2 seconds -``` - -**Time saved:** 60-120 hours of manual documentation โ†’ **8 seconds** - -**๐Ÿ’ก Tip**: After importing, the CLI may suggest generating a bootstrap constitution for Spec-Kit integration. This auto-generates a constitution from your repository analysis: - -```bash -# If suggested, accept to auto-generate -# Or run manually: -specfact sdd constitution bootstrap --repo . -``` - -This is especially useful if you plan to sync with Spec-Kit later. - -### Step 1.2: Review Extracted Specs - -```bash -# Review the extracted plan using CLI commands -specfact plan compare --bundle legacy-api -``` - -**What to look for:** - -- High-confidence features (95%+) - These are well-understood -- Low-confidence features (<70%) - These need manual review -- Missing features - May indicate incomplete extraction -- Edge cases - Already discovered by CrossHair - -### Step 1.3: Validate Extraction Quality - -```bash -# Compare extracted plan to your understanding (bundle directory paths) -specfact plan compare \ - --manual .specfact/projects/manual-plan \ - --auto .specfact/projects/your-project -``` - -**What you get:** - -- Deviations between manual and auto-derived plans -- Missing features in extraction -- Extra features in extraction (may be undocumented functionality) - ---- - -## Phase 2: Protect Critical Paths - -### Step 2.1: Identify Critical Functions - -**Criteria for "critical":** - -- High business value (payment, authentication, data processing) -- High risk (production bugs would be costly) -- Complex logic (hard to understand, easy to break) -- Frequently called (high impact if broken) - -**Review extracted plan:** - -```bash -# Review plan using CLI commands -specfact plan compare --bundle legacy-api -``` - -### Step 2.2: Add Contracts Incrementally - -#### Week 1: Start with 3-5 critical functions - -```python -# Example: Add contracts to payment processing -import icontract - -@icontract.require(lambda amount: amount > 0, "Amount must be positive") -@icontract.require(lambda currency: currency in ['USD', 'EUR', 'GBP']) -@icontract.ensure(lambda result: result.status in ['SUCCESS', 'FAILED']) -def process_payment(user_id, amount, currency): - # Legacy code with contracts - ... -``` - -#### Week 2: Expand to 10-15 functions - -#### Week 3: Add contracts to all public APIs - -#### Week 4+: Add contracts to internal functions as needed - -### Step 2.3: Start in Shadow Mode - -**Shadow mode** observes violations without blocking: - -```bash -# Run in shadow mode (observe only) -specfact enforce stage --preset minimal -``` - -**Benefits:** - -- See violations without breaking workflow -- Understand contract behavior before enforcing -- Build confidence gradually - -**Graduation path:** - -1. **Shadow mode** (Week 1) - Observe only -2. **Warn mode** (Week 2) - Log violations, don't block -3. **Block mode** (Week 3+) - Raise exceptions on violations - ---- - -## Phase 3: Discover Hidden Edge Cases - -### Step 3.1: Run CrossHair on Critical Functions - -```bash -# Discover edge cases in payment processing -hatch run contract-explore src/payment.py -``` - -**What CrossHair does:** - -- Explores all possible code paths symbolically -- Finds inputs that violate contracts -- Generates concrete test cases for violations - -**Example output:** - -```text -โŒ Postcondition violation found: - Function: process_payment - Input: amount=0.0, currency='USD' - Issue: Amount must be positive (got 0.0) - -``` - -### Step 3.2: Fix Discovered Edge Cases - -```python -# Add validation for edge cases -@icontract.require( - lambda amount: amount > 0 and amount <= 1000000, - "Amount must be between 0 and 1,000,000" -) -def process_payment(...): - # Now handles edge cases discovered by CrossHair - ... -``` - -### Step 3.3: Document Edge Cases - -**Keep notes on:** - -- Edge cases discovered -- Contract violations found -- Fixes applied -- Test cases generated - -**Why this matters:** - -- Prevents regressions in future refactoring -- Documents hidden business rules -- Helps new team members understand code - ---- - -## Phase 4: Modernize Safely - -### Step 4.1: Refactor Incrementally - -**One function at a time:** - -1. Add contracts to function (if not already done) -2. Run CrossHair to discover edge cases -3. Refactor function implementation -4. Verify contracts still pass -5. Move to next function - -**Example:** - -```python -# Before: Legacy implementation -@icontract.require(lambda amount: amount > 0) -def process_payment(user_id, amount, currency): - # 80 lines of legacy code - ... - -# After: Modernized implementation (same contracts) -@icontract.require(lambda amount: amount > 0) -def process_payment(user_id, amount, currency): - # Modernized code (same contracts protect behavior) - payment_service = PaymentService() - return payment_service.process(user_id, amount, currency) -``` - -### Step 4.2: Catch Regressions Automatically - -**Contracts catch violations during refactoring:** - -```python -# During modernization, accidentally break contract: -process_payment(user_id=-1, amount=-50, currency="XYZ") - -# Runtime enforcement catches it: -# โŒ ContractViolation: Amount must be positive (got -50) -# โ†’ Fix the bug before it reaches production! - -``` - -### Step 4.3: Verify Modernization Success - -```bash -# Run contract validation -hatch run contract-test-full - -# Check for violations -specfact enforce stage --preset strict -``` - -**Success criteria:** - -- โœ… All contracts pass -- โœ… No new violations introduced -- โœ… Edge cases still handled -- โœ… Performance acceptable - ---- - -## Phase 5: Validate and Measure - -### Step 5.1: Measure ROI - -**Track metrics:** - -- Time saved on documentation -- Bugs prevented during modernization -- Edge cases discovered -- Developer onboarding time reduction - -**Example metrics:** - -- Documentation: 87% time saved (8 hours vs. 60 hours) -- Bugs prevented: 4 production bugs -- Edge cases: 6 discovered automatically -- Onboarding: 60% faster (3-5 days vs. 2-3 weeks) - -### Step 5.2: Document Success - -**Create case study:** - -- Problem statement -- Solution approach -- Quantified results -- Lessons learned - -**Why this matters:** - -- Validates approach for future projects -- Helps other teams learn from your experience -- Builds confidence in brownfield modernization - ---- - -## Real-World Example: Complete Journey - -### The Problem - -Legacy Django app: - -- 47 Python files -- No documentation -- No type hints -- No tests -- 15 undocumented API endpoints - -### The Journey - -#### Week 1: Understand - -- Ran `specfact code import legacy-api --repo .` โ†’ 23 features extracted in 8 seconds -- Reviewed extracted plan โ†’ Identified 5 critical features -- Time: 2 hours (vs. 60 hours manual) - -#### Week 2: Protect - -- Added contracts to 5 critical functions -- Started in shadow mode โ†’ Observed 3 violations -- Time: 16 hours - -#### Week 3: Discover - -- Ran CrossHair on critical functions โ†’ Discovered 6 edge cases -- Fixed edge cases โ†’ Added validation -- Time: 4 hours - -#### Week 4: Modernize - -- Refactored 5 critical functions with contract safety net -- Caught 4 regressions automatically (contracts prevented bugs) -- Time: 24 hours - -#### Week 5: Validate - -- All contracts passing -- No production bugs from modernization -- New developers productive in 3 days (vs. 2-3 weeks) - -### The Results - -- โœ… **87% time saved** on documentation (8 hours vs. 60 hours) -- โœ… **4 production bugs prevented** during modernization -- โœ… **6 edge cases discovered** automatically -- โœ… **60% faster onboarding** (3-5 days vs. 2-3 weeks) -- โœ… **Zero downtime** modernization - -**ROI:** $42,000 saved, 5-week acceleration - ---- - -## Best Practices - -### 1. Start Small - -- Don't try to contract everything at once -- Start with 3-5 critical functions -- Expand incrementally - -### 2. Use Shadow Mode First - -- Observe violations before enforcing -- Build confidence gradually -- Graduate to warn โ†’ block mode - -### 3. Run CrossHair Early - -- Discover edge cases before refactoring -- Fix issues proactively -- Document findings - -### 4. Refactor Incrementally - -- One function at a time -- Verify contracts after each refactor -- Don't rush - -### 5. Document Everything - -- Edge cases discovered -- Contract violations found -- Fixes applied -- Lessons learned - ---- - -## Common Pitfalls - -### โŒ Trying to Contract Everything at Once - -**Problem:** Overwhelming, slows down development - -**Solution:** Start with 3-5 critical functions, expand incrementally - -### โŒ Skipping Shadow Mode - -**Problem:** Too many violations, breaks workflow - -**Solution:** Always start in shadow mode, graduate gradually - -### โŒ Ignoring CrossHair Findings - -**Problem:** Edge cases discovered but not fixed - -**Solution:** Fix edge cases before refactoring - -### โŒ Refactoring Too Aggressively - -**Problem:** Breaking changes, contract violations - -**Solution:** Refactor incrementally, verify contracts after each change - ---- - -## Next Steps - -1. **[Integration Showcases](../examples/integration-showcases/)** - See real bugs fixed via VS Code, Cursor, GitHub Actions integrations -2. **[Brownfield Engineer Guide](brownfield-engineer.md)** - Complete persona guide -3. **[ROI Calculator](brownfield-roi.md)** - Calculate your savings -4. **[Examples](../examples/)** - Real-world brownfield examples -5. **[FAQ](brownfield-faq.md)** - More brownfield questions - ---- - -## Support - -- ๐Ÿ’ฌ [GitHub Discussions](https://github.com/nold-ai/specfact-cli/discussions) -- ๐Ÿ› [GitHub Issues](https://github.com/nold-ai/specfact-cli/issues) -- ๐Ÿ“ง [hello@noldai.com](mailto:hello@noldai.com) - ---- +- `specfact project --help` +- `specfact project sync --help` +- `specfact code --help` +- `specfact code review --help` +- `specfact spec --help` +- `specfact govern --help` +- `specfact backlog --help` -**Happy modernizing!** ๐Ÿš€ +For exact syntax, verify against live help in the current release before copying examples. diff --git a/docs/guides/command-chains.md b/docs/guides/command-chains.md index 9551d79..536734a 100644 --- a/docs/guides/command-chains.md +++ b/docs/guides/command-chains.md @@ -4,759 +4,363 @@ title: Command Chains Reference permalink: /guides/command-chains/ --- -# 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**: - -```bash -# Step 1: Extract specifications from legacy code -specfact code import legacy-api --repo . - -# Step 2: Review the extracted plan -specfact plan compare --bundle legacy-api - -# Step 3: Update features based on review findings -specfact plan update-feature --bundle legacy-api --feature - -# Step 4: Enforce SDD (Spec-Driven Development) compliance -specfact enforce sdd --bundle legacy-api - -# Step 5: Run full validation suite -specfact repro --verbose -``` - -**Workflow Diagram**: - -```mermaid -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 `plan update-feature` to refine them. -- **After `plan review`**: 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 -- Project bundle with features, stories, and acceptance criteria -- SDD-compliant codebase -- Validated contracts and tests - -**Related Guides**: - -- [Brownfield Engineer Guide](brownfield-engineer.md) - Complete walkthrough -- [Brownfield Journey](brownfield-journey.md) - Real-world examples -- [Brownfield FAQ](brownfield-faq.md) - Common questions - ---- - -## 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**: - -```bash -# Step 1: Initialize a new project bundle -specfact plan init new-feature --interactive - -# Step 2: Add features to the plan -specfact plan add-feature --bundle new-feature --name "User Authentication" - -# Step 3: Add user stories to features -specfact plan add-story --bundle new-feature --feature --story "As a user, I want to log in" - -# Step 4: Review the plan for completeness -specfact plan compare --bundle new-feature - -# Step 5: Harden the plan (finalize before implementation) -specfact enforce sdd --bundle new-feature - -# Step 6: Generate contracts from the plan -specfact generate contracts --bundle new-feature - -# Step 7: Enforce SDD compliance -specfact enforce sdd --bundle new-feature -``` - -**Workflow Diagram**: - -```mermaid -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 `plan init`**: Choose interactive mode to get guided prompts, or use flags for automation. -- **After `plan add-feature`**: Add multiple features before adding stories, or add stories immediately. -- **After `plan review`**: If ambiguities are found, add more details or stories before hardening. -- **After `plan harden`**: Once hardened, the plan is locked. Generate contracts before enforcement. - -**Expected Outcomes**: - -- Complete project bundle with features and stories -- Generated contracts ready for implementation -- SDD-compliant plan ready for development - -**Related Guides**: - -- [Agile/Scrum Workflows](agile-scrum-workflows.md) - Persona-based planning -- [Workflows Guide](workflows.md) - General workflow patterns - ---- - -## 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**: - -```bash -# For Code/Spec Adapters (Spec-Kit, OpenSpec, generic-markdown): -# Step 1: Import from external tool via bridge adapter -specfact sync bridge --repo . --adapter speckit --write - -# Step 2: Review the imported plan -specfact plan compare --bundle - -# Step 3: Set up bidirectional sync (optional) -specfact sync bridge --adapter speckit --bundle --bidirectional --watch - -# Step 4: Enforce SDD compliance -specfact enforce sdd --bundle - -# For Backlog Adapters (GitHub Issues, ADO, Linear, Jira) - NEW FEATURE: -# Step 1: Export OpenSpec change proposals to GitHub Issues -specfact 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 sync bridge --adapter github --track-code-changes --repo-owner owner --repo-name repo -``` - -**Workflow Diagram**: - -```mermaid -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 `plan 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**: - -- [Spec-Kit Journey](speckit-journey.md) - Complete Spec-Kit integration guide -- [OpenSpec Journey](openspec-journey.md) - OpenSpec integration guide -- [DevOps Adapter Integration](devops-adapter-integration.md) - GitHub Issues, ADO, Linear, Jira -- [Bridge Adapters Reference](../reference/commands.md#sync-bridge) - Command reference - ---- - -## 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**: - -```bash -# 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: Verify contracts at runtime -specfact contract verify --bundle api-bundle -``` - -**Workflow Diagram**: - -```mermaid -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**: - -- [Specmatic Integration](specmatic-integration.md) - Complete Specmatic guide -- [Contract Testing Workflow](contract-testing-workflow.md) - Contract testing patterns - ---- - -## 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**: - -```bash -# Step 1: Initialize sidecar workspace -specfact validate sidecar init - -# Step 2: Run sidecar validation workflow -specfact validate sidecar run - -# Step 3: Review validation results -# Results are saved to .specfact/projects//reports/sidecar/ -``` - -**Workflow Diagram**: - -```mermaid -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**: - -- [Sidecar Validation Guide](sidecar-validation.md) - Complete sidecar validation walkthrough -- [Command Reference - Validate Commands](../reference/commands.md#validate---validation-commands) - Command reference -- [Framework Detection](../reference/commands.md#framework-detection) - Supported frameworks - ---- - -## 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**: - -```bash -# Step 1: Review the plan before promotion -specfact plan compare --bundle - -# Step 2: Enforce SDD compliance -specfact enforce sdd --bundle - -# Step 3: Promote the plan to next stage -specfact plan select --bundle - -# Step 4: Bump version when releasing -specfact plan upgrade --bundle -``` - -**Workflow Diagram**: - -```mermaid -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 `plan review`**: 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 project bundle - -**Related Guides**: - -- [Agile/Scrum Workflows](agile-scrum-workflows.md) - Stage management -- [Project Version Management](../reference/commands.md#project-version) - Version commands - ---- - -## 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**: - -```bash -# Step 1: Import current code state -specfact code import current-state --repo . - -# Step 2: Compare code against plan -specfact plan compare --bundle --code-vs-plan - -# Step 3: Detect drift -specfact drift detect --bundle - -# Step 4: Sync repository (if drift found) -specfact sync repository --bundle --direction -``` - -**Workflow Diagram**: - -```mermaid -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 `plan 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**: - -- [Drift Detection](../reference/commands.md#drift-detect) - Command reference -- [Plan Comparison](../reference/commands.md#plan-compare) - Comparison options - ---- - -## 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**: - -```bash -# Step 1: Generate contract prompt for AI IDE -specfact generate contracts-prompt --bundle --feature - -# Step 2: [In AI IDE] Use slash command to apply contracts -# /specfact-cli/contracts-apply - -# Step 3: Check contract coverage -specfact contract coverage --bundle - -# Step 4: Run validation -specfact repro --verbose -``` - -**Workflow Diagram**: - -```mermaid -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 generating prompt**: Review the prompt in your AI IDE before applying. -- **Contract coverage**: 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**: - -- [AI IDE Workflow](ai-ide-workflow.md) - Complete AI IDE integration guide -- [IDE Integration](ide-integration.md) - General IDE setup - ---- - -## 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**: - -```bash -# Step 1: Generate test prompt for AI IDE -specfact generate test-prompt --bundle --feature - -# Step 2: [In AI IDE] Use slash command to generate tests -# /specfact-cli/test-generate - -# Step 3: Generate tests from specification -specfact spec generate-tests --spec --output tests/ - -# Step 4: Run tests -pytest tests/ -``` - -**Workflow Diagram**: - -```mermaid -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 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**: - -- [AI IDE Workflow](ai-ide-workflow.md) - AI IDE integration -- [Testing Workflow](contract-testing-workflow.md) - Testing patterns - ---- - -## 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**: - -```bash -# Step 1: Run validation with verbose output -specfact repro --verbose - -# Step 2: Generate fix prompt for discovered gaps -specfact generate fix-prompt --bundle --gap - -# Step 3: [In AI IDE] Use slash command to apply fixes -# /specfact-cli/fix-apply - -# Step 4: Enforce SDD compliance -specfact enforce sdd --bundle -``` - -**Workflow Diagram**: - -```mermaid -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 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**: - -- [AI IDE Workflow](ai-ide-workflow.md) - AI IDE integration -- [Troubleshooting](troubleshooting.md) - Common issues and fixes - ---- - -## 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**: - -```bash -# Step 1: Bootstrap constitution from repository -specfact sdd constitution bootstrap --repo . - -# Step 2: Enrich constitution with repository context -specfact sdd constitution enrich --repo . - -# Step 3: Validate constitution completeness -specfact sdd constitution validate - -# Step 4: List SDD manifests -specfact sdd list -``` - -**Workflow Diagram**: - -```mermaid -graph TD - A[Repository] -->|sdd constitution bootstrap| B[Bootstrap Constitution] - B -->|sdd constitution enrich| C[Enrich Constitution] - C -->|sdd constitution validate| D[Validate Constitution] - D -->|sdd list| E[SDD Manifests] - D -->|Issues Found| C -``` - -**Decision Points**: - -- **Bootstrap vs Enrich**: Use `bootstrap` for new constitutions, `enrich` for existing ones. -- **Validation**: Run validation after bootstrap/enrich to ensure completeness. -- **Spec-Kit Compatibility**: These commands are for Spec-Kit format only. 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**: - -- [Spec-Kit Journey](speckit-journey.md) - Spec-Kit integration -- [SDD Constitution Commands](../reference/commands.md#sdd-constitution---manage-project-constitutions) - Command reference - ---- - -## Orphaned Commands Integration - -The following commands are now integrated into documented workflows: - -### `plan update-idea` - -**Integrated into**: [Greenfield Planning Chain](#2-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](team-collaboration-workflow.md) and [Plan Promotion & Release Chain](#5-plan-promotion--release-chain) - -**When to use**: Team collaboration with persona-based workflows. - -**Workflow**: See [Team Collaboration Workflow](team-collaboration-workflow.md) for complete workflow. - ---- - -### `migrate *` Commands - -**Integrated into**: [Migration Guide](migration-guide.md) - -**When to use**: Migrating between versions or from other tools. - -**Workflow**: See [Migration Guide](migration-guide.md) for decision tree and workflows. - ---- - -### `sdd list` - -**Integrated into**: [SDD Constitution Management Chain](#10-sdd-constitution-management-chain) - -**When to use**: List SDD manifests in repository. - -**Workflow**: Use after constitution management to verify manifests. - ---- - -### `contract verify` - -**Integrated into**: [API Contract Development Chain](#4-api-contract-development-chain) - -**When to use**: Verify contracts at runtime. - -**Workflow**: Use as final step in API Contract Development Chain. - ---- - -## See Also - -- [Common Tasks Index](common-tasks.md) - Quick reference for "How do I X?" questions -- [Command Reference](../reference/commands.md) - Complete command documentation -- [Agile/Scrum Workflows](agile-scrum-workflows.md) - Team collaboration patterns -- [Brownfield Engineer Guide](brownfield-engineer.md) - Legacy modernization guide -- [Sidecar Validation Guide](sidecar-validation.md) - Validate external codebases -- [Spec-Kit Journey](speckit-journey.md) - Spec-Kit integration -- [OpenSpec Journey](openspec-journey.md) - OpenSpec integration -- [Team Collaboration Workflow](team-collaboration-workflow.md) - Team collaboration guide -- [Migration Guide](migration-guide.md) - Migration decision tree +# Legacy Workflow Note + +This page described older SpecFact CLI - v0.42.1 + +โฑ๏ธ Started: 2026-03-18 00:18:23 +Command 'plan' is not installed. +Install workflow bundles with specfact init --profile or specfact +module install . + +โœ“ Finished: 2026-03-18 00:18:23 | Duration: 0.03s, SpecFact CLI - v0.42.1 + +โฑ๏ธ Started: 2026-03-18 00:18:33 +Command 'generate' is not installed. +Install workflow bundles with specfact init --profile or specfact +module install . + +โœ“ Finished: 2026-03-18 00:18:33 | Duration: 0.03s, SpecFact CLI - v0.42.1 + +โฑ๏ธ Started: 2026-03-18 00:18:44 +Command 'contract' is not installed. +Install workflow bundles with specfact init --profile or specfact +module install . + +โœ“ Finished: 2026-03-18 00:18:44 | Duration: 0.03s, or SpecFact CLI - v0.42.1 + +โฑ๏ธ Started: 2026-03-18 00:18:55 +Command 'sdd' is not installed. +Install workflow bundles with specfact init --profile or specfact +module install . + +โœ“ Finished: 2026-03-18 00:18:55 | Duration: 0.02s workflows that are not part of the current public mounted CLI in this repository. The detailed command examples previously documented here were removed because they no longer match the command surface exposed by + Usage: specfact [OPTIONS] COMMAND [ARGS]... + + SpecFact CLI - Spec โ†’ Contract โ†’ Sentinel for Contract-Driven Development + +โ•ญโ”€ Options โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ +โ”‚ --version -v Show version and โ”‚ +โ”‚ exit โ”‚ +โ”‚ --banner Show ASCII art โ”‚ +โ”‚ banner (hidden โ”‚ +โ”‚ by default, โ”‚ +โ”‚ shown on first โ”‚ +โ”‚ run) โ”‚ +โ”‚ --mode TEXT Operational โ”‚ +โ”‚ mode: cicd โ”‚ +โ”‚ (fast, โ”‚ +โ”‚ deterministic) โ”‚ +โ”‚ or copilot โ”‚ +โ”‚ (enhanced, โ”‚ +โ”‚ interactive) โ”‚ +โ”‚ --debug Enable debug โ”‚ +โ”‚ output: console โ”‚ +โ”‚ diagnostics and โ”‚ +โ”‚ log file at โ”‚ +โ”‚ ~/.specfact/logโ€ฆ โ”‚ +โ”‚ (operation โ”‚ +โ”‚ metadata for โ”‚ +โ”‚ file I/O and API โ”‚ +โ”‚ calls) โ”‚ +โ”‚ --skip-checks Skip startup โ”‚ +โ”‚ checks (template โ”‚ +โ”‚ validation and โ”‚ +โ”‚ version check) - โ”‚ +โ”‚ useful for CI/CD โ”‚ +โ”‚ --input-format [yaml|json] Default โ”‚ +โ”‚ structured input โ”‚ +โ”‚ format (yaml or โ”‚ +โ”‚ json) โ”‚ +โ”‚ [default: yaml] โ”‚ +โ”‚ --output-format [yaml|json] Default โ”‚ +โ”‚ structured โ”‚ +โ”‚ output format โ”‚ +โ”‚ for generated โ”‚ +โ”‚ files (yaml or โ”‚ +โ”‚ json) โ”‚ +โ”‚ [default: yaml] โ”‚ +โ”‚ --interactive --no-interactive Force โ”‚ +โ”‚ interaction mode โ”‚ +โ”‚ (default auto โ”‚ +โ”‚ based on โ”‚ +โ”‚ terminal/CI โ”‚ +โ”‚ detection) โ”‚ +โ”‚ --install-compleโ€ฆ Install โ”‚ +โ”‚ completion for โ”‚ +โ”‚ the current โ”‚ +โ”‚ shell. โ”‚ +โ”‚ --show-completion Show completion โ”‚ +โ”‚ for the current โ”‚ +โ”‚ shell, to copy โ”‚ +โ”‚ it or customize โ”‚ +โ”‚ the โ”‚ +โ”‚ installation. โ”‚ +โ”‚ --help,--help-adโ€ฆ -h,-ha Show this โ”‚ +โ”‚ message and โ”‚ +โ”‚ exit. โ”‚ +โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ +โ•ญโ”€ Commands โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ +โ”‚ init Bootstrap SpecFact and manage module lifecycle (use `init ide` for โ”‚ +โ”‚ IDE setup) โ”‚ +โ”‚ module Manage marketplace modules (install, uninstall, search, list, โ”‚ +โ”‚ show, upgrade) โ”‚ +โ”‚ upgrade Check for and install SpecFact CLI updates โ”‚ +โ”‚ backlog Module package: nold-ai/specfact-backlog โ”‚ +โ”‚ code Module package: nold-ai/specfact-codebase โ”‚ +โ”‚ govern Module package: nold-ai/specfact-govern โ”‚ +โ”‚ project Module package: nold-ai/specfact-project โ”‚ +โ”‚ spec Module package: nold-ai/specfact-spec โ”‚ +โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ. + +Use the current mounted entrypoints instead: + +- +โฑ๏ธ Started: 2026-03-18 00:19:19 + + Usage: specfact project [OPTIONS] COMMAND [ARGS]... + + Manage project bundles with persona workflows + +โ•ญโ”€ Options โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ +โ”‚ --install-completion Install completion for the current โ”‚ +โ”‚ shell. โ”‚ +โ”‚ --show-completion Show completion for the current shell, โ”‚ +โ”‚ to copy it or customize the โ”‚ +โ”‚ installation. โ”‚ +โ”‚ --help-advanced,--help -ha,-h Show this message and exit. โ”‚ +โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ +โ•ญโ”€ Commands โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ +โ”‚ link-backlog Link a project bundle to a backlog provider โ”‚ +โ”‚ configuration. โ”‚ +โ”‚ health-check Run project-level health checks including backlog graph โ”‚ +โ”‚ health. โ”‚ +โ”‚ devops-flow Run integrated DevOps stage actions for a project bundle. โ”‚ +โ”‚ snapshot Save current linked backlog graph as baseline snapshot. โ”‚ +โ”‚ regenerate Re-derive plan state from current bundle and linked โ”‚ +โ”‚ backlog graph. โ”‚ +โ”‚ export-roadmap Export roadmap milestones from backlog dependency โ”‚ +โ”‚ critical path. โ”‚ +โ”‚ export Export persona-owned sections from project bundle to โ”‚ +โ”‚ Markdown. โ”‚ +โ”‚ import Import persona-edited Markdown file back into project โ”‚ +โ”‚ bundle. โ”‚ +โ”‚ lock Lock a section for a persona. โ”‚ +โ”‚ unlock Unlock a section. โ”‚ +โ”‚ locks List all section locks. โ”‚ +โ”‚ init-personas Initialize personas in project bundle manifest. โ”‚ +โ”‚ merge Merge project bundles using three-way merge with โ”‚ +โ”‚ persona-aware conflict resolution. โ”‚ +โ”‚ resolve-conflict Resolve a specific conflict in a project bundle. โ”‚ +โ”‚ version Manage project bundle versions โ”‚ +โ”‚ sync Synchronize external tool artifacts and repository โ”‚ +โ”‚ changes (Spec-Kit, OpenSpec, GitHub, Linear, Jira, etc.). โ”‚ +โ”‚ See 'specfact backlog refine' for template-driven backlog โ”‚ +โ”‚ refinement. โ”‚ +โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ + + + +โœ“ Finished: 2026-03-18 00:19:19 | Duration: 0.39s +- +โฑ๏ธ Started: 2026-03-18 00:19:30 + + Usage: specfact project sync [OPTIONS] COMMAND [ARGS]... + + Synchronize external tool artifacts and repository changes (Spec-Kit, + OpenSpec, GitHub, Linear, Jira, etc.). See 'specfact backlog refine' for + template-driven backlog refinement. + +โ•ญโ”€ Options โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ +โ”‚ --help,--help-advanced -h,-ha Show this message and exit. โ”‚ +โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ +โ•ญโ”€ Commands โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ +โ”‚ bridge Sync changes between external tool artifacts and SpecFact โ”‚ +โ”‚ using bridge architecture. โ”‚ +โ”‚ repository Sync code changes to SpecFact artifacts. โ”‚ +โ”‚ intelligent Continuous intelligent bidirectional sync with conflict โ”‚ +โ”‚ resolution. โ”‚ +โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ + + +โœ“ Finished: 2026-03-18 00:19:31 | Duration: 0.31s +- +โฑ๏ธ Started: 2026-03-18 00:19:43 + + Usage: specfact code [OPTIONS] COMMAND [ARGS]... + + Code command extensions for structured review workflows. + +โ•ญโ”€ Options โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ +โ”‚ --install-completion Install completion for the current โ”‚ +โ”‚ shell. โ”‚ +โ”‚ --show-completion Show completion for the current shell, โ”‚ +โ”‚ to copy it or customize the โ”‚ +โ”‚ installation. โ”‚ +โ”‚ --help-advanced,--help -h,-ha Show this message and exit. โ”‚ +โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ +โ•ญโ”€ Commands โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ +โ”‚ review Governed code review workflows. โ”‚ +โ”‚ import Import codebases and related external inputs into SpecFact โ”‚ +โ”‚ project bundles. โ”‚ +โ”‚ analyze Analyze codebase for contract coverage and quality โ”‚ +โ”‚ drift Detect drift between code and specifications โ”‚ +โ”‚ validate Validation commands โ”‚ +โ”‚ repro Run validation suite for reproducibility โ”‚ +โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ + + + +โœ“ Finished: 2026-03-18 00:19:45 | Duration: 1.16s +- +โฑ๏ธ Started: 2026-03-18 00:19:55 + + Usage: specfact code review [OPTIONS] COMMAND [ARGS]... + + Governed code review workflows. + +โ•ญโ”€ Options โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ +โ”‚ --help-advanced,--help -h,-ha Show this message and exit. โ”‚ +โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ +โ•ญโ”€ Commands โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ +โ”‚ run Execute code review runs. โ”‚ +โ”‚ ledger Persist and inspect review reward history. โ”‚ +โ”‚ rules Manage the code-review house-rules skill. โ”‚ +โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ + + +โœ“ Finished: 2026-03-18 00:19:56 | Duration: 0.64s +- +โฑ๏ธ Started: 2026-03-18 00:20:05 + + Usage: specfact spec [OPTIONS] COMMAND [ARGS]... + + Specmatic integration for API contract testing (OpenAPI/AsyncAPI validation, + backward compatibility, mock servers) + +โ•ญโ”€ Options โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ +โ”‚ --install-completion Install completion for the current โ”‚ +โ”‚ shell. โ”‚ +โ”‚ --show-completion Show completion for the current shell, โ”‚ +โ”‚ to copy it or customize the โ”‚ +โ”‚ installation. โ”‚ +โ”‚ --help-advanced,--help -h,-ha Show this message and exit. โ”‚ +โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ +โ•ญโ”€ Commands โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ +โ”‚ validate Validate OpenAPI/AsyncAPI specification using Specmatic. โ”‚ +โ”‚ backward-compat Check backward compatibility between two spec versions. โ”‚ +โ”‚ generate-tests Generate Specmatic test suite from specification. โ”‚ +โ”‚ mock Launch Specmatic mock server from specification. โ”‚ +โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ + + + +โœ“ Finished: 2026-03-18 00:20:06 | Duration: 0.35s +- +โฑ๏ธ Started: 2026-03-18 00:20:16 + + Usage: specfact govern [OPTIONS] COMMAND [ARGS]... + + Governance and quality gates: enforce, patch. + +โ•ญโ”€ Options โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ +โ”‚ --install-completion Install completion for the current โ”‚ +โ”‚ shell. โ”‚ +โ”‚ --show-completion Show completion for the current shell, โ”‚ +โ”‚ to copy it or customize the โ”‚ +โ”‚ installation. โ”‚ +โ”‚ --help,--help-advanced -h,-ha Show this message and exit. โ”‚ +โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ +โ•ญโ”€ Commands โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ +โ”‚ enforce Configure quality gates and enforcement modes โ”‚ +โ”‚ patch Preview and apply patches (local or upstream with --write). โ”‚ +โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ + + + +โœ“ Finished: 2026-03-18 00:20:17 | Duration: 0.55s +- +โฑ๏ธ Started: 2026-03-18 00:20:29 + + Usage: specfact backlog [OPTIONS] COMMAND [ARGS]... + + Backlog refinement and template management + +โ•ญโ”€ Options โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ +โ”‚ --install-completion Install completion for the current โ”‚ +โ”‚ shell. โ”‚ +โ”‚ --show-completion Show completion for the current shell, โ”‚ +โ”‚ to copy it or customize the โ”‚ +โ”‚ installation. โ”‚ +โ”‚ --help,--help-advanced -ha,-h Show this message and exit. โ”‚ +โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ +โ•ญโ”€ Commands โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ +โ”‚ ceremony Ceremony-oriented backlog workflows โ”‚ +โ”‚ delta Backlog delta analysis and impact tracking โ”‚ +โ”‚ auth Authenticate backlog providers โ”‚ +โ”‚ sync Sync current backlog graph with stored baseline and โ”‚ +โ”‚ export delta outputs. โ”‚ +โ”‚ verify-readiness Verify release readiness for selected backlog items. โ”‚ +โ”‚ analyze-deps Analyze backlog dependencies for a project. โ”‚ +โ”‚ diff Show changes since baseline sync. โ”‚ +โ”‚ promote Validate promotion impact for an item and print promotion โ”‚ +โ”‚ intent. โ”‚ +โ”‚ refine Refine backlog items using AI-assisted template matching. โ”‚ +โ”‚ daily Show daily standup view: list my/filtered backlog items โ”‚ +โ”‚ with status and last activity. โ”‚ +โ”‚ init-config Scaffold `.specfact/backlog-config.yaml` with default โ”‚ +โ”‚ backlog provider config structure. โ”‚ +โ”‚ map-fields Interactive command to map ADO fields to canonical field โ”‚ +โ”‚ names. โ”‚ +โ”‚ add Create a backlog item with optional parent hierarchy โ”‚ +โ”‚ validation and DoR checks. โ”‚ +โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ + + + +โœ“ Finished: 2026-03-18 00:20:30 | Duration: 1.56s +- +โฑ๏ธ Started: 2026-03-18 00:20:42 + + Usage: specfact module [OPTIONS] COMMAND [ARGS]... + + Manage marketplace modules + +โ•ญโ”€ Options โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ +โ”‚ --install-completion Install completion for the current โ”‚ +โ”‚ shell. โ”‚ +โ”‚ --show-completion Show completion for the current shell, โ”‚ +โ”‚ to copy it or customize the โ”‚ +โ”‚ installation. โ”‚ +โ”‚ --help,--help-advanced -h,-ha Show this message and exit. โ”‚ +โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ +โ•ญโ”€ Commands โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ +โ”‚ init Bootstrap shipped module artifacts into user or project โ”‚ +โ”‚ module root. โ”‚ +โ”‚ install Install a module from bundled artifacts or marketplace โ”‚ +โ”‚ registry. โ”‚ +โ”‚ uninstall Uninstall a marketplace module. โ”‚ +โ”‚ add-registry Add a custom registry to the config. โ”‚ +โ”‚ list-registries List all configured registries (official + custom). โ”‚ +โ”‚ remove-registry Remove a custom registry from the config. โ”‚ +โ”‚ enable Enable modules in lifecycle state registry. โ”‚ +โ”‚ disable Disable modules in lifecycle state registry. โ”‚ +โ”‚ search Search marketplace and installed modules by โ”‚ +โ”‚ id/description/tags. โ”‚ +โ”‚ list List installed modules with trust labels and optional โ”‚ +โ”‚ origin details. โ”‚ +โ”‚ show Show detailed metadata for an installed module. โ”‚ +โ”‚ upgrade Upgrade marketplace module(s) to latest available โ”‚ +โ”‚ versions. โ”‚ +โ”‚ alias Manage command aliases (map name to namespaced module) โ”‚ +โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ + + + +โœ“ Finished: 2026-03-18 00:20:42 | Duration: 0.47s + +When you need exact syntax, verify against live help in the current release, for example: + + + +This page needs a full rewrite around the mounted command groups before task-level workflow examples can be published again. diff --git a/docs/guides/common-tasks.md b/docs/guides/common-tasks.md index 1c6f87b..94b2f53 100644 --- a/docs/guides/common-tasks.md +++ b/docs/guides/common-tasks.md @@ -4,625 +4,29 @@ title: Common Tasks Quick Reference permalink: /common-tasks/ --- -# Common Tasks Quick Reference +# Legacy Workflow Note -> **Quick answers to "How do I X?" questions** +This page described older `specfact plan`, `specfact generate`, `specfact contract`, or `specfact sdd constitution` workflows that are not part of the current public mounted CLI in this repository. The detailed command examples previously documented here were removed because they no longer match the command surface exposed by `specfact --help`. ---- - -## 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](command-chains.md#when-to-use-which-chain) to find the right workflow. - ---- - -## Getting Started - -### I want to analyze my legacy code - -**Recommended**: [Brownfield Modernization Chain](command-chains.md#1-brownfield-modernization-chain) - -**Command**: `import from-code` - -**Quick Example**: - -```bash -specfact code import legacy-api --repo . -``` - -**Detailed Guide**: [Brownfield Engineer Guide](brownfield-engineer.md) - ---- - -### I want to plan a new feature from scratch - -**Recommended**: [Greenfield Planning Chain](command-chains.md#2-greenfield-planning-chain) - -**Command**: `plan init` โ†’ `plan add-feature` โ†’ `plan add-story` - -**Quick Example**: +Use the current mounted entrypoints instead: -```bash -specfact plan init new-feature --interactive -specfact plan add-feature --bundle new-feature --name "User Authentication" -specfact plan add-story --bundle new-feature --feature --story "As a user, I want to log in" -``` - -**Detailed Guide**: [Agile/Scrum Workflows](agile-scrum-workflows.md) - ---- - -### I want to sync with Spec-Kit or OpenSpec +- `specfact project --help` +- `specfact project sync --help` +- `specfact code --help` +- `specfact code review --help` +- `specfact spec --help` +- `specfact govern --help` +- `specfact backlog --help` +- `specfact module --help` -**Recommended**: [External Tool Integration Chain](command-chains.md#3-external-tool-integration-chain) - -**Command**: `sync bridge` - -**Quick Example**: +When you need exact syntax, verify against live help in the current release, for example: ```bash -specfact sync bridge --repo . --adapter speckit --write -specfact sync bridge --adapter speckit --bundle --bidirectional --watch +specfact project sync bridge --help +specfact code repro --help +specfact code validate sidecar --help +specfact spec validate --help +specfact govern enforce --help ``` -**Detailed Guide**: [Spec-Kit Journey](speckit-journey.md) | [OpenSpec Journey](openspec-journey.md) - ---- - -## Brownfield Modernization - -### I want to extract specifications from existing code - -**Recommended**: `import from-code` - -**Quick Example**: - -```bash -specfact code import legacy-api --repo ./legacy-app -``` - -**Detailed Guide**: [Brownfield Engineer Guide](brownfield-engineer.md#step-1-understand-what-you-have) - ---- - -### I want to review and update extracted features - -**Recommended**: `plan compare` โ†’ `plan update-feature` - -**Quick Example**: - -```bash -specfact plan compare --bundle legacy-api -specfact plan update-feature --bundle legacy-api --feature -``` - -**Detailed Guide**: [Brownfield Engineer Guide](brownfield-engineer.md#step-2-refine-your-plan) - ---- - -### I want to detect code-spec drift - -**Recommended**: [Code-to-Plan Comparison Chain](command-chains.md#6-code-to-plan-comparison-chain) - -**Command**: `plan compare` โ†’ `drift detect` - -**Quick Example**: - -```bash -specfact code import current-state --repo . -specfact plan compare --bundle --code-vs-plan -specfact drift detect --bundle -``` - -**Detailed Guide**: [Drift Detection](../reference/commands.md#drift-detect) - ---- - -### I want to add contracts to existing code - -**Recommended**: [AI-Assisted Code Enhancement Chain](command-chains.md#7-ai-assisted-code-enhancement-chain-emerging) - -**Command**: `generate contracts-prompt` โ†’ [AI IDE] โ†’ `contracts-apply` - -**Quick Example**: - -```bash -specfact generate contracts-prompt --bundle --feature -# Then use AI IDE slash command: /specfact-cli/contracts-apply -specfact contract coverage --bundle -``` - -**Detailed Guide**: [AI IDE Workflow](ai-ide-workflow.md) - ---- - -## API Development - -### I want to validate API contracts - -**Recommended**: [API Contract Development Chain](command-chains.md#4-api-contract-development-chain) - -**Command**: `spec validate` โ†’ `spec backward-compat` - -**Quick Example**: - -```bash -specfact spec validate --spec openapi.yaml -specfact spec backward-compat --spec openapi.yaml --previous-spec openapi-v1.yaml -``` - -**Detailed Guide**: [Specmatic Integration](specmatic-integration.md) - ---- - -### I want to validate an external codebase without modifying source - -**Recommended**: [Sidecar Validation Chain](command-chains.md#5-sidecar-validation-chain) - -**Command**: `validate sidecar init` โ†’ `validate sidecar run` - -**Quick Example**: - -```bash -# 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](sidecar-validation.md) - ---- - -### I want to generate tests from API specifications - -**Recommended**: `spec generate-tests` - -**Quick Example**: - -```bash -specfact spec generate-tests --spec openapi.yaml --output tests/ -pytest tests/ -``` - -**Detailed Guide**: [Contract Testing Workflow](contract-testing-workflow.md) - ---- - -### I want to create a mock server for API development - -**Recommended**: `spec mock` - -**Quick Example**: - -```bash -specfact spec mock --spec openapi.yaml --port 8080 -``` - -**Detailed Guide**: [Specmatic Integration](specmatic-integration.md) - ---- - -## Team Collaboration - -### I want to set up team collaboration - -**Recommended**: [Team Collaboration Workflow](team-collaboration-workflow.md) - -**Command**: `project export` โ†’ `project import` โ†’ `project lock/unlock` - -**Quick Example**: - -```bash -specfact project init-personas --bundle -specfact project export --bundle --persona product-owner -# Edit exported Markdown files -specfact project import --bundle --persona product-owner --source exported-plan.md -``` - -**Detailed Guide**: [Agile/Scrum Workflows](agile-scrum-workflows.md) - ---- - -### I want to export persona-specific views - -**Recommended**: `project export` - -**Quick Example**: - -```bash -specfact project export --bundle --persona product-owner -specfact project export --bundle --persona architect -specfact project export --bundle --persona developer -``` - -**Detailed Guide**: [Agile/Scrum Workflows](agile-scrum-workflows.md#persona-based-workflows) - ---- - -### I want to manage project versions - -**Recommended**: `project version check` โ†’ `project version bump` - -**Quick Example**: - -```bash -specfact project version check --bundle -specfact project version bump --bundle --type minor -``` - -**Detailed Guide**: [Project Version Management](../reference/commands.md#project-version) - ---- - -## Plan Management - -### I want to promote a plan through stages - -**Recommended**: [Plan Promotion & Release Chain](command-chains.md#5-plan-promotion--release-chain) - -**Command**: `plan compare` โ†’ `enforce sdd` โ†’ `plan select` - -**Quick Example**: - -```bash -specfact plan compare --bundle -specfact enforce sdd --bundle -specfact plan select --bundle -``` - -**Detailed Guide**: [Agile/Scrum Workflows](agile-scrum-workflows.md) - ---- - -### I want to compare two plans - -**Recommended**: `plan compare` - -**Quick Example**: - -```bash -specfact plan compare --bundle plan-v1 plan-v2 -``` - -**Detailed Guide**: [Plan Comparison](../reference/commands.md#plan-compare) - ---- - -## Validation & Enforcement - -### I want to validate everything - -**Recommended**: `repro` - -**Quick Example**: - -```bash -specfact repro --verbose -``` - -**Detailed Guide**: [Validation Workflow](brownfield-engineer.md#step-3-validate-everything) - ---- - -### I want to enforce SDD compliance - -**Recommended**: `enforce sdd` - -**Quick Example**: - -```bash -specfact enforce sdd --bundle -``` - -**Detailed Guide**: [SDD Enforcement](../reference/commands.md#enforce-sdd) - ---- - -### I want to find gaps in my code - -**Recommended**: [Gap Discovery & Fixing Chain](command-chains.md#9-gap-discovery--fixing-chain-emerging) - -**Command**: `repro --verbose` โ†’ `generate fix-prompt` - -**Quick Example**: - -```bash -specfact repro --verbose -specfact generate fix-prompt --bundle --gap -# Then use AI IDE to apply fixes -``` - -**Detailed Guide**: [AI IDE Workflow](ai-ide-workflow.md) - ---- - -## AI IDE Integration - -### I want to set up AI IDE slash commands - -**Recommended**: `init --ide cursor` - -**Quick Example**: - -```bash -specfact init ide --ide cursor -``` - -**Detailed Guide**: [AI IDE Workflow](ai-ide-workflow.md) | [IDE Integration](ide-integration.md) - ---- - -### I want to generate tests using AI - -**Recommended**: [Test Generation from Specifications Chain](command-chains.md#8-test-generation-from-specifications-chain-emerging) - -**Command**: `generate test-prompt` โ†’ [AI IDE] โ†’ `spec generate-tests` - -**Quick Example**: - -```bash -specfact generate test-prompt --bundle --feature -# Then use AI IDE slash command: /specfact-cli/test-generate -specfact spec generate-tests --spec --output tests/ -``` - -**Detailed Guide**: [AI IDE Workflow](ai-ide-workflow.md) - ---- - -## DevOps Integration ๐Ÿ†• **NEW FEATURE** - -### I want to integrate SpecFact into my agile DevOps workflows - -**Recommended**: [DevOps Adapter Integration](devops-adapter-integration.md) - Bidirectional backlog sync - -**Command**: `sync bridge --adapter github --bidirectional` - -**Quick Example**: - -```bash -# 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](devops-adapter-integration.md) - ---- - -### I want to standardize backlog items using templates - -**Recommended**: [Backlog Refinement Guide](backlog-refinement.md) ๐Ÿ†• **NEW FEATURE** - AI-assisted template-driven refinement - -**Command**: `backlog refine` - -**Quick Example**: - -```bash -# 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](backlog-refinement.md) - ---- - -### I want to refine backlog items in a specific sprint - -**Recommended**: `backlog refine` with sprint filtering - -**Command**: `backlog refine --sprint ` - -**Quick Example**: - -```bash -# 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](backlog-refinement.md#quick-start) - ---- - -### I want to use persona-specific templates for backlog refinement - -**Recommended**: `backlog refine` with persona/framework filtering - -**Command**: `backlog refine --persona --framework ` - -**Quick Example**: - -```bash -# 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](backlog-refinement.md#template-system) - ---- - -### 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**: - -```bash -# 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](backlog-refinement.md#definition-of-ready-dor) - ---- - -### 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**: - -```bash -# 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](devops-adapter-integration.md) - ---- - -### 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 ` - -**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**: - -```bash -# 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](devops-adapter-integration.md#update-existing-issues) - ---- - -### I want to track changes in GitHub Projects - -**Recommended**: DevOps bridge adapter with project linking - -**Quick Example**: - -```bash -specfact sync bridge --adapter github --mode export-only --project "SpecFact CLI Development Board" -``` - -**Detailed Guide**: [DevOps Adapter Integration](devops-adapter-integration.md) - ---- - -## Migration & Troubleshooting - -### I want to migrate from an older version - -**Recommended**: Check migration guides - -**Quick Example**: - -```bash -# Check current version -specfact --version - -# Review migration guide for your version -# See: guides/migration-*.md -``` - -**Detailed Guide**: [Migration Guide](migration-guide.md) | [Troubleshooting](troubleshooting.md) - ---- - -### I want to troubleshoot an issue - -**Recommended**: [Troubleshooting Guide](troubleshooting.md) - -**Quick Example**: - -```bash -# Run validation with verbose output -specfact repro --verbose - -# Check plan for issues -specfact plan compare --bundle -``` - -**Detailed Guide**: [Troubleshooting](troubleshooting.md) - ---- - -## See Also - -- [Command Chains Reference](command-chains.md) - Complete workflows with decision trees -- [Command Reference](../reference/commands.md) - Complete command documentation -- [Brownfield Engineer Guide](brownfield-engineer.md) - Legacy modernization guide -- [Agile/Scrum Workflows](agile-scrum-workflows.md) - Team collaboration patterns +This page needs a full rewrite around the mounted command groups before task-level workflow examples can be published again. diff --git a/docs/guides/competitive-analysis.md b/docs/guides/competitive-analysis.md index 9a0ccda..a835f4f 100644 --- a/docs/guides/competitive-analysis.md +++ b/docs/guides/competitive-analysis.md @@ -4,360 +4,18 @@ title: Competitive Analysis permalink: /competitive-analysis/ --- -# What You Gain with SpecFact CLI +# Legacy Workflow Note -How SpecFact CLI complements and extends other development tools. +This page referenced command groups or workflow steps that are no longer part of the current public mounted CLI in this repository. The old examples were removed to avoid directing readers to unavailable commands. -## Overview +Use the current mounted entrypoints instead: -SpecFact CLI is a **brownfield-first legacy code modernization tool** that reverse engineers existing Python code into documented specs, then enforces them as runtime contracts. It builds on the strengths of specification tools like GitHub Spec-Kit and works alongside AI coding platforms to provide production-ready quality gates for legacy codebases. +- `specfact project --help` +- `specfact project sync --help` +- `specfact code --help` +- `specfact code review --help` +- `specfact spec --help` +- `specfact govern --help` +- `specfact backlog --help` ---- - -## Building on Specification Tools - -SpecFact CLI integrates with multiple specification and planning tools through a plugin-based adapter architecture: - -- **GitHub Spec-Kit** - Interactive specification authoring -- **OpenSpec** - Specification anchoring and change tracking (v0.22.0+) -- **GitHub Issues** - DevOps backlog integration -- **Future**: Linear, Jira, Azure DevOps, and more - -### Building on GitHub Spec-Kit - -### What Spec-Kit Does Great - -GitHub Spec-Kit pioneered the concept of **living specifications** with interactive slash commands. It's excellent for: - -- โœ… **Interactive Specification** - Slash commands (`/speckit.specify`, `/speckit.plan`) with AI assistance -- โœ… **Rapid Prototyping** - Quick spec โ†’ plan โ†’ tasks โ†’ code workflow for **new features** -- โœ… **Learning & Exploration** - Great for understanding state machines, contracts, requirements -- โœ… **IDE Integration** - CoPilot chat makes it accessible to less technical developers -- โœ… **Constitution & Planning** - Add constitution, plans, and feature breakdowns for new features -- โœ… **Single-Developer Projects** - Perfect for personal projects and learning - -**Note**: Spec-Kit excels at working with **new features** - you can add constitution, create plans, and break down features for things you're building from scratch. - -### What SpecFact CLI Adds To GitHub Spec-Kit - -SpecFact CLI **complements Spec-Kit** by adding automation and enforcement: - -| Enhancement | What You Get | -|-------------|--------------| -| **Automated enforcement** | Runtime + static contract validation, CI/CD gates | -| **Shared plans** | **Shared structured plans** enable team collaboration with automated bidirectional sync (not just manual markdown sharing like Spec-Kit) | -| **Code vs plan drift detection** | Automated comparison of intended design (manual plan) vs actual implementation (code-derived plan from `import from-code`) | -| **CI/CD integration** | Automated quality gates in your pipeline | -| **Brownfield support** | Analyze existing code to complement Spec-Kit's greenfield focus | -| **Property testing** | FSM fuzzing, Hypothesis-based validation | -| **No-escape gates** | Budget-based enforcement prevents violations | -| **Bidirectional sync** | Keep using Spec-Kit interactively, sync automatically with SpecFact | - -### The Journey: From Spec-Kit to SpecFact - -**Spec-Kit and SpecFact are complementary, not competitive:** - -- **Stage 1: Spec-Kit** - Interactive authoring with slash commands (`/speckit.specify`, `/speckit.plan`) -- **Stage 2: SpecFact** - Automated enforcement (CI/CD gates, contract validation) -- **Stage 3: Bidirectional Sync** - Use both tools together (Spec-Kit authoring + SpecFact enforcement) - -**[Learn the full journey โ†’](speckit-journey.md)** - -### Working With OpenSpec - -**OpenSpec** is another complementary tool that focuses on specification anchoring and change tracking. SpecFact CLI integrates with OpenSpec via the OpenSpec adapter (available in v0.22.0+): - -- **OpenSpec** manages specifications and change proposals (the "what" and "why") -- **SpecFact** analyzes existing code and enforces contracts (the "how" and "safety") -- **Bridge Adapters** sync change proposals to DevOps tools (the "tracking") - -**Integration:** - -```bash -# Read-only sync from OpenSpec to SpecFact (v0.22.0+) -specfact sync bridge --adapter openspec --mode read-only \ - --bundle my-project \ - --repo /path/to/openspec-repo - -# Export OpenSpec change proposals to GitHub Issues -specfact sync bridge --adapter github --mode export-only \ - --repo-owner your-org \ - --repo-name your-repo \ - --repo /path/to/openspec-repo -``` - -**[Learn the full OpenSpec integration journey โ†’](openspec-journey.md)** - -### Seamless Migration - -Already using Spec-Kit? SpecFact CLI **imports your work** in one command: - -```bash -specfact sync bridge --adapter speckit --repo ./my-speckit-project --write -``` - -**Result**: Your Spec-Kit artifacts (spec.md, plan.md, tasks.md) become production-ready contracts with zero manual work. - -**Ongoing**: Keep using Spec-Kit interactively, sync automatically with SpecFact: - -```bash -# Enable bidirectional sync (bridge-based, adapter-agnostic) -specfact sync bridge --adapter speckit --bundle --repo . --bidirectional --watch -``` - -**Best of both worlds**: Interactive authoring (Spec-Kit) + Automated enforcement (SpecFact) - -**Note**: SpecFact CLI uses a plugin-based adapter registry pattern. All adapters (Spec-Kit, OpenSpec, GitHub, etc.) are registered in `AdapterRegistry` and accessed via `specfact sync bridge --adapter `, making the architecture extensible for future tool integrations. - -**Team collaboration**: **Shared structured plans** enable multiple developers to work on the same plan with automated deviation detection. Unlike Spec-Kit's manual markdown sharing, SpecFact provides automated bidirectional sync that keeps plans synchronized across team members: - -```bash -# Enable bidirectional sync for team collaboration -specfact sync bridge --adapter speckit --bundle --repo . --bidirectional --watch -# โ†’ Automatically syncs Spec-Kit artifacts โ†” SpecFact project bundles -# โ†’ Multiple developers can work on the same plan with automated synchronization -# โ†’ No manual markdown sharing required - -# Detect code vs plan drift automatically -specfact plan compare --bundle legacy-api --code-vs-plan -# โ†’ Compares intended design (manual plan = what you planned) vs actual implementation (code-derived plan = what's in your code) -# โ†’ Auto-derived plans come from `import from-code` (code analysis), so comparison IS "code vs plan drift" -# โ†’ Identifies deviations automatically (not just artifact consistency like Spec-Kit's /speckit.analyze) -``` - ---- - -## Working With AI Coding Tools - -### What AI Tools Do Great - -Tools like **Replit Agent 3, Lovable, Cursor, and Copilot** excel at: - -- โœ… Rapid code generation -- โœ… Quick prototyping -- โœ… Learning and exploration -- โœ… Boilerplate reduction - -### What SpecFact CLI Adds To AI Coding Tools - -SpecFact CLI **validates AI-generated code** with: - -| Enhancement | What You Get | -|-------------|--------------| -| **Contract validation** | Ensure AI code meets your specs | -| **Runtime sentinels** | Catch async anti-patterns automatically | -| **No-escape gates** | Block broken code from merging | -| **Offline validation** | Works in air-gapped environments | -| **Evidence trails** | Reproducible proof of quality | -| **Team standards** | Enforce consistent patterns across AI-generated code | -| **CoPilot integration** | Slash commands for seamless IDE workflow | -| **Agent mode routing** | Enhanced prompts for better AI assistance | - -### Perfect Combination - -**AI tools generate code fast** โ†’ **SpecFact CLI ensures it's correct** - -Use AI for speed, use SpecFact for quality. - -### CoPilot-Enabled Mode - -When using Cursor, Copilot, or other AI assistants, SpecFact CLI integrates seamlessly: - -```bash -# Slash commands in IDE (after specfact init) -specfact init ide --ide cursor -/specfact.01-import legacy-api --repo . --confidence 0.7 -/specfact.02-plan init legacy-api -/specfact.06-sync --repo . --bidirectional -``` - -**Benefits:** - -- **Automatic mode detection** - Switches to CoPilot mode when available -- **Context injection** - Uses current file, selection, and workspace context -- **Enhanced prompts** - Optimized for AI understanding -- **Agent mode routing** - Specialized prompts for different operations - ---- - -## Key Capabilities - -### 1. Temporal Contracts - -**What it means**: State machines with runtime validation - -**Why developers love it**: Catches state transition bugs automatically - -**Example**: - -```yaml -# Protocol enforces valid state transitions -transitions: - - from_state: CONNECTED - on_event: disconnect - to_state: DISCONNECTING - guard: no_pending_messages # โœ… Checked at runtime -``` - -### 2. Proof-Carrying Promotion - -**What it means**: Evidence required before code merges - -**Why developers love it**: "Works on my machine" becomes provable - -**Example**: - -```bash -# PR includes reproducible evidence -specfact repro --budget 120 --report evidence.md -``` - -### 3. Brownfield-First โญ PRIMARY - -**What it means**: **Primary use case** - Reverse engineer existing legacy code into documented specs, then enforce contracts to prevent regressions during modernization. - -**Why developers love it**: Understand undocumented legacy code in minutes, not weeks. Modernize with confidence knowing contracts catch regressions automatically. - -**Example**: - -```bash -# Primary use case: Analyze legacy code -specfact code import legacy-api --repo ./legacy-app - -# Extract specs from existing code in < 10 seconds -# Then enforce contracts to prevent regressions -specfact enforce stage --preset balanced -``` - -**How it complements Spec-Kit**: Spec-Kit focuses on new feature authoring (greenfield); SpecFact CLI's **primary focus** is brownfield code modernization with runtime enforcement. - -### 4. Code vs Plan Drift Detection - -**What it means**: Automated comparison of intended design (manual plan = what you planned) vs actual implementation (code-derived plan = what's in your code). Auto-derived plans come from `import from-code` (code analysis), so comparison IS "code vs plan drift". - -**Why developers love it**: Detects code vs plan drift automatically (not just artifact consistency like Spec-Kit's `/speckit.analyze`). Spec-Kit's `/speckit.analyze` only checks artifact consistency between markdown files; SpecFact CLI detects actual code vs plan drift by comparing manual plans (intended design) with code-derived plans (actual implementation from code analysis). - -**Example**: - -```bash -# Detect code vs plan drift automatically -specfact plan compare --bundle legacy-api --code-vs-plan -# โ†’ Compares intended design (manual plan = what you planned) vs actual implementation (code-derived plan = what's in your code) -# โ†’ Auto-derived plans come from `import from-code` (code analysis), so comparison IS "code vs plan drift" -# โ†’ Identifies deviations automatically (not just artifact consistency like Spec-Kit's /speckit.analyze) -``` - -**How it complements Spec-Kit**: Spec-Kit's `/speckit.analyze` only checks artifact consistency between markdown files; SpecFact CLI detects code vs plan drift by comparing manual plans (intended design) with code-derived plans (actual implementation from `import from-code`). - -### 5. Evidence-Based - -**What it means**: Reproducible validation and reports - -**Why developers love it**: Debug failures with concrete data - -**Example**: - -```bash -# Generate reproducible evidence -specfact repro --report evidence.md -``` - -### 6. Offline-First - -**What it means**: Works without internet connection - -**Why developers love it**: Air-gapped environments, no data exfiltration, fast - -**Example**: - -```bash -# Works completely offline -uvx specfact-cli@latest plan init --interactive -``` - ---- - -## When to Use SpecFact CLI - -### SpecFact CLI is Perfect For โญ PRIMARY - -- โœ… **Legacy code modernization** โญ - Reverse engineer undocumented code into specs -- โœ… **Brownfield projects** โญ - Understand and modernize existing Python codebases -- โœ… **High-risk refactoring** โญ - Prevent regressions with runtime contract enforcement -- โœ… **Production systems** - Need quality gates and validation -- โœ… **Team projects** - Multiple developers need consistent standards -- โœ… **Compliance environments** - Evidence-based validation required -- โœ… **Air-gapped deployments** - Offline-first architecture -- โœ… **Open source projects** - Transparent, inspectable tooling - -### SpecFact CLI Works Alongside - -- โœ… **AI coding assistants** - Validate AI-generated code -- โœ… **Spec-Kit projects** - One-command import -- โœ… **Existing CI/CD** - Drop-in quality gates -- โœ… **Your IDE** - Command-line or extension (v0.2) - ---- - -## Getting Started With SpecFact CLI - -### Modernizing Legacy Code? โญ PRIMARY - -**Reverse engineer existing code**: - -```bash -# Primary use case: Analyze legacy codebase -specfact code import legacy-api --repo ./legacy-app -``` - -See [Use Cases: Brownfield Modernization](use-cases.md#use-case-1-brownfield-code-modernization-primary) โญ - -### Already Using Spec-Kit? (Secondary) - -**One-command import**: - -```bash -specfact sync bridge --adapter speckit --repo . --write -``` - -See [Use Cases: Spec-Kit Migration](use-cases.md#use-case-2-github-spec-kit-migration-secondary) - -### Using AI Coding Tools? - -**Add validation layer**: - -1. Let AI generate code as usual -2. Run `specfact code import --repo .` (auto-detects CoPilot mode) -3. Review auto-generated plan -4. Enable `specfact enforce stage --preset balanced` - -**With CoPilot Integration:** - -Use slash commands directly in your IDE: - -```bash -# First, initialize IDE integration -specfact init ide --ide cursor - -# Then use slash commands in IDE chat -/specfact.01-import legacy-api --repo . --confidence 0.7 -/specfact.compare --bundle legacy-api -/specfact.06-sync --repo . --bidirectional -``` - -SpecFact CLI automatically detects CoPilot and switches to enhanced mode. - -### Starting From Scratch? - -**Greenfield approach**: - -1. `specfact plan init legacy-api --interactive` -2. Add features and stories -3. Enable strict enforcement -4. Let SpecFact guide development - -See [Getting Started](../getting-started/README.md) for detailed setup. - ---- - -See [Getting Started](../getting-started/README.md) for quick setup and [Use Cases](use-cases.md) for detailed scenarios. +For exact syntax, verify against live help in the current release before copying examples. diff --git a/docs/guides/contract-testing-workflow.md b/docs/guides/contract-testing-workflow.md index 471d29a..951c313 100644 --- a/docs/guides/contract-testing-workflow.md +++ b/docs/guides/contract-testing-workflow.md @@ -1,269 +1,26 @@ -# Contract Testing Workflow - Simple Guide for Developers +# Legacy Workflow Note -## Quick Start: Verify Your Contract +This page described older `specfact plan`, `specfact generate`, `specfact contract`, or `specfact sdd constitution` workflows that are not part of the current public mounted CLI in this repository. The detailed command examples previously documented here were removed because they no longer match the command surface exposed by `specfact --help`. -The easiest way to verify your OpenAPI contract works is with a single command: +Use the current mounted entrypoints instead: -```bash -# Verify a specific contract -specfact contract verify --bundle my-api --feature FEATURE-001 - -# Verify all contracts in a bundle -specfact contract verify --bundle my-api -``` - -**What this does:** - -1. โœ… Validates your contract schema -2. โœ… Generates examples from the contract -3. โœ… Starts a mock server -4. โœ… Tests connectivity - -**That's it!** Your contract is verified and ready to use. The mock server keeps running so you can test your client code. - -## What You Can Do Without a Real API - -### โœ… Contract Verification (No API Needed) - -Use `contract verify` to ensure your contract is correct: - -```bash -specfact contract verify --bundle my-api --feature FEATURE-001 -``` - -**Output:** - -``` -``` - -Step 1: Validating contracts... -โœ“ FEATURE-001: Valid (13 endpoints) - -Step 2: Generating examples... -โœ“ FEATURE-001: Examples generated - -Step 3: Starting mock server for FEATURE-001... -โœ“ Mock server started at - -Step 4: Testing connectivity... -โœ“ Health check passed: UP - -โœ“ Contract verification complete! - -Summary: - โ€ข Contracts validated: 1 - โ€ข Examples generated: 1 - โ€ข Mock server: - -``` - -### โœ… Mock Server for Development - -Start a mock server that generates responses from your contract: - -```bash -# Start mock server with examples -specfact contract serve --bundle my-api --feature FEATURE-001 --examples - -# Or use the verify command (starts mock server automatically) -specfact contract verify --bundle my-api --feature FEATURE-001 -``` - -**Use cases:** - -- Frontend development without backend -- Client library testing -- Integration testing (test your client against the contract) - -### โœ… Contract Validation - -Validate that your contract schema is correct: - -```bash -# Validate a specific contract -specfact contract validate --bundle my-api --feature FEATURE-001 - -# Check coverage across all contracts -specfact contract coverage --bundle my-api -``` - -## Complete Workflow Examples - -### Example 1: New Contract Development - -```bash -# 1. Create a new contract -specfact contract init --bundle my-api --feature FEATURE-001 - -# 2. Edit the contract file -# Edit: .specfact/projects/my-api/contracts/FEATURE-001.openapi.yaml - -# 3. Verify everything works -specfact contract verify --bundle my-api --feature FEATURE-001 - -# 4. Test your client code against the mock server -curl http://localhost:9000/api/endpoint -``` - -### Example 2: CI/CD Pipeline - -```bash -# Validate contracts without starting mock server -specfact contract verify --bundle my-api --skip-mock --no-interactive - -# Or just validate -specfact contract validate --bundle my-api --no-interactive -``` - -### Example 3: Multiple Contracts - -```bash -# Verify all contracts in a bundle -specfact contract verify --bundle my-api - -# Check coverage -specfact contract coverage --bundle my-api -``` - -## What Requires a Real API +- `specfact project --help` +- `specfact project sync --help` +- `specfact code --help` +- `specfact code review --help` +- `specfact spec --help` +- `specfact govern --help` +- `specfact backlog --help` +- `specfact module --help` -### โŒ Contract Testing Against Real Implementation - -The `specmatic test` command requires a **real API implementation**: +When you need exact syntax, verify against live help in the current release, for example: ```bash -# This REQUIRES a running API -specmatic test \ - --spec .specfact/projects/my-api/contracts/FEATURE-001.openapi.yaml \ - --host http://localhost:8000 +specfact project sync bridge --help +specfact code repro --help +specfact code validate sidecar --help +specfact spec validate --help +specfact govern enforce --help ``` -**When to use:** - -- After implementing your API -- To verify your implementation matches the contract -- In integration tests - -**Workflow:** - -```bash -# 1. Generate test files -specfact contract test --bundle my-api --feature FEATURE-001 - -# 2. Start your real API -python -m uvicorn main:app --port 8000 - -# 3. Run contract tests -specmatic test \ - --spec .specfact/projects/my-api/contracts/FEATURE-001.openapi.yaml \ - --host http://localhost:8000 -``` - -## Command Reference - -### `contract verify` - All-in-One Verification - -The simplest way to verify your contract: - -```bash -specfact contract verify [OPTIONS] - -Options: - --bundle TEXT Project bundle name - --feature TEXT Feature key (optional - verifies all if not specified) - --port INTEGER Port for mock server (default: 9000) - --skip-mock Skip mock server (only validate) - --no-interactive Non-interactive mode (CI/CD) -``` - -**What it does:** - -1. Validates contract schema -2. Generates examples -3. Starts mock server (unless `--skip-mock`) -4. Tests connectivity - -### `contract validate` - Schema Validation - -```bash -specfact contract validate --bundle my-api --feature FEATURE-001 -``` - -Validates the OpenAPI schema structure. - -### `contract serve` - Mock Server - -```bash -specfact contract serve --bundle my-api --feature FEATURE-001 --examples -``` - -Starts a mock server that generates responses from your contract. - -### `contract coverage` - Coverage Report - -```bash -specfact contract coverage --bundle my-api -``` - -Shows contract coverage metrics across all features. - -### `contract test` - Generate Tests - -```bash -specfact contract test --bundle my-api --feature FEATURE-001 -``` - -Generates test files that can be run against a real API. - -## Key Insights - -| Task | Requires Real API? | Command | -|------|-------------------|---------| -| **Contract Verification** | โŒ No | `contract verify` | -| **Schema Validation** | โŒ No | `contract validate` | -| **Mock Server** | โŒ No | `contract serve` | -| **Example Generation** | โŒ No | `contract verify` (automatic) | -| **Contract Testing** | โœ… Yes | `specmatic test` (after `contract test`) | - -## Troubleshooting - -### Mock Server Won't Start - -```bash -# Check if Specmatic is installed -npx specmatic --version - -# Install if needed -npm install -g @specmatic/specmatic -``` - -### Contract Validation Fails - -```bash -# Check contract file syntax -cat .specfact/projects/my-api/contracts/FEATURE-001.openapi.yaml - -# Validate manually -specfact contract validate --bundle my-api --feature FEATURE-001 -``` - -### Examples Not Generated - -Examples are generated automatically from your OpenAPI schema. If generation fails: - -- Check that your schema has proper request/response definitions -- Ensure data types are properly defined -- Run `contract verify` to see detailed error messages - -## Best Practices - -1. **Start with `contract verify`** - It does everything you need -2. **Use mock servers for development** - No need to wait for backend -3. **Validate in CI/CD** - Use `--skip-mock --no-interactive` for fast validation -4. **Test against real API** - Use `specmatic test` after implementation - -## Next Steps - -- Read the [API Reference](../reference/commands.md) for detailed command options -- Check [Architecture Documentation](../reference/architecture.md) for bundle management -- See [Agile/Scrum Workflows](../guides/agile-scrum-workflows.md) for team collaboration +This page needs a full rewrite around the mounted command groups before task-level workflow examples can be published again. diff --git a/docs/guides/copilot-mode.md b/docs/guides/copilot-mode.md index db54572..14d17de 100644 --- a/docs/guides/copilot-mode.md +++ b/docs/guides/copilot-mode.md @@ -4,196 +4,18 @@ title: Using CoPilot Mode permalink: /copilot-mode/ --- -# Using CoPilot Mode +# Legacy Workflow Note -**Status**: โœ… **AVAILABLE** (v0.4.2+) -**Last Updated**: 2025-11-02 +This page referenced command groups or workflow steps that are no longer part of the current public mounted CLI in this repository. The old examples were removed to avoid directing readers to unavailable commands. ---- - -## Overview - -SpecFact CLI supports two operational modes: - -- **CI/CD Mode** (Default): Fast, deterministic execution for automation -- **CoPilot Mode**: Interactive assistance with enhanced prompts for IDEs - -Mode is auto-detected based on environment, or you can explicitly set it with `--mode cicd` or `--mode copilot`. - ---- - -## Quick Start - -### Quick Start Using CoPilot Mode - -```bash -# Explicitly enable CoPilot mode -specfact --mode copilot import from-code legacy-api --repo . --confidence 0.7 - -# Mode is auto-detected based on environment (IDE integration, CoPilot API availability) -specfact code import legacy-api --repo . --confidence 0.7 # Auto-detects CoPilot if available -``` - -### What You Get with CoPilot Mode - -- โœ… **Enhanced prompts** with context injection (current file, selection, workspace) -- โœ… **Agent routing** for better analysis and planning -- โœ… **Context-aware execution** optimized for interactive use -- โœ… **Better AI steering** with detailed instructions - ---- - -## How It Works - -### Mode Detection - -SpecFact CLI automatically detects the operational mode: - -1. **Explicit flag** - `--mode cicd` or `--mode copilot` (highest priority) -2. **Environment detection** - Checks for CoPilot API availability, IDE integration -3. **Default** - Falls back to CI/CD mode if no CoPilot environment detected - -### Agent Routing - -In CoPilot mode, commands are routed through specialized agents: - -| Command | Agent | Purpose | -|---------|-------|---------| -| `import from-code` | `AnalyzeAgent` | AI-first brownfield analysis with semantic understanding (multi-language support) | -| `plan init` | `PlanAgent` | Plan management with business logic understanding | -| `plan compare` | `PlanAgent` | Plan comparison with deviation analysis | -| `sync bridge --adapter speckit` | `SyncAgent` | Bidirectional sync with conflict resolution | - -### Context Injection - -CoPilot mode automatically injects relevant context: - -- **Current file**: Active file in IDE -- **Selection**: Selected text/code -- **Workspace**: Repository root path -- **Git context**: Current branch, recent commits -- **Codebase context**: Directory structure, files, dependencies - -This context is used to generate enhanced prompts that instruct the AI IDE to: - -- Understand the codebase semantically -- Call the SpecFact CLI with appropriate arguments -- Enhance CLI results with semantic understanding - -### Pragmatic Integration Benefits - -- โœ… **No separate LLM setup** - Uses AI IDE's existing LLM (Cursor, CoPilot, etc.) -- โœ… **No additional API costs** - Leverages existing IDE infrastructure -- โœ… **Simpler architecture** - No langchain, API keys, or complex integration -- โœ… **Better developer experience** - Native IDE integration via slash commands -- โœ… **Streamlined workflow** - AI understands codebase, CLI handles structured work - ---- - -## Examples - -### Example 1: Brownfield Analysis โญ PRIMARY - -```bash -# CI/CD mode (fast, deterministic, Python-only) -specfact --mode cicd import from-code --repo . --confidence 0.7 - -# CoPilot mode (AI-first, semantic understanding, multi-language) -specfact --mode copilot import from-code --repo . --confidence 0.7 - -# Output (CoPilot mode): -# Mode: CoPilot (AI-first analysis) -# ๐Ÿค– AI-powered analysis (semantic understanding)... -# โœ“ AI analysis complete -# โœ“ Found X features -# โœ“ Detected themes: ... -``` - -**Key Differences**: - -- **CoPilot Mode**: Uses LLM for semantic understanding, supports all languages, generates high-quality Spec-Kit artifacts -- **CI/CD Mode**: Uses Python AST for fast analysis, Python-only, generates generic content (hardcoded fallbacks) - -### Example 2: Plan Initialization - -```bash -# CI/CD mode (minimal prompts) -specfact --mode cicd plan init --no-interactive - -# CoPilot mode (enhanced interactive prompts) -specfact --mode copilot plan init --interactive - -# Output: -# Mode: CoPilot (agent routing) -# Agent prompt generated (XXX chars) -# [enhanced interactive prompts] -``` - -### Example 3: Plan Comparison - -```bash -# CoPilot mode with enhanced deviation analysis (bundle directory paths) -specfact --mode copilot plan compare \ - --manual .specfact/projects/main \ - --auto .specfact/projects/my-project-auto - -# Output: -# Mode: CoPilot (agent routing) -# Agent prompt generated (XXX chars) -# [enhanced deviation analysis with context] -``` - ---- - -## Mode Differences - -| Feature | CI/CD Mode | CoPilot Mode | -|---------|-----------|--------------| -| **Speed** | Fast, deterministic | Slightly slower, context-aware | -| **Output** | Structured, minimal | Enhanced, detailed | -| **Prompts** | Standard | Enhanced with context | -| **Context** | Minimal | Full context injection | -| **Agent Routing** | Direct execution | Agent-based routing | -| **Use Case** | Automation, CI/CD | Interactive development, IDE | - ---- - -## When to Use Each Mode - -### Use CI/CD Mode When - -- โœ… Running in CI/CD pipelines -- โœ… Automating workflows -- โœ… Need fast, deterministic execution -- โœ… Don't need enhanced prompts - -### Use CoPilot Mode When - -- โœ… Working in IDE with AI assistance -- โœ… Need enhanced prompts for better AI steering -- โœ… Want context-aware execution -- โœ… Interactive development workflows - ---- - -## IDE Integration - -For IDE integration with slash commands, see: - -- **[IDE Integration Guide](ide-integration.md)** - Set up slash commands in your IDE - ---- - -## Related Documentation - -- [IDE Integration Guide](ide-integration.md) - Set up IDE slash commands -- [Command Reference](../reference/commands.md) - All CLI commands -- [Architecture](../reference/architecture.md) - Technical details - ---- +Use the current mounted entrypoints instead: -## Next Steps +- `specfact project --help` +- `specfact project sync --help` +- `specfact code --help` +- `specfact code review --help` +- `specfact spec --help` +- `specfact govern --help` +- `specfact backlog --help` -- โœ… Use `--mode copilot` on CLI commands for enhanced prompts -- ๐Ÿ“– Read [IDE Integration Guide](ide-integration.md) for slash commands -- ๐Ÿ“– Read [Command Reference](../reference/commands.md) for all commands +For exact syntax, verify against live help in the current release before copying examples. diff --git a/docs/guides/custom-registries.md b/docs/guides/custom-registries.md index c443171..5fceccd 100644 --- a/docs/guides/custom-registries.md +++ b/docs/guides/custom-registries.md @@ -53,7 +53,7 @@ Choose `always` for fully controlled internal registries; use `prompt` for unkno ## Priority -When multiple registries are configured, they are queried in order: official first, then custom registries by ascending priority number. Search and install use this order; the first matching module id wins. Use priority to prefer an internal registry over the official one for overlapping names (e.g. `specfact/backlog` from your mirror). +When multiple registries are configured, they are queried in order: official first, then custom registries by ascending priority number. Search and install use this order; the first matching module id wins. Use priority to prefer an internal registry over the official one for overlapping names (e.g. `nold-ai/specfact-backlog` from your mirror). ## Search across registries diff --git a/docs/guides/devops-adapter-integration.md b/docs/guides/devops-adapter-integration.md index 9a4a211..f7d9e52 100644 --- a/docs/guides/devops-adapter-integration.md +++ b/docs/guides/devops-adapter-integration.md @@ -113,7 +113,7 @@ EOF Export the change proposal to create a GitHub issue: ```bash -specfact sync bridge --adapter github --mode export-only \ +specfact project sync bridge --adapter github --mode export-only \ --repo-owner your-org \ --repo-name your-repo \ --repo /path/to/openspec-repo @@ -128,7 +128,7 @@ As you implement the feature, track progress automatically: git commit -m "feat: implement add-feature-x - initial API design" # Track progress (detects commits and adds comments) -specfact sync bridge --adapter github --mode export-only \ +specfact project sync bridge --adapter github --mode export-only \ --repo-owner your-org \ --repo-name your-repo \ --track-code-changes \ @@ -174,7 +174,7 @@ specfact backlog auth github --client-id YOUR_CLIENT_ID ```bash # Uses gh auth token automatically -specfact sync bridge --adapter github --mode export-only \ +specfact project sync bridge --adapter github --mode export-only \ --repo-owner your-org \ --repo-name your-repo \ --use-gh-cli @@ -184,7 +184,7 @@ specfact sync bridge --adapter github --mode export-only \ ```bash export GITHUB_TOKEN=ghp_your_token_here -specfact sync bridge --adapter github --mode export-only \ +specfact project sync bridge --adapter github --mode export-only \ --repo-owner your-org \ --repo-name your-repo ``` @@ -192,7 +192,7 @@ specfact sync bridge --adapter github --mode export-only \ **Option 4: Command Line Flag** ```bash -specfact sync bridge --adapter github --mode export-only \ +specfact project sync bridge --adapter github --mode export-only \ --repo-owner your-org \ --repo-name your-repo \ --github-token ghp_your_token_here @@ -204,7 +204,7 @@ specfact sync bridge --adapter github --mode export-only \ ```bash # Export all active proposals to GitHub Issues -specfact sync bridge --adapter github --mode export-only \ +specfact project sync bridge --adapter github --mode export-only \ --repo-owner your-org \ --repo-name your-repo \ --repo /path/to/openspec-repo @@ -214,7 +214,7 @@ specfact sync bridge --adapter github --mode export-only \ ```bash # Detect code changes and add progress comments -specfact sync bridge --adapter github --mode export-only \ +specfact project sync bridge --adapter github --mode export-only \ --repo-owner your-org \ --repo-name your-repo \ --track-code-changes \ @@ -225,14 +225,14 @@ specfact sync bridge --adapter github --mode export-only \ ```bash # Export only specific change proposals -specfact sync bridge --adapter github --mode export-only \ +specfact project sync bridge --adapter github --mode export-only \ --repo-owner your-org \ --repo-name your-repo \ --change-ids add-feature-x,update-api \ --repo /path/to/openspec-repo ``` -### Project backlog context (.specfact/backlog.yaml) +### Project backlog context (.nold-ai/specfact-backlog.yaml) Store project-level adapter context (org, repo, project per adapter) so you do not have to pass `--repo-owner`, `--repo-name`, `--ado-org`, `--ado-project`, or `--ado-team` on every backlog command after authenticating once. @@ -280,7 +280,7 @@ ado: So after authenticating once, **running from the repo root is enough** for both GitHub and ADOโ€”org/repo or org/project are detected automatically from the git remote. -Applies to all backlog commands: `specfact backlog daily`, `specfact backlog refine`, `specfact sync bridge`, etc. +Applies to all backlog commands: `specfact backlog daily`, `specfact backlog refine`, `specfact project sync bridge`, etc. --- @@ -298,7 +298,7 @@ Applies to all backlog commands: `specfact backlog daily`, `specfact backlog ref ```bash # โœ… CORRECT: Direct export from OpenSpec to GitHub -specfact sync bridge --adapter github --mode export-only \ +specfact project sync bridge --adapter github --mode export-only \ --repo-owner your-org \ --repo-name your-repo \ --change-ids add-feature-x \ @@ -328,7 +328,7 @@ specfact sync bridge --adapter github --mode export-only \ ```bash # Step 1: Import GitHub issue into bundle (stores lossless content) -specfact sync bridge --adapter github --mode bidirectional \ +specfact project sync bridge --adapter github --mode bidirectional \ --repo-owner your-org --repo-name your-repo \ --bundle migration-bundle \ --backlog-ids 123 @@ -337,7 +337,7 @@ specfact sync bridge --adapter github --mode bidirectional \ # Note the change_id from output # Step 2: Export from bundle to ADO (uses stored content) -specfact sync bridge --adapter ado --mode export-only \ +specfact project sync bridge --adapter ado --mode export-only \ --ado-org your-org --ado-project your-project \ --bundle migration-bundle \ --change-ids add-feature-x # Use change_id from Step 1 @@ -361,7 +361,7 @@ specfact sync bridge --adapter ado --mode export-only \ ```bash # โŒ WRONG: This will show "0 backlog items exported" -specfact sync bridge --adapter github --mode export-only \ +specfact project sync bridge --adapter github --mode export-only \ --repo-owner your-org --repo-name your-repo \ --bundle some-bundle \ --change-ids add-feature-x \ @@ -374,7 +374,7 @@ specfact sync bridge --adapter github --mode export-only \ ```bash # โœ… CORRECT: Direct export (no --bundle) -specfact sync bridge --adapter github --mode export-only \ +specfact project sync bridge --adapter github --mode export-only \ --repo-owner your-org --repo-name your-repo \ --change-ids add-feature-x \ --repo /path/to/openspec-repo @@ -413,13 +413,13 @@ When your OpenSpec change proposals are in a different repository than your sour # Source code in specfact-cli # Step 1: Create issue from proposal -specfact sync bridge --adapter github --mode export-only \ +specfact project sync bridge --adapter github --mode export-only \ --repo-owner nold-ai \ --repo-name specfact-cli-internal \ --repo /path/to/specfact-cli-internal # Step 2: Track code changes from source code repo -specfact sync bridge --adapter github --mode export-only \ +specfact project sync bridge --adapter github --mode export-only \ --repo-owner nold-ai \ --repo-name specfact-cli-internal \ --track-code-changes \ @@ -463,7 +463,7 @@ When exporting to public repositories, use content sanitization to protect inter ```bash # Public repository: sanitize content -specfact sync bridge --adapter github --mode export-only \ +specfact project sync bridge --adapter github --mode export-only \ --repo-owner your-org \ --repo-name public-repo \ --sanitize \ @@ -471,7 +471,7 @@ specfact sync bridge --adapter github --mode export-only \ --repo /path/to/openspec-repo # Internal repository: use full content -specfact sync bridge --adapter github --mode export-only \ +specfact project sync bridge --adapter github --mode export-only \ --repo-owner your-org \ --repo-name internal-repo \ --no-sanitize \ @@ -571,7 +571,7 @@ When `--sanitize` is enabled, progress comments are sanitized: 2. **Export to GitHub**: ```bash - specfact sync bridge --adapter github --mode export-only \ + specfact project sync bridge --adapter github --mode export-only \ --repo-owner your-org \ --repo-name your-repo \ --repo /path/to/openspec-repo @@ -594,7 +594,7 @@ When `--sanitize` is enabled, progress comments are sanitized: 2. **Track Progress**: ```bash - specfact sync bridge --adapter github --mode export-only \ + specfact project sync bridge --adapter github --mode export-only \ --repo-owner your-org \ --repo-name your-repo \ --track-code-changes \ @@ -613,7 +613,7 @@ When `--sanitize` is enabled, progress comments are sanitized: Add manual progress comments without code change detection: ```bash -specfact sync bridge --adapter github --mode export-only \ +specfact project sync bridge --adapter github --mode export-only \ --repo-owner your-org \ --repo-name your-repo \ --add-progress-comment \ @@ -638,7 +638,7 @@ SpecFact supports more than exporting and updating backlog items: Example: Import selected GitHub issues into a bundle and keep them in sync: ```bash -specfact sync bridge --adapter github --mode bidirectional \ +specfact project sync bridge --adapter github --mode bidirectional \ --repo-owner your-org --repo-name your-repo \ --bundle main \ --backlog-ids 111,112 @@ -672,7 +672,7 @@ Migrate a GitHub issue to Azure DevOps while preserving all content: ```bash # Step 1: Import GitHub issue into bundle (stores lossless content) # This creates a change proposal in the bundle and stores raw content -specfact sync bridge --adapter github --mode bidirectional \ +specfact project sync bridge --adapter github --mode bidirectional \ --repo-owner your-org --repo-name your-repo \ --bundle main \ --backlog-ids 123 @@ -692,7 +692,7 @@ ls /path/to/openspec-repo/openspec/changes/ # Step 3: Export from bundle to ADO (uses stored lossless content) # Replace with the actual change_id from Step 1 -specfact sync bridge --adapter ado --mode export-only \ +specfact project sync bridge --adapter ado --mode export-only \ --ado-org your-org --ado-project your-project \ --bundle main \ --change-ids add-feature-x # Use the actual change_id from Step 1 @@ -751,7 +751,7 @@ Keep proposals in sync across GitHub (public) and ADO (internal): ```bash # Day 1: Create proposal in OpenSpec, export to GitHub (public) # Assume change_id is "add-feature-x" (from openspec/changes/add-feature-x/proposal.md) -specfact sync bridge --adapter github --mode export-only \ +specfact project sync bridge --adapter github --mode export-only \ --repo-owner your-org --repo-name public-repo \ --sanitize \ --repo /path/to/openspec-repo \ @@ -762,7 +762,7 @@ specfact sync bridge --adapter github --mode export-only \ # Day 2: Import GitHub issue into bundle (for internal team) # This stores lossless content in the bundle -specfact sync bridge --adapter github --mode bidirectional \ +specfact project sync bridge --adapter github --mode bidirectional \ --repo-owner your-org --repo-name public-repo \ --bundle internal \ --backlog-ids 123 @@ -772,7 +772,7 @@ specfact sync bridge --adapter github --mode bidirectional \ # Day 3: Export to ADO for internal tracking (full content, no sanitization) # Uses the change_id from Day 2 -specfact sync bridge --adapter ado --mode export-only \ +specfact project sync bridge --adapter ado --mode export-only \ --ado-org your-org --ado-project internal-project \ --bundle internal \ --change-ids add-feature-x @@ -782,7 +782,7 @@ specfact sync bridge --adapter ado --mode export-only \ # Day 4: Update in ADO, sync back to GitHub (status sync) # Import ADO work item to update bundle with latest status -specfact sync bridge --adapter ado --mode bidirectional \ +specfact project sync bridge --adapter ado --mode bidirectional \ --ado-org your-org --ado-project internal-project \ --bundle internal \ --backlog-ids 456 @@ -791,7 +791,7 @@ specfact sync bridge --adapter ado --mode bidirectional \ # Bundle now has latest status from ADO # Then sync status back to GitHub -specfact sync bridge --adapter github --mode export-only \ +specfact project sync bridge --adapter github --mode export-only \ --repo-owner your-org --repo-name public-repo \ --update-existing \ --repo /path/to/openspec-repo \ @@ -853,7 +853,7 @@ export AZURE_DEVOPS_TOKEN='your-ado-token' # Step 1: Import GitHub issue into bundle # This stores the issue in a bundle with lossless content preservation -specfact sync bridge --adapter github --mode bidirectional \ +specfact project sync bridge --adapter github --mode bidirectional \ --repo-owner your-org --repo-name your-repo \ --bundle migration-bundle \ --backlog-ids 123 @@ -869,7 +869,7 @@ ls .specfact/projects/migration-bundle/change_tracking/proposals/ # Step 3: Export to Azure DevOps # Use the change_id from Step 1 -specfact sync bridge --adapter ado --mode export-only \ +specfact project sync bridge --adapter ado --mode export-only \ --ado-org your-org --ado-project your-project \ --bundle migration-bundle \ --change-ids add-feature-x @@ -884,13 +884,13 @@ specfact sync bridge --adapter ado --mode export-only \ # Content should match exactly (Why, What Changes sections, formatting) # Step 5: Optional - Round-trip back to GitHub to verify -specfact sync bridge --adapter ado --mode bidirectional \ +specfact project sync bridge --adapter ado --mode bidirectional \ --ado-org your-org --ado-project your-project \ --bundle migration-bundle \ --backlog-ids 456 # Then export back to GitHub -specfact sync bridge --adapter github --mode export-only \ +specfact project sync bridge --adapter github --mode export-only \ --repo-owner your-org --repo-name your-repo \ --bundle migration-bundle \ --change-ids add-feature-x \ @@ -922,7 +922,7 @@ export AZURE_DEVOPS_TOKEN='your-ado-token' # Import GitHub issue #110 into bundle 'cross-sync-test' # Note: Bundle will be auto-created if it doesn't exist # This stores lossless content in the bundle -specfact sync bridge --adapter github --mode bidirectional \ +specfact project sync bridge --adapter github --mode bidirectional \ --repo-owner nold-ai --repo-name specfact-cli \ --bundle cross-sync-test \ --backlog-ids 110 @@ -943,7 +943,7 @@ ls /path/to/openspec-repo/openspec/changes/ # ============================================================ # Export the proposal to ADO using the change_id from Step 1 # Replace with the actual change_id from Step 1 -specfact sync bridge --adapter ado --mode export-only \ +specfact project sync bridge --adapter ado --mode export-only \ --ado-org your-org --ado-project your-project \ --bundle cross-sync-test \ --change-ids @@ -959,7 +959,7 @@ specfact sync bridge --adapter ado --mode export-only \ # Import the ADO work item back into the bundle # This updates the bundle with ADO's version of the content # Replace with the ID from Step 2 -specfact sync bridge --adapter ado --mode bidirectional \ +specfact project sync bridge --adapter ado --mode bidirectional \ --ado-org your-org --ado-project your-project \ --bundle cross-sync-test \ --backlog-ids @@ -973,7 +973,7 @@ specfact sync bridge --adapter ado --mode bidirectional \ # ============================================================ # Export back to GitHub to complete the round-trip # This updates the original GitHub issue with any changes from ADO -specfact sync bridge --adapter github --mode export-only \ +specfact project sync bridge --adapter github --mode export-only \ --repo-owner nold-ai --repo-name specfact-cli \ --bundle cross-sync-test \ --change-ids \ @@ -1057,7 +1057,7 @@ The change proposal must have `source_tracking` metadata linking it to the GitHu To update a specific change proposal's linked issue: ```bash -specfact sync bridge --adapter github --mode export-only \ +specfact project sync bridge --adapter github --mode export-only \ --repo-owner your-org \ --repo-name your-repo \ --change-ids your-change-id \ @@ -1070,7 +1070,7 @@ specfact sync bridge --adapter github --mode export-only \ ```bash cd /path/to/openspec-repo -specfact sync bridge --adapter github --mode export-only \ +specfact project sync bridge --adapter github --mode export-only \ --repo-owner nold-ai \ --repo-name specfact-cli \ --change-ids implement-adapter-enhancement-recommendations \ @@ -1083,7 +1083,7 @@ specfact sync bridge --adapter github --mode export-only \ To update all change proposals that have linked GitHub issues: ```bash -specfact sync bridge --adapter github --mode export-only \ +specfact project sync bridge --adapter github --mode export-only \ --repo-owner your-org \ --repo-name your-repo \ --update-existing \ @@ -1134,7 +1134,7 @@ By default, archived change proposals (in `openspec/changes/archive/`) are exclu ```bash # Update all archived proposals with new comment logic -specfact sync bridge --adapter github --mode export-only \ +specfact project sync bridge --adapter github --mode export-only \ --repo-owner your-org \ --repo-name your-repo \ --include-archived \ @@ -1142,7 +1142,7 @@ specfact sync bridge --adapter github --mode export-only \ --repo /path/to/openspec-repo # Update specific archived proposal -specfact sync bridge --adapter github --mode export-only \ +specfact project sync bridge --adapter github --mode export-only \ --repo-owner your-org \ --repo-name your-repo \ --change-ids add-code-change-tracking \ @@ -1164,7 +1164,7 @@ When `--include-archived` is used with `--update-existing`: ```bash # Update issue #107 with improved branch detection -specfact sync bridge --adapter github --mode export-only \ +specfact project sync bridge --adapter github --mode export-only \ --repo-owner nold-ai \ --repo-name specfact-cli \ --change-ids add-code-change-tracking \ @@ -1252,7 +1252,7 @@ Verify `openspec/changes//proposal.md` was updated: ```bash # โŒ WRONG: Using --bundle when exporting from OpenSpec - specfact sync bridge --adapter github --mode export-only \ + specfact project sync bridge --adapter github --mode export-only \ --repo-owner your-org --repo-name your-repo \ --bundle some-bundle \ --change-ids add-feature-x \ @@ -1270,7 +1270,7 @@ Verify `openspec/changes//proposal.md` was updated: ```bash # โœ… CORRECT: Direct export from OpenSpec - specfact sync bridge --adapter github --mode export-only \ + specfact project sync bridge --adapter github --mode export-only \ --repo-owner your-org --repo-name your-repo \ --change-ids add-feature-x \ --repo /path/to/openspec-repo @@ -1280,13 +1280,13 @@ Verify `openspec/changes//proposal.md` was updated: ```bash # Step 1: Import from backlog into bundle - specfact sync bridge --adapter github --mode bidirectional \ + specfact project sync bridge --adapter github --mode bidirectional \ --repo-owner your-org --repo-name your-repo \ --bundle your-bundle \ --backlog-ids 123 # Step 2: Export from bundle (now it will work) - specfact sync bridge --adapter ado --mode export-only \ + specfact project sync bridge --adapter ado --mode export-only \ --ado-org your-org --ado-project your-project \ --bundle your-bundle \ --change-ids @@ -1447,13 +1447,13 @@ specfact backlog auth azure-devops # Option 2: Environment Variable export AZURE_DEVOPS_TOKEN=your_pat_token -specfact sync bridge --adapter ado --mode export-only \ +specfact project sync bridge --adapter ado --mode export-only \ --ado-org your-org \ --ado-project your-project \ --repo /path/to/openspec-repo # Option 3: Command Line Flag -specfact sync bridge --adapter ado --mode export-only \ +specfact project sync bridge --adapter ado --mode export-only \ --ado-org your-org \ --ado-project your-project \ --ado-token your_pat_token \ @@ -1464,26 +1464,26 @@ specfact sync bridge --adapter ado --mode export-only \ ```bash # Bidirectional sync (import work items AND export proposals) -specfact sync bridge --adapter ado --bidirectional \ +specfact project sync bridge --adapter ado --bidirectional \ --ado-org your-org \ --ado-project your-project \ --repo /path/to/openspec-repo # Export-only (one-way: OpenSpec โ†’ ADO) -specfact sync bridge --adapter ado --mode export-only \ +specfact project sync bridge --adapter ado --mode export-only \ --ado-org your-org \ --ado-project your-project \ --repo /path/to/openspec-repo # Export with explicit work item type -specfact sync bridge --adapter ado --mode export-only \ +specfact project sync bridge --adapter ado --mode export-only \ --ado-org your-org \ --ado-project your-project \ --ado-work-item-type "User Story" \ --repo /path/to/openspec-repo # Track code changes and add progress comments -specfact sync bridge --adapter ado --mode export-only \ +specfact project sync bridge --adapter ado --mode export-only \ --ado-org your-org \ --ado-project your-project \ --track-code-changes \ @@ -1502,7 +1502,7 @@ The ADO adapter automatically derives work item type from your project's process You can override with `--ado-work-item-type`: ```bash -specfact sync bridge --adapter ado --mode export-only \ +specfact project sync bridge --adapter ado --mode export-only \ --ado-org your-org \ --ado-project your-project \ --ado-work-item-type "Bug" \ diff --git a/docs/guides/dual-stack-enrichment.md b/docs/guides/dual-stack-enrichment.md index 6087e4f..951c313 100644 --- a/docs/guides/dual-stack-enrichment.md +++ b/docs/guides/dual-stack-enrichment.md @@ -1,343 +1,26 @@ -# Dual-Stack Enrichment Pattern +# Legacy Workflow Note -**Status**: โœ… **AVAILABLE** (v0.13.0+) -**Last Updated**: 2025-12-23 -**Version**: v0.20.4 (enrichment parser improvements: story merging, format validation) +This page described older `specfact plan`, `specfact generate`, `specfact contract`, or `specfact sdd constitution` workflows that are not part of the current public mounted CLI in this repository. The detailed command examples previously documented here were removed because they no longer match the command surface exposed by `specfact --help`. ---- +Use the current mounted entrypoints instead: -## Overview +- `specfact project --help` +- `specfact project sync --help` +- `specfact code --help` +- `specfact code review --help` +- `specfact spec --help` +- `specfact govern --help` +- `specfact backlog --help` +- `specfact module --help` -The **Dual-Stack Enrichment Pattern** is SpecFact's approach to combining CLI automation with AI IDE (LLM) capabilities. It ensures that all artifacts are CLI-generated and validated, while allowing LLMs to add semantic understanding and enhancements. - -## Core Principle - -**ALWAYS use the SpecFact CLI as the primary tool**. LLM enrichment is a **secondary layer** that enhances CLI output with semantic understanding, but **never replaces CLI artifact creation**. - -## CLI vs LLM Capabilities - -### CLI-Only Operations (CI/CD Mode - No LLM Required) - -The CLI can perform these operations **without LLM**: - -- โœ… Tool execution (ruff, pylint, basedpyright, mypy, semgrep, specmatic) -- โœ… Bundle management (create, load, save, validate structure) -- โœ… Metadata management (timestamps, hashes, telemetry) -- โœ… Planning operations (init, add-feature, add-story, update-idea, update-feature) -- โœ… AST/Semgrep-based analysis (code structure, patterns, relationships) -- โœ… Specmatic validation (OpenAPI/AsyncAPI contract validation) -- โœ… Format validation (YAML/JSON schema compliance) -- โœ… Source tracking and drift detection - -**CRITICAL LIMITATIONS**: - -- โŒ **CANNOT generate code** - No LLM available in CLI-only mode -- โŒ **CANNOT do reasoning** - No semantic understanding without LLM - -### LLM-Required Operations (AI IDE Mode - Via Slash Prompts) - -These operations **require LLM** and are only available via AI IDE slash prompts: - -- โœ… Code generation (requires LLM reasoning) -- โœ… Code enhancement (contracts, refactoring, improvements) -- โœ… Semantic understanding (business logic, context, priorities) -- โœ… Plan enrichment (missing features, confidence adjustments, business context) -- โœ… Code reasoning (why decisions were made, trade-offs, constraints) - -**Access**: Only available via AI IDE slash prompts (Cursor, CoPilot, etc.) -**Pattern**: Slash prompt โ†’ LLM generates โ†’ CLI validates โ†’ Apply if valid - -## Three-Phase Workflow - -When working with AI IDE slash prompts, follow this three-phase workflow: - -### Phase 1: CLI Grounding (REQUIRED) +When you need exact syntax, verify against live help in the current release, for example: ```bash -# Execute CLI to get structured output -specfact [options] --no-interactive +specfact project sync bridge --help +specfact code repro --help +specfact code validate sidecar --help +specfact spec validate --help +specfact govern enforce --help ``` -**Capture**: - -- CLI-generated artifacts (project bundles, reports) -- Metadata (timestamps, confidence scores) -- Telemetry (execution time, file counts) - -### Phase 2: LLM Enrichment (OPTIONAL, Copilot Only) - -**Purpose**: Add semantic understanding to CLI output - -**What to do**: - -- Read CLI-generated artifacts (use file reading tools for display only) -- Research codebase for additional context -- Identify missing features/stories -- Suggest confidence adjustments -- Extract business context -- **CRITICAL**: Generate enrichment report in the exact format specified below (see "Enrichment Report Format" section) - -**What NOT to do**: - -- โŒ Create YAML/JSON artifacts directly -- โŒ Modify CLI artifacts directly (use CLI commands to update) -- โŒ Bypass CLI validation -- โŒ Write to `.specfact/` folder directly (always use CLI) -- โŒ Use direct file manipulation tools for writing (use CLI commands) -- โŒ Deviate from the enrichment report format (will cause parsing failures) - -**Output**: Generate enrichment report (Markdown) saved to `.specfact/projects//reports/enrichment/` (bundle-specific, Phase 8.5) - -**Enrichment Report Format** (REQUIRED for successful parsing): - -The enrichment parser expects a specific Markdown format. Follow this structure exactly: - -```markdown -# [Bundle Name] Enrichment Report - -**Date**: YYYY-MM-DDTHH:MM:SS -**Bundle**: - ---- - -## Missing Features - -1. **Feature Title** (Key: FEATURE-XXX) - - Confidence: 0.85 - - Outcomes: outcome1, outcome2, outcome3 - - Stories: - 1. Story title here - - Acceptance: criterion1, criterion2, criterion3 - 2. Another story title - - Acceptance: criterion1, criterion2 - -2. **Another Feature** (Key: FEATURE-YYY) - - Confidence: 0.80 - - Outcomes: outcome1, outcome2 - - Stories: - 1. Story title - - Acceptance: criterion1, criterion2, criterion3 - -## Confidence Adjustments - -- FEATURE-EXISTING-KEY: 0.90 (reason: improved understanding after code review) - -## Business Context - -- Priority: High priority feature for core functionality -- Constraint: Must support both REST and GraphQL APIs -- Risk: Potential performance issues with large datasets -``` - -**Format Requirements**: - -1. **Section Header**: Must use `## Missing Features` (case-insensitive, but prefer this exact format) -2. **Feature Format**: - - Numbered list: `1. **Feature Title** (Key: FEATURE-XXX)` - - **Bold title** is required (use `**Title**`) - - **Key in parentheses**: `(Key: FEATURE-XXX)` - must be uppercase, alphanumeric with hyphens/underscores - - Fields on separate lines with `-` prefix: - - `- Confidence: 0.85` (float between 0.0-1.0) - - `- Outcomes: comma-separated or line-separated list` - - `- Stories:` (required - each feature must have at least one story) -3. **Stories Format**: - - Numbered list under `Stories:` section: `1. Story title` - - **Indentation**: Stories must be indented (2-4 spaces) under the feature - - **Acceptance Criteria**: `- Acceptance: criterion1, criterion2, criterion3` - - Can be comma-separated on one line - - Or multi-line (each criterion on new line) - - Must start with `- Acceptance:` -4. **Optional Sections**: - - `## Confidence Adjustments`: List existing features with confidence updates - - `## Business Context`: Priorities, constraints, risks (bullet points) -5. **File Naming**: `-.enrichment.md` (e.g., `djangogoat-2025-12-23T23-50-00.enrichment.md`) - -**Example** (working format): - -```markdown -## Missing Features - -1. **User Authentication** (Key: FEATURE-USER-AUTHENTICATION) - - Confidence: 0.85 - - Outcomes: User registration, login, profile management - - Stories: - 1. User can sign up for new account - - Acceptance: sign_up view processes POST requests, creates User automatically, user is logged in after signup, redirects to profile page - 2. User can log in with credentials - - Acceptance: log_in view authenticates username/password, on success user is logged in and redirected, on failure error message is displayed -``` - -**Common Mistakes to Avoid**: - -- โŒ Missing `(Key: FEATURE-XXX)` - parser needs this to identify features -- โŒ Missing `Stories:` section - every feature must have at least one story -- โŒ Stories not indented - parser expects indented numbered lists -- โŒ Missing `- Acceptance:` prefix - acceptance criteria won't be parsed -- โŒ Using bullet points (`-`) instead of numbers (`1.`) for stories -- โŒ Feature title not in bold (`**Title**`) - parser may not extract title correctly - -**Important Notes**: - -- **Stories are merged**: When updating existing features (not creating new ones), stories from the enrichment report are merged into the existing feature. New stories are added, existing stories are preserved. -- **Feature titles updated**: If a feature exists but has an empty title, the enrichment report will update it. -- **Validation**: The enrichment parser validates the format and will fail with clear error messages if the format is incorrect. - -### Phase 3: CLI Artifact Creation (REQUIRED) - -```bash -# Use enrichment to update plan via CLI -specfact code import [] --repo --enrichment --no-interactive -``` - -**Result**: Final artifacts are CLI-generated with validated enrichments - -**What happens during enrichment application**: - -- Missing features are added with their stories and acceptance criteria -- Existing features are updated (confidence, outcomes, title if empty) -- Stories are merged into existing features (new stories added, existing preserved) -- Business context is applied to the project bundle -- All changes are validated and saved via CLI - -## Standard Validation Loop Pattern (For LLM-Generated Code) - -When generating or enhancing code via LLM, **ALWAYS** follow this pattern: - -```text -1. CLI Prompt Generation (Required) - โ†“ - CLI generates structured prompt โ†’ saved to .specfact/prompts/ - (e.g., `generate contracts-prompt`, future: `generate code-prompt`) - -2. LLM Execution (Required - AI IDE Only) - โ†“ - LLM reads prompt โ†’ generates enhanced code โ†’ writes to TEMPORARY file - (NEVER writes directly to original artifacts) - Pattern: `enhanced_.py` or `generated_.py` - -3. CLI Validation Loop (Required, up to N retries) - โ†“ - CLI validates temp file with all relevant tools: - - Syntax validation (py_compile) - - File size check (must be >= original) - - AST structure comparison (preserve functions/classes) - - Contract imports verification - - Code quality checks (ruff, pylint, basedpyright, mypy) - - Test execution (contract-test, pytest) - โ†“ - If validation fails: - - CLI provides detailed error feedback - - LLM fixes issues in temp file - - Re-validate (max 3 attempts) - โ†“ - If validation succeeds: - - CLI applies changes to original file - - CLI removes temporary file - - CLI updates metadata/telemetry -``` - -**This pattern must be used for**: - -- โœ… Contract enhancement (`generate contracts-prompt` / `contracts-apply`) - Already implemented -- โณ Code generation (future: `generate code-prompt` / `code-apply`) - Needs implementation -- โณ Plan enrichment (future: `plan enrich-prompt` / `enrich-apply`) - Needs implementation -- โณ Any LLM-enhanced artifact modification - Needs implementation - -## Example: Contract Enhancement Workflow - -This is a real example of the validation loop pattern in action: - -### Step 1: Generate Prompt - -```bash -specfact generate contracts-prompt src/auth/login.py --apply beartype,icontract --bundle legacy-api -``` - -**Result**: Prompt saved to `.specfact/projects/legacy-api/prompts/enhance-login-beartype-icontract.md` - -### Step 2: LLM Enhances Code - -1. AI IDE reads the prompt file -2. AI IDE reads the original file (`src/auth/login.py`) -3. AI IDE generates enhanced code with contracts -4. AI IDE writes to temporary file: `enhanced_login.py` -5. **DO NOT modify original file directly** - -### Step 3: Validate and Apply - -```bash -specfact generate contracts-apply enhanced_login.py --original src/auth/login.py -``` - -**Validation includes**: - -- Syntax validation -- File size check -- AST structure comparison -- Contract imports verification -- Code quality checks -- Test execution - -**If validation fails**: - -- Review error messages -- Fix issues in `enhanced_login.py` -- Re-run validation (up to 3 attempts) - -**If validation succeeds**: - -- CLI applies changes to `src/auth/login.py` -- CLI removes `enhanced_login.py` -- CLI updates metadata/telemetry - -## Why This Pattern? - -### Benefits - -- โœ… **Format Consistency**: All artifacts match CLI schema versions -- โœ… **Traceability**: CLI metadata tracks who/what/when -- โœ… **Validation**: CLI ensures schema compliance -- โœ… **Reliability**: Works in both Copilot and CI/CD -- โœ… **No Format Drift**: CLI-generated artifacts always match current schema - -### What Happens If You Don't Follow - -- โŒ Artifacts may not match CLI schema versions -- โŒ Missing metadata and telemetry -- โŒ Format inconsistencies -- โŒ Validation failures -- โŒ Works only in Copilot mode, fails in CI/CD -- โŒ Code generation attempts in CLI-only mode will fail (no LLM available) - -## Rules - -1. **Execute CLI First**: Always run CLI commands before any analysis -2. **Use CLI for Writes**: All write operations must go through CLI -3. **Read for Display Only**: Use file reading tools for display/analysis only -4. **Never Modify .specfact/**: Do not create/modify files in `.specfact/` directly -5. **Never Bypass Validation**: CLI ensures schema compliance and metadata -6. **Code Generation Requires LLM**: Code generation is only possible via AI IDE slash prompts, not CLI-only -7. **Use Validation Loop**: All LLM-generated code must follow the validation loop pattern - -## Available CLI Commands - -- `specfact plan init ` - Initialize project bundle -- `specfact plan select ` - Set active plan (used as default for other commands) -- `specfact code import [] --repo ` - Import from codebase (uses active plan if bundle not specified) -- `specfact plan compare [--bundle ]` - Review plan (uses active plan if bundle not specified) -- `specfact enforce sdd [--bundle ]` - Validate SDD compliance (uses active plan if bundle not specified) -- `specfact generate contracts-prompt --apply ` - Generate contract enhancement prompt -- `specfact generate contracts-apply --original ` - Validate and apply enhanced code -- `specfact sync bridge --adapter --repo ` - Sync with external tools -- See [Command Reference](../reference/commands.md) for full list - -**Note**: Most commands now support active plan fallback. If `--bundle` is not specified, commands automatically use the active plan set via `plan select`. This improves workflow efficiency in AI IDE environments. - ---- - -## Related Documentation - -- **[Architecture Documentation](../reference/architecture.md)** - Enforcement rules and quality gates -- **[Operational Modes](../reference/modes.md)** - CI/CD vs Copilot modes -- **[IDE Integration](ide-integration.md)** - Setting up slash commands -- **[Command Reference](../reference/commands.md)** - Complete command reference +This page needs a full rewrite around the mounted command groups before task-level workflow examples can be published again. diff --git a/docs/guides/ide-integration.md b/docs/guides/ide-integration.md index 90a99c1..f49ff0b 100644 --- a/docs/guides/ide-integration.md +++ b/docs/guides/ide-integration.md @@ -4,342 +4,29 @@ title: IDE Integration with SpecFact CLI permalink: /guides/ide-integration/ --- -# IDE Integration with SpecFact CLI +# Legacy Workflow Note -**Status**: โœ… **AVAILABLE** (v0.4.2+) -**Last Updated**: 2025-11-09 +This page described older `specfact plan`, `specfact generate`, `specfact contract`, or `specfact sdd constitution` workflows that are not part of the current public mounted CLI in this repository. The detailed command examples previously documented here were removed because they no longer match the command surface exposed by `specfact --help`. -**CLI-First Approach**: SpecFact works offline, requires no account, and integrates with your existing workflow. Works with VS Code, Cursor, GitHub Actions, pre-commit hooks, or any IDE. No platform to learn, no vendor lock-in. +Use the current mounted entrypoints instead: -**Terminal Output**: The CLI automatically detects embedded terminals (Cursor, VS Code) and CI/CD environments, adapting output formatting automatically. Progress indicators work in all environments - see [Troubleshooting](troubleshooting.md#terminal-output-issues) for details. +- `specfact project --help` +- `specfact project sync --help` +- `specfact code --help` +- `specfact code review --help` +- `specfact spec --help` +- `specfact govern --help` +- `specfact backlog --help` +- `specfact module --help` ---- - -## Overview - -SpecFact CLI supports IDE integration through **prompt templates** that work with various AI-assisted IDEs. These templates are copied to IDE-specific locations and automatically registered by the IDE as slash commands. - -**See real examples**: [Integration Showcases](../examples/integration-showcases/) - 5 complete examples showing bugs fixed via IDE integrations - -**Supported IDEs:** - -- โœ… **Cursor** - `.cursor/commands/` -- โœ… **VS Code / GitHub Copilot** - `.github/prompts/` + `.vscode/settings.json` -- โœ… **Claude Code** - `.claude/commands/` -- โœ… **Gemini CLI** - `.gemini/commands/` -- โœ… **Qwen Code** - `.qwen/commands/` -- โœ… **opencode** - `.opencode/command/` -- โœ… **Windsurf** - `.windsurf/workflows/` -- โœ… **Kilo Code** - `.kilocode/workflows/` -- โœ… **Auggie** - `.augment/commands/` -- โœ… **Roo Code** - `.roo/commands/` -- โœ… **CodeBuddy** - `.codebuddy/commands/` -- โœ… **Amp** - `.agents/commands/` -- โœ… **Amazon Q Developer** - `.amazonq/prompts/` - ---- - -## Quick Start - -### Step 1: Initialize IDE Integration - -Run the `specfact init` command in your repository: - -```bash -# Auto-detect IDE -specfact init - -# Or specify IDE explicitly -specfact init ide --ide cursor -specfact init ide --ide vscode -specfact init ide --ide copilot - -# Install required packages for contract enhancement -specfact init --install-deps - -# Initialize for specific IDE and install dependencies -specfact init ide --ide cursor --install-deps -``` - -**What it does:** - -1. Detects your IDE (or uses `--ide` flag) -2. Copies prompt templates from `resources/prompts/` to IDE-specific location -3. Creates/updates VS Code settings if needed -4. Makes slash commands available in your IDE -5. Optionally installs required packages for contract enhancement (if `--install-deps` is provided): - - `beartype>=0.22.4` - Runtime type checking - - `icontract>=2.7.1` - Design-by-contract decorators - - `crosshair-tool>=0.0.97` - Contract exploration - - `pytest>=8.4.2` - Testing framework - -### Step 2: Use Slash Commands in Your IDE - -Once initialized, you can use slash commands directly in your IDE's AI chat: - -**In Cursor / VS Code / Copilot:** +When you need exact syntax, verify against live help in the current release, for example: ```bash -# Core workflow commands (numbered for natural progression) -/specfact.01-import legacy-api --repo . -/specfact.02-plan init legacy-api -/specfact.02-plan add-feature --bundle legacy-api --key FEATURE-001 --title "User Auth" -/specfact.03-review legacy-api -/specfact.04-sdd legacy-api -/specfact.05-enforce legacy-api -/specfact.06-sync --adapter speckit --repo . --bidirectional -/specfact.07-contracts legacy-api --apply all-contracts # Analyze, generate prompts, apply contracts sequentially - -# Advanced commands -/specfact.compare --bundle legacy-api -/specfact.validate --repo . +specfact project sync bridge --help +specfact code repro --help +specfact code validate sidecar --help +specfact spec validate --help +specfact govern enforce --help ``` -The IDE automatically recognizes these commands and provides enhanced prompts. - ---- - -## How It Works - -### Prompt Templates - -Slash commands are **markdown prompt templates** (not executable CLI commands). They: - -1. **Live in your repository** - Templates are stored in `resources/prompts/` (packaged with SpecFact CLI) -2. **Get copied to IDE locations** - `specfact init` copies them to IDE-specific directories -3. **Registered automatically** - The IDE reads these files and makes them available as slash commands -4. **Provide enhanced prompts** - Templates include detailed instructions for the AI assistant - -### Template Format - -Each template follows this structure: - -```markdown ---- -description: Command description for IDE display ---- - -## User Input - -```text -$ARGUMENTS -``` - -## Goal - -Detailed instructions for the AI assistant... - -## Execution Steps - -1. Parse arguments... - -2. Execute command... - -3. Generate output... - -```text - -### IDE Registration - -**How IDEs discover slash commands:** - -- **VS Code / Copilot**: Reads `.github/prompts/*.prompt.md` files listed in `.vscode/settings.json` under `chat.promptFilesRecommendations` -- **Cursor**: Automatically discovers `.cursor/commands/*.md` files -- **Other IDEs**: Follow their respective discovery mechanisms - ---- - -## Available Slash Commands - -**Complete Reference**: [Prompts README](../prompts/README.md) - Full slash commands reference with examples - -**Workflow Guide**: [AI IDE Workflow Guide](ai-ide-workflow.md) - Complete workflow from setup to validation - -## Available Slash Commands - -**Core Workflow Commands** (numbered for workflow ordering): - -| Command | Description | CLI Equivalent | -|---------|-------------|----------------| -| `/specfact.01-import` | Import codebase into project bundle | `specfact code import ` | -| `/specfact.02-plan` | Plan management (init, add-feature, add-story, update-idea, update-feature, update-story) | `specfact plan ` | -| `/specfact.03-review` | Review plan and select active bundle | `specfact plan compare --bundle `, `specfact plan select` | -| `/specfact.04-sdd` | Create SDD manifest from plan | `specfact enforce sdd --bundle ` | -| `/specfact.05-enforce` | Validate SDD and contracts | `specfact enforce sdd ` | -| `/specfact.06-sync` | Sync with external tools or repository | `specfact sync bridge --adapter ` | -| `/specfact.07-contracts` | Contract enhancement workflow: analyze โ†’ generate prompts โ†’ apply sequentially | `specfact analyze contracts`, `specfact generate contracts-prompt`, `specfact generate contracts-apply` | - -**Advanced Commands** (no numbering): - -| Command | Description | CLI Equivalent | -|---------|-------------|----------------| -| `/specfact.compare` | Compare manual vs auto plans | `specfact plan compare` | -| `/specfact.validate` | Run validation suite | `specfact repro` | -| `/specfact.generate-contracts-prompt` | Generate AI IDE prompt for adding contracts | `specfact generate contracts-prompt --apply ` | - ---- - -## Examples - -### Example 1: Initialize for Cursor - -```bash -# Run init in your repository -cd /path/to/my-project -specfact init ide --ide cursor - -# Output: -# โœ“ Initialization Complete -# Copied 5 template(s) to .cursor/commands/ -# -# You can now use SpecFact slash commands in Cursor! -# Example: /specfact.01-import legacy-api --repo . -``` - -**Now in Cursor:** - -1. Open Cursor AI chat -2. Type `/specfact.01-import legacy-api --repo .` -3. Cursor recognizes the command and provides enhanced prompts - -### Example 2: Initialize for VS Code / Copilot - -```bash -# Run init in your repository -specfact init ide --ide vscode - -# Output: -# โœ“ Initialization Complete -# Copied 5 template(s) to .github/prompts/ -# Updated VS Code settings: .vscode/settings.json - -``` - -**VS Code settings.json:** - -```json -{ - "chat": { - "promptFilesRecommendations": [ - ".github/prompts/specfact.01-import.prompt.md", - ".github/prompts/specfact.02-plan.prompt.md", - ".github/prompts/specfact.03-review.prompt.md", - ".github/prompts/specfact.04-sdd.prompt.md", - ".github/prompts/specfact.05-enforce.prompt.md", - ".github/prompts/specfact.06-sync.prompt.md", - ".github/prompts/specfact.07-contracts.prompt.md", - ".github/prompts/specfact.compare.prompt.md", - ".github/prompts/specfact.validate.prompt.md" - ] - } -} -``` - -### Example 3: Update Templates - -If you update SpecFact CLI, run `init` again to update templates: - -```bash -# Re-run init to update templates (use --force to overwrite) -specfact init ide --ide cursor --force -``` - ---- - -## Advanced Usage - -### Custom Template Locations - -By default, templates are copied from SpecFact CLI's package resources. To use custom templates: - -1. Create your own templates in a custom location -2. Modify `specfact init` to use custom path (future feature) - -### IDE-Specific Customization - -Different IDEs may require different template formats: - -- **Markdown** (Cursor, Claude, etc.): Direct `.md` files -- **TOML** (Gemini, Qwen): Converted to TOML format automatically -- **VS Code**: `.prompt.md` files with settings.json integration - -The `specfact init` command handles all conversions automatically. - ---- - -## Troubleshooting - -### Slash Commands Not Showing in IDE - -**Issue**: Commands don't appear in IDE autocomplete - -**Solutions:** - -1. **Verify files exist:** - - ```bash - ls .cursor/commands/specfact-*.md # For Cursor - ls .github/prompts/specfact-*.prompt.md # For VS Code - - ``` - -2. **Re-run init:** - - ```bash - specfact init ide --ide cursor --force - ``` - -3. **Restart IDE**: Some IDEs require restart to discover new commands - -### VS Code Settings Not Updated - -**Issue**: VS Code settings.json not created or updated - -**Solutions:** - -1. **Check permissions:** - - ```bash - ls -la .vscode/settings.json - - ``` - -2. **Manually verify settings.json:** - - ```json - { - "chat": { - "promptFilesRecommendations": [...] - } - } - - ``` - -3. **Re-run init:** - - ```bash - specfact init ide --ide vscode --force - ``` - ---- - -## Related Documentation - -- [Command Reference](../reference/commands.md) - All CLI commands -- [CoPilot Mode Guide](copilot-mode.md) - Using `--mode copilot` on CLI -- [Getting Started](../getting-started/installation.md) - Installation and setup -- [Troubleshooting](troubleshooting.md#terminal-output-issues) - Terminal output auto-detection in embedded terminals - ---- - -## Next Steps - -- โญ **[Integration Showcases](../examples/integration-showcases/)** - See real bugs fixed via VS Code, Cursor, GitHub Actions integrations -- โœ… Initialize IDE integration with `specfact init` -- โœ… Use slash commands in your IDE -- ๐Ÿ“– Read [CoPilot Mode Guide](copilot-mode.md) for CLI usage -- ๐Ÿ“– Read [Command Reference](../reference/commands.md) for all commands - ---- - -**Trademarks**: All product names, logos, and brands mentioned in this guide 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](../../TRADEMARKS.md) for more information. +This page needs a full rewrite around the mounted command groups before task-level workflow examples can be published again. diff --git a/docs/guides/import-features.md b/docs/guides/import-features.md index 1cd0ee0..a660049 100644 --- a/docs/guides/import-features.md +++ b/docs/guides/import-features.md @@ -6,11 +6,11 @@ permalink: /guides/import-features/ # Import Command Features -This guide covers advanced features and optimizations in the `import from-code` command. +This guide covers advanced features and optimizations in the `code import` command. ## Overview -The `import from-code` command has been optimized for large codebases and includes several features to improve reliability, performance, and user experience: +The `code import` command has been optimized for large codebases and includes several features to improve reliability, performance, and user experience: - **Progress Reporting**: Real-time progress bars for long-running operations - **Feature Validation**: Automatic validation of existing features when resuming imports diff --git a/docs/guides/installing-modules.md b/docs/guides/installing-modules.md index d83ee8d..fa89c6d 100644 --- a/docs/guides/installing-modules.md +++ b/docs/guides/installing-modules.md @@ -14,21 +14,21 @@ Use plain `specfact ...` commands in this guide (not `hatch run specfact ...`) s ```bash # Marketplace id format -specfact module install specfact/backlog +specfact module install nold-ai/specfact-backlog -# Bare names are accepted and normalized to specfact/ -specfact module install backlog +# Short names are accepted when they resolve unambiguously +specfact module install specfact-backlog # Install into project scope instead of user scope -specfact module install backlog --scope project --repo /path/to/repo +specfact module install nold-ai/specfact-backlog --scope project --repo /path/to/repo # Force bundled-only or marketplace-only source resolution -specfact module install backlog --source bundled -specfact module install backlog --source marketplace -specfact module install backlog --source marketplace --trust-non-official +specfact module install nold-ai/specfact-backlog --source bundled +specfact module install nold-ai/specfact-backlog --source marketplace +specfact module install nold-ai/specfact-backlog --source marketplace --trust-non-official # Install a specific version -specfact module install specfact/backlog --version 0.35.0 +specfact module install nold-ai/specfact-backlog --version 0.41.12 ``` Notes: @@ -46,13 +46,13 @@ Before installing a marketplace module, SpecFact resolves its dependencies (othe ```bash # Install with dependency resolution (default) -specfact module install specfact/backlog +specfact module install nold-ai/specfact-backlog # Skip dependency resolution (install only the requested module) -specfact module install specfact/backlog --skip-deps +specfact module install nold-ai/specfact-backlog --skip-deps # Force install despite dependency conflicts (use with care) -specfact module install specfact/backlog --force +specfact module install nold-ai/specfact-backlog --force ``` - Use `--skip-deps` when you want to install a single module without pulling its dependencies or when you manage dependencies yourself. @@ -170,9 +170,9 @@ Use `--force` to allow dependency-aware cascades when required. ## Uninstall Behavior ```bash -specfact module uninstall backlog -specfact module uninstall specfact/backlog -specfact module uninstall backlog --scope project --repo /path/to/repo +specfact module uninstall specfact-backlog +specfact module uninstall nold-ai/specfact-backlog +specfact module uninstall nold-ai/specfact-backlog --scope project --repo /path/to/repo ``` Uninstall supports user and project scope roots. diff --git a/docs/guides/integrations-overview.md b/docs/guides/integrations-overview.md index d44efd3..4dad320 100644 --- a/docs/guides/integrations-overview.md +++ b/docs/guides/integrations-overview.md @@ -243,7 +243,7 @@ Use this decision tree to determine which integrations to use: Start: What do you need? โ”œโ”€ Need to work with existing code? -โ”‚ โ””โ”€ โœ… Use SpecFact CLI `import from-code` (brownfield analysis) +โ”‚ โ””โ”€ โœ… Use SpecFact CLI `code import` (brownfield analysis) โ”‚ โ”œโ”€ Need to create new features interactively? โ”‚ โ””โ”€ โœ… Use Spec-Kit integration (greenfield development) @@ -270,7 +270,7 @@ Start: What do you need? #### 1. Brownfield Modernization with OpenSpec and DevOps Integration -- Use SpecFact CLI `import from-code` to analyze existing code +- Use SpecFact CLI `code import` to analyze existing code - Export to OpenSpec for specification anchoring - Use OpenSpec change proposals for tracking improvements - **Sync proposals to GitHub Issues via DevOps adapter** - Integrate into agile DevOps workflows diff --git a/docs/guides/migration-0.16-to-0.19.md b/docs/guides/migration-0.16-to-0.19.md index 646196e..ee01927 100644 --- a/docs/guides/migration-0.16-to-0.19.md +++ b/docs/guides/migration-0.16-to-0.19.md @@ -1,174 +1,15 @@ -# Migration Guide: v0.16.x to v0.20.0 LTS +# Legacy Workflow Note -This guide helps you upgrade from SpecFact CLI v0.16.x to v0.20.0 LTS (Long-Term Stable). +This page referenced command groups or workflow steps that are no longer part of the current public mounted CLI in this repository. The old examples were removed to avoid directing readers to unavailable commands. -## Overview +Use the current mounted entrypoints instead: -v0.17.0 - v0.20.0 are part of the **0.x stabilization track** leading to v0.20.0 LTS. +- `specfact project --help` +- `specfact project sync --help` +- `specfact code --help` +- `specfact code review --help` +- `specfact spec --help` +- `specfact govern --help` +- `specfact backlog --help` -### Key Changes - -| Version | Changes | -|---------|---------| -| **0.17.0** | Deprecated `implement` command, added bridge commands, version management | -| **0.18.0** | Updated documentation positioning, AI IDE bridge workflow | -| **0.19.0** | Full test coverage for Phase 7, migration guide | -| **0.20.0 LTS** | Long-Term Stable release - production-ready analysis and enforcement | - ---- - -## Breaking Changes - -### `implement` Command Deprecated - -The `implement tasks` command was deprecated in v0.17.0 and removed in v0.22.0. The `generate tasks` command was also removed in v0.22.0. - -**Before (v0.16.x):** - -```bash -specfact implement tasks .specfact/projects/my-bundle/tasks.yaml -``` - -**After (v0.17.0+):** - -Use the new bridge commands instead: - -```bash -# Set up CrossHair for contract exploration (one-time setup, only available since v0.20.1) -specfact repro setup - -# Analyze and validate your codebase -specfact repro --verbose - -# Generate AI-ready prompt to fix a gap -specfact generate fix-prompt GAP-001 --bundle my-bundle - -# Generate AI-ready prompt to add tests -specfact generate test-prompt src/auth/login.py --bundle my-bundle -``` - -### `run idea-to-ship` Removed - -The `run idea-to-ship` command has been removed in v0.17.0. - -**Rationale:** Code generation features are being redesigned for v1.0 with AI-assisted workflows. - ---- - -## New Features - -### Bridge Commands (v0.17.0) - -New commands that generate AI-ready prompts for your IDE: - -```bash -# Generate fix prompt for a gap -specfact generate fix-prompt GAP-001 - -# Generate test prompt for a file -specfact generate test-prompt src/module.py --type unit -``` - -### Version Management (v0.17.0) - -New commands for managing bundle versions: - -```bash -# Check for recommended version bump -specfact project version check --bundle my-bundle - -# Bump version (major/minor/patch) -specfact project version bump --bundle my-bundle --type minor - -# Set explicit version -specfact project version set --bundle my-bundle --version 2.0.0 -``` - -### CI Version Check (v0.17.0) - -GitHub Actions template now includes version check with configurable modes: - -- `info` - Informational only -- `warn` (default) - Log warnings, continue CI -- `block` - Fail CI if version bump not followed - ---- - -## Upgrade Steps - -### Step 1: Update SpecFact CLI - -```bash -pip install -U specfact-cli -# or -uvx specfact-cli@latest --version -``` - -### Step 2: Verify Version - -```bash -specfact --version -# Should show: SpecFact CLI version 0.19.0 -``` - -### Step 3: Update Workflows - -If you were using `implement tasks` or `run idea-to-ship`, migrate to bridge commands: - -**Old workflow:** - -```bash -# REMOVED in v0.22.0 - Use Spec-Kit, OpenSpec, or other SDD tools instead -# specfact generate tasks --bundle my-bundle -# specfact implement tasks .specfact/projects/my-bundle/tasks.yaml -``` - -**New workflow:** - -```bash -# 1. Analyze and validate your codebase -specfact repro --verbose - -# 2. Generate AI prompts for each gap -specfact generate fix-prompt GAP-001 --bundle my-bundle - -# 3. Copy prompt to AI IDE, get fix, apply - -# 4. Validate -specfact enforce sdd --bundle my-bundle -``` - -### Step 4: Update CI/CD (Optional) - -Add version check to your GitHub Actions: - -```yaml -- name: Version Check - run: specfact project version check --bundle ${{ env.BUNDLE_NAME }} - env: - SPECFACT_VERSION_CHECK_MODE: warn # or 'info' or 'block' -``` - ---- - -## FAQ - -### Q: Why was `implement` deprecated? - -**A:** The `implement` command attempted to generate code directly, but this approach doesn't align with the Ultimate Vision for v1.0. In v1.0, AI copilots will consume structured data from SpecFact and generate code, with SpecFact validating the results. The bridge commands provide a transitional workflow. - -### Q: Can I still use v0.16.x? - -**A:** Yes, v0.16.x will continue to work. However, we recommend upgrading to v0.20.0 LTS for the latest fixes, features, and long-term stability. v0.20.0 is the Long-Term Stable (LTS) release and will receive bug fixes and security updates until v1.0 GA. - -### Q: When will v1.0 be released? - -**A:** See the [GitHub Discussions](https://github.com/nold-ai/specfact-cli/discussions) for the v1.0 roadmap. - ---- - -## Support - -- ๐Ÿ’ฌ **Questions?** [GitHub Discussions](https://github.com/nold-ai/specfact-cli/discussions) -- ๐Ÿ› **Found a bug?** [GitHub Issues](https://github.com/nold-ai/specfact-cli/issues) -- ๐Ÿ“ง **Need help?** [hello@noldai.com](mailto:hello@noldai.com) +For exact syntax, verify against live help in the current release before copying examples. diff --git a/docs/guides/migration-cli-reorganization.md b/docs/guides/migration-cli-reorganization.md index 09fdab9..951c313 100644 --- a/docs/guides/migration-cli-reorganization.md +++ b/docs/guides/migration-cli-reorganization.md @@ -1,303 +1,26 @@ -# CLI Reorganization Migration Guide +# Legacy Workflow Note -**Date**: 2025-11-27 -**Version**: 0.9.3+ +This page described older `specfact plan`, `specfact generate`, `specfact contract`, or `specfact sdd constitution` workflows that are not part of the current public mounted CLI in this repository. The detailed command examples previously documented here were removed because they no longer match the command surface exposed by `specfact --help`. -This guide helps you migrate from the old command structure to the new reorganized structure, including parameter standardization, slash command changes, and bundle parameter integration. +Use the current mounted entrypoints instead: ---- +- `specfact project --help` +- `specfact project sync --help` +- `specfact code --help` +- `specfact code review --help` +- `specfact spec --help` +- `specfact govern --help` +- `specfact backlog --help` +- `specfact module --help` -## Overview of Changes - -The CLI reorganization includes: - -1. **Parameter Standardization** - Consistent parameter names across all commands -2. **Parameter Grouping** - Logical organization (Target โ†’ Output โ†’ Behavior โ†’ Advanced) -3. **Slash Command Reorganization** - Reduced from 13 to 8 commands with numbered workflow ordering -4. **Bundle Parameter Integration** - All commands now use `--bundle` parameter - ---- - -## Parameter Name Changes - -### Standard Parameter Names - -| Old Name | New Name | Commands Affected | -|----------|----------|-------------------| -| `--base-path` | `--repo` | `generate contracts` | -| `--output` | `--out` | `bridge constitution bootstrap` | -| `--format` | `--output-format` | `enforce sdd`, `plan compare` | -| `--non-interactive` | `--no-interactive` | All commands | -| `--name` (bundle name) | `--bundle` | All commands | - -### Deprecation Policy - -- **Transition Period**: 3 months from implementation date (2025-11-27) -- **Deprecation Warnings**: Commands using deprecated names will show warnings -- **Removal**: Deprecated names will be removed after transition period -- **Documentation**: All examples and docs updated immediately - -### Examples - -**Before**: - -```bash -specfact generate contracts --base-path . -specfact plan compare --bundle legacy-api --format json --out report.json -specfact enforce sdd legacy-api --non-interactive -``` - -**After**: - -```bash -specfact generate contracts --repo . -specfact plan compare --bundle legacy-api --output-format json --out report.json -specfact enforce sdd legacy-api --no-interactive -``` - ---- - -## Slash Command Changes - -### Old Slash Commands (13 total) โ†’ New Slash Commands (8 total) - -| Old Command | New Command | Notes | -|-------------|-------------|-------| -| `/specfact-import-from-code` | `/specfact.01-import` | Numbered for workflow ordering | -| `/specfact-plan-init` | `/specfact.02-plan` | Unified plan management | -| `/specfact-plan-add-feature` | `/specfact.02-plan` | Merged into plan command | -| `/specfact-plan-add-story` | `/specfact.02-plan` | Merged into plan command | -| `/specfact-plan-update-idea` | `/specfact.02-plan` | Merged into plan command | -| `/specfact-plan-update-feature` | `/specfact.02-plan` | Merged into plan command | -| `/specfact-plan-review` | `/specfact.03-review` | Numbered for workflow ordering | -| `/specfact-plan-promote` | `/specfact.03-review` | Merged into review command | -| `/specfact-plan-compare` | `/specfact.compare` | Advanced command (no numbering) | -| `/specfact-enforce` | `/specfact.05-enforce` | Numbered for workflow ordering | -| `/specfact-sync` | `/specfact.06-sync` | Numbered for workflow ordering | -| `/specfact-repro` | `/specfact.validate` | Advanced command (no numbering) | -| `/specfact-plan-select` | *(CLI-only)* | Removed (use CLI directly) | - -### Workflow Ordering - -The new numbered commands follow natural workflow progression: - -1. **Import** (`/specfact.01-import`) - Start by importing existing code -2. **Plan** (`/specfact.02-plan`) - Manage your project bundle -3. **Review** (`/specfact.03-review`) - Review and promote your plan -4. **SDD** (`/specfact.04-sdd`) - Create SDD manifest -5. **Enforce** (`/specfact.05-enforce`) - Validate SDD and contracts -6. **Sync** (`/specfact.06-sync`) - Sync with external tools - -**Advanced Commands** (no numbering): - -- `/specfact.compare` - Compare plans -- `/specfact.validate` - Validation suite - -### Ordered Workflow Examples - -**Before**: - -```bash -/specfact-import-from-code --repo . --confidence 0.7 -/specfact-plan-init my-project -/specfact-plan-add-feature --key FEATURE-001 --title "User Auth" -/specfact-plan-review my-project -``` - -**After**: - -```bash -/specfact.01-import legacy-api --repo . --confidence 0.7 -/specfact.02-plan init legacy-api -/specfact.02-plan add-feature --bundle legacy-api --key FEATURE-001 --title "User Auth" -/specfact.03-review legacy-api -``` - ---- - -## Bundle Parameter Addition - -### All Commands Now Require `--bundle` - -**Before** (positional argument): - -```bash -specfact plan init legacy-api -specfact plan compare --bundle legacy-api -``` - -**After** (named parameter): - -```bash -specfact plan init legacy-api -specfact plan compare --bundle legacy-api -``` - -### Path Resolution Changes - -- **Old**: Used positional argument or `--name` for bundle identification -- **New**: Uses `--bundle` parameter for bundle name -- **Path**: Bundle path is resolved from bundle name: `.specfact/projects//` - -### Migration Steps - -1. **Update all scripts** to use `--bundle` instead of positional arguments -2. **Update CI/CD pipelines** to use new parameter format -3. **Update IDE slash commands** to use new numbered format -4. **Test workflows** to ensure bundle resolution works correctly - ---- - -## Command Path Changes - -### Constitution Commands - -**Current Command**: +When you need exact syntax, verify against live help in the current release, for example: ```bash -specfact sdd constitution bootstrap -specfact sdd constitution enrich -specfact sdd constitution validate +specfact project sync bridge --help +specfact code repro --help +specfact code validate sidecar --help +specfact spec validate --help +specfact govern enforce --help ``` -**Note**: The old `specfact constitution` command has been removed. All constitution functionality is now available under `specfact sdd constitution`. - ---- - -## Why the Change? - -The constitution commands are **Spec-Kit adapter commands** - they're only needed when syncing with Spec-Kit or working in Spec-Kit format. They are now under the `sdd` (Spec-Driven Development) command group, as constitution management is part of the SDD workflow. - -**Benefits**: - -- Clearer command organization (adapters grouped together) -- Better aligns with bridge architecture -- Makes it obvious these are for external tool integration - ---- - -## Command Changes - -The old `specfact constitution` command has been removed. Use `specfact sdd constitution` instead: - -```bash -$ specfact constitution bootstrap --repo . -โš  Breaking Change: The 'specfact constitution' command has been removed. -Please use 'specfact sdd constitution' instead. -Example: 'specfact constitution bootstrap' โ†’ 'specfact sdd constitution bootstrap' - -[bold cyan]Generating bootstrap constitution for:[/bold cyan] . -... -``` - ---- - -## Updated Workflows - -### Brownfield Import Workflow - -```bash -specfact code import legacy-api --repo . -specfact sdd constitution bootstrap --repo . -specfact sync bridge --adapter speckit -``` - -### Constitution Management Workflow - -```bash -specfact sdd constitution bootstrap --repo . -specfact sdd constitution validate -specfact sdd constitution enrich --repo . -``` - ---- - -## CI/CD Updates - -Update your CI/CD pipelines to use the new command paths: - -**GitHub Actions Example**: - -```yaml -- name: Validate Constitution - run: specfact sdd constitution validate -``` - -**GitLab CI Example**: - -```yaml -validate_constitution: - script: - - specfact sdd constitution validate -``` - ---- - -## Script Updates - -Update any scripts that use the old commands: - -**Bash Script Example**: - -```bash -#!/bin/bash -# Old -# specfact constitution bootstrap --repo . - -# New -specfact sdd constitution bootstrap --repo . -``` - -**Python Script Example**: - -```python -# Old -# subprocess.run(["specfact", "constitution", "bootstrap", "--repo", "."]) - -# New -subprocess.run(["specfact", "sdd", "constitution", "bootstrap", "--repo", "."]) -``` - ---- - -## IDE Integration - -If you're using IDE slash commands, update your prompts: - -**Old**: - -```bash -/specfact-plan-init legacy-api -``` - -**New**: - -```bash -/specfact.02-plan init legacy-api -``` - ---- - -## Module System Migration Note - -This CLI reorganization aligns with the module-first architecture: - -- Core runtime remains responsible for lifecycle, registry, and orchestration. -- Feature command implementations belong in `src/specfact_cli/modules//src/commands.py`. -- Legacy `src/specfact_cli/commands/*.py` files are compatibility shims only. - -When updating internal tooling or extensions, prefer module-local imports over shim imports. - ---- - -## Questions? - -If you encounter any issues during migration: - -1. Check the [Command Reference](../reference/commands.md) for updated examples -2. Review the [Troubleshooting Guide](./troubleshooting.md) -3. Open an issue on GitHub - ---- - -**Last Updated**: 2025-01-27 +This page needs a full rewrite around the mounted command groups before task-level workflow examples can be published again. diff --git a/docs/guides/migration-guide.md b/docs/guides/migration-guide.md index 6efbc3b..a7775af 100644 --- a/docs/guides/migration-guide.md +++ b/docs/guides/migration-guide.md @@ -4,236 +4,29 @@ title: Migration Guide permalink: /migration-guide/ --- -# Migration Guide +# Legacy Workflow Note -> **Decision tree and workflow for migrating between SpecFact CLI versions and from other tools** +This page described older `specfact plan`, `specfact generate`, `specfact contract`, or `specfact sdd constitution` workflows that are not part of the current public mounted CLI in this repository. The detailed command examples previously documented here were removed because they no longer match the command surface exposed by `specfact --help`. ---- - -## Overview - -This guide helps you decide when and how to migrate: - -- **Between SpecFact CLI versions** - When upgrading to a new version -- **From other tools** - When migrating from Spec-Kit, OpenSpec, or other SDD tools -- **Between project structures** - When restructuring your project bundles - ---- - -## Migration Decision Tree - -``` -Start: What do you need to migrate? - -โ”œโ”€ Upgrading SpecFact CLI version? -โ”‚ โ”œโ”€ Minor version (0.19 โ†’ 0.20)? -โ”‚ โ”‚ โ””โ”€ โ†’ Usually automatic, check [Version-Specific Migration Guides](#version-specific-migrations) -โ”‚ โ”œโ”€ Major version (0.x โ†’ 1.0)? -โ”‚ โ”‚ โ””โ”€ โ†’ Check breaking changes, use [Version-Specific Migration Guides](#version-specific-migrations) -โ”‚ โ””โ”€ CLI reorganization (pre-0.16 โ†’ 0.16+)? -โ”‚ โ””โ”€ โ†’ See [CLI Reorganization Migration](migration-cli-reorganization.md) -โ”‚ -โ”œโ”€ Migrating from Spec-Kit? -โ”‚ โ””โ”€ โ†’ See [Spec-Kit Journey Guide](speckit-journey.md) -โ”‚ -โ”œโ”€ Migrating from OpenSpec? -โ”‚ โ””โ”€ โ†’ See [OpenSpec Journey Guide](openspec-journey.md) -โ”‚ -โ””โ”€ Restructuring project bundles? - โ””โ”€ โ†’ See [Project Bundle Management](../reference/commands.md#project---project-bundle-management) -``` - ---- - -## Version-Specific Migrations - -### Migration from 0.16 to 0.19+ - -**Breaking Changes**: CLI command reorganization - -**Migration Steps**: - -1. Review [CLI Reorganization Migration Guide](migration-cli-reorganization.md) -2. Update scripts and CI/CD pipelines -3. Test commands in development environment -4. Update documentation references - -**Related**: [Migration 0.16 to 0.19](migration-0.16-to-0.19.md) - ---- - -### Migration from Pre-0.16 to 0.16+ - -**Breaking Changes**: Major CLI reorganization - -**Migration Steps**: - -1. Review [CLI Reorganization Migration Guide](migration-cli-reorganization.md) -2. Update all command references -3. Migrate project bundles to new schema -4. Update CI/CD configurations +Use the current mounted entrypoints instead: -**Related**: [CLI Reorganization Migration](migration-cli-reorganization.md) +- `specfact project --help` +- `specfact project sync --help` +- `specfact code --help` +- `specfact code review --help` +- `specfact spec --help` +- `specfact govern --help` +- `specfact backlog --help` +- `specfact module --help` ---- - -## Tool Migration Workflows - -### Migrating from Spec-Kit - -**Workflow**: Use External Tool Integration Chain - -1. Import from Spec-Kit via bridge adapter -2. Review imported plan -3. Set up bidirectional sync (optional) -4. Enforce SDD compliance - -**Detailed Guide**: [Spec-Kit Journey Guide](speckit-journey.md) - -**Command Chain**: [External Tool Integration Chain](command-chains.md#3-external-tool-integration-chain) - ---- - -### Migrating from OpenSpec - -**Workflow**: Use External Tool Integration Chain - -1. Import from OpenSpec via bridge adapter -2. Review imported change proposals -3. Set up DevOps sync (optional) -4. Enforce SDD compliance - -**Detailed Guide**: [OpenSpec Journey Guide](openspec-journey.md) - -**Command Chain**: [External Tool Integration Chain](command-chains.md#3-external-tool-integration-chain) - ---- - -## Project Structure Migrations - -### Migrating Between Project Bundles - -**When to use**: Restructuring projects, splitting/merging bundles - -**Commands**: +When you need exact syntax, verify against live help in the current release, for example: ```bash -# Export from old bundle -specfact project export --bundle old-bundle --persona - -# Create new bundle -specfact plan init new-bundle - -# Import to new bundle (manual editing may be required) -specfact project import --bundle new-bundle --persona --source exported.md +specfact project sync bridge --help +specfact code repro --help +specfact code validate sidecar --help +specfact spec validate --help +specfact govern enforce --help ``` -**Related**: [Project Bundle Management](../reference/commands.md#project---project-bundle-management) - ---- - -## Plan Schema Migrations - -### Upgrading Project Bundles - -**When to use**: When project bundles are on an older schema version - -**Command**: - -```bash -# Upgrade all bundles -specfact plan upgrade --all - -# Upgrade specific bundle -specfact plan upgrade --bundle -``` - -**Benefits**: - -- Improved performance (44% faster `plan select`) -- New features and metadata -- Better compatibility - -**Related**: [Plan Upgrade](../reference/commands.md#plan-upgrade) - ---- - -## Migration Workflow Examples - -### Example 1: Upgrading SpecFact CLI - -```bash -# 1. Check current version -specfact --version - -# 2. Review migration guide for target version -# See: guides/migration-*.md - -# 3. Upgrade SpecFact CLI -pip install --upgrade specfact-cli - -# 4. Upgrade project bundles -specfact plan upgrade --all - -# 5. Test commands -specfact plan select --last 5 -``` - ---- - -### Example 2: Migrating from Spec-Kit - -```bash -# 1. Import from Spec-Kit -specfact sync bridge --repo . --adapter speckit --write - -# 2. Review imported plan -specfact plan compare --bundle - -# 3. Set up bidirectional sync (optional) -specfact sync bridge --adapter speckit --bundle --bidirectional --watch - -# 4. Enforce SDD compliance -specfact enforce sdd --bundle -``` - -**Related**: [Spec-Kit Journey Guide](speckit-journey.md) - ---- - -## Troubleshooting Migrations - -### Common Issues - -**Issue**: Project bundles fail to upgrade - -**Solution**: - -```bash -# Check bundle schema version -specfact plan select --bundle --json | jq '.schema_version' - -# Manual upgrade if needed -specfact plan upgrade --bundle --force -``` - -**Issue**: Imported plans have missing data - -**Solution**: - -1. Review import logs -2. Use `plan review` to identify gaps -3. Use `plan update-feature` to fill missing data -4. Re-import if needed - -**Related**: [Troubleshooting Guide](troubleshooting.md) - ---- - -## See Also - -- [Command Chains Reference](command-chains.md) - Complete workflows -- [Common Tasks Index](common-tasks.md) - Quick reference -- [Spec-Kit Journey Guide](speckit-journey.md) - Spec-Kit migration -- [OpenSpec Journey Guide](openspec-journey.md) - OpenSpec migration -- [Troubleshooting Guide](troubleshooting.md) - Common issues +This page needs a full rewrite around the mounted command groups before task-level workflow examples can be published again. diff --git a/docs/guides/module-marketplace.md b/docs/guides/module-marketplace.md index fdafceb..2e6560e 100644 --- a/docs/guides/module-marketplace.md +++ b/docs/guides/module-marketplace.md @@ -15,7 +15,7 @@ For the curated official bundle list and trust/dependency quick reference, see ## Registry Overview - **Official registry**: (index: `registry/index.json`) -- **Marketplace module id format**: `namespace/name` (e.g. `specfact/backlog`). Marketplace modules must use this format; flat names are allowed only for custom/local modules with a warning. +- **Marketplace module id format**: `namespace/name` (e.g. `nold-ai/specfact-backlog`). Marketplace modules must use this format; flat names are allowed only for custom/local modules with a warning. - **Custom registries**: You can add private or third-party registries. See [Custom registries](custom-registries.md) for adding, listing, removing, trust levels, and priority. ## Custom registries and search @@ -65,7 +65,7 @@ Checksum mismatch blocks installation. **Namespace enforcement**: -- Modules installed from the marketplace must use the `namespace/name` format (e.g. `specfact/backlog`). Invalid format is rejected. +- Modules installed from the marketplace must use the `namespace/name` format (e.g. `nold-ai/specfact-backlog`). Invalid format is rejected. - If a module with the same logical name is already installed from a different source or namespace, install reports a collision and suggests using an alias or uninstalling the existing module. Additional local hardening: diff --git a/docs/guides/openspec-journey.md b/docs/guides/openspec-journey.md index 3f10aaf..9b963ba 100644 --- a/docs/guides/openspec-journey.md +++ b/docs/guides/openspec-journey.md @@ -51,7 +51,7 @@ OpenSpec **is not designed primarily for** (but SpecFact CLI provides): | Need | OpenSpec Solution | SpecFact Solution | |------|------------------|-------------------| -| **Work with existing code** โญ **PRIMARY** | โš ๏ธ **Not designed for** - Focuses on spec authoring | โœ… **`import from-code`** โญ - Reverse-engineer existing code to plans (PRIMARY use case) | +| **Work with existing code** โญ **PRIMARY** | โš ๏ธ **Not designed for** - Focuses on spec authoring | โœ… **`code import`** โญ - Reverse-engineer existing code to plans (PRIMARY use case) | | **Sync change proposals to DevOps** | โš ๏ธ **Not designed for** - Manual process | โœ… **`sync bridge --adapter github`** โœ… - Export proposals to GitHub Issues (IMPLEMENTED) | | **Track code changes** | โš ๏ธ **Not designed for** - Manual tracking | โœ… **`--track-code-changes`** โœ… - Auto-detect commits and add progress comments (IMPLEMENTED) | | **Runtime enforcement** | Manual validation | โœ… **Contract enforcement** - Prevent regressions with executable contracts | @@ -75,7 +75,7 @@ graph TB end subgraph "SpecFact: Code Analysis & Enforcement" - SF1[import from-code
Extract specs from code] + SF1[code import
Extract specs from code] SF2[Runtime Contracts
Prevent regressions] SF3[Bridge Adapters
Sync to DevOps] end @@ -144,7 +144,7 @@ Add new feature X to improve user experience. EOF # Step 2: Export to GitHub Issues -specfact sync bridge --adapter github --mode export-only \ +specfact project sync bridge --adapter github --mode export-only \ --repo-owner your-org \ --repo-name your-repo \ --repo /path/to/openspec-repo @@ -167,7 +167,7 @@ sequenceDiagram participant GH as GitHub Issues Dev->>OS: Create change proposal
openspec/changes/add-feature-x/ - Dev->>SF: specfact sync bridge --adapter github + Dev->>SF: specfact project sync bridge --adapter github SF->>OS: Read proposal.md SF->>GH: Create issue from proposal GH-->>SF: Issue #123 created @@ -176,7 +176,7 @@ sequenceDiagram Note over Dev,GH: Implementation Phase Dev->>Dev: Make commits with change ID - Dev->>SF: specfact sync bridge --track-code-changes + Dev->>SF: specfact project sync bridge --track-code-changes SF->>SF: Detect commits mentioning
change ID SF->>GH: Add progress comment
to issue #123 GH-->>Dev: Progress visible in issue @@ -208,7 +208,7 @@ Read-only sync from OpenSpec to SpecFact for change proposal tracking: ```bash # Sync OpenSpec change proposals to SpecFact -specfact sync bridge --adapter openspec --mode read-only \ +specfact project sync bridge --adapter openspec --mode read-only \ --bundle my-project \ --repo /path/to/openspec-repo @@ -235,7 +235,7 @@ graph LR end subgraph "SpecFact Analysis" - SF1[import from-code
Extract features] + SF1[code import
Extract features] SF2[Alignment Report
Compare specs vs code] end @@ -264,7 +264,7 @@ Full bidirectional sync between OpenSpec and SpecFact: ```bash # Bidirectional sync (future) -specfact sync bridge --adapter openspec --bidirectional \ +specfact project sync bridge --adapter openspec --bidirectional \ --bundle my-project \ --repo /path/to/openspec-repo \ --watch @@ -335,7 +335,7 @@ Legacy API needs modernization for better performance and maintainability. EOF # Step 3: Export proposal to GitHub Issues โœ… IMPLEMENTED -specfact sync bridge --adapter github --mode export-only \ +specfact project sync bridge --adapter github --mode export-only \ --repo-owner your-org \ --repo-name your-repo \ --repo /path/to/openspec-repo @@ -344,7 +344,7 @@ specfact sync bridge --adapter github --mode export-only \ git commit -m "feat: modernize-api - refactor endpoints" # Step 5: Track progress โœ… IMPLEMENTED -specfact sync bridge --adapter github --mode export-only \ +specfact project sync bridge --adapter github --mode export-only \ --repo-owner your-org \ --repo-name your-repo \ --track-code-changes \ @@ -352,14 +352,14 @@ specfact sync bridge --adapter github --mode export-only \ --code-repo /path/to/source-code-repo # Step 6: Sync OpenSpec change proposals โœ… AVAILABLE -specfact sync bridge --adapter openspec --mode read-only \ +specfact project sync bridge --adapter openspec --mode read-only \ --bundle legacy-api \ --repo /path/to/openspec-repo # โ†’ Generates alignment report # โ†’ Shows gaps between OpenSpec specs and code # Step 7: Add runtime contracts -specfact enforce stage --preset balanced +specfact govern enforce stage --preset balanced # Step 8: Archive completed change openspec archive modernize-api diff --git a/docs/guides/policy-engine-commands.md b/docs/guides/policy-engine-commands.md index eea9a3a..bfcb409 100644 --- a/docs/guides/policy-engine-commands.md +++ b/docs/guides/policy-engine-commands.md @@ -51,7 +51,7 @@ specfact policy validate --repo . --format both Artifact resolution order when `--snapshot` is omitted: -1. `.specfact/backlog-baseline.json` +1. `.nold-ai/specfact-backlog-baseline.json` 2. Latest `.specfact/plans/backlog-*.yaml|yml|json` You can still override with an explicit path: diff --git a/docs/guides/sidecar-validation.md b/docs/guides/sidecar-validation.md index 729e5aa..e902c9a 100644 --- a/docs/guides/sidecar-validation.md +++ b/docs/guides/sidecar-validation.md @@ -22,13 +22,13 @@ Sidecar validation enables contract-based validation of external codebases (libr ### 1. Initialize Sidecar Workspace ```bash -specfact validate sidecar init +specfact code validate sidecar init ``` **Example:** ```bash -specfact validate sidecar init legacy-api /path/to/django-project +specfact code validate sidecar init legacy-api /path/to/django-project ``` This will: @@ -42,20 +42,20 @@ This will: ### 2. Run Validation ```bash -specfact validate sidecar run +specfact code validate sidecar run ``` **Example:** ```bash # Run full validation (CrossHair + Specmatic) -specfact validate sidecar run legacy-api /path/to/django-project +specfact code validate sidecar run legacy-api /path/to/django-project # Run only CrossHair analysis -specfact validate sidecar run legacy-api /path/to/django-project --no-run-specmatic +specfact code validate sidecar run legacy-api /path/to/django-project --no-run-specmatic # Run only Specmatic validation -specfact validate sidecar run legacy-api /path/to/django-project --no-run-crosshair +specfact code validate sidecar run legacy-api /path/to/django-project --no-run-crosshair ``` ## Workflow @@ -122,8 +122,8 @@ Validation tools are executed: **Example:** ```bash -specfact validate sidecar init django-app /path/to/django-project -specfact validate sidecar run django-app /path/to/django-project +specfact code validate sidecar init django-app /path/to/django-project +specfact code validate sidecar run django-app /path/to/django-project ``` ### FastAPI @@ -141,8 +141,8 @@ specfact validate sidecar run django-app /path/to/django-project **Example:** ```bash -specfact validate sidecar init fastapi-app /path/to/fastapi-project -specfact validate sidecar run fastapi-app /path/to/fastapi-project +specfact code validate sidecar init fastapi-app /path/to/fastapi-project +specfact code validate sidecar run fastapi-app /path/to/fastapi-project ``` ### Django REST Framework (DRF) @@ -160,8 +160,8 @@ specfact validate sidecar run fastapi-app /path/to/fastapi-project **Example:** ```bash -specfact validate sidecar init drf-api /path/to/drf-project -specfact validate sidecar run drf-api /path/to/drf-project +specfact code validate sidecar init drf-api /path/to/drf-project +specfact code validate sidecar run drf-api /path/to/drf-project ``` ### Flask @@ -183,8 +183,8 @@ specfact validate sidecar run drf-api /path/to/drf-project **Example:** ```bash -specfact validate sidecar init flask-app /path/to/flask-project -specfact validate sidecar run flask-app /path/to/flask-project +specfact code validate sidecar init flask-app /path/to/flask-project +specfact code validate sidecar run flask-app /path/to/flask-project ``` **Dependency Installation:** @@ -216,8 +216,8 @@ Flask applications automatically have dependencies installed in an isolated venv **Example:** ```bash -specfact validate sidecar init python-lib /path/to/python-library -specfact validate sidecar run python-lib /path/to/python-library +specfact code validate sidecar init python-lib /path/to/python-library +specfact code validate sidecar run python-lib /path/to/python-library ``` ## Configuration @@ -302,7 +302,7 @@ You can force Specmatic to run even without service configuration using the `--r ```bash # Force Specmatic to run (may fail if no service available) -specfact validate sidecar run legacy-api /path/to/repo --run-specmatic +specfact code validate sidecar run legacy-api /path/to/repo --run-specmatic ``` **Configuration:** @@ -422,13 +422,13 @@ Specmatic requires a service endpoint to test against. If no service configurati 3. **Re-run with Specmatic enabled**: ```bash - specfact validate sidecar run legacy-api /path/to/repo --run-specmatic + specfact code validate sidecar run legacy-api /path/to/repo --run-specmatic ``` 4. **Skip Specmatic explicitly** (if you only need CrossHair): ```bash - specfact validate sidecar run legacy-api /path/to/repo --no-run-specmatic + specfact code validate sidecar run legacy-api /path/to/repo --no-run-specmatic ``` ### Module Resolution Errors @@ -467,23 +467,23 @@ Specmatic requires a service endpoint to test against. If no service configurati ```bash # Initialize -specfact validate sidecar init django-blog /path/to/django-blog +specfact code validate sidecar init django-blog /path/to/django-blog # Run validation -specfact validate sidecar run django-blog /path/to/django-blog +specfact code validate sidecar run django-blog /path/to/django-blog ``` ### Example 2: FastAPI API ```bash # Initialize -specfact validate sidecar init fastapi-api /path/to/fastapi-api +specfact code validate sidecar init fastapi-api /path/to/fastapi-api # Run only CrossHair (no HTTP endpoints - Specmatic auto-skipped) -specfact validate sidecar run fastapi-api /path/to/fastapi-api --no-run-specmatic +specfact code validate sidecar run fastapi-api /path/to/fastapi-api --no-run-specmatic # Or let auto-skip handle it (Specmatic will be skipped automatically) -specfact validate sidecar run fastapi-api /path/to/fastapi-api +specfact code validate sidecar run fastapi-api /path/to/fastapi-api ``` **Note**: In this example, Specmatic is automatically skipped because no service configuration is provided. The validation will focus on CrossHair analysis only. @@ -492,10 +492,10 @@ specfact validate sidecar run fastapi-api /path/to/fastapi-api ```bash # Initialize -specfact validate sidecar init flask-app /path/to/flask-project +specfact code validate sidecar init flask-app /path/to/flask-project # Run validation (dependencies automatically installed in isolated venv) -specfact validate sidecar run flask-app /path/to/flask-project --no-run-specmatic +specfact code validate sidecar run flask-app /path/to/flask-project --no-run-specmatic ``` **Note**: Flask applications automatically have dependencies installed in `.specfact/venv/` during initialization. All HTTP methods are captured (e.g., routes with `methods=['GET','POST']` generate separate routes for each method). @@ -504,21 +504,21 @@ specfact validate sidecar run flask-app /path/to/flask-project --no-run-specmati ```bash # Initialize -specfact validate sidecar init python-lib /path/to/python-library +specfact code validate sidecar init python-lib /path/to/python-library # Run validation -specfact validate sidecar run python-lib /path/to/python-library +specfact code validate sidecar run python-lib /path/to/python-library ``` ## Repro Integration -Sidecar validation can be integrated into the `specfact repro` command for validating unannotated code as part of the reproducibility suite. +Sidecar validation can be integrated into the `specfact code repro` command for validating unannotated code as part of the reproducibility suite. ### Using Sidecar with Repro ```bash # Run repro with sidecar validation for unannotated code -specfact repro --sidecar --sidecar-bundle legacy-api --repo /path/to/repo +specfact code repro --sidecar --sidecar-bundle legacy-api --repo /path/to/repo ``` **What it does:** @@ -531,7 +531,7 @@ specfact repro --sidecar --sidecar-bundle legacy-api --repo /path/to/repo **Safe Defaults for Repro Mode:** -When used with `specfact repro --sidecar`, sidecar validation automatically applies safe defaults: +When used with `specfact code repro --sidecar`, sidecar validation automatically applies safe defaults: - **CrossHair timeout**: 30 seconds (vs 60 default) - **Per-path timeout**: 5 seconds @@ -542,10 +542,10 @@ When used with `specfact repro --sidecar`, sidecar validation automatically appl ```bash # Initialize sidecar workspace first -specfact validate sidecar init legacy-api /path/to/repo +specfact code validate sidecar init legacy-api /path/to/repo # Then run repro with sidecar validation -specfact repro --sidecar --sidecar-bundle legacy-api --repo /path/to/repo --verbose +specfact code repro --sidecar --sidecar-bundle legacy-api --repo /path/to/repo --verbose ``` **Output:** diff --git a/docs/guides/speckit-comparison.md b/docs/guides/speckit-comparison.md index 03c3132..fa8c707 100644 --- a/docs/guides/speckit-comparison.md +++ b/docs/guides/speckit-comparison.md @@ -213,16 +213,16 @@ permalink: /guides/speckit-comparison/ # (Interactive slash commands in GitHub) # Step 2: Import Spec-Kit artifacts into SpecFact (via bridge adapter) -specfact sync bridge --adapter speckit --repo ./my-project +specfact project sync bridge --adapter speckit --repo ./my-project # Step 3: Add runtime contracts to critical Python paths # (SpecFact contract decorators) # Step 4: Keep both in sync (using adapter registry pattern) -specfact sync bridge --adapter speckit --bundle --repo . --bidirectional +specfact project sync bridge --adapter speckit --bundle --repo . --bidirectional ``` -**Note**: SpecFact CLI uses a plugin-based adapter registry pattern. All adapters (Spec-Kit, OpenSpec, GitHub, etc.) are registered in `AdapterRegistry` and accessed via `specfact sync bridge --adapter `, making the architecture extensible for future tool integrations. +**Note**: SpecFact CLI uses a plugin-based adapter registry pattern. All adapters (Spec-Kit, OpenSpec, GitHub, etc.) are registered in `AdapterRegistry` and accessed via `specfact project sync bridge --adapter `, making the architecture extensible for future tool integrations. --- @@ -294,14 +294,14 @@ Use both together for best results. - **GitHub Issues** - Export change proposals to DevOps backlogs - **Future**: Linear, Jira, Azure DevOps, and more -All adapters are registered in `AdapterRegistry` and accessed via `specfact sync bridge --adapter `, making the architecture extensible for future tool integrations. +All adapters are registered in `AdapterRegistry` and accessed via `specfact project sync bridge --adapter `, making the architecture extensible for future tool integrations. ### Can I migrate from Spec-Kit to SpecFact? **Yes.** SpecFact can import Spec-Kit artifacts: ```bash -specfact sync bridge --adapter speckit --repo ./my-project +specfact project sync bridge --adapter speckit --repo ./my-project ``` You can also keep using both tools with bidirectional sync via the adapter registry pattern. @@ -312,7 +312,7 @@ You can also keep using both tools with bidirectional sync via the adapter regis ```bash # Read-only sync from OpenSpec to SpecFact -specfact sync bridge --adapter openspec --mode read-only \ +specfact project sync bridge --adapter openspec --mode read-only \ --bundle my-project \ --repo /path/to/openspec-repo ``` diff --git a/docs/guides/speckit-journey.md b/docs/guides/speckit-journey.md index a373cdd..df41a1e 100644 --- a/docs/guides/speckit-journey.md +++ b/docs/guides/speckit-journey.md @@ -4,544 +4,18 @@ title: "The Journey: From Spec-Kit to SpecFact" permalink: /guides/speckit-journey/ --- -# The Journey: From Spec-Kit to SpecFact +# Legacy Workflow Note -> **Spec-Kit and SpecFact are complementary, not competitive.** -> **Primary Use Case**: SpecFact CLI for brownfield code modernization -> **Secondary Use Case**: Add SpecFact enforcement to Spec-Kit's interactive authoring for new features +This page referenced command groups or workflow steps that are no longer part of the current public mounted CLI in this repository. The old examples were removed to avoid directing readers to unavailable commands. ---- - -## ๐ŸŽฏ Why Level Up? - -### **What Spec-Kit Does Great** - -Spec-Kit is **excellent** for: - -- โœ… **Interactive Specification** - Slash commands (`/speckit.specify`, `/speckit.plan`) with AI assistance -- โœ… **Rapid Prototyping** - Quick spec โ†’ plan โ†’ tasks โ†’ code workflow for **NEW features** -- โœ… **Learning & Exploration** - Great for understanding state machines, contracts, requirements -- โœ… **IDE Integration** - CoPilot chat makes it accessible to less technical developers -- โœ… **Constitution & Planning** - Add constitution, plans, and feature breakdowns for new features -- โœ… **Single-Developer Projects** - Perfect for personal projects and learning - -**Note**: Spec-Kit excels at working with **new features** - you can add constitution, create plans, and break down features for things you're building from scratch. - -### **What Spec-Kit Is Designed For (vs. SpecFact CLI)** - -Spec-Kit **is designed primarily for**: - -- โœ… **Greenfield Development** - Interactive authoring of new features via slash commands -- โœ… **Specification-First Workflow** - Natural language โ†’ spec โ†’ plan โ†’ tasks โ†’ code -- โœ… **Interactive AI Assistance** - CoPilot chat-based specification and planning -- โœ… **New Feature Planning** - Add constitution, plans, and feature breakdowns for new features - -Spec-Kit **is not designed primarily for** (but SpecFact CLI provides): - -- โš ๏ธ **Work with Existing Code** - **Not designed primarily for analyzing existing repositories or iterating on existing features** - - Spec-Kit allows you to add constitution, plans, and feature breakdowns for **NEW features** via interactive slash commands - - Current design focuses on greenfield development and interactive authoring - - **This is the primary area where SpecFact CLI complements Spec-Kit** ๐ŸŽฏ -- โš ๏ธ **Brownfield Analysis** - Not designed primarily for reverse-engineering from existing code -- โš ๏ธ **Automated Enforcement** - Not designed for CI/CD gates or automated contract validation -- โš ๏ธ **Team Collaboration** - Not designed for shared plans or deviation detection between developers -- โš ๏ธ **Production Quality Gates** - Not designed for proof bundles or budget-based enforcement -- โš ๏ธ **Multi-Repository Sync** - Not designed for cross-repo consistency validation -- โš ๏ธ **Deterministic Execution** - Designed for interactive AI interactions rather than scriptable automation - -### **When to Level Up** - -| Need | Spec-Kit Solution | SpecFact Solution | -|------|------------------|-------------------| -| **Work with existing code** โญ **PRIMARY** | โš ๏ธ **Not designed for** - Focuses on new feature authoring | โœ… **`import from-code`** โญ - Reverse-engineer existing code to plans (PRIMARY use case) | -| **Iterate on existing features** โญ **PRIMARY** | โš ๏ธ **Not designed for** - Focuses on new feature planning | โœ… **Auto-derive plans** โญ - Understand existing features from code (PRIMARY use case) | -| **Brownfield projects** โญ **PRIMARY** | โš ๏ธ **Not designed for** - Designed primarily for greenfield | โœ… **Brownfield analysis** โญ - Work with existing projects (PRIMARY use case) | -| **Team collaboration** | Manual sharing, no sync | **Shared structured plans** (automated bidirectional sync for team collaboration), automated deviation detection | -| **CI/CD integration** | Manual validation | Automated gates, proof bundles | -| **Production deployment** | Manual checklist | Automated quality gates | -| **Code review** | Manual review | Automated deviation detection | -| **Compliance** | Manual audit | Proof bundles, reproducible checks | - ---- - -## ๐ŸŒฑ Brownfield Modernization with SpecFact + Spec-Kit - -### **Best of Both Worlds for Legacy Code** - -When modernizing legacy code, you can use **both tools together** for maximum value: - -1. **Spec-Kit** for initial spec generation (fast, LLM-powered) -2. **SpecFact** for runtime contract enforcement (safety net) -3. **Spec-Kit** maintains documentation (living specs) -4. **SpecFact** prevents regressions (contract enforcement) - -### **Workflow: Legacy Code โ†’ Modernized Code** - -```bash -# Step 1: Use SpecFact to extract specs from legacy code -specfact code import customer-portal --repo ./legacy-app - -# Output: Auto-generated project bundle from existing code -# โœ… Analyzed 47 Python files -# โœ… Extracted 23 features -# โœ… Generated 112 user stories -# โฑ๏ธ Completed in 8.2 seconds -# ๐Ÿ“ Project bundle: .specfact/projects/customer-portal/ - -# Step 2: (Optional) Use Spec-Kit to refine specs interactively -# /speckit.specify --feature "Payment Processing" -# /speckit.plan --feature "Payment Processing" - -# Step 3: Use SpecFact to add runtime contracts -# Add @icontract decorators to critical paths - -# Step 4: Modernize safely with contract safety net -# Refactor knowing contracts will catch regressions - -# Step 5: Keep both in sync -specfact sync bridge --adapter speckit --bundle customer-portal --repo . --bidirectional --watch -``` - -### **Why This Works** - -- **SpecFact code2spec** extracts specs from undocumented legacy code automatically -- **Spec-Kit interactive authoring** refines specs with LLM assistance -- **SpecFact runtime contracts** prevent regressions during modernization -- **Spec-Kit documentation** maintains living specs for team - -**Result:** Fast spec generation + runtime safety net = confident modernization - -### **See Also** - -- **[Brownfield Engineer Guide](brownfield-engineer.md)** - Complete brownfield workflow -- **[Brownfield Journey](brownfield-journey.md)** - Step-by-step modernization guide -- **[Spec-Kit Comparison](speckit-comparison.md)** - Detailed comparison - ---- - -## ๐Ÿš€ The Onboarding Journey - -### **Stage 1: Discovery** ("What is SpecFact?") - -**Time**: < 5 minutes - -Learn how SpecFact complements Spec-Kit: - -```bash -# See it in action -specfact --help - -# Read the docs -cat docs/getting-started.md -``` - -**What you'll discover**: - -- โœ… SpecFact imports your Spec-Kit artifacts automatically -- โœ… Automated enforcement (CI/CD gates, contract validation) -- โœ… **Shared plans** (bidirectional sync for team collaboration) -- โœ… **Code vs plan drift detection** (automated deviation detection) -- โœ… Production readiness (quality gates, proof bundles) - -**Key insight**: SpecFact **preserves** your Spec-Kit workflow - you can use both tools together! - ---- - -### **Stage 2: First Import** ("Try It Out") - -**Time**: < 60 seconds - -Import your Spec-Kit project to see what SpecFact adds: - -```bash -# 1. Preview what will be imported -specfact sync bridge --adapter speckit --repo ./my-speckit-project --dry-run - -# 2. Execute import (one command) - bundle name will be auto-detected or you can specify with --bundle -specfact sync bridge --adapter speckit --repo ./my-speckit-project --write - -# 3. Review generated bundle using CLI commands -specfact plan compare --bundle -``` - -**What was created**: - -- Modular project bundle at `.specfact/projects//` (multiple aspect files) -- `.specfact/protocols/workflow.protocol.yaml` (from FSM if detected) -- `.specfact/gates/config.yaml` (quality gates configuration) - -**Note**: Use CLI commands to interact with bundles. Do not edit `.specfact` files directly. - -**What happens**: - -1. **Parses Spec-Kit artifacts**: `specs/[###-feature-name]/spec.md`, `plan.md`, `tasks.md`, `.specify/memory/constitution.md` -2. **Generates SpecFact plans**: Converts Spec-Kit features/stories โ†’ SpecFact models -3. **Creates enforcement config**: Quality gates, CI/CD integration -4. **Preserves Spec-Kit artifacts**: Your original files remain untouched - -**Result**: Your Spec-Kit specs become production-ready contracts with automated quality gates! - ---- - -### **Stage 3: Adoption** ("Use Both Together") - -**Time**: Ongoing (automatic) - -Keep using Spec-Kit interactively, sync automatically with SpecFact: - -```bash -# Enable bidirectional sync (bridge-based, adapter-agnostic) -specfact sync bridge --adapter speckit --bundle --repo . --bidirectional --watch -``` - -**Workflow**: - -```bash -# 1. Continue using Spec-Kit interactively (slash commands) -/speckit.specify --feature "User Authentication" -/speckit.plan --feature "User Authentication" -/speckit.tasks --feature "User Authentication" - -# 2. SpecFact automatically syncs new artifacts (watch mode) -# โ†’ Detects changes in specs/[###-feature-name]/ -# โ†’ Imports new spec.md, plan.md, tasks.md -# โ†’ Updates .specfact/projects// aspect files -# โ†’ Enables shared plans for team collaboration - -# 3. Detect code vs plan drift automatically -specfact plan compare --code-vs-plan -# โ†’ Compares intended design (manual plan = what you planned) vs actual implementation (code-derived plan = what's in your code) -# โ†’ Identifies deviations automatically (not just artifact consistency like Spec-Kit's /speckit.analyze) -# โ†’ Auto-derived plans come from `import from-code` (code analysis), so comparison IS "code vs plan drift" - -# 4. Enable automated enforcement -specfact enforce stage --preset balanced - -# 5. CI/CD automatically validates (GitHub Action) -# โ†’ Runs on every PR -# โ†’ Blocks HIGH severity issues -# โ†’ Generates proof bundles -``` - -**What you get**: - -- โœ… **Interactive authoring** (Spec-Kit): Use slash commands for rapid prototyping -- โœ… **Automated enforcement** (SpecFact): CI/CD gates catch issues automatically -- โœ… **Team collaboration** (SpecFact): Shared plans, deviation detection -- โœ… **Production readiness** (SpecFact): Quality gates, proof bundles - -**Best of both worlds**: Spec-Kit for authoring, SpecFact for enforcement! - ---- - -### **Stage 4: Migration** ("Full SpecFact Workflow") - -**Time**: Progressive (1-4 weeks) - -**Optional**: Migrate to full SpecFact workflow (or keep using both tools together) - -#### **Week 1: Import + Sync** - -```bash -# Import existing Spec-Kit project -specfact sync bridge --adapter speckit --repo . --write - -# Enable bidirectional sync (bridge-based, adapter-agnostic) -specfact sync bridge --adapter speckit --bundle --repo . --bidirectional --watch -``` - -**Result**: Both tools working together seamlessly. - -#### **Week 2-3: Enable Enforcement (Shadow Mode)** - -```bash -# Start in shadow mode (observe only) -specfact enforce stage --preset minimal - -# Set up CrossHair for contract exploration -specfact repro setup - -# Review what would be blocked -specfact repro --verbose - -# Apply auto-fixes for violations (if available) -specfact repro --fix --verbose -``` - -**Result**: See what SpecFact would catch, no blocking yet. Auto-fixes can be applied for Semgrep violations. - -#### **Week 4: Enable Balanced Enforcement** - -```bash -# Enable balanced mode (block HIGH, warn MEDIUM) -specfact enforce stage --preset balanced - -# Test with real PR -git checkout -b test-enforcement -# Make a change that violates contracts -specfact repro # Should block HIGH issues - -# Or apply auto-fixes first -specfact repro --fix # Apply Semgrep auto-fixes, then validate -``` +Use the current mounted entrypoints instead: -**Result**: Automated enforcement catching critical issues. Auto-fixes can be applied before validation. - -#### **Week 5+: Full SpecFact Workflow** (Optional) - -```bash -# Enable strict enforcement -specfact enforce stage --preset strict - -# Full automation (CI/CD, brownfield analysis, etc.) -# (CrossHair setup already done in Week 3) -specfact repro --budget 120 --verbose -``` - -**Result**: Complete SpecFact workflow - or keep using both tools together! - ---- - -## ๐Ÿ“‹ Step-by-Step Migration - -### **Step 1: Preview Migration** - -```bash -# See what will be imported (safe - no changes) -specfact sync bridge --adapter speckit --repo ./my-speckit-project --dry-run -``` - -**Expected Output**: - -```bash -๐Ÿ” Analyzing Spec-Kit project via bridge adapter... -โœ… Found .specify/ directory (modern format) -โœ… Found specs/001-user-authentication/spec.md -โœ… Found specs/001-user-authentication/plan.md -โœ… Found specs/001-user-authentication/tasks.md -โœ… Found .specify/memory/constitution.md - -**๐Ÿ’ก Tip**: If constitution is missing or minimal, run `specfact sdd constitution bootstrap --repo .` to auto-generate from repository analysis. - -๐Ÿ“Š Migration Preview: - - Will create: .specfact/projects// (modular project bundle) - - Will create: .specfact/protocols/workflow.protocol.yaml (if FSM detected) - - Will create: .specfact/gates/config.yaml - - Will convert: Spec-Kit features โ†’ SpecFact Feature models - - Will convert: Spec-Kit user stories โ†’ SpecFact Story models - -๐Ÿš€ Ready to migrate (use --write to execute) -``` - -### **Step 2: Execute Migration** - -```bash -# Execute migration (creates SpecFact artifacts) -specfact sync bridge \ - --adapter speckit \ - --repo ./my-speckit-project \ - --write \ - --report migration-report.md -``` - -**What it does**: - -1. **Parses Spec-Kit artifacts** (via bridge adapter): - - `specs/[###-feature-name]/spec.md` โ†’ Features, user stories, requirements - - `specs/[###-feature-name]/plan.md` โ†’ Technical context, architecture - - `specs/[###-feature-name]/tasks.md` โ†’ Tasks, story mappings - - `.specify/memory/constitution.md` โ†’ Principles, constraints - -2. **Generates SpecFact artifacts**: - - `.specfact/projects//` - Modular project bundle (multiple aspect files) - - `.specfact/protocols/workflow.protocol.yaml` - FSM protocol (if detected) - - `.specfact/gates/config.yaml` - Quality gates configuration - -3. **Preserves Spec-Kit artifacts**: - - Original files remain untouched - - Bidirectional sync keeps both aligned - -### **Step 3: Review Generated Artifacts** - -```bash -# Review project bundle using CLI commands -specfact plan compare --bundle - -# Review enforcement config using CLI commands -specfact enforce stage --preset minimal - -# Review migration report -cat migration-report.md -``` - -**Note**: Use CLI commands to interact with bundles. Do not edit `.specfact` files directly. - -**What to check**: - -- โœ… Features/stories correctly mapped from Spec-Kit -- โœ… Acceptance criteria preserved -- โœ… Business context extracted from constitution -- โœ… Enforcement config matches your needs - -### **Step 4: Enable Shared Plans (Bidirectional Sync)** - -**Shared structured plans** enable team collaboration with automated bidirectional sync. Unlike Spec-Kit's manual markdown sharing, SpecFact automatically keeps plans synchronized across team members. - -```bash -# One-time sync -specfact sync bridge --adapter speckit --bundle --repo . --bidirectional - -# Continuous watch mode (recommended for team collaboration) -specfact sync bridge --adapter speckit --bundle --repo . --bidirectional --watch --interval 5 -``` - -**What it syncs**: - -- **Spec-Kit โ†’ SpecFact**: New `spec.md`, `plan.md`, `tasks.md` โ†’ Updated `.specfact/projects//` aspect files -- **SpecFact โ†’ Spec-Kit**: Changes to `.specfact/projects//` โ†’ Updated Spec-Kit markdown with all required fields auto-generated: - - **spec.md**: Frontmatter, INVSEST criteria, Scenarios (Primary, Alternate, Exception, Recovery) - - **plan.md**: Constitution Check, Phases, Technology Stack (from constraints) - - **tasks.md**: Phase organization, Story mappings ([US1], [US2]), Parallel markers -- **Team collaboration**: Multiple developers can work on the same plan with automated synchronization -- **No manual editing required**: All Spec-Kit fields are auto-generated - ready for `/speckit.analyze` without additional work - -### **Step 5: Enable Enforcement** - -```bash -# Week 1-2: Shadow mode (observe only) -specfact enforce stage --preset minimal - -# Week 3-4: Balanced mode (block HIGH, warn MEDIUM) -specfact enforce stage --preset balanced - -# Week 5+: Strict mode (block MEDIUM+) -specfact enforce stage --preset strict -``` - -### **Step 6: Validate** - -```bash -# Set up CrossHair for contract exploration (one-time setup) -specfact repro setup - -# Run all checks -specfact repro --verbose - -# Check CI/CD integration -git push origin feat/specfact-migration -# โ†’ GitHub Action runs automatically -# โ†’ PR blocked if HIGH severity issues found -``` - ---- - -## ๐Ÿ’ก Best Practices - -### **1. Start in Shadow Mode** - -```bash -# Always start with shadow mode (no blocking) -specfact enforce stage --preset minimal -specfact repro -``` - -**Why**: See what SpecFact would catch before enabling blocking. - -### **2. Use Shared Plans (Bidirectional Sync)** - -```bash -# Enable bidirectional sync for team collaboration -specfact sync bridge --adapter speckit --bundle --repo . --bidirectional --watch -``` - -**Why**: **Shared structured plans** enable team collaboration with automated bidirectional sync. Unlike Spec-Kit's manual markdown sharing, SpecFact automatically keeps plans synchronized across team members. Continue using Spec-Kit interactively, get SpecFact automation automatically. - -### **3. Progressive Enforcement** - -```bash -# Week 1: Shadow (observe) -specfact enforce stage --preset minimal - -# Week 2-3: Balanced (block HIGH) -specfact enforce stage --preset balanced - -# Week 4+: Strict (block MEDIUM+) -specfact enforce stage --preset strict -``` - -**Why**: Gradual adoption reduces disruption and builds team confidence. - -### **4. Keep Spec-Kit Artifacts** - -**Don't delete Spec-Kit files** - they're still useful: - -- โœ… Interactive authoring (slash commands) -- โœ… Fallback if SpecFact has issues -- โœ… Team members who prefer Spec-Kit workflow - -**Bidirectional sync** keeps both aligned automatically. - ---- - -## โ“ FAQ - -### **Q: Do I need to stop using Spec-Kit?** - -**A**: No! SpecFact works **alongside** Spec-Kit. Use Spec-Kit for interactive authoring (new features), SpecFact for automated enforcement and existing code analysis. - -### **Q: What happens to my Spec-Kit artifacts?** - -**A**: They're **preserved** - SpecFact imports them but doesn't modify them. Bidirectional sync keeps both aligned. - -### **Q: Can I export back to Spec-Kit?** - -**A**: Yes! SpecFact can export back to Spec-Kit format. Your original files are never modified. - -### **Q: What if I prefer Spec-Kit workflow?** - -**A**: Keep using Spec-Kit! Bidirectional sync automatically keeps SpecFact artifacts updated. Use SpecFact for CI/CD enforcement and brownfield analysis. - -### **Q: Does SpecFact replace Spec-Kit?** - -**A**: No - they're **complementary**. Spec-Kit excels at interactive authoring for new features, SpecFact adds automation, enforcement, and brownfield analysis capabilities. - ---- - -## See Also - -### Related Guides - -- [Integrations Overview](integrations-overview.md) - Overview of all SpecFact CLI integrations - -- [Command Chains Reference](command-chains.md) - Complete workflows including [External Tool Integration Chain](command-chains.md#3-external-tool-integration-chain) -- [Common Tasks Index](common-tasks.md) - Quick reference for "How do I sync with Spec-Kit?" -- [Spec-Kit Comparison](speckit-comparison.md) - Detailed comparison guide -- [Use Cases](use-cases.md) - Detailed Spec-Kit migration use case - -### Related Commands - -- [Command Reference - Import Commands](../reference/commands.md#import---import-from-external-formats) - `import from-bridge` reference -- [Command Reference - Sync Commands](../reference/commands.md#sync-bridge) - `sync bridge` reference -- [Command Reference - SDD Constitution](../reference/commands.md#sdd-constitution---manage-project-constitutions) - Constitution management - -### Related Examples - -- [Spec-Kit Migration Examples](../examples/) - Real-world migration examples - -### Getting Started - -- [Getting Started](../getting-started/README.md) - Quick setup guide -- [Architecture](../reference/architecture.md) - How SpecFact integrates with Spec-Kit - ---- - -**Next Steps**: - -1. **Try it**: `specfact sync bridge --adapter speckit --repo . --dry-run` -2. **Import**: `specfact sync bridge --adapter speckit --repo . --write` -3. **Sync**: `specfact sync bridge --adapter speckit --bundle --repo . --bidirectional --watch` -4. **Enforce**: `specfact enforce stage --preset minimal` (start shadow mode) - ---- +- `specfact project --help` +- `specfact project sync --help` +- `specfact code --help` +- `specfact code review --help` +- `specfact spec --help` +- `specfact govern --help` +- `specfact backlog --help` -> **Remember**: Spec-Kit and SpecFact are complementary. Use Spec-Kit for interactive authoring, add SpecFact for automated enforcement. Best of both worlds! ๐Ÿš€ +For exact syntax, verify against live help in the current release before copying examples. diff --git a/docs/guides/specmatic-integration.md b/docs/guides/specmatic-integration.md index 5f3f152..ee01927 100644 --- a/docs/guides/specmatic-integration.md +++ b/docs/guides/specmatic-integration.md @@ -1,646 +1,15 @@ -# Specmatic Integration Guide +# Legacy Workflow Note -> **API Contract Testing with Specmatic** -> Validate OpenAPI/AsyncAPI specifications, check backward compatibility, and run mock servers +This page referenced command groups or workflow steps that are no longer part of the current public mounted CLI in this repository. The old examples were removed to avoid directing readers to unavailable commands. ---- +Use the current mounted entrypoints instead: -## Overview +- `specfact project --help` +- `specfact project sync --help` +- `specfact code --help` +- `specfact code review --help` +- `specfact spec --help` +- `specfact govern --help` +- `specfact backlog --help` -SpecFact CLI integrates with **Specmatic** to provide service-level contract testing for API specifications. This complements SpecFact's code-level contracts (icontract, beartype, CrossHair) by adding API contract validation. - -**What Specmatic adds:** - -- โœ… **OpenAPI/AsyncAPI validation** - Validate specification structure and examples -- โœ… **Backward compatibility checking** - Detect breaking changes between spec versions -- โœ… **Mock server generation** - Run development mock servers from specifications -- โœ… **Test suite generation** - Auto-generate contract tests from specs - ---- - -## Quick Reference: When to Use What - -| Command | Purpose | Output | When to Use | -|---------|---------|--------|-------------| -| `spec validate` | **Check if spec is valid** | Validation report (console) | Before committing spec changes, verify spec correctness | -| `spec generate-tests` | **Create tests to validate API** | Test files (on disk) | To test your API implementation matches the spec | -| `spec mock` | **Run mock server** | Running server | Test client code, frontend development | -| `spec backward-compat` | **Check breaking changes** | Compatibility report | When updating API versions | - -**Key Difference:** - -- `validate` = "Is my spec file correct?" (checks the specification itself) -- `generate-tests` = "Create tests to verify my API matches the spec" (creates executable tests) - -**Typical Workflow:** - -```bash -# 1. Validate spec is correct -specfact spec validate --bundle my-api - -# 2. Generate tests from spec -specfact spec generate-tests --bundle my-api --output tests/ - -# 3. Run tests against your API -specmatic test --spec ... --host http://localhost:8000 -``` - ---- - -## Installation - -**Important**: Specmatic is a **Java CLI tool**, not a Python package. It must be installed separately. - -### Install Specmatic - -Visit the [Specmatic download page](https://docs.specmatic.io/download.html) for detailed installation instructions. - -**Quick install options:** - -```bash -# Option 1: Direct installation (requires Java 17+) -# macOS/Linux -curl https://docs.specmatic.io/install-specmatic.sh | bash - -# Windows (PowerShell) -irm https://docs.specmatic.io/install-specmatic.ps1 | iex - -# Option 2: Via npm/npx (requires Java/JRE and Node.js) -# Run directly without installation -npx specmatic --version - -# Option 3: macOS (Homebrew) -brew install specmatic - -# Verify installation -specmatic --version -``` - -**Note**: SpecFact CLI automatically detects Specmatic whether it's installed directly or available via `npx`. If you have Java/JRE installed, you can use `npx specmatic` without a separate installation. - -### Verify Integration - -SpecFact CLI will automatically detect if Specmatic is available: - -```bash -# Check if Specmatic is detected -specfact spec validate --help - -# If Specmatic is not installed, you'll see: -# โœ— Specmatic not available: Specmatic CLI not found. Install from: https://docs.specmatic.io/ -``` - ---- - -## Commands - -### Validate Specification - -Validate an OpenAPI/AsyncAPI specification. Can validate a single file or all contracts in a project bundle: - -```bash -# Validate a single spec file -specfact spec validate api/openapi.yaml - -# With backward compatibility check -specfact spec validate api/openapi.yaml --previous api/openapi.v1.yaml - -# Validate all contracts in active bundle (interactive selection) -specfact spec validate - -# Validate all contracts in specific bundle -specfact spec validate --bundle legacy-api - -# Non-interactive: validate all contracts in active bundle -specfact spec validate --bundle legacy-api --no-interactive -``` - -**CLI-First Pattern**: The command uses the active plan (from `specfact plan select`) as default, or you can specify `--bundle`. Never requires direct `.specfact` paths - always use the CLI interface. - -**What it checks:** - -- Schema structure validation -- Example generation test -- Backward compatibility (if previous version provided) - -### Check Backward Compatibility - -Compare two specification versions: - -```bash -specfact spec backward-compat api/openapi.v1.yaml api/openapi.v2.yaml -``` - -**Output:** - -- โœ“ Compatible - No breaking changes detected -- โœ— Breaking changes - Lists incompatible changes - -### Generate Test Suite - -Auto-generate contract tests from specification. Can generate for a single file or all contracts in a bundle: - -```bash -# Generate for a single spec file -specfact spec generate-tests api/openapi.yaml - -# Generate to custom location -specfact spec generate-tests api/openapi.yaml --output tests/specmatic/ - -# Generate tests for all contracts in active bundle -specfact spec generate-tests --bundle legacy-api - -# Generate tests for all contracts in specific bundle -specfact spec generate-tests --bundle legacy-api --output tests/contract/ -``` - -**CLI-First Pattern**: Uses active plan as default, or specify `--bundle`. Never requires direct `.specfact` paths. - -### What Can You Do With Generated Tests? - -The tests generated by `spec generate-tests` are **executable contract tests** that validate your API implementation against your OpenAPI/AsyncAPI specification. Here's a complete walkthrough: - -#### Understanding Generated Tests - -When you run `specfact spec generate-tests`, Specmatic creates test files that: - -- **Validate request format**: Check that requests match the spec (headers, body, query params) -- **Validate response format**: Verify responses match the spec (status codes, headers, body schema) -- **Test all endpoints**: Ensure all endpoints defined in the spec are implemented -- **Check data types**: Validate that data types and constraints are respected -- **Property-based testing**: Automatically generate diverse test data to find edge cases - -#### Step-by-Step: Using Generated Tests - -**Step 1: Generate Tests from Your Contract** - -```bash -# Generate tests for all contracts in your bundle -specfact spec generate-tests --bundle my-api --output tests/contract/ - -# Output: -# [1/5] Generating test suite from: .specfact/projects/my-api/contracts/api.openapi.yaml -# โœ“ Test suite generated: tests/contract/ -# ... -# โœ“ Generated tests for 5 contract(s) -``` - -**Step 2: Review Generated Test Files** - -The tests are generated in the output directory (default: `.specfact/specmatic-tests/`): - -```bash -# Check what was generated -ls -la tests/contract/ -# Output shows Specmatic test files (format depends on Specmatic version) -``` - -**Step 3: Start Your API Server** - -Before running tests, start your API implementation: - -```bash -# Example: Start FastAPI server -python -m uvicorn main:app --port 8000 - -# Or Flask -python app.py - -# Or any other API server -# Make sure it's running on the expected host/port -``` - -**Step 4: Run Tests Against Your API** - -Use Specmatic's test runner to execute the generated tests: - -```bash -# Run tests against your running API -specmatic test \ - --spec .specfact/projects/my-api/contracts/api.openapi.yaml \ - --host http://localhost:8000 - -# Output: -# โœ“ GET /api/users - Request/Response match contract -# โœ“ POST /api/users - Request/Response match contract -# โœ— GET /api/products - Response missing required field 'price' -# ... -``` - -**Step 5: Fix Issues and Re-run** - -If tests fail, fix your API implementation and re-run: - -```bash -# Fix the API code -# ... make changes ... - -# Restart API server -python -m uvicorn main:app --port 8000 - -# Re-run tests -specmatic test --spec ... --host http://localhost:8000 -``` - -#### Complete Example: Contract-Driven Development Workflow - -Here's a full workflow from contract to tested implementation: - -```bash -# 1. Import existing code and extract contracts -specfact code import user-api --repo . - -# 2. Validate contracts are correct -specfact spec validate --bundle user-api - -# Output: -# [1/3] Validating specification: contracts/user-api.openapi.yaml -# โœ“ Specification is valid: user-api.openapi.yaml -# ... - -# 3. Generate tests from validated contracts -specfact spec generate-tests --bundle user-api --output tests/contract/ - -# Output: -# [1/3] Generating test suite from: contracts/user-api.openapi.yaml -# โœ“ Test suite generated: tests/contract/ -# โœ“ Generated tests for 3 contract(s) - -# 4. Start your API server -python -m uvicorn api.main:app --port 8000 & -sleep 3 # Wait for server to start - -# 5. Run contract tests -specmatic test \ - --spec .specfact/projects/user-api/contracts/user-api.openapi.yaml \ - --host http://localhost:8000 - -# Output: -# Running contract tests... -# โœ“ GET /api/users - Passed -# โœ“ POST /api/users - Passed -# โœ“ GET /api/users/{id} - Passed -# All tests passed! โœ“ -``` - -#### CI/CD Integration Example - -Add contract testing to your CI/CD pipeline: - -```yaml -# .github/workflows/contract-tests.yml -name: Contract Tests - -on: [push, pull_request] - -jobs: - contract-tests: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - - - name: Install Specmatic - run: | - curl https://docs.specmatic.io/install-specmatic.sh | bash - - - name: Install SpecFact CLI - run: pip install specfact-cli - - - name: Generate contract tests - run: | - specfact spec generate-tests \ - --bundle my-api \ - --output tests/contract/ \ - --no-interactive - - - name: Start API server - run: | - python -m uvicorn main:app --port 8000 & - sleep 5 - - - name: Run contract tests - run: | - specmatic test \ - --spec .specfact/projects/my-api/contracts/api.openapi.yaml \ - --host http://localhost:8000 -``` - -#### Testing Against Mock Servers - -You can also test your client code against Specmatic mock servers: - -```bash -# Terminal 1: Start mock server -specfact spec mock --bundle my-api --port 9000 - -# Terminal 2: Run your client code against mock -python client.py # Your client code that calls the API - -# The mock server: -# - Validates requests match the spec -# - Returns spec-compliant responses -# - Helps test client code without a real API -``` - -#### Benefits of Using Generated Tests - -1. **Automated Validation**: Catch contract violations automatically -2. **Early Detection**: Find issues before deployment -3. **Documentation**: Tests serve as executable examples -4. **Confidence**: Ensure API changes don't break contracts -5. **Integration Safety**: Prevent breaking changes between services -6. **Property-Based Testing**: Automatically test edge cases and boundary conditions - -#### Troubleshooting Test Execution - -**Tests fail with "Connection refused":** - -```bash -# Make sure your API server is running -curl http://localhost:8000/health # Test server is up - -# Check the host/port in your test command matches your server -specmatic test --spec ... --host http://localhost:8000 -``` - -**Tests fail with "Response doesn't match contract":** - -```bash -# Check what the actual response is -curl -v http://localhost:8000/api/users - -# Compare with your OpenAPI spec -# Fix your API implementation to match the spec -``` - -**Tests pass but you want to see details:** - -```bash -# Use verbose mode (if supported by Specmatic version) -specmatic test --spec ... --host ... --verbose -``` - -### Run Mock Server - -Start a mock server for development. Can use a single spec file or select from bundle contracts: - -```bash -# Auto-detect spec file from current directory -specfact spec mock - -# Specify spec file and port -specfact spec mock --spec api/openapi.yaml --port 9000 - -# Use examples mode (less strict) -specfact spec mock --spec api/openapi.yaml --examples - -# Select contract from active bundle (interactive) -specfact spec mock --bundle legacy-api - -# Use specific bundle (non-interactive, uses first contract) -specfact spec mock --bundle legacy-api --no-interactive -``` - -**CLI-First Pattern**: Uses active plan as default, or specify `--bundle`. Interactive selection when multiple contracts available. - -**Mock server features:** - -- Serves API endpoints based on specification -- Validates requests against spec -- Returns example responses -- Press Ctrl+C to stop - ---- - -## Integration with Other Commands - -Specmatic validation is automatically integrated into: - -### Import Command - -When importing code, SpecFact auto-detects and validates OpenAPI/AsyncAPI specs: - -```bash -# Import with bundle (uses active plan if --bundle not specified) -specfact code import legacy-api --repo . - -# Automatically validates: -# - Repo-level OpenAPI/AsyncAPI specs (openapi.yaml, asyncapi.yaml) -# - Bundle contract files referenced in features -# - Suggests starting mock server if API specs found -``` - -### Enforce Command - -SDD enforcement includes Specmatic validation for all contracts referenced in the bundle: - -```bash -# Enforce SDD (uses active plan if --bundle not specified) -specfact enforce sdd --bundle legacy-api - -# Automatically validates: -# - All contract files referenced in bundle features -# - Includes validation results in enforcement report -# - Reports deviations for invalid contracts -``` - -### Sync Command - -Repository sync validates specs before synchronization: - -```bash -# Sync bridge (uses active plan if --bundle not specified) -specfact sync bridge --bundle legacy-api --repo . - -# Automatically validates: -# - OpenAPI/AsyncAPI specs before sync operation -# - Prevents syncing invalid contracts -# - Reports validation errors before proceeding -``` - ---- - -## How It Works - -### Architecture - -```text -โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” -โ”‚ SpecFact Complete Stack โ”‚ -โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค -โ”‚ โ”‚ -โ”‚ Layer 1: Code-Level Contracts (Current) โ”‚ -โ”‚ โ”œโ”€ icontract: Function preconditions/postconditions โ”‚ -โ”‚ โ”œโ”€ beartype: Runtime type validation โ”‚ -โ”‚ โ””โ”€ CrossHair: Symbolic execution & counterexamples โ”‚ -โ”‚ โ”‚ -โ”‚ Layer 2: Service-Level Contracts (Specmatic) โ”‚ -โ”‚ โ”œโ”€ OpenAPI/AsyncAPI validation โ”‚ -โ”‚ โ”œโ”€ Backward compatibility checking โ”‚ -โ”‚ โ”œโ”€ Mock server for development โ”‚ -โ”‚ โ””โ”€ Contract testing automation โ”‚ -โ”‚ โ”‚ -โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ -``` - -### Integration Pattern - -SpecFact calls Specmatic via subprocess: - -1. **Check availability** - Verifies Specmatic CLI is in PATH -2. **Execute command** - Runs Specmatic CLI with appropriate arguments -3. **Parse results** - Extracts validation results and errors -4. **Display output** - Shows results in SpecFact's rich console format - ---- - -## Examples - -### Example 1: Validate API Spec During Import - -```bash -# Project has openapi.yaml -specfact code import api-service --repo . - -# Output: -# โœ“ Import complete! -# ๐Ÿ” Found 1 API specification file(s) -# Validating openapi.yaml with Specmatic... -# โœ“ openapi.yaml is valid -# Validated 3 bundle contract(s), 0 failed. -# ๐Ÿ’ก Tip: Run 'specfact spec mock --bundle api-service' to start a mock server for development -``` - -### Example 2: Check Breaking Changes - -```bash -# Compare API versions -specfact spec backward-compat api/v1/openapi.yaml api/v2/openapi.yaml - -# Output: -# โœ— Breaking changes detected -# Breaking Changes: -# - Removed endpoint /api/v1/users -# - Changed response schema for /api/v1/products -``` - -### Example 3: Development Workflow with Bundle - -```bash -# 1. Set active bundle -specfact plan select api-service - -# 2. Validate all contracts in bundle (interactive selection) -specfact spec validate -# Shows list of contracts, select by number or 'all' - -# 3. Start mock server from bundle (interactive selection) -specfact spec mock --bundle api-service --port 9000 - -# 4. In another terminal, test against mock -curl http://localhost:9000/api/users - -# 5. Generate tests for all contracts -specfact spec generate-tests --bundle api-service --output tests/ -``` - -### Example 4: CI/CD Workflow (Non-Interactive) - -```bash -# 1. Validate all contracts in bundle (non-interactive) -specfact spec validate --bundle api-service --no-interactive - -# 2. Generate tests for all contracts -specfact spec generate-tests --bundle api-service --output tests/ --no-interactive - -# 3. Run generated tests -pytest tests/specmatic/ -``` - ---- - -## Troubleshooting - -### Specmatic Not Found - -**Error:** - -```text -โœ— Specmatic not available: Specmatic CLI not found. Install from: https://docs.specmatic.io/ -``` - -**Solution:** - -1. Install Specmatic from [https://docs.specmatic.io/](https://docs.specmatic.io/) -2. Ensure `specmatic` is in your PATH -3. Verify with: `specmatic --version` - -### Validation Failures - -**Error:** - -```text -โœ— Specification validation failed -Errors: - - Schema validation failed: missing required field 'info' -``` - -**Solution:** - -1. Check your OpenAPI/AsyncAPI spec format -2. Validate with: `specmatic validate your-spec.yaml` -3. Review Specmatic documentation for spec requirements - -### Mock Server Won't Start - -**Error:** - -```text -โœ— Failed to start mock server: Port 9000 already in use -``` - -**Solution:** - -1. Use a different port: `specfact spec mock --port 9001` -2. Stop the existing server on that port -3. Check for other processes: `lsof -i :9000` - ---- - -## Best Practices - -1. **Validate early** - Run `specfact spec validate` before committing spec changes -2. **Check compatibility** - Use `specfact spec backward-compat` when updating API versions -3. **Use mock servers** - Start mock servers during development to test integrations -4. **Generate tests** - Auto-generate tests for CI/CD pipelines -5. **Integrate in workflows** - Let SpecFact auto-validate specs during import/enforce/sync - ---- - -## See Also - -### Related Guides - -- [Integrations Overview](integrations-overview.md) - Overview of all SpecFact CLI integrations -- [Command Chains Reference](command-chains.md) - Complete workflows including [API Contract Development Chain](command-chains.md#4-api-contract-development-chain) -- [Common Tasks Index](common-tasks.md) - Quick reference for API-related tasks -- [Contract Testing Workflow](contract-testing-workflow.md) - Contract testing patterns - -### Related Commands - -- [Command Reference - Spec Commands](../reference/commands.md#spec-commands) - Full command documentation -- [Command Reference - Contract Commands](../reference/commands.md#contract-commands) - Contract verification commands - -### Related Examples - -- [API Contract Development Examples](../examples/) - Real-world examples - -### External Documentation - -- **[Specmatic Official Docs](https://docs.specmatic.io/)** - Specmatic documentation -- **[OpenAPI Specification](https://swagger.io/specification/)** - OpenAPI spec format -- **[AsyncAPI Specification](https://www.asyncapi.com/)** - AsyncAPI spec format - ---- - -**Note**: Specmatic is an external tool and must be installed separately. SpecFact CLI provides integration but does not include Specmatic itself. +For exact syntax, verify against live help in the current release before copying examples. diff --git a/docs/guides/troubleshooting.md b/docs/guides/troubleshooting.md index 7d4d987..ca3d61c 100644 --- a/docs/guides/troubleshooting.md +++ b/docs/guides/troubleshooting.md @@ -4,850 +4,29 @@ title: Troubleshooting permalink: /troubleshooting/ --- -# Troubleshooting +# Legacy Workflow Note -Common issues and solutions for SpecFact CLI. +This page described older `specfact plan`, `specfact generate`, `specfact contract`, or `specfact sdd constitution` workflows that are not part of the current public mounted CLI in this repository. The detailed command examples previously documented here were removed because they no longer match the command surface exposed by `specfact --help`. -## Installation Issues +Use the current mounted entrypoints instead: -### Command Not Found +- `specfact project --help` +- `specfact project sync --help` +- `specfact code --help` +- `specfact code review --help` +- `specfact spec --help` +- `specfact govern --help` +- `specfact backlog --help` +- `specfact module --help` -**Issue**: `specfact: command not found` - -**Solutions**: - -1. **Check installation**: - - ```bash - pip show specfact-cli - ``` - -2. **Reinstall**: - - ```bash - pip install --upgrade specfact-cli - ``` - -## Plan Select Command is Slow - -**Symptom**: `specfact plan select` takes a long time (5+ seconds) to list plans. - -**Cause**: Project bundles may be missing summary metadata (older schema version 1.0). - -**Solution**: - -```bash -# Upgrade all project bundles to latest schema (adds summary metadata) -specfact plan upgrade --all - -# Verify upgrade worked -specfact plan select --last 5 -``` - -**Performance Improvement**: After upgrade, `plan select` is 44% faster (3.6s vs 6.5s) and scales better with large project bundles. - -1. **Use uvx** (no installation needed): - - ```bash - uvx specfact-cli@latest --help - ``` - -### Permission Denied - -**Issue**: `Permission denied` when running commands - -**Solutions**: - -1. **Use user install**: - - ```bash - pip install --user specfact-cli - ``` - -2. **Check PATH**: - - ```bash - echo $PATH - # Should include ~/.local/bin - ``` - -3. **Add to PATH**: - - ```bash - export PATH="$HOME/.local/bin:$PATH" - ``` - ---- - -## Import Issues - -### Spec-Kit Not Detected - -**Issue**: `No Spec-Kit project found` when running `import from-bridge --adapter speckit` - -**Solutions**: - -1. **Check directory structure**: - - ```bash - ls -la .specify/ - ls -la specs/ - ``` - -2. **Verify Spec-Kit format**: - - - Should have `.specify/` directory - - Should have `specs/` directory with feature folders - - Should have `specs/[###-feature-name]/spec.md` files - -3. **Use explicit path**: - - ```bash - specfact sync bridge --adapter speckit --repo /path/to/speckit-project - ``` - -### Code Analysis Fails (Brownfield) โญ - -**Issue**: `Analysis failed` or `No features detected` when analyzing legacy code - -**Solutions**: - -1. **Check repository path**: - - ```bash - specfact code import legacy-api --repo . --verbose - ``` - -2. **Lower confidence threshold** (for legacy code with less structure): - - ```bash - specfact code import legacy-api --repo . --confidence 0.3 - ``` - -3. **Check file structure**: - - ```bash - find . -name "*.py" -type f | head -10 - ``` - -4. **Use CoPilot mode** (recommended for brownfield - better semantic understanding): - - ```bash - specfact --mode copilot import from-code legacy-api --repo . --confidence 0.7 - ``` - -5. **For legacy codebases**, start with minimal confidence and review extracted features: - - ```bash - specfact code import legacy-api --repo . --confidence 0.2 - ``` - ---- - -## Sync Issues - -### Watch Mode Not Starting - -**Issue**: Watch mode exits immediately or doesn't detect changes - -**Solutions**: - -1. **Check repository path**: - - ```bash - specfact sync bridge --adapter speckit --bundle --repo . --watch --interval 5 --verbose - ``` - -2. **Verify directory exists**: - - ```bash - ls -la .specify/ - ls -la .specfact/ - ``` - -3. **Check permissions**: - - ```bash - ls -la .specfact/projects/ - ``` - -4. **Try one-time sync first**: - - ```bash - specfact sync bridge --adapter speckit --bundle --repo . --bidirectional - ``` - -### Bidirectional Sync Conflicts - -**Issue**: Conflicts during bidirectional sync - -**Solutions**: - -1. **Check conflict resolution**: - - - SpecFact takes priority by default - - Manual resolution may be needed - -2. **Review changes**: - - ```bash - git status - git diff - ``` - -3. **Use one-way sync**: - - ```bash - # Spec-Kit โ†’ SpecFact only - specfact sync bridge --adapter speckit --bundle --repo . - - # SpecFact โ†’ Spec-Kit only (manual) - # Edit Spec-Kit files manually - ``` - ---- - -## Enforcement Issues - -### Enforcement Not Working - -**Issue**: Violations not being blocked or warned - -**Solutions**: - -1. **Check enforcement configuration** (use CLI commands): - - ```bash - specfact enforce stage --preset minimal - ``` - -2. **Verify enforcement mode**: - - ```bash - specfact enforce stage --preset balanced - ``` - -3. **Run validation**: - - ```bash - specfact repro --verbose - ``` - -4. **Check severity levels**: - - - HIGH โ†’ BLOCK (in balanced/strict mode) - - MEDIUM โ†’ WARN (in balanced/strict mode) - - LOW โ†’ LOG (in all modes) - -### False Positives - -**Issue**: Valid code being flagged as violations - -**Solutions**: - -1. **Review violation details**: - - ```bash - specfact repro --verbose - ``` - -2. **Adjust confidence threshold**: - - ```bash - specfact code import legacy-api --repo . --confidence 0.7 - ``` - -3. **Check enforcement rules** (use CLI commands): - - ```bash - specfact enforce stage --preset minimal - ``` - -4. **Use minimal mode** (observe only): - - ```bash - specfact enforce stage --preset minimal - ``` - ---- - -## Constitution Issues - -### Constitution Missing or Minimal - -**Issue**: `Constitution required` or `Constitution is minimal` when running `sync bridge --adapter speckit` - -**Solutions**: - -1. **Auto-generate bootstrap constitution** (recommended for brownfield): - - ```bash - specfact sdd constitution bootstrap --repo . - ``` - - This analyzes your repository (README.md, pyproject.toml, .cursor/rules/, docs/rules/) and generates a bootstrap constitution. - -2. **Enrich existing minimal constitution**: - - ```bash - specfact sdd constitution enrich --repo . - ``` - - This fills placeholders in an existing constitution with repository context. - -3. **Validate constitution completeness**: - - ```bash - specfact sdd constitution validate - ``` - - This checks if the constitution is complete and ready for use. - -4. **Manual creation** (for greenfield): - - - Run `/speckit.constitution` command in your AI assistant - - Fill in the constitution template manually - -**When to use each option**: - -- **Bootstrap** (brownfield): Use when you want to extract principles from existing codebase -- **Enrich** (existing constitution): Use when you have a minimal constitution with placeholders -- **Manual** (greenfield): Use when starting a new project and want full control - -### Constitution Validation Fails - -**Issue**: `specfact sdd constitution validate` reports issues - -**Solutions**: - -1. **Check for placeholders**: - - ```bash - grep -r "\[.*\]" .specify/memory/constitution.md - ``` - -2. **Run enrichment**: - - ```bash - specfact sdd constitution enrich --repo . - ``` - -3. **Review validation output**: - - ```bash - specfact sdd constitution validate --constitution .specify/memory/constitution.md - ``` - - The output will list specific issues (missing sections, placeholders, etc.). - -4. **Fix issues manually** or re-run bootstrap: - - ```bash - specfact sdd constitution bootstrap --repo . --overwrite - ``` - ---- - -## Plan Comparison Issues - -### Plans Not Found - -**Issue**: `Plan not found` when running `plan compare` - -**Solutions**: - -1. **Check plan locations**: - - ```bash - ls -la .specfact/projects/ - ls -la .specfact/projects//reports/brownfield/ - ``` - -2. **Use explicit paths** (bundle directory paths): - - ```bash - specfact plan compare \ - --manual .specfact/projects/manual-plan \ - --auto .specfact/projects/auto-derived - ``` - -3. **Generate auto-derived plan first**: - - ```bash - specfact code import legacy-api --repo . - ``` - -### No Deviations Found (Expected Some) - -**Issue**: Comparison shows no deviations but you expect some - -**Solutions**: - -1. **Check feature key normalization**: - - - Different key formats may normalize to the same key - - Check `reference/feature-keys.md` for details - -2. **Verify plan contents** (use CLI commands): - - ```bash - specfact plan compare --bundle - ``` - -3. **Use verbose mode**: - - ```bash - specfact plan compare --bundle legacy-api --verbose - ``` - ---- - -## IDE Integration Issues - -### Slash Commands Not Working - -**Issue**: Slash commands not recognized in IDE - -**Solutions**: - -1. **Reinitialize IDE integration**: - -```bash - specfact init ide --ide cursor --force -``` - -2. **Check command files**: - - ```bash - ls -la .cursor/commands/specfact-*.md - ``` - -3. **Restart IDE**: Some IDEs require restart to discover new commands - -4. **Check IDE settings**: - - - VS Code: Check `.vscode/settings.json` - - Cursor: Check `.cursor/settings.json` - -### Command Files Not Created - -**Issue**: Command files not created after `specfact init` - -**Solutions**: - -1. **Check permissions**: - - ```bash - ls -la .cursor/commands/ - ``` - -2. **Use force flag**: - -```bash - specfact init ide --ide cursor --force -``` - -3. **Check IDE type**: - -```bash - specfact init ide --ide cursor # For Cursor - specfact init ide --ide vscode # For VS Code -``` - ---- - -## Mode Detection Issues - -### Wrong Mode Detected - -**Issue**: CI/CD mode when CoPilot should be detected (or vice versa) - -**Solutions**: - -1. **Use explicit mode**: - - ```bash - specfact --mode copilot import from-code my-project --repo . - ``` - -2. **Check environment variables**: - - ```bash - echo $COPILOT_API_URL - echo $VSCODE_PID - ``` - -3. **Set mode explicitly**: - - ```bash - export SPECFACT_MODE=copilot - specfact code import legacy-api --repo . - ``` - -4. **See [Operational Modes](../reference/modes.md)** for details - ---- - -## Performance Issues - -### Slow Analysis - -**Issue**: Code analysis takes too long - -**Solutions**: - -1. **Use CI/CD mode** (faster): - - ```bash - specfact --mode cicd import from-code my-project --repo . - ``` - -2. **Increase confidence threshold** (fewer features): - - ```bash - specfact code import legacy-api --repo . --confidence 0.8 - ``` - -3. **Exclude directories**: - - ```bash - # Use .gitignore or exclude patterns - specfact code import legacy-api --repo . --exclude "tests/" - ``` - -### Watch Mode High CPU - -**Issue**: Watch mode uses too much CPU - -**Solutions**: - -1. **Increase interval**: - - ```bash - specfact sync bridge --adapter speckit --bundle --repo . --watch --interval 10 - ``` - -2. **Use one-time sync**: - - ```bash - specfact sync bridge --adapter speckit --bundle --repo . --bidirectional - ``` - -3. **Check file system events**: - - - Too many files being watched - - Consider excluding directories - ---- - -## Terminal Output Issues - -SpecFact CLI **automatically detects terminal capabilities** and adjusts output formatting for optimal user experience across different environments. No manual configuration required - the CLI adapts to your terminal environment. - -### How Terminal Auto-Detection Works - -The CLI automatically detects terminal capabilities in this order: - -1. **Test Mode Detection**: - - `TEST_MODE=true` or `PYTEST_CURRENT_TEST` โ†’ **MINIMAL** mode - -2. **CI/CD Detection**: - - `CI`, `GITHUB_ACTIONS`, `GITLAB_CI`, `CIRCLECI`, `TRAVIS`, `JENKINS_URL`, `BUILDKITE` โ†’ **BASIC** mode - -3. **Color Support Detection**: - - `NO_COLOR` โ†’ Disables colors (respects [NO_COLOR standard](https://no-color.org/)) - - `FORCE_COLOR=1` โ†’ Forces colors - - `TERM` and `COLORTERM` environment variables โ†’ Additional hints - -4. **Terminal Type Detection**: - - TTY detection (`sys.stdout.isatty()`) โ†’ Interactive vs non-interactive - - Interactive TTY with animations โ†’ **GRAPHICAL** mode - - Non-interactive โ†’ **BASIC** mode - -5. **Default Fallback**: - - If uncertain โ†’ **BASIC** mode (safe, readable output) - -### Terminal Modes - -The CLI supports three terminal modes (auto-selected based on detection): - -- **GRAPHICAL** - Full Rich features (colors, animations, progress bars) for interactive terminals -- **BASIC** - Plain text, no animations, simple progress updates for CI/CD and embedded terminals -- **MINIMAL** - Minimal output for test mode - -### Environment Variables (Optional Overrides) - -You can override auto-detection using standard environment variables: - -- **`NO_COLOR`** - Disables all colors (respects [NO_COLOR standard](https://no-color.org/)) -- **`FORCE_COLOR=1`** - Forces color output even in non-interactive terminals -- **`CI=true`** - Explicitly enables basic mode (no animations, plain text) -- **`TEST_MODE=true`** - Enables minimal mode for testing - -### Examples - -```bash -# Auto-detection (default behavior) -specfact code import my-bundle -# โ†’ Automatically detects terminal and uses appropriate mode - -# Manual override: Disable colors -NO_COLOR=1 specfact code import my-bundle - -# Manual override: Force colors in CI/CD -FORCE_COLOR=1 specfact sync bridge - -# Manual override: Explicit CI/CD mode -CI=true specfact code import my-bundle -``` - -### No Progress Visible in Embedded Terminals - -**Issue**: No progress indicators visible when running commands in Cursor, VS Code, or other embedded terminals. - -**Cause**: Embedded terminals are non-interactive and may not support Rich animations. - -**Solution**: The CLI automatically detects embedded terminals and switches to basic mode with plain text progress updates. If you still don't see progress: - -1. **Verify auto-detection is working**: - - ```bash - # Check terminal mode (should show BASIC in embedded terminals) - python -c "from specfact_cli.runtime import get_terminal_mode; print(get_terminal_mode())" - ``` - -2. **Check environment variables**: - - ```bash - # Ensure NO_COLOR is not set (unless you want plain text) - unset NO_COLOR - ``` - -3. **Verify terminal supports stdout**: - - Embedded terminals should support stdout (not stderr-only) - - Progress updates are throttled - wait a few seconds for updates - -4. **Manual override** (if needed): - - ```bash - # Force basic mode - CI=true specfact code import my-bundle - ``` - -### Colors Not Working in CI/CD - -**Issue**: No colors in CI/CD pipeline output. - -**Cause**: CI/CD environments are automatically detected and use basic mode (no colors) for better log readability. - -**Solution**: This is expected behavior. CI/CD logs are more readable without colors. To force colors: +When you need exact syntax, verify against live help in the current release, for example: ```bash -FORCE_COLOR=1 specfact code import my-bundle +specfact project sync bridge --help +specfact code repro --help +specfact code validate sidecar --help +specfact spec validate --help +specfact govern enforce --help ``` ---- - -## Azure DevOps Issues - -### Azure DevOps Token Required - -**Issue**: "Azure DevOps token required" error when running `specfact backlog refine ado` or `specfact backlog map-fields`. - -**Solutions**: - -1. **Use stored token** (recommended): - - ```bash - specfact backlog auth azure-devops - # Or use PAT token for longer expiration: - specfact backlog auth azure-devops --pat your_pat_token - ``` - -2. **Use explicit token**: - - ```bash - specfact backlog refine ado --ado-org myorg --ado-project myproject --ado-token your_token - ``` - -3. **Set environment variable**: - - ```bash - export AZURE_DEVOPS_TOKEN=your_token - specfact backlog refine ado --ado-org myorg --ado-project myproject - ``` - -**Token Resolution Priority**: - -The command automatically uses tokens in this order: - -1. Explicit `--ado-token` parameter -2. `AZURE_DEVOPS_TOKEN` environment variable -3. Stored token via `specfact backlog auth azure-devops` -4. Expired stored token (shows warning with options) - -### OAuth Token Expired - -**Issue**: "Stored OAuth token expired" warning when using ADO commands. - -**Cause**: OAuth tokens expire after approximately 1 hour. - -**Solutions**: - -1. **Use PAT token** (recommended for automation, up to 1 year expiration): - - ```bash - specfact backlog auth azure-devops --pat your_pat_token - ``` - -2. **Re-authenticate**: - - ```bash - specfact backlog auth azure-devops - ``` - -3. **Use explicit token**: - - ```bash - specfact backlog refine ado --ado-org myorg --ado-project myproject --ado-token your_token - ``` - -### Fields Not Extracted from ADO Work Items - -**Issue**: Fields like acceptance criteria or assignee are not being extracted from ADO work items. - -**Solutions**: - -1. **Check field names**: ADO field names are case-sensitive and must match exactly: - - Use `specfact backlog map-fields` to discover exact field names in your project - - Common fields: `Microsoft.VSTS.Common.AcceptanceCriteria` (preferred) or `System.AcceptanceCriteria` - -2. **Verify custom mapping**: Check if custom mapping file exists and is correct: - - ```bash - cat .specfact/templates/backlog/field_mappings/ado_custom.yaml - ``` - -3. **Reset to defaults**: If mappings are corrupted: - - ```bash - specfact backlog map-fields --ado-org myorg --ado-project myproject --reset - ``` - -4. **Check multiple alternatives**: SpecFact CLI supports multiple field names for the same canonical field. Both `System.AcceptanceCriteria` and `Microsoft.VSTS.Common.AcceptanceCriteria` are checked automatically. - -### Interactive Mapping Command Fails - -**Issue**: `specfact backlog map-fields` fails with connection or permission errors. - -**Solutions**: - -1. **Check token permissions**: Ensure your PAT has "Work Items (Read)" permission -2. **Verify organization/project names**: Check for typos in `--ado-org` and `--ado-project` -3. **Test API connection**: - - ```bash - curl -u ":{token}" "https://dev.azure.com/{org}/{project}/_apis/wit/fields?api-version=7.1" - ``` - -4. **Use explicit token**: Override with `--ado-token` if stored token has issues -5. **Check base URL**: For on-premise Azure DevOps Server, use `--ado-base-url` - -### Custom Mapping Not Applied - -**Issue**: Custom field mapping file exists but is not being used. - -**Solutions**: - -1. **Check file location**: Must be at `.specfact/templates/backlog/field_mappings/ado_custom.yaml` -2. **Verify YAML syntax**: Use a YAML validator to check syntax -3. **Check file permissions**: Ensure the file is readable -4. **Validate schema**: Ensure the file matches `FieldMappingConfig` schema -5. **Automatic detection**: Custom mappings are automatically detected - no restart needed. If not working, check file path and syntax. - -### Backlog refine or work item PATCH fails (400/422) - -**Issue**: `specfact backlog refine ado ... --write` or work item update fails with HTTP 400/422 (e.g. "400 Client Error: Bad Request") or an ADO message like "TF51535: Cannot find field System.AcceptanceCriteria." - -**Cause**: The Azure DevOps project may use a custom process template where field names or paths differ from defaults (e.g. no `System.AcceptanceCriteria`). The JSON Patch sent by the CLI targets a field that does not exist or is not writable in that project. - -**Solutions**: - -1. **Read the console message** โ€“ The CLI prints the ADO error text and a hint, e.g. "Check custom field mapping; see ado_custom.yaml or documentation." If a field is named (e.g. "Field 'System.AcceptanceCriteria' not found"), that is the one to fix in mapping or template. - -2. **Run with `--debug` and inspect the log** โ€“ This gives you the exact ADO response and the patch paths that were sent: - - Run: `specfact --debug backlog refine ado --ado-org --ado-project ...` (or the failing command). - - Open `~/.specfact/logs/specfact-debug.log` and search for `"operation": "ado_patch"` and `"status": "failed"`. - - In that line, `extra.response_body` is a redacted snippet of the ADO error payload; `extra.patch_paths` lists the JSON Patch paths (e.g. `["/fields/System.AcceptanceCriteria", ...]`). Use these to see which field path failed. - -3. **Fix field mapping** โ€“ If the error is about a missing or wrong field: - - Ensure `.specfact/templates/backlog/field_mappings/ado_custom.yaml` exists and maps your canonical fields to the field names/paths that exist in your ADO project. - - Use `specfact backlog map-fields --ado-org --ado-project ` to discover available fields in the project. - - See [Custom Field Mapping](custom-field-mapping.md) and [Debug Logging โ€“ Examining ADO API Errors](../reference/debug-logging.md#examining-ado-api-errors). - -4. **Check project process template** โ€“ Custom ADO process templates can rename or remove fields. Align your mapping with the actual work item type and process in the project. - ---- - -## CI and GitHub Actions - -### Downloading test and repro logs from CI - -When a PR or push runs the **PR Orchestrator** workflow, test and repro output are uploaded as workflow artifacts so you can debug failures without re-running the full suite locally. - -1. **Where to find artifacts** - - - Open the workflow run: **Actions** โ†’ select the **PR Orchestrator** run (e.g. from your PR or branch). - - Scroll to the **Artifacts** section at the bottom of the run. - -2. **Artifact names and contents** - - | Artifact | Job | Contents | - |----------------------|------------------|---------------------------------------------------------------------------| - | `test-logs` | Tests (Python 3.12) | Full test run and coverage logs from `hatch run smart-test-full` (`logs/tests/`). | - | `coverage-reports` | Tests (Python 3.12) | Coverage XML for quality gates (when unit tests ran). | - | `compat-py311-logs` | Compatibility (Python 3.11) | Pytest and coverage XML output from the compat job. | - | `type-check-logs` | Type Checking (basedpyright) | Full basedpyright type-check output. | - | `lint-logs` | Linting (ruff, pylint) | Full lint run output. | - | `quality-gates-logs`| Quality Gates (Advisory) | Coverage percentage and advisory message. | - | `repro-logs` | Contract-First CI | Full stdout/stderr of `specfact repro` (`logs/repro/`). | - | `repro-reports` | Contract-First CI | Repro report YAMLs from `.specfact/reports/enforcement/`. | - -3. **How to use them** - - - Download the artifact (e.g. `test-logs` or `repro-logs`) from the run page. - - Unzip and open the log or report files to see the full output that led to the failure. - - Use this instead of copying snippets from the step log, so you get complete error context before fixing and pushing again. - ---- - -## Getting Help - -If you're still experiencing issues: - -1. **Check logs**: - - - **Debug log file** (when using `--debug`): Debug output and structured operation metadata are written to `~/.specfact/logs/specfact-debug.log`. See [Debug Logging](../reference/debug-logging.md) for what is logged and how to use it. - - **Verbose repro** (ad-hoc capture): - - ```bash - specfact --debug # Writes to ~/.specfact/logs/specfact-debug.log - specfact repro --verbose 2>&1 | tee debug.log - ``` - -2. **Search documentation**: - - - [Command Reference](../reference/commands.md) - - [Use Cases](use-cases.md) - - [Workflows](workflows.md) - -3. **Community support**: - - - ๐Ÿ’ฌ [GitHub Discussions](https://github.com/nold-ai/specfact-cli/discussions) - - ๐Ÿ› [GitHub Issues](https://github.com/nold-ai/specfact-cli/issues) - -4. **Direct support**: - - - ๐Ÿ“ง [hello@noldai.com](mailto:hello@noldai.com) - -**Happy building!** ๐Ÿš€ +This page needs a full rewrite around the mounted command groups before task-level workflow examples can be published again. diff --git a/docs/guides/use-cases.md b/docs/guides/use-cases.md index 2f9bdca..2876175 100644 --- a/docs/guides/use-cases.md +++ b/docs/guides/use-cases.md @@ -4,659 +4,29 @@ title: Use Cases permalink: /use-cases/ --- -# Use Cases +# Legacy Workflow Note -Detailed use cases and examples for SpecFact CLI. +This page described older `specfact plan`, `specfact generate`, `specfact contract`, or `specfact sdd constitution` workflows that are not part of the current public mounted CLI in this repository. The detailed command examples previously documented here were removed because they no longer match the command surface exposed by `specfact --help`. -> **Primary Use Case**: Brownfield code modernization (Use Case 1) -> **Secondary Use Case**: Adding enforcement to Spec-Kit projects (Use Case 2) -> **Alternative**: Greenfield spec-first development (Use Case 3) -> **Validation Use Case**: Sidecar validation of external codebases (Use Case 4) ๐Ÿ†• +Use the current mounted entrypoints instead: -**CLI-First Approach**: SpecFact works offline, requires no account, and integrates with your existing workflow. Works with VS Code, Cursor, GitHub Actions, pre-commit hooks, or any IDE. No platform to learn, no vendor lock-in. +- `specfact project --help` +- `specfact project sync --help` +- `specfact code --help` +- `specfact code review --help` +- `specfact spec --help` +- `specfact govern --help` +- `specfact backlog --help` +- `specfact module --help` ---- - -## Use Case 1: Brownfield Code Modernization โญ PRIMARY - -**Problem**: Existing codebase with no specs, no documentation, or outdated documentation. Need to understand legacy code and add quality gates incrementally without breaking existing functionality. - -**Solution**: Reverse engineer existing code into documented specs, then progressively enforce contracts to prevent regressions during modernization. - -### Steps - -#### 1. Analyze Code - -```bash -# CI/CD mode (fast, deterministic) - Full repository -specfact code import \ - --repo . \ - --shadow-only \ - --confidence 0.7 \ - --report analysis.md - -# Partial analysis (large codebases or monorepos) -specfact code import \ - --repo . \ - --entry-point src/core \ - --confidence 0.7 \ - --bundle core-module \ - --report analysis-core.md - -# CoPilot mode (enhanced prompts, interactive) -specfact --mode copilot import from-code \ - --repo . \ - --confidence 0.7 \ - --report analysis.md -``` - -**With IDE Integration:** - -```bash -# First, initialize IDE integration -specfact init ide --ide cursor - -# Then use slash command in IDE chat -/specfact.01-import legacy-api --repo . --confidence 0.7 -``` - -See [IDE Integration Guide](ide-integration.md) for setup instructions. See [Integration Showcases](../examples/integration-showcases/) for real examples of bugs fixed via IDE integrations. - -**What it analyzes (AI-First / CoPilot Mode):** - -- Semantic understanding of codebase (LLM) -- Multi-language support (Python, TypeScript, JavaScript, PowerShell, etc.) -- Actual priorities, constraints, unknowns from code context -- Meaningful scenarios from acceptance criteria -- High-quality Spec-Kit compatible artifacts - -**What it analyzes (AST-Based / CI/CD Mode):** - -- Module dependency graph (Python-only) -- Commit history for feature boundaries -- Test files for acceptance criteria -- Type hints for API surfaces -- Async patterns for anti-patterns - -**CoPilot Enhancement:** - -- Context injection (current file, selection, workspace) -- Enhanced prompts for semantic understanding -- Interactive assistance for complex codebases -- Multi-language analysis support - -#### 2. Review Auto-Generated Plan - -```bash -cat analysis.md -``` - -**Expected sections:** - -- **Features Detected** - With confidence scores -- **Stories Inferred** - From commit messages -- **API Surface** - Public functions/classes -- **Async Patterns** - Detected issues -- **State Machine** - Inferred from code flow - -#### 3. Sync Repository Changes (Optional) - -Keep plan artifacts updated as code changes: - -```bash -# One-time sync -specfact sync repository --repo . --target .specfact - -# Continuous watch mode -specfact sync repository --repo . --watch --interval 5 -``` - -**What it tracks:** - -- Code changes โ†’ Plan artifact updates -- Deviations from manual plans -- Feature/story extraction from code - -#### 4. Compare with Manual Plan (if exists) - -```bash -specfact plan compare \ - --manual .specfact/projects/manual-plan \ - --auto .specfact/projects/auto-derived \ - --output-format markdown \ - --out .specfact/projects//reports/comparison/deviation-report.md -``` - -**With CoPilot:** - -```bash -# Use slash command in IDE chat (after specfact init) -/specfact.compare --bundle legacy-api -# Or with explicit paths: /specfact.compare --manual main.bundle.yaml --auto auto.bundle.yaml -``` - -**CoPilot Enhancement:** - -- Deviation explanations -- Fix suggestions -- Interactive deviation review - -**Output:** - -```markdown -# Deviation Report - -## Missing Features (in manual but not in auto) - -- FEATURE-003: User notifications - - Confidence: N/A (not detected in code) - - Recommendation: Implement or remove from manual plan - -## Extra Features (in auto but not in manual) - -- FEATURE-AUTO-001: Database migrations - - Confidence: 0.85 - - Recommendation: Add to manual plan - -## Mismatched Stories - -- STORY-001: User login - - Manual acceptance: "OAuth 2.0 support" - - Auto acceptance: "Basic auth only" - - Severity: HIGH - - Recommendation: Update implementation or manual plan -``` - -#### 5. Fix High-Severity Deviations - -Focus on: - -- **Async anti-patterns** - Blocking I/O in async functions -- **Missing contracts** - APIs without validation -- **State machine gaps** - Unreachable states -- **Test coverage** - Missing acceptance tests - -#### 6. Progressive Enforcement - -```bash -# Week 1-2: Shadow mode (observe) -specfact enforce stage --preset minimal - -# Week 3-4: Balanced mode (warn on medium, block high) -specfact enforce stage --preset balanced - -# Week 5+: Strict mode (block medium+) -specfact enforce stage --preset strict -``` - -### Expected Timeline (Brownfield Modernization) - -- **Analysis**: 2-5 minutes -- **Review**: 1-2 hours -- **High-severity fixes**: 1-3 days -- **Shadow mode**: 1-2 weeks -- **Production enforcement**: After validation stabilizes - ---- - -## Use Case 2: GitHub Spec-Kit Migration (Secondary) - -**Problem**: You have a Spec-Kit project but need automated enforcement, team collaboration, and production deployment quality gates. - -**Solution**: Import Spec-Kit artifacts into SpecFact CLI for automated contract enforcement while keeping Spec-Kit for interactive authoring. - -### Steps (Spec-Kit Migration) - -#### 1. Preview Migration - -```bash -specfact sync bridge --adapter speckit --repo ./spec-kit-project --dry-run -``` - -**Expected Output:** - -```bash -๐Ÿ” Analyzing Spec-Kit project via bridge adapter... -โœ… Found .specify/ directory (modern format) -โœ… Found specs/001-user-authentication/spec.md -โœ… Found specs/001-user-authentication/plan.md -โœ… Found specs/001-user-authentication/tasks.md -โœ… Found .specify/memory/constitution.md - -๐Ÿ“Š Migration Preview: - - Will create: .specfact/projects// (modular project bundle) - - Will create: .specfact/protocols/workflow.protocol.yaml (if FSM detected) - - Will create: .specfact/gates/config.yaml - - Will convert: Spec-Kit features โ†’ SpecFact Feature models - - Will convert: Spec-Kit user stories โ†’ SpecFact Story models - -๐Ÿš€ Ready to migrate (use --write to execute) -``` - -#### 2. Execute Migration - -```bash -specfact sync bridge \ - --adapter speckit \ - --repo ./spec-kit-project \ - --write \ - --report migration-report.md -``` - -#### 3. Review Generated Contracts - -```bash -# Review using CLI commands -specfact plan compare --bundle -``` - -Review: - -- `.specfact/projects//` - Modular project bundle (converted from Spec-Kit artifacts) -- `.specfact/protocols/workflow.protocol.yaml` - FSM definition (if protocol detected) -- `.specfact/enforcement/config.yaml` - Quality gates configuration -- `.semgrep/async-anti-patterns.yaml` - Anti-pattern rules (if async patterns detected) -- `.github/workflows/specfact-gate.yml` - CI workflow (optional) - -#### 4: Generate Constitution (If Missing) - -Before syncing, ensure you have a valid constitution: - -```bash -# Auto-generate from repository analysis (recommended for brownfield) -specfact sdd constitution bootstrap --repo . - -# Validate completeness -specfact sdd constitution validate - -# Or enrich existing minimal constitution -specfact sdd constitution enrich --repo . -``` - -**Note**: The `sync bridge --adapter speckit` command will detect if the constitution is missing or minimal and suggest bootstrap automatically. - -#### 5. Enable Bidirectional Sync (Optional) - -Keep Spec-Kit and SpecFact synchronized: - -```bash -# One-time bidirectional sync -specfact sync bridge --adapter speckit --bundle --repo . --bidirectional - -# Continuous watch mode -specfact sync bridge --adapter speckit --bundle --repo . --bidirectional --watch --interval 5 -``` - -**What it syncs:** - -- `specs/[###-feature-name]/spec.md`, `plan.md`, `tasks.md` โ†” `.specfact/projects//` aspect files -- `.specify/memory/constitution.md` โ†” SpecFact business context -- `specs/[###-feature-name]/research.md`, `data-model.md`, `quickstart.md` โ†” SpecFact supporting artifacts -- `specs/[###-feature-name]/contracts/*.yaml` โ†” SpecFact protocol definitions -- Automatic conflict resolution with priority rules - -#### 6. Enable Enforcement - -```bash -# Start in shadow mode (observe only) -specfact enforce stage --preset minimal - -# After stabilization, enable warnings -specfact enforce stage --preset balanced - -# For production, enable strict mode -specfact enforce stage --preset strict -``` - -#### 7. Validate - -```bash -# First-time setup: Configure CrossHair for contract exploration -specfact repro setup - -# Run validation -specfact repro --verbose -``` - -### Expected Timeline (Spec-Kit Migration) - -- **Preview**: < 1 minute -- **Migration**: 2-5 minutes -- **Review**: 15-30 minutes -- **Stabilization**: 1-2 weeks (shadow mode) -- **Production**: After validation passes - ---- - -## Use Case 3: Greenfield Spec-First Development (Alternative) - -**Problem**: Starting a new project, want contract-driven development from day 1. - -**Solution**: Use SpecFact CLI for spec-first planning and strict enforcement. - -### Steps (Greenfield Development) - -#### 1. Create Plan Interactively - -```bash -# Standard interactive mode -specfact plan init --interactive - -# CoPilot mode (enhanced prompts) -specfact --mode copilot plan init --interactive -``` - -**With CoPilot (IDE Integration):** - -```bash -# Use slash command in IDE chat (after specfact init) -/specfact.02-plan init legacy-api -# Or update idea: /specfact.02-plan update-idea --bundle legacy-api --title "My Project" -``` - -**Interactive prompts:** - -```bash -๐ŸŽฏ SpecFact CLI - Plan Initialization - -What's your idea title? -> Real-time collaboration platform - -What's the narrative? (high-level vision) -> Enable teams to collaborate in real-time with contract-driven quality - -What are the product themes? (comma-separated) -> Developer Experience, Real-time Sync, Quality Assurance - -What's the first release name? -> v0.1 - -What are the release objectives? (comma-separated) -> WebSocket server, Client SDK, Basic presence - -โœ… Plan initialized: .specfact/projects// -``` - -#### 2. Add Features and Stories - -```bash -# Add feature -specfact plan add-feature \ - --key FEATURE-001 \ - --title "WebSocket Server" \ - --outcomes "Handle 1000 concurrent connections" \ - --outcomes "< 100ms message latency" \ - --acceptance "Given client connection, When message sent, Then delivered within 100ms" - -# Add story -specfact plan add-story \ - --feature FEATURE-001 \ - --key STORY-001 \ - --title "Connection handling" \ - --acceptance "Accept WebSocket connections" \ - --acceptance "Maintain heartbeat every 30s" \ - --acceptance "Graceful disconnect cleanup" -``` - -#### 3. Define Protocol - -Create `contracts/protocols/workflow.protocol.yaml`: - -```yaml -states: - - DISCONNECTED - - CONNECTING - - CONNECTED - - RECONNECTING - - DISCONNECTING - -start: DISCONNECTED - -transitions: - - from_state: DISCONNECTED - on_event: connect - to_state: CONNECTING - - - from_state: CONNECTING - on_event: connection_established - to_state: CONNECTED - guard: handshake_valid - - - from_state: CONNECTED - on_event: connection_lost - to_state: RECONNECTING - guard: should_reconnect - - - from_state: RECONNECTING - on_event: reconnect_success - to_state: CONNECTED - - - from_state: CONNECTED - on_event: disconnect - to_state: DISCONNECTING -``` - -#### 4. Enable Strict Enforcement - -```bash -specfact enforce stage --preset strict -``` - -#### 5. Validate Continuously - -```bash -# First-time setup: Configure CrossHair for contract exploration -specfact repro setup - -# During development -specfact repro - -# In CI/CD -specfact repro --budget 120 --verbose -``` - -### Expected Timeline (Greenfield Development) - -- **Planning**: 1-2 hours -- **Protocol design**: 30 minutes -- **Implementation**: Per feature/story -- **Validation**: Continuous (< 90s per check) - ---- - -## Use Case 4: CI/CD Integration - -**Problem**: Need automated quality gates in pull requests. - -**Solution**: Add SpecFact GitHub Action to PR workflow. - -**Terminal Output**: The CLI automatically detects CI/CD environments and uses plain text output (no colors, no animations) for better log readability. Progress updates are visible in CI/CD logs. See [Troubleshooting](troubleshooting.md#terminal-output-issues) for details. - -### Steps (CI/CD Integration) - -#### 1. Add GitHub Action - -Create `.github/workflows/specfact.yml`: - -```yaml -name: SpecFact CLI Validation - -on: - pull_request: - branches: [main, dev] - push: - branches: [main, dev] - workflow_dispatch: - inputs: - budget: - description: "Time budget in seconds" - required: false - default: "90" - type: string - -jobs: - specfact-validation: - name: Contract Validation - runs-on: ubuntu-latest - permissions: - contents: read - pull-requests: write - checks: write - steps: - - name: Checkout - uses: actions/checkout@v4 - - - name: Set up Python - uses: actions/setup-python@v5 - with: - python-version: "3.11" - cache: "pip" - - - name: Install SpecFact CLI - run: pip install specfact-cli - - - name: Set up CrossHair Configuration - run: specfact repro setup - - - name: Run Contract Validation - run: specfact repro --verbose --budget 90 - - - name: Generate PR Comment - if: github.event_name == 'pull_request' - run: python -m specfact_cli.utils.github_annotations - env: - SPECFACT_REPORT_PATH: .specfact/projects//reports/enforcement/report-*.yaml -``` - -**Features**: - -- โœ… PR annotations for violations -- โœ… PR comments with violation summaries -- โœ… Auto-fix suggestions in PR comments -- โœ… Budget-based blocking -- โœ… Manual workflow dispatch support - -#### 2. Configure Enforcement - -Create `.specfact.yaml`: - -```yaml -version: "1.0" - -enforcement: - preset: balanced # Block HIGH, warn MEDIUM - -repro: - budget: 120 - parallel: true - fail_fast: false - -analysis: - confidence_threshold: 0.7 - exclude_patterns: - - "**/__pycache__/**" - - "**/node_modules/**" -``` - -#### 3. Test Locally - -```bash -# Before pushing -specfact repro --verbose - -# Apply auto-fixes for violations -specfact repro --fix --verbose - -# If issues found -specfact enforce stage --preset minimal # Temporarily allow -# Fix issues -specfact enforce stage --preset balanced # Re-enable -``` - -#### 4. Monitor PR Checks - -The GitHub Action will: - -- Run contract validation -- Check for async anti-patterns -- Validate state machine transitions -- Generate deviation reports -- Block PR if HIGH severity issues found - -### Expected Results - -- **Clean PRs**: Pass in < 90s -- **Blocked PRs**: Clear deviation report -- **False positives**: < 5% (use override mechanism) - ---- - -## Use Case 5: Multi-Repository Consistency - -**Problem**: Multiple microservices need consistent contract enforcement. - -**Solution**: Share common project bundle and enforcement config. - -### Steps (Multi-Repository) - -#### 1. Create Shared Project Bundle - -In a shared repository: - -```bash -# Create shared plan -specfact plan init --interactive - -# Add common features -specfact plan add-feature \ - --key FEATURE-COMMON-001 \ - --title "API Standards" \ - --outcomes "Consistent REST patterns" \ - --outcomes "Standardized error responses" -``` - -#### 2. Distribute to Services - -```bash -# In each microservice -git submodule add https://github.com/org/shared-contracts contracts/shared - -# Or copy files -cp ../shared-contracts/plan.bundle.yaml contracts/shared/ -``` - -#### 3. Validate Against Shared Plan +When you need exact syntax, verify against live help in the current release, for example: ```bash -# In each service -specfact plan compare \ - --manual contracts/shared/plan.bundle.yaml \ - --auto contracts/service/plan.bundle.yaml \ - --output-format markdown +specfact project sync bridge --help +specfact code repro --help +specfact code validate sidecar --help +specfact spec validate --help +specfact govern enforce --help ``` -#### 4. Enforce Consistency - -```bash -# First-time setup: Configure CrossHair for contract exploration -specfact repro setup - -# Add to CI -specfact repro -specfact plan compare --manual contracts/shared/plan.bundle.yaml --auto . -``` - -### Expected Benefits - -- **Consistency**: All services follow same patterns -- **Reusability**: Shared contracts and protocols -- **Maintainability**: Update once, apply everywhere - ---- - -See [Commands](../reference/commands.md) for detailed command reference and [Getting Started](../getting-started/README.md) for quick setup. - -## Integration Examples - -- **[Integration Showcases](../examples/integration-showcases/)** โญ - Real bugs fixed via VS Code, Cursor, GitHub Actions integrations -- **[IDE Integration](ide-integration.md)** - Set up slash commands in your IDE +This page needs a full rewrite around the mounted command groups before task-level workflow examples can be published again. diff --git a/docs/guides/using-module-security-and-extensions.md b/docs/guides/using-module-security-and-extensions.md index 86f8d3b..fc73177 100644 --- a/docs/guides/using-module-security-and-extensions.md +++ b/docs/guides/using-module-security-and-extensions.md @@ -6,142 +6,18 @@ description: How to use arch-06 (module security) and arch-07 (schema extensions nav_order: 22 --- -# Using Module Security and Schema Extensions +# Legacy Workflow Note -With **arch-06** (manifest security) and **arch-07** (schema extension system) in place, you can use verified modules and store module-specific metadata on bundles and features. This guide shows how to utilize these features from the CLI and in your own modules. +This page referenced command groups or workflow steps that are no longer part of the current public mounted CLI in this repository. The old examples were removed to avoid directing readers to unavailable commands. -## Quick reference +Use the current mounted entrypoints instead: -| Capability | What it does | Where to read more | -|------------|--------------|--------------------| -| **arch-06** | Publisher + integrity (checksum/signature) on module manifests; versioned dependencies | [Module Security](/reference/module-security/) | -| **arch-07** | `extensions` dict on Feature/ProjectBundle; `get_extension`/`set_extension`; `schema_extensions` in manifest | [Extending ProjectBundle](/guides/extending-projectbundle/) | +- `specfact project --help` +- `specfact project sync --help` +- `specfact code --help` +- `specfact code review --help` +- `specfact spec --help` +- `specfact govern --help` +- `specfact backlog --help` ---- - -## Using arch-06 (module security) - -### As a CLI user (consuming modules) - -- **Verified modules**: When you run any command that loads modules (e.g. `specfact backlog ...`, `specfact project ...`), the registry discovers modules and, when a module has `integrity.checksum` in its `module-package.yaml`, verifies the manifest checksum before registering. If verification fails, that module is skipped and a warning is logged; other modules still load. -- **Unsigned modules**: Modules without `integrity` metadata are allowed by default (backward compatible). To document explicit opt-in in strict environments, set: - ```bash - export SPECFACT_ALLOW_UNSIGNED=1 - ``` -- **Versioned dependencies**: Manifests can declare `module_dependencies_versioned` and `pip_dependencies_versioned` (each entry: `name`, `version_specifier`) for install-time resolution. You donโ€™t need to do anything special; the installer uses these when present. - -You donโ€™t run a separate โ€œverifyโ€ command; verification happens automatically at module registration when the CLI starts. - -### As a module author (publishing a module) - -1. **Add publisher and integrity to `module-package.yaml`** (optional but recommended): - - ```yaml - name: my-module - version: "0.1.0" - commands: [my-group] - - publisher: - name: "Your Name or Org" - email: "contact@example.com" - - integrity: - checksum: "sha256:" # Required for verification - signature: "" # Optional; requires trusted key on consumer side - ``` - -2. **Generate the checksum** using the bundled script: - - ```bash - ./scripts/sign-module.sh path/to/module-package.yaml - # Output: sha256: - # Add that value to integrity.checksum in the manifest - ``` - -3. **CI**: Use `.github/workflows/sign-modules.yml` (or equivalent) to produce or validate checksums when manifest files change. - -4. **Versioned dependencies** (optional): - - ```yaml - module_dependencies_versioned: - - name: backlog-core - version_specifier: ">=0.2.0" - pip_dependencies_versioned: - - name: requests - version_specifier: ">=2.28.0" - ``` - -Details: [Module Security](/reference/module-security/). - ---- - -## Using arch-07 (schema extensions) - -### As a CLI user (running commands that use extensions) - -Several commands already read or write extension data on `ProjectBundle` (and its manifest). You use them as usual; extensions are persisted with the bundle. - -- **Link a backlog provider** (writes `backlog_core.backlog_config` on project metadata): - ```bash - specfact project link-backlog --bundle my-bundle --adapter github --project-id my-org/my-repo - ``` -- **Health check and other project commands** read that same extension to resolve adapter/project/template: - ```bash - specfact project health-check --bundle my-bundle - ``` - -Any command that loads a bundle (e.g. `specfact plan ...`, `specfact sync ...`, `specfact spec ...`) loads the full bundle including `extensions`; round-trip save keeps extension data. So you donโ€™t need a special โ€œextensionsโ€ command to benefit from themโ€”theyโ€™re part of the bundle. - -**Introspecting registered extensions (programmatic):** There is no `specfact extensions list` CLI yet. From Python you can call: - -```python -from specfact_cli.registry.extension_registry import get_extension_registry -all_exts = get_extension_registry().list_all() # dict: module_name -> list of SchemaExtension -``` - -### As a module author (using extensions in your commands) - -1. **Declare extensions** in `module-package.yaml` so the CLI can validate and avoid collisions: - - ```yaml - schema_extensions: - - target: Feature - field: my_custom_id - type_hint: str - description: My moduleโ€™s external ID for this feature - - target: ProjectBundle - field: last_sync_ts - type_hint: str - description: ISO timestamp of last sync - ``` - -2. **In your command code**, when you have a `ProjectBundle` or `Feature` (e.g. from `load_bundle_with_progress` or from a project bundle): - - ```python - from specfact_cli.models.plan import Feature - from specfact_cli.models.project import ProjectBundle - - # On a Feature - feature.set_extension("my_module", "my_custom_id", "EXT-123") - value = feature.get_extension("my_module", "my_custom_id") # "EXT-123" - missing = feature.get_extension("my_module", "other", default="n/a") # "n/a" - - # On ProjectBundle (e.g. bundle.manifest.project_metadata or bundle itself) - bundle.set_extension("my_module", "last_sync_ts", "2026-02-16T12:00:00Z") - ts = bundle.get_extension("my_module", "last_sync_ts") - ``` - -3. **Naming rules**: `module_name`: lowercase, alphanumeric + underscores/hyphens, **no dots**. `field`: lowercase, alphanumeric + underscores. Keys are stored as `module_name.field` (e.g. `my_module.my_custom_id`). - -4. **Project metadata**: The built-in `project link-backlog` command uses **project_metadata** (on the bundle manifest), which also supports `get_extension`/`set_extension` with the same `module_name.field` convention (e.g. `backlog_core.backlog_config`). Use the same pattern for your moduleโ€™s config stored on the project. - -Full API and examples: [Extending ProjectBundle](/guides/extending-projectbundle/). - ---- - -## Summary - -- **arch-06**: Use `scripts/sign-module.sh` and `integrity`/`publisher` in manifests; consumers get automatic checksum verification at registration; set `SPECFACT_ALLOW_UNSIGNED=1` if you explicitly allow unsigned modules. -- **arch-07**: Use `get_extension`/`set_extension` on Feature and ProjectBundle in your module code; declare `schema_extensions` in `module-package.yaml`; use existing commands like `specfact project link-backlog` and `specfact project health-check` to see extensions in action. - -For deeper reference: [Module Security](/reference/module-security/), [Extending ProjectBundle](/guides/extending-projectbundle/), [Architecture](/reference/architecture/). +For exact syntax, verify against live help in the current release before copying examples. diff --git a/docs/guides/ux-features.md b/docs/guides/ux-features.md index 8518189..e4d1270 100644 --- a/docs/guides/ux-features.md +++ b/docs/guides/ux-features.md @@ -4,314 +4,18 @@ title: UX Features Guide permalink: /ux-features/ --- -# UX Features Guide +# Legacy Workflow Note -This guide covers the user experience features that make SpecFact CLI intuitive and efficient. +This page referenced command groups or workflow steps that are no longer part of the current public mounted CLI in this repository. The old examples were removed to avoid directing readers to unavailable commands. -## Progressive Disclosure +Use the current mounted entrypoints instead: -SpecFact CLI uses progressive disclosure to show the most important options first, while keeping advanced options accessible when needed. This reduces cognitive load for new users while maintaining full functionality for power users. +- `specfact project --help` +- `specfact project sync --help` +- `specfact code --help` +- `specfact code review --help` +- `specfact spec --help` +- `specfact govern --help` +- `specfact backlog --help` -### Regular Help - -By default, `--help` shows only the most commonly used options: - -```bash -specfact code import --help -``` - -This displays: - -- Required arguments -- Common options (bundle, repo, output) -- Behavior flags (interactive, verbose, dry-run, force) -- Essential workflow options - -### Advanced Help - -To see all options including advanced configuration, use `--help-advanced` (alias: `-ha`): - -```bash -specfact code import --help-advanced -``` - -This reveals: - -- **Advanced configuration options**: Confidence thresholds, key formats, adapter types -- **Fine-tuning parameters**: Watch intervals, time budgets, session limits -- **Expert-level settings**: Taxonomy filtering, content hash matching, backward compatibility checks -- **CI/CD automation options**: Non-interactive JSON inputs, exact name matching - -### Hidden Options Summary - -The following options are hidden by default across commands: - -**Import Commands:** - -- `--entry-point` - Partial analysis (subdirectory only) -- `--enrichment` - LLM enrichment workflow -- `--adapter` - Adapter type configuration (auto-detected) -- `--confidence` - Feature detection threshold -- `--key-format` - Feature key format (classname vs sequential) - -**Sync Commands:** - -- `--adapter` - Adapter type configuration (auto-detected) -- `--interval` - Watch mode interval tuning -- `--confidence` - Feature detection threshold - -**Plan Commands:** - -- `--max-questions` - Review session limit -- `--category` - Taxonomy category filtering -- `--findings-format` - Output format for findings -- `--answers` - Non-interactive JSON input -- `--stages` - Filter by promotion stages -- `--last` - Show last N plans -- `--current` - Show only active plan -- `--name` - Exact bundle name matching -- `--id` - Content hash ID matching - -**Spec Commands:** - -- `--previous` - Backward compatibility check - -**Other Commands:** - -- `repro --budget` - Time budget configuration -- `generate contracts-prompt --output` - Custom output path -- `init --ide` - IDE selection override (auto-detection works) - -**Tip**: Advanced options are still functional even when hidden - you can use them directly without `--help-advanced`/`-ha`. The flag only affects what's shown in help text. - -**Example:** - -```bash -# This works even though --confidence is hidden in regular help: -specfact code import my-bundle --confidence 0.7 --key-format sequential - -# To see all options in help: -specfact code import --help-advanced # or -ha -``` - -## Context Detection - -SpecFact CLI automatically detects your project context to provide smart defaults and suggestions. - -### Auto-Detection - -When you run commands, SpecFact automatically detects: - -- **Project Type**: Python, JavaScript, etc. -- **Framework**: FastAPI, Django, Flask, etc. -- **Existing Specs**: OpenAPI/AsyncAPI specifications -- **Project Bundles**: Existing SpecFact project bundles -- **Configuration**: Specmatic configuration files - -### Smart Defaults - -Based on detected context, SpecFact provides intelligent defaults: - -```bash -# If OpenAPI spec detected, suggests validation -specfact spec validate --bundle - -# If low contract coverage detected, suggests analysis -specfact analyze contracts --bundle -``` - -### Explicit Context - -You can also explicitly check your project context: - -```bash -# Context detection is automatic, but you can verify -specfact code import my-bundle --repo . -# CLI automatically detects Python, FastAPI, existing specs, etc. -``` - -## Intelligent Suggestions - -SpecFact provides context-aware suggestions to guide your workflow. - -### Next Steps - -After running commands, SpecFact suggests logical next steps: - -```bash -$ specfact code import legacy-api -โœ“ Import complete - -๐Ÿ’ก Suggested next steps: - โ€ข specfact analyze contracts --bundle legacy-api # Analyze contract coverage - โ€ข specfact enforce sdd --bundle legacy-api # Enforce quality gates - โ€ข specfact sync intelligent --bundle legacy-api # Sync code and specs -``` - -### Error Fixes - -When errors occur, SpecFact suggests specific fixes: - -```bash -$ specfact analyze contracts --bundle missing-bundle -โœ— Error: Bundle 'missing-bundle' not found - -๐Ÿ’ก Suggested fixes: - โ€ข specfact plan select # Select an active project bundle - โ€ข specfact code import missing-bundle # Create a new bundle -``` - -### Improvements - -Based on analysis, SpecFact suggests improvements: - -```bash -$ specfact analyze contracts --bundle legacy-api -โš  Low contract coverage detected (30%) - -๐Ÿ’ก Suggested improvements: - โ€ข specfact analyze contracts --bundle legacy-api # Identify missing contracts - โ€ข specfact code import legacy-api # Extract contracts from code -``` - -## Template-Driven Quality - -SpecFact uses templates to ensure high-quality, consistent specifications. - -### Feature Specification Templates - -When creating features, templates guide you to focus on: - -- **WHAT** users need (not HOW to implement) -- **WHY** the feature is valuable -- **Uncertainty markers** for ambiguous requirements: `[NEEDS CLARIFICATION: specific question]` -- **Completeness checklists** to ensure nothing is missed - -### Implementation Plan Templates - -Implementation plans follow templates that: - -- Keep high-level steps readable -- Extract detailed algorithms to separate files -- Enforce test-first thinking (contracts โ†’ tests โ†’ implementation) -- Include phase gates for architectural principles - -### Contract Extraction Templates - -Contract extraction uses templates to: - -- Extract contracts from legacy code patterns -- Identify validation logic -- Map to formal contracts (icontract, beartype) -- Mark uncertainties for later clarification - -## Enhanced Watch Mode - -Watch mode has been enhanced with intelligent change detection. - -### Hash-Based Detection - -Watch mode only processes files that actually changed: - -```bash -specfact sync intelligent --bundle my-bundle --watch -``` - -**Features**: - -- SHA256 hash-based change detection -- Only processes files with actual content changes -- Skips unchanged files (even if modified timestamp changed) -- Faster sync operations - -### Dependency Tracking - -Watch mode tracks file dependencies: - -- Identifies dependent files -- Processes dependencies when source files change -- Incremental processing (only changed files and dependencies) - -### Cache Optimization - -Watch mode uses an optimized cache: - -- LZ4 compression (when available) for faster I/O -- Persistent cache across sessions -- Automatic cache management - -## Unified Progress Display - -All commands use consistent progress indicators that automatically adapt to your terminal environment. - -### Progress Format - -Progress displays use a consistent `n/m` format: - -```bash -Loading artifact 3/12: FEATURE-001.yaml -``` - -This shows: - -- Current item number (3) -- Total items (12) -- Current artifact name (FEATURE-001.yaml) -- Elapsed time - -### Automatic Terminal Adaptation - -The CLI **automatically detects terminal capabilities** and adjusts progress display: - -- **Interactive terminals** โ†’ Full Rich progress with animations, colors, and progress bars -- **Embedded terminals** (Cursor, VS Code) โ†’ Plain text progress updates (no animations) -- **CI/CD pipelines** โ†’ Plain text progress updates for readable logs -- **Test mode** โ†’ Minimal output - -**No manual configuration required** - the CLI adapts automatically. See [Troubleshooting](troubleshooting.md#terminal-output-issues) for details. - -### Visibility - -Progress is shown for: - -- All bundle load/save operations -- Long-running operations (>1 second) -- File processing operations -- Analysis operations - -**No "dark" periods** - you always know what's happening, regardless of terminal type. - -## Best Practices - -### Using Progressive Disclosure - -1. **Start with regular help** - Most users only need common options -2. **Use `--help-advanced` (`-ha`)** when you need fine-grained control -3. **Advanced options work without help** - You can use them directly - -### Leveraging Context Detection - -1. **Let SpecFact auto-detect** - It's usually correct -2. **Verify context** - Check suggestions match your project -3. **Use explicit flags** - Override auto-detection when needed - -### Following Suggestions - -1. **Read suggestions carefully** - They're context-aware -2. **Follow the workflow** - Suggestions guide logical next steps -3. **Use error suggestions** - They provide specific fixes - -### Using Templates - -1. **Follow template structure** - Ensures quality and consistency -2. **Mark uncertainties** - Use `[NEEDS CLARIFICATION]` markers -3. **Complete checklists** - Templates include completeness checks - ---- - -**Related Documentation**: - -- [Command Reference](../reference/commands.md) - Complete command documentation -- [Workflows](workflows.md) - Common daily workflows -- [IDE Integration](ide-integration.md) - Enhanced IDE experience -- [Troubleshooting](troubleshooting.md#terminal-output-issues) - Terminal output auto-detection and troubleshooting +For exact syntax, verify against live help in the current release before copying examples. diff --git a/docs/guides/workflows.md b/docs/guides/workflows.md index 64ac888..951c313 100644 --- a/docs/guides/workflows.md +++ b/docs/guides/workflows.md @@ -1,553 +1,26 @@ -# Common Workflows +# Legacy Workflow Note -Daily workflows for using SpecFact CLI effectively. +This page described older `specfact plan`, `specfact generate`, `specfact contract`, or `specfact sdd constitution` workflows that are not part of the current public mounted CLI in this repository. The detailed command examples previously documented here were removed because they no longer match the command surface exposed by `specfact --help`. -> **Primary Workflow**: Brownfield code modernization -> **Secondary Workflow**: Spec-Kit bidirectional sync +Use the current mounted entrypoints instead: -**CLI-First Approach**: SpecFact works offline, requires no account, and integrates with your existing workflow. Works with VS Code, Cursor, GitHub Actions, pre-commit hooks, or any IDE. No platform to learn, no vendor lock-in. +- `specfact project --help` +- `specfact project sync --help` +- `specfact code --help` +- `specfact code review --help` +- `specfact spec --help` +- `specfact govern --help` +- `specfact backlog --help` +- `specfact module --help` -## Module System Context - -These workflows run on SpecFact's module-first architecture: - -- Core runtime provides lifecycle, registry, contract checks, and orchestration. -- Workflow features are implemented in module-local command implementations. -- Adapters are loaded through registry interfaces rather than hard-wired command logic. - -This separation allows feature modules and adapters to evolve independently while keeping core CLI behavior stable. - ---- - -## Brownfield Code Modernization โญ PRIMARY - -Reverse engineer existing code and enforce contracts incrementally. - -**Integration**: Works with VS Code, Cursor, GitHub Actions, pre-commit hooks. See [Integration Showcases](../examples/integration-showcases/) for real examples. - -### Step 1: Analyze Legacy Code - -```bash -# Full repository analysis -specfact code import legacy-api --repo . - -# For large codebases, analyze specific modules: -specfact code import core-module --repo . --entry-point src/core -specfact code import api-module --repo . --entry-point src/api -``` - -### Step 2: Review Extracted Specs - -```bash -# Compare and review bundle contents -specfact plan compare --bundle legacy-api -``` - -**Note**: Use CLI commands to interact with bundles. The bundle structure (`.specfact/projects//`) is managed by SpecFact CLI - use commands like `plan compare`, `plan add-feature`, `plan update-feature` to modify bundles, not direct file editing. - -### Step 3: Add Contracts Incrementally - -```bash -# Start in shadow mode -specfact enforce stage --preset minimal -``` - -See [Brownfield Journey Guide](brownfield-journey.md) for complete workflow. - -### Partial Repository Coverage - -For large codebases or monorepos with multiple projects, use `--entry-point` to analyze specific subdirectories: - -```bash -# Analyze individual projects in a monorepo -specfact code import api-service --repo . --entry-point projects/api-service -specfact code import web-app --repo . --entry-point projects/web-app -specfact code import mobile-app --repo . --entry-point projects/mobile-app - -# Analyze specific modules for incremental modernization -specfact code import core-module --repo . --entry-point src/core -specfact code import integrations-module --repo . --entry-point src/integrations -``` - -**Benefits:** - -- **Faster analysis** - Focus on specific modules for quicker feedback -- **Incremental modernization** - Modernize one module at a time -- **Multi-bundle support** - Create separate project bundles for different projects/modules -- **Better organization** - Keep bundles organized by project boundaries - -**Note:** When using `--entry-point`, each analysis creates a separate project bundle. Use `specfact plan compare` to compare different bundles. - ---- - -## Bridge Adapter Sync (Secondary) - -Keep SpecFact synchronized with external tools (Spec-Kit, OpenSpec, GitHub Issues, etc.) via the plugin-based adapter registry. - -**Supported Adapters**: - -- **Spec-Kit** (`--adapter speckit`) - Bidirectional sync for interactive authoring -- **OpenSpec** (`--adapter openspec`) - Read-only sync for change proposal tracking (v0.22.0+) -- **GitHub Issues** (`--adapter github`) - Export change proposals to DevOps backlogs -- **Future**: Linear, Jira, Azure DevOps, and more - -**Note**: SpecFact CLI uses a plugin-based adapter registry pattern. All adapters are registered in `AdapterRegistry` and accessed via `specfact sync bridge --adapter `, making the architecture extensible for future tool integrations. - -### Spec-Kit Bidirectional Sync - -Keep Spec-Kit and SpecFact synchronized automatically. - -#### One-Time Sync - -```bash -specfact sync bridge --adapter speckit --bundle --repo . --bidirectional -``` - -**What it does**: - -- Syncs Spec-Kit artifacts โ†’ SpecFact project bundles -- Syncs SpecFact project bundles โ†’ Spec-Kit artifacts -- Resolves conflicts automatically (SpecFact takes priority) - -**When to use**: - -- After migrating from Spec-Kit -- When you want to keep both tools in sync -- Before making changes in either tool - -#### Watch Mode (Continuous Sync) - -```bash -specfact sync bridge --adapter speckit --bundle --repo . --bidirectional --watch --interval 5 -``` - -**What it does**: - -- Monitors file system for changes -- Automatically syncs when files are created/modified -- Runs continuously until interrupted (Ctrl+C) - -**When to use**: - -- During active development -- When multiple team members use both tools -- For real-time synchronization - -**Example**: - -```bash -# Terminal 1: Start watch mode -specfact sync bridge --adapter speckit --bundle my-project --repo . --bidirectional --watch --interval 5 - -# Terminal 2: Make changes in Spec-Kit -echo "# New Feature" >> specs/002-new-feature/spec.md - -# Watch mode automatically detects and syncs -# Output: "Detected 1 change(s), syncing..." -``` - -#### What Gets Synced - -- `specs/[###-feature-name]/spec.md` โ†” `.specfact/projects//features/FEATURE-*.yaml` -- `specs/[###-feature-name]/plan.md` โ†” `.specfact/projects//product.yaml` -- `specs/[###-feature-name]/tasks.md` โ†” `.specfact/projects//features/FEATURE-*.yaml` -- `.specify/memory/constitution.md` โ†” SpecFact business context (business.yaml) -- `specs/[###-feature-name]/contracts/*.yaml` โ†” `.specfact/protocols/*.yaml` - -**Note**: When syncing from SpecFact to Spec-Kit, all required Spec-Kit fields (frontmatter, INVSEST criteria, Constitution Check, Phases, Technology Stack, Story mappings) are automatically generated. No manual editing required - generated artifacts are ready for `/speckit.analyze`. - -### OpenSpec Read-Only Sync - -Sync OpenSpec change proposals to SpecFact (v0.22.0+): - -```bash -# Read-only sync from OpenSpec to SpecFact -specfact sync bridge --adapter openspec --mode read-only \ - --bundle my-project \ - --repo /path/to/openspec-repo -``` - -**What it does**: - -- Reads OpenSpec change proposals from `openspec/changes/` -- Syncs proposals to SpecFact change tracking -- Read-only mode (does not modify OpenSpec files) - -**When to use**: - -- When working with OpenSpec change proposals -- For tracking OpenSpec proposals in SpecFact format -- Before exporting proposals to DevOps tools - -See [OpenSpec Journey Guide](openspec-journey.md) for complete integration workflow. - ---- - -## Repository Sync Workflow - -Keep plan artifacts updated as code changes. - -### One-Time Repository Sync - -```bash -specfact sync repository --repo . --target .specfact -``` - -**What it does**: - -- Analyzes code changes -- Updates plan artifacts -- Detects deviations from manual plans - -**When to use**: - -- After making code changes -- Before comparing plans -- To update auto-derived plans - -### Repository Watch Mode (Continuous Sync) - -```bash -specfact sync repository --repo . --watch --interval 5 -``` - -**What it does**: - -- Monitors code files for changes -- Automatically updates plan artifacts -- Triggers sync when files are created/modified/deleted - -**When to use**: - -- During active development -- For real-time plan updates -- When code changes frequently - -**Example**: - -```bash -# Terminal 1: Start watch mode -specfact sync repository --repo . --watch --interval 5 - -# Terminal 2: Make code changes -echo "class NewService:" >> src/new_service.py - -# Watch mode automatically detects and syncs -# Output: "Detected 1 change(s), syncing..." -``` - ---- - -## Enforcement Workflow - -Progressive enforcement from observation to blocking. - -### Step 1: Shadow Mode (Observe Only) - -```bash -specfact enforce stage --preset minimal -``` - -**What it does**: - -- Sets enforcement to LOG only -- Observes violations without blocking -- Collects metrics and reports - -**When to use**: - -- Initial setup -- Understanding current state -- Baseline measurement - -### Step 2: Balanced Mode (Warn on Issues) - -```bash -specfact enforce stage --preset balanced -``` - -**What it does**: - -- BLOCKs HIGH severity violations -- WARNs on MEDIUM severity violations -- LOGs LOW severity violations - -**When to use**: - -- After stabilization period -- When ready for warnings -- Before production deployment - -### Step 3: Strict Mode (Block Everything) - -```bash -specfact enforce stage --preset strict -``` - -**What it does**: - -- BLOCKs all violations (HIGH, MEDIUM, LOW) -- Enforces all rules strictly -- Production-ready enforcement - -**When to use**: - -- Production environments -- After full validation -- When all issues are resolved - -### Running Validation - -```bash -# First-time setup: Configure CrossHair for contract exploration -specfact repro setup - -# Quick validation -specfact repro - -# Verbose validation with budget -specfact repro --verbose --budget 120 - -# Apply auto-fixes -specfact repro --fix --budget 120 -``` - -**What it does**: - -- `repro setup` configures CrossHair for contract exploration (one-time setup) -- `repro` validates contracts -- Checks types -- Detects async anti-patterns -- Validates state machines -- Applies auto-fixes (if available) - ---- - -## Plan Comparison Workflow - -Compare manual plans vs auto-derived plans to detect deviations. - -### Quick Comparison - -```bash -specfact plan compare --bundle legacy-api -``` - -**What it does**: - -- Compares two project bundles (manual vs auto-derived) -- Finds bundles in `.specfact/projects/` -- Compares and reports deviations - -**When to use**: - -- After code changes -- Before merging PRs -- Regular validation - -### Detailed Comparison - -```bash -specfact plan compare \ - --manual .specfact/projects/manual-plan \ - --auto .specfact/projects/auto-derived \ - --out comparison-report.md -``` - -**Note**: Commands accept bundle directory paths, not individual files. - -**What it does**: - -- Compares specific plans -- Generates detailed report -- Shows all deviations with severity - -**When to use**: - -- Investigating specific deviations -- Generating reports for review -- Deep analysis - -### Code vs Plan Comparison - -```bash -specfact plan compare --bundle legacy-api --code-vs-plan -``` - -**What it does**: - -- Compares current code state vs manual plan -- Auto-derives plan from code -- Compares in one command - -**When to use**: - -- Quick drift detection -- Before committing changes -- CI/CD validation - ---- - -## Daily Development Workflow - -Typical workflow for daily development. - -### Morning: Check Status - -```bash -# Validate everything -specfact repro --verbose - -# Compare plans -specfact plan compare --bundle legacy-api -``` - -**What it does**: - -- Validates current state -- Detects any deviations -- Reports issues - -### During Development: Watch Mode +When you need exact syntax, verify against live help in the current release, for example: ```bash -# Start watch mode for repository sync -specfact sync repository --repo . --watch --interval 5 +specfact project sync bridge --help +specfact code repro --help +specfact code validate sidecar --help +specfact spec validate --help +specfact govern enforce --help ``` -**What it does**: - -- Monitors code changes -- Updates plan artifacts automatically -- Keeps plans in sync - -### Before Committing: Validate - -```bash -# Run validation -specfact repro - -# Compare plans -specfact plan compare --bundle legacy-api -``` - -**What it does**: - -- Ensures no violations -- Detects deviations -- Validates contracts - -### After Committing: CI/CD - -```bash -# CI/CD pipeline runs -specfact repro --verbose --budget 120 -``` - -**What it does**: - -- Validates in CI/CD -- Blocks merges on violations -- Generates reports - ---- - -## Migration Workflow - -Complete workflow for migrating from Spec-Kit or OpenSpec. - -### Spec-Kit Migration - -#### Step 1: Preview - -```bash -specfact sync bridge --adapter speckit --repo . --dry-run -``` - -**What it does**: - -- Analyzes Spec-Kit project using bridge adapter -- Shows what will be imported -- Does not modify anything - -#### Step 2: Execute - -```bash -specfact sync bridge --adapter speckit --repo . --write -``` - -**What it does**: - -- Imports Spec-Kit artifacts using bridge adapter -- Creates modular project bundle structure -- Converts to SpecFact format (multiple aspect files) - -#### Step 3: Set Up Sync - -```bash -specfact sync bridge --adapter speckit --bundle --repo . --bidirectional --watch --interval 5 -``` - -**What it does**: - -- Enables bidirectional sync via Spec-Kit adapter -- Keeps both tools in sync -- Monitors for changes - -### OpenSpec Integration - -Sync with OpenSpec change proposals (v0.22.0+): - -```bash -# Read-only sync from OpenSpec to SpecFact -specfact sync bridge --adapter openspec --mode read-only \ - --bundle my-project \ - --repo /path/to/openspec-repo - -# Export OpenSpec change proposals to GitHub Issues -specfact sync bridge --adapter github --mode export-only \ - --repo-owner your-org \ - --repo-name your-repo \ - --repo /path/to/openspec-repo -``` - -**What it does**: - -- Reads OpenSpec change proposals using OpenSpec adapter -- Syncs proposals to SpecFact change tracking -- Exports proposals to DevOps tools via GitHub adapter - -See [OpenSpec Journey Guide](openspec-journey.md) for complete integration workflow. - -### Step 4: Enable Enforcement - -```bash -# Start in shadow mode -specfact enforce stage --preset minimal - -# After stabilization, enable warnings -specfact enforce stage --preset balanced - -# For production, enable strict mode -specfact enforce stage --preset strict -``` - -**What it does**: - -- Progressive enforcement -- Gradual rollout -- Production-ready - ---- - -## Related Documentation - -- **[Integration Showcases](../examples/integration-showcases/)** โญ - Real bugs fixed via VS Code, Cursor, GitHub Actions integrations -- [Use Cases](use-cases.md) - Detailed use case scenarios -- [Command Reference](../reference/commands.md) - All commands with examples -- [Troubleshooting](troubleshooting.md) - Common issues and solutions -- [IDE Integration](ide-integration.md) - Set up slash commands - ---- - -**Happy building!** ๐Ÿš€ +This page needs a full rewrite around the mounted command groups before task-level workflow examples can be published again. diff --git a/docs/reference/README.md b/docs/reference/README.md index 0ea2fc7..66907c3 100644 --- a/docs/reference/README.md +++ b/docs/reference/README.md @@ -30,18 +30,17 @@ Complete technical reference for the official modules site and bundle-owned work ### Commands -- `specfact sync bridge --adapter speckit --bundle ` - Import from external tools via bridge adapter +- `specfact project sync bridge --adapter speckit --bundle ` - Import from external tools via bridge adapter - `specfact code import ` - Reverse-engineer plans from code -- `specfact plan init ` - Initialize new development plan -- `specfact plan compare` - Compare manual vs auto plans -- `specfact enforce stage` - Configure quality gates -- `specfact repro` - Run full validation suite -- `specfact sync bridge --adapter --bundle ` - Sync with external tools via bridge adapter +- `specfact code analyze contracts` - Analyze contract coverage for a codebase bundle +- `specfact govern enforce stage` - Configure quality gates +- `specfact code repro` - Run the reproducibility validation suite +- `specfact project sync bridge --adapter --bundle ` - Sync with external tools via bridge adapter - `specfact spec validate [--bundle ]` - Validate OpenAPI/AsyncAPI specifications - `specfact spec generate-tests [--bundle ]` - Generate contract tests from specifications - `specfact spec mock [--bundle ]` - Launch mock server for development - `specfact init ide --ide ` - Initialize IDE integration explicitly -- `specfact module install [--scope user|project] [--source auto|bundled|marketplace] [--repo PATH]` - Install modules with scope and source control (bare names normalize to `specfact/`) +- `specfact module install [--scope user|project] [--source auto|bundled|marketplace] [--repo PATH]` - Install modules with scope and source control - `specfact module list [--source ...] [--show-origin] [--show-bundled-available]` - List modules with trust/publisher, optional origin details, and optional bundled-not-installed section - `specfact module show ` - Show detailed module metadata and full command tree with short descriptions - `specfact module search ` - Search marketplace and installed modules diff --git a/docs/reference/command-syntax-policy.md b/docs/reference/command-syntax-policy.md index 1adee46..2992786 100644 --- a/docs/reference/command-syntax-policy.md +++ b/docs/reference/command-syntax-policy.md @@ -16,15 +16,15 @@ Always document commands exactly as implemented by `specfact --help` i - Do not assume all commands use the same bundle argument style. - Do not convert positional bundle arguments to `--bundle` unless the command explicitly supports it. -## Bundle Argument Conventions (v0.30.x baseline) +## Bundle Argument Conventions - Positional bundle argument: - `specfact code import [BUNDLE]` - - `specfact plan init BUNDLE` - - `specfact plan compare [BUNDLE]` - `--bundle` option: - - Supported by many plan mutation commands (for example `plan add-feature`, `plan add-story`, `plan update-feature`) - - Not universally supported across all commands + - Supported by commands such as `specfact project sync bridge --bundle ` + - Not universally supported across all commands, so always verify with `--help` + +For callback-style commands such as `specfact code import`, keep options before the positional bundle argument in examples, for example `specfact code import --repo . legacy-api`. ## IDE Init Syntax @@ -44,8 +44,7 @@ Before merging command docs updates: ```bash hatch run specfact code import --help -hatch run specfact plan init --help -hatch run specfact plan compare --help -hatch run specfact plan add-feature --help +hatch run specfact project sync bridge --help +hatch run specfact code validate sidecar --help +hatch run specfact govern enforce --help ``` - diff --git a/docs/reference/commands.md b/docs/reference/commands.md index 83dbcbe..a3cab33 100644 --- a/docs/reference/commands.md +++ b/docs/reference/commands.md @@ -10,27 +10,27 @@ SpecFact CLI ships a lean core. Workflow commands are installed from marketplace ## Top-Level Commands -Root command surface includes core commands and installed command groups: +Root command surface includes core commands and the mounted bundle command groups visible in `specfact --help`: - `specfact init` -- `specfact auth` - `specfact module` - `specfact upgrade` -- `specfact plan ...` -- `specfact sync ...` - `specfact code ...` - `specfact backlog ...` - `specfact project ...` - `specfact spec ...` -- `specfact enforce ...` -- `specfact analyze ...` -- `specfact drift ...` -- `specfact validate ...` -- `specfact repro ...` -- `specfact generate ...` -- `specfact sdd ...` -- `specfact contract ...` -- `specfact review` +- `specfact govern ...` + +Nested mounted groups in the current release include: + +- `specfact code review ...` +- `specfact code analyze ...` +- `specfact code drift ...` +- `specfact code validate ...` +- `specfact code repro ...` +- `specfact project sync ...` +- `specfact govern enforce ...` +- `specfact govern patch ...` Use `specfact init --profile ` (or `--install `) to install workflow bundles. @@ -38,12 +38,12 @@ Use `specfact init --profile ` (or `--install `) to install workflow | Bundle ID | Main command families | |---|---| -| `nold-ai/specfact-project` | `plan`, `project`, `sync`, `migrate`, `code import` | +| `nold-ai/specfact-project` | `project`, `project sync` | | `nold-ai/specfact-backlog` | `backlog` | -| `nold-ai/specfact-codebase` | `code import`, `analyze`, `drift`, `validate`, `repro` | -| `nold-ai/specfact-spec` | `spec`, `contract`, `sdd`, `generate` | -| `nold-ai/specfact-govern` | `enforce` | -| `nold-ai/specfact-code-review` | `review` | +| `nold-ai/specfact-codebase` | `code import`, `code analyze`, `code drift`, `code validate`, `code repro` | +| `nold-ai/specfact-spec` | `spec` | +| `nold-ai/specfact-govern` | `govern`, `govern enforce`, `govern patch` | +| `nold-ai/specfact-code-review` | `code review` | ## Common Flows @@ -55,12 +55,12 @@ specfact init --profile solo-developer specfact module install nold-ai/specfact-backlog # Project workflow examples -specfact code import legacy-api --repo . -specfact plan init my-project +specfact code import --repo . legacy-api +specfact project sync bridge --adapter github --mode export-only --repo . # Code workflow examples -specfact validate sidecar init legacy-api /path/to/repo -specfact repro --verbose +specfact code validate sidecar init legacy-api /path/to/repo +specfact code repro --verbose # Backlog workflow examples specfact backlog refine --help diff --git a/docs/reference/debug-logging.md b/docs/reference/debug-logging.md index e99044c..1a87662 100644 --- a/docs/reference/debug-logging.md +++ b/docs/reference/debug-logging.md @@ -4,187 +4,18 @@ title: Debug Logging permalink: /debug-logging/ --- - -# Debug Logging +# Legacy Workflow Note -When you run SpecFact CLI with the global `--debug` flag, the CLI writes debug output to your **console** and to a **rotating log file** under your user directory. This helps diagnose I/O, API, and template issues without cluttering normal output. +This page referenced command groups or workflow steps that are no longer part of the current public mounted CLI in this repository. The old examples were removed to avoid directing readers to unavailable commands. -## For Users +Use the current mounted entrypoints instead: -### Enabling Debug Mode +- `specfact project --help` +- `specfact project sync --help` +- `specfact code --help` +- `specfact code review --help` +- `specfact spec --help` +- `specfact govern --help` +- `specfact backlog --help` -Pass `--debug` before any command: - -```bash -specfact --debug init -specfact --debug backlog refine --adapter ado --project my-project -specfact --debug plan select -``` - -Debug output appears in the terminal and is also appended to a log file. - -### Where Logs Are Written - -| Location | Purpose | -|---------|---------| -| **Console** | Same debug messages you see in the terminal (Rich formatting). | -| **`~/.specfact/logs/specfact-debug.log`** | Rotating log file (plain text). Created on first use when `--debug` is set. Directory is created with mode `0o755` if missing. | - -- **Path**: `~` is your home directory (e.g. `/home/you` on Linux, `C:\Users\you` on Windows). -- **Rotation**: The file rotates at 5 MB and keeps up to 5 backup files (`specfact-debug.log.1`, โ€ฆ). -- **Scope**: User-level only; not tied to a specific repo or bundle. - -### What Gets Logged - -When `--debug` is on, the CLI logs: - -1. **Debug messages** - Any line emitted via the internal `debug_print()`: template resolution steps, path discovery, fallbacks (e.g. in `specfact init`). Each line is prefixed with a **timestamp** and **caller** (module and function) for context. - -2. **Structured operation metadata** - One JSON line per operation, with: - - **operation** โ€“ Type (e.g. `api_request`, `file_read`, `template_resolution`). - - **target** โ€“ Path or URL (sensitive parts redacted). - - **status** โ€“ Result (e.g. `success`, HTTP status, `error`, `prepared`, `finished`, `failed`). - - **caller** โ€“ Module and function that logged the operation (for context). - - **error** โ€“ Optional error message on failure. - - **extra** โ€“ Optional extra fields (redacted); for API calls may include payload (sanitized), response, reason. - -**Log format**: Every line in the debug log file starts with a timestamp (`YYYY-MM-DD HH:MM:SS`), then a pipe and the message or structured JSON. Narrative lines include caller (module:function) before the message. File operations log status `prepared`/`finished`/`failed`; API operations log operation, URL (redacted), payload (sanitized), response, status, error, and reason where applicable. - -**Redaction**: URLs, paths, and `extra` are passed through `LoggerSetup.redact_secrets` so tokens and secrets are masked in the log file. - -### What Is Logged by Component - -| Component | Operations / events logged (when `--debug`) | -|----------|---------------------------------------------| -| **auth azure-devops** | Start, success (PAT or OAuth), or error; key steps (OAuth flow, device code) when `--debug` is on. | -| **init** | Template resolution: paths tried, success/failure, fallbacks (e.g. development path, package path, `importlib` fallbacks). | -| **backlog refine** | File read for import: path, success/error (e.g. `--import-from-tmp`). File write for export: path, success/error (e.g. `--export-to-tmp`). | -| **Azure DevOps adapter** | WIQL request (redacted URL, method, status); Work Items GET (redacted URL, status); Work Items PATCH (redacted URL, status). On PATCH failure: structured log with `operation=ado_patch`, `status=failed`, and `extra` containing `response_body` (redacted snippet of ADO error payload) and `patch_paths` (JSON Patch paths attempted). | -| **GitHub adapter** | API request/response (redacted URL, method, status); on failure, redacted error snippet. | - -### Example Log Snippets - -**Plain debug line (from `debug_print`; timestamp and caller prefixed):** - -```text -2025-01-28 14:30:00 | specfact_cli.commands.init:run | Debug: Trying development path: /path/to/templates -``` - -**Structured operation (from `debug_log_operation`; timestamp prefixed by formatter):** - -```text -2025-01-28 14:30:01 | debug_log_operation {"operation": "file_read", "target": "/path/to/export.md", "status": "success", "caller": "specfact_cli.commands.backlog_commands:export_backlog"} -2025-01-28 14:30:02 | debug_log_operation {"operation": "ado_wiql", "target": "https://dev.azure.com/***/***/_apis/...", "status": "200", "caller": "specfact_cli.adapters.ado:..."} -2025-01-28 14:30:03 | debug_log_operation {"operation": "template_resolution", "target": "/usr/lib/.../templates/backlog", "status": "success", "caller": "specfact_cli.commands.init:..."} -``` - -### Troubleshooting With Debug Logs - -1. Run the failing command with `--debug`: - - ```bash - specfact --debug - ``` - -2. Reproduce the issue, then open `~/.specfact/logs/specfact-debug.log`. -3. Look for: - - **template_resolution** โ€“ Where `init` looked for templates and whether it succeeded. - - **file_read** / **file_write** โ€“ Paths and success/error for backlog export/import. - - **ado_wiql**, **ado_get**, **ado_patch** โ€“ ADO API calls (URLs redacted, status/error present). - - **api_request** โ€“ GitHub (or other) API calls with status and optional error. - -See also [Troubleshooting](../guides/troubleshooting.md). - -### Examining ADO API Errors - -When an Azure DevOps PATCH fails (e.g. HTTP 400 during `backlog refine ado` or work item update), the CLI does two things: - -1. **Console** โ€“ You see the ADO error message and a short hint (e.g. "Check custom field mapping; see ado_custom.yaml or documentation."). If the ADO message names a field (e.g. "Cannot find field System.AcceptanceCriteria"), that field is highlighted so you can fix mapping or template issues. - -2. **Debug log** (only when `--debug` is on) โ€“ One structured line is written with: - - **operation**: `ado_patch` - - **status**: `failed` - - **error**: Parsed ADO message or short summary - - **extra.response_body**: Redacted snippet of the ADO response (up to ~1โ€“2 KB). Use this to see the exact server error (e.g. TF51535, field name). - - **extra.patch_paths**: List of JSON Patch paths that were sent (e.g. `["/fields/System.AcceptanceCriteria", "/fields/System.Description"]`). Use this to see which field path failed. - -To analyze an ADO API error: - -1. Run the command with `--debug` and reproduce the failure. -2. In the console, read the red error line: it contains the ADO message and the custom-mapping hint. -3. Open `~/.specfact/logs/specfact-debug.log` and search for `"operation": "ado_patch"` and `"status": "failed"`. -4. In that line, use `extra.response_body` to see the serverโ€™s error text and `extra.patch_paths` to see which field paths were attempted. -5. If the error is about a missing or invalid field (e.g. custom process template), update [custom field mapping](../guides/custom-field-mapping.md) (e.g. `.specfact/templates/backlog/field_mappings/ado_custom.yaml`) or see [Azure DevOps Issues](../guides/troubleshooting.md#azure-devops-issues) in Troubleshooting. - ---- - -## For Developers - -### Debug log standard (apply consistently) - -Debug logs are **critical for anomaly analysis, unexpected errors/failures, reporting, and bug reports**. Every debug log must follow the same pattern so logs are useful like in a regular production toolโ€”**no single-line INFO-style entries**; every significant operation must provide **full context**. - -**Required pattern for every significant operation:** - -| Phase | What to log | Example status / extra | -|-------|----------------|-------------------------| -| **Started / prepared** | Once when the operation begins | `status=started` or `prepared`; `target`; `extra` (e.g. flow, method, cache) | -| **Progress / attempt** | For each distinct step (if multi-step) | `status=attempt`; `extra.method`, `extra.reason` (what was tried) | -| **Outcome** | Exactly once when the operation ends | **Success**: `status=success` (or HTTP status); `extra` (method, cache, reason). **Failure**: `status=failed` or `error`; `error=`; `extra.reason` | - -**Minimum content:** - -- **Every line**: timestamp (automatic), caller (automatic or explicit). -- **Structured lines**: `operation`, `target` (redacted), `status`; when applicable: `error`, `extra` (payload, response, reason, method, cacheโ€”sanitized). - -**Apply everywhere:** Auth flows, file I/O, API calls, template resolution, and any operation that can fail or affect behavior. Reference: `auth azure-devops` (started โ†’ cache_prepared โ†’ attempt interactive_browser โ†’ success/fallback โ†’ attempt device_code โ†’ success/failed โ†’ success token_stored). - -### Runtime API - -- **`specfact_cli.runtime.set_debug_mode(debug: bool)`** - Turn global debug mode on or off (e.g. from the CLI callback when `--debug` is set). - -- **`specfact_cli.runtime.is_debug_mode() -> bool`** - Returns whether debug mode is currently on. - -- **`specfact_cli.runtime.init_debug_log_file()`** - Ensures the debug log file under `~/.specfact/logs` is created and the file handler is set up. Called by the CLI when `--debug` is True so the first write goes to the file immediately. - -- **`specfact_cli.runtime.debug_print(*args, **kwargs)`** - If debug is on: prints to the configured Rich console and appends a plain-text line to `~/.specfact/logs/specfact-debug.log` (args only; no Rich markup in the file). If debug is off: no-op. - -- **`specfact_cli.runtime.debug_log_operation(operation, target, status, error=None, extra=None, caller=None)`** - If debug is on: writes one JSON line to the debug log file with `operation`, `target`, `status`, optional `error`, optional `extra`, and `caller` (inferred if not provided). `target` and `extra` are redacted via `LoggerSetup.redact_secrets`. If debug is off: no-op. Follow the debug log standard: log started/prepared โ†’ attempt โ†’ success/failed with reason. - -### User-Level Log Directory - -- **`specfact_cli.common.logger_setup.get_specfact_home_logs_dir() -> str`** - Returns `os.path.expanduser("~/.specfact/logs")`, creating the directory with `mode=0o755` and `exist_ok=True` on first use. Use this if you need the path for the debug log or related files. - -### When to Use What - -- **`debug_print(...)`** - For human-oriented messages (template paths, โ€œtrying Xโ€, โ€œusing Yโ€). Shown in console and written as a single plain line to the log file. - -- **`debug_log_operation(...)`** - For machine-friendly operation records (API calls, file I/O, template resolution result). Always use for URLs or paths; redaction is applied to `target` and `extra`. - -### Adding New Log Points - -1. **Follow the debug log standard** - For each significant operation: log **started/prepared** โ†’ **attempt** (if multi-step) โ†’ **success** or **failed** with **reason/error**. Include operation, target, status, error, extra (payload/response/reasonโ€”sanitized). Never log only one line for an operation that can succeed or fail; always log outcome and reason. - -2. **New adapter or command** - When `is_debug_mode()` is True, call `debug_log_operation(operation, target, status, error=..., extra=..., caller=...)` at start, at each attempt, and at outcome. Use clear operation names (e.g. `ado_wiql`, `file_read`, `template_resolution`). For file ops: prepared โ†’ finished/failed. For API ops: attempt โ†’ success/failed with payload (sanitized), response, reason. - -3. **New debug messages** - Use `debug_print(...)` for narrative steps; they will appear in console and in `specfact-debug.log` as plain text. Prefer pairing with `debug_log_operation` so the log has both human-readable and machine-friendly context. - -4. **Sensitive data** - Pass URLs/paths/tokens only as `target` or inside `extra`; they are redacted before being written to the log file. - -### Relation to Other Logging - -- **`~/.specfact/logs/`** is for the **global** `--debug` session log only (`specfact-debug.log`). It is **not** the same as bundle-specific `.specfact/projects//logs/` (used for other runtime/agent logs). See [Directory Structure](directory-structure.md). +For exact syntax, verify against live help in the current release before copying examples. diff --git a/docs/reference/dependency-resolution.md b/docs/reference/dependency-resolution.md index 9dc4edf..3ba4da9 100644 --- a/docs/reference/dependency-resolution.md +++ b/docs/reference/dependency-resolution.md @@ -38,8 +38,8 @@ Resolution is used only for **marketplace** installs. Bundled and custom modules ## Bypass options -- **Skip resolution**: `specfact module install specfact/backlog --skip-deps` installs only `specfact/backlog` and does not pull or check its `pip_dependencies` / `module_dependencies`. -- **Override conflicts**: `specfact module install specfact/backlog --force` proceeds even when the resolver reports conflicts. Enable/disable and dependency-aware cascades may still use `--force` where applicable. +- **Skip resolution**: `specfact module install nold-ai/specfact-backlog --skip-deps` installs only `nold-ai/specfact-backlog` and does not pull or check its `pip_dependencies` / `module_dependencies`. +- **Override conflicts**: `specfact module install nold-ai/specfact-backlog --force` proceeds even when the resolver reports conflicts. Enable/disable and dependency-aware cascades may still use `--force` where applicable. ## See also diff --git a/docs/reference/directory-structure.md b/docs/reference/directory-structure.md index 320deb2..c6f1f7f 100644 --- a/docs/reference/directory-structure.md +++ b/docs/reference/directory-structure.md @@ -4,758 +4,29 @@ title: SpecFact CLI Directory Structure permalink: /directory-structure/ --- -# SpecFact CLI Directory Structure +# Legacy Workflow Note -This document defines the canonical directory structure for SpecFact CLI artifacts. +This page described older `specfact plan`, `specfact generate`, `specfact contract`, or `specfact sdd constitution` workflows that are not part of the current public mounted CLI in this repository. The detailed command examples previously documented here were removed because they no longer match the command surface exposed by `specfact --help`. -> **Primary Use Case**: SpecFact CLI is designed for **brownfield code modernization** - reverse-engineering existing codebases into documented specs with runtime contract enforcement. The directory structure reflects this brownfield-first approach. +Use the current mounted entrypoints instead: -**CLI-First Approach**: SpecFact works offline, requires no account, and integrates with your existing workflow. Works with VS Code, Cursor, GitHub Actions, pre-commit hooks, or any IDE. No platform to learn, no vendor lock-in. +- `specfact project --help` +- `specfact project sync --help` +- `specfact code --help` +- `specfact code review --help` +- `specfact spec --help` +- `specfact govern --help` +- `specfact backlog --help` +- `specfact module --help` -## Overview - -All SpecFact artifacts are stored under `.specfact/` in the repository root. This ensures: - -- **Consistency**: All artifacts in one predictable location -- **Multiple plans**: Support for multiple project bundles in a single repository -- **Gitignore-friendly**: Easy to exclude reports from version control -- **Clear separation**: Plans (versioned) vs reports (ephemeral) -- **CLI-first**: All artifacts are local, no cloud storage required - -**User-level debug logs**: When you run with `--debug`, the CLI also writes a rotating debug log under your home directory: `~/.specfact/logs/specfact-debug.log`. This is separate from repo-level `.specfact/` and is used only for global debug output. See [Debug Logging](debug-logging.md). - -**User-level registry** (v0.27+): After you run `specfact init`, the CLI creates `~/.specfact/registry/` with: - -- `commands.json` โ€“ Command names and help text used for fast root `specfact --help` without loading every command module. -- `modules.json` โ€“ Per-module state (id, version, enabled) for optional module packages. - - Managed by `specfact module ...` commands (`init`, `list`, `install`, `enable`, `disable`, `uninstall`, `upgrade`) - - Supports dependency-safe lifecycle operations with optional `--force` cascading behavior - -`specfact init` is bootstrap-focused; module lifecycle is canonical under `specfact module`. IDE prompt/template setup is handled by `specfact init ide`. - -**Module artifact roots**: - -- Canonical per-user module root: `/.specfact/modules` -- Optional workspace-local module root: `/.specfact/modules` -- Module denylist file: `/.specfact/module-denylist.txt` (override with `SPECFACT_MODULE_DENYLIST_FILE`) -- Trusted non-official publisher decisions are stored in `/.specfact/metadata.json` -- SpecFact does **not** auto-discover `/modules` to avoid assuming ownership of non-`.specfact` repository paths. -- In repository context, `/.specfact/modules` has higher discovery precedence than `/.specfact/modules`. - -For how the CLI discovers and loads commands from module packages (registry, module-package.yaml, lazy loading), see [Architecture โ€“ Modules design](architecture.md#modules-design). - -## Canonical Structure - -```bash -.specfact/ -โ”œโ”€โ”€ config.yaml # SpecFact configuration (optional) -โ”œโ”€โ”€ config/ # Global configuration (optional) -โ”‚ โ”œโ”€โ”€ bridge.yaml # Bridge configuration for external tools -โ”‚ โ””โ”€โ”€ ... -โ”œโ”€โ”€ cache/ # Shared cache (gitignored, global for performance) -โ”‚ โ”œโ”€โ”€ dependency-graph.json -โ”‚ โ””โ”€โ”€ commit-history.json -โ”œโ”€โ”€ projects/ # Modular project bundles (versioned in git) -โ”‚ โ”œโ”€โ”€ / # Project bundle directory -โ”‚ โ”‚ โ”œโ”€โ”€ bundle.manifest.yaml # Bundle metadata, versioning, and checksums -โ”‚ โ”‚ โ”œโ”€โ”€ idea.yaml # Product vision (optional) -โ”‚ โ”‚ โ”œโ”€โ”€ business.yaml # Business context (optional) -โ”‚ โ”‚ โ”œโ”€โ”€ product.yaml # Releases, themes (required) -โ”‚ โ”‚ โ”œโ”€โ”€ clarifications.yaml # Clarification sessions (optional) -โ”‚ โ”‚ โ”œโ”€โ”€ sdd.yaml # SDD manifest (bundle-specific, Phase 8.5) -โ”‚ โ”‚ โ”œโ”€โ”€ tasks.yaml # Task breakdown (bundle-specific, Phase 8.5) -โ”‚ โ”‚ โ”œโ”€โ”€ features/ # Individual feature files -โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ FEATURE-001.yaml -โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ FEATURE-002.yaml -โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ ... -โ”‚ โ”‚ โ”œโ”€โ”€ contracts/ # OpenAPI contracts (bundle-specific) -โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ ... -โ”‚ โ”‚ โ”œโ”€โ”€ protocols/ # FSM protocols (bundle-specific) -โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ ... -โ”‚ โ”‚ โ”œโ”€โ”€ reports/ # Bundle-specific reports (gitignored, Phase 8.5) -โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ brownfield/ -โ”‚ โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ analysis-2025-10-31T14-30-00.md -โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ comparison/ -โ”‚ โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ report-2025-10-31T14-30-00.md -โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ enrichment/ -โ”‚ โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ -2025-10-31T14-30-00.enrichment.md -โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ enforcement/ -โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ report-2025-10-31T14-30-00.yaml -โ”‚ โ”‚ โ”œโ”€โ”€ logs/ # Bundle-specific logs (gitignored, Phase 8.5) -โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ 2025-10-31T14-30-00.log -โ”‚ โ”‚ โ””โ”€โ”€ prompts/ # AI IDE contract enhancement prompts (optional) -โ”‚ โ”‚ โ””โ”€โ”€ enhance--.md -โ”‚ โ”œโ”€โ”€ legacy-api/ # Example: Brownfield-derived bundle -โ”‚ โ”‚ โ”œโ”€โ”€ bundle.manifest.yaml -โ”‚ โ”‚ โ”œโ”€โ”€ product.yaml -โ”‚ โ”‚ โ”œโ”€โ”€ sdd.yaml -โ”‚ โ”‚ โ”œโ”€โ”€ tasks.yaml -โ”‚ โ”‚ โ”œโ”€โ”€ features/ -โ”‚ โ”‚ โ”œโ”€โ”€ reports/ -โ”‚ โ”‚ โ””โ”€โ”€ logs/ -โ”‚ โ””โ”€โ”€ my-project/ # Example: Main project bundle -โ”‚ โ”œโ”€โ”€ bundle.manifest.yaml -โ”‚ โ”œโ”€โ”€ idea.yaml -โ”‚ โ”œโ”€โ”€ business.yaml -โ”‚ โ”œโ”€โ”€ product.yaml -โ”‚ โ”œโ”€โ”€ sdd.yaml -โ”‚ โ”œโ”€โ”€ tasks.yaml -โ”‚ โ”œโ”€โ”€ features/ -โ”‚ โ”œโ”€โ”€ reports/ -โ”‚ โ””โ”€โ”€ logs/ -โ””โ”€โ”€ gates/ # Enforcement configuration (global) - โ””โ”€โ”€ config.yaml # Enforcement settings (versioned) -``` - -## Directory Purposes - -### `.specfact/projects/` (Versioned) - -**Purpose**: Store modular project bundles that define the contract for the project. - -**Guidelines**: - -- Each project bundle is stored in its own directory: `.specfact/projects//` -- Each bundle directory contains multiple aspect files: - - `bundle.manifest.yaml` - Bundle metadata, versioning, checksums, and feature index (required) - - **Schema Versioning**: Set `schema_metadata.schema_version` to `"1.1"` to enable change tracking (v0.21.1+) - - **Change Tracking** (v1.1+): Optional `change_tracking` and `change_archive` fields are loaded via bridge adapters (not stored in bundle directory) - - `change_tracking`: Active change proposals and feature deltas (loaded from external tools like OpenSpec) - - `change_archive`: Completed changes with audit trail (loaded from external tools) - - Both fields are optional and backward compatible - v1.0 bundles work without them - - See [Schema Versioning](schema-versioning.md) for details - - `product.yaml` - Product definition with themes and releases (required) - - `idea.yaml` - Product vision and intent (optional) - - `business.yaml` - Business context and market segments (optional) - - `clarifications.yaml` - Clarification sessions and Q&A (optional) - - `sdd.yaml` - SDD manifest (bundle-specific, Phase 8.5, versioned) - - `tasks.yaml` - Task breakdown (bundle-specific, Phase 8.5, versioned) - - `features/` - Directory containing individual feature files: - - `FEATURE-001.yaml` - Individual feature with stories - - `FEATURE-002.yaml` - Individual feature with stories - - Each feature file is self-contained with its stories, acceptance criteria, etc. - - `contracts/` - OpenAPI contract files (bundle-specific, versioned) - - `protocols/` - FSM protocol definitions (bundle-specific, versioned) - - `reports/` - Bundle-specific analysis reports (gitignored, Phase 8.5) - - `logs/` - Bundle-specific execution logs (gitignored, Phase 8.5) -- **Always committed to git** - these are the source of truth (except reports/ and logs/) -- **Phase 8.5**: All bundle-specific artifacts are stored within bundle folders for better isolation -- Use descriptive bundle names: `legacy-api`, `my-project`, `feature-auth` -- Supports multiple bundles per repository for brownfield modernization, monorepos, or feature branches -- Aspect files are YAML format (JSON support may be added in future) - -**Project Bundle Structure:** - -Project bundles are YAML (or JSON) files with the following structure: - -```yaml -version: "1.1" # Schema version (current: 1.1) - -metadata: - stage: "draft" # draft, review, approved, released - summary: # Summary metadata for fast access (added in v1.1) - features_count: 5 - stories_count: 12 - themes_count: 2 - releases_count: 1 - content_hash: "abc123def456..." # SHA256 hash for integrity - computed_at: "2025-01-15T10:30:00" - -idea: - title: "Project Title" - narrative: "Project description" - # ... other idea fields - -product: - themes: ["Theme1", "Theme2"] - releases: [...] - -features: - - key: "FEATURE-001" - title: "Feature Title" - stories: [...] - # ... other feature fields -``` - -**Bundle Manifest Structure (bundle.manifest.yaml):** - -The `bundle.manifest.yaml` file contains bundle metadata and (in v1.1+) optional change tracking fields: - -```yaml -schema_metadata: - schema_version: "1.1" # Set to "1.1" to enable change tracking (v0.21.1+) - project_version: "0.1.0" - -# ... other manifest fields (checksums, feature index, etc.) - -# Optional change tracking fields (v1.1+, loaded via bridge adapters) -change_tracking: null # Optional - loaded via bridge adapters (not stored in bundle directory) -change_archive: [] # Optional - list of archived changes (not stored in bundle directory) -``` - -**Note**: The `change_tracking` and `change_archive` fields are optional and loaded dynamically via bridge adapters (e.g., OpenSpec adapter) rather than being stored directly in the bundle directory. This allows change tracking to be managed by external tools while keeping bundles tool-agnostic. See [Schema Versioning](schema-versioning.md) for details. - -**Summary Metadata (v1.1+):** - -Project bundles version 1.1 and later include summary metadata in the `metadata.summary` section. This provides: - -- **Fast access**: Read plan counts without parsing entire file (44% faster performance) -- **Integrity verification**: Content hash detects plan modifications -- **Performance optimization**: Only reads first 50KB for large files (>10MB) - -**Upgrading Project Bundles:** - -Use `specfact plan upgrade` to migrate older project bundles to the latest schema: - -```bash -# Upgrade active plan -specfact plan upgrade - -# Upgrade all plans -specfact plan upgrade --all - -# Preview upgrades -specfact plan upgrade --dry-run -``` - -See [`plan upgrade`](../reference/commands.md#plan-upgrade) for details. - -**Example**: +When you need exact syntax, verify against live help in the current release, for example: ```bash -.specfact/projects/ -โ”œโ”€โ”€ my-project/ # Primary project bundle -โ”‚ โ”œโ”€โ”€ bundle.manifest.yaml # Metadata, checksums, feature index -โ”‚ โ”œโ”€โ”€ idea.yaml # Product vision -โ”‚ โ”œโ”€โ”€ business.yaml # Business context -โ”‚ โ”œโ”€โ”€ product.yaml # Themes and releases -โ”‚ โ”œโ”€โ”€ features/ # Individual feature files -โ”‚ โ”‚ โ”œโ”€โ”€ FEATURE-001.yaml -โ”‚ โ”‚ โ”œโ”€โ”€ FEATURE-002.yaml -โ”‚ โ”‚ โ””โ”€โ”€ FEATURE-003.yaml -โ”‚ โ””โ”€โ”€ prompts/ # AI IDE contract enhancement prompts (optional) -โ”‚ โ””โ”€โ”€ enhance--.md -โ”œโ”€โ”€ legacy-api/ # โญ Reverse-engineered from existing API (brownfield) -โ”‚ โ”œโ”€โ”€ bundle.manifest.yaml -โ”‚ โ”œโ”€โ”€ product.yaml -โ”‚ โ”œโ”€โ”€ features/ -โ”‚ โ”‚ โ”œโ”€โ”€ FEATURE-AUTH.yaml -โ”‚ โ”‚ โ””โ”€โ”€ FEATURE-PAYMENT.yaml -โ”‚ โ””โ”€โ”€ prompts/ # Bundle-specific prompts (avoids conflicts) -โ”‚ โ””โ”€โ”€ enhance--.md -โ”œโ”€โ”€ legacy-payment/ # โญ Reverse-engineered from existing payment system (brownfield) -โ”‚ โ”œโ”€โ”€ bundle.manifest.yaml -โ”‚ โ”œโ”€โ”€ product.yaml -โ”‚ โ””โ”€โ”€ features/ -โ”‚ โ””โ”€โ”€ FEATURE-PAYMENT.yaml -โ””โ”€โ”€ feature-auth/ # Auth feature bundle - โ”œโ”€โ”€ bundle.manifest.yaml - โ”œโ”€โ”€ product.yaml - โ””โ”€โ”€ features/ - โ””โ”€โ”€ FEATURE-AUTH.yaml +specfact project sync bridge --help +specfact code repro --help +specfact code validate sidecar --help +specfact spec validate --help +specfact govern enforce --help ``` -### `.specfact/protocols/` (Versioned) - -**Purpose**: Store FSM (Finite State Machine) protocol definitions. - -**Guidelines**: - -- Define valid states and transitions -- **Always committed to git** -- Used for workflow validation - -**Example**: - -```bash -.specfact/protocols/ -โ”œโ”€โ”€ development-workflow.protocol.yaml -โ””โ”€โ”€ deployment-pipeline.protocol.yaml -``` - -### Bundle-Specific Artifacts (Phase 8.5) - -**Phase 8.5 Update**: All bundle-specific artifacts are now stored within `.specfact/projects//` folders for better isolation and organization. - -**Bundle-Specific Artifacts**: - -- **Reports**: `.specfact/projects//reports/` (gitignored) - - `brownfield/` - Brownfield analysis reports - - `comparison/` - Plan comparison reports - - `enrichment/` - LLM enrichment reports - - `enforcement/` - SDD enforcement validation reports -- **SDD Manifests**: `.specfact/projects//sdd.yaml` (versioned) -- **Tasks**: `.specfact/projects//tasks.yaml` (versioned) -- **Logs**: `.specfact/projects//logs/` (gitignored) - -**Migration**: Use `specfact migrate artifacts` to move existing artifacts from global locations to bundle-specific folders. - -**Example**: - -```bash -.specfact/projects/legacy-api/ -โ”œโ”€โ”€ bundle.manifest.yaml -โ”œโ”€โ”€ product.yaml -โ”œโ”€โ”€ sdd.yaml # Bundle-specific SDD manifest -โ”œโ”€โ”€ tasks.yaml # Bundle-specific task breakdown -โ”œโ”€โ”€ reports/ # Bundle-specific reports (gitignored) -โ”‚ โ”œโ”€โ”€ brownfield/ -โ”‚ โ”‚ โ””โ”€โ”€ analysis-2025-10-31T14-30-00.md -โ”‚ โ”œโ”€โ”€ comparison/ -โ”‚ โ”‚ โ””โ”€โ”€ report-2025-10-31T14-30-00.md -โ”‚ โ”œโ”€โ”€ enrichment/ -โ”‚ โ”‚ โ””โ”€โ”€ legacy-api-2025-10-31T14-30-00.enrichment.md -โ”‚ โ””โ”€โ”€ enforcement/ -โ”‚ โ””โ”€โ”€ report-2025-10-31T14-30-00.yaml -โ””โ”€โ”€ logs/ # Bundle-specific logs (gitignored) - โ””โ”€โ”€ 2025-10-31T14-30-00.log -``` - -### Legacy Global Locations (Removed) - -**Note**: The following global locations have been removed (Phase 8.5): - -- โŒ `.specfact/plans/` - Removed (active bundle config migrated to `.specfact/config.yaml`) -- โŒ `.specfact/gates/results/` - Removed (enforcement reports are bundle-specific) -- โŒ `.specfact/reports/` - Removed (reports are bundle-specific) -- โŒ `.specfact/sdd/` - Removed (SDD manifests are bundle-specific) -- โŒ `.specfact/tasks/` - Removed (task files are bundle-specific) - -**Migration**: Use `specfact migrate cleanup-legacy` to remove empty legacy directories, and `specfact migrate artifacts` to migrate existing artifacts to bundle-specific locations. - -### `.specfact/gates/` (Versioned) - -**Purpose**: Global enforcement configuration. - -**Guidelines**: - -- `config.yaml` is versioned (defines enforcement policy) -- Enforcement reports are bundle-specific (stored in `.specfact/projects//reports/enforcement/`) - -**Example**: - -```bash -.specfact/gates/ -โ””โ”€โ”€ config.yaml # Versioned: enforcement policy -``` - -**Note**: Enforcement execution reports are stored in bundle-specific locations (Phase 8.5): - -- `.specfact/projects//reports/enforcement/report-.yaml` - -### `.specfact/cache/` (Gitignored) - -**Purpose**: Tool caches for faster execution. - -**Guidelines**: - -- **Gitignored** - optimization only -- Safe to delete anytime -- Automatically regenerated - -## Default Command Paths - -### `specfact code import` โญ PRIMARY - -**Primary use case**: Reverse-engineer existing codebases into project bundles. - -```bash -# Command syntax -specfact code import --repo . [OPTIONS] - -# Creates modular bundle at: -.specfact/projects// -โ”œโ”€โ”€ bundle.manifest.yaml # Bundle metadata, versioning, checksums, feature index -โ”œโ”€โ”€ product.yaml # Product definition (required) -โ”œโ”€โ”€ idea.yaml # Product vision (if provided) -โ”œโ”€โ”€ business.yaml # Business context (if provided) -โ””โ”€โ”€ features/ # Individual feature files - โ”œโ”€โ”€ FEATURE-001.yaml - โ”œโ”€โ”€ FEATURE-002.yaml - โ””โ”€โ”€ ... - -# Analysis report (bundle-specific, gitignored, Phase 8.5) -.specfact/projects//reports/brownfield/analysis-.md -``` - -**Example (brownfield modernization)**: - -```bash -# Analyze legacy codebase -specfact code import legacy-api --repo . --confidence 0.7 - -# Creates: -# - .specfact/projects/legacy-api/bundle.manifest.yaml (versioned) -# - .specfact/projects/legacy-api/product.yaml (versioned) -# - .specfact/projects/legacy-api/features/FEATURE-*.yaml (versioned, one per feature) -# - .specfact/reports/brownfield/analysis-2025-10-31T14-30-00.md (gitignored) -``` - -### `specfact plan init` (Alternative) - -**Alternative use case**: Create new project bundles for greenfield projects. - -```bash -# Command syntax -specfact plan init [OPTIONS] - -# Creates modular bundle at: -.specfact/projects// -โ”œโ”€โ”€ bundle.manifest.yaml # Bundle metadata and versioning -โ”œโ”€โ”€ product.yaml # Product definition (required) -โ”œโ”€โ”€ idea.yaml # Product vision (if provided via prompts) -โ””โ”€โ”€ features/ # Empty features directory (created when first feature added) - -# Also creates (if --interactive): -.specfact/config.yaml -``` - -### `specfact plan compare` - -```bash -# Compare two bundles (explicit paths to bundle directories) -specfact plan compare \ - --manual .specfact/projects/manual-plan \ - --auto .specfact/projects/auto-derived \ - --out .specfact/reports/comparison/report-*.md - -# Note: Commands accept bundle directory paths, not individual files -``` - -### `specfact sync bridge` - -```bash -# Sync with external tools (Spec-Kit, Linear, Jira, etc.) -specfact sync bridge --adapter speckit --bundle --repo . --bidirectional - -# Watch mode -specfact sync bridge --adapter speckit --bundle --repo . --bidirectional --watch --interval 5 - -# Sync files are tracked in .specfact/reports/sync/ -``` - -### `specfact sync repository` - -```bash -# Sync code changes -specfact sync repository --repo . --target .specfact - -# Watch mode -specfact sync repository --repo . --watch --interval 5 - -# Sync reports in .specfact/reports/sync/ -``` - -### `specfact enforce stage` - -```bash -# Reads/writes -.specfact/gates/config.yaml -``` - -### `specfact init` - -Bootstraps local module lifecycle state (without IDE template copy side effects): - -```bash -# Bootstrap and discover modules -specfact init - -# Canonical lifecycle commands -specfact module list -specfact module install specfact/backlog -specfact module uninstall backlog -``` - -### `specfact init ide` - -Initializes IDE integration by copying prompt templates to IDE-specific locations: - -```bash -# Auto-detect IDE -specfact init ide - -# Specify IDE explicitly -specfact init ide --ide cursor -specfact init ide --ide vscode -specfact init ide --ide copilot -``` - -**Creates/updates IDE-specific directories:** - -- **Cursor**: `.cursor/commands/` (markdown files) -- **VS Code / Copilot**: `.github/prompts/` (`.prompt.md` files) + `.vscode/settings.json` -- **Claude Code**: `.claude/commands/` (markdown files) -- **Gemini**: `.gemini/commands/` (TOML files) -- **Qwen**: `.qwen/commands/` (TOML files) -- **Other IDEs**: See [IDE Integration Guide](../guides/ide-integration.md) - -**See [IDE Integration Guide](../guides/ide-integration.md)** for complete setup instructions. - -**See real examples**: [Integration Showcases](../examples/integration-showcases/) - 5 complete examples showing bugs fixed via IDE integrations - -## Configuration File - -`.specfact/config.yaml` (optional): - -```yaml -version: "1.0" - -# Default bundle to use (optional) -default_bundle: my-project - -# Analysis settings -analysis: - confidence_threshold: 0.7 - exclude_patterns: - - "**/__pycache__/**" - - "**/node_modules/**" - - "**/venv/**" - -# Enforcement settings -enforcement: - preset: balanced # strict, balanced, minimal, shadow - budget_seconds: 120 - fail_fast: false - -# Repro settings -repro: - parallel: true - timeout: 300 -``` - -## IDE Integration Directories - -When you run `specfact init`, prompt templates are copied to IDE-specific locations for slash command integration. - -### IDE-Specific Locations - -| IDE | Directory | Format | Settings File | -|-----|-----------|--------|---------------| -| **Cursor** | `.cursor/commands/` | Markdown | None | -| **VS Code / Copilot** | `.github/prompts/` | `.prompt.md` | `.vscode/settings.json` | -| **Claude Code** | `.claude/commands/` | Markdown | None | -| **Gemini** | `.gemini/commands/` | TOML | None | -| **Qwen** | `.qwen/commands/` | TOML | None | -| **opencode** | `.opencode/command/` | Markdown | None | -| **Windsurf** | `.windsurf/workflows/` | Markdown | None | -| **Kilo Code** | `.kilocode/workflows/` | Markdown | None | -| **Auggie** | `.augment/commands/` | Markdown | None | -| **Roo Code** | `.roo/commands/` | Markdown | None | -| **CodeBuddy** | `.codebuddy/commands/` | Markdown | None | -| **Amp** | `.agents/commands/` | Markdown | None | -| **Amazon Q** | `.amazonq/prompts/` | Markdown | None | - -### Example Structure (Cursor) - -```bash -.cursor/ -โ””โ”€โ”€ commands/ - โ”œโ”€โ”€ specfact.01-import.md - โ”œโ”€โ”€ specfact.02-plan.md - โ”œโ”€โ”€ specfact.03-review.md - โ”œโ”€โ”€ specfact.04-sdd.md - โ”œโ”€โ”€ specfact.05-enforce.md - โ”œโ”€โ”€ specfact.06-sync.md - โ”œโ”€โ”€ specfact.compare.md - โ””โ”€โ”€ specfact.validate.md -``` - -### Example Structure (VS Code / Copilot) - -```bash -.github/ -โ””โ”€โ”€ prompts/ - โ”œโ”€โ”€ specfact.01-import.prompt.md - โ”œโ”€โ”€ specfact.02-plan.prompt.md - โ”œโ”€โ”€ specfact.03-review.prompt.md - โ”œโ”€โ”€ specfact.04-sdd.prompt.md - โ”œโ”€โ”€ specfact.05-enforce.prompt.md - โ”œโ”€โ”€ specfact.06-sync.prompt.md - โ”œโ”€โ”€ specfact.compare.prompt.md - โ””โ”€โ”€ specfact.validate.prompt.md -.vscode/ -โ””โ”€โ”€ settings.json # Updated with promptFilesRecommendations -``` - -**Guidelines:** - -- **Versioned** - IDE directories are typically committed to git (team-shared configuration) -- **Templates** - Prompt templates are read-only for the IDE, not modified by users -- **Settings** - VS Code `settings.json` is merged (not overwritten) to preserve existing settings -- **Auto-discovery** - IDEs automatically discover and register templates as slash commands -- **CLI-first** - Works offline, no account required, no vendor lock-in - -**See [IDE Integration Guide](../guides/ide-integration.md)** for detailed setup and usage. - -**See real examples**: [Integration Showcases](../examples/integration-showcases/) - 5 complete examples showing bugs fixed via IDE integrations - ---- - -## SpecFact CLI Package Structure - -The SpecFact CLI package includes prompt templates that are copied to IDE locations: - -```bash -specfact-cli/ -โ””โ”€โ”€ resources/ - โ””โ”€โ”€ prompts/ # Prompt templates (in package) - โ”œโ”€โ”€ specfact.01-import.md - โ”œโ”€โ”€ specfact.02-plan.md - โ”œโ”€โ”€ specfact.03-review.md - โ”œโ”€โ”€ specfact.04-sdd.md - โ”œโ”€โ”€ specfact.05-enforce.md - โ”œโ”€โ”€ specfact.06-sync.md - โ”œโ”€โ”€ specfact.compare.md - โ”œโ”€โ”€ specfact.validate.md - โ””โ”€โ”€ shared/ - โ””โ”€โ”€ cli-enforcement.md -``` - -**These templates are:** - -- Packaged with SpecFact CLI -- Copied to IDE locations by `specfact init` -- Not modified by users (read-only templates) - ---- - -## `.gitignore` Recommendations - -Add to `.gitignore`: - -```gitignore -# SpecFact ephemeral artifacts -.specfact/projects/*/reports/ -.specfact/projects/*/logs/ -.specfact/cache/ - -# Keep these versioned -!.specfact/projects/ -!.specfact/config.yaml -!.specfact/gates/config.yaml - -# IDE integration directories (optional - typically versioned) -# Uncomment if you don't want to commit IDE integration files -# .cursor/commands/ -# .github/prompts/ -# .vscode/settings.json -# .claude/commands/ -# .gemini/commands/ -# .qwen/commands/ -``` - -**Note**: IDE integration directories are typically **versioned** (committed to git) so team members share the same slash commands. However, you can gitignore them if preferred. - -## Migration from Old Structure - -If you have existing artifacts in other locations: - -```bash -# Old structure (monolithic bundles, deprecated) -.specfact/plans/.bundle. -.specfact/reports/analysis.md - -# New structure (modular bundles) -.specfact/projects/my-project/ -โ”œโ”€โ”€ bundle.manifest.yaml -โ””โ”€โ”€ bundle.yaml -.specfact/reports/brownfield/analysis.md - -# Migration -mkdir -p .specfact/projects/my-project .specfact/reports/brownfield -# Convert monolithic bundle to modular bundle structure -# (Use 'specfact plan upgrade' or manual conversion) -mv reports/analysis.md .specfact/reports/brownfield/ -``` - -## Multiple Plans in One Repository - -SpecFact supports multiple project bundles for: - -- **Brownfield modernization** โญ **PRIMARY**: Separate plans for legacy components vs modernized code -- **Monorepos**: One plan per service -- **Feature branches**: Feature-specific plans - -**Example (Brownfield Modernization)**: - -```bash -.specfact/projects/ -โ”œโ”€โ”€ my-project/ # Overall project bundle -โ”‚ โ”œโ”€โ”€ bundle.manifest.yaml -โ”‚ โ”œโ”€โ”€ product.yaml -โ”‚ โ””โ”€โ”€ features/ -โ”‚ โ””โ”€โ”€ ... -โ”œโ”€โ”€ legacy-api/ # โญ Reverse-engineered from existing API (brownfield) -โ”‚ โ”œโ”€โ”€ bundle.manifest.yaml -โ”‚ โ”œโ”€โ”€ product.yaml -โ”‚ โ””โ”€โ”€ features/ -โ”‚ โ”œโ”€โ”€ FEATURE-AUTH.yaml -โ”‚ โ””โ”€โ”€ FEATURE-API.yaml -โ”œโ”€โ”€ legacy-payment/ # โญ Reverse-engineered from existing payment system (brownfield) -โ”‚ โ”œโ”€โ”€ bundle.manifest.yaml -โ”‚ โ”œโ”€โ”€ product.yaml -โ”‚ โ””โ”€โ”€ features/ -โ”‚ โ””โ”€โ”€ FEATURE-PAYMENT.yaml -โ”œโ”€โ”€ modernized-api/ # New API bundle (after modernization) -โ”‚ โ”œโ”€โ”€ bundle.manifest.yaml -โ”‚ โ”œโ”€โ”€ product.yaml -โ”‚ โ””โ”€โ”€ features/ -โ”‚ โ””โ”€โ”€ ... -โ””โ”€โ”€ feature-new-auth/ # Experimental feature bundle - โ”œโ”€โ”€ bundle.manifest.yaml - โ”œโ”€โ”€ product.yaml - โ””โ”€โ”€ features/ - โ””โ”€โ”€ FEATURE-AUTH.yaml -``` - -**Usage (Brownfield Workflow)**: - -```bash -# Step 1: Reverse-engineer legacy codebase -specfact code import legacy-api \ - --repo src/legacy-api \ - --confidence 0.7 - -# Step 2: Compare legacy vs modernized (use bundle directories, not files) -specfact plan compare \ - --manual .specfact/projects/legacy-api \ - --auto .specfact/projects/modernized-api - -# Step 3: Analyze specific legacy component -specfact code import legacy-payment \ - --repo src/legacy-payment \ - --confidence 0.7 -``` - -## Summary - -### SpecFact Artifacts - -- **`.specfact/`** - All SpecFact artifacts live here -- **`projects/` and `protocols/`** - Versioned (git) -- **`reports/`, `gates/results/`, `cache/`** - Gitignored (ephemeral) -- **Modular bundles** - Each bundle in its own directory with manifest and content files -- **Use descriptive bundle names** - Supports multiple bundles per repo -- **Default paths always start with `.specfact/`** - Consistent and predictable -- **Timestamped reports** - Auto-generated reports include timestamps for tracking -- **Bridge architecture** - Bidirectional sync with external tools (Spec-Kit, Linear, Jira, etc.) via bridge adapters - -### IDE Integration - -- **IDE directories** - Created by `specfact init` (e.g., `.cursor/commands/`, `.github/prompts/`) -- **Prompt templates** - Copied from `resources/prompts/` in SpecFact CLI package -- **Typically versioned** - IDE directories are usually committed to git for team sharing -- **Auto-discovery** - IDEs automatically discover and register templates as slash commands -- **Settings files** - VS Code `settings.json` is merged (not overwritten) - -### Quick Reference - -| Type | Location | Git Status | Purpose | -|------|----------|------------|---------| -| **Project Bundles** | `.specfact/projects//` | Versioned | Modular contract definitions | -| **Bundle Prompts** | `.specfact/projects//prompts/` | Versioned (optional) | AI IDE contract enhancement prompts | -| **Protocols** | `.specfact/protocols/` | Versioned | FSM definitions | -| **Reports** | `.specfact/reports/` | Gitignored | Analysis reports | -| **Cache** | `.specfact/cache/` | Gitignored | Tool caches | -| **IDE Templates** | `.cursor/commands/`, `.github/prompts/`, etc. | Versioned (recommended) | Slash command templates | +This page needs a full rewrite around the mounted command groups before task-level workflow examples can be published again. diff --git a/docs/reference/feature-keys.md b/docs/reference/feature-keys.md index 01b3489..ee01927 100644 --- a/docs/reference/feature-keys.md +++ b/docs/reference/feature-keys.md @@ -1,250 +1,15 @@ -# Feature Key Normalization +# Legacy Workflow Note -Reference documentation for feature key formats and normalization in SpecFact CLI. +This page referenced command groups or workflow steps that are no longer part of the current public mounted CLI in this repository. The old examples were removed to avoid directing readers to unavailable commands. -## Overview +Use the current mounted entrypoints instead: -SpecFact CLI supports multiple feature key formats to accommodate different use cases and historical plans. The normalization system ensures consistent comparison and merging across different formats. +- `specfact project --help` +- `specfact project sync --help` +- `specfact code --help` +- `specfact code review --help` +- `specfact spec --help` +- `specfact govern --help` +- `specfact backlog --help` -## Supported Key Formats - -### 1. Classname Format (Default) - -**Format**: `FEATURE-CLASSNAME` - -**Example**: `FEATURE-CONTRACTFIRSTTESTMANAGER` - -**Use case**: Auto-derived plans from brownfield analysis - -**Generation**: - -```bash -specfact code import --key-format classname -``` - -### 2. Sequential Format - -**Format**: `FEATURE-001`, `FEATURE-002`, `FEATURE-003`, ... - -**Example**: `FEATURE-001` - -**Use case**: Manual plans and greenfield development - -**Generation**: - -```bash -specfact code import --key-format sequential -``` - -**Manual creation**: When creating plans interactively, use `FEATURE-001` format: - -```bash -specfact plan init -# Enter feature key: FEATURE-001 -``` - -### 3. Underscore Format (Legacy) - -**Format**: `000_FEATURE_NAME` or `001_FEATURE_NAME` - -**Example**: `000_CONTRACT_FIRST_TEST_MANAGER` - -**Use case**: Legacy plans or plans imported from other systems - -**Note**: This format is supported for comparison but not generated by the analyzer. - -## Normalization - -The normalization system automatically handles different formats when comparing plans: - -### How It Works - -1. **Normalize keys**: Remove prefixes (`FEATURE-`, `000_`) and underscores -2. **Compare**: Match features by normalized key -3. **Display**: Show original keys in reports - -### Example - -```python -from specfact_cli.utils.feature_keys import normalize_feature_key - -# These all normalize to the same key: -normalize_feature_key("000_CONTRACT_FIRST_TEST_MANAGER") -# โ†’ "CONTRACTFIRSTTESTMANAGER" - -normalize_feature_key("FEATURE-CONTRACTFIRSTTESTMANAGER") -# โ†’ "CONTRACTFIRSTTESTMANAGER" - -normalize_feature_key("FEATURE-001") -# โ†’ "001" -``` - -## Automatic Normalization - -### Plan Comparison - -The `plan compare` command automatically normalizes keys: - -```bash -specfact plan compare --manual main.bundle.yaml --auto auto-derived.yaml -``` - -**Behavior**: Features with different key formats but the same normalized key are matched correctly. - -### Plan Merging - -When merging plans (e.g., via `sync bridge --adapter speckit`), normalization ensures features are matched correctly: - -```bash -specfact sync bridge --adapter speckit --bundle --bidirectional -``` - -**Behavior**: Features are matched by normalized key, not exact key format. - -## Converting Key Formats - -### Using Python Utilities - -```python -from specfact_cli.utils.feature_keys import ( - convert_feature_keys, - to_sequential_key, - to_classname_key, -) - -# Convert to sequential format -features_seq = convert_feature_keys(features, target_format="sequential", start_index=1) - -# Convert to classname format -features_class = convert_feature_keys(features, target_format="classname") -``` - -### Command-Line (Future) - -A `plan normalize` command may be added in the future to convert existing plans: - -```bash -# (Future) Convert plan to sequential format -specfact plan normalize --from main.bundle.yaml --to main-sequential.yaml --output-format sequential -``` - -## Best Practices - -### 1. Choose a Consistent Format - -**Recommendation**: Use **sequential format** (`FEATURE-001`) for new plans: - -- โœ… Easy to reference in documentation -- โœ… Clear ordering -- โœ… Standard format for greenfield plans - -**Auto-derived plans**: Use **classname format** (`FEATURE-CLASSNAME`): - -- โœ… Directly maps to codebase classes -- โœ… Self-documenting -- โœ… Easy to trace back to source code - -### 2. Don't Worry About Format Differences - -**Key insight**: The normalization system handles format differences automatically: - -- โœ… Comparison works across formats -- โœ… Merging works across formats -- โœ… Reports show original keys - -**Action**: Choose the format that fits your workflow; the system handles the rest. - -### 3. Use Sequential for Manual Plans - -When creating plans manually or interactively: - -```bash -specfact plan init -# Enter feature key: FEATURE-001 # โ† Use sequential format -# Enter feature title: User Authentication -``` - -**Why**: Sequential format is easier to reference and understand in documentation. - -### 4. Let Analyzer Use Classname Format - -When analyzing existing codebases: - -```bash -specfact code import --key-format classname # โ† Default, explicit for clarity -``` - -**Why**: Classname format directly maps to codebase structure, making it easy to trace features back to classes. - -## Migration Guide - -### Converting Existing Plans - -If you have a plan with `000_FEATURE_NAME` format and want to convert: - -1. **Load the plan**: - - ```python - from specfact_cli.utils import load_yaml - from specfact_cli.utils.feature_keys import convert_feature_keys - - plan_data = load_yaml("main.bundle.yaml") - features = plan_data["features"] - ``` - -2. **Convert to sequential**: - - ```python - converted = convert_feature_keys(features, target_format="sequential", start_index=1) - plan_data["features"] = converted - ``` - -3. **Save the plan**: - - ```python - from specfact_cli.utils import dump_yaml - - dump_yaml(plan_data, "main-sequential.yaml") - ``` - -### Recommended Migration - -**For existing plans**: Keep the current format; normalization handles comparison automatically. - -**For new plans**: Use sequential format (`FEATURE-001`) for consistency. - -## Troubleshooting - -### Feature Not Matching Between Plans - -**Issue**: Features appear as "missing" even though they exist in both plans. - -**Solution**: Check if keys normalize to the same value: - -```python -from specfact_cli.utils.feature_keys import normalize_feature_key - -key1 = "000_CONTRACT_FIRST_TEST_MANAGER" -key2 = "FEATURE-CONTRACTFIRSTTESTMANAGER" - -print(normalize_feature_key(key1)) # Should match -print(normalize_feature_key(key2)) # Should match -``` - -### Key Format Not Recognized - -**Issue**: Key format doesn't match expected patterns. - -**Solution**: The normalization system is flexible and handles variations: - -- `FEATURE-XXX` โ†’ normalized -- `000_XXX` โ†’ normalized -- `XXX` โ†’ normalized (no prefix) - -**Note**: If normalization fails, check the key manually for special characters or unusual formats. - -## See Also - -- [Brownfield Analysis](../guides/use-cases.md#use-case-2-brownfield-code-hardening) - Explains why different formats exist -- [Plan Comparison](../reference/commands.md#plan-compare) - How comparison works with normalization -- [Plan Sync](../reference/commands.md#sync) - How sync handles different formats +For exact syntax, verify against live help in the current release before copying examples. diff --git a/docs/reference/modes.md b/docs/reference/modes.md index 36a1528..62d4742 100644 --- a/docs/reference/modes.md +++ b/docs/reference/modes.md @@ -36,16 +36,16 @@ This reference shows how to test mode detection and command routing in practice. ```bash # Test CI/CD mode explicitly -hatch run specfact --mode cicd hello +hatch run specfact --mode cicd module list # Test CoPilot mode explicitly -hatch run specfact --mode copilot hello +hatch run specfact --mode copilot module list # Test invalid mode (should fail) -hatch run specfact --mode invalid hello +hatch run specfact --mode invalid module list -# Test short form -m flag -hatch run specfact -m cicd hello +# Test repeated invocation with explicit flag +hatch run specfact --mode cicd module list ``` ### Quick Test Script @@ -67,15 +67,15 @@ This script tests all detection scenarios automatically. ```bash # Set environment variable and test export SPECFACT_MODE=copilot -specfact hello +specfact module list # Set to CI/CD mode export SPECFACT_MODE=cicd -specfact hello +specfact module list # Unset to test default unset SPECFACT_MODE -specfact hello # Should default to CI/CD +specfact module list # Should default to CI/CD ``` ### 3. Test Auto-Detection @@ -85,15 +85,15 @@ specfact hello # Should default to CI/CD ```bash # Simulate CoPilot API available export COPILOT_API_URL=https://api.copilot.com -specfact hello # Should detect CoPilot mode +specfact module list # Should detect CoPilot mode # Or with token export COPILOT_API_TOKEN=token123 -specfact hello # Should detect CoPilot mode +specfact module list # Should detect CoPilot mode # Or with GitHub Copilot token export GITHUB_COPILOT_TOKEN=token123 -specfact hello # Should detect CoPilot mode +specfact module list # Should detect CoPilot mode ``` #### Test IDE Detection @@ -102,17 +102,17 @@ specfact hello # Should detect CoPilot mode # Simulate VS Code environment export VSCODE_PID=12345 export COPILOT_ENABLED=true -specfact hello # Should detect CoPilot mode +specfact module list # Should detect CoPilot mode # Simulate Cursor environment export CURSOR_PID=12345 export CURSOR_COPILOT_ENABLED=true -specfact hello # Should detect CoPilot mode +specfact module list # Should detect CoPilot mode # Simulate VS Code via TERM_PROGRAM export TERM_PROGRAM=vscode export VSCODE_COPILOT_ENABLED=true -specfact hello # Should detect CoPilot mode +specfact module list # Should detect CoPilot mode ``` ### 4. Test Priority Order @@ -120,11 +120,11 @@ specfact hello # Should detect CoPilot mode ```bash # Test that explicit flag overrides environment export SPECFACT_MODE=copilot -specfact --mode cicd hello # Should use CI/CD mode (flag wins) +specfact --mode cicd module list # Should use CI/CD mode (flag wins) # Test that explicit flag overrides auto-detection export COPILOT_API_URL=https://api.copilot.com -specfact --mode cicd hello # Should use CI/CD mode (flag wins) +specfact --mode cicd module list # Should use CI/CD mode (flag wins) ``` ### 5. Test Default Behavior @@ -137,7 +137,7 @@ unset COPILOT_API_TOKEN unset GITHUB_COPILOT_TOKEN unset VSCODE_PID unset CURSOR_PID -specfact hello # Should default to CI/CD mode +specfact module list # Should default to CI/CD mode ``` ## Python Interactive Testing @@ -169,11 +169,11 @@ hatch run python test_mode_practical.py ### Test with Actual Commands -The `import from-code` command now uses mode-aware routing. You should see mode information in the output (but execution is the same for now): +The `code import` command now uses mode-aware routing. You should see mode information in the output (but execution is the same for now): ```bash # Test with CI/CD mode (bundle name as positional argument) -hatch run specfact --mode cicd import from-code test-project --repo . --confidence 0.5 --shadow-only +hatch run specfact --mode cicd code import --repo . --shadow-only test-project # Expected output: # Mode: CI/CD (direct execution) @@ -183,7 +183,7 @@ hatch run specfact --mode cicd import from-code test-project --repo . --confiden ```bash # Test with CoPilot mode (bundle name as positional argument) -hatch run specfact --mode copilot import from-code test-project --repo . --confidence 0.5 --shadow-only +hatch run specfact --mode copilot code import --repo . --shadow-only test-project # Expected output: # Mode: CoPilot (agent routing) @@ -200,7 +200,7 @@ You can also test the routing logic directly in Python: hatch run python -c " from specfact_cli.modes import OperationalMode, get_router router = get_router() -result = router.route('import from-code', OperationalMode.CICD, {}) +result = router.route('code import', OperationalMode.CICD, {}) print(f'Mode: {result.mode}') print(f'Execution mode: {result.execution_mode}') " @@ -209,7 +209,7 @@ print(f'Execution mode: {result.execution_mode}') hatch run python -c " from specfact_cli.modes import OperationalMode, get_router router = get_router() -result = router.route('import from-code', OperationalMode.COPILOT, {}) +result = router.route('code import', OperationalMode.COPILOT, {}) print(f'Mode: {result.mode}') print(f'Execution mode: {result.execution_mode}') " @@ -222,8 +222,8 @@ print(f'Execution mode: {result.execution_mode}') ```bash # In GitHub Actions or CI/CD # No environment variables set -# Should auto-detect CI/CD mode (bundle name as positional argument) -hatch run specfact code import my-project --repo . --confidence 0.7 +# Should auto-detect CI/CD mode +hatch run specfact code import --repo . my-project # Expected: Mode: CI/CD (direct execution) ``` @@ -233,8 +233,8 @@ hatch run specfact code import my-project --repo . --confidence 0.7 ```bash # Developer running in VS Code/Cursor with CoPilot enabled # IDE environment variables automatically set -# Should auto-detect CoPilot mode (bundle name as positional argument) -hatch run specfact code import my-project --repo . --confidence 0.7 +# Should auto-detect CoPilot mode +hatch run specfact code import --repo . my-project # Expected: Mode: CoPilot (agent routing) ``` @@ -242,8 +242,8 @@ hatch run specfact code import my-project --repo . --confidence 0.7 ### Scenario 3: Force Mode Override ```bash -# Developer wants CI/CD mode even though CoPilot is available (bundle name as positional argument) -hatch run specfact --mode cicd import from-code my-project --repo . --confidence 0.7 +# Developer wants CI/CD mode even though CoPilot is available +hatch run specfact --mode cicd code import --repo . my-project # Expected: Mode: CI/CD (direct execution) - flag overrides auto-detection ``` @@ -260,31 +260,31 @@ echo "=== Testing Mode Detection ===" echo echo "1. Testing explicit CI/CD mode:" -specfact --mode cicd hello +specfact --mode cicd module list echo echo "2. Testing explicit CoPilot mode:" -specfact --mode copilot hello +specfact --mode copilot module list echo echo "3. Testing invalid mode (should fail):" -specfact --mode invalid hello 2>&1 || echo "โœ“ Failed as expected" +specfact --mode invalid module list 2>&1 || echo "โœ“ Failed as expected" echo echo "4. Testing SPECFACT_MODE environment variable:" export SPECFACT_MODE=copilot -specfact hello +specfact module list unset SPECFACT_MODE echo echo "5. Testing CoPilot API detection:" export COPILOT_API_URL=https://api.copilot.com -specfact hello +specfact module list unset COPILOT_API_URL echo echo "6. Testing default (no overrides):" -specfact hello +specfact module list echo echo "=== All Tests Complete ===" diff --git a/docs/reference/module-categories.md b/docs/reference/module-categories.md index 0854b3d..a1868c9 100644 --- a/docs/reference/module-categories.md +++ b/docs/reference/module-categories.md @@ -19,20 +19,17 @@ Core commands remain top-level: Category command groups: - `specfact project ...` -- `specfact plan ...` -- `specfact sync ...` - `specfact backlog ...` - `specfact code ...` -- `specfact analyze ...` -- `specfact drift ...` -- `specfact validate ...` -- `specfact repro ...` +- `specfact project sync ...` +- `specfact code analyze ...` +- `specfact code drift ...` +- `specfact code validate ...` +- `specfact code repro ...` - `specfact spec ...` -- `specfact contract ...` -- `specfact sdd ...` -- `specfact generate ...` -- `specfact enforce ...` -- `specfact review` +- `specfact govern ...` +- `specfact govern enforce ...` +- `specfact code review ...` ## Canonical Category Assignments @@ -43,30 +40,27 @@ Category command groups: | `module_registry` | `core` | โ€” | โ€” | `module` | | `upgrade` | `core` | โ€” | โ€” | `upgrade` | | `project` | `project` | `specfact-project` | `project` | `project` | -| `plan` | `project` | `specfact-project` | `project` | `plan` | | `import_cmd` | `project` | `specfact-project` | `project` | `import` | | `sync` | `project` | `specfact-project` | `project` | `sync` | -| `migrate` | `project` | `specfact-project` | `project` | `migrate` | | `backlog` | `backlog` | `specfact-backlog` | `backlog` | `backlog` | | `policy_engine` | `backlog` | `specfact-backlog` | `backlog` | `policy` | | `analyze` | `codebase` | `specfact-codebase` | `code` | `analyze` | | `drift` | `codebase` | `specfact-codebase` | `code` | `drift` | | `validate` | `codebase` | `specfact-codebase` | `code` | `validate` | | `repro` | `codebase` | `specfact-codebase` | `code` | `repro` | -| `contract` | `spec` | `specfact-spec` | `spec` | `contract` | -| `spec` | `spec` | `specfact-spec` | `spec` | `api` | -| `sdd` | `spec` | `specfact-spec` | `spec` | `sdd` | -| `generate` | `spec` | `specfact-spec` | `spec` | `generate` | +| `spec` | `spec` | `specfact-spec` | `spec` | `spec` | | `enforce` | `govern` | `specfact-govern` | `govern` | `enforce` | | `patch_mode` | `govern` | `specfact-govern` | `govern` | `patch` | +| `review` | `code-review` | `specfact-code-review` | `code` | `review` | ## Bundle Contents by Category -- `specfact-project`: `project`, `plan`, `import`, `sync`, `migrate` +- `specfact-project`: `project`, `sync` - `specfact-backlog`: `backlog`, `policy` -- `specfact-codebase`: `analyze`, `drift`, `validate`, `repro` -- `specfact-spec`: `contract`, `api`, `sdd`, `generate` +- `specfact-codebase`: `code import`, `code analyze`, `code drift`, `code validate`, `code repro` +- `specfact-spec`: `spec` - `specfact-govern`: `enforce`, `patch` +- `specfact-code-review`: `code review` ## Bundle Package Layout and Namespaces @@ -85,7 +79,7 @@ Namespace mapping: Compatibility note: -- Commands from each bundle are available at the top level (e.g., `specfact repro`, `specfact enforce`, `specfact plan`). +- In the current CLI release, bundle commands are mounted under the root groups shown by `specfact --help` (for example `specfact code repro` and `specfact govern enforce`). ## First-Run Profiles @@ -109,4 +103,4 @@ specfact init --install all Command surface: - Core top-level commands (`init`, `auth`, `module`, `upgrade`). -- Workflow commands available at the top level (e.g., `specfact plan`, `specfact repro`, `specfact enforce`). +- Workflow commands available through mounted groups (for example `specfact project sync`, `specfact code repro`, `specfact govern enforce`). diff --git a/docs/reference/parameter-standard.md b/docs/reference/parameter-standard.md index 67720e9..951c313 100644 --- a/docs/reference/parameter-standard.md +++ b/docs/reference/parameter-standard.md @@ -1,246 +1,26 @@ -# Parameter Standard +# Legacy Workflow Note -**Date**: 2025-11-26 -**Status**: Active -**Purpose**: Standardize parameter names and grouping across all SpecFact CLI commands +This page described older `specfact plan`, `specfact generate`, `specfact contract`, or `specfact sdd constitution` workflows that are not part of the current public mounted CLI in this repository. The detailed command examples previously documented here were removed because they no longer match the command surface exposed by `specfact --help`. ---- +Use the current mounted entrypoints instead: -## ๐Ÿ“‹ Overview +- `specfact project --help` +- `specfact project sync --help` +- `specfact code --help` +- `specfact code review --help` +- `specfact spec --help` +- `specfact govern --help` +- `specfact backlog --help` +- `specfact module --help` -This document defines the standard parameter names, groupings, and conventions for all SpecFact CLI commands. All commands must follow these standards for consistency and improved user experience. +When you need exact syntax, verify against live help in the current release, for example: ---- - -## ๐ŸŽฏ Parameter Naming Conventions - -### Standard Parameter Names - -| Concept | Standard Name | Deprecated Names | Notes | -|---------|--------------|------------------|-------| -| Repository path | `--repo` | `--base-path` | Use `--repo` for repository root path | -| Output file path | `--out` | `--output` | Use `--out` for output file paths | -| Output format | `--output-format` | `--format` | Use `--output-format` for format specification | -| Interactive mode | `--interactive/--no-interactive` | `--non-interactive` | Use `--interactive/--no-interactive` for mode control | -| Project bundle | `--bundle` | `--name`, `--plan` (when used for bundle name) | Use `--bundle` for project bundle name | -| Project bundle path | `--plan` | N/A | Use `--plan` for project bundle file/directory path | -| SDD manifest path | `--sdd` | N/A | Use `--sdd` for SDD manifest file path | - -### Deprecation Policy - -- **Transition Period**: 3 months from implementation date -- **Deprecation Warnings**: Commands using deprecated names will show warnings -- **Removal**: Deprecated names will be removed after transition period -- **Documentation**: All examples and docs updated immediately - ---- - -## ๐Ÿ“Š Parameter Grouping - -Parameters must be organized into logical groups in the following order: - -### Group 1: Target/Input (Required) - -**Purpose**: What to operate on - -**Parameters**: - -- `--bundle NAME` - Project bundle name (required for modular structure) -- `--repo PATH` - Repository path (default: ".") -- `--plan PATH` - Project bundle path (default: active plan for bundle) -- `--sdd PATH` - SDD manifest path (default: bundle-specific .specfact/projects//sdd.yaml, Phase 8.5, with fallback to legacy .specfact/sdd/.yaml) -- `--constitution PATH` - Constitution path (default: .specify/memory/constitution.md) - -**Help Text Format**: - -```python -# Target/Input ---bundle NAME # Project bundle name (required) ---repo PATH # Repository path (default: ".") ---plan PATH # Project bundle path (default: active plan for bundle) -``` - -### Group 2: Output/Results - -**Purpose**: Where to write results - -**Parameters**: - -- `--out PATH` - Output file path (default: auto-generated) -- `--report PATH` - Report file path (default: auto-generated) -- `--output-format FMT` - Output format: yaml, json, markdown (default: yaml) - -**Help Text Format**: - -```python -# Output/Results ---out PATH # Output file path (default: auto-generated) ---report PATH # Report file path (default: auto-generated) ---output-format FMT # Output format: yaml, json, markdown (default: yaml) -``` - -### Group 3: Behavior/Options - -**Purpose**: How to operate - -**Parameters**: - -- `--interactive/--no-interactive` - Interactive mode (default: auto-detect) -- `--force` - Overwrite existing files -- `--dry-run` - Preview without writing -- `--verbose` - Verbose output -- `--shadow-only` - Observe without enforcing - -**Help Text Format**: - -```python -# Behavior/Options ---interactive # Interactive mode (default: auto-detect) ---no-interactive # Non-interactive mode (for CI/CD) ---force # Overwrite existing files ---dry-run # Preview without writing ---verbose # Verbose output -``` - -### Group 4: Advanced/Configuration - -**Purpose**: Advanced settings and configuration - -**Parameters**: - -- `--confidence FLOAT` - Confidence threshold: 0.0-1.0 (default: 0.5) -- `--budget SECONDS` - Time budget in seconds (default: 120) -- `--preset PRESET` - Enforcement preset: minimal, balanced, strict (default: balanced) -- `--max-questions INT` - Maximum questions per session (default: 5) - -**Help Text Format**: - -```python -# Advanced/Configuration ---confidence FLOAT # Confidence threshold: 0.0-1.0 (default: 0.5) ---budget SECONDS # Time budget in seconds (default: 120) ---preset PRESET # Enforcement preset: minimal, balanced, strict (default: balanced) +```bash +specfact project sync bridge --help +specfact code repro --help +specfact code validate sidecar --help +specfact spec validate --help +specfact govern enforce --help ``` ---- - -## ๐Ÿ”„ Parameter Changes Required - -### Phase 1.2: Rename Inconsistent Parameters โœ… **COMPLETED** - -The following parameters have been renamed: - -1. **`--base-path` โ†’ `--repo`** โœ… - - **File**: `src/specfact_cli/modules/generate/src/commands.py` - - **Command**: `generate contracts` - - **Status**: Completed - Parameter renamed and all references updated - -2. **`--output` โ†’ `--out`** โœ… - - **File**: `src/specfact_cli/modules/sdd/src/commands.py` - - **Command**: `sdd constitution bootstrap` - - **Status**: Completed - Parameter renamed and all references updated - -3. **`--format` โ†’ `--output-format`** โœ… - - **Files**: - - `src/specfact_cli/modules/plan/src/commands.py` (plan compare command) - - `src/specfact_cli/modules/enforce/src/commands.py` (enforce sdd command) - - **Status**: Completed - Parameters renamed and all references updated - -4. **`--non-interactive` โ†’ `--no-interactive`** โœ… - - **Files**: - - `src/specfact_cli/cli.py` (global flag) - - `src/specfact_cli/modules/plan/src/commands.py` (multiple commands) - - `src/specfact_cli/modules/enforce/src/commands.py` (enforce sdd command) - - `src/specfact_cli/modules/generate/src/commands.py` (generate contracts command) - - **Status**: Completed - Global flag and all command flags updated, interaction logic fixed - -### Phase 1.3: Verify `--bundle` Parameter โœ… **COMPLETED** - -**Commands with `--bundle` Parameter**: - -| Command | Parameter Type | Status | Notes | -|---------|---------------|--------|-------| -| `plan init` | Required Argument | โœ… | `bundle: str = typer.Argument(...)` | -| `plan review` | Required Argument | โœ… | `bundle: str = typer.Argument(...)` | -| `plan promote` | Required Argument | โœ… | `bundle: str = typer.Argument(...)` | -| `plan harden` | Required Argument | โœ… | `bundle: str = typer.Argument(...)` | -| `enforce sdd` | Required Argument | โœ… | `bundle: str = typer.Argument(...)` | -| `import from-code` | Required Argument | โœ… | `bundle: str = typer.Argument(...)` | -| `plan add-feature` | Optional Option | โœ… | `bundle: str \| None = typer.Option(...)` with validation | -| `plan add-story` | Optional Option | โœ… | `bundle: str \| None = typer.Option(...)` with validation | -| `plan update-idea` | Optional Option | โœ… | `bundle: str \| None = typer.Option(...)` with validation | -| `plan update-feature` | Optional Option | โœ… | `bundle: str \| None = typer.Option(...)` with validation | -| `plan update-story` | Optional Option | โœ… | `bundle: str \| None = typer.Option(...)` with validation | -| `plan compare` | Optional Option | โœ… | `bundle: str \| None = typer.Option(...)` - Added for consistency | -| `generate contracts` | Optional Option | โœ… | `bundle: str \| None = typer.Option(...)` - Added, prioritizes bundle over plan/sdd | -| `sync bridge` | Optional Option | โœ… | `bundle: str \| None = typer.Option(...)` - Auto-detects if not provided | - -**Validation Improvements**: - -- โœ… Enhanced `_find_bundle_dir()` function with better error messages -- โœ… Lists available bundles when bundle not found -- โœ… Suggests similar bundle names -- โœ… Provides clear creation instructions -- โœ… All commands with optional `--bundle` have fallback logic to find default bundle -- โœ… Help text updated to indicate when `--bundle` is required vs optional - ---- - -## โœ… Validation Checklist - -Before marking a command as compliant: - -- [ ] All parameters use standard names (no deprecated names) -- [ ] Parameters grouped in correct order (Target โ†’ Output โ†’ Behavior โ†’ Advanced) -- [ ] Help text shows parameter groups with comments -- [ ] Defaults shown explicitly in help text -- [ ] Deprecation warnings added for old names (if applicable) -- [ ] Tests updated to use new parameter names -- [ ] Documentation updated with new parameter names - ---- - -## ๐Ÿ“ Examples - -### Before (Inconsistent) - -```python -@app.command("contracts") -def generate_contracts( - base_path: Path | None = typer.Option(None, "--base-path", help="Base directory"), - non_interactive: bool = typer.Option(False, "--non-interactive", help="Non-interactive mode"), -) -> None: - ... -``` - -### After (Standardized) - -```python -@app.command("contracts") -def generate_contracts( - # Target/Input - repo: Path | None = typer.Option(None, "--repo", help="Repository path (default: current directory)"), - - # Behavior/Options - no_interactive: bool = typer.Option(False, "--no-interactive", help="Non-interactive mode (for CI/CD automation)"), -) -> None: - ... -``` - ---- - -## ๐Ÿ”— Related Documentation - -- **[CLI Reorganization Implementation Plan](../../specfact-cli-internal/docs/internal/implementation/CLI_REORGANIZATION_IMPLEMENTATION_PLAN.md)** - Full reorganization plan -- **[Command Reference](./commands.md)** - Complete command reference -- **[Project Bundle Refactoring Plan](../../specfact-cli-internal/docs/internal/implementation/PROJECT_BUNDLE_REFACTORING_PLAN.md)** - Bundle parameter requirements - ---- - -**Rulesets Applied**: - -- Clean Code Principles (consistent naming, logical grouping) -- Estimation Bias Prevention (evidence-based standards) -- Markdown Rules (proper formatting, comprehensive structure) - -**AI Model**: Claude Sonnet 4.5 (claude-sonnet-4-20250514) +This page needs a full rewrite around the mounted command groups before task-level workflow examples can be published again. diff --git a/docs/reference/specmatic.md b/docs/reference/specmatic.md index c264673..666fb65 100644 --- a/docs/reference/specmatic.md +++ b/docs/reference/specmatic.md @@ -269,7 +269,7 @@ if mock_server.is_running(): ### Import Command Integration -The `import from-code` command automatically validates bundle contracts with Specmatic after import. +The `code import` command automatically validates bundle contracts with Specmatic after import. **Location**: `specfact_cli.commands.import_cmd._validate_bundle_contracts()` diff --git a/docs/reference/telemetry.md b/docs/reference/telemetry.md index 51647a8..f325641 100644 --- a/docs/reference/telemetry.md +++ b/docs/reference/telemetry.md @@ -477,7 +477,7 @@ No. We buffer metrics in-memory and write to disk at the end of each command. Wh Yes. Point `SPECFACT_TELEMETRY_ENDPOINT` to an internal collector. Nothing leaves your network unless you decide to forward it. All data is stored locally in `~/.specfact/telemetry.log` by default. **Can I prove contracts are preventing bugs?** -Absolutely. We surface `violations_detected` from commands like `specfact repro` so you can compare "bugs caught by contracts" vs. "bugs caught by legacy tests" over time, and we aggregate the ratios (anonymously) to showcase SpecFact's brownfield impact publicly. +Absolutely. We surface `violations_detected` from commands like `specfact code repro` so you can compare "bugs caught by contracts" vs. "bugs caught by legacy tests" over time, and we aggregate the ratios (anonymously) to showcase SpecFact's brownfield impact publicly. **What happens if the collector is unavailable?** Telemetry gracefully degrades - events are still written to local storage (`~/.specfact/telemetry.log`), and export failures are logged but don't affect your CLI commands. You can retry exports later by processing the local log file. diff --git a/docs/reference/thorough-codebase-validation.md b/docs/reference/thorough-codebase-validation.md index 91501fe..df8fd1e 100644 --- a/docs/reference/thorough-codebase-validation.md +++ b/docs/reference/thorough-codebase-validation.md @@ -13,28 +13,28 @@ This reference describes how to run thorough in-depth validation in different mo | Mode | When to use | Primary command(s) | |------|-------------|---------------------| -| **Quick check** | Fast local/CI gate (lint, type-check, CrossHair with default budget) | `specfact repro --repo ` | +| **Quick check** | Fast local/CI gate (lint, type-check, CrossHair with default budget) | `specfact code repro --repo ` | | **Thorough (contract-decorated)** | Repo already uses `@icontract` / `@beartype`; run full contract stack | `hatch run contract-test-full` | -| **Sidecar (unmodified code)** | Third-party or legacy repo; no edits to target source | `specfact repro --repo --sidecar --sidecar-bundle ` | -| **Dogfooding** | Validate the specfact-cli repo with the same pipeline | `specfact repro --repo .` + `hatch run contract-test-full` (optional sidecar) | +| **Sidecar (unmodified code)** | Third-party or legacy repo; no edits to target source | `specfact code repro --repo --sidecar --sidecar-bundle ` | +| **Dogfooding** | Validate the specfact-cli repo with the same pipeline | `specfact code repro --repo .` + `hatch run contract-test-full` (optional sidecar) | -## 1. Quick check (`specfact repro`) +## 1. Quick check (`specfact code repro`) Run the standard reproducibility suite (ruff, semgrep if config exists, basedpyright, CrossHair, optional pytest contracts/smoke): ```bash -specfact repro --repo . -specfact repro --repo /path/to/external/repo --verbose +specfact code repro --repo . +specfact code repro --repo /path/to/external/repo --verbose ``` - **Time budget**: Default 120s; use `--budget N` (advanced) to change. - **Deep CrossHair**: To increase per-path timeout for CrossHair (e.g. for critical modules), use `--crosshair-per-path-timeout N` (seconds; N must be positive). Default behavior is unchanged when not set. ```bash -specfact repro --repo . --crosshair-per-path-timeout 60 +specfact code repro --repo . --crosshair-per-path-timeout 60 ``` -Required env: none. Optional: `[tool.crosshair]` in `pyproject.toml` (e.g. from `specfact repro setup`). +Required env: none. Optional: `[tool.crosshair]` in `pyproject.toml` (e.g. from `specfact code repro setup`). ## 2. Thorough validation for contract-decorated codebases @@ -63,7 +63,7 @@ Document this as the recommended thorough path for contract-decorated code; CI c For repositories you cannot or do not want to modify (no contract decorators added): ```bash -specfact repro --repo --sidecar --sidecar-bundle +specfact code repro --repo --sidecar --sidecar-bundle ``` - Main repro checks run first (lint, semgrep, type-check, CrossHair if available). @@ -79,14 +79,14 @@ Maintainers can validate the specfact-cli repository with the same pipeline: 1. **Repro + contract-test-full** (recommended minimum): ```bash - specfact repro --repo . + specfact code repro --repo . hatch run contract-test-full ``` 2. **Optional sidecar** (to cover unannotated code in specfact-cli): ```bash - specfact repro --repo . --sidecar --sidecar-bundle + specfact code repro --repo . --sidecar --sidecar-bundle ``` Use the same commands in a CI job or release checklist so specfact-cli validates itself before release. No repo-specific code is required beyond existing repro and contract-test tooling. @@ -95,10 +95,10 @@ Use the same commands in a CI job or release checklist so specfact-cli validates | Goal | Commands | |------|----------| -| Quick gate | `specfact repro --repo .` | -| Deep CrossHair (repro) | `specfact repro --repo . --crosshair-per-path-timeout 60` | +| Quick gate | `specfact code repro --repo .` | +| Deep CrossHair (repro) | `specfact code repro --repo . --crosshair-per-path-timeout 60` | | Full contract stack | `hatch run contract-test-full` | -| Unmodified repo | `specfact repro --repo --sidecar --sidecar-bundle ` | -| Dogfooding | `specfact repro --repo .` then `hatch run contract-test-full`; optionally add `--sidecar --sidecar-bundle ` to repro | +| Unmodified repo | `specfact code repro --repo --sidecar --sidecar-bundle ` | +| Dogfooding | `specfact code repro --repo .` then `hatch run contract-test-full`; optionally add `--sidecar --sidecar-bundle ` to repro | Required env/config: optional `[tool.crosshair]` in `pyproject.toml`; for sidecar, a valid sidecar bundle and CrossHair installed when sidecar CrossHair is used. diff --git a/openspec/changes/docs-cli-command-alignment/.openspec.yaml b/openspec/changes/docs-cli-command-alignment/.openspec.yaml new file mode 100644 index 0000000..bea0667 --- /dev/null +++ b/openspec/changes/docs-cli-command-alignment/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-03-17 diff --git a/openspec/changes/docs-cli-command-alignment/TDD_EVIDENCE.md b/openspec/changes/docs-cli-command-alignment/TDD_EVIDENCE.md new file mode 100644 index 0000000..aadf0bd --- /dev/null +++ b/openspec/changes/docs-cli-command-alignment/TDD_EVIDENCE.md @@ -0,0 +1,38 @@ +## Audit Evidence + +- Captured mounted root command surface with `hatch run specfact --help` +- Captured mounted subcommand surfaces with: + - `hatch run specfact backlog --help` + - `hatch run specfact code --help` + - `hatch run specfact code validate sidecar --help` + - `hatch run specfact code repro --help` + - `hatch run specfact code review --help` + - `hatch run specfact govern --help` + - `hatch run specfact govern enforce --help` + - `hatch run specfact project --help` + - `hatch run specfact project sync --help` + - `hatch run specfact project sync bridge --help` + - `hatch run specfact spec --help` + - `hatch run specfact module install --help` + - `hatch run specfact module init --help` + - `hatch run specfact module list --help` + - `hatch run specfact module uninstall --help` +- Cross-checked official module ids from `packages/*/module-package.yaml` + +## Verification Evidence + +- Verified explicit mode examples with: + - `hatch run specfact --mode cicd module list` + - `hatch run specfact --mode copilot module list` +- Verified `code import` example syntax with: + - `hatch run specfact code import --repo . --shadow-only my-project` + - Command started successfully and accepted the updated option ordering +- Verified OpenSpec change validity with: + - `openspec validate docs-cli-command-alignment --strict` +- Verified edited-file stale pattern cleanup with: + - `rg -n -- '--write|--dry-run|--budget|specfact hello|import from-code|specfact/(backlog|codebase|project|spec|govern)|backlog-core' ...` +- Verified runnable example cleanup across docs with: + - `rg -n "^specfact (plan|generate|contract|sdd|sync|repro|validate|enforce|analyze|drift|review)\b|^hatch run specfact (plan|generate|contract|sdd|sync|repro|validate|enforce|analyze|drift|review)\b|^uvx specfact-cli@latest (plan|generate|contract|sdd|sync|repro|validate|enforce|analyze|drift|review)\b" docs -g '*.md'` + - Final scan returned no remaining runnable examples using removed top-level command groups +- Replaced legacy workflow pages that could not be mapped to current mounted public commands with explicit legacy notes and current `--help` entrypoints, to keep the docs aligned without inventing unsupported replacements +- Note: `openspec` emitted non-blocking PostHog network errors in the sandboxed environment after successful command completion diff --git a/openspec/changes/docs-cli-command-alignment/design.md b/openspec/changes/docs-cli-command-alignment/design.md new file mode 100644 index 0000000..d3a3e3b --- /dev/null +++ b/openspec/changes/docs-cli-command-alignment/design.md @@ -0,0 +1,28 @@ +## Context + +The current CLI help surface in this workspace exposes the following mounted groups: + +- Core: `init`, `module`, `upgrade` +- Installed bundle roots: `backlog`, `code`, `govern`, `project`, `spec` +- Nested groups used by current docs examples: + - `project sync` + - `code analyze` + - `code drift` + - `code review` + - `code validate` + - `code repro` + - `govern enforce` + +The bundle manifests in this repository publish official package ids under the `nold-ai/...` namespace. + +## Decisions + +- Treat live `hatch run specfact --help` output as the source of truth for mounted command paths. +- Update central reference and installation pages first, because they drive most user navigation and copy-paste behavior. +- Use fully qualified official module ids such as `nold-ai/specfact-backlog` in docs examples to avoid stale namespace assumptions. +- Avoid inventing replacements for command groups that are not currently mounted; instead, remove or stop advertising them from the central docs. + +## Verification + +- Re-run targeted `hatch run specfact ... --help` commands for the paths documented after the edits. +- Re-run `rg` searches for the old command prefixes in the edited files to confirm the stale references were removed there. diff --git a/openspec/changes/docs-cli-command-alignment/proposal.md b/openspec/changes/docs-cli-command-alignment/proposal.md new file mode 100644 index 0000000..774f2ee --- /dev/null +++ b/openspec/changes/docs-cli-command-alignment/proposal.md @@ -0,0 +1,24 @@ +## Why + +The modules docs still describe pre-reorganization command paths and old bundle identifiers in several core reference and installation pages. Readers following those pages hit commands that are no longer mounted in the current CLI or install the wrong module ids. + +## What Changes + +- Audit the current mounted CLI surface against the modules docs using live `specfact --help` output and module manifests. +- Update core reference and getting-started pages to use the current mounted command paths such as `specfact project sync ...`, `specfact code repro ...`, `specfact govern enforce ...`, and `specfact code validate ...`. +- Replace stale example module identifiers like `specfact/backlog` and `backlog-core` with the official `nold-ai/...` package ids shipped from this repository. +- Add a docs requirement that modules docs must reflect the current mounted command surface and official bundle ids. + +## Capabilities + +### New Capabilities +- None + +### Modified Capabilities +- `modules-docs-publishing`: Docs command examples and install guidance must match the current mounted CLI surface and official module ids. + +## Impact + +- Affected docs under `docs/reference/`, `docs/guides/`, and `docs/getting-started/` +- OpenSpec delta under `openspec/changes/docs-cli-command-alignment/specs/modules-docs-publishing/spec.md` +- User-facing impact: readers can follow current commands without falling back to removed shims or obsolete package ids diff --git a/openspec/changes/docs-cli-command-alignment/specs/modules-docs-publishing/spec.md b/openspec/changes/docs-cli-command-alignment/specs/modules-docs-publishing/spec.md new file mode 100644 index 0000000..831bdda --- /dev/null +++ b/openspec/changes/docs-cli-command-alignment/specs/modules-docs-publishing/spec.md @@ -0,0 +1,12 @@ +## MODIFIED Requirements + +### Requirement: Modules docs site is the canonical home for official bundle documentation + +The modules documentation site SHALL present itself as the canonical published home for official bundle and module-specific deep documentation, and its command examples SHALL match the currently mounted CLI surface shipped with the official modules. + +#### Scenario: Reader follows a command example from the modules docs + +- **WHEN** a reader copies a command example from the modules docs reference or installation pages +- **THEN** the example uses a command path that is currently mounted in `specfact --help` +- **AND** the example does not rely on removed top-level shims such as flat `sync`, `repro`, `validate`, or `enforce` command groups when the mounted path is nested under another group +- **AND** official bundle install examples use the current published module ids from `specfact-cli-modules` diff --git a/openspec/changes/docs-cli-command-alignment/tasks.md b/openspec/changes/docs-cli-command-alignment/tasks.md new file mode 100644 index 0000000..0b388ee --- /dev/null +++ b/openspec/changes/docs-cli-command-alignment/tasks.md @@ -0,0 +1,17 @@ +## 1. Audit + +- [x] 1.1 Capture the current mounted command surface from `hatch run specfact --help` and relevant subcommand help +- [x] 1.2 Compare central reference and install docs against the mounted command surface and module manifests + +## 2. Docs Updates + +- [x] 2.1 Update command-reference pages to use current mounted command groups +- [x] 2.2 Update installation and module-management guides to use official `nold-ai/...` package ids +- [x] 2.3 Update getting-started pages that still advertise removed or unmapped command paths +- [x] 2.4 Add an OpenSpec delta requiring docs command examples to match the mounted CLI surface + +## 3. Verification + +- [x] 3.1 Re-run focused `specfact --help` checks for every command family documented in the edited pages +- [x] 3.2 Re-run targeted repo searches for stale command prefixes in the edited pages +- [x] 3.3 Record verification evidence in `TDD_EVIDENCE.md` From 9142d0b7ee81cc98eee32e3225210e01f56c72f8 Mon Sep 17 00:00:00 2001 From: Dominikus Nold Date: Wed, 18 Mar 2026 00:24:30 +0100 Subject: [PATCH 2/2] fix: clean legacy command-chains note --- docs/guides/command-chains.md | 366 ++-------------------------------- 1 file changed, 16 insertions(+), 350 deletions(-) diff --git a/docs/guides/command-chains.md b/docs/guides/command-chains.md index 536734a..1f1055a 100644 --- a/docs/guides/command-chains.md +++ b/docs/guides/command-chains.md @@ -6,361 +6,27 @@ permalink: /guides/command-chains/ # Legacy Workflow Note -This page described older SpecFact CLI - v0.42.1 - -โฑ๏ธ Started: 2026-03-18 00:18:23 -Command 'plan' is not installed. -Install workflow bundles with specfact init --profile or specfact -module install . - -โœ“ Finished: 2026-03-18 00:18:23 | Duration: 0.03s, SpecFact CLI - v0.42.1 - -โฑ๏ธ Started: 2026-03-18 00:18:33 -Command 'generate' is not installed. -Install workflow bundles with specfact init --profile or specfact -module install . - -โœ“ Finished: 2026-03-18 00:18:33 | Duration: 0.03s, SpecFact CLI - v0.42.1 - -โฑ๏ธ Started: 2026-03-18 00:18:44 -Command 'contract' is not installed. -Install workflow bundles with specfact init --profile or specfact -module install . - -โœ“ Finished: 2026-03-18 00:18:44 | Duration: 0.03s, or SpecFact CLI - v0.42.1 - -โฑ๏ธ Started: 2026-03-18 00:18:55 -Command 'sdd' is not installed. -Install workflow bundles with specfact init --profile or specfact -module install . - -โœ“ Finished: 2026-03-18 00:18:55 | Duration: 0.02s workflows that are not part of the current public mounted CLI in this repository. The detailed command examples previously documented here were removed because they no longer match the command surface exposed by - Usage: specfact [OPTIONS] COMMAND [ARGS]... - - SpecFact CLI - Spec โ†’ Contract โ†’ Sentinel for Contract-Driven Development - -โ•ญโ”€ Options โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ -โ”‚ --version -v Show version and โ”‚ -โ”‚ exit โ”‚ -โ”‚ --banner Show ASCII art โ”‚ -โ”‚ banner (hidden โ”‚ -โ”‚ by default, โ”‚ -โ”‚ shown on first โ”‚ -โ”‚ run) โ”‚ -โ”‚ --mode TEXT Operational โ”‚ -โ”‚ mode: cicd โ”‚ -โ”‚ (fast, โ”‚ -โ”‚ deterministic) โ”‚ -โ”‚ or copilot โ”‚ -โ”‚ (enhanced, โ”‚ -โ”‚ interactive) โ”‚ -โ”‚ --debug Enable debug โ”‚ -โ”‚ output: console โ”‚ -โ”‚ diagnostics and โ”‚ -โ”‚ log file at โ”‚ -โ”‚ ~/.specfact/logโ€ฆ โ”‚ -โ”‚ (operation โ”‚ -โ”‚ metadata for โ”‚ -โ”‚ file I/O and API โ”‚ -โ”‚ calls) โ”‚ -โ”‚ --skip-checks Skip startup โ”‚ -โ”‚ checks (template โ”‚ -โ”‚ validation and โ”‚ -โ”‚ version check) - โ”‚ -โ”‚ useful for CI/CD โ”‚ -โ”‚ --input-format [yaml|json] Default โ”‚ -โ”‚ structured input โ”‚ -โ”‚ format (yaml or โ”‚ -โ”‚ json) โ”‚ -โ”‚ [default: yaml] โ”‚ -โ”‚ --output-format [yaml|json] Default โ”‚ -โ”‚ structured โ”‚ -โ”‚ output format โ”‚ -โ”‚ for generated โ”‚ -โ”‚ files (yaml or โ”‚ -โ”‚ json) โ”‚ -โ”‚ [default: yaml] โ”‚ -โ”‚ --interactive --no-interactive Force โ”‚ -โ”‚ interaction mode โ”‚ -โ”‚ (default auto โ”‚ -โ”‚ based on โ”‚ -โ”‚ terminal/CI โ”‚ -โ”‚ detection) โ”‚ -โ”‚ --install-compleโ€ฆ Install โ”‚ -โ”‚ completion for โ”‚ -โ”‚ the current โ”‚ -โ”‚ shell. โ”‚ -โ”‚ --show-completion Show completion โ”‚ -โ”‚ for the current โ”‚ -โ”‚ shell, to copy โ”‚ -โ”‚ it or customize โ”‚ -โ”‚ the โ”‚ -โ”‚ installation. โ”‚ -โ”‚ --help,--help-adโ€ฆ -h,-ha Show this โ”‚ -โ”‚ message and โ”‚ -โ”‚ exit. โ”‚ -โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ -โ•ญโ”€ Commands โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ -โ”‚ init Bootstrap SpecFact and manage module lifecycle (use `init ide` for โ”‚ -โ”‚ IDE setup) โ”‚ -โ”‚ module Manage marketplace modules (install, uninstall, search, list, โ”‚ -โ”‚ show, upgrade) โ”‚ -โ”‚ upgrade Check for and install SpecFact CLI updates โ”‚ -โ”‚ backlog Module package: nold-ai/specfact-backlog โ”‚ -โ”‚ code Module package: nold-ai/specfact-codebase โ”‚ -โ”‚ govern Module package: nold-ai/specfact-govern โ”‚ -โ”‚ project Module package: nold-ai/specfact-project โ”‚ -โ”‚ spec Module package: nold-ai/specfact-spec โ”‚ -โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ. +This page described older `specfact plan`, `specfact generate`, `specfact contract`, or `specfact sdd constitution` workflows that are not part of the current public mounted CLI in this repository. The detailed command examples previously documented here were removed because they no longer match the command surface exposed by `specfact --help`. Use the current mounted entrypoints instead: -- -โฑ๏ธ Started: 2026-03-18 00:19:19 - - Usage: specfact project [OPTIONS] COMMAND [ARGS]... - - Manage project bundles with persona workflows - -โ•ญโ”€ Options โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ -โ”‚ --install-completion Install completion for the current โ”‚ -โ”‚ shell. โ”‚ -โ”‚ --show-completion Show completion for the current shell, โ”‚ -โ”‚ to copy it or customize the โ”‚ -โ”‚ installation. โ”‚ -โ”‚ --help-advanced,--help -ha,-h Show this message and exit. โ”‚ -โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ -โ•ญโ”€ Commands โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ -โ”‚ link-backlog Link a project bundle to a backlog provider โ”‚ -โ”‚ configuration. โ”‚ -โ”‚ health-check Run project-level health checks including backlog graph โ”‚ -โ”‚ health. โ”‚ -โ”‚ devops-flow Run integrated DevOps stage actions for a project bundle. โ”‚ -โ”‚ snapshot Save current linked backlog graph as baseline snapshot. โ”‚ -โ”‚ regenerate Re-derive plan state from current bundle and linked โ”‚ -โ”‚ backlog graph. โ”‚ -โ”‚ export-roadmap Export roadmap milestones from backlog dependency โ”‚ -โ”‚ critical path. โ”‚ -โ”‚ export Export persona-owned sections from project bundle to โ”‚ -โ”‚ Markdown. โ”‚ -โ”‚ import Import persona-edited Markdown file back into project โ”‚ -โ”‚ bundle. โ”‚ -โ”‚ lock Lock a section for a persona. โ”‚ -โ”‚ unlock Unlock a section. โ”‚ -โ”‚ locks List all section locks. โ”‚ -โ”‚ init-personas Initialize personas in project bundle manifest. โ”‚ -โ”‚ merge Merge project bundles using three-way merge with โ”‚ -โ”‚ persona-aware conflict resolution. โ”‚ -โ”‚ resolve-conflict Resolve a specific conflict in a project bundle. โ”‚ -โ”‚ version Manage project bundle versions โ”‚ -โ”‚ sync Synchronize external tool artifacts and repository โ”‚ -โ”‚ changes (Spec-Kit, OpenSpec, GitHub, Linear, Jira, etc.). โ”‚ -โ”‚ See 'specfact backlog refine' for template-driven backlog โ”‚ -โ”‚ refinement. โ”‚ -โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ - - - -โœ“ Finished: 2026-03-18 00:19:19 | Duration: 0.39s -- -โฑ๏ธ Started: 2026-03-18 00:19:30 - - Usage: specfact project sync [OPTIONS] COMMAND [ARGS]... - - Synchronize external tool artifacts and repository changes (Spec-Kit, - OpenSpec, GitHub, Linear, Jira, etc.). See 'specfact backlog refine' for - template-driven backlog refinement. - -โ•ญโ”€ Options โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ -โ”‚ --help,--help-advanced -h,-ha Show this message and exit. โ”‚ -โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ -โ•ญโ”€ Commands โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ -โ”‚ bridge Sync changes between external tool artifacts and SpecFact โ”‚ -โ”‚ using bridge architecture. โ”‚ -โ”‚ repository Sync code changes to SpecFact artifacts. โ”‚ -โ”‚ intelligent Continuous intelligent bidirectional sync with conflict โ”‚ -โ”‚ resolution. โ”‚ -โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ - - -โœ“ Finished: 2026-03-18 00:19:31 | Duration: 0.31s -- -โฑ๏ธ Started: 2026-03-18 00:19:43 - - Usage: specfact code [OPTIONS] COMMAND [ARGS]... - - Code command extensions for structured review workflows. - -โ•ญโ”€ Options โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ -โ”‚ --install-completion Install completion for the current โ”‚ -โ”‚ shell. โ”‚ -โ”‚ --show-completion Show completion for the current shell, โ”‚ -โ”‚ to copy it or customize the โ”‚ -โ”‚ installation. โ”‚ -โ”‚ --help-advanced,--help -h,-ha Show this message and exit. โ”‚ -โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ -โ•ญโ”€ Commands โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ -โ”‚ review Governed code review workflows. โ”‚ -โ”‚ import Import codebases and related external inputs into SpecFact โ”‚ -โ”‚ project bundles. โ”‚ -โ”‚ analyze Analyze codebase for contract coverage and quality โ”‚ -โ”‚ drift Detect drift between code and specifications โ”‚ -โ”‚ validate Validation commands โ”‚ -โ”‚ repro Run validation suite for reproducibility โ”‚ -โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ - - - -โœ“ Finished: 2026-03-18 00:19:45 | Duration: 1.16s -- -โฑ๏ธ Started: 2026-03-18 00:19:55 - - Usage: specfact code review [OPTIONS] COMMAND [ARGS]... - - Governed code review workflows. - -โ•ญโ”€ Options โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ -โ”‚ --help-advanced,--help -h,-ha Show this message and exit. โ”‚ -โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ -โ•ญโ”€ Commands โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ -โ”‚ run Execute code review runs. โ”‚ -โ”‚ ledger Persist and inspect review reward history. โ”‚ -โ”‚ rules Manage the code-review house-rules skill. โ”‚ -โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ - - -โœ“ Finished: 2026-03-18 00:19:56 | Duration: 0.64s -- -โฑ๏ธ Started: 2026-03-18 00:20:05 - - Usage: specfact spec [OPTIONS] COMMAND [ARGS]... - - Specmatic integration for API contract testing (OpenAPI/AsyncAPI validation, - backward compatibility, mock servers) - -โ•ญโ”€ Options โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ -โ”‚ --install-completion Install completion for the current โ”‚ -โ”‚ shell. โ”‚ -โ”‚ --show-completion Show completion for the current shell, โ”‚ -โ”‚ to copy it or customize the โ”‚ -โ”‚ installation. โ”‚ -โ”‚ --help-advanced,--help -h,-ha Show this message and exit. โ”‚ -โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ -โ•ญโ”€ Commands โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ -โ”‚ validate Validate OpenAPI/AsyncAPI specification using Specmatic. โ”‚ -โ”‚ backward-compat Check backward compatibility between two spec versions. โ”‚ -โ”‚ generate-tests Generate Specmatic test suite from specification. โ”‚ -โ”‚ mock Launch Specmatic mock server from specification. โ”‚ -โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ - - - -โœ“ Finished: 2026-03-18 00:20:06 | Duration: 0.35s -- -โฑ๏ธ Started: 2026-03-18 00:20:16 - - Usage: specfact govern [OPTIONS] COMMAND [ARGS]... - - Governance and quality gates: enforce, patch. - -โ•ญโ”€ Options โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ -โ”‚ --install-completion Install completion for the current โ”‚ -โ”‚ shell. โ”‚ -โ”‚ --show-completion Show completion for the current shell, โ”‚ -โ”‚ to copy it or customize the โ”‚ -โ”‚ installation. โ”‚ -โ”‚ --help,--help-advanced -h,-ha Show this message and exit. โ”‚ -โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ -โ•ญโ”€ Commands โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ -โ”‚ enforce Configure quality gates and enforcement modes โ”‚ -โ”‚ patch Preview and apply patches (local or upstream with --write). โ”‚ -โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ - - - -โœ“ Finished: 2026-03-18 00:20:17 | Duration: 0.55s -- -โฑ๏ธ Started: 2026-03-18 00:20:29 - - Usage: specfact backlog [OPTIONS] COMMAND [ARGS]... - - Backlog refinement and template management - -โ•ญโ”€ Options โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ -โ”‚ --install-completion Install completion for the current โ”‚ -โ”‚ shell. โ”‚ -โ”‚ --show-completion Show completion for the current shell, โ”‚ -โ”‚ to copy it or customize the โ”‚ -โ”‚ installation. โ”‚ -โ”‚ --help,--help-advanced -ha,-h Show this message and exit. โ”‚ -โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ -โ•ญโ”€ Commands โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ -โ”‚ ceremony Ceremony-oriented backlog workflows โ”‚ -โ”‚ delta Backlog delta analysis and impact tracking โ”‚ -โ”‚ auth Authenticate backlog providers โ”‚ -โ”‚ sync Sync current backlog graph with stored baseline and โ”‚ -โ”‚ export delta outputs. โ”‚ -โ”‚ verify-readiness Verify release readiness for selected backlog items. โ”‚ -โ”‚ analyze-deps Analyze backlog dependencies for a project. โ”‚ -โ”‚ diff Show changes since baseline sync. โ”‚ -โ”‚ promote Validate promotion impact for an item and print promotion โ”‚ -โ”‚ intent. โ”‚ -โ”‚ refine Refine backlog items using AI-assisted template matching. โ”‚ -โ”‚ daily Show daily standup view: list my/filtered backlog items โ”‚ -โ”‚ with status and last activity. โ”‚ -โ”‚ init-config Scaffold `.specfact/backlog-config.yaml` with default โ”‚ -โ”‚ backlog provider config structure. โ”‚ -โ”‚ map-fields Interactive command to map ADO fields to canonical field โ”‚ -โ”‚ names. โ”‚ -โ”‚ add Create a backlog item with optional parent hierarchy โ”‚ -โ”‚ validation and DoR checks. โ”‚ -โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ - - - -โœ“ Finished: 2026-03-18 00:20:30 | Duration: 1.56s -- -โฑ๏ธ Started: 2026-03-18 00:20:42 - - Usage: specfact module [OPTIONS] COMMAND [ARGS]... - - Manage marketplace modules - -โ•ญโ”€ Options โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ -โ”‚ --install-completion Install completion for the current โ”‚ -โ”‚ shell. โ”‚ -โ”‚ --show-completion Show completion for the current shell, โ”‚ -โ”‚ to copy it or customize the โ”‚ -โ”‚ installation. โ”‚ -โ”‚ --help,--help-advanced -h,-ha Show this message and exit. โ”‚ -โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ -โ•ญโ”€ Commands โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ -โ”‚ init Bootstrap shipped module artifacts into user or project โ”‚ -โ”‚ module root. โ”‚ -โ”‚ install Install a module from bundled artifacts or marketplace โ”‚ -โ”‚ registry. โ”‚ -โ”‚ uninstall Uninstall a marketplace module. โ”‚ -โ”‚ add-registry Add a custom registry to the config. โ”‚ -โ”‚ list-registries List all configured registries (official + custom). โ”‚ -โ”‚ remove-registry Remove a custom registry from the config. โ”‚ -โ”‚ enable Enable modules in lifecycle state registry. โ”‚ -โ”‚ disable Disable modules in lifecycle state registry. โ”‚ -โ”‚ search Search marketplace and installed modules by โ”‚ -โ”‚ id/description/tags. โ”‚ -โ”‚ list List installed modules with trust labels and optional โ”‚ -โ”‚ origin details. โ”‚ -โ”‚ show Show detailed metadata for an installed module. โ”‚ -โ”‚ upgrade Upgrade marketplace module(s) to latest available โ”‚ -โ”‚ versions. โ”‚ -โ”‚ alias Manage command aliases (map name to namespaced module) โ”‚ -โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ - - - -โœ“ Finished: 2026-03-18 00:20:42 | Duration: 0.47s +- `specfact project --help` +- `specfact project sync --help` +- `specfact code --help` +- `specfact code review --help` +- `specfact spec --help` +- `specfact govern --help` +- `specfact backlog --help` +- `specfact module --help` When you need exact syntax, verify against live help in the current release, for example: - +```bash +specfact project sync bridge --help +specfact code repro --help +specfact code validate sidecar --help +specfact spec validate --help +specfact govern enforce --help +``` This page needs a full rewrite around the mounted command groups before task-level workflow examples can be published again.