From ccf2a32e5415296b9a33b48fe9912c863afc8113 Mon Sep 17 00:00:00 2001 From: Dominikus Nold Date: Wed, 18 Mar 2026 00:45:11 +0100 Subject: [PATCH 1/2] docs: fix command syntax parity after lean-core/modules split (v0.42.2) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace all stale CLI syntax families in authored docs with current shipped commands. Adds docs parity tests that guard against regression. Removed syntax families corrected: - specfact project plan → project devops-flow / project snapshot / govern enforce sdd - project import from-bridge → code import from-bridge - specfact backlog policy → backlog verify-readiness / backlog refine - specfact spec contract → spec validate / spec generate-tests / spec mock - specfact spec sdd constitution → govern enforce sdd [BUNDLE] - spec generate → AI IDE skills or removed Updated docs: README.md, docs/index.md, docs/README.md, docs/reference/commands.md (+4 reference docs), docs/getting-started/ (4 files), docs/guides/ (21 files), docs/examples/ (5 files), docs/prompts/ (2 files). Added 11 new docs parity tests in test_release_docs_parity.py: - 7 tests asserting removed syntax families stay absent - 4 tests asserting current command families remain documented Co-Authored-By: Claude Sonnet 4.6 --- CHANGELOG.md | 9 ++ README.md | 22 +-- docs/README.md | 16 +-- docs/examples/brownfield-data-pipeline.md | 4 +- .../brownfield-django-modernization.md | 19 ++- docs/examples/brownfield-flask-api.md | 4 +- docs/examples/dogfooding-specfact-cli.md | 40 ++---- docs/examples/quick-examples.md | 102 +++++--------- docs/getting-started/README.md | 6 +- docs/getting-started/first-steps.md | 71 +++------- docs/getting-started/installation.md | 13 +- .../tutorial-openspec-speckit.md | 21 ++- docs/guides/agile-scrum-workflows.md | 10 +- docs/guides/ai-ide-workflow.md | 44 +++--- docs/guides/brownfield-engineer.md | 7 +- docs/guides/brownfield-journey.md | 16 +-- docs/guides/command-chains.md | 127 ++++++++---------- docs/guides/common-tasks.md | 53 ++++---- docs/guides/competitive-analysis.md | 10 +- docs/guides/contract-testing-workflow.md | 88 ++++++------ docs/guides/devops-adapter-integration.md | 10 +- docs/guides/dual-stack-enrichment.md | 29 ++-- docs/guides/ide-integration.md | 12 +- docs/guides/migration-0.16-to-0.19.md | 23 ++-- docs/guides/migration-cli-reorganization.md | 18 +-- docs/guides/migration-guide.md | 38 +++--- docs/guides/policy-engine-commands.md | 68 ++++------ docs/guides/speckit-comparison.md | 4 +- docs/guides/speckit-journey.md | 26 ++-- docs/guides/specmatic-integration.md | 19 ++- docs/guides/troubleshooting.md | 70 ++++------ docs/guides/use-cases.md | 65 +++------ .../using-module-security-and-extensions.md | 2 +- docs/guides/ux-features.md | 9 +- docs/guides/workflows.md | 24 ++-- docs/index.md | 5 +- docs/prompts/PROMPT_VALIDATION_CHECKLIST.md | 77 +++++------ docs/prompts/README.md | 8 +- docs/reference/README.md | 6 +- docs/reference/command-syntax-policy.md | 15 ++- docs/reference/commands.md | 30 +++-- docs/reference/directory-structure.md | 52 +++---- docs/reference/feature-keys.md | 29 +--- .../TDD_EVIDENCE.md | 52 +++++++ pyproject.toml | 2 +- setup.py | 2 +- src/specfact_cli/__init__.py | 2 +- tests/unit/docs/test_release_docs_parity.py | 116 ++++++++++++++++ 48 files changed, 716 insertions(+), 779 deletions(-) create mode 100644 openspec/changes/docs-03-command-syntax-parity/TDD_EVIDENCE.md diff --git a/CHANGELOG.md b/CHANGELOG.md index c616627f..100ef5cd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,15 @@ All notable changes to this project will be documented in this file. **Important:** Changes need to be documented below this block as this is the header section. Each section should be separated by a horizontal rule. Newer changelog entries need to be added on top of prior ones to keep the history chronological with most recent changes first. +--- + +## [0.42.2] - 2026-03-18 + +### Fixed + +- Corrected all authored docs (`README.md`, `docs/`) to use shipped command surfaces after the lean-core and modules split. Removed or replaced stale syntax families (`project plan`, `project import from-bridge`, `backlog policy`, `spec contract`, `spec sdd`, `spec generate` prompt subcommands) with current equivalents (`code import from-bridge`, `backlog verify-readiness`, `spec validate`, `spec generate-tests`, `govern enforce sdd`). +- Added docs parity tests that fail when removed syntax families reappear in authored docs, guarding against future regression. + --- ## [0.42.1] - 2026-03-17 diff --git a/README.md b/README.md index 7cde3521..67c2feef 100644 --- a/README.md +++ b/README.md @@ -80,9 +80,9 @@ specfact code validate sidecar run my-project /path/to/repo As of `0.40.0`, flat root commands are removed. Use grouped commands: -- `specfact validate ...` -> `specfact code validate ...` -- `specfact plan ...` -> `specfact project plan ...` -- `specfact policy ...` -> `specfact backlog policy ...` +- `specfact validate ...` → `specfact code validate ...` +- `specfact plan ...` → removed; use `specfact project devops-flow` or `specfact project snapshot` +- `specfact policy ...` → removed; use `specfact backlog verify-readiness` ### Backlog Bridge (60 seconds) @@ -100,7 +100,7 @@ specfact backlog daily ado --ado-org --ado-project "" --state any specfact backlog refine ado --ado-org --ado-project "" --id --preview # 3) Keep backlog + spec intent aligned (avoid silent drift) -specfact backlog policy validate --group-by-item +specfact backlog verify-readiness --bundle ``` For GitHub, replace adapter/org/project with: @@ -168,18 +168,18 @@ Most tools help **either** coders **or** agile teams. SpecFact does both: Recommended command entrypoints: - `specfact backlog ceremony standup ...` - `specfact backlog ceremony refinement ...` -- `specfact backlog policy validate ...` -- `specfact backlog policy suggest ...` +- `specfact backlog verify-readiness --bundle ` +- `specfact backlog analyze-deps --bundle ` -What the Policy Engine does in practice: +What the backlog readiness and ceremony commands do in practice: - Turns team agreements (DoR, DoD, flow checks) into executable checks against your real backlog data. - Shows exactly what is missing per item (for example missing acceptance criteria or definition of done). -- Generates patch-ready suggestions so teams can fix policy gaps quickly without guessing. +- Run structured ceremony workflows (standup, refinement, retrospective) directly from the CLI. Start with: -- `specfact backlog policy init --template scrum` -- `specfact backlog policy validate --group-by-item` -- `specfact backlog policy suggest --group-by-item --limit 5` +- `specfact backlog ceremony standup --help` +- `specfact backlog verify-readiness --bundle ` +- `specfact backlog refine --help` **Try it now** diff --git a/docs/README.md b/docs/README.md index 1f593926..8950bdce 100644 --- a/docs/README.md +++ b/docs/README.md @@ -29,18 +29,18 @@ Most tools help **either** coders **or** agile teams. SpecFact does both: Recommended command entrypoints: - `specfact backlog ceremony standup ...` - `specfact backlog ceremony refinement ...` -- `specfact backlog policy validate ...` -- `specfact backlog policy suggest ...` +- `specfact backlog verify-readiness --bundle ` +- `specfact backlog analyze-deps --bundle ` -What the Policy Engine does in practice: +What the backlog ceremony and readiness commands do in practice: - Converts team working agreements (DoR, DoD, flow/PI readiness) into deterministic checks. -- Flags exact policy gaps per backlog item with actionable evidence pointers. -- Produces patch-ready suggestions so teams can remediate quickly. +- Flags exact readiness gaps per backlog item with actionable evidence pointers. +- Runs structured ceremony workflows (standup, refinement) against live backlog data. Start with: -- `specfact backlog policy init --template scrum` -- `specfact backlog policy validate --group-by-item` -- `specfact backlog policy suggest --group-by-item --limit 5` +- `specfact backlog ceremony standup --help` +- `specfact backlog verify-readiness --bundle ` +- `specfact backlog refine --help` **Try it now** diff --git a/docs/examples/brownfield-data-pipeline.md b/docs/examples/brownfield-data-pipeline.md index bc5320e7..d3bdb1f4 100644 --- a/docs/examples/brownfield-data-pipeline.md +++ b/docs/examples/brownfield-data-pipeline.md @@ -81,7 +81,7 @@ After extracting the plan, create a hard SDD manifest: ```bash # Create SDD manifest from the extracted plan -specfact project plan harden customer-etl +specfact govern enforce sdd customer-etl ``` ### Output @@ -131,7 +131,7 @@ Promote your plan to "review" stage (requires valid SDD): ```bash # Promote plan to review stage -specfact project plan promote customer-etl --stage review +specfact project devops-flow --stage review --bundle customer-etl ``` **Why this matters**: Plan promotion enforces SDD presence, ensuring you have a hard spec before starting modernization work. diff --git a/docs/examples/brownfield-django-modernization.md b/docs/examples/brownfield-django-modernization.md index 00c74c21..df6280e4 100644 --- a/docs/examples/brownfield-django-modernization.md +++ b/docs/examples/brownfield-django-modernization.md @@ -85,7 +85,7 @@ After extracting the plan, create a hard SDD (Spec-Driven Development) manifest ```bash # Create SDD manifest from the extracted plan -specfact project plan harden customer-portal +specfact govern enforce sdd customer-portal ``` ### Output @@ -161,7 +161,7 @@ specfact govern enforce sdd customer-portal - 2 medium severity deviations - Fix: Add contracts to stories or adjust thresholds -💡 Run 'specfact project plan harden' to update SDD manifest +💡 Run 'specfact govern enforce sdd ' to enforce SDD ``` --- @@ -172,13 +172,13 @@ Review your plan to identify ambiguities and ensure SDD compliance: ```bash # Review plan (automatically checks SDD, bundle name as positional argument) -specfact project plan review customer-portal --max-questions 5 +specfact project devops-flow --stage develop --bundle customer-portal ``` ### Output ```text -📋 SpecFact CLI - Plan Review +📋 SpecFact CLI - DevOps Flow (develop stage) ✅ Loading project bundle: .specfact/projects/customer-portal/ ✅ Current stage: draft @@ -193,10 +193,9 @@ specfact project plan review customer-portal --max-questions 5 ... ✅ Review complete: 5 questions identified -💡 Run 'specfact project plan review --answers answers.json' to resolve in bulk ``` -**SDD integration**: The review command automatically checks for SDD presence and validates coverage thresholds, warning you if thresholds aren't met. +**SDD integration**: The devops-flow develop stage automatically checks for SDD presence and validates coverage thresholds, warning you if thresholds aren't met. --- @@ -206,13 +205,13 @@ Before starting modernization, promote your plan to "review" stage. This require ```bash # Promote plan to review stage (requires SDD, bundle name as positional argument) -specfact project plan promote customer-portal --stage review +specfact project devops-flow --stage review --bundle customer-portal ``` ### Output (Success) ```text -📋 SpecFact CLI - Plan Promotion +📋 SpecFact CLI - DevOps Flow (review stage) ✅ Loading project bundle: .specfact/projects/customer-portal/ ✅ Current stage: draft @@ -231,7 +230,7 @@ specfact project plan promote customer-portal --stage review ```text ❌ SDD manifest is required for promotion to 'review' or higher stages -💡 Run 'specfact project plan harden' to create SDD manifest +💡 Run 'specfact govern enforce sdd ' to enforce SDD ``` **Why this matters**: Plan promotion now enforces SDD presence, ensuring you have a hard spec before starting modernization work. This prevents drift and ensures coverage thresholds are met. @@ -246,7 +245,7 @@ Review the extracted plan to identify high-risk functions: ```bash # Review extracted plan using CLI commands -specfact project plan review customer-portal +specfact project health-check ``` diff --git a/docs/examples/brownfield-flask-api.md b/docs/examples/brownfield-flask-api.md index adaafaa1..0a61eaac 100644 --- a/docs/examples/brownfield-flask-api.md +++ b/docs/examples/brownfield-flask-api.md @@ -80,7 +80,7 @@ After extracting the plan, create a hard SDD manifest: ```bash # Create SDD manifest from the extracted plan -specfact project plan harden customer-api +specfact govern enforce sdd customer-api ``` ### Output @@ -130,7 +130,7 @@ Promote your plan to "review" stage (requires valid SDD): ```bash # Promote plan to review stage -specfact project plan promote customer-api --stage review +specfact project devops-flow --stage review --bundle customer-api ``` **Why this matters**: Plan promotion enforces SDD presence, ensuring you have a hard spec before starting modernization work. diff --git a/docs/examples/dogfooding-specfact-cli.md b/docs/examples/dogfooding-specfact-cli.md index 8c2ace14..5475c586 100644 --- a/docs/examples/dogfooding-specfact-cli.md +++ b/docs/examples/dogfooding-specfact-cli.md @@ -156,7 +156,7 @@ features: Now comes the magic - compare the manual plan against what's actually implemented: ```bash -specfact project plan compare +specfact project regenerate ``` ### Results @@ -249,7 +249,7 @@ Let's try again with **minimal enforcement** (never blocks): ```bash specfact govern enforce stage --preset minimal -specfact project plan compare +specfact project regenerate ``` ### New Enforcement Report @@ -291,7 +291,8 @@ After validating the brownfield analysis workflow, we took it a step further: ** First, we generated a structured prompt for our AI IDE (Cursor) to enhance the telemetry module: ```bash -specfact spec generate contracts-prompt src/specfact_cli/telemetry.py --bundle specfact-cli-test --apply all-contracts --no-interactive +# Use your AI IDE skill (/specfact.07-contracts) for contract enhancement workflows +/specfact.07-contracts specfact-cli-test --apply all-contracts ``` **Output**: @@ -335,7 +336,7 @@ We copied the prompt to Cursor (our AI IDE), which: The AI IDE ran SpecFact CLI validation on the enhanced code: ```bash -specfact spec generate contracts-apply enhanced_telemetry.py --original src/specfact_cli/telemetry.py +# Use your AI IDE skill (/specfact.07-contracts) for contract enhancement workflows ``` ### Validation Results @@ -439,25 +440,10 @@ This demonstrates **real production use**: ## Complete Contract Enhancement Workflow ```bash -# 1. Generate prompt (1 second) -specfact spec generate contracts-prompt src/specfact_cli/telemetry.py \ - --bundle specfact-cli-test \ - --apply all-contracts \ - --no-interactive -# ✅ Prompt saved to: .specfact/projects/specfact-cli-test/prompts/ - -# 2. AI IDE enhancement (2-3 minutes) -# - Copy prompt to Cursor/CoPilot/etc. -# - AI IDE reads file and adds contracts -# - AI IDE writes to enhanced_telemetry.py - -# 3. Validate and apply (10 seconds) -specfact spec generate contracts-apply enhanced_telemetry.py \ - --original src/specfact_cli/telemetry.py -# ✅ 7-step validation passed -# ✅ All tests passed (10/10) -# ✅ Code quality checks passed -# ✅ Changes applied to original file +# 1. Generate prompt and apply contracts via AI IDE skill (2-3 minutes) +# Use your AI IDE skill (/specfact.07-contracts) for contract enhancement workflows +/specfact.07-contracts specfact-cli-test --apply all-contracts +# ✅ Prompt generated, contracts analyzed, and applied through IDE skill # Total time: ~3 minutes (mostly AI IDE processing) # Total value: Production-ready contract-enhanced code @@ -553,8 +539,8 @@ specfact code import specfact-cli --repo . --confidence 0.5 specfact govern enforce stage --preset balanced # ✅ BLOCK HIGH, WARN MEDIUM, LOG LOW -# 3. Compare plans (5 seconds) - uses active plan or default bundle -specfact project plan compare +# 3. Regenerate/compare plans (5 seconds) - uses active plan or default bundle +specfact project regenerate # ✅ Finds 24 deviations # ❌ BLOCKS execution (2 HIGH violations) @@ -578,7 +564,7 @@ specfact project plan compare **Problem**: "How do I prevent bad code from merging?" -**Solution**: Set enforcement preset → configure CI to run `plan compare` +**Solution**: Set enforcement preset → configure CI to run `project regenerate` **Result**: PRs blocked automatically if they violate contracts @@ -611,7 +597,7 @@ hatch run python -c "import sys; sys.path.insert(0, 'src'); from specfact_cli.cl hatch run python -c "import sys; sys.path.insert(0, 'src'); from specfact_cli.cli import app; app()" enforce stage --preset balanced # Compare plans -hatch run python -c "import sys; sys.path.insert(0, 'src'); from specfact_cli.cli import app; app()" plan compare +hatch run python -c "import sys; sys.path.insert(0, 'src'); from specfact_cli.cli import app; app()" project regenerate ``` ### Learn More diff --git a/docs/examples/quick-examples.md b/docs/examples/quick-examples.md index 093027be..4728db31 100644 --- a/docs/examples/quick-examples.md +++ b/docs/examples/quick-examples.md @@ -30,13 +30,13 @@ pip install specfact-cli ```bash # Starting a new project? -specfact project plan init my-project --interactive +specfact project snapshot --bundle my-project # Have existing code? specfact code import my-project --repo . # Using GitHub Spec-Kit? -specfact project import from-bridge --adapter speckit --repo ./my-project --dry-run +specfact code import from-bridge --adapter speckit --repo ./my-project --dry-run ``` @@ -44,10 +44,10 @@ specfact project import from-bridge --adapter speckit --repo ./my-project --dry- ```bash # Preview migration -specfact project import from-bridge --adapter speckit --repo ./spec-kit-project --dry-run +specfact code import from-bridge --adapter speckit --repo ./spec-kit-project --dry-run # Execute migration -specfact project import from-bridge --adapter speckit --repo ./spec-kit-project --write +specfact code import from-bridge --adapter speckit --repo ./spec-kit-project --write ``` @@ -85,47 +85,25 @@ specfact code import large-project --repo . --confidence 0.5 ## Plan Management ```bash -# Initialize plan (bundle name as positional argument) -specfact project plan init my-project --interactive +# Initialize plan (create a snapshot for a new bundle) +specfact project snapshot --bundle my-project -# Add feature (bundle name via --bundle option) -specfact project plan add-feature \ - --bundle my-project \ - --key FEATURE-001 \ - --title "User Authentication" \ - --outcomes "Users can login securely" - -# Add story (bundle name via --bundle option) -specfact project 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" - -# Create hard SDD manifest (required for promotion) -specfact project plan harden my-project +# Enforce SDD (validates plan and coverage thresholds) +specfact govern enforce sdd my-project -# Review plan (checks SDD automatically, bundle name as positional argument) -specfact project plan review my-project --max-questions 5 +# Review plan (check health and SDD compliance) +specfact project health-check -# Promote plan (requires SDD for review+ stages) -specfact project plan promote my-project --stage review +# Promote plan to review stage +specfact project devops-flow --stage review --bundle my-project ``` ## Plan Comparison ```bash -# Quick comparison (auto-detects plans) -specfact project plan compare --repo . - -# Explicit comparison (bundle directory paths) -specfact project plan compare \ - --manual .specfact/projects/manual-plan \ - --auto .specfact/projects/auto-derived - -# Code vs plan comparison -specfact project plan compare --code-vs-plan --repo . +# Regenerate and compare plans +specfact project regenerate ``` @@ -149,23 +127,17 @@ specfact project sync repository --repo . --watch --interval 5 ## SDD (Spec-Driven Development) Workflow ```bash -# Create hard SDD manifest from plan -specfact project plan harden - # Validate SDD manifest against plan specfact govern enforce sdd # Validate SDD with custom output format specfact govern enforce sdd --output-format json --out validation-report.json -# Review plan (automatically checks SDD) -specfact project plan review --max-questions 5 - -# Promote plan (requires SDD for review+ stages) -specfact project plan promote --stage review +# Review plan health (checks SDD automatically) +specfact project health-check -# Force promotion despite SDD validation failures -specfact project plan promote --stage review --force +# Promote plan to review stage (requires SDD) +specfact project devops-flow --stage review --bundle ``` ## Enforcement @@ -243,14 +215,14 @@ specfact code import my-project --repo . ```bash # Morning: Check status specfact code repro --verbose -specfact project plan compare --repo . +specfact project regenerate # During development: Watch mode specfact project sync repository --repo . --watch --interval 5 # Before committing: Validate specfact code repro -specfact project plan compare --repo . +specfact project regenerate ``` @@ -260,35 +232,32 @@ specfact project plan compare --repo . # Step 1: Extract specs from legacy code specfact code import my-project --repo . -# Step 2: Create hard SDD manifest -specfact project plan harden my-project - -# Step 3: Validate SDD before starting work +# Step 2: Validate SDD and coverage thresholds specfact govern enforce sdd my-project -# Step 4: Review plan (checks SDD automatically) -specfact project plan review my-project --max-questions 5 +# Step 3: Review plan health (checks SDD automatically) +specfact project health-check -# Step 5: Promote plan (requires SDD for review+ stages) -specfact project plan promote my-project --stage review +# Step 4: Promote plan to review stage (requires SDD) +specfact project devops-flow --stage review --bundle my-project -# Step 6: Add contracts to critical paths +# Step 5: Add contracts to critical paths # ... (add @icontract decorators to code) -# Step 7: Re-validate SDD after adding contracts +# Step 6: Re-validate SDD after adding contracts specfact govern enforce sdd my-project -# Step 8: Continue modernization with SDD safety net +# Step 7: Continue modernization with SDD safety net ``` ### Migration from Spec-Kit ```bash # Step 1: Preview -specfact project import from-bridge --adapter speckit --repo . --dry-run +specfact code import from-bridge --adapter speckit --repo . --dry-run # Step 2: Execute -specfact project import from-bridge --adapter speckit --repo . --write +specfact code import from-bridge --adapter speckit --repo . --write # Step 3: Set up sync specfact project sync bridge --adapter speckit --bundle --repo . --bidirectional --watch --interval 5 @@ -304,11 +273,11 @@ specfact govern enforce stage --preset minimal # Step 1: Analyze code specfact code import my-project --repo . --confidence 0.7 -# Step 2: Review plan using CLI commands -specfact project plan review my-project +# Step 2: Review plan health +specfact project health-check -# Step 3: Compare with manual plan -specfact project plan compare --repo . +# Step 3: Regenerate and compare plans +specfact project regenerate # Step 4: Set up watch mode specfact project sync repository --repo . --watch --interval 5 @@ -331,8 +300,7 @@ specfact code import \ --repo . \ --report analysis-report.md -specfact project plan compare \ - --repo . \ +specfact project regenerate \ --out comparison-report.md ``` diff --git a/docs/getting-started/README.md b/docs/getting-started/README.md index 16a48f38..9187bc1a 100644 --- a/docs/getting-started/README.md +++ b/docs/getting-started/README.md @@ -35,7 +35,7 @@ uvx specfact-cli@latest project import from-code my-project --repo . ```bash # CLI-only mode (bundle name as positional argument) -uvx specfact-cli@latest project plan init my-project --interactive +uvx specfact-cli@latest project snapshot --bundle my-project # Interactive AI Assistant mode (recommended for better results) # Requires: pip install specfact-cli && specfact init @@ -48,8 +48,8 @@ uvx specfact-cli@latest project plan init my-project --interactive Flat root commands were removed. Use grouped command forms: - `specfact validate ...` -> `specfact code validate ...` -- `specfact project plan ...` -> `specfact project plan ...` -- `specfact backlog policy ...` -> `specfact backlog policy ...` +- `specfact plan ...` → removed; use `specfact project devops-flow` or `specfact project snapshot` +- `specfact policy ...` → removed; use `specfact backlog verify-readiness` First-run bundle selection examples: diff --git a/docs/getting-started/first-steps.md b/docs/getting-started/first-steps.md index ca06af00..8e38c05e 100644 --- a/docs/getting-started/first-steps.md +++ b/docs/getting-started/first-steps.md @@ -95,10 +95,10 @@ specfact init --profile solo-developer ```bash # Review the extracted bundle using CLI commands -specfact project plan review my-project +specfact project health-check # Or get structured findings for analysis -specfact project plan review my-project --list-findings --findings-format json +specfact project health-check ``` Review the auto-generated plan to understand what SpecFact discovered about your codebase. @@ -108,7 +108,7 @@ Review the auto-generated plan to understand what SpecFact discovered about your **💡 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 spec sdd constitution bootstrap --repo . +# specfact spec sdd constitution commands are removed; use specfact govern enforce sdd [BUNDLE] for SDD enforcement ``` ### Step 3: Find and Fix Gaps @@ -131,16 +131,12 @@ specfact code repro --verbose ### Step 4: Use AI to Fix Gaps (New in 0.17+) ```bash -# Generate AI-ready prompt to fix a specific gap -specfact spec generate fix-prompt GAP-001 --bundle my-project - -# Generate AI-ready prompt to add tests -specfact spec generate test-prompt src/auth/login.py +# Use your AI IDE skill (/specfact.07-contracts) for contract enhancement workflows ``` **What happens**: -- Creates structured prompt file in `.specfact/prompts/` +- Use your AI IDE's `/specfact.07-contracts` skill to generate contract enhancement prompts - Copy prompt to your AI IDE (Cursor, Copilot, Claude) - AI generates the fix - Validate with SpecFact enforcement @@ -165,65 +161,39 @@ See [Brownfield Engineer Guide](../guides/brownfield-engineer.md) for complete w **Time**: 5-10 minutes -### Step 1: Initialize a Plan +### Step 1: Initialize a Project Snapshot ```bash -specfact project plan init my-project --interactive +specfact project snapshot --bundle my-project ``` **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 +📋 Initializing new project snapshot... -✅ Plan initialized successfully! +✅ Snapshot created successfully! 📁 Project bundle: .specfact/projects/my-project/ ``` -### Step 2: Add Your First Feature - -```bash -specfact project 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 +### Step 2: Import Code to Populate the Bundle ```bash -specfact project 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" +specfact code import my-project --repo . ``` **What happens**: -- Adds a user story to the feature -- Defines acceptance criteria -- Links the story to the feature +- Analyzes your codebase and extracts features and stories +- Populates the project bundle at `.specfact/projects/my-project/` -### Step 4: Validate the Plan +### Step 3: Validate the Plan ```bash specfact code repro @@ -260,7 +230,7 @@ specfact code repro ### Step 1: Preview Migration ```bash -specfact project import from-bridge \ +specfact code import from-bridge \ --repo ./my-speckit-project \ --adapter speckit \ --dry-run @@ -295,7 +265,7 @@ specfact project import from-bridge \ ### Step 2: Execute Migration ```bash -specfact project import from-bridge \ +specfact code import from-bridge \ --repo ./my-speckit-project \ --adapter speckit \ --write @@ -313,10 +283,7 @@ specfact project import from-bridge \ ```bash # Review the imported bundle -specfact project plan review - -# Check bundle status -specfact project plan select +specfact project health-check ``` **What was created**: @@ -325,7 +292,7 @@ specfact project plan select - `.specfact/protocols/workflow.protocol.yaml` - FSM definition (if protocol detected) - `.specfact/gates/config.yaml` - Quality gates configuration -**Note**: Use CLI commands (`plan review`, `plan add-feature`, etc.) to interact with bundles. Do not edit `.specfact` files directly. +**Note**: Use CLI commands (`project health-check`, `code import`, etc.) to interact with bundles. Do not edit `.specfact` files directly. ### Step 4: Set Up Bidirectional Sync (Optional) @@ -333,7 +300,7 @@ Keep Spec-Kit and SpecFact synchronized: ```bash # Generate constitution if missing (auto-suggested during sync) -specfact spec sdd constitution bootstrap --repo . +# specfact spec sdd constitution commands are removed; use specfact govern enforce sdd [BUNDLE] for SDD enforcement # One-time bidirectional sync specfact project sync bridge --adapter speckit --bundle --repo . --bidirectional diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index d741b498..6dac2ea6 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -236,7 +236,7 @@ specfact init --install all Start a new contract-driven project: ```bash -specfact project plan init --interactive +specfact project snapshot ``` This will guide you through creating: @@ -280,10 +280,10 @@ Convert an existing GitHub Spec-Kit project: ```bash # Preview what will be migrated -specfact project import from-bridge --adapter speckit --repo ./my-speckit-project --dry-run +specfact code import from-bridge --adapter speckit --repo ./my-speckit-project --dry-run # Execute migration (one-time import) -specfact project import from-bridge \ +specfact code import from-bridge \ --adapter speckit \ --repo ./my-speckit-project \ --write @@ -502,11 +502,8 @@ specfact --version specfact --help specfact --help -# Initialize plan (bundle name as positional argument) -specfact project plan init my-project --interactive - -# Add feature -specfact project plan add-feature --key FEATURE-001 --title "My Feature" +# Initialize project snapshot +specfact project snapshot --bundle my-project # Validate everything specfact code repro diff --git a/docs/getting-started/tutorial-openspec-speckit.md b/docs/getting-started/tutorial-openspec-speckit.md index a38d82a4..7da1895d 100644 --- a/docs/getting-started/tutorial-openspec-speckit.md +++ b/docs/getting-started/tutorial-openspec-speckit.md @@ -351,7 +351,7 @@ ls specs/ ```bash # Preview import -specfact project import from-bridge --adapter speckit --repo ./my-speckit-project --dry-run +specfact code import from-bridge --adapter speckit --repo ./my-speckit-project --dry-run # Expected output: # 🔍 Analyzing Spec-Kit project via bridge adapter... @@ -377,7 +377,7 @@ specfact project import from-bridge --adapter speckit --repo ./my-speckit-projec ```bash # Execute import -specfact project import from-bridge \ +specfact code import from-bridge \ --adapter speckit \ --repo ./my-speckit-project \ --write @@ -401,10 +401,10 @@ specfact project import from-bridge \ **Review what was created:** ```bash -# Review plan bundle (bundle name is positional argument, not --bundle) +# Review project health (check bundle health and SDD compliance) # IMPORTANT: Must be in the project directory where .specfact/ exists cd /path/to/your-speckit-project -specfact project plan review +specfact project health-check # Note: Bundle name is typically "main" for Spec-Kit imports # Check actual bundle name: ls .specfact/projects/ @@ -415,8 +415,8 @@ specfact project plan review # ✅ Plan bundle reviewed successfully ``` -**Note**: -- `plan review` takes the bundle name as a positional argument (not `--bundle`) +**Note**: +- `project health-check` checks the project state and SDD compliance - It uses the current directory to find `.specfact/projects/` (no `--repo` option) - You must be in the project directory where the bundle was created @@ -494,10 +494,10 @@ specfact govern enforce stage --preset balanced **Compare intended design vs actual implementation:** ```bash -# Compare code vs plan (use --bundle to specify bundle name) +# Regenerate and compare plans to detect drift # IMPORTANT: Must be in the project directory where .specfact/ exists cd /path/to/my-speckit-project -specfact project plan compare --code-vs-plan --bundle +specfact project regenerate # Note: Bundle name is typically "main" for Spec-Kit imports # Check actual bundle name: ls .specfact/projects/ @@ -514,9 +514,8 @@ specfact project plan compare --code-vs-plan --bundle - 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) +**Note**: +- `project regenerate` uses the current directory to find bundles - You must be in the project directory where the bundle was created --- diff --git a/docs/guides/agile-scrum-workflows.md b/docs/guides/agile-scrum-workflows.md index 84928c8c..d5def64a 100644 --- a/docs/guides/agile-scrum-workflows.md +++ b/docs/guides/agile-scrum-workflows.md @@ -116,14 +116,14 @@ SpecFact CLI supports real-world agile/scrum practices through: ## Policy Engine Commands (DoR/DoD/Flow/PI) -Use the `policy` command group to run deterministic readiness checks before sprint and refinement ceremonies: +Use the readiness and refinement commands to run deterministic readiness checks before sprint and refinement ceremonies: ```bash -# Validate configured policy rules against a snapshot -specfact backlog policy validate --repo . --format both +# Validate configured readiness rules against a snapshot +specfact backlog verify-readiness --repo . -# Generate confidence-scored, patch-ready suggestions (no automatic writes) -specfact backlog policy suggest --repo . +# Generate AI-assisted refinement suggestions (no automatic writes) +specfact backlog refine --repo . ``` Policy configuration is loaded from `.specfact/policy.yaml` and supports Scrum (`dor_required_fields`, diff --git a/docs/guides/ai-ide-workflow.md b/docs/guides/ai-ide-workflow.md index 2a6328f4..c9012ab7 100644 --- a/docs/guides/ai-ide-workflow.md +++ b/docs/guides/ai-ide-workflow.md @@ -63,18 +63,18 @@ Once initialized, the following slash commands are available in your IDE: | Slash Command | Purpose | Equivalent CLI Command | |---------------|---------|------------------------| | `/specfact.01-import` | Import from codebase | `specfact code import` | -| `/specfact.02-plan` | Plan management | `specfact project plan init/add-feature/add-story` | -| `/specfact.03-review` | Review plan | `specfact project plan review` | +| `/specfact.02-plan` | Plan management | `specfact project snapshot` | +| `/specfact.03-review` | Review plan | `specfact project snapshot` | | `/specfact.04-sdd` | Create SDD manifest | `specfact govern enforce sdd` | | `/specfact.05-enforce` | SDD enforcement | `specfact govern enforce sdd` | | `/specfact.06-sync` | Sync operations | `specfact project sync bridge` | -| `/specfact.07-contracts` | Contract management | `specfact spec generate contracts-prompt` | +| `/specfact.07-contracts` | Contract management | See AI IDE skill `/specfact.07-contracts` | ### Advanced Commands | Slash Command | Purpose | Equivalent CLI Command | |---------------|---------|------------------------| -| `/specfact.compare` | Compare plans | `specfact project plan compare` | +| `/specfact.compare` | Compare plans | `specfact project devops-flow --stage plan --action compare` | | `/specfact.validate` | Validation suite | `specfact code repro` | | `/specfact.backlog-refine` | Backlog refinement (AI IDE interactive loop, provided by the backlog bundle) | `specfact backlog refine github \| ado` | @@ -113,14 +113,8 @@ specfact code repro --verbose #### 2. Generate AI-Ready Prompt ```bash -# Generate fix prompt for a specific gap -specfact spec generate fix-prompt GAP-001 --bundle my-project - -# Or generate contract prompt -specfact spec generate contracts-prompt --bundle my-project --feature FEATURE-001 - -# Or generate test prompt -specfact spec generate test-prompt src/auth/login.py --bundle my-project +# Use your AI IDE skill (/specfact.07-contracts) for contract enhancement workflows +# Use your AI IDE skill (/specfact.07-contracts) for fix and test prompt workflows ``` #### 3. Use AI IDE to Apply Fixes @@ -147,12 +141,12 @@ cat .specfact/prompts/fix-prompt-GAP-001.md #### 4. Validate with SpecFact ```bash -# Check contract coverage -specfact spec contract coverage --bundle my-project - # Run validation specfact code repro --verbose +# Validate spec compliance +specfact spec validate --bundle my-project + # Enforce SDD compliance specfact govern enforce sdd --bundle my-project ``` @@ -169,19 +163,19 @@ The AI IDE workflow integrates with several command chains: ### AI-Assisted Code Enhancement Chain -**Workflow**: `generate contracts-prompt` → [AI IDE] → `contracts-apply` → `contract coverage` → `repro` +**Workflow**: `/specfact.07-contracts` (AI IDE skill) → `spec validate` → `repro` **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` +**Workflow**: `/specfact.07-contracts` (AI IDE skill) → `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**: `repro --verbose` → `generate fix-prompt` → [AI IDE] → `enforce sdd` +**Workflow**: `repro --verbose` → `/specfact.07-contracts` (AI IDE skill) → `enforce sdd` **Related**: [Gap Discovery & Fixing Chain](command-chains.md#9-gap-discovery--fixing-chain-emerging) @@ -198,16 +192,12 @@ specfact code import legacy-api --repo . # 2. Find gaps specfact code repro --verbose -# 3. Generate contract prompt -specfact spec 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 +# 3. Use AI IDE skill for contract enhancement +# Use your AI IDE skill (/specfact.07-contracts) for contract enhancement workflows +# /specfact.07-contracts legacy-api FEATURE-001 -# 5. Validate -specfact spec contract coverage --bundle legacy-api +# 4. Validate +specfact spec validate --bundle legacy-api specfact code repro --verbose specfact govern enforce sdd --bundle legacy-api ``` diff --git a/docs/guides/brownfield-engineer.md b/docs/guides/brownfield-engineer.md index c1dd38d6..0f34bca1 100644 --- a/docs/guides/brownfield-engineer.md +++ b/docs/guides/brownfield-engineer.md @@ -94,12 +94,11 @@ This enables: - **Multi-plan support** - Create separate plan 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: +**💡 Tip**: After importing, the CLI may suggest enforcing SDD compliance for Spec-Kit integration. Run SDD enforcement to validate compliance: ```bash -# If suggested, accept to auto-generate -# Or run manually: -specfact spec sdd constitution bootstrap --repo . +# Enforce SDD compliance for your bundle +specfact govern enforce sdd ``` This is especially useful if you plan to sync with Spec-Kit later. diff --git a/docs/guides/brownfield-journey.md b/docs/guides/brownfield-journey.md index 61a32cad..00c5465d 100644 --- a/docs/guides/brownfield-journey.md +++ b/docs/guides/brownfield-journey.md @@ -56,13 +56,7 @@ specfact code import legacy-api --repo ./legacy-app **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 spec sdd constitution bootstrap --repo . -``` +**💡 Tip**: After importing, the CLI may suggest generating a bootstrap constitution for Spec-Kit integration. This auto-generates a constitution from your repository analysis. Use `specfact govern enforce sdd [BUNDLE]` for SDD enforcement when working with Spec-Kit bundles. This is especially useful if you plan to sync with Spec-Kit later. @@ -70,7 +64,7 @@ This is especially useful if you plan to sync with Spec-Kit later. ```bash # Review the extracted plan using CLI commands -specfact project plan review legacy-api +specfact project snapshot legacy-api ``` **What to look for:** @@ -84,7 +78,9 @@ specfact project plan review legacy-api ```bash # Compare extracted plan to your understanding (bundle directory paths) -specfact project plan compare \ +specfact project devops-flow \ + --stage plan \ + --action compare \ --manual .specfact/projects/manual-plan \ --auto .specfact/projects/your-project ``` @@ -112,7 +108,7 @@ specfact project plan compare \ ```bash # Review plan using CLI commands -specfact project plan review legacy-api +specfact project snapshot legacy-api ``` ### Step 2.2: Add Contracts Incrementally diff --git a/docs/guides/command-chains.md b/docs/guides/command-chains.md index a51a7284..d80328de 100644 --- a/docs/guides/command-chains.md +++ b/docs/guides/command-chains.md @@ -86,10 +86,10 @@ Start: What do you want to accomplish? specfact code import legacy-api --repo . # Step 2: Review the extracted plan -specfact project plan review legacy-api +specfact project snapshot legacy-api # Step 3: Update features based on review findings -specfact project plan update-feature --bundle legacy-api --feature +specfact project devops-flow --stage plan --action update-feature --bundle legacy-api --feature # Step 4: Enforce SDD (Spec-Driven Development) compliance specfact govern enforce sdd --bundle legacy-api @@ -114,8 +114,8 @@ graph TD **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 `import from-code`**: Review the extracted plan. If features are incomplete or incorrect, use `project devops-flow --stage plan --action update-feature` to refine them. +- **After `project snapshot`**: If ambiguities are found, resolve them before proceeding to enforcement. - **After `enforce sdd`**: If compliance fails, update the plan and re-run enforcement. - **After `repro`**: If validation fails, fix issues and re-run the chain from the appropriate step. @@ -144,22 +144,21 @@ graph TD ```bash # Step 1: Initialize a new plan bundle -specfact project plan init new-feature --interactive +specfact project devops-flow --stage plan --action init --bundle new-feature --interactive # Step 2: Add features to the plan -specfact project plan add-feature --bundle new-feature --name "User Authentication" +specfact project devops-flow --stage plan --action add-feature --bundle new-feature --name "User Authentication" # Step 3: Add user stories to features -specfact project plan add-story --bundle new-feature --feature --story "As a user, I want to log in" +specfact project devops-flow --stage plan --action add-story --bundle new-feature --feature --story "As a user, I want to log in" # Step 4: Review the plan for completeness -specfact project plan review new-feature +specfact project snapshot new-feature # Step 5: Harden the plan (finalize before implementation) -specfact project plan harden --bundle new-feature +specfact project devops-flow --stage plan --action harden --bundle new-feature -# Step 6: Generate contracts from the plan -specfact spec generate contracts --bundle new-feature +# Step 6: Use your AI IDE skill (/specfact.07-contracts) for contract enhancement workflows # Step 7: Enforce SDD compliance specfact govern enforce sdd --bundle new-feature @@ -181,10 +180,10 @@ graph TD **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. +- **After `devops-flow plan init`**: Choose interactive mode to get guided prompts, or use flags for automation. +- **After `devops-flow plan add-feature`**: Add multiple features before adding stories, or add stories immediately. +- **After `project snapshot`**: If ambiguities are found, add more details or stories before hardening. +- **After `devops-flow plan harden`**: Once hardened, the plan is locked. Use the AI IDE skill for contract enhancement before enforcement. **Expected Outcomes**: @@ -210,10 +209,10 @@ graph TD ```bash # For Code/Spec Adapters (Spec-Kit, OpenSpec, generic-markdown): # Step 1: Import from external tool via bridge adapter -specfact project import from-bridge --repo . --adapter speckit --write +specfact code import from-bridge --repo . --adapter speckit --write # Step 2: Review the imported plan -specfact project plan review +specfact project snapshot # Step 3: Set up bidirectional sync (optional) specfact project sync bridge --adapter speckit --bundle --bidirectional --watch @@ -245,7 +244,7 @@ graph LR **Decision Points**: -- **After `import from-bridge`**: Review the imported plan. If it needs refinement, use `plan update-feature`. +- **After `import from-bridge`**: Review the imported plan. If it needs refinement, use `project devops-flow --stage plan --action update-feature`. - **Bidirectional sync**: Use `--watch` mode for continuous synchronization, or run sync manually as needed. - **Adapter selection**: - **Code/Spec adapters** (use `import from-bridge`): `speckit`, `openspec`, `generic-markdown` @@ -288,8 +287,8 @@ 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 spec contract verify --bundle api-bundle +# Step 5: Validate contracts at runtime +specfact spec validate --bundle api-bundle ``` **Workflow Diagram**: @@ -393,13 +392,13 @@ graph TD ```bash # Step 1: Review the plan before promotion -specfact project plan review +specfact project snapshot # Step 2: Enforce SDD compliance specfact govern enforce sdd --bundle # Step 3: Promote the plan to next stage -specfact project plan promote --bundle --stage +specfact project devops-flow --stage release --action promote --bundle --stage # Step 4: Bump version when releasing specfact project version bump --bundle --type @@ -417,7 +416,7 @@ graph LR **Decision Points**: -- **After `plan review`**: If issues are found, fix them before promotion. +- **After `project snapshot`**: If issues are found, fix them before promotion. - **SDD enforcement**: Ensure compliance before promoting to production stages. - **Version bumping**: Choose appropriate version type (major/minor/patch) based on changes. @@ -447,7 +446,7 @@ graph LR specfact code import current-state --repo . # Step 2: Compare code against plan -specfact project plan compare --bundle --code-vs-plan +specfact project devops-flow --stage plan --action compare --bundle --code-vs-plan # Step 3: Detect drift specfact code drift detect --bundle @@ -470,7 +469,7 @@ graph TD **Decision Points**: -- **After `plan compare`**: Review the comparison results to understand differences. +- **After `devops-flow compare`**: Review the comparison results to understand differences. - **Drift detection**: If drift is detected, decide whether to sync code-to-plan or plan-to-code. - **Sync direction**: Choose `code-to-plan` to update plan from code, or `plan-to-code` to update code from plan. @@ -496,16 +495,13 @@ graph TD **Command Sequence**: ```bash -# Step 1: Generate contract prompt for AI IDE -specfact spec generate contracts-prompt --bundle --feature +# Step 1: Use your AI IDE skill (/specfact.07-contracts) for contract enhancement workflows +# /specfact.07-contracts -# Step 2: [In AI IDE] Use slash command to apply contracts -# /specfact-cli/contracts-apply +# Step 2: Validate spec compliance +specfact spec validate --bundle -# Step 3: Check contract coverage -specfact spec contract coverage --bundle - -# Step 4: Run validation +# Step 3: Run validation specfact code repro --verbose ``` @@ -521,8 +517,8 @@ graph TD **Decision Points**: -- **After generating prompt**: Review the prompt in your AI IDE before applying. -- **Contract coverage**: Ensure coverage meets your requirements before validation. +- **After using AI IDE skill**: Review the AI-generated contracts before applying. +- **Spec validation**: Ensure coverage meets your requirements before validation. - **Validation**: If validation fails, review and fix contracts, then re-run. **Expected Outcomes**: @@ -547,16 +543,13 @@ graph TD **Command Sequence**: ```bash -# Step 1: Generate test prompt for AI IDE -specfact spec generate test-prompt --bundle --feature - -# Step 2: [In AI IDE] Use slash command to generate tests -# /specfact-cli/test-generate +# Step 1: Use your AI IDE skill (/specfact.07-contracts) for contract enhancement workflows +# /specfact.07-contracts -# Step 3: Generate tests from specification +# Step 2: Generate tests from specification specfact spec generate-tests --spec --output tests/ -# Step 4: Run tests +# Step 3: Run tests pytest tests/ ``` @@ -574,7 +567,7 @@ graph TD **Decision Points**: -- **Test generation method**: Use AI IDE for custom tests, or `spec generate-tests` for specification-based tests. +- **Test generation method**: Use AI IDE skill `/specfact.07-contracts` for custom tests, or `spec generate-tests` for specification-based tests. - **Test coverage**: Review generated tests to ensure they cover all scenarios. - **Test execution**: Run tests in CI/CD for continuous validation. @@ -603,13 +596,10 @@ graph TD # Step 1: Run validation with verbose output specfact code repro --verbose -# Step 2: Generate fix prompt for discovered gaps -specfact spec generate fix-prompt --bundle --gap - -# Step 3: [In AI IDE] Use slash command to apply fixes -# /specfact-cli/fix-apply +# Step 2: Use your AI IDE skill (/specfact.07-contracts) for contract enhancement workflows +# /specfact.07-contracts -# Step 4: Enforce SDD compliance +# Step 3: Enforce SDD compliance specfact govern enforce sdd --bundle ``` @@ -627,7 +617,7 @@ graph TD **Decision Points**: - **After `repro --verbose`**: Review discovered gaps and prioritize fixes. -- **Fix application**: Review AI-suggested fixes before applying. +- **Fix application**: Review AI-suggested fixes from `/specfact.07-contracts` before applying. - **SDD enforcement**: Ensure compliance after fixes are applied. **Expected Outcomes**: @@ -652,35 +642,24 @@ graph TD **Command Sequence**: ```bash -# Step 1: Bootstrap constitution from repository -specfact spec sdd constitution bootstrap --repo . - -# Step 2: Enrich constitution with repository context -specfact spec sdd constitution enrich --repo . - -# Step 3: Validate constitution completeness -specfact spec sdd constitution validate - -# Step 4: List SDD manifests -specfact spec sdd list +# Use specfact govern enforce sdd [BUNDLE] for SDD enforcement +specfact govern enforce sdd ``` **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 + A[Repository] -->|govern enforce sdd| B[SDD Enforcement] + B -->|Pass| C[SDD Compliant] + B -->|Issues Found| D[Fix Issues] + D --> B ``` **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. +- **SDD Enforcement**: Use `specfact govern enforce sdd [BUNDLE]` for all SDD enforcement workflows. +- **Spec-Kit Compatibility**: SDD constitution commands are removed. SpecFact uses modular project bundles internally. **Expected Outcomes**: @@ -729,21 +708,21 @@ The following commands are now integrated into documented workflows: --- -### `sdd list` +### `govern enforce sdd` **Integrated into**: [SDD Constitution Management Chain](#10-sdd-constitution-management-chain) -**When to use**: List SDD manifests in repository. +**When to use**: Enforce SDD compliance for a bundle. -**Workflow**: Use after constitution management to verify manifests. +**Workflow**: Use after plan hardening to validate SDD compliance. --- -### `contract verify` +### `spec validate` **Integrated into**: [API Contract Development Chain](#4-api-contract-development-chain) -**When to use**: Verify contracts at runtime. +**When to use**: Validate contracts at runtime. **Workflow**: Use as final step in API Contract Development Chain. diff --git a/docs/guides/common-tasks.md b/docs/guides/common-tasks.md index b49da3bc..de640cca 100644 --- a/docs/guides/common-tasks.md +++ b/docs/guides/common-tasks.md @@ -40,14 +40,14 @@ specfact code import legacy-api --repo . **Recommended**: [Greenfield Planning Chain](command-chains.md#2-greenfield-planning-chain) -**Command**: `plan init` → `plan add-feature` → `plan add-story` +**Command**: `project devops-flow --stage plan --action init` → `add-feature` → `add-story` **Quick Example**: ```bash -specfact project plan init new-feature --interactive -specfact project plan add-feature --bundle new-feature --name "User Authentication" -specfact project plan add-story --bundle new-feature --feature --story "As a user, I want to log in" +specfact project devops-flow --stage plan --action init --bundle new-feature --interactive +specfact project devops-flow --stage plan --action add-feature --bundle new-feature --name "User Authentication" +specfact project devops-flow --stage plan --action add-story --bundle new-feature --feature --story "As a user, I want to log in" ``` **Detailed Guide**: [Agile/Scrum Workflows](agile-scrum-workflows.md) @@ -58,12 +58,12 @@ specfact project plan add-story --bundle new-feature --feature --st **Recommended**: [External Tool Integration Chain](command-chains.md#3-external-tool-integration-chain) -**Command**: `import from-bridge` → `sync bridge` +**Command**: `code import from-bridge` → `sync bridge` **Quick Example**: ```bash -specfact project import from-bridge --repo . --adapter speckit --write +specfact code import from-bridge --repo . --adapter speckit --write specfact project sync bridge --adapter speckit --bundle --bidirectional --watch ``` @@ -89,13 +89,13 @@ specfact code import legacy-api --repo ./legacy-app ### I want to review and update extracted features -**Recommended**: `plan review` → `plan update-feature` +**Recommended**: `project snapshot` → `project devops-flow --stage plan --action update-feature` **Quick Example**: ```bash -specfact project plan review legacy-api -specfact project plan update-feature --bundle legacy-api --feature +specfact project snapshot legacy-api +specfact project devops-flow --stage plan --action update-feature --bundle legacy-api --feature ``` **Detailed Guide**: [Brownfield Engineer Guide](brownfield-engineer.md#step-2-refine-your-plan) @@ -106,13 +106,13 @@ specfact project plan update-feature --bundle legacy-api --feature **Recommended**: [Code-to-Plan Comparison Chain](command-chains.md#6-code-to-plan-comparison-chain) -**Command**: `plan compare` → `drift detect` +**Command**: `project devops-flow compare` → `drift detect` **Quick Example**: ```bash specfact code import current-state --repo . -specfact project plan compare --bundle --code-vs-plan +specfact project devops-flow --stage plan --action compare --bundle --code-vs-plan specfact code drift detect --bundle ``` @@ -124,14 +124,14 @@ specfact code drift detect --bundle **Recommended**: [AI-Assisted Code Enhancement Chain](command-chains.md#7-ai-assisted-code-enhancement-chain-emerging) -**Command**: `generate contracts-prompt` → [AI IDE] → `contracts-apply` +**Command**: AI IDE skill `/specfact.07-contracts` → `spec validate` **Quick Example**: ```bash -specfact spec generate contracts-prompt --bundle --feature -# Then use AI IDE slash command: /specfact-cli/contracts-apply -specfact spec contract coverage --bundle +# Use your AI IDE skill (/specfact.07-contracts) for contract enhancement workflows +# /specfact.07-contracts +specfact spec validate --bundle ``` **Detailed Guide**: [AI IDE Workflow](ai-ide-workflow.md) @@ -273,14 +273,14 @@ specfact project version bump --bundle --type minor **Recommended**: [Plan Promotion & Release Chain](command-chains.md#5-plan-promotion--release-chain) -**Command**: `plan review` → `enforce sdd` → `plan promote` +**Command**: `project snapshot` → `enforce sdd` → `project devops-flow release promote` **Quick Example**: ```bash -specfact project plan review +specfact project snapshot specfact govern enforce sdd --bundle -specfact project plan promote --bundle --stage approved +specfact project devops-flow --stage release --action promote --bundle --stage approved ``` **Detailed Guide**: [Agile/Scrum Workflows](agile-scrum-workflows.md) @@ -289,12 +289,12 @@ specfact project plan promote --bundle --stage approved ### I want to compare two plans -**Recommended**: `plan compare` +**Recommended**: `project devops-flow compare` **Quick Example**: ```bash -specfact project plan compare --bundle plan-v1 plan-v2 +specfact project devops-flow --stage plan --action compare --bundle plan-v1 plan-v2 ``` **Detailed Guide**: [Plan Comparison](../reference/commands.md#plan-compare) @@ -335,14 +335,13 @@ specfact govern enforce sdd --bundle **Recommended**: [Gap Discovery & Fixing Chain](command-chains.md#9-gap-discovery--fixing-chain-emerging) -**Command**: `repro --verbose` → `generate fix-prompt` +**Command**: `repro --verbose` → AI IDE skill `/specfact.07-contracts` **Quick Example**: ```bash specfact code repro --verbose -specfact spec generate fix-prompt --bundle --gap -# Then use AI IDE to apply fixes +# Use your AI IDE skill (/specfact.07-contracts) for contract enhancement workflows ``` **Detailed Guide**: [AI IDE Workflow](ai-ide-workflow.md) @@ -369,13 +368,13 @@ specfact init ide --ide cursor **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` +**Command**: AI IDE skill `/specfact.07-contracts` → `spec generate-tests` **Quick Example**: ```bash -specfact spec generate test-prompt --bundle --feature -# Then use AI IDE slash command: /specfact-cli/test-generate +# Use your AI IDE skill (/specfact.07-contracts) for contract enhancement workflows +# /specfact.07-contracts specfact spec generate-tests --spec --output tests/ ``` @@ -613,7 +612,7 @@ specfact --version specfact code repro --verbose # Check plan for issues -specfact project plan review +specfact project snapshot ``` **Detailed Guide**: [Troubleshooting](troubleshooting.md) diff --git a/docs/guides/competitive-analysis.md b/docs/guides/competitive-analysis.md index fa24ea0b..fb2f7368 100644 --- a/docs/guides/competitive-analysis.md +++ b/docs/guides/competitive-analysis.md @@ -93,7 +93,7 @@ specfact project sync bridge --adapter github --mode export-only \ Already using Spec-Kit? SpecFact CLI **imports your work** in one command: ```bash -specfact project import from-bridge --adapter speckit --repo ./my-speckit-project --write +specfact code import from-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. @@ -119,7 +119,7 @@ specfact project sync bridge --adapter speckit --bundle --repo . - # → No manual markdown sharing required # Detect code vs plan drift automatically -specfact project plan compare --bundle legacy-api --code-vs-plan +specfact project devops-flow --stage plan --action 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) @@ -241,7 +241,7 @@ specfact govern enforce stage --preset balanced ```bash # Detect code vs plan drift automatically -specfact project plan compare --bundle legacy-api --code-vs-plan +specfact project devops-flow --stage plan --action 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) @@ -317,7 +317,7 @@ See [Use Cases: Brownfield Modernization](use-cases.md#use-case-1-brownfield-cod **One-command import**: ```bash -specfact project import from-bridge --adapter speckit --repo . --write +specfact code import from-bridge --adapter speckit --repo . --write ``` See [Use Cases: Spec-Kit Migration](use-cases.md#use-case-2-github-spec-kit-migration-secondary) @@ -351,7 +351,7 @@ SpecFact CLI automatically detects CoPilot and switches to enhanced mode. **Greenfield approach**: -1. `specfact project plan init legacy-api --interactive` +1. `specfact project devops-flow --stage plan --action init --bundle legacy-api --interactive` 2. Add features and stories 3. Enable strict enforcement 4. Let SpecFact guide development diff --git a/docs/guides/contract-testing-workflow.md b/docs/guides/contract-testing-workflow.md index 86ed0ffd..49eebace 100644 --- a/docs/guides/contract-testing-workflow.md +++ b/docs/guides/contract-testing-workflow.md @@ -17,11 +17,11 @@ description: Practical contract testing workflow guidance for SpecFact users and The easiest way to verify your OpenAPI contract works is with a single command: ```bash -# Verify a specific contract -specfact spec contract verify --bundle my-api --feature FEATURE-001 +# Validate a specific contract bundle +specfact spec validate --bundle my-api --feature FEATURE-001 -# Verify all contracts in a bundle -specfact spec contract verify --bundle my-api +# Validate all contracts in a bundle +specfact spec validate --bundle my-api ``` **What this does:** @@ -35,12 +35,12 @@ specfact spec contract verify --bundle my-api ## What You Can Do Without a Real API -### ✅ Contract Verification (No API Needed) +### ✅ Contract Validation (No API Needed) -Use `contract verify` to ensure your contract is correct: +Use `spec validate` to ensure your contract is correct: ```bash -specfact spec contract verify --bundle my-api --feature FEATURE-001 +specfact spec validate --bundle my-api --feature FEATURE-001 ``` **Output:** @@ -75,10 +75,10 @@ Start a mock server that generates responses from your contract: ```bash # Start mock server with examples -specfact spec contract serve --bundle my-api --feature FEATURE-001 --examples +specfact spec mock --bundle my-api --feature FEATURE-001 --examples -# Or use the verify command (starts mock server automatically) -specfact spec contract verify --bundle my-api --feature FEATURE-001 +# Or use the validate command (starts mock server automatically) +specfact spec validate --bundle my-api --feature FEATURE-001 ``` **Use cases:** @@ -93,10 +93,10 @@ Validate that your contract schema is correct: ```bash # Validate a specific contract -specfact spec contract validate --bundle my-api --feature FEATURE-001 +specfact spec validate --bundle my-api --feature FEATURE-001 -# Check coverage across all contracts -specfact spec contract coverage --bundle my-api +# Check test coverage across all contracts +specfact spec generate-tests --bundle my-api ``` ## Complete Workflow Examples @@ -104,14 +104,14 @@ specfact spec contract coverage --bundle my-api ### Example 1: New Contract Development ```bash -# 1. Create a new contract -specfact spec contract init --bundle my-api --feature FEATURE-001 +# 1. Set up validation for a new bundle +specfact spec validate --bundle my-api # 2. Edit the contract file # Edit: .specfact/projects/my-api/contracts/FEATURE-001.openapi.yaml -# 3. Verify everything works -specfact spec contract verify --bundle my-api --feature FEATURE-001 +# 3. Validate everything works +specfact spec validate --bundle my-api --feature FEATURE-001 # 4. Test your client code against the mock server curl http://localhost:9000/api/endpoint @@ -121,20 +121,20 @@ curl http://localhost:9000/api/endpoint ```bash # Validate contracts without starting mock server -specfact spec contract verify --bundle my-api --skip-mock --no-interactive +specfact spec validate --bundle my-api --skip-mock --no-interactive # Or just validate -specfact spec contract validate --bundle my-api --no-interactive +specfact spec validate --bundle my-api --no-interactive ``` ### Example 3: Multiple Contracts ```bash -# Verify all contracts in a bundle -specfact spec contract verify --bundle my-api +# Validate all contracts in a bundle +specfact spec validate --bundle my-api -# Check coverage -specfact spec contract coverage --bundle my-api +# Generate tests from contracts +specfact spec generate-tests --bundle my-api ``` ## What Requires a Real API @@ -160,7 +160,7 @@ specmatic test \ ```bash # 1. Generate test files -specfact spec contract test --bundle my-api --feature FEATURE-001 +specfact spec generate-tests --bundle my-api --feature FEATURE-001 # 2. Start your real API python -m uvicorn main:app --port 8000 @@ -173,12 +173,12 @@ specmatic test \ ## Command Reference -### `contract verify` - All-in-One Verification +### `spec validate` - All-in-One Verification The simplest way to verify your contract: ```bash -specfact spec contract verify [OPTIONS] +specfact spec validate [OPTIONS] Options: --bundle TEXT Project bundle name @@ -195,34 +195,26 @@ Options: 3. Starts mock server (unless `--skip-mock`) 4. Tests connectivity -### `contract validate` - Schema Validation +### `spec validate` - Schema Validation ```bash -specfact spec contract validate --bundle my-api --feature FEATURE-001 +specfact spec validate --bundle my-api --feature FEATURE-001 ``` Validates the OpenAPI schema structure. -### `contract serve` - Mock Server +### `spec mock` - Mock Server ```bash -specfact spec contract serve --bundle my-api --feature FEATURE-001 --examples +specfact spec mock --bundle my-api --feature FEATURE-001 --examples ``` Starts a mock server that generates responses from your contract. -### `contract coverage` - Coverage Report +### `spec generate-tests` - Generate Tests ```bash -specfact spec contract coverage --bundle my-api -``` - -Shows contract coverage metrics across all features. - -### `contract test` - Generate Tests - -```bash -specfact spec contract test --bundle my-api --feature FEATURE-001 +specfact spec generate-tests --bundle my-api --feature FEATURE-001 ``` Generates test files that can be run against a real API. @@ -231,11 +223,11 @@ Generates test files that can be run against a real API. | 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`) | +| **Contract Validation** | ❌ No | `spec validate` | +| **Schema Validation** | ❌ No | `spec validate` | +| **Mock Server** | ❌ No | `spec mock` | +| **Example Generation** | ❌ No | `spec validate` (automatic) | +| **Contract Testing** | ✅ Yes | `specmatic test` (after `spec generate-tests`) | ## Troubleshooting @@ -256,7 +248,7 @@ npm install -g @specmatic/specmatic cat .specfact/projects/my-api/contracts/FEATURE-001.openapi.yaml # Validate manually -specfact spec contract validate --bundle my-api --feature FEATURE-001 +specfact spec validate --bundle my-api --feature FEATURE-001 ``` ### Examples Not Generated @@ -265,11 +257,11 @@ Examples are generated automatically from your OpenAPI schema. If generation fai - Check that your schema has proper request/response definitions - Ensure data types are properly defined -- Run `contract verify` to see detailed error messages +- Run `spec validate` to see detailed error messages ## Best Practices -1. **Start with `contract verify`** - It does everything you need +1. **Start with `spec validate`** - 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 diff --git a/docs/guides/devops-adapter-integration.md b/docs/guides/devops-adapter-integration.md index 3ba5e66b..b25f2488 100644 --- a/docs/guides/devops-adapter-integration.md +++ b/docs/guides/devops-adapter-integration.md @@ -22,14 +22,14 @@ You can validate policy readiness (DoR/DoD, Kanban flow gates, SAFe PI hooks) be your backlog system: ```bash -# Deterministic policy validation with JSON + Markdown output -specfact backlog policy validate --repo . --format both +# Deterministic readiness validation +specfact backlog verify-readiness --repo . -# AI-assisted suggestions with confidence scores and patch-ready output -specfact backlog policy suggest --repo . +# AI-assisted refinement suggestions (no automatic writes) +specfact backlog refine --repo . ``` -Both commands read `.specfact/policy.yaml`. `policy suggest` never writes changes automatically; it emits +Both commands read `.specfact/policy.yaml`. `backlog refine` never writes changes automatically; it emits recommendations you can review and apply explicitly in your normal workflow. ## Overview diff --git a/docs/guides/dual-stack-enrichment.md b/docs/guides/dual-stack-enrichment.md index 0ae66389..6b365473 100644 --- a/docs/guides/dual-stack-enrichment.md +++ b/docs/guides/dual-stack-enrichment.md @@ -216,10 +216,10 @@ specfact code import [] --repo --enrichment ` - Initialize project bundle -- `specfact project plan select ` - Set active plan (used as default for other commands) +- `specfact project devops-flow --stage plan --action init --bundle ` - Initialize project bundle +- `specfact project snapshot ` - Set active plan / review plan state (used as default for other commands) - `specfact code import [] --repo ` - Import from codebase (uses active plan if bundle not specified) -- `specfact project plan review []` - Review plan (uses active plan if bundle not specified) -- `specfact project plan harden []` - Create SDD manifest (uses active plan if bundle not specified) +- `specfact project snapshot []` - Review plan (uses active plan if bundle not specified) +- `specfact project devops-flow --stage plan --action harden --bundle []` - Create SDD manifest (uses active plan if bundle not specified) - `specfact govern enforce sdd []` - Validate SDD (uses active plan if bundle not specified) -- `specfact spec generate contracts-prompt --apply ` - Generate contract enhancement prompt -- `specfact spec generate contracts-apply --original ` - Validate and apply enhanced code +- Use AI IDE skill `/specfact.07-contracts` for contract enhancement workflows (prompt generation, validation, and apply) - `specfact project sync bridge --adapter --repo ` - Sync with external tools - See [Command Reference](../reference/commands.md) for full list diff --git a/docs/guides/ide-integration.md b/docs/guides/ide-integration.md index 2c19a9fd..f2abb1f4 100644 --- a/docs/guides/ide-integration.md +++ b/docs/guides/ide-integration.md @@ -162,20 +162,20 @@ Detailed instructions for the AI assistant... | Command | Description | CLI Equivalent | |---------|-------------|----------------| | `/specfact.01-import` | Import codebase into plan bundle | `specfact code import ` | -| `/specfact.02-plan` | Plan management (init, add-feature, add-story, update-idea, update-feature, update-story) | `specfact project plan ` | -| `/specfact.03-review` | Review plan and promote through stages | `specfact project plan review `, `specfact project plan promote ` | -| `/specfact.04-sdd` | Create SDD manifest from plan | `specfact project plan harden ` | +| `/specfact.02-plan` | Plan management (init, add-feature, add-story, update-idea, update-feature, update-story) | `specfact project snapshot --bundle ` | +| `/specfact.03-review` | Review plan and promote through stages | `specfact project devops-flow --stage develop --bundle `, `specfact project health-check` | +| `/specfact.04-sdd` | Create SDD manifest from plan | `specfact project snapshot ` | | `/specfact.05-enforce` | Validate SDD and contracts | `specfact govern enforce sdd ` | | `/specfact.06-sync` | Sync with external tools or repository | `specfact project sync bridge --adapter ` | -| `/specfact.07-contracts` | Contract enhancement workflow: analyze → generate prompts → apply sequentially | `specfact code analyze contracts`, `specfact spec generate contracts-prompt`, `specfact spec generate contracts-apply` | +| `/specfact.07-contracts` | Contract enhancement workflow: analyze → generate prompts → apply sequentially | `specfact code analyze contracts` (use your AI IDE skill `/specfact.07-contracts` for contract enhancement workflows) | **Advanced Commands** (no numbering): | Command | Description | CLI Equivalent | |---------|-------------|----------------| -| `/specfact.compare` | Compare manual vs auto plans | `specfact project plan compare` | +| `/specfact.compare` | Compare manual vs auto plans | `specfact project regenerate` | | `/specfact.validate` | Run validation suite | `specfact code repro` | -| `/specfact.generate-contracts-prompt` | Generate AI IDE prompt for adding contracts | `specfact spec generate contracts-prompt --apply ` | +| `/specfact.generate-contracts-prompt` | Generate AI IDE prompt for adding contracts | Use your AI IDE skill (`/specfact.07-contracts`) for contract enhancement workflows | --- diff --git a/docs/guides/migration-0.16-to-0.19.md b/docs/guides/migration-0.16-to-0.19.md index 8f789e3e..d1f0af50 100644 --- a/docs/guides/migration-0.16-to-0.19.md +++ b/docs/guides/migration-0.16-to-0.19.md @@ -40,11 +40,8 @@ specfact code repro setup # Analyze and validate your codebase specfact code repro --verbose -# Generate AI-ready prompt to fix a gap -specfact spec generate fix-prompt GAP-001 --bundle my-bundle - -# Generate AI-ready prompt to add tests -specfact spec generate test-prompt src/auth/login.py --bundle my-bundle +# Use your AI IDE skill (/specfact.07-contracts) for contract enhancement workflows +# These AI IDE prompt generation commands were removed; use /specfact.07-contracts skill instead ``` ### `run idea-to-ship` Removed @@ -59,14 +56,11 @@ The `run idea-to-ship` command has been removed in v0.17.0. ### Bridge Commands (v0.17.0) -New commands that generate AI-ready prompts for your IDE: +AI-ready prompts for your IDE are now generated via the AI IDE skill workflow: ```bash -# Generate fix prompt for a gap -specfact spec generate fix-prompt GAP-001 - -# Generate test prompt for a file -specfact spec generate test-prompt src/module.py --type unit +# Use your AI IDE skill (/specfact.07-contracts) for contract enhancement workflows +# These AI IDE prompt generation commands were removed; use /specfact.07-contracts skill instead ``` ### Version Management (v0.17.0) @@ -119,8 +113,8 @@ If you were using `implement tasks` or `run idea-to-ship`, migrate to bridge com ```bash # REMOVED in v0.22.0 - Use Spec-Kit, OpenSpec, or other SDD tools instead -# specfact spec generate tasks --bundle my-bundle -# specfact implement tasks .specfact/projects/my-bundle/tasks.yaml +# These task generation commands were removed; use specfact govern enforce sdd --bundle my-bundle instead +# specfact implement tasks was also removed in v0.22.0 ``` **New workflow:** @@ -129,8 +123,7 @@ If you were using `implement tasks` or `run idea-to-ship`, migrate to bridge com # 1. Analyze and validate your codebase specfact code repro --verbose -# 2. Generate AI prompts for each gap -specfact spec generate fix-prompt GAP-001 --bundle my-bundle +# 2. Use your AI IDE skill (/specfact.07-contracts) for contract enhancement workflows # 3. Copy prompt to AI IDE, get fix, apply diff --git a/docs/guides/migration-cli-reorganization.md b/docs/guides/migration-cli-reorganization.md index aa758d7f..1e26e610 100644 --- a/docs/guides/migration-cli-reorganization.md +++ b/docs/guides/migration-cli-reorganization.md @@ -24,7 +24,7 @@ The CLI reorganization includes: | Old Name | New Name | Commands Affected | |----------|----------|-------------------| -| `--base-path` | `--repo` | `generate contracts` | +| `--base-path` | `--repo` | `code import` and other commands (note: `generate contracts` is removed) | | `--output` | `--out` | `bridge constitution bootstrap` | | `--format` | `--output-format` | `enforce sdd`, `plan compare` | | `--non-interactive` | `--no-interactive` | All commands | @@ -42,19 +42,19 @@ The CLI reorganization includes: **Before**: ```bash -specfact spec generate contracts --base-path . -specfact project plan compare --bundle legacy-api --format json --out report.json +# Old: project plan compare (removed) → use: specfact project regenerate specfact govern enforce sdd legacy-api --non-interactive ``` **After**: ```bash -specfact spec generate contracts --repo . -specfact project plan compare --bundle legacy-api --output-format json --out report.json +specfact project regenerate --bundle legacy-api --output-format json --out report.json specfact govern enforce sdd legacy-api --no-interactive ``` +**Note**: `specfact spec generate contracts` is removed. Use your AI IDE skill (`/specfact.07-contracts`) for contract enhancement workflows. + --- ## Slash Command Changes @@ -122,15 +122,15 @@ The new numbered commands follow natural workflow progression: **Before** (positional argument): ```bash -specfact project plan init legacy-api -specfact project plan review legacy-api +# Old: project plan init (removed) → use: specfact code import legacy-api --repo . +# Old: project plan review (removed) → use: specfact project devops-flow --stage develop --bundle legacy-api ``` **After** (named parameter): ```bash -specfact project plan init legacy-api -specfact project plan review legacy-api +specfact code import legacy-api --repo . +specfact project devops-flow --stage develop --bundle legacy-api ``` ### Path Resolution Changes diff --git a/docs/guides/migration-guide.md b/docs/guides/migration-guide.md index 28b3d71a..c9c080e7 100644 --- a/docs/guides/migration-guide.md +++ b/docs/guides/migration-guide.md @@ -122,7 +122,7 @@ Start: What do you need to migrate? specfact project export --bundle old-bundle --persona # Create new bundle -specfact project plan init new-bundle +specfact code import new-bundle --repo . # Import to new bundle (manual editing may be required) specfact project import --bundle new-bundle --persona --source exported.md @@ -141,20 +141,20 @@ specfact project import --bundle new-bundle --persona --source exporte **Command**: ```bash -# Upgrade all bundles -specfact project plan upgrade --all +# Regenerate all bundles +specfact project regenerate -# Upgrade specific bundle -specfact project plan upgrade --bundle +# Regenerate specific bundle +specfact project regenerate --bundle ``` **Benefits**: -- Improved performance (44% faster `plan select`) +- Improved performance - New features and metadata - Better compatibility -**Related**: [Plan Upgrade](../reference/commands.md#plan-upgrade) +**Related**: [Project Commands](../reference/commands.md#project---project-bundle-management) --- @@ -172,11 +172,11 @@ specfact --version # 3. Upgrade SpecFact CLI pip install --upgrade specfact-cli -# 4. Upgrade plan bundles -specfact project plan upgrade --all +# 4. Regenerate plan bundles +specfact project regenerate # 5. Test commands -specfact project plan select --last 5 +specfact project health-check ``` --- @@ -185,10 +185,10 @@ specfact project plan select --last 5 ```bash # 1. Import from Spec-Kit -specfact import from-bridge --repo . --adapter speckit --write +specfact code import from-bridge --repo . --adapter speckit --write # 2. Review imported plan -specfact project plan review +specfact project devops-flow --stage develop --bundle # 3. Set up bidirectional sync (optional) specfact project sync bridge --adapter speckit --bundle --bidirectional --watch @@ -205,16 +205,16 @@ specfact govern enforce sdd --bundle ### Common Issues -**Issue**: Plan bundles fail to upgrade +**Issue**: Plan bundles fail to regenerate **Solution**: ```bash -# Check bundle schema version -specfact project plan select --bundle --json | jq '.schema_version' +# Check bundle health +specfact project health-check -# Manual upgrade if needed -specfact project plan upgrade --bundle --force +# Regenerate if needed +specfact project regenerate --bundle ``` **Issue**: Imported plans have missing data @@ -222,8 +222,8 @@ specfact project plan upgrade --bundle --force **Solution**: 1. Review import logs -2. Use `plan review` to identify gaps -3. Use `plan update-feature` to fill missing data +2. Use `project devops-flow --stage develop` to identify gaps +3. Use `project health-check` to check status 4. Re-import if needed **Related**: [Troubleshooting Guide](troubleshooting.md) diff --git a/docs/guides/policy-engine-commands.md b/docs/guides/policy-engine-commands.md index f086166d..968ffb43 100644 --- a/docs/guides/policy-engine-commands.md +++ b/docs/guides/policy-engine-commands.md @@ -11,47 +11,26 @@ permalink: /guides/policy-engine-commands/ > Canonical bundle-specific deep guidance now lives in the canonical modules docs site, currently > published at `https://modules.specfact.io/`. -Use SpecFact policy commands to scaffold, validate, and improve policy configuration for common frameworks. +> **Note**: `backlog policy` commands were removed. The equivalent workflows are now under `backlog verify-readiness`, `backlog refine`, and `backlog ceremony`. + +Use SpecFact policy commands to validate readiness, refine backlog items, and run agile ceremonies. ## Overview The policy engine currently supports: -- `specfact backlog policy init` to scaffold `.specfact/policy.yaml` from a built-in template. -- `specfact backlog policy validate` to evaluate configured rules deterministically against policy input artifacts. -- `specfact backlog policy suggest` to generate confidence-scored, patch-ready recommendations (no automatic writes). +- `specfact backlog verify-readiness` to evaluate configured rules deterministically against policy input artifacts. +- `specfact backlog refine` to generate confidence-scored, patch-ready recommendations (no automatic writes). +- `specfact backlog ceremony` to run agile ceremonies (standup, refinement, etc.). ## Commands -### Initialize Policy Config - -Create a starter policy configuration file: - -```bash -specfact backlog policy init --repo . --template scrum -``` - -Supported templates: - -- `scrum` -- `kanban` -- `safe` -- `mixed` - -Interactive mode (template prompt): - -```bash -specfact backlog policy init --repo . -``` - -The command writes `.specfact/policy.yaml`. Use `--force` to overwrite an existing file. +### Verify Readiness -### Validate Policies - -Run policy checks with deterministic output: +Check that backlog items meet Definition of Ready / Definition of Done criteria: ```bash -specfact backlog policy validate --repo . --format both +specfact backlog verify-readiness --repo . --format both ``` Artifact resolution order when `--snapshot` is omitted: @@ -62,20 +41,20 @@ Artifact resolution order when `--snapshot` is omitted: You can still override with an explicit path: ```bash -specfact backlog policy validate --repo . --snapshot ./snapshot.json --format both +specfact backlog verify-readiness --repo . --snapshot ./snapshot.json --format both ``` Filter and scope output: ```bash # only one rule family, max 20 findings -specfact backlog policy validate --repo . --rule scrum.dor --limit 20 --format json +specfact backlog verify-readiness --repo . --rule scrum.dor --limit 20 --format json # item-centric grouped output -specfact backlog policy validate --repo . --group-by-item --format both +specfact backlog verify-readiness --repo . --group-by-item --format both # in grouped mode, --limit applies to item groups -specfact backlog policy validate --repo . --group-by-item --limit 4 --format json +specfact backlog verify-readiness --repo . --group-by-item --limit 4 --format json ``` Output formats: @@ -86,29 +65,38 @@ Output formats: When config is missing or invalid, the command prints a docs hint pointing back to this policy format guidance. -### Suggest Policy Fixes +### Refine Backlog Items -Generate suggestions from validation findings: +Generate suggestions from readiness findings: ```bash -specfact backlog policy suggest --repo . +specfact backlog refine --repo . ``` Suggestion shaping options: ```bash # suggestions for one rule family, limited output -specfact backlog policy suggest --repo . --rule scrum.dod --limit 10 +specfact backlog refine --repo . --rule scrum.dod --limit 10 # grouped suggestions by backlog item index -specfact backlog policy suggest --repo . --group-by-item +specfact backlog refine --repo . --group-by-item # grouped mode limits item groups, not per-item fields -specfact backlog policy suggest --repo . --group-by-item --limit 4 +specfact backlog refine --repo . --group-by-item --limit 4 ``` Suggestions include confidence scores and patch-ready structure, but no file is modified automatically. +### Run Agile Ceremonies + +Run standup or refinement ceremonies: + +```bash +specfact backlog ceremony standup +specfact backlog ceremony refinement +``` + ## Policy File Location and Format Expected location: diff --git a/docs/guides/speckit-comparison.md b/docs/guides/speckit-comparison.md index afd83085..52ea1551 100644 --- a/docs/guides/speckit-comparison.md +++ b/docs/guides/speckit-comparison.md @@ -213,7 +213,7 @@ permalink: /guides/speckit-comparison/ # (Interactive slash commands in GitHub) # Step 2: Import Spec-Kit artifacts into SpecFact (via bridge adapter) -specfact project import from-bridge --adapter speckit --repo ./my-project +specfact code import from-bridge --adapter speckit --repo ./my-project # Step 3: Add runtime contracts to critical Python paths # (SpecFact contract decorators) @@ -301,7 +301,7 @@ All adapters are registered in `AdapterRegistry` and accessed via `specfact proj **Yes.** SpecFact can import Spec-Kit artifacts: ```bash -specfact project import from-bridge --adapter speckit --repo ./my-project +specfact code import from-bridge --adapter speckit --repo ./my-project ``` You can also keep using both tools with bidirectional sync via the adapter registry pattern. diff --git a/docs/guides/speckit-journey.md b/docs/guides/speckit-journey.md index 7e8d6794..5bc5a92f 100644 --- a/docs/guides/speckit-journey.md +++ b/docs/guides/speckit-journey.md @@ -155,13 +155,13 @@ Import your Spec-Kit project to see what SpecFact adds: ```bash # 1. Preview what will be imported -specfact project import from-bridge --adapter speckit --repo ./my-speckit-project --dry-run +specfact code import from-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 project import from-bridge --adapter speckit --repo ./my-speckit-project --write +specfact code import from-bridge --adapter speckit --repo ./my-speckit-project --write # 3. Review generated bundle using CLI commands -specfact project plan review +specfact project devops-flow --stage develop --bundle ``` **What was created**: @@ -209,10 +209,10 @@ specfact project sync bridge --adapter speckit --bundle --repo . - # → Enables shared plans for team collaboration # 3. Detect code vs plan drift automatically -specfact project plan compare --code-vs-plan -# → Compares intended design (manual plan = what you planned) vs actual implementation (code-derived plan = what's in your code) +specfact project regenerate +# → Regenerates project artifacts from current code state # → 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" +# → Auto-derived plans come from `import from-code` (code analysis), so regeneration reflects current drift # 4. Enable automated enforcement specfact govern enforce stage --preset balanced @@ -244,7 +244,7 @@ specfact govern enforce stage --preset balanced ```bash # Import existing Spec-Kit project -specfact project import from-bridge --adapter speckit --repo . --write +specfact code import from-bridge --adapter speckit --repo . --write # Enable bidirectional sync (bridge-based, adapter-agnostic) specfact project sync bridge --adapter speckit --bundle --repo . --bidirectional --watch @@ -308,7 +308,7 @@ specfact code repro --budget 120 --verbose ```bash # See what will be imported (safe - no changes) -specfact project import from-bridge --adapter speckit --repo ./my-speckit-project --dry-run +specfact code import from-bridge --adapter speckit --repo ./my-speckit-project --dry-run ``` **Expected Output**: @@ -321,7 +321,7 @@ specfact project import from-bridge --adapter speckit --repo ./my-speckit-projec ✅ Found specs/001-user-authentication/tasks.md ✅ Found .specify/memory/constitution.md -**💡 Tip**: If constitution is missing or minimal, run `specfact spec sdd constitution bootstrap --repo .` to auto-generate from repository analysis. +**💡 Tip**: If constitution is missing or minimal, use `specfact govern enforce sdd [BUNDLE]` for SDD enforcement. Note: `specfact spec sdd constitution` commands are removed. 📊 Migration Preview: - Will create: .specfact/projects// (modular project bundle) @@ -337,7 +337,7 @@ specfact project import from-bridge --adapter speckit --repo ./my-speckit-projec ```bash # Execute migration (creates SpecFact artifacts) -specfact project import from-bridge \ +specfact code import from-bridge \ --adapter speckit \ --repo ./my-speckit-project \ --write \ @@ -365,7 +365,7 @@ specfact project import from-bridge \ ```bash # Review plan bundle using CLI commands -specfact project plan review +specfact project devops-flow --stage develop --bundle # Review enforcement config using CLI commands specfact govern enforce show-config @@ -537,8 +537,8 @@ specfact govern enforce stage --preset strict **Next Steps**: -1. **Try it**: `specfact project import from-bridge --adapter speckit --repo . --dry-run` -2. **Import**: `specfact project import from-bridge --adapter speckit --repo . --write` +1. **Try it**: `specfact code import from-bridge --adapter speckit --repo . --dry-run` +2. **Import**: `specfact code import from-bridge --adapter speckit --repo . --write` 3. **Sync**: `specfact project sync bridge --adapter speckit --bundle --repo . --bidirectional --watch` 4. **Enforce**: `specfact govern enforce stage --preset minimal` (start shadow mode) diff --git a/docs/guides/specmatic-integration.md b/docs/guides/specmatic-integration.md index 65114f0e..1635875c 100644 --- a/docs/guides/specmatic-integration.md +++ b/docs/guides/specmatic-integration.md @@ -115,7 +115,7 @@ specfact spec validate --bundle legacy-api specfact spec validate --bundle legacy-api --no-interactive ``` -**CLI-First Pattern**: The command uses the active plan (from `specfact project plan select`) as default, or you can specify `--bundle`. Never requires direct `.specfact` paths - always use the CLI interface. +**CLI-First Pattern**: The command uses the current bundle (specified via --bundle) as default. Never requires direct `.specfact` paths - always use the CLI interface. **What it checks:** @@ -154,7 +154,7 @@ specfact spec generate-tests --bundle legacy-api 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. +**CLI-First Pattern**: Uses the current bundle (specified via --bundle). Never requires direct `.specfact` paths. ### What Can You Do With Generated Tests? @@ -401,7 +401,7 @@ specfact spec mock --bundle legacy-api 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. +**CLI-First Pattern**: Uses the current bundle (specified via --bundle). Interactive selection when multiple contracts available. **Mock server features:** @@ -421,7 +421,7 @@ Specmatic validation is automatically integrated into: When importing code, SpecFact auto-detects and validates OpenAPI/AsyncAPI specs: ```bash -# Import with bundle (uses active plan if --bundle not specified) +# Import with bundle specfact code import legacy-api --repo . # Automatically validates: @@ -435,7 +435,7 @@ specfact code import legacy-api --repo . SDD enforcement includes Specmatic validation for all contracts referenced in the bundle: ```bash -# Enforce SDD (uses active plan if --bundle not specified) +# Enforce SDD specfact govern enforce sdd --bundle legacy-api # Automatically validates: @@ -449,7 +449,7 @@ specfact govern enforce sdd --bundle legacy-api Repository sync validates specs before synchronization: ```bash -# Sync bridge (uses active plan if --bundle not specified) +# Sync bridge specfact project sync bridge --bundle legacy-api --repo . # Automatically validates: @@ -527,11 +527,8 @@ specfact spec backward-compat api/v1/openapi.yaml api/v2/openapi.yaml ### Example 3: Development Workflow with Bundle ```bash -# 1. Set active bundle -specfact project plan select api-service - -# 2. Validate all contracts in bundle (interactive selection) -specfact spec validate +# 1. Validate all contracts in bundle (interactive selection) +specfact spec validate --bundle api-service # Shows list of contracts, select by number or 'all' # 3. Start mock server from bundle (interactive selection) diff --git a/docs/guides/troubleshooting.md b/docs/guides/troubleshooting.md index 00d30bc8..e1eb0614 100644 --- a/docs/guides/troubleshooting.md +++ b/docs/guides/troubleshooting.md @@ -28,23 +28,23 @@ Common issues and solutions for SpecFact CLI. pip install --upgrade specfact-cli ``` -## Plan Select Command is Slow +## Plan Bundles are Slow or Outdated -**Symptom**: `specfact project plan select` takes a long time (5+ seconds) to list plans. +**Symptom**: Project commands take a long time or return stale data. **Cause**: Plan bundles may be missing summary metadata (older schema version 1.0). **Solution**: ```bash -# Upgrade all plan bundles to latest schema (adds summary metadata) -specfact project plan upgrade --all +# Regenerate all plan bundles to latest schema +specfact project regenerate -# Verify upgrade worked -specfact project plan select --last 5 +# Verify with health check +specfact project health-check ``` -**Performance Improvement**: After upgrade, `plan select` is 44% faster (3.6s vs 6.5s) and scales better with large plan bundles. +**Performance Improvement**: After regenerating, bundles are updated and scale better with large projects. 1. **Use uvx** (no installation needed): @@ -103,7 +103,7 @@ specfact project plan select --last 5 3. **Use explicit path**: ```bash - specfact project import from-bridge --adapter speckit --repo /path/to/speckit-project + specfact code import from-bridge --adapter speckit --repo /path/to/speckit-project ``` ### Code Analysis Fails (Brownfield) ⭐ @@ -277,46 +277,31 @@ specfact project plan select --last 5 **Issue**: `Constitution required` or `Constitution is minimal` when running `sync bridge --adapter speckit` -**Solutions**: - -1. **Auto-generate bootstrap constitution** (recommended for brownfield): - - ```bash - specfact spec 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 spec sdd constitution enrich --repo . - ``` +> **Note**: `specfact spec sdd constitution` commands are removed; use `specfact govern enforce sdd [BUNDLE]` for SDD enforcement. - This fills placeholders in an existing constitution with repository context. +**Solutions**: -3. **Validate constitution completeness**: +1. **Enforce SDD** (recommended): ```bash - specfact spec sdd constitution validate + specfact govern enforce sdd ``` - This checks if the constitution is complete and ready for use. + This validates SDD compliance for your bundle. -4. **Manual creation** (for greenfield): +2. **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 +- **SDD enforcement** (all cases): Use `specfact govern enforce sdd [BUNDLE]` to validate compliance - **Manual** (greenfield): Use when starting a new project and want full control ### Constitution Validation Fails -**Issue**: `specfact spec sdd constitution validate` reports issues +**Issue**: Constitution validation reports issues **Solutions**: @@ -326,25 +311,16 @@ specfact project plan select --last 5 grep -r "\[.*\]" .specify/memory/constitution.md ``` -2. **Run enrichment**: +2. **Run SDD enforcement**: ```bash - specfact spec sdd constitution enrich --repo . - ``` - -3. **Review validation output**: - - ```bash - specfact spec sdd constitution validate --constitution .specify/memory/constitution.md + # specfact spec sdd constitution commands are removed; use specfact govern enforce sdd [BUNDLE] for SDD enforcement + specfact govern enforce sdd ``` The output will list specific issues (missing sections, placeholders, etc.). -4. **Fix issues manually** or re-run bootstrap: - - ```bash - specfact spec sdd constitution bootstrap --repo . --overwrite - ``` +3. **Fix issues manually** or re-run enforcement. --- @@ -366,7 +342,7 @@ specfact project plan select --last 5 2. **Use explicit paths** (bundle directory paths): ```bash - specfact project plan compare \ + specfact project devops-flow --stage plan --action compare \ --manual .specfact/projects/manual-plan \ --auto .specfact/projects/auto-derived ``` @@ -391,13 +367,13 @@ specfact project plan select --last 5 2. **Verify plan contents** (use CLI commands): ```bash - specfact project plan review + specfact project devops-flow --stage develop --bundle ``` 3. **Use verbose mode**: ```bash - specfact project plan compare --bundle legacy-api --verbose + specfact project devops-flow --stage plan --action compare --bundle legacy-api --verbose ``` --- diff --git a/docs/guides/use-cases.md b/docs/guides/use-cases.md index 19226ac6..4faed708 100644 --- a/docs/guides/use-cases.md +++ b/docs/guides/use-cases.md @@ -120,9 +120,8 @@ specfact project sync repository --repo . --watch --interval 5 #### 4. Compare with Manual Plan (if exists) ```bash -specfact project plan compare \ - --manual .specfact/projects/manual-plan \ - --auto .specfact/projects/auto-derived \ +specfact project regenerate \ + --bundle \ --output-format markdown \ --out .specfact/projects//reports/comparison/deviation-report.md ``` @@ -210,7 +209,7 @@ specfact govern enforce stage --preset strict #### 1. Preview Migration ```bash -specfact project import from-bridge --adapter speckit --repo ./spec-kit-project --dry-run +specfact code import from-bridge --adapter speckit --repo ./spec-kit-project --dry-run ``` **Expected Output:** @@ -236,7 +235,7 @@ specfact project import from-bridge --adapter speckit --repo ./spec-kit-project #### 2. Execute Migration ```bash -specfact project import from-bridge \ +specfact code import from-bridge \ --adapter speckit \ --repo ./spec-kit-project \ --write \ @@ -247,7 +246,7 @@ specfact project import from-bridge \ ```bash # Review using CLI commands -specfact project plan review +specfact project devops-flow --stage develop --bundle ``` Review: @@ -260,17 +259,11 @@ Review: #### 4: Generate Constitution (If Missing) -Before syncing, ensure you have a valid constitution: +Before syncing, ensure you have a valid constitution. Use SDD enforcement to validate: ```bash -# Auto-generate from repository analysis (recommended for brownfield) -specfact spec sdd constitution bootstrap --repo . - -# Validate completeness -specfact spec sdd constitution validate - -# Or enrich existing minimal constitution -specfact spec sdd constitution enrich --repo . +# specfact spec sdd constitution commands are removed; use specfact govern enforce sdd [BUNDLE] for SDD enforcement +specfact govern enforce sdd ``` **Note**: The `sync bridge --adapter speckit` command will detect if the constitution is missing or minimal and suggest bootstrap automatically. @@ -340,10 +333,10 @@ specfact code repro --verbose ```bash # Standard interactive mode -specfact project plan init --interactive +specfact project snapshot --interactive # CoPilot mode (enhanced prompts) -specfact --mode copilot plan init --interactive +specfact --mode copilot project snapshot --interactive ``` **With CoPilot (IDE Integration):** @@ -380,22 +373,11 @@ What are the release objectives? (comma-separated) #### 2. Add Features and Stories ```bash -# Add feature -specfact project 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 project 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" +# Add feature (via project snapshot with feature spec) +specfact project snapshot --bundle + +# Use project devops-flow to enrich features through the develop stage +specfact project devops-flow --stage develop --bundle ``` #### 3. Define Protocol @@ -605,14 +587,7 @@ In a shared repository: ```bash # Create shared plan -specfact project plan init --interactive - -# Add common features -specfact project plan add-feature \ - --key FEATURE-COMMON-001 \ - --title "API Standards" \ - --outcomes "Consistent REST patterns" \ - --outcomes "Standardized error responses" +specfact project snapshot --interactive ``` #### 2. Distribute to Services @@ -629,10 +604,8 @@ cp ../shared-contracts/plan.bundle.yaml contracts/shared/ ```bash # In each service -specfact project plan compare \ - --manual contracts/shared/plan.bundle.yaml \ - --auto contracts/service/plan.bundle.yaml \ - --output-format markdown +specfact project regenerate --bundle +specfact project health-check ``` #### 4. Enforce Consistency @@ -643,7 +616,7 @@ specfact code repro setup # Add to CI specfact code repro -specfact project plan compare --manual contracts/shared/plan.bundle.yaml --auto . +specfact project regenerate ``` ### Expected Benefits diff --git a/docs/guides/using-module-security-and-extensions.md b/docs/guides/using-module-security-and-extensions.md index 5f32844c..370b7140 100644 --- a/docs/guides/using-module-security-and-extensions.md +++ b/docs/guides/using-module-security-and-extensions.md @@ -90,7 +90,7 @@ Several commands already read or write extension data on `ProjectBundle` (and it specfact project health-check --bundle my-bundle ``` -Any command that loads a bundle (e.g. `specfact project plan ...`, `specfact project 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. +Any command that loads a bundle (e.g. `specfact project sync ...`, `specfact project health-check ...`, `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: diff --git a/docs/guides/ux-features.md b/docs/guides/ux-features.md index 33898e2d..86d50959 100644 --- a/docs/guides/ux-features.md +++ b/docs/guides/ux-features.md @@ -60,15 +60,14 @@ The following options are hidden by default across commands: - `--interval` - Watch mode interval tuning - `--confidence` - Feature detection threshold -**Plan Commands:** +**Project 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 +- `--last` - Show last N items - `--name` - Exact bundle name matching - `--id` - Content hash ID matching @@ -79,7 +78,7 @@ The following options are hidden by default across commands: **Other Commands:** - `repro --budget` - Time budget configuration -- `generate contracts-prompt --output` - Custom output path +- (Note: `generate contracts-prompt` is removed; use your AI IDE skill `/specfact.07-contracts` for contract enhancement workflows) - `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. @@ -157,7 +156,7 @@ $ specfact code analyze --bundle missing-bundle ✗ Error: Bundle 'missing-bundle' not found 💡 Suggested fixes: - • specfact project plan select # Select an active plan bundle + • specfact project health-check # Check available bundles • specfact code import missing-bundle # Create a new bundle ``` diff --git a/docs/guides/workflows.md b/docs/guides/workflows.md index c30629e2..ac419ed1 100644 --- a/docs/guides/workflows.md +++ b/docs/guides/workflows.md @@ -40,13 +40,13 @@ specfact code import api-module --repo . --entry-point src/api ```bash # Review bundle to understand extracted specs -specfact project plan review legacy-api +specfact project devops-flow --stage develop --bundle legacy-api -# Or get structured findings for analysis -specfact project plan review legacy-api --list-findings --findings-format json +# Or check project health for structured findings +specfact project health-check ``` -**Note**: Use CLI commands to interact with bundles. The bundle structure (`.specfact/projects//`) is managed by SpecFact CLI - use commands like `plan review`, `plan add-feature`, `plan update-feature` to modify bundles, not direct file editing. +**Note**: Use CLI commands to interact with bundles. The bundle structure (`.specfact/projects//`) is managed by SpecFact CLI - use commands like `project devops-flow`, `project health-check`, `project snapshot` to manage bundles, not direct file editing. ### Step 3: Add Contracts Incrementally @@ -79,7 +79,7 @@ specfact code import integrations-module --repo . --entry-point src/integrations - **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 project plan compare` to compare different bundles. +**Note:** When using `--entry-point`, each analysis creates a separate project bundle. Use `specfact project devops-flow --stage plan --action compare` to compare different bundles. --- @@ -333,7 +333,7 @@ Compare manual plans vs auto-derived plans to detect deviations. ### Quick Comparison ```bash -specfact project plan compare --bundle legacy-api +specfact project devops-flow --stage plan --action compare --bundle legacy-api ``` **What it does**: @@ -351,7 +351,7 @@ specfact project plan compare --bundle legacy-api ### Detailed Comparison ```bash -specfact project plan compare \ +specfact project devops-flow --stage plan --action compare \ --manual .specfact/projects/manual-plan \ --auto .specfact/projects/auto-derived \ --out comparison-report.md @@ -374,7 +374,7 @@ specfact project plan compare \ ### Code vs Plan Comparison ```bash -specfact project plan compare --bundle legacy-api --code-vs-plan +specfact project devops-flow --stage plan --action compare --bundle legacy-api --code-vs-plan ``` **What it does**: @@ -402,7 +402,7 @@ Typical workflow for daily development. specfact code repro --verbose # Compare plans -specfact project plan compare --bundle legacy-api +specfact project devops-flow --stage plan --action compare --bundle legacy-api ``` **What it does**: @@ -431,7 +431,7 @@ specfact project sync repository --repo . --watch --interval 5 specfact code repro # Compare plans -specfact project plan compare --bundle legacy-api +specfact project devops-flow --stage plan --action compare --bundle legacy-api ``` **What it does**: @@ -464,7 +464,7 @@ Complete workflow for migrating from Spec-Kit or OpenSpec. #### Step 1: Preview ```bash -specfact project import from-bridge --adapter speckit --repo . --dry-run +specfact code import from-bridge --adapter speckit --repo . --dry-run ``` **What it does**: @@ -476,7 +476,7 @@ specfact project import from-bridge --adapter speckit --repo . --dry-run #### Step 2: Execute ```bash -specfact project import from-bridge --adapter speckit --repo . --write +specfact code import from-bridge --adapter speckit --repo . --write ``` **What it does**: diff --git a/docs/index.md b/docs/index.md index 02a5477e..990959d2 100644 --- a/docs/index.md +++ b/docs/index.md @@ -36,6 +36,7 @@ Most tools help **either** coders **or** agile teams. SpecFact does both: Recommended command entrypoints: - `specfact backlog ceremony standup ...` - `specfact backlog ceremony refinement ...` +- `specfact backlog verify-readiness --bundle ` **Try it now** @@ -62,7 +63,7 @@ specfact backlog daily ado --ado-org --ado-project "" --state any specfact backlog refine ado --ado-org --ado-project "" --id --preview # 3) Validate drift before implementation -specfact backlog policy validate --group-by-item +specfact backlog verify-readiness --bundle ``` GitHub variant: @@ -176,7 +177,7 @@ Module lifecycle note: use `specfact module` (`init`, `install`, `list`, `show`, - **[Command Chains](guides/command-chains.md)** ⭐ **NEW** - Complete workflows from start to finish - **[Agile/Scrum Workflows](guides/agile-scrum-workflows.md)** - Persona-based collaboration for teams -- **[Policy Engine Commands](guides/policy-engine-commands.md)** - Scaffold policy config templates and run `backlog policy init|validate|suggest` +- **[Policy Engine Commands](guides/policy-engine-commands.md)** - Run backlog readiness and ceremony workflows - **[DevOps Backlog Integration](guides/devops-adapter-integration.md)** 🆕 **NEW FEATURE** - Integrate SpecFact into agile DevOps workflows with bidirectional backlog sync - **[Backlog Refinement](guides/backlog-refinement.md)** 🆕 **NEW FEATURE** - AI-assisted template-driven backlog refinement for standardizing work items - **[Backlog Dependency Analysis](guides/backlog-dependency-analysis.md)** - Analyze critical path, cycles, orphans, and dependency impact from backlog graph data diff --git a/docs/prompts/PROMPT_VALIDATION_CHECKLIST.md b/docs/prompts/PROMPT_VALIDATION_CHECKLIST.md index 43fa76ee..77fc3057 100644 --- a/docs/prompts/PROMPT_VALIDATION_CHECKLIST.md +++ b/docs/prompts/PROMPT_VALIDATION_CHECKLIST.md @@ -61,8 +61,8 @@ The validator checks: - [ ] **CORRECT examples present**: Prompt shows examples of what TO do (using CLI commands) - [ ] **Command examples**: Examples show actual CLI usage with correct flags - [ ] **Flag documentation**: All flags are documented with defaults and descriptions -- [ ] **Filter options documented** (for `plan select`): `--current`, `--stages`, `--last`, `--no-interactive` flags are documented with use cases and examples -- [ ] **Positional vs option arguments**: Correctly distinguishes between positional arguments and `--option` flags (e.g., `specfact project plan select 20` not `specfact project plan select --plan 20`) +- [ ] **Filter options documented** (for bundle selection): `--bundle`, `--no-interactive` flags are documented with use cases and examples +- [ ] **Positional vs option arguments**: Correctly distinguishes between positional arguments and `--option` flags - [ ] **Boolean flags documented correctly**: Boolean flags use `--flag/--no-flag` syntax, not `--flag true/false` - ❌ **WRONG**: `--draft true` or `--draft false` (Typer boolean flags don't accept values) - ✅ **CORRECT**: `--draft` (sets True) or `--no-draft` (sets False) or omit (leaves unchanged) @@ -92,7 +92,7 @@ The validator checks: - [ ] Explanation: Stories are required for promotion validation - [ ] Phase 3: CLI Artifact Creation documented - [ ] Enrichment report location specified (`.specfact/projects//reports/enrichment/`, bundle-specific, Phase 8.5) -- [ ] **Auto-enrichment workflow** (for `plan review`): +- [ ] **Auto-enrichment workflow** (for `project devops-flow --stage develop`): - [ ] `--auto-enrich` flag documented with when to use it - [ ] LLM reasoning guidance for detecting when enrichment is needed - [ ] Post-enrichment analysis steps documented @@ -102,7 +102,7 @@ The validator checks: - [ ] Examples of enrichment output and refinement process - [ ] **Generic criteria detection**: Instructions to identify and replace generic patterns ("interact with the system", "works correctly") - [ ] **Code-specific criteria generation**: Instructions to research codebase and create testable criteria with method names, parameters, return values -- [ ] **Feature deduplication** (for `sync`, `plan review`, `import from-code`): +- [ ] **Feature deduplication** (for `sync`, `project devops-flow --stage develop`, `import from-code`): - [ ] **Automated deduplication documented**: CLI automatically deduplicates features using normalized key matching - [ ] **Deduplication scope explained**: - [ ] Exact normalized key matches (e.g., `FEATURE-001` vs `001_FEATURE_NAME`) @@ -112,15 +112,15 @@ The validator checks: - [ ] Review feature titles and descriptions for semantic similarity - [ ] Identify features that represent the same functionality with different names - [ ] Suggest consolidation when multiple features cover the same code/functionality - - [ ] Use `specfact project plan update-feature` or `specfact project plan add-feature` to consolidate + - [ ] Use `specfact project devops-flow --stage develop` to consolidate - [ ] **Deduplication output**: CLI shows "✓ Removed N duplicate features" - LLM should acknowledge this - [ ] **Post-deduplication review**: LLM should review remaining features for semantic duplicates - [ ] **Execution steps**: Clear, sequential steps - [ ] **Error handling**: Instructions for handling errors - [ ] **Validation**: CLI validation steps documented -- [ ] **Coverage validation** (for `plan promote`): Documentation of coverage status checks (critical vs important categories) +- [ ] **Coverage validation** (for `project devops-flow --stage review`): Documentation of coverage status checks (critical vs important categories) - [ ] **Copilot-friendly formatting** (if applicable): Instructions for formatting output as Markdown tables for better readability -- [ ] **Interactive workflows** (if applicable): Support for "details" requests and other interactive options (e.g., "20 details" for plan selection) +- [ ] **Interactive workflows** (if applicable): Support for "details" requests and other interactive options (e.g., bundle details for bundle selection) ### 5. Consistency @@ -189,7 +189,7 @@ For each prompt, test the following scenarios: 1. Invoke `/specfact.03-review legacy-api` with a plan bundle 2. Verify the LLM: - - ✅ Executes `specfact project plan review` CLI command + - ✅ Executes `specfact project devops-flow --stage develop --bundle ` CLI command - ✅ Parses CLI output for ambiguity findings - ✅ Waits for user input when questions are asked - ✅ Does NOT create clarifications directly in YAML @@ -202,57 +202,50 @@ For each prompt, test the following scenarios: 2. Verify the LLM: - ✅ **Detects need for enrichment**: Recognizes vague patterns ("is implemented", "System MUST Helper class", generic tasks) - ✅ **Suggests or uses `--auto-enrich`**: Either suggests using `--auto-enrich` flag or automatically uses it based on plan quality indicators - - ✅ **Executes enrichment**: Runs `specfact project plan review --auto-enrich` + - ✅ **Executes enrichment**: Runs `specfact project devops-flow --stage develop --bundle --auto-enrich` - ✅ **Parses enrichment results**: Captures enrichment summary (features updated, stories updated, acceptance criteria enhanced, etc.) - ✅ **Analyzes enrichment quality**: Uses LLM reasoning to review what was enhanced - ✅ **Identifies generic patterns**: Finds placeholder text like "interact with the system" that needs refinement - ✅ **Proposes specific refinements**: Suggests domain-specific improvements using CLI commands - - ✅ **Executes refinements**: Uses `specfact project plan update-feature --bundle ` to refine generic improvements - - ✅ **Re-runs review**: Executes `specfact project plan review` again to verify improvements + - ✅ **Executes refinements**: Uses `specfact project devops-flow --stage develop --bundle ` to refine generic improvements + - ✅ **Re-runs review**: Executes `specfact project devops-flow --stage develop` again to verify improvements 3. Test with explicit enrichment request (e.g., "enrich the plan"): - ✅ Uses `--auto-enrich` flag immediately - ✅ Reviews enrichment results - ✅ Suggests further improvements if needed -#### Scenario 5: Plan Selection Workflow (for plan-select) +#### Scenario 5: Bundle Selection Workflow -1. Invoke `/specfact.02-plan select` (or use CLI: `specfact project plan select`) +1. Invoke `specfact project health-check` (or use CLI to list bundles) 2. Verify the LLM: - - ✅ Executes `specfact project plan select` CLI command - - ✅ Formats plan list as copilot-friendly Markdown table (not Rich table) - - ✅ Provides selection options (number, "number details", "q" to quit) - - ✅ Waits for user response with `[WAIT FOR USER RESPONSE - DO NOT CONTINUE]` -3. Request plan details (e.g., "20 details"): - - ✅ Loads plan bundle YAML file + - ✅ Executes `specfact project health-check` CLI command + - ✅ Formats bundle list as copilot-friendly Markdown table (not Rich table) + - ✅ Provides selection options and waits for user response with `[WAIT FOR USER RESPONSE - DO NOT CONTINUE]` +3. Request bundle details: + - ✅ Loads bundle information via CLI - ✅ Extracts and displays detailed information (idea, themes, top features, business context) - - ✅ Asks if user wants to select the plan + - ✅ Asks if user wants to use the bundle - ✅ Waits for user confirmation -4. Select a plan (e.g., "20" or "y" after details): - - ✅ Uses **positional argument** syntax: `specfact project plan select 20` (NOT `--plan 20`) +4. Select a bundle (specify `--bundle `): + - ✅ Uses `--bundle ` parameter syntax - ✅ Confirms selection with CLI output - ✅ Does NOT create config.yaml directly -5. Test filter options: - - ✅ Uses `--current` flag to show only active plan: `specfact project plan select --current` - - ✅ Uses `--stages` flag to filter by stages: `specfact project plan select --stages draft,review` - - ✅ Uses `--last N` flag to show recent plans: `specfact project plan select --last 5` -6. Test non-interactive mode (CI/CD): - - ✅ Uses `--no-interactive` flag with `--current`: `specfact project plan select --no-interactive --current` - - ✅ Uses `--no-interactive` flag with `--last 1`: `specfact project plan select --no-interactive --last 1` - - ✅ Handles error when multiple plans match filters in non-interactive mode +5. Test non-interactive mode (CI/CD): + - ✅ Uses `--no-interactive` flag: `specfact project health-check --no-interactive` - ✅ Does NOT prompt for input when `--no-interactive` is used #### Scenario 6: Plan Promotion with Coverage Validation (for plan-promote) -1. Invoke `/specfact-plan-promote` with a plan that has missing critical categories +1. Invoke `/specfact.03-review legacy-api` to promote through review stage 2. Verify the LLM: - - ✅ Executes `specfact project plan promote --stage review --validate` CLI command + - ✅ Executes `specfact project devops-flow --stage review --bundle ` CLI command - ✅ Parses CLI output showing coverage validation errors - ✅ Shows which critical categories are Missing - - ✅ Suggests running `specfact project plan review` to resolve ambiguities + - ✅ Suggests running `specfact project devops-flow --stage develop` to resolve ambiguities - ✅ Does NOT attempt to bypass validation by creating artifacts directly - - ✅ Waits for user decision (use `--force` or run `plan review` first) + - ✅ Waits for user decision (use `--force` or run develop stage first) 3. Invoke promotion with `--force` flag: - - ✅ Uses `--force` flag correctly: `specfact project plan promote --stage review --force` + - ✅ Uses `--force` flag correctly: `specfact project devops-flow --stage review --bundle --force` - ✅ Explains that `--force` bypasses validation (not recommended) - ✅ Does NOT create plan bundle directly @@ -280,8 +273,8 @@ After testing, review: - [ ] Analyzes enrichment results with reasoning - [ ] Proposes and executes specific refinements using CLI commands - [ ] Iterates until plan quality meets standards -- [ ] **Selection workflow** (if applicable): Copilot-friendly table formatting, details option, correct CLI syntax (positional arguments), filter options (`--current`, `--stages`, `--last`), non-interactive mode (`--no-interactive`) -- [ ] **Promotion workflow** (if applicable): Coverage validation respected, suggestions to run `plan review` when categories are Missing +- [ ] **Selection workflow** (if applicable): Copilot-friendly table formatting, details option, correct CLI syntax (`--bundle`), non-interactive mode (`--no-interactive`) +- [ ] **Promotion workflow** (if applicable): Coverage validation respected, suggestions to run `project devops-flow --stage develop` when categories are Missing - [ ] **Error handling**: Errors handled gracefully without assumptions ## Common Issues to Watch For @@ -336,14 +329,14 @@ After testing, review: ### ❌ Wrong Argument Format (Positional vs Option) -**Symptom**: LLM uses `--option` flag when command expects positional argument (e.g., `specfact project plan select --plan 20` instead of `specfact project plan select 20`) +**Symptom**: LLM uses incorrect argument format when command expects a specific syntax (e.g., positional vs named arguments) **Fix**: - Verify actual CLI command signature (use `specfact --help`) - Update prompt to explicitly state positional vs option arguments - Add examples showing correct syntax -- Add warning about common mistakes (e.g., "NOT `specfact project plan select --plan 20` (this will fail)") +- Add warning about common mistakes ### ❌ Wrong Boolean Flag Usage @@ -365,7 +358,7 @@ After testing, review: ### ❌ Missing Coverage Validation -**Symptom**: LLM promotes plans without checking coverage status, or doesn't suggest running `plan review` when categories are Missing +**Symptom**: LLM promotes plans without checking coverage status, or doesn't suggest running `project devops-flow --stage develop` when categories are Missing **Fix**: @@ -421,7 +414,7 @@ The following prompts are available for SpecFact CLI commands: - `specfact.04-sdd.md` - Create SDD manifest (new, based on `plan harden`) - `specfact.05-enforce.md` - SDD enforcement (replaces `specfact-enforce.md`) - `specfact.06-sync.md` - Sync operations (replaces `specfact-sync.md`) -- `specfact.07-contracts.md` - Contract enhancement workflow: analyze → generate prompts → apply contracts sequentially (new, based on `analyze contracts`, `generate contracts-prompt`, `generate contracts-apply`) +- `specfact.07-contracts.md` - Contract enhancement workflow: analyze → generate prompts → apply contracts sequentially (use `specfact govern enforce sdd [BUNDLE]` for SDD enforcement; contract prompt generation is handled via this IDE skill) ### Advanced Commands (No Numbering) @@ -444,7 +437,7 @@ The following prompts are available for SpecFact CLI commands: - Added `specfact.07-contracts.md` to available prompts list - New contract enhancement workflow prompt for sequential contract application -- Workflow: analyze contracts → generate prompts → apply contracts with careful review +- Workflow: analyze contracts → apply contracts with careful review (via IDE skill; use `specfact govern enforce sdd [BUNDLE]` for SDD enforcement) ### Version 1.10 (2025-01-XX) diff --git a/docs/prompts/README.md b/docs/prompts/README.md index fe7f8315..0b8f162c 100644 --- a/docs/prompts/README.md +++ b/docs/prompts/README.md @@ -50,7 +50,7 @@ SpecFact CLI provides slash commands that work with AI-assisted IDEs (Cursor, VS **Purpose**: Plan management (init, add-feature, add-story, update-idea, update-feature, update-story) -**Equivalent CLI**: `specfact project plan init/add-feature/add-story/update-idea/update-feature/update-story` +**Equivalent CLI**: `specfact project snapshot --bundle ` / `specfact project health-check` (plan editing subcommands removed) **Example**: @@ -67,7 +67,7 @@ SpecFact CLI provides slash commands that work with AI-assisted IDEs (Cursor, VS **Purpose**: Review plan and promote -**Equivalent CLI**: `specfact project plan review` +**Equivalent CLI**: `specfact project devops-flow --stage develop --bundle ` or `specfact project health-check --bundle ` **Example**: @@ -131,7 +131,7 @@ SpecFact CLI provides slash commands that work with AI-assisted IDEs (Cursor, VS **Purpose**: Contract management (analyze, generate prompts, apply contracts sequentially) -**Equivalent CLI**: `specfact spec generate contracts-prompt` +**Equivalent CLI**: `specfact govern enforce sdd [BUNDLE]` (contract enhancement workflows are handled via this slash command) **Example**: @@ -149,7 +149,7 @@ SpecFact CLI provides slash commands that work with AI-assisted IDEs (Cursor, VS **Purpose**: Compare plans -**Equivalent CLI**: `specfact project plan compare` +**Equivalent CLI**: `specfact project regenerate --bundle ` **Example**: diff --git a/docs/reference/README.md b/docs/reference/README.md index 41d965d4..d34cf38a 100644 --- a/docs/reference/README.md +++ b/docs/reference/README.md @@ -30,10 +30,10 @@ Complete technical reference for SpecFact CLI. ### Commands -- `specfact project import from-bridge --adapter speckit` - Import from external tools via bridge adapter +- `specfact code import from-bridge --adapter speckit` - Import from external tools via bridge adapter - `specfact code import ` - Reverse-engineer plans from code -- `specfact project plan init ` - Initialize new development plan -- `specfact project plan compare` - Compare manual vs auto plans +- `specfact project snapshot --bundle ` - Save current backlog graph as baseline snapshot +- `specfact project devops-flow --stage ` - Run integrated DevOps stage actions - `specfact govern enforce stage` - Configure quality gates - `specfact code repro` - Run full validation suite - `specfact project sync bridge --adapter --bundle ` - Sync with external tools via bridge adapter diff --git a/docs/reference/command-syntax-policy.md b/docs/reference/command-syntax-policy.md index 8e9e9659..a1e1dd19 100644 --- a/docs/reference/command-syntax-policy.md +++ b/docs/reference/command-syntax-policy.md @@ -16,14 +16,14 @@ 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 project plan init BUNDLE` - - `specfact project plan review [BUNDLE]` + - `specfact project snapshot --bundle ` + - `specfact project devops-flow --stage ` - `--bundle` option: - - Supported by many plan mutation commands (for example `plan add-feature`, `plan add-story`, `plan update-feature`) + - Supported by many spec and govern commands (for example `spec validate`, `spec generate-tests`, `govern enforce sdd`) - Not universally supported across all commands ## IDE Init Syntax @@ -44,8 +44,9 @@ Before merging command docs updates: ```bash hatch run specfact code import --help -hatch run specfact project plan init --help -hatch run specfact project plan review --help -hatch run specfact project plan add-feature --help +hatch run specfact project snapshot --help +hatch run specfact project devops-flow --help +hatch run specfact govern enforce --help +hatch run specfact spec validate --help ``` diff --git a/docs/reference/commands.md b/docs/reference/commands.md index 3ed06c76..593771b3 100644 --- a/docs/reference/commands.md +++ b/docs/reference/commands.md @@ -38,31 +38,29 @@ After bundle install, command groups are mounted by category: | Bundle ID | Group | Main command families | |---|---|---| -| `nold-ai/specfact-project` | `project` | `project ...`, `project plan ...`, `project import ...`, `project sync ...`, `project migrate ...` | -| `nold-ai/specfact-backlog` | `backlog` | `backlog ...`, `backlog policy ...`, `backlog auth ...` | -| `nold-ai/specfact-codebase` | `code` | `code analyze ...`, `code drift ...`, `code validate ...`, `code repro ...` | -| `nold-ai/specfact-spec` | `spec` | `spec contract ...`, `spec api ...`, `spec sdd ...`, `spec generate ...` | -| `nold-ai/specfact-govern` | `govern` | `govern enforce ...`, `govern patch ...` | +| `nold-ai/specfact-project` | `project` | `project link-backlog`, `project health-check`, `project devops-flow`, `project snapshot`, `project regenerate`, `project export-roadmap`, `project import`, `project export`, `project sync` | +| `nold-ai/specfact-backlog` | `backlog` | `backlog ceremony`, `backlog refine`, `backlog daily`, `backlog sync`, `backlog auth`, `backlog analyze-deps`, `backlog verify-readiness`, `backlog delta`, `backlog add` | +| `nold-ai/specfact-codebase` | `code` | `code analyze`, `code drift`, `code validate`, `code repro`, `code import`, `code review` | +| `nold-ai/specfact-spec` | `spec` | `spec validate`, `spec backward-compat`, `spec generate-tests`, `spec mock` | +| `nold-ai/specfact-govern` | `govern` | `govern enforce`, `govern patch` | ## Migration: Removed Flat Commands -Flat compatibility shims were removed in this change. Use grouped commands. +Flat compatibility shims were removed in `0.40.0`. Use grouped commands. | Removed | Replacement | |---|---| -| `specfact plan ...` | `specfact project plan ...` | -| `specfact import ...` | `specfact project import ...` | +| `specfact plan ...` | Removed — use `specfact project devops-flow` or `specfact project snapshot` | +| `specfact import ...` | `specfact code import ...` (codebase import) or `specfact project import ...` (persona Markdown) | | `specfact sync ...` | `specfact project sync ...` | -| `specfact migrate ...` | `specfact project migrate ...` | | `specfact backlog ...` (flat module) | `specfact backlog ...` (bundle group) | | `specfact analyze ...` | `specfact code analyze ...` | | `specfact drift ...` | `specfact code drift ...` | | `specfact validate ...` | `specfact code validate ...` | | `specfact repro ...` | `specfact code repro ...` | -| `specfact contract ...` | `specfact spec contract ...` | -| `specfact spec ...` (flat module) | `specfact spec api ...` | -| `specfact sdd ...` | `specfact spec sdd ...` | -| `specfact generate ...` | `specfact spec generate ...` | +| `specfact contract ...` | Removed — use `specfact spec validate` | +| `specfact sdd ...` | Removed — use `specfact govern enforce sdd [BUNDLE]` | +| `specfact generate ...` | Removed — no direct replacement; use AI IDE skills for prompt generation | | `specfact enforce ...` | `specfact govern enforce ...` | | `specfact patch ...` | `specfact govern patch ...` | @@ -77,7 +75,7 @@ specfact module install nold-ai/specfact-backlog # Project workflow examples specfact code import legacy-api --repo . -specfact project plan review legacy-api +specfact project snapshot --bundle legacy-api # Code workflow examples specfact code validate sidecar init legacy-api /path/to/repo @@ -86,6 +84,10 @@ specfact code repro --verbose # Backlog workflow examples specfact backlog ceremony standup --help specfact backlog ceremony refinement --help + +# Spec validation examples +specfact spec validate --bundle my-api +specfact spec generate-tests --bundle my-api --output tests/ ``` ## See Also diff --git a/docs/reference/directory-structure.md b/docs/reference/directory-structure.md index 785ccb2c..3673ddf7 100644 --- a/docs/reference/directory-structure.md +++ b/docs/reference/directory-structure.md @@ -238,20 +238,14 @@ Plan bundles version 1.1 and later include summary metadata in the `metadata.sum **Upgrading Plan Bundles:** -Use `specfact project plan upgrade` to migrate older plan bundles to the latest schema: +Use `specfact project regenerate` to re-derive project state from the current bundle: ```bash -# Upgrade active plan -specfact project plan upgrade - -# Upgrade all plans -specfact project plan upgrade --all - -# Preview upgrades -specfact project plan upgrade --dry-run +# Re-derive project state +specfact project regenerate --bundle ``` -See [`plan upgrade`](../reference/commands.md#plan-upgrade) for details. +See the [Command Reference](../reference/commands.md) for details. **Example**: @@ -424,35 +418,22 @@ specfact code import legacy-api --repo . --confidence 0.7 # - .specfact/reports/brownfield/analysis-2025-10-31T14-30-00.md (gitignored) ``` -### `specfact project plan init` (Alternative) +### Creating Project Bundles (Greenfield) -**Alternative use case**: Create new project bundles for greenfield projects. +For greenfield projects, use `code import` with your source, or create a bundle structure manually: ```bash -# Command syntax -specfact project plan init [OPTIONS] +# Analyze a new codebase and create a bundle +specfact code import --repo . # 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 project plan compare` - -```bash -# Compare two bundles (explicit paths to bundle directories) -specfact project plan compare \ - --manual .specfact/projects/manual-plan \ - --auto .specfact/projects/auto-derived \ - --out .specfact/reports/comparison/report-*.md +├── product.yaml # Product definition +└── features/ # Features directory -# Note: Commands accept bundle directory paths, not individual files +# Snapshot current state +specfact project snapshot --bundle ``` ### `specfact project sync bridge` @@ -698,7 +679,7 @@ If you have existing artifacts in other locations: # Migration mkdir -p .specfact/projects/my-project .specfact/reports/brownfield # Convert monolithic bundle to modular bundle structure -# (Use 'specfact project plan upgrade' or manual conversion) +# (Use 'specfact project regenerate' or manual conversion) mv reports/analysis.md .specfact/reports/brownfield/ ``` @@ -750,10 +731,9 @@ specfact code import legacy-api \ --repo src/legacy-api \ --confidence 0.7 -# Step 2: Compare legacy vs modernized (use bundle directories, not files) -specfact project plan compare \ - --manual .specfact/projects/legacy-api \ - --auto .specfact/projects/modernized-api +# Step 2: Snapshot and regenerate project state +specfact project snapshot --bundle legacy-api +specfact project regenerate --bundle legacy-api # Step 3: Analyze specific legacy component specfact code import legacy-payment \ diff --git a/docs/reference/feature-keys.md b/docs/reference/feature-keys.md index 382ec6c7..15885f4b 100644 --- a/docs/reference/feature-keys.md +++ b/docs/reference/feature-keys.md @@ -36,12 +36,8 @@ specfact code import --key-format classname specfact code import --key-format sequential ``` -**Manual creation**: When creating plans interactively, use `FEATURE-001` format: - -```bash -specfact project plan init -# Enter feature key: FEATURE-001 -``` +**Manual creation**: When creating project state interactively, use `FEATURE-001` format and +manage it via `project snapshot` or `project devops-flow`. ### 3. Underscore Format (Legacy) @@ -83,11 +79,7 @@ normalize_feature_key("FEATURE-001") ### Plan Comparison -The `plan compare` command automatically normalizes keys: - -```bash -specfact project plan compare --manual main.bundle.yaml --auto auto-derived.yaml -``` +Key normalization is applied automatically when comparing or merging bundle data. **Behavior**: Features with different key formats but the same normalized key are matched correctly. @@ -119,13 +111,12 @@ features_seq = convert_feature_keys(features, target_format="sequential", start_ features_class = convert_feature_keys(features, target_format="classname") ``` -### Command-Line (Future) +### Command-Line -A `plan normalize` command may be added in the future to convert existing plans: +Use `project regenerate` to re-derive project state from the current bundle: ```bash -# (Future) Convert plan to sequential format -specfact project plan normalize --from main.bundle.yaml --to main-sequential.yaml --output-format sequential +specfact project regenerate --bundle ``` ## Best Practices @@ -156,13 +147,7 @@ specfact project plan normalize --from main.bundle.yaml --to main-sequential.yam ### 3. Use Sequential for Manual Plans -When creating plans manually or interactively: - -```bash -specfact project plan init -# Enter feature key: FEATURE-001 # ← Use sequential format -# Enter feature title: User Authentication -``` +When creating project bundles manually, use `FEATURE-001` sequential format for feature keys. **Why**: Sequential format is easier to reference and understand in documentation. diff --git a/openspec/changes/docs-03-command-syntax-parity/TDD_EVIDENCE.md b/openspec/changes/docs-03-command-syntax-parity/TDD_EVIDENCE.md new file mode 100644 index 00000000..0c93aa55 --- /dev/null +++ b/openspec/changes/docs-03-command-syntax-parity/TDD_EVIDENCE.md @@ -0,0 +1,52 @@ +# TDD Evidence: docs-03-command-syntax-parity + +## Pre-Implementation Failing Run + +**Timestamp**: 2026-03-18 + +**Command**: +``` +cd /home/dom/git/nold-ai/specfact-cli-worktrees/feature/docs-03-command-syntax-parity +hatch test -- tests/unit/docs/test_release_docs_parity.py -v -k "removed or current" +``` + +**Result**: 9 FAILED, 3 PASSED + +**Failing tests**: + +- `test_removed_project_plan_syntax_absent_from_authored_docs` — 'specfact project plan' still present in authored docs +- `test_removed_project_import_from_bridge_syntax_absent_from_authored_docs` — 'project import from-bridge' still present +- `test_removed_backlog_policy_syntax_absent_from_authored_docs` — 'backlog policy' still present +- `test_removed_spec_contract_syntax_absent_from_authored_docs` — 'spec contract' still present +- `test_removed_spec_api_syntax_absent_from_authored_docs` — 'spec api' still present +- `test_removed_spec_sdd_syntax_absent_from_authored_docs` — 'spec sdd' still present +- `test_removed_spec_generate_syntax_absent_from_authored_docs` — 'spec generate ' still present +- `test_current_spec_commands_documented_in_commands_reference` — 'spec validate' missing from commands.md (stale bundle mapping table still shows old spec commands) +- `test_current_backlog_subcommands_documented_in_commands_reference` — 'backlog refine' missing from commands reference + +## Post-Implementation Passing Run + +**Timestamp**: 2026-03-18 + +**Command**: +``` +cd /home/dom/git/nold-ai/specfact-cli-worktrees/feature/docs-03-command-syntax-parity +hatch test -- tests/unit/docs/test_release_docs_parity.py -v +``` + +**Result**: 21 PASSED (all) + +All new parity tests pass: +- `test_removed_project_plan_syntax_absent_from_authored_docs` ✓ +- `test_removed_project_import_from_bridge_syntax_absent_from_authored_docs` ✓ +- `test_removed_backlog_policy_syntax_absent_from_authored_docs` ✓ +- `test_removed_spec_contract_syntax_absent_from_authored_docs` ✓ +- `test_removed_spec_api_syntax_absent_from_authored_docs` ✓ +- `test_removed_spec_sdd_syntax_absent_from_authored_docs` ✓ +- `test_removed_spec_generate_syntax_absent_from_authored_docs` ✓ +- `test_current_code_import_from_bridge_documented` ✓ +- `test_current_spec_commands_documented_in_commands_reference` ✓ +- `test_current_govern_enforce_sdd_documented` ✓ +- `test_current_backlog_subcommands_documented_in_commands_reference` ✓ + +All 10 pre-existing tests also pass. diff --git a/pyproject.toml b/pyproject.toml index bb2da73c..ba325ef2 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "hatchling.build" [project] name = "specfact-cli" -version = "0.42.1" +version = "0.42.2" description = "The swiss knife CLI for agile DevOps teams. Keep backlog, specs, tests, and code in sync with validation and contract enforcement for new projects and long-lived codebases." readme = "README.md" requires-python = ">=3.11" diff --git a/setup.py b/setup.py index 792b502a..66a38ea1 100644 --- a/setup.py +++ b/setup.py @@ -7,7 +7,7 @@ if __name__ == "__main__": _setup = setup( name="specfact-cli", - version="0.42.1", + version="0.42.2", description=( "The swiss knife CLI for agile DevOps teams. Keep backlog, specs, tests, and code in sync with " "validation and contract enforcement for new projects and long-lived codebases." diff --git a/src/specfact_cli/__init__.py b/src/specfact_cli/__init__.py index 636daf7e..16ecd148 100644 --- a/src/specfact_cli/__init__.py +++ b/src/specfact_cli/__init__.py @@ -42,6 +42,6 @@ def _bootstrap_bundle_paths() -> None: _bootstrap_bundle_paths() -__version__ = "0.42.1" +__version__ = "0.42.2" __all__ = ["__version__"] diff --git a/tests/unit/docs/test_release_docs_parity.py b/tests/unit/docs/test_release_docs_parity.py index a5b6129a..f16fdf1c 100644 --- a/tests/unit/docs/test_release_docs_parity.py +++ b/tests/unit/docs/test_release_docs_parity.py @@ -89,3 +89,119 @@ def test_bundle_focused_pages_use_handoff_note_instead_of_future_migration_langu assert "canonical modules docs site" in github_adapter assert "planned to migrate to `specfact-cli-modules`" not in backlog_refinement assert "planned to migrate to `specfact-cli-modules`" not in github_adapter + + +# --------------------------------------------------------------------------- +# docs-03-command-syntax-parity: removed syntax families must be absent +# --------------------------------------------------------------------------- + +_AUTHORED_DOC_ROOTS = ["README.md", "docs"] + + +def _scan_authored_docs(pattern: str) -> list[tuple[str, int, str]]: + """Return list of (relative_path, line_number, line_text) for pattern hits. + + Lines that are clearly labeled as historical/removed context are excluded: + - Code-block comment lines (stripped line starts with ``#``) + - Blockquote lines that reference a removed command (stripped starts with ``>``) + - Any line where the pattern co-occurs with the word "removed" or "(removed)" + """ + hits: list[tuple[str, int, str]] = [] + repo_root = Path(__file__).resolve().parents[3] + sources: list[Path] = [repo_root / "README.md"] + docs_dir = repo_root / "docs" + for p in docs_dir.rglob("*.md"): + if "_site" not in p.parts and "vendor" not in p.parts: + sources.append(p) + for src in sources: + if not src.exists(): + continue + for lineno, line in enumerate(src.read_text(encoding="utf-8").splitlines(), 1): + if pattern not in line: + continue + stripped = line.strip() + # Skip comment lines in code blocks + if stripped.startswith("#"): + continue + # Skip blockquote lines (historical/migration notes) + if stripped.startswith(">"): + continue + # Skip lines that explicitly label the pattern as removed + lower = stripped.lower() + if "removed" in lower or "(removed)" in lower or "is removed" in lower: + continue + hits.append((str(src.relative_to(repo_root)), lineno, stripped)) + return hits + + +def _fmt_hits(hits: list[tuple[str, int, str]]) -> str: + return "\n".join(f" {p}:{n} {line}" for p, n, line in hits) + + +def test_removed_project_plan_syntax_absent_from_authored_docs() -> None: + """specfact project plan is not a shipped command; must not appear as current syntax.""" + hits = _scan_authored_docs("specfact project plan") + assert not hits, f"Removed syntax 'specfact project plan' still present:\n{_fmt_hits(hits)}" + + +def test_removed_project_import_from_bridge_syntax_absent_from_authored_docs() -> None: + """project import from-bridge moved to code import from-bridge; old path must not appear.""" + hits = _scan_authored_docs("project import from-bridge") + assert not hits, f"Removed syntax 'project import from-bridge' still present:\n{_fmt_hits(hits)}" + + +def test_removed_backlog_policy_syntax_absent_from_authored_docs() -> None: + """backlog policy is not a shipped subcommand; must not appear as current syntax.""" + hits = _scan_authored_docs("backlog policy") + assert not hits, f"Removed syntax 'backlog policy' still present:\n{_fmt_hits(hits)}" + + +def test_removed_spec_contract_syntax_absent_from_authored_docs() -> None: + hits = _scan_authored_docs("spec contract") + assert not hits, f"Removed syntax 'spec contract' still present:\n{_fmt_hits(hits)}" + + +def test_removed_spec_api_syntax_absent_from_authored_docs() -> None: + # Search for "specfact spec api" to avoid false positives from --spec api/openapi.yaml paths + hits = _scan_authored_docs("specfact spec api") + assert not hits, f"Removed syntax 'specfact spec api' still present:\n{_fmt_hits(hits)}" + + +def test_removed_spec_sdd_syntax_absent_from_authored_docs() -> None: + hits = _scan_authored_docs("spec sdd") + assert not hits, f"Removed syntax 'spec sdd' still present:\n{_fmt_hits(hits)}" + + +def test_removed_spec_generate_syntax_absent_from_authored_docs() -> None: + # "spec generate " (space) catches stale subcommands like fix-prompt, test-prompt, + # contracts-prompt etc. without matching the valid "spec generate-tests" (hyphen). + hits = _scan_authored_docs("spec generate ") + assert not hits, f"Removed syntax 'spec generate ' still present:\n{_fmt_hits(hits)}" + + +# --------------------------------------------------------------------------- +# docs-03-command-syntax-parity: current command families must be present +# --------------------------------------------------------------------------- + + +def test_current_code_import_from_bridge_documented() -> None: + """Bridge import moved to code import from-bridge; at least one authored doc must show this.""" + hits = _scan_authored_docs("code import") + assert hits, "Current syntax 'code import' must appear in at least one authored doc" + + +def test_current_spec_commands_documented_in_commands_reference() -> None: + commands_doc = _repo_file("docs/reference/commands.md").read_text(encoding="utf-8") + for cmd in ("spec validate", "spec backward-compat", "spec generate-tests", "spec mock"): + assert cmd in commands_doc, f"Current command '{cmd}' missing from docs/reference/commands.md" + + +def test_current_govern_enforce_sdd_documented() -> None: + commands_doc = _repo_file("docs/reference/commands.md").read_text(encoding="utf-8") + assert "govern enforce" in commands_doc, "'govern enforce' must appear in commands reference" + + +def test_current_backlog_subcommands_documented_in_commands_reference() -> None: + commands_doc = _repo_file("docs/reference/commands.md").read_text(encoding="utf-8") + for sub in ("backlog ceremony", "backlog refine", "backlog daily", "backlog sync"): + assert sub in commands_doc, f"Current subcommand '{sub}' missing from commands reference" From 948f194964a4ec9b9369343547e97908381f6a91 Mon Sep 17 00:00:00 2001 From: Dominikus Nold Date: Fri, 20 Mar 2026 11:30:42 +0100 Subject: [PATCH 2/2] docs: align core docs ownership and parity --- README.md | 241 +++---------- docs/LICENSE.md | 6 + docs/README.md | 202 +++-------- docs/TRADEMARKS.md | 6 + docs/architecture/component-graph.md | 6 + docs/architecture/data-flow.md | 6 + docs/architecture/discrepancies-report.md | 6 + docs/architecture/interface-contracts.md | 6 + docs/architecture/module-system.md | 6 + docs/architecture/state-machines.md | 6 + docs/contributing/github-project-gh-cli.md | 6 + docs/examples/brownfield-data-pipeline.md | 6 + .../brownfield-django-modernization.md | 6 + docs/examples/brownfield-flask-api.md | 6 + docs/examples/dogfooding-specfact-cli.md | 6 + docs/examples/integration-showcases/README.md | 6 + .../integration-showcases-quick-reference.md | 6 + .../integration-showcases-testing-guide.md | 6 + .../integration-showcases.md | 6 + docs/getting-started/README.md | 6 + .../tutorial-openspec-speckit.md | 6 + docs/guides/README.md | 6 + docs/guides/brownfield-faq.md | 6 + docs/guides/brownfield-roi.md | 6 + docs/guides/integrations-overview.md | 6 + docs/guides/migration-0.16-to-0.19.md | 6 + docs/guides/migration-cli-reorganization.md | 6 + docs/guides/specmatic-integration.md | 6 + docs/guides/workflows.md | 6 + docs/index.md | 321 ++++-------------- .../enhanced-analysis-dependencies.md | 6 + docs/openspec-opsx-migration.md | 6 + .../plans/ci-pr-orchestrator-log-artifacts.md | 6 + docs/prompts/PROMPT_VALIDATION_CHECKLIST.md | 6 + docs/prompts/README.md | 6 + docs/reference/README.md | 86 +++-- docs/reference/commands.md | 164 ++++++--- docs/reference/feature-keys.md | 6 + docs/reference/parameter-standard.md | 6 + docs/reference/specmatic.md | 6 + docs/reference/telemetry.md | 6 + docs/technical/README.md | 6 + docs/technical/code2spec-analysis-logic.md | 6 + docs/technical/dual-stack-pattern.md | 6 + docs/technical/testing.md | 6 + docs/validation-integration.md | 6 + openspec/CHANGE_ORDER.md | 1 + .../CHANGE_VALIDATION.md | 68 ++++ .../COMMAND_SYNTAX_AUDIT.md | 90 +++++ .../TDD_EVIDENCE.md | 84 +++-- .../docs-03-command-syntax-parity/design.md | 72 ++++ .../docs-03-command-syntax-parity/proposal.md | 40 +++ .../specs/cli-output/spec.md | 12 + .../specs/documentation-alignment/spec.md | 23 ++ .../docs-03-command-syntax-parity/tasks.md | 35 ++ tests/unit/docs/test_release_docs_parity.py | 13 + 56 files changed, 969 insertions(+), 729 deletions(-) create mode 100644 openspec/changes/docs-03-command-syntax-parity/CHANGE_VALIDATION.md create mode 100644 openspec/changes/docs-03-command-syntax-parity/COMMAND_SYNTAX_AUDIT.md create mode 100644 openspec/changes/docs-03-command-syntax-parity/design.md create mode 100644 openspec/changes/docs-03-command-syntax-parity/proposal.md create mode 100644 openspec/changes/docs-03-command-syntax-parity/specs/cli-output/spec.md create mode 100644 openspec/changes/docs-03-command-syntax-parity/specs/documentation-alignment/spec.md create mode 100644 openspec/changes/docs-03-command-syntax-parity/tasks.md diff --git a/README.md b/README.md index 67c2feef..865d7831 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,8 @@ - Module-specific deep docs are canonically owned by `specfact-cli-modules`. - The live modules docs site is currently published at `https://modules.specfact.io/`. -Use this repository's docs for core runtime, lifecycle, registry, trust, and architecture guidance. Use the modules docs site for bundle-specific workflow and module-authoring deep dives. +Use this repository's docs for the overall SpecFact workflow, CLI runtime lifecycle, module registry, trust model, and command-group topology. +Use the modules docs site for bundle-specific deep dives, adapter details, workflow tutorials, and module-authoring guidance. In short, module-specific deep docs are canonically owned by `specfact-cli-modules`. --- @@ -47,19 +48,14 @@ pip install -U specfact-cli ### Bootstrap and IDE Setup ```bash -# First run: install workflow bundles (required) +# First run: install official bundles specfact init --profile solo-developer -# Other first-run options +# Alternative bundle selection specfact init --install backlog,codebase specfact init --install all -# First-run bundle selection (examples) -specfact init --profile solo-developer -specfact init --install backlog,codebase -specfact init --install all - -# Configure IDE prompts/templates (interactive selector by default) +# IDE prompt/template setup specfact init ide specfact init ide --ide cursor specfact init ide --ide vscode @@ -71,19 +67,14 @@ specfact init ide --ide vscode # Analyze an existing codebase specfact code import my-project --repo . +# Snapshot current project state +specfact project snapshot --bundle my-project + # Validate external code without modifying source specfact code validate sidecar init my-project /path/to/repo specfact code validate sidecar run my-project /path/to/repo ``` -### Migration Note (Flat Commands Removed) - -As of `0.40.0`, flat root commands are removed. Use grouped commands: - -- `specfact validate ...` → `specfact code validate ...` -- `specfact plan ...` → removed; use `specfact project devops-flow` or `specfact project snapshot` -- `specfact policy ...` → removed; use `specfact backlog verify-readiness` - ### Backlog Bridge (60 seconds) SpecFact's USP is closing the drift gap between **backlog -> specs -> code**. @@ -95,19 +86,18 @@ These commands require the backlog bundle to be installed first, for example via specfact backlog init-config --force specfact backlog map-fields --provider ado --ado-org --ado-project "" -# 2) Run standup/refinement on real backlog scope -specfact backlog daily ado --ado-org --ado-project "" --state any --assignee any --limit 5 -specfact backlog refine ado --ado-org --ado-project "" --id --preview +# 2) Run ceremony workflows on real backlog scope +specfact backlog ceremony standup ado --ado-org --ado-project "" --state any --assignee any --limit 5 +specfact backlog ceremony refinement ado --ado-org --ado-project "" --id --preview -# 3) Keep backlog + spec intent aligned (avoid silent drift) +# 3) Keep backlog + spec intent aligned specfact backlog verify-readiness --bundle ``` -For GitHub, replace adapter/org/project with: -`specfact backlog daily github --repo-owner --repo-name ...` +Compatibility note: `specfact backlog daily ...` and `specfact backlog refine ...` still exist, but the preferred entrypoints are `backlog ceremony standup` and `backlog ceremony refinement`. -Deep dive: -- **[Backlog Quickstart Demo (GitHub + ADO)](docs/getting-started/tutorial-backlog-quickstart-demo.md)** +For GitHub, replace adapter/org/project with: +`specfact backlog ceremony standup github --repo-owner --repo-name --state any --assignee any --limit 5` **AI IDE quick start** @@ -118,110 +108,34 @@ Deep dive: **Next steps** -- **[Getting Started](docs/getting-started/README.md)** -- **[AI IDE Workflow](docs/guides/ai-ide-workflow.md)** -- **[Command Chains](docs/guides/command-chains.md)** +- **[Core CLI docs](docs/index.md)** +- **[Reference: command topology](docs/reference/commands.md)** +- **[Canonical modules docs site](https://modules.specfact.io/)** --- -## Proof and Expectations - -- **Typical runtime**: 2-15 minutes depending on repo size and complexity. -- **Checkpointing**: Progress is saved during analysis so you can resume safely. -- **Performance**: Optimized for large codebases with cached parsing and file hashes. - ---- - -## Why It Matters (Plain Language) - -- **Clarity**: Turn messy code into clear specs your team can trust. -- **Safety**: Catch risky changes early with validation and contract checks. -- **Sync**: Keep backlog items, specs, tests, and code aligned end to end. -- **Adoption**: Simple CLI, no platform lock-in, works offline. - ---- - -## Who It Is For - -- **Vibe coders and new builders** who want to ship fast with guardrails and confidence. -- **Legacy professionals** who want AI speed without lowering standards. -- **DevOps and engineering leaders** who need evidence and repeatable workflows. - ---- - -## How It Works (High Level) - -1. **Analyze**: Read code and extract specs, gaps, and risks. -2. **Sync**: Connect specs, backlog items, and plans in one workflow. -3. **Validate**: Enforce contracts and block regressions before production. - ---- - -## The Missing Link (Coder + DevOps Bridge) - -Most tools help **either** coders **or** agile teams. SpecFact does both: - -- **Backlog sync that is actually strong**: round-trip sync + refinement with GitHub, Azure DevOps, Jira, Linear. -- **Ceremony support teams can run**: standup, refinement, sprint planning, flow metrics (Scrum/Kanban/SAFe). -- **Policy + validation**: DoR/DoD/flow checks plus contract enforcement for production-grade stability. - -Recommended command entrypoints: -- `specfact backlog ceremony standup ...` -- `specfact backlog ceremony refinement ...` -- `specfact backlog verify-readiness --bundle ` -- `specfact backlog analyze-deps --bundle ` - -What the backlog readiness and ceremony commands do in practice: -- Turns team agreements (DoR, DoD, flow checks) into executable checks against your real backlog data. -- Shows exactly what is missing per item (for example missing acceptance criteria or definition of done). -- Run structured ceremony workflows (standup, refinement, retrospective) directly from the CLI. - -Start with: -- `specfact backlog ceremony standup --help` -- `specfact backlog verify-readiness --bundle ` -- `specfact backlog refine --help` - -**Try it now** - -- **Coders**: [AI IDE Workflow](docs/guides/ai-ide-workflow.md) -- **Agile teams**: [Agile/Scrum Workflows](docs/guides/agile-scrum-workflows.md) - ---- - -## Modules and Capabilities - -**Core runtime** - -- **Permanent commands**: `init`, `module`, `upgrade` -- **Core responsibilities**: lifecycle, registry, trust, contracts, orchestration, shared runtime utilities - -**Marketplace-installed bundles** - -- **Backlog**: Refinement, dependency analysis, sprint summaries, risk rollups. -- **Ceremony**: Standup, refinement, and planning entry points. -- **Policy**: DoR, DoD, flow, PI readiness checks. -- **Patch**: Preview, apply, and write changes safely. +## Core CLI Features -**Adapters and bridges** +The `specfact-cli` repository owns the platform-level features that every workflow bundle depends on: -- **Specs**: Spec-Kit and OpenSpec -- **Backlogs**: GitHub Issues, Azure DevOps, Jira, Linear -- **Contracts**: Specmatic, OpenAPI +- `specfact init` for first-run bootstrap and IDE setup. +- `specfact module` for install/list/show/search/enable/disable/uninstall/upgrade lifecycle flows. +- `specfact upgrade` for CLI upgrades. +- Runtime contracts, registry bootstrapping, trust checks, logging, and shared orchestration. +- The grouped command surface that mounts installed bundle families under `project`, `backlog`, `code`, `spec`, and `govern`. -For technical architecture details (module lifecycle, registry internals, adapters, and implementation status), use: +## Official Modules Integration -- [Architecture Reference](docs/reference/architecture.md) -- [Architecture Docs Index](docs/architecture/README.md) -- [Architecture Implementation Status](docs/architecture/implementation-status.md) +Official workflow behavior now ships from `nold-ai/specfact-cli-modules`. +The core CLI discovers those bundle packages, mounts their command groups, and enforces compatibility, trust, and lifecycle rules. -### Official Marketplace Bundles +Installed official bundles expose the current grouped surfaces: -SpecFact ships official bundle packages via the dedicated marketplace registry repository -`nold-ai/specfact-cli-modules`. - -This core docs set remains the canonical docs entry point and release-line overview for marketplace concepts. -Bundle-specific deep docs are canonically owned by `specfact-cli-modules` and are currently published at: -`https://modules.specfact.io/`. +- `specfact project ...` +- `specfact backlog ...` +- `specfact code ...` +- `specfact spec ...` +- `specfact govern ...` Install examples: @@ -240,16 +154,17 @@ specfact module init --scope project specfact module init ``` -Official bundles are verified as `official` tier (`nold-ai` publisher). Some bundles -auto-install dependencies: +Use this repo's docs for the current CLI/runtime release branch and the overall process of how official modules plug into the core platform. +Use `https://modules.specfact.io/` for the in-depth backlog, project, spec, govern, adapter, and module-authoring guides. -- `nold-ai/specfact-spec` pulls `nold-ai/specfact-project` -- `nold-ai/specfact-govern` pulls `nold-ai/specfact-project` +--- -Use this repo's docs for the current CLI/runtime release branch and for marketplace lifecycle overview content. -Use the modules docs site for bundle-specific deep guidance so bundle-only changes can ship without rebuilding the core docs release branch. +## How It Works (High Level) ---- +1. **Bootstrap**: install the CLI and initialize the official bundles you need. +2. **Analyze or sync**: import code, connect backlog systems, or sync external artifacts into project bundles. +3. **Validate**: run spec, governance, and sidecar validation flows before implementation or release. +4. **Iterate safely**: use module-provided workflows while the core runtime keeps command mounting, trust, and lifecycle consistent. ## Where SpecFact Fits @@ -258,75 +173,3 @@ SpecFact complements your stack rather than replacing it. - **Spec-Kit/OpenSpec** for authoring and change tracking - **Backlog tools** for planning and delivery - **CI/CD** for enforcement and regression prevention - -**SpecFact connects them** with adapters, policy checks, and deterministic validation. - -**Integrations snapshot**: GitHub, Azure DevOps, Jira, Linear, Spec-Kit, OpenSpec, Specmatic. - -- **[Integrations Overview](docs/guides/integrations-overview.md)** -- **[DevOps Adapter Integration](docs/guides/devops-adapter-integration.md)** - ---- - -## Recommended Paths - -- **I want a quick win**: [Getting Started](docs/getting-started/README.md) -- **I use an AI IDE**: [AI IDE Workflow](docs/guides/ai-ide-workflow.md) -- **We have a team backlog**: [Agile/Scrum Workflows](docs/guides/agile-scrum-workflows.md) -- **We have a long-lived codebase**: [Working With Existing Code](docs/guides/brownfield-engineer.md) - ---- - -## Documentation Map - -- **[Documentation Index](docs/README.md)** -- **[Command Reference](docs/reference/commands.md)** -- **[Backlog Refinement](docs/guides/backlog-refinement.md)** -- **[Backlog Dependency Analysis](docs/guides/backlog-dependency-analysis.md)** -- **[Backlog Delta Commands](docs/guides/backlog-delta-commands.md)** -- **[Policy Engine Commands](docs/guides/policy-engine-commands.md)** -- **[Project DevOps Flow](docs/guides/project-devops-flow.md)** -- **[Sidecar Validation](docs/guides/sidecar-validation.md)** -- **[OpenSpec Journey](docs/guides/openspec-journey.md)** - ---- - -## Contributing - -We welcome contributions. See [CONTRIBUTING.md](CONTRIBUTING.md). - -```bash -git clone https://github.com/nold-ai/specfact-cli.git -cd specfact-cli -pip install -e ".[dev]" -hatch run contract-test-full -``` - ---- - -## License - -**Apache License 2.0** - Open source and enterprise-friendly. - -[Full license](LICENSE) - ---- - -## Support - -- **GitHub Discussions**: https://github.com/nold-ai/specfact-cli/discussions -- **GitHub Issues**: https://github.com/nold-ai/specfact-cli/issues -- **Email**: hello@noldai.com -- **Debug logs**: Run with `--debug` and check `~/.specfact/logs/specfact-debug.log`. - ---- - -
- -**Built by [NOLD AI](https://noldai.com)** - -Copyright © 2025-2026 Nold AI (Owner: Dominikus Nold) - -**Trademarks**: NOLD AI (NOLDAI) is a registered trademark (wordmark) at the European Union Intellectual Property Office (EUIPO). All other trademarks mentioned in this project are the property of their respective owners. See [TRADEMARKS.md](TRADEMARKS.md) for more information. - -
diff --git a/docs/LICENSE.md b/docs/LICENSE.md index dd8dba5c..8353814c 100644 --- a/docs/LICENSE.md +++ b/docs/LICENSE.md @@ -1,3 +1,9 @@ +--- +layout: default +title: LICENSE +permalink: /LICENSE/ +--- + Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ diff --git a/docs/README.md b/docs/README.md index 8950bdce..6d560557 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,181 +2,77 @@ layout: default title: Documentation Index permalink: /documentation-index/ -description: High-level index for the SpecFact CLI documentation sections and guides. +description: High-level index for the SpecFact core CLI docs and canonical modules docs handoff. --- # SpecFact CLI Documentation -> **The "swiss knife" CLI that turns any codebase into a clear, safe, and shippable workflow.** -> Keep backlog, specs, tests, and code in sync so AI-assisted changes don’t break production. -> Works for brand-new projects and long-lived codebases — even if you’re new to coding. +This repository owns the **core CLI** documentation set for SpecFact. +It explains the overall process of using SpecFact CLI, the platform runtime, and how official modules integrate into the grouped command surface. -**Built for both worlds** +For **module-specific deep functionality**, use the canonical modules docs site at `https://modules.specfact.io/`. +The canonical modules docs site owns the detailed guides for bundle workflows, adapters, and module authoring. -- **Vibe coders and new builders** who want to ship fast with guardrails and confidence. -- **Legacy professionals** who want AI speed without lowering standards, plus end-to-end spec -> backlog -> code sync. +## Core Docs Scope ---- - -## The Missing Link (Coder + DevOps Bridge) - -Most tools help **either** coders **or** agile teams. SpecFact does both: - -- **Backlog sync that is actually strong**: round-trip sync + refinement for GitHub, Azure DevOps, Jira, Linear. -- **Ceremony support teams can run**: standup, refinement, sprint planning, flow metrics (Scrum/Kanban/SAFe). -- **Policy + validation**: DoR/DoD/flow checks plus contract enforcement for production-grade safety. - -Recommended command entrypoints: -- `specfact backlog ceremony standup ...` -- `specfact backlog ceremony refinement ...` -- `specfact backlog verify-readiness --bundle ` -- `specfact backlog analyze-deps --bundle ` +Use this docs set for: -What the backlog ceremony and readiness commands do in practice: -- Converts team working agreements (DoR, DoD, flow/PI readiness) into deterministic checks. -- Flags exact readiness gaps per backlog item with actionable evidence pointers. -- Runs structured ceremony workflows (standup, refinement) against live backlog data. +- CLI bootstrap, lifecycle, and upgrade flows +- module registry, trust, and ownership boundaries +- overall workflow topology across `project`, `backlog`, `code`, `spec`, and `govern` +- runtime and architecture reference for the lean-core platform -Start with: -- `specfact backlog ceremony standup --help` -- `specfact backlog verify-readiness --bundle ` -- `specfact backlog refine --help` +## Modules Docs Scope -**Try it now** +Use the canonical modules docs site for: -- **Coders**: [AI IDE Workflow](guides/ai-ide-workflow.md) -- **Agile teams**: [Agile/Scrum Workflows](guides/agile-scrum-workflows.md) +- backlog refinement, ceremony, dependency-analysis, and delta workflows +- project bundle and bridge-sync runbooks +- spec bundle deep dives and govern bundle deep dives +- adapter-specific behavior and official bundle tutorials +- module development, publishing, signing, and marketplace operations ---- +The canonical modules docs site is currently published at `https://modules.specfact.io/`. +This docs set keeps release-line overview and handoff content for bundle workflows while the canonical modules docs site carries the deep bundle-specific guidance. -## Start Here (Pick Your Path) +## Core Entry Points -**Pick your path** - -- **Working with existing code**: [Getting Started](getting-started/README.md) and [Legacy Engineer Guide](guides/brownfield-engineer.md) -- **Agile team workflows**: [Agile/Scrum Workflows](guides/agile-scrum-workflows.md) and [Backlog Refinement](guides/backlog-refinement.md) -- **AI IDE workflow**: [AI IDE Workflow Guide](guides/ai-ide-workflow.md) -- **Integrations**: [Integrations Overview](guides/integrations-overview.md) - ---- - -## Modules and Capabilities - -**Core runtime** - -- **Permanent commands**: `init`, `module`, `upgrade` -- **Core responsibilities**: lifecycle, registry, trust, contracts, orchestration, shared runtime utilities - -**Marketplace-installed bundles** - -- **Backlog**: Refinement, dependency analysis, sprint summaries, risk rollups. -- **Ceremony**: Standup, refinement, and planning entry points. -- **Policy**: DoR, DoD, flow, PI readiness checks. -- **Patch**: Preview, apply, and write changes safely. - -**Adapters and bridges** - -- **Specs**: Spec-Kit and OpenSpec -- **Backlogs**: GitHub Issues, Azure DevOps, Jira, Linear -- **Contracts**: Specmatic, OpenAPI - -## Module Lifecycle System - -SpecFact CLI uses a lifecycle-managed module system: - -- `specfact init` bootstraps local state. -- `specfact init ide` handles IDE prompt/template installation and updates. -- `specfact module` is the canonical lifecycle surface for install/list/show/search/enable/disable/uninstall/upgrade. -- Dependency and compatibility guards prevent invalid module states; `--force` enables dependency-aware cascades. +- [Docs Home](index.md) +- [Getting Started](getting-started/README.md) +- [Command Reference](reference/commands.md) +- [Reference Index](reference/README.md) +- [Architecture Reference](reference/architecture.md) -This is the baseline for marketplace-driven module lifecycle and future community module distribution. +## Current Core Command Topology -`docs.specfact.io` is the canonical docs entry point for SpecFact, and this repository owns the -core CLI/runtime section of that experience. +The live CLI groups installed workflow commands by category: -The canonical modules docs site is currently published at -`https://modules.specfact.io/`. -Bundle-specific deep guides in this repo remain as release-line overview or handoff content rather than the long-term canonical source. +- `specfact init` +- `specfact module` +- `specfact upgrade` +- `specfact project ...` +- `specfact backlog ...` +- `specfact code ...` +- `specfact spec ...` +- `specfact govern ...` -### Why the Module System Is the Foundation +Preferred backlog workflow entrypoints: -This architecture intentionally separates the CLI core from feature modules: +- `specfact backlog ceremony standup ...` +- `specfact backlog ceremony refinement ...` +- `specfact backlog verify-readiness --bundle ` +- `specfact backlog analyze-deps --bundle ` -- Core provides lifecycle, registry, contracts, and orchestration. -- Official workflow bundles are authored and released from `nold-ai/specfact-cli-modules`. -- This docs set keeps release-line overview and handoff content for bundle workflows while the canonical modules docs site carries the deep bundle-specific guidance. -- Compatibility shims preserve legacy import paths during migration windows. +Compatibility note: `specfact backlog daily ...` and `specfact backlog refine ...` remain available, but the ceremony forms are the preferred command path. -Practical outcomes: +## Core vs Modules Navigation -- Feature modules can be developed and released at different speeds. -- Module teams can iterate without repeatedly rebuilding core command wiring. -- Stable contracts/interfaces keep migrations predictable and reduce regressions. +- **Core CLI docs**: runtime, lifecycle, contracts, command topology, architecture +- **Canonical modules docs site**: bundle-specific tutorials, command details, adapters, module authoring -For implementation details, see: +### Recommended next reads -- [Architecture](reference/architecture.md) -- [Module Contracts](reference/module-contracts.md) - [Installing Modules](guides/installing-modules.md) -- [Module Marketplace](guides/module-marketplace.md) -- [Custom registries](guides/custom-registries.md) -- [Publishing modules](guides/publishing-modules.md) -- [Module Signing and Key Rotation](guides/module-signing-and-key-rotation.md) - ---- - -## Documentation Sections - -### Getting Started - -- [Installation](getting-started/installation.md) -- [First Steps](getting-started/first-steps.md) -- [Enhanced Analysis Dependencies](installation/enhanced-analysis-dependencies.md) - -### Guides - -- [Agile/Scrum Workflows](guides/agile-scrum-workflows.md) -- [Backlog Refinement](guides/backlog-refinement.md) -- [Backlog Dependency Analysis](guides/backlog-dependency-analysis.md) -- [Backlog Delta Commands](guides/backlog-delta-commands.md) -- [Policy Engine Commands](guides/policy-engine-commands.md) -- [Project DevOps Flow](guides/project-devops-flow.md) -- [DevOps Adapter Integration](guides/devops-adapter-integration.md) -- [AI IDE Workflow](guides/ai-ide-workflow.md) -- [Sidecar Validation](guides/sidecar-validation.md) -- [Use Cases](guides/use-cases.md) - -### Integrations - -- [Spec-Kit Journey](guides/speckit-journey.md) -- [OpenSpec Journey](guides/openspec-journey.md) -- [Specmatic Integration](guides/specmatic-integration.md) -- [Custom Field Mapping](guides/custom-field-mapping.md) - -### Reference - -- [Command Reference](reference/commands.md) -- [Architecture](reference/architecture.md) -- [Debug Logging](reference/debug-logging.md) - -### Contributing - -- [Development Setup](getting-started/installation.md#development-setup) -- [Testing Procedures](technical/testing.md) -- [Technical Deep Dives](technical/README.md) - ---- - -## Helpful Shortcuts - -- **Command Chains**: [guides/command-chains.md](guides/command-chains.md) -- **Common Tasks**: [guides/common-tasks.md](guides/common-tasks.md) -- **Online Docs**: https://docs.specfact.io/ - ---- - -## Need Help? - -- **GitHub Discussions**: https://github.com/nold-ai/specfact-cli/discussions -- **GitHub Issues**: https://github.com/nold-ai/specfact-cli/issues -- **Email**: hello@noldai.com +- [Module Categories](reference/module-categories.md) +- [Module Contracts](reference/module-contracts.md) +- [Canonical modules docs site](https://modules.specfact.io/) diff --git a/docs/TRADEMARKS.md b/docs/TRADEMARKS.md index 03d6262b..8897f94a 100644 --- a/docs/TRADEMARKS.md +++ b/docs/TRADEMARKS.md @@ -1,3 +1,9 @@ +--- +layout: default +title: TRADEMARKS +permalink: /TRADEMARKS/ +--- + # Trademarks ## NOLD AI Trademark diff --git a/docs/architecture/component-graph.md b/docs/architecture/component-graph.md index 9144958f..47d8a3d0 100644 --- a/docs/architecture/component-graph.md +++ b/docs/architecture/component-graph.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Component Graph +permalink: /architecture/component-graph/ +--- + # SpecFact CLI Component Graph ## High-level components diff --git a/docs/architecture/data-flow.md b/docs/architecture/data-flow.md index 03cfadc5..20aaeb0a 100644 --- a/docs/architecture/data-flow.md +++ b/docs/architecture/data-flow.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Data Flow +permalink: /architecture/data-flow/ +--- + # SpecFact CLI Data Flow Architecture ## Command execution flow diff --git a/docs/architecture/discrepancies-report.md b/docs/architecture/discrepancies-report.md index cde8cf31..8b9dc1e3 100644 --- a/docs/architecture/discrepancies-report.md +++ b/docs/architecture/discrepancies-report.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Discrepancies Report +permalink: /architecture/discrepancies-report/ +--- + # SpecFact CLI Architecture Discrepancies Report ## Executive Summary diff --git a/docs/architecture/interface-contracts.md b/docs/architecture/interface-contracts.md index 8c4f1e42..be51798f 100644 --- a/docs/architecture/interface-contracts.md +++ b/docs/architecture/interface-contracts.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Interface Contracts +permalink: /architecture/interface-contracts/ +--- + # SpecFact CLI Interface Contracts ## Command Registry contract diff --git a/docs/architecture/module-system.md b/docs/architecture/module-system.md index b8a5da49..018568d8 100644 --- a/docs/architecture/module-system.md +++ b/docs/architecture/module-system.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Module System +permalink: /architecture/module-system/ +--- + # SpecFact CLI Module System Architecture ## Status diff --git a/docs/architecture/state-machines.md b/docs/architecture/state-machines.md index 0a1b0962..c8ef3bc1 100644 --- a/docs/architecture/state-machines.md +++ b/docs/architecture/state-machines.md @@ -1,3 +1,9 @@ +--- +layout: default +title: State Machines +permalink: /architecture/state-machines/ +--- + # SpecFact CLI State Machine Logic ## CLI command lifecycle diff --git a/docs/contributing/github-project-gh-cli.md b/docs/contributing/github-project-gh-cli.md index fba7bae3..1dd8a67e 100644 --- a/docs/contributing/github-project-gh-cli.md +++ b/docs/contributing/github-project-gh-cli.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Github Project Gh Cli +permalink: /contributing/github-project-gh-cli/ +--- + # SpecFact CLI project – gh CLI automation How to set **Projects** and project fields (Status, Type, Parent issue) that appear on each issue/PR **sidebar** for the [SpecFact CLI project](https://github.com/orgs/nold-ai/projects/1). All of this can be done with the GitHub CLI (`gh`). diff --git a/docs/examples/brownfield-data-pipeline.md b/docs/examples/brownfield-data-pipeline.md index d3bdb1f4..d29aa958 100644 --- a/docs/examples/brownfield-data-pipeline.md +++ b/docs/examples/brownfield-data-pipeline.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Brownfield Data Pipeline +permalink: /examples/brownfield-data-pipeline/ +--- + # Brownfield Example: Modernizing Legacy Data Pipeline > **Complete walkthrough: From undocumented ETL pipeline to contract-enforced data processing** diff --git a/docs/examples/brownfield-django-modernization.md b/docs/examples/brownfield-django-modernization.md index df6280e4..9782d2eb 100644 --- a/docs/examples/brownfield-django-modernization.md +++ b/docs/examples/brownfield-django-modernization.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Brownfield Django Modernization +permalink: /examples/brownfield-django-modernization/ +--- + # Brownfield Example: Modernizing Legacy Django Code > **Complete walkthrough: From undocumented legacy Django app to contract-enforced modern codebase** diff --git a/docs/examples/brownfield-flask-api.md b/docs/examples/brownfield-flask-api.md index 0a61eaac..ea127bea 100644 --- a/docs/examples/brownfield-flask-api.md +++ b/docs/examples/brownfield-flask-api.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Brownfield Flask Api +permalink: /examples/brownfield-flask-api/ +--- + # Brownfield Example: Modernizing Legacy Flask API > **Complete walkthrough: From undocumented Flask API to contract-enforced modern service** diff --git a/docs/examples/dogfooding-specfact-cli.md b/docs/examples/dogfooding-specfact-cli.md index 5475c586..686ce414 100644 --- a/docs/examples/dogfooding-specfact-cli.md +++ b/docs/examples/dogfooding-specfact-cli.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Dogfooding Specfact Cli +permalink: /examples/dogfooding-specfact-cli/ +--- + # Real-World Example: SpecFact CLI Analyzing Itself > **TL;DR**: We ran SpecFact CLI on its own codebase in two ways: (1) **Brownfield analysis** discovered **19 features** and **49 stories** in **under 3 seconds**, found **24 deviations**, and blocked the merge (as configured). (2) **Contract enhancement** added beartype, icontract, and CrossHair contracts to our core telemetry module with **7-step validation** (all tests passed, code quality maintained). Total time: **< 10 seconds** for analysis, **~3 minutes** for contract enhancement. 🚀 diff --git a/docs/examples/integration-showcases/README.md b/docs/examples/integration-showcases/README.md index 80b035b7..5b062f0d 100644 --- a/docs/examples/integration-showcases/README.md +++ b/docs/examples/integration-showcases/README.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Integration Showcases +permalink: /examples/integration-showcases/ +--- + # Integration Showcases > **Core USP**: SpecFact CLI works seamlessly with VS Code, Cursor, GitHub Actions, and any agentic workflow. This folder contains real examples of bugs that were caught and fixed through different integration points. diff --git a/docs/examples/integration-showcases/integration-showcases-quick-reference.md b/docs/examples/integration-showcases/integration-showcases-quick-reference.md index 08db3680..3bd0a06e 100644 --- a/docs/examples/integration-showcases/integration-showcases-quick-reference.md +++ b/docs/examples/integration-showcases/integration-showcases-quick-reference.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Integration Showcases Quick Reference +permalink: /examples/integration-showcases/integration-showcases-quick-reference/ +--- + # Integration Showcases - Quick Reference > **Quick command reference** for testing all 5 integration examples diff --git a/docs/examples/integration-showcases/integration-showcases-testing-guide.md b/docs/examples/integration-showcases/integration-showcases-testing-guide.md index c6227ed4..253db248 100644 --- a/docs/examples/integration-showcases/integration-showcases-testing-guide.md +++ b/docs/examples/integration-showcases/integration-showcases-testing-guide.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Integration Showcases Testing Guide +permalink: /examples/integration-showcases/integration-showcases-testing-guide/ +--- + # Integration Showcases Testing Guide > **Purpose**: Step-by-step guide to test and validate all 5 integration examples from `integration-showcases.md` diff --git a/docs/examples/integration-showcases/integration-showcases.md b/docs/examples/integration-showcases/integration-showcases.md index 9b904809..84c3fb9e 100644 --- a/docs/examples/integration-showcases/integration-showcases.md +++ b/docs/examples/integration-showcases/integration-showcases.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Integration Showcases +permalink: /examples/integration-showcases/integration-showcases/ +--- + # Integration Showcases: Bugs Fixed via CLI Integrations > **Core USP**: SpecFact CLI works seamlessly with VS Code, Cursor, GitHub Actions, and any agentic workflow. This document showcases real examples of bugs that were caught and fixed through different integration points. diff --git a/docs/getting-started/README.md b/docs/getting-started/README.md index 9187bc1a..528d568f 100644 --- a/docs/getting-started/README.md +++ b/docs/getting-started/README.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Getting Started +permalink: /getting-started/ +--- + # Getting Started with SpecFact CLI Welcome to SpecFact CLI! This guide will help you get started in under 60 seconds. diff --git a/docs/getting-started/tutorial-openspec-speckit.md b/docs/getting-started/tutorial-openspec-speckit.md index 7da1895d..eb52c134 100644 --- a/docs/getting-started/tutorial-openspec-speckit.md +++ b/docs/getting-started/tutorial-openspec-speckit.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Tutorial Openspec Speckit +permalink: /getting-started/tutorial-openspec-speckit/ +--- + # Tutorial: Using SpecFact with OpenSpec or Spec-Kit > **Complete step-by-step guide for new users** diff --git a/docs/guides/README.md b/docs/guides/README.md index 89a286be..1650fa1d 100644 --- a/docs/guides/README.md +++ b/docs/guides/README.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Guides +permalink: /guides/ +--- + # Guides Practical guides for using SpecFact CLI effectively. diff --git a/docs/guides/brownfield-faq.md b/docs/guides/brownfield-faq.md index fc6b7c47..8120afb0 100644 --- a/docs/guides/brownfield-faq.md +++ b/docs/guides/brownfield-faq.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Brownfield Faq +permalink: /guides/brownfield-faq/ +--- + # Brownfield Modernization FAQ > **Frequently asked questions about using SpecFact CLI for legacy code modernization** diff --git a/docs/guides/brownfield-roi.md b/docs/guides/brownfield-roi.md index 70e2845f..e8e3a746 100644 --- a/docs/guides/brownfield-roi.md +++ b/docs/guides/brownfield-roi.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Brownfield Roi +permalink: /guides/brownfield-roi/ +--- + # Brownfield Modernization ROI with SpecFact > **Calculate your time and cost savings when modernizing legacy Python code** diff --git a/docs/guides/integrations-overview.md b/docs/guides/integrations-overview.md index d44efd35..d2687613 100644 --- a/docs/guides/integrations-overview.md +++ b/docs/guides/integrations-overview.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Integrations Overview +permalink: /guides/integrations-overview/ +--- + # Integrations Overview > **Comprehensive guide to all SpecFact CLI integrations** diff --git a/docs/guides/migration-0.16-to-0.19.md b/docs/guides/migration-0.16-to-0.19.md index d1f0af50..8ae43310 100644 --- a/docs/guides/migration-0.16-to-0.19.md +++ b/docs/guides/migration-0.16-to-0.19.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Migration 0.16 To 0.19 +permalink: /guides/migration-0.16-to-0.19/ +--- + # Migration Guide: v0.16.x to v0.20.0 LTS This guide helps you upgrade from SpecFact CLI v0.16.x to v0.20.0 LTS (Long-Term Stable). diff --git a/docs/guides/migration-cli-reorganization.md b/docs/guides/migration-cli-reorganization.md index 1e26e610..d72b3e31 100644 --- a/docs/guides/migration-cli-reorganization.md +++ b/docs/guides/migration-cli-reorganization.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Migration Cli Reorganization +permalink: /guides/migration-cli-reorganization/ +--- + # CLI Reorganization Migration Guide **Date**: 2025-11-27 diff --git a/docs/guides/specmatic-integration.md b/docs/guides/specmatic-integration.md index 1635875c..e9d14102 100644 --- a/docs/guides/specmatic-integration.md +++ b/docs/guides/specmatic-integration.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Specmatic Integration +permalink: /guides/specmatic-integration/ +--- + # Specmatic Integration Guide > **API Contract Testing with Specmatic** diff --git a/docs/guides/workflows.md b/docs/guides/workflows.md index ac419ed1..905d380f 100644 --- a/docs/guides/workflows.md +++ b/docs/guides/workflows.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Workflows +permalink: /guides/workflows/ +--- + # Common Workflows Daily workflows for using SpecFact CLI effectively. diff --git a/docs/index.md b/docs/index.md index 990959d2..4dd11806 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,307 +1,104 @@ --- layout: default title: SpecFact CLI Documentation -description: The swiss knife CLI that keeps backlog, specs, tests, and code in sync. Works for new and long-lived projects. +description: Core CLI docs for runtime lifecycle, command topology, and official module integration. permalink: / --- # SpecFact CLI Documentation -**Docs Home**: `docs.specfact.io` currently serves as the canonical docs entry point and, until the dedicated portal cutover lands, also hosts the Core CLI section. +**Docs Home**: `docs.specfact.io` is the canonical docs entry point for SpecFact. -**Core CLI**: this site owns runtime, lifecycle, registry, trust, and architecture guidance for `specfact-cli`. +**Core CLI**: this site owns runtime, lifecycle, registry, trust, command-topology, and architecture guidance for `specfact-cli`. **Modules**: bundle-specific deep docs are canonically owned by `specfact-cli-modules` and are currently published at `https://modules.specfact.io/`. -**The "swiss knife" CLI that turns any codebase into a clear, safe, and shippable workflow** -Keep backlog, specs, tests, and code in sync so AI-assisted changes don’t break production. +This core docs site should answer two questions: -**Built for both worlds** +- How does the SpecFact platform work end to end? +- How do the official modules plug into the core CLI runtime? -- **Vibe coders and new builders** who want to ship fast with guardrails and confidence. -- **Legacy professionals** who want AI speed without lowering standards, plus end-to-end spec -> backlog -> code sync. - -**Core promise**: Works for new and long-lived projects with contract enforcement and validation. +Use the modules docs site when you need the in-depth workflows for backlog, project, code, spec, govern, adapters, or module authoring. --- -## The Missing Link (Coder + DevOps Bridge) - -Most tools help **either** coders **or** agile teams. SpecFact does both: +## What The Core CLI Owns -- **Backlog sync that is actually strong**: round-trip sync + refinement with GitHub, Azure DevOps, Jira, Linear. -- **Ceremony support teams can run**: standup, refinement, sprint planning, flow metrics (Scrum/Kanban/SAFe). -- **Policy + validation**: DoR/DoD/flow checks plus contract enforcement for production-grade stability. +The `specfact-cli` repository owns the stable platform surface: -Recommended command entrypoints: -- `specfact backlog ceremony standup ...` -- `specfact backlog ceremony refinement ...` -- `specfact backlog verify-readiness --bundle ` +- `specfact init` for bootstrap and IDE setup. +- `specfact module` for lifecycle management of official and marketplace modules. +- `specfact upgrade` for CLI updates. +- Runtime contracts, module discovery, registry bootstrapping, publisher trust, and shared orchestration. +- The grouped command topology that mounts installed workflows under `project`, `backlog`, `code`, `spec`, and `govern`. -**Try it now** +## What The Modules Docs Own -- **Coders**: [AI IDE Workflow](guides/ai-ide-workflow.md) -- **Agile teams**: [Agile/Scrum Workflows](guides/agile-scrum-workflows.md) +The canonical modules docs site covers the official bundle-specific deep guidance: ---- +- backlog ceremonies, refinement, dependency analysis, delta workflows, and adapter specifics +- project bundle workflows and bridge synchronization +- spec validation, mock, backward-compatibility, and contract-test details +- govern enforcement, patch workflows, and bundle-focused runbooks +- module development, publishing, signing, registries, and marketplace operations -## 🚀 Quick Start +Canonical modules site: `https://modules.specfact.io/` -### Backlog Bridge in 60 Seconds +--- -SpecFact closes the drift gap between **backlog -> specs -> code**. -These commands require the backlog bundle to be installed first, for example via -`specfact init --profile backlog-team` or `specfact init --install backlog`. +## Quick Start ```bash -# 1) Initialize backlog config + field mapping -specfact backlog init-config --force -specfact backlog map-fields --provider ado --ado-org --ado-project "" - -# 2) Read and refine real backlog scope -specfact backlog daily ado --ado-org --ado-project "" --state any --assignee any --limit 5 -specfact backlog refine ado --ado-org --ado-project "" --id --preview - -# 3) Validate drift before implementation -specfact backlog verify-readiness --bundle -``` - -GitHub variant: -`specfact backlog daily github --repo-owner --repo-name --state any --assignee any --limit 5` - -Deep dive: -- **[Backlog Quickstart Demo (GitHub + ADO)](getting-started/tutorial-backlog-quickstart-demo.md)** - -### New to SpecFact CLI? - -**Primary Use Case**: Understanding and improving existing codebases (and new projects) - -1. **[Installation](getting-started/installation.md)** - Get started in 60 seconds -2. **[First Steps](getting-started/first-steps.md)** - Run your first command -3. **[Module Bootstrap Checklist](getting-started/module-bootstrap-checklist.md)** - Quickly verify official bundles are installed for user/project scope -4. **[Tutorial: Backlog Refine with AI IDE](getting-started/tutorial-backlog-refine-ai-ide.md)** - Integrate backlog refinement with your AI IDE (agile DevOps) -5. **[Tutorial: Daily Standup and Sprint Review](getting-started/tutorial-daily-standup-sprint-review.md)** - Daily standup view, post comments, and Copilot export (GitHub/ADO) -6. **[Working With Existing Code](guides/brownfield-engineer.md)** ⭐ **PRIMARY** - Legacy-first guide -7. **[The Existing Code Journey](guides/brownfield-journey.md)** ⭐ - Complete modernization workflow - -### Using GitHub Spec-Kit or OpenSpec? - -**Secondary Use Case**: Add automated enforcement to your Spec-Kit or OpenSpec projects - -- **[From Spec-Kit to SpecFact](guides/speckit-journey.md)** - Add enforcement to Spec-Kit projects -- **[Spec-Kit Comparison](guides/speckit-comparison.md)** - Understand when to use each tool -- **[From OpenSpec to SpecFact](guides/openspec-journey.md)** - Add enforcement to OpenSpec projects - -## Module System Foundation - -SpecFact now uses a lean-core plus bundle architecture to reduce hard-wired command coupling. +# Install and bootstrap official bundles +uvx specfact-cli@latest +specfact init --profile solo-developer -- Core runtime (`specfact-cli`) handles lifecycle, registry, contracts, and orchestration. -- Official workflow behavior lives in installable bundle packages from `nold-ai/specfact-cli-modules`. -- Flat command-path shims were removed; use workflow command groups. +# Analyze an existing repository +specfact code import my-project --repo . -Implementation ownership: +# Snapshot project state +specfact project snapshot --bundle my-project -- Runtime and registry: `specfact-cli` -- Official bundles and registry artifacts: `specfact-cli-modules` -- Legacy compatibility shims in core: `src/specfact_cli/commands/*.py` (only `app` re-export is guaranteed) +# Run backlog ceremony workflow +specfact backlog ceremony refinement github --search "is:open label:feature" --preview -Why this matters: +# Validate before implementation or release +specfact spec validate --bundle my-project +specfact govern enforce sdd my-project +``` -- Modules can evolve at different speeds without repeatedly changing CLI core wiring. -- Interfaces and contracts keep feature development isolated and safer to iterate. -- Pending OpenSpec-driven module changes can land incrementally with lower migration risk. +Compatibility note: `specfact backlog daily ...` and `specfact backlog refine ...` remain available, but the preferred workflow entrypoints are `specfact backlog ceremony standup ...` and `specfact backlog ceremony refinement ...`. -### Category Command Groups and First-Run Selection +## Current Command Groups -SpecFact now groups feature commands by workflow domain: +The live CLI currently exposes these top-level commands: +- `specfact init` +- `specfact module` +- `specfact upgrade` - `specfact project ...` - `specfact backlog ...` - `specfact code ...` - `specfact spec ...` - `specfact govern ...` -On a fresh setup, `specfact init` supports first-run bundle selection: - -```bash -specfact init --profile solo-developer -specfact init --install backlog,codebase -specfact init --install all -``` - -See [Module Categories](reference/module-categories.md) for full mappings and profile presets. - -**Module security and extensions:** - -- **[Using Module Security and Extensions](guides/using-module-security-and-extensions.md)** - How to use verified modules (arch-06) and schema extensions (arch-07) from the CLI and as a module author -- **[Extending ProjectBundle](guides/extending-projectbundle.md)** - Declare and use namespaced extension fields on Feature/ProjectBundle -- **[Module Signing and Key Rotation](guides/module-signing-and-key-rotation.md)** - Runbook for public key placement, signing, CI verification, key rotation, and emergency revocation -- **[Module Security](reference/module-security.md)** - Publisher, integrity (checksum/signature), and versioned dependencies - -### For Technical Readers - -- **[Architecture Reference](reference/architecture.md)** - Current architecture model and interfaces -- **[Architecture Docs Index](architecture/README.md)** - Component graph, module system, data flow, state machines -- **[Architecture Implementation Status](architecture/implementation-status.md)** - Implemented vs planned features -- **[Architecture ADRs](architecture/adr/README.md)** - Decision records and template - - -## Module Marketplace - -SpecFact now supports a central marketplace workflow for module installation and lifecycle management. - -Official bundles are now marketplace-distributed as `nold-ai/specfact-*` modules: - -- `nold-ai/specfact-project` -- `nold-ai/specfact-backlog` -- `nold-ai/specfact-codebase` -- `nold-ai/specfact-spec` -- `nold-ai/specfact-govern` - -This page remains the core-side overview for marketplace concepts and docs navigation. -Bundle-specific deep documentation is canonically owned by `specfact-cli-modules` and is currently published at: -`https://modules.specfact.io/`. - -- **[Installing Modules](guides/installing-modules.md)** - Install, list, uninstall, and upgrade modules -- **[Module Marketplace](guides/module-marketplace.md)** - Registry model, security checks, and discovery priority -- **[Marketplace Bundles](guides/marketplace.md)** - Official bundle ids, trust tiers, and dependency auto-install behavior -- **[Code Review Module](modules/code-review.md)** - Install and use the `nold-ai/specfact-code-review` scaffold under `specfact code review` -- **[Module Signing and Key Rotation](guides/module-signing-and-key-rotation.md)** - Signing and key management runbook - -Module lifecycle note: use `specfact module` (`init`, `install`, `list`, `show`, `search`, `enable`, `disable`, `uninstall`, `upgrade`) for module management. - -## 📚 Documentation - -### Guides +Use [Reference: Command Topology](reference/commands.md) for the exact grouped surfaces and migration mapping. -- **[Command Chains](guides/command-chains.md)** ⭐ **NEW** - Complete workflows from start to finish -- **[Agile/Scrum Workflows](guides/agile-scrum-workflows.md)** - Persona-based collaboration for teams -- **[Policy Engine Commands](guides/policy-engine-commands.md)** - Run backlog readiness and ceremony workflows -- **[DevOps Backlog Integration](guides/devops-adapter-integration.md)** 🆕 **NEW FEATURE** - Integrate SpecFact into agile DevOps workflows with bidirectional backlog sync -- **[Backlog Refinement](guides/backlog-refinement.md)** 🆕 **NEW FEATURE** - AI-assisted template-driven backlog refinement for standardizing work items -- **[Backlog Dependency Analysis](guides/backlog-dependency-analysis.md)** - Analyze critical path, cycles, orphans, and dependency impact from backlog graph data -- **[Backlog Delta Commands](guides/backlog-delta-commands.md)** - Track backlog graph changes under `specfact backlog delta` -- **[Project DevOps Flow](guides/project-devops-flow.md)** - Run plan/develop/review/release/monitor stage actions from one command surface -- **[Extending ProjectBundle](guides/extending-projectbundle.md)** - Add namespaced custom fields to Feature/ProjectBundle (arch-07) -- **[Using Module Security and Extensions](guides/using-module-security-and-extensions.md)** - Use arch-06 (module security) and arch-07 (schema extensions) from CLI and as a module author -- **[Sidecar Validation](guides/sidecar-validation.md)** 🆕 - Validate external codebases without modifying source -- **[Thorough Codebase Validation](reference/thorough-codebase-validation.md)** - Quick check, contract-full, sidecar, dogfooding -- **[UX Features](guides/ux-features.md)** - Progressive disclosure, context detection, intelligent suggestions -- **[Use Cases](guides/use-cases.md)** - Real-world scenarios and workflows -- **[IDE Integration](guides/ide-integration.md)** - Set up slash commands in your IDE -- **[CoPilot Mode](guides/copilot-mode.md)** - Using `--mode copilot` on CLI -- **[Template Customization](guides/template-customization.md)** 🆕 **NEW** - Create and customize backlog templates for your team -- **[Troubleshooting](guides/troubleshooting.md)** - Common issues and solutions -- **[Competitive Analysis](guides/competitive-analysis.md)** - How SpecFact compares - -### DevOps & Backlog Sync 🚀 - -**For Developers & DevOps Teams**: Keep your backlogs in sync with feature branches, code changes, and validations. - -- **[DevOps Integration Guide](guides/devops-adapter-integration.md)** ⭐ - Complete guide for GitHub Issues and Azure DevOps integration - - **Cross-Adapter Sync**: Lossless round-trip migration between backlog tools (GitHub ↔ ADO) - - **Bidirectional Sync**: Import backlog items as proposals, export proposals as backlog items - - **Code Change Tracking**: Automatically detect commits and add progress comments - - **Status Synchronization**: Keep OpenSpec and backlog status in sync - -- **[Backlog Refinement Guide](guides/backlog-refinement.md)** 🆕 **NEW** - AI-assisted template-driven refinement for standardizing work items - - **[Tutorial: Backlog Refine with AI IDE](getting-started/tutorial-backlog-refine-ai-ide.md)** - End-to-end tutorial for agile DevOps teams (slash prompt, DoR, split stories, underspec/overspec) - - **[Tutorial: Daily Standup and Sprint Review](getting-started/tutorial-daily-standup-sprint-review.md)** - Daily standup view, post yesterday/today/blockers, interactive mode, Copilot export (GitHub/ADO) - - **Template Detection**: Automatically detect which template matches a backlog item with priority-based resolution - - **AI-Assisted Refinement**: Generate prompts for IDE AI copilots to refine unstructured input - - **Confidence Scoring**: Validate refined content and provide confidence scores - - **Lossless Preservation**: Preserve original backlog data for round-trip synchronization - - **Agile Filtering** 🆕: Filter by sprint, release, iteration, labels, state, assignee for agile workflows - - **Persona/Framework Support** 🆕: Filter templates by persona (product-owner, architect, developer) and framework (scrum, safe, kanban) - - **Definition of Ready (DoR)** 🆕: Validate sprint readiness with repo-level DoR configuration - - **Preview/Write Safety** 🆕: Preview mode by default, explicit `--write` flag for writeback - - **OpenSpec Integration** 🆕: Add OpenSpec reference comments with `--openspec-comment` flag (preserves original body) - - **Template Customization** 🆕: Create custom templates for your team - see [Template Customization Guide](guides/template-customization.md) - -- **[Authentication](reference/authentication.md)** - Device code auth for GitHub and Azure DevOps -- **[GitHub Adapter](adapters/github.md)** - GitHub Issues adapter reference -- **[Azure DevOps Adapter](adapters/azuredevops.md)** - Azure DevOps work items adapter reference -- **[Backlog Adapter Patterns](adapters/backlog-adapter-patterns.md)** - Patterns for implementing backlog adapters - -**Quick Start for DevOps Teams:** - -```bash -# Export OpenSpec proposals to GitHub Issues -specfact project sync bridge --adapter github --mode export-only \ - --repo-owner your-org --repo-name your-repo - -# Export to Azure DevOps work items -specfact project sync bridge --adapter ado --mode export-only \ - --ado-org your-org --ado-project your-project - -# Cross-adapter sync: GitHub -> ADO (lossless round-trip) -specfact project sync bridge --adapter github --mode bidirectional \ - --bundle main --backlog-ids 123 -specfact project sync bridge --adapter ado --mode export-only \ - --bundle main --change-ids -``` - -### Reference - -- **[Reference Documentation](reference/)** - Complete technical reference index -- **[Command Reference](reference/commands.md)** - Complete command documentation -- **[Authentication](reference/authentication.md)** - Device code auth flows and token storage -- **[Architecture](reference/architecture.md)** - Technical design and principles -- **[Architecture Docs Index](architecture/README.md)** - Deep-dive architecture documentation -- **[Architecture Implementation Status](architecture/implementation-status.md)** - Current vs planned architecture scope -- **[Architecture ADRs](architecture/adr/README.md)** - Architecture decision records -- **[Bridge Registry](reference/bridge-registry.md)** 🆕 - Module-declared bridge converters and lifecycle registration -- **[Operational Modes](reference/modes.md)** - CI/CD vs CoPilot modes -- **[Directory Structure](reference/directory-structure.md)** - Project structure - -### Module Protocol Reporting - -- Lifecycle protocol compliance reporting now classifies modules using the effective runtime interface and - emits a single aggregate summary line for full/partial/legacy status. - -### Examples - -- **[Brownfield Examples](examples/)** - Real-world modernization examples -- **[Quick Examples](examples/quick-examples.md)** - Code snippets and patterns - ---- - -## 🆘 Getting Help - -### Documentation - -You're here! Browse the guides above. - -### Community - -- 💬 [GitHub Discussions](https://github.com/nold-ai/specfact-cli/discussions) - Ask questions -- 🐛 [GitHub Issues](https://github.com/nold-ai/specfact-cli/issues) - Report bugs - -### Direct Support - -- 📧 Email: [hello@noldai.com](mailto:hello@noldai.com) - ---- - -## 🤝 Contributing - -Found an error or want to improve the docs? - -1. Fork the repository -2. Edit the markdown files in `docs/` -3. Submit a pull request - -See [CONTRIBUTING.md](https://github.com/nold-ai/specfact-cli/blob/main/CONTRIBUTING.md) for guidelines. - ---- - -**Happy building!** 🚀 - ---- +## Core Docs Start Points -Copyright © 2025 Nold AI (Owner: Dominikus Nold) +- **[Getting Started](getting-started/README.md)** +- **[Command Reference](reference/commands.md)** +- **[Reference Index](reference/README.md)** +- **[Architecture Reference](reference/architecture.md)** +- **[Module Categories](reference/module-categories.md)** +- **[Module Contracts](reference/module-contracts.md)** +- **[Installing Modules](guides/installing-modules.md)** -**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](https://github.com/nold-ai/specfact-cli/blob/main/TRADEMARKS.md) for more information. +## Canonical Modules Docs Start Points -**License**: See [LICENSE](https://github.com/nold-ai/specfact-cli/blob/main/LICENSE) for licensing information. +- **[Modules Docs Home](https://modules.specfact.io/)** +- **[Modules Command Reference](https://modules.specfact.io/reference/commands/)** +- **[Backlog Refinement Guide](https://modules.specfact.io/guides/backlog-refinement/)** +- **[Project DevOps Flow Guide](https://modules.specfact.io/guides/project-devops-flow/)** +- **[Module Development Guide](https://modules.specfact.io/guides/module-development/)** +- **[Publishing Modules Guide](https://modules.specfact.io/guides/publishing-modules/)** diff --git a/docs/installation/enhanced-analysis-dependencies.md b/docs/installation/enhanced-analysis-dependencies.md index 5c01aaa3..061f0a95 100644 --- a/docs/installation/enhanced-analysis-dependencies.md +++ b/docs/installation/enhanced-analysis-dependencies.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Enhanced Analysis Dependencies +permalink: /installation/enhanced-analysis-dependencies/ +--- + # Enhanced Analysis Dependencies ## Python Package Dependencies diff --git a/docs/openspec-opsx-migration.md b/docs/openspec-opsx-migration.md index c66629f7..16dff6a6 100644 --- a/docs/openspec-opsx-migration.md +++ b/docs/openspec-opsx-migration.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Openspec Opsx Migration +permalink: /openspec-opsx-migration/ +--- + # OpenSpec OPSX Migration SpecFact CLI has migrated to **OpenSpec OPSX** (fluid, action-based workflow). Project context and configuration now use `openspec/config.yaml` as the primary source; `openspec/project.md` is supported as a legacy fallback so existing repos keep working. diff --git a/docs/plans/ci-pr-orchestrator-log-artifacts.md b/docs/plans/ci-pr-orchestrator-log-artifacts.md index fc9cbf25..53e45c5b 100644 --- a/docs/plans/ci-pr-orchestrator-log-artifacts.md +++ b/docs/plans/ci-pr-orchestrator-log-artifacts.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Ci Pr Orchestrator Log Artifacts +permalink: /plans/ci-pr-orchestrator-log-artifacts/ +--- + # Plan: PR Orchestrator — Attach Test and Repro Logs to CI Runs **Repository**: `nold-ai/specfact-cli` (public) diff --git a/docs/prompts/PROMPT_VALIDATION_CHECKLIST.md b/docs/prompts/PROMPT_VALIDATION_CHECKLIST.md index 77fc3057..e9af06b4 100644 --- a/docs/prompts/PROMPT_VALIDATION_CHECKLIST.md +++ b/docs/prompts/PROMPT_VALIDATION_CHECKLIST.md @@ -1,3 +1,9 @@ +--- +layout: default +title: PROMPT VALIDATION CHECKLIST +permalink: /prompts/PROMPT_VALIDATION_CHECKLIST/ +--- + # Prompt Validation Checklist This checklist helps ensure prompt templates are correct, aligned with CLI commands, and provide good UX. diff --git a/docs/prompts/README.md b/docs/prompts/README.md index 0b8f162c..2b45a77e 100644 --- a/docs/prompts/README.md +++ b/docs/prompts/README.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Prompts +permalink: /prompts/ +--- + # Prompt Templates and Slash Commands Reference This directory contains documentation and tools for validating slash command prompts, as well as a reference for all available slash commands. diff --git a/docs/reference/README.md b/docs/reference/README.md index d34cf38a..1b31fd9a 100644 --- a/docs/reference/README.md +++ b/docs/reference/README.md @@ -6,66 +6,58 @@ permalink: /reference/ # Reference Documentation -Complete technical reference for SpecFact CLI. +Complete technical reference for the **core SpecFact CLI platform**. -## Available References +This section documents the stable runtime, command topology, contracts, registry model, and ownership boundaries that `specfact-cli` owns directly. +For bundle-specific deep command guides and runbooks, use the canonical modules docs site at `https://modules.specfact.io/`. -- **[Commands](commands.md)** - Complete command reference with all options -- **[Thorough Codebase Validation](thorough-codebase-validation.md)** - Quick check, contract-decorated, sidecar, and dogfooding +## Core Reference Topics + +- **[Commands](commands.md)** - Exact grouped command topology and migration mapping - **[Command Syntax Policy](command-syntax-policy.md)** - Source-of-truth argument syntax conventions for docs -- **[Authentication](authentication.md)** - Device code auth flows and token storage - **[Architecture](architecture.md)** - Technical design, module structure, and internals +- **[Authentication](authentication.md)** - Device code auth flows and token storage - **[Debug Logging](debug-logging.md)** - Where and what is logged when using `--debug` - **[Operational Modes](modes.md)** - CI/CD vs CoPilot modes -- **[Specmatic API](specmatic.md)** - Specmatic integration API reference (functions, classes, integration points) -- **[Telemetry](telemetry.md)** - Opt-in analytics and privacy guarantees -- **[Feature Keys](feature-keys.md)** - Key normalization and formats -- **[Directory Structure](directory-structure.md)** - Project structure and organization -- **[Schema Versioning](schema-versioning.md)** - Bundle schema versions and backward compatibility (v1.0, v1.1) +- **[Module Categories](module-categories.md)** - Category grouping model and canonical bundle assignments +- **[Module Contracts](module-contracts.md)** - Runtime-facing interfaces and ownership boundary - **[Module Security](module-security.md)** - Marketplace/module integrity and publisher metadata -- **[Module Categories](module-categories.md)** - Category grouping model, canonical module assignments, bundles, and first-run profiles -- **[Dependency resolution](dependency-resolution.md)** - How module/pip dependency resolution works and bypass options - -## Quick Reference - -### Commands +- **[Bridge Registry](bridge-registry.md)** - Registry-facing bridge converter declarations +- **[Directory Structure](directory-structure.md)** - Project structure and organization +- **[Feature Keys](feature-keys.md)** - Key normalization and formats +- **[Dependency Resolution](dependency-resolution.md)** - Module/pip dependency resolution behavior +- **[Thorough Codebase Validation](thorough-codebase-validation.md)** - Validation strategy overview -- `specfact code import from-bridge --adapter speckit` - Import from external tools via bridge adapter -- `specfact code import ` - Reverse-engineer plans from code -- `specfact project snapshot --bundle ` - Save current backlog graph as baseline snapshot -- `specfact project devops-flow --stage ` - Run integrated DevOps stage actions -- `specfact govern enforce stage` - Configure quality gates -- `specfact code repro` - Run full 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 resolve through the configured source policy) -- `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 -- `specfact module uninstall ` / `specfact module upgrade [|--all]` - Manage module lifecycle with source-aware behavior +## Live Command Topology Summary -### Modes +Current top-level commands in the shipped CLI: -- **CI/CD Mode** - Fast, deterministic execution -- **CoPilot Mode** - Enhanced prompts with context injection +- `specfact init` +- `specfact module` +- `specfact upgrade` +- `specfact project ...` +- `specfact backlog ...` +- `specfact code ...` +- `specfact spec ...` +- `specfact govern ...` -### IDE Integration +Selected current command examples: -- `specfact init ide --ide ` - Set up slash commands in IDE -- See [IDE Integration Guide](../guides/ide-integration.md) for details +- `specfact code import from-bridge --adapter speckit --repo .` +- `specfact project sync bridge --adapter github --bundle ` +- `specfact project import --bundle ` +- `specfact spec validate --bundle ` +- `specfact spec generate-tests --bundle --output tests/` +- `specfact govern enforce sdd [BUNDLE]` +- `specfact module install [--scope user|project]` -## Technical Details +## Ownership Boundary -- **Architecture**: See [Architecture](architecture.md) -- **Command Registry and Module System**: See [Architecture - Command Registry and Module System](architecture.md#command-registry-and-module-system) -- **Operational Modes**: See [Architecture - Operational Modes](architecture.md#operational-modes) -- **Ownership Boundary**: See [Architecture - Core vs modules-repo ownership boundary](architecture.md#core-vs-modules-repo-ownership-boundary) +- Core docs site: command topology, runtime lifecycle, contracts, registry, trust, architecture +- Canonical modules docs site: in-depth bundle commands, workflow tutorials, adapters, official module operations -## Related Documentation +See also: -- [Getting Started](../getting-started/README.md) - Installation and first steps -- [Guides](../guides/README.md) - Usage guides and examples -- [Examples](../examples/README.md) - Real-world examples +- [Getting Started](../getting-started/README.md) +- [Documentation Index](../README.md) +- [Canonical modules docs site](https://modules.specfact.io/) diff --git a/docs/reference/commands.md b/docs/reference/commands.md index 593771b3..2b97cf97 100644 --- a/docs/reference/commands.md +++ b/docs/reference/commands.md @@ -6,40 +6,129 @@ permalink: /reference/commands/ # Command Reference -SpecFact CLI now ships a lean core. Workflow commands are installed from marketplace bundles. +SpecFact CLI ships a lean core. Workflow commands are installed from official or marketplace modules and mounted under grouped command families. Flat root-level compatibility shims were removed in `0.40.0`; use category-group commands only. ## Top-Level Commands -Root command surface includes core commands and installed category groups only: +The live root command surface includes: - `specfact init` - `specfact module` - `specfact upgrade` -- `specfact code ...` - `specfact backlog ...` +- `specfact code ...` +- `specfact govern ...` - `specfact project ...` - `specfact spec ...` -- `specfact govern ...` -Use `specfact init --profile ` (or `--install `) to install workflow bundles. +Use `specfact init --profile ` or `specfact init --install ` to bootstrap the workflow bundles you need. -## Workflow Command Groups +## Core-Owned Commands -After bundle install, command groups are mounted by category: +### `specfact init` -- `specfact project ...` -- `specfact backlog ...` -- `specfact code ...` -- `specfact spec ...` -- `specfact govern ...` +Bootstrap SpecFact and manage first-run setup. + +- `specfact init --profile ` +- `specfact init --install ` +- `specfact init ide [--ide ]` + +### `specfact module` + +Manage installed modules and registries. + +- `specfact module init` +- `specfact module install` +- `specfact module uninstall` +- `specfact module add-registry` +- `specfact module list-registries` +- `specfact module remove-registry` +- `specfact module enable` +- `specfact module disable` +- `specfact module search` +- `specfact module list` +- `specfact module show` +- `specfact module upgrade` +- `specfact module alias` + +### `specfact upgrade` + +Check for and install CLI updates. + +## Installed Workflow Command Groups + +After bundle install, workflow commands are mounted by category: + +### `specfact project` -## Bundle to Command Mapping +- `project link-backlog` +- `project health-check` +- `project devops-flow` +- `project snapshot` +- `project regenerate` +- `project export-roadmap` +- `project export` +- `project import` +- `project lock` +- `project unlock` +- `project locks` +- `project init-personas` +- `project merge` +- `project resolve-conflict` +- `project version` +- `project sync` + +### `specfact backlog` + +- `backlog ceremony` +- `backlog delta` +- `backlog auth` +- `backlog sync` +- `backlog verify-readiness` +- `backlog analyze-deps` +- `backlog diff` +- `backlog promote` +- `backlog refine` +- `backlog daily` +- `backlog init-config` +- `backlog map-fields` +- `backlog add` + +Preferred ceremony paths: + +- `specfact backlog ceremony standup ...` +- `specfact backlog ceremony refinement ...` + +Compatibility note: `specfact backlog daily ...` and `specfact backlog refine ...` remain available. + +### `specfact code` + +- `code review` +- `code import` +- `code analyze` +- `code drift` +- `code validate` +- `code repro` + +### `specfact spec` + +- `spec validate` +- `spec backward-compat` +- `spec generate-tests` +- `spec mock` + +### `specfact govern` + +- `govern enforce` +- `govern patch` + +## Bundle To Command Mapping | Bundle ID | Group | Main command families | |---|---|---| -| `nold-ai/specfact-project` | `project` | `project link-backlog`, `project health-check`, `project devops-flow`, `project snapshot`, `project regenerate`, `project export-roadmap`, `project import`, `project export`, `project sync` | -| `nold-ai/specfact-backlog` | `backlog` | `backlog ceremony`, `backlog refine`, `backlog daily`, `backlog sync`, `backlog auth`, `backlog analyze-deps`, `backlog verify-readiness`, `backlog delta`, `backlog add` | +| `nold-ai/specfact-project` | `project` | `project link-backlog`, `project health-check`, `project devops-flow`, `project snapshot`, `project regenerate`, `project export-roadmap`, `project import`, `project export`, `project sync`, `project version` | +| `nold-ai/specfact-backlog` | `backlog` | `backlog ceremony`, `backlog refine`, `backlog daily`, `backlog sync`, `backlog auth`, `backlog analyze-deps`, `backlog verify-readiness`, `backlog delta`, `backlog add`, `backlog map-fields` | | `nold-ai/specfact-codebase` | `code` | `code analyze`, `code drift`, `code validate`, `code repro`, `code import`, `code review` | | `nold-ai/specfact-spec` | `spec` | `spec validate`, `spec backward-compat`, `spec generate-tests`, `spec mock` | | `nold-ai/specfact-govern` | `govern` | `govern enforce`, `govern patch` | @@ -50,54 +139,53 @@ Flat compatibility shims were removed in `0.40.0`. Use grouped commands. | Removed | Replacement | |---|---| -| `specfact plan ...` | Removed — use `specfact project devops-flow` or `specfact project snapshot` | -| `specfact import ...` | `specfact code import ...` (codebase import) or `specfact project import ...` (persona Markdown) | +| `specfact plan ...` | Removed - use `specfact project devops-flow` or `specfact project snapshot` | +| `specfact import ...` | `specfact code import ...` (codebase import) or `specfact project import ...` (persona Markdown import) | | `specfact sync ...` | `specfact project sync ...` | -| `specfact backlog ...` (flat module) | `specfact backlog ...` (bundle group) | | `specfact analyze ...` | `specfact code analyze ...` | | `specfact drift ...` | `specfact code drift ...` | | `specfact validate ...` | `specfact code validate ...` | | `specfact repro ...` | `specfact code repro ...` | -| `specfact contract ...` | Removed — use `specfact spec validate` | -| `specfact sdd ...` | Removed — use `specfact govern enforce sdd [BUNDLE]` | -| `specfact generate ...` | Removed — no direct replacement; use AI IDE skills for prompt generation | +| `specfact contract ...` | Removed - use `specfact spec validate` | +| `specfact sdd ...` | Removed - use `specfact govern enforce sdd [BUNDLE]` | +| `specfact generate ...` | Removed - use the active grouped workflow or IDE skill instead | | `specfact enforce ...` | `specfact govern enforce ...` | | `specfact patch ...` | `specfact govern patch ...` | ## Common Flows ```bash -# First run (required) +# First run specfact init --profile solo-developer # Install specific workflow bundle specfact module install nold-ai/specfact-backlog -# Project workflow examples +# Code + project flow specfact code import legacy-api --repo . specfact project snapshot --bundle legacy-api -# Code workflow examples -specfact code validate sidecar init legacy-api /path/to/repo -specfact code repro --verbose - -# Backlog workflow examples +# Backlog flow specfact backlog ceremony standup --help specfact backlog ceremony refinement --help +specfact backlog verify-readiness --bundle legacy-api -# Spec validation examples -specfact spec validate --bundle my-api -specfact spec generate-tests --bundle my-api --output tests/ +# Bridge synchronization +specfact project sync bridge --adapter github --bundle legacy-api --mode export-only + +# Spec validation +specfact spec validate --bundle legacy-api +specfact spec generate-tests --bundle legacy-api --output tests/ ``` -## See Also +## Handoff To Canonical Modules Docs + +This command reference remains part of the core docs set because it explains the lean-core command topology and ownership boundary. +Bundle-specific command details, tutorials, and adapter runbooks live in the canonical modules docs site, currently published at `https://modules.specfact.io/`. +See also: + +- [Reference Index](README.md) - [Module Categories](module-categories.md) -- [Marketplace Bundles](../guides/marketplace.md) - [Installing Modules](../guides/installing-modules.md) - [Canonical modules docs site](https://modules.specfact.io/) - -> Modules docs handoff: this command reference remains part of the core docs set because it -> explains the lean-core command topology. Bundle-specific command details live in the -> canonical modules docs site, currently published at -> `https://modules.specfact.io/`. diff --git a/docs/reference/feature-keys.md b/docs/reference/feature-keys.md index 15885f4b..a37c0166 100644 --- a/docs/reference/feature-keys.md +++ b/docs/reference/feature-keys.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Feature Keys +permalink: /reference/feature-keys/ +--- + # Feature Key Normalization Reference documentation for feature key formats and normalization in SpecFact CLI. diff --git a/docs/reference/parameter-standard.md b/docs/reference/parameter-standard.md index e045f561..4d2fad77 100644 --- a/docs/reference/parameter-standard.md +++ b/docs/reference/parameter-standard.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Parameter Standard +permalink: /reference/parameter-standard/ +--- + # Parameter Standard **Date**: 2025-11-26 diff --git a/docs/reference/specmatic.md b/docs/reference/specmatic.md index c2646738..dd80079b 100644 --- a/docs/reference/specmatic.md +++ b/docs/reference/specmatic.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Specmatic +permalink: /reference/specmatic/ +--- + # Specmatic API Reference > **API Reference for Specmatic Integration** diff --git a/docs/reference/telemetry.md b/docs/reference/telemetry.md index f325641b..b2917208 100644 --- a/docs/reference/telemetry.md +++ b/docs/reference/telemetry.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Telemetry +permalink: /reference/telemetry/ +--- + # Privacy-First Telemetry (Optional) > **Opt-in analytics that highlight how SpecFact prevents brownfield regressions.** diff --git a/docs/technical/README.md b/docs/technical/README.md index f9241822..4caf47c2 100644 --- a/docs/technical/README.md +++ b/docs/technical/README.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Technical +permalink: /technical/ +--- + # Technical Deep Dives Technical documentation for contributors and developers working on SpecFact CLI. diff --git a/docs/technical/code2spec-analysis-logic.md b/docs/technical/code2spec-analysis-logic.md index 2760d924..36713bc3 100644 --- a/docs/technical/code2spec-analysis-logic.md +++ b/docs/technical/code2spec-analysis-logic.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Code2spec Analysis Logic +permalink: /technical/code2spec-analysis-logic/ +--- + # Code2Spec Analysis Logic: How It Works > **TL;DR**: SpecFact CLI uses **AI-first approach** via AI IDE integration (Cursor, CoPilot, etc.) for semantic understanding, with **AST-based fallback** for CI/CD mode. The AI IDE's native LLM understands the codebase semantically, then calls the SpecFact CLI for structured analysis. This avoids separate LLM API setup, langchain, or additional API keys while providing high-quality, semantic-aware analysis that works with all languages and generates Spec-Kit compatible artifacts. diff --git a/docs/technical/dual-stack-pattern.md b/docs/technical/dual-stack-pattern.md index 7df5c21e..afa76024 100644 --- a/docs/technical/dual-stack-pattern.md +++ b/docs/technical/dual-stack-pattern.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Dual Stack Pattern +permalink: /technical/dual-stack-pattern/ +--- + # Dual-Stack Enrichment Pattern - Technical Specification **Status**: ✅ **IMPLEMENTED** (v0.13.0+) diff --git a/docs/technical/testing.md b/docs/technical/testing.md index 58dd92ed..c7191fc9 100644 --- a/docs/technical/testing.md +++ b/docs/technical/testing.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Testing +permalink: /technical/testing/ +--- + # Testing Guide This document provides comprehensive guidance on testing the SpecFact CLI, including examples of how to test the `.specfact/` directory structure. diff --git a/docs/validation-integration.md b/docs/validation-integration.md index c5a6b478..ceced7f3 100644 --- a/docs/validation-integration.md +++ b/docs/validation-integration.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Validation Integration +permalink: /validation-integration/ +--- + # Validation Integration with Change Proposals This document describes how SpecFact validation integrates with OpenSpec change proposals to validate against proposed specifications. diff --git a/openspec/CHANGE_ORDER.md b/openspec/CHANGE_ORDER.md index 56ba1803..31de1899 100644 --- a/openspec/CHANGE_ORDER.md +++ b/openspec/CHANGE_ORDER.md @@ -80,6 +80,7 @@ These are derived extensions of the same 2026-02-15 plan and are required to ope | Module | Order | Change folder | GitHub # | Blocked by | |--------|-------|---------------|----------|------------| | docs | 01 | docs-01-core-modules-docs-alignment | [#348](https://github.com/nold-ai/specfact-cli/issues/348) | module-migration-01 ✅; module-migration-02 ✅; module-migration-03 ✅; module-migration-05 ✅; module-migration-06/07 outputs inform residual cleanup wording | +| docs | 03 | docs-03-command-syntax-parity | pending | docs-01 ✅; docs-02 ✅ | ### Marketplace (module distribution) diff --git a/openspec/changes/docs-03-command-syntax-parity/CHANGE_VALIDATION.md b/openspec/changes/docs-03-command-syntax-parity/CHANGE_VALIDATION.md new file mode 100644 index 00000000..d0b6e7cd --- /dev/null +++ b/openspec/changes/docs-03-command-syntax-parity/CHANGE_VALIDATION.md @@ -0,0 +1,68 @@ +# Change Validation Report: docs-03-command-syntax-parity + +## Summary + +This proposed change is a docs-governance and validation change. It does not introduce a runtime API or contract change in production code, but it does correct a large set of user-facing command examples that currently point to removed or transitional CLI surfaces. + +## Artifacts Reviewed + +- `openspec/changes/docs-03-command-syntax-parity/proposal.md` +- `openspec/changes/docs-03-command-syntax-parity/design.md` +- `openspec/changes/docs-03-command-syntax-parity/tasks.md` +- `openspec/changes/docs-03-command-syntax-parity/COMMAND_SYNTAX_AUDIT.md` +- `openspec/changes/docs-03-command-syntax-parity/specs/documentation-alignment/spec.md` +- `openspec/changes/docs-03-command-syntax-parity/specs/cli-output/spec.md` + +## Live CLI Surface Checked + +Validated from the current executable CLI in this repo: + +- `specfact --help` +- `specfact backlog --help` +- `specfact project --help` +- `specfact code --help` +- `specfact spec --help` +- `specfact govern --help` +- `specfact project sync bridge -h` +- `specfact govern enforce sdd -h` +- `specfact spec validate -h` +- `specfact project plan --help` → fails with `No such command 'plan'` +- `specfact plan --help` → reports command not installed + +Additional bridge-import evidence was taken from: + +- `tests/integration/importers/test_speckit_import_integration.py` + +## Dependency And Breaking-Change Analysis + +- Runtime/API breaking change risk: none in proposal stage; the change targets docs and docs-validation only. +- Behavioral risk during implementation: low to medium. + - Low for pages that simply replace removed syntax with verified current groups. + - Medium for pages that describe workflows whose former command family no longer has a direct one-to-one replacement (`project plan ...`, old `spec` subgroup trees, and some migration docs). +- Cross-repo dependency risk: low. + - The docs ownership split from `docs-01` and `docs-02` is already established. + - This proposal is local to `specfact-cli` docs and tests, though any replacement examples that point to bundle-owned deep docs must continue to respect the modules-site handoff model. + +## Scope Validation + +The audit found stale syntax in all of the following authored docs clusters: + +- repo entry and landing docs +- reference docs +- getting-started docs +- workflow and migration guides +- examples and brownfield walkthroughs +- prompt docs + +The full file inventory is captured in `COMMAND_SYNTAX_AUDIT.md`. + +## Recommendation + +Proceed. + +This change is appropriately scoped as a documentation-alignment and docs-parity change. During implementation, any example whose current replacement remains ambiguous should be removed or reframed as historical context rather than publishing an unverified command. + +## Validation Status + +- Command: `openspec validate docs-03-command-syntax-parity --strict` +- Result: pending re-run in feature worktree diff --git a/openspec/changes/docs-03-command-syntax-parity/COMMAND_SYNTAX_AUDIT.md b/openspec/changes/docs-03-command-syntax-parity/COMMAND_SYNTAX_AUDIT.md new file mode 100644 index 00000000..6b015db0 --- /dev/null +++ b/openspec/changes/docs-03-command-syntax-parity/COMMAND_SYNTAX_AUDIT.md @@ -0,0 +1,90 @@ +# Command Syntax Audit + +## Verified Current Command Surface (2026-03-20) + +Verified from live CLI help in the active worktree: + +- Core commands: `specfact init`, `specfact module`, `specfact upgrade` +- Installed workflow groups: `specfact backlog`, `specfact code`, `specfact govern`, `specfact project`, `specfact spec` + +Verified notable current groups and parameters: + +- `specfact module` + - supports `init`, `install`, `uninstall`, `add-registry`, `list-registries`, `remove-registry`, `enable`, `disable`, `search`, `list`, `show`, `upgrade`, `alias` +- `specfact project` + - supports `link-backlog`, `health-check`, `devops-flow`, `snapshot`, `regenerate`, `export-roadmap`, `export`, `import`, `lock`, `unlock`, `locks`, `init-personas`, `merge`, `resolve-conflict`, `version`, `sync` + - does not expose `project plan` + - `project import` is persona Markdown import, not bridge import +- `specfact project sync bridge` + - remains the current bridge synchronization path +- `specfact backlog` + - supports `ceremony`, `delta`, `auth`, `sync`, `verify-readiness`, `analyze-deps`, `diff`, `promote`, `refine`, `daily`, `init-config`, `map-fields`, `add` + - preferred ceremony entrypoints are `backlog ceremony standup` and `backlog ceremony refinement` + - compatibility aliases `backlog daily` and `backlog refine` still exist + - does not expose `backlog policy` +- `specfact code` + - supports `review`, `import`, `analyze`, `drift`, `validate`, `repro` + - bridge import lives under `code import`, not `project import` +- `specfact govern` + - supports `enforce`, `patch` + - `govern enforce sdd [BUNDLE]` remains valid with positional bundle input +- `specfact spec` + - supports `validate`, `backward-compat`, `generate-tests`, `mock` + - does not expose `spec contract`, `spec api`, `spec sdd`, or `spec generate` + +## Authored Docs Syntax Status + +The authored docs review now confirms: + +- removed syntax families such as `specfact project plan`, `project import from-bridge`, `backlog policy`, and retired `spec` subgroup trees are absent as current syntax +- any remaining mentions are intentionally historical notes, blockquotes, or code comments explicitly marked as removed/transitional context +- current grouped command families are present in the core command reference and landing docs + +## Docs Ownership Audit + +The sibling modules repository already contains the canonical deep bundle docs inventory under `/home/dom/git/nold-ai/specfact-cli-modules/docs`, including: + +- backlog workflow guides +- project and bridge-sync guides +- spec/govern deep guides +- adapter references +- module development, publishing, signing, marketplace, and registry docs + +That means the core docs in this repository should stay focused on: + +- overall SpecFact process and navigation +- core CLI lifecycle and grouped command topology +- runtime, contracts, registry, trust, and architecture +- explanation of how official modules integrate into the core platform + +The canonical modules docs site should continue to own: + +- module-specific deep functionality +- adapter-specific operational runbooks +- detailed official bundle workflows +- module authoring and publishing guidance + +## Required Changes Applied In This Session + +### Core topology and ownership pages updated + +- `README.md` +- `docs/index.md` +- `docs/README.md` +- `docs/reference/README.md` +- `docs/reference/commands.md` + +These now: + +- reflect the exact grouped command surface +- explain the core-vs-modules ownership boundary explicitly +- use the canonical modules docs site as the deep-docs handoff target +- prefer current ceremony-style backlog entrypoints while acknowledging compatibility aliases + +### Docs integrity fixes applied + +Added missing Jekyll front matter to the published Markdown pages that previously lacked it, including examples, guides, prompts, technical docs, architecture deep dives, legal/reference pages, and other published docs under `docs/`. + +## Outcome + +The docs tree is now aligned with the real command surface, the core/modules ownership split, and GitHub Pages front-matter requirements. diff --git a/openspec/changes/docs-03-command-syntax-parity/TDD_EVIDENCE.md b/openspec/changes/docs-03-command-syntax-parity/TDD_EVIDENCE.md index 0c93aa55..2ff01bc6 100644 --- a/openspec/changes/docs-03-command-syntax-parity/TDD_EVIDENCE.md +++ b/openspec/changes/docs-03-command-syntax-parity/TDD_EVIDENCE.md @@ -1,52 +1,76 @@ # TDD Evidence: docs-03-command-syntax-parity -## Pre-Implementation Failing Run +## Existing Syntax-Parity Evidence (2026-03-18) + +### Pre-Implementation Failing Run **Timestamp**: 2026-03-18 **Command**: -``` +```bash cd /home/dom/git/nold-ai/specfact-cli-worktrees/feature/docs-03-command-syntax-parity hatch test -- tests/unit/docs/test_release_docs_parity.py -v -k "removed or current" ``` **Result**: 9 FAILED, 3 PASSED -**Failing tests**: +**Failure summary**: -- `test_removed_project_plan_syntax_absent_from_authored_docs` — 'specfact project plan' still present in authored docs -- `test_removed_project_import_from_bridge_syntax_absent_from_authored_docs` — 'project import from-bridge' still present -- `test_removed_backlog_policy_syntax_absent_from_authored_docs` — 'backlog policy' still present -- `test_removed_spec_contract_syntax_absent_from_authored_docs` — 'spec contract' still present -- `test_removed_spec_api_syntax_absent_from_authored_docs` — 'spec api' still present -- `test_removed_spec_sdd_syntax_absent_from_authored_docs` — 'spec sdd' still present -- `test_removed_spec_generate_syntax_absent_from_authored_docs` — 'spec generate ' still present -- `test_current_spec_commands_documented_in_commands_reference` — 'spec validate' missing from commands.md (stale bundle mapping table still shows old spec commands) -- `test_current_backlog_subcommands_documented_in_commands_reference` — 'backlog refine' missing from commands reference +- removed syntax families still appeared in authored docs +- command reference still reflected stale grouped-command mappings -## Post-Implementation Passing Run +### Post-Implementation Passing Run **Timestamp**: 2026-03-18 **Command**: -``` +```bash cd /home/dom/git/nold-ai/specfact-cli-worktrees/feature/docs-03-command-syntax-parity hatch test -- tests/unit/docs/test_release_docs_parity.py -v ``` -**Result**: 21 PASSED (all) - -All new parity tests pass: -- `test_removed_project_plan_syntax_absent_from_authored_docs` ✓ -- `test_removed_project_import_from_bridge_syntax_absent_from_authored_docs` ✓ -- `test_removed_backlog_policy_syntax_absent_from_authored_docs` ✓ -- `test_removed_spec_contract_syntax_absent_from_authored_docs` ✓ -- `test_removed_spec_api_syntax_absent_from_authored_docs` ✓ -- `test_removed_spec_sdd_syntax_absent_from_authored_docs` ✓ -- `test_removed_spec_generate_syntax_absent_from_authored_docs` ✓ -- `test_current_code_import_from_bridge_documented` ✓ -- `test_current_spec_commands_documented_in_commands_reference` ✓ -- `test_current_govern_enforce_sdd_documented` ✓ -- `test_current_backlog_subcommands_documented_in_commands_reference` ✓ - -All 10 pre-existing tests also pass. +**Result**: 21 PASSED + +That earlier work established the command-syntax parity baseline for the change. + +## Front-Matter Integrity Follow-Up (2026-03-20) + +### Pre-Fix Failing Run + +**Timestamp**: 2026-03-20T10:45:52+01:00 + +**Command**: +```bash +cd /home/dom/git/nold-ai/specfact-cli-worktrees/feature/docs-03-command-syntax-parity +PATH=/home/dom/git/nold-ai/specfact-cli/.venv/bin:$PATH \ +PYTHONPATH=/home/dom/git/nold-ai/specfact-cli-worktrees/feature/docs-03-command-syntax-parity/src \ +/home/dom/git/nold-ai/specfact-cli/.venv/bin/python -m pytest tests/unit/docs/test_release_docs_parity.py -q +``` + +**Result**: 1 FAILED, 21 PASSED + +**Failure summary**: + +- new docs integrity coverage showed 41 published Markdown pages under `docs/` missing Jekyll front matter +- missing pages included architecture deep dives, examples, prompts, technical docs, and multiple guide/reference pages + +### Post-Fix Passing Run + +**Timestamp**: 2026-03-20T10:45:52+01:00 + +**Command**: +```bash +cd /home/dom/git/nold-ai/specfact-cli-worktrees/feature/docs-03-command-syntax-parity +PATH=/home/dom/git/nold-ai/specfact-cli/.venv/bin:$PATH \ +PYTHONPATH=/home/dom/git/nold-ai/specfact-cli-worktrees/feature/docs-03-command-syntax-parity/src \ +/home/dom/git/nold-ai/specfact-cli/.venv/bin/python -m pytest tests/unit/docs/test_release_docs_parity.py -q +``` + +**Result**: 22 PASSED + +**Verification summary**: + +- command-syntax parity checks pass +- core/modules docs split checks pass +- canonical modules-site handoff checks pass +- all published Markdown docs now have Jekyll front matter diff --git a/openspec/changes/docs-03-command-syntax-parity/design.md b/openspec/changes/docs-03-command-syntax-parity/design.md new file mode 100644 index 00000000..95537006 --- /dev/null +++ b/openspec/changes/docs-03-command-syntax-parity/design.md @@ -0,0 +1,72 @@ +# Design: Audit And Correct Docs Command Syntax After Core/Modules Split + +## Context + +The current executable CLI in `dev` exposes this high-level surface: + +- Core commands: `init`, `module`, `upgrade` +- Bundle groups: `backlog`, `code`, `govern`, `project`, `spec` + +Verified current group surfaces from live help: + +- `backlog`: `ceremony`, `delta`, `auth`, `sync`, `verify-readiness`, `analyze-deps`, `diff`, `promote`, `refine`, `daily`, `init-config`, `map-fields`, `add` +- `project`: `link-backlog`, `health-check`, `devops-flow`, `snapshot`, `regenerate`, `export-roadmap`, `export`, `import`, `lock`, `unlock`, `locks`, `init-personas`, `merge`, `resolve-conflict`, `version`, `sync` +- `code`: `review`, `import`, `analyze`, `drift`, `validate`, `repro` +- `spec`: `validate`, `backward-compat`, `generate-tests`, `mock` +- `govern`: `enforce`, `patch` + +The authored docs still contain older or transitional syntax families that no longer match that surface, including: + +1. `specfact project plan ...` +2. `specfact project import from-bridge ...` +3. `specfact backlog policy ...` +4. `specfact spec contract ...`, `specfact spec api ...`, `specfact spec sdd ...`, `specfact spec generate ...` +5. migration guidance that maps removed flat shims to equally removed intermediate commands + +## Goals + +- Produce one exhaustive audit of authored docs that still reference removed or transitional syntax after the split. +- Update every affected doc page to either: + - use a verified current command path and parameter form, or + - remove/reframe the example when there is no direct replacement. +- Add parity checks that fail when removed syntax families reappear in authored docs. + +## Non-Goals + +- Change the runtime CLI implementation in this proposal stage +- Promise that all current CLI help prose is already canonical; some help text still contains stale wording and should not be treated as authoritative without verification +- Edit generated `docs/_site/` output directly + +## Verified Replacement Principles + +- `project plan` is not an executable `project` subcommand and must not appear as current syntax. +- Root `plan` is not installed as a workflow command in the shipped lean-core surface and must not be presented as a current workflow entrypoint. +- `project import` is now persona Markdown import, not external bridge import. +- Backlog workflows should use the current `backlog` groups such as `ceremony`, `refine`, `daily`, `auth`, `sync`, `analyze-deps`, and `verify-readiness`, not `backlog policy`. +- `govern enforce sdd [BUNDLE]` remains a valid current surface and should be documented with its current positional bundle form when examples require SDD validation. +- `spec` documentation should use the shipped Specmatic surface: `validate`, `backward-compat`, `generate-tests`, and `mock`. + +## Documentation Audit Strategy + +The implementation should use the audit inventory in `COMMAND_SYNTAX_AUDIT.md` and remediate the docs in clusters: + +1. Entry and landing docs +2. Reference and migration docs +3. Getting-started and workflow guides +4. Brownfield/examples/tutorial content +5. Prompt-oriented docs and internal command cheat sheets + +For each stale example, implementation must choose one of three outcomes: + +- Replace with a verified current command +- Reframe as historical migration context +- Remove if the workflow is no longer supported as a user-facing path + +## Validation Strategy + +Implementation should add lightweight regression checks for: + +- landing page and README ownership language +- authored-doc command syntax for removed command families +- command reference and migration pages that must route users to current group surfaces +- marketplace/reference pages that must distinguish core commands from bundle-delivered commands diff --git a/openspec/changes/docs-03-command-syntax-parity/proposal.md b/openspec/changes/docs-03-command-syntax-parity/proposal.md new file mode 100644 index 00000000..43f0f292 --- /dev/null +++ b/openspec/changes/docs-03-command-syntax-parity/proposal.md @@ -0,0 +1,40 @@ +# Change: Audit And Correct Docs Command Syntax After Core/Modules Split + +## Why + +The authored docs still contain a large amount of pre-split and transitional CLI syntax that no longer matches the executable command surface in `dev`. After the lean-core and modules split, command groups, ownership boundaries, and some parameter forms changed, but many examples in `README.md`, `docs/`, and prompt-oriented docs still point readers to removed paths such as `specfact project plan ...`, `specfact project import from-bridge ...`, `specfact backlog policy ...`, and retired `specfact spec ...` subgroup trees. + +That drift now creates direct user harm: copied commands fail, migration guidance points to non-existent groups, and docs blur the difference between current core/runtime commands and removed or relocated workflow syntax. This change establishes one audited source of truth for required doc rewrites and updates every affected authored doc page to the shipped command surface. + +## What Changes + +- Audit authored docs against the currently shipped CLI implementation and classify every stale command-syntax family introduced or exposed by the core/modules split. +- Update all affected authored docs, examples, guides, reference pages, getting-started pages, and prompt docs so command examples use current supported groups, subcommands, and parameter forms. +- Replace transitional mappings that currently point from one removed syntax family to another removed syntax family with verified current surfaces or with explicit historical context when no direct replacement exists. +- Expand lightweight docs parity coverage so future releases fail fast when authored docs reintroduce removed command groups or stale parameter examples. + +## Capabilities + +### New Capabilities + +- None. + +### Modified Capabilities + +- `documentation-alignment`: docs command examples, migration guidance, and command reference content must reflect the current executable core/bundle command topology and supported parameter forms. +- `cli-output`: docs parity validation must enforce command-syntax correctness for authored docs, not just spot-check a single reference page. + +## Impact + +- Affected docs: `README.md`, `docs/index.md`, `docs/README.md`, selected files in `docs/reference/`, `docs/getting-started/`, `docs/guides/`, `docs/examples/`, and `docs/prompts/`. +- Affected validation: docs parity tests must expand beyond current release-doc checks to guard against removed syntax families such as `project plan`, `project import from-bridge`, `backlog policy`, and retired `spec` subgroup paths. +- User-facing impact: command examples copied from docs will match the real CLI again, especially for bundle install/bootstrap, backlog workflows, bridge import/sync, project workflows, SDD enforcement, and Specmatic commands. +- Rollback plan: if a specific replacement path remains ambiguous during implementation, remove or label the example as historical context instead of publishing an unverified command. + +## Source Tracking + + +- **GitHub Issue**: pending +- **Issue URL**: pending +- **Last Synced Status**: local-proposal +- **Sanitized**: true diff --git a/openspec/changes/docs-03-command-syntax-parity/specs/cli-output/spec.md b/openspec/changes/docs-03-command-syntax-parity/specs/cli-output/spec.md new file mode 100644 index 00000000..82860a92 --- /dev/null +++ b/openspec/changes/docs-03-command-syntax-parity/specs/cli-output/spec.md @@ -0,0 +1,12 @@ +## MODIFIED Requirements + +### Requirement: Command Reference Completeness + +The system SHALL keep authored docs parity validation aligned with the shipped CLI command surfaces for each release, including checks that removed command-syntax families stay absent from authored docs. + +#### Scenario: Docs parity checks run after command-surface changes + +- **GIVEN** authored docs contain user-facing command examples in `README.md` and `docs/` +- **WHEN** docs parity validation runs for a release +- **THEN** validation fails if authored docs still reference removed or transitional syntax families such as `project plan`, `project import from-bridge`, `backlog policy`, or retired `spec` subgroup trees +- **AND** validation passes only when current docs examples align with the shipped command groups and the supported parameter forms documented for that release diff --git a/openspec/changes/docs-03-command-syntax-parity/specs/documentation-alignment/spec.md b/openspec/changes/docs-03-command-syntax-parity/specs/documentation-alignment/spec.md new file mode 100644 index 00000000..1df692ae --- /dev/null +++ b/openspec/changes/docs-03-command-syntax-parity/specs/documentation-alignment/spec.md @@ -0,0 +1,23 @@ +## MODIFIED Requirements + +### Requirement: Live docs reflect lean-core and grouped bundle command topology + +The live authored documentation set SHALL use command examples and migration guidance that match the currently shipped core and bundle command groups, and SHALL NOT present removed or transitional command families as current syntax. + +#### Scenario: Reader copies a documented command after the split + +- **WHEN** a reader copies a command from `README.md` or authored docs under `docs/` +- **THEN** the command path matches a currently shipped surface from the active CLI release +- **AND** removed or transitional syntax such as `specfact project plan ...`, `specfact project import from-bridge ...`, `specfact backlog policy ...`, or retired `specfact spec ...` subgroup trees is replaced, removed, or clearly labeled as historical context +- **AND** command examples route readers through the correct current group for that workflow area (`backlog`, `code`, `govern`, `project`, or `spec`) + +### Requirement: Command reference reflects ownership and package boundaries + +The command reference and migration guidance SHALL map old flat or pre-split syntax to currently shipped command groups and supported parameter forms, and SHALL NOT redirect readers from one removed surface to another removed surface. + +#### Scenario: Reader checks migration mapping for removed syntax + +- **WHEN** a reader opens command reference or migration guidance to translate older SpecFact examples +- **THEN** the docs identify whether a legacy surface still exists, moved to a current command group, or no longer has a direct supported equivalent +- **AND** the guidance uses currently executable commands and current option names for any documented replacement path +- **AND** the docs do not present `project plan` as the replacement for removed flat commands in the post-split CLI diff --git a/openspec/changes/docs-03-command-syntax-parity/tasks.md b/openspec/changes/docs-03-command-syntax-parity/tasks.md new file mode 100644 index 00000000..e5f0bff1 --- /dev/null +++ b/openspec/changes/docs-03-command-syntax-parity/tasks.md @@ -0,0 +1,35 @@ +## 1. Change Setup And Discovery + +- [x] 1.1 Create worktree `../specfact-cli-worktrees/feature/docs-03-command-syntax-parity` with branch `feature/docs-03-command-syntax-parity` from `origin/dev` +- [x] 1.2 Verify the shipped command surface from the active worktree using live CLI help and relevant integration tests for `init`, `module`, `backlog`, `project`, `code`, `spec`, and `govern` +- [x] 1.3 Finalize `openspec/changes/docs-03-command-syntax-parity/COMMAND_SYNTAX_AUDIT.md` so every authored doc file with stale syntax is mapped to a required rewrite outcome + +## 2. Spec Deltas First + +- [x] 2.1 Add the `documentation-alignment` spec delta covering authored-doc command examples and migration guidance +- [x] 2.2 Add the `cli-output` spec delta covering docs parity enforcement for removed syntax families +- [x] 2.3 Review every audited doc file and confirm whether each stale example should be replaced, reframed as historical context, or removed + +## 3. Validation First + +- [x] 3.1 Add failing docs parity coverage for removed syntax families across authored docs (`project plan`, `project import from-bridge`, `backlog policy`, retired `spec` subgroup trees) +- [x] 3.2 Add failing docs parity coverage for the corrected current command families and parameter forms that should remain present after remediation +- [x] 3.3 Record the failing validation evidence in `openspec/changes/docs-03-command-syntax-parity/TDD_EVIDENCE.md` + +## 4. Docs Syntax Remediation + +- [x] 4.1 Update entry and landing docs: `README.md`, `docs/index.md`, `docs/README.md` +- [x] 4.2 Update reference docs: `docs/reference/README.md`, `docs/reference/commands.md`, `docs/reference/command-syntax-policy.md`, `docs/reference/directory-structure.md`, `docs/reference/feature-keys.md` +- [x] 4.3 Update getting-started docs: `docs/getting-started/README.md`, `docs/getting-started/first-steps.md`, `docs/getting-started/installation.md`, `docs/getting-started/tutorial-openspec-speckit.md` +- [x] 4.4 Update workflow and migration guides: `docs/guides/agile-scrum-workflows.md`, `docs/guides/ai-ide-workflow.md`, `docs/guides/brownfield-journey.md`, `docs/guides/command-chains.md`, `docs/guides/common-tasks.md`, `docs/guides/competitive-analysis.md`, `docs/guides/devops-adapter-integration.md`, `docs/guides/dual-stack-enrichment.md`, `docs/guides/ide-integration.md`, `docs/guides/migration-0.16-to-0.19.md`, `docs/guides/migration-cli-reorganization.md`, `docs/guides/migration-guide.md`, `docs/guides/policy-engine-commands.md`, `docs/guides/speckit-comparison.md`, `docs/guides/speckit-journey.md`, `docs/guides/specmatic-integration.md`, `docs/guides/troubleshooting.md`, `docs/guides/use-cases.md`, `docs/guides/using-module-security-and-extensions.md`, `docs/guides/ux-features.md`, `docs/guides/workflows.md` +- [x] 4.5 Update examples and brownfield walkthroughs: `docs/examples/quick-examples.md`, `docs/examples/dogfooding-specfact-cli.md`, `docs/examples/brownfield-django-modernization.md`, `docs/examples/brownfield-data-pipeline.md`, `docs/examples/brownfield-flask-api.md` +- [x] 4.6 Update prompt-oriented docs and internal docs references: `docs/prompts/README.md`, `docs/prompts/PROMPT_VALIDATION_CHECKLIST.md` +- [x] 4.7 Review which module-specific deep docs now belong in `specfact-cli-modules/docs`, keep only core-process and core-runtime content in this repo, and add/adjust handoff language where migration is required + +## 5. Validation And Delivery + +- [x] 5.1 Re-run the targeted docs parity checks and record passing evidence in `openspec/changes/docs-03-command-syntax-parity/TDD_EVIDENCE.md` +- [x] 5.2 Run `openspec validate docs-03-command-syntax-parity --strict` +- [x] 5.3 Run the relevant repo quality gates for touched docs/test files +- [ ] 5.4 Update `CHANGELOG.md` and apply the required patch-version bump if this docs fix ships as a releaseable change +- [ ] 5.5 Open PR to `dev` from `feature/docs-03-command-syntax-parity` diff --git a/tests/unit/docs/test_release_docs_parity.py b/tests/unit/docs/test_release_docs_parity.py index f16fdf1c..255c3587 100644 --- a/tests/unit/docs/test_release_docs_parity.py +++ b/tests/unit/docs/test_release_docs_parity.py @@ -205,3 +205,16 @@ def test_current_backlog_subcommands_documented_in_commands_reference() -> None: commands_doc = _repo_file("docs/reference/commands.md").read_text(encoding="utf-8") for sub in ("backlog ceremony", "backlog refine", "backlog daily", "backlog sync"): assert sub in commands_doc, f"Current subcommand '{sub}' missing from commands reference" + + +def test_all_published_docs_markdown_files_have_jekyll_front_matter() -> None: + repo_root = Path(__file__).resolve().parents[3] + docs_root = repo_root / "docs" + missing: list[str] = [] + for path in sorted(docs_root.rglob("*.md")): + if "_site" in path.parts or "vendor" in path.parts: + continue + first_line = path.read_text(encoding="utf-8").splitlines()[0] if path.read_text(encoding="utf-8") else "" + if first_line != "---": + missing.append(str(path.relative_to(repo_root))) + assert not missing, "Docs files missing front matter:\n" + "\n".join(missing)