diff --git a/docs/guides/README.md b/docs/guides/README.md index 79d6683..36f2949 100644 --- a/docs/guides/README.md +++ b/docs/guides/README.md @@ -1,31 +1,37 @@ # Guides -Practical module-owned guides for official bundles, adapters, publishing, and deep workflow documentation. +Practical module-owned guides for official bundles, adapters, publishing, and workflow documentation. ## Available Guides -### Primary Use Case: Brownfield Modernization ⭐ +### Primary Use Case: Brownfield Modernization -- **[Brownfield Engineer Guide](brownfield-engineer.md)** ⭐ **PRIMARY** - Complete guide for modernizing legacy code -- **[The Brownfield Journey](brownfield-journey.md)** ⭐ **PRIMARY** - Step-by-step modernization workflow -- **[Brownfield ROI](brownfield-roi.md)** ⭐ - Calculate time and cost savings -- **[Brownfield FAQ](brownfield-faq.md)** ⭐ - Common questions about brownfield modernization +- **[Brownfield modernization](brownfield-modernization.md)** - End-to-end legacy modernization flow using current mounted commands +- **[Brownfield FAQ and ROI](brownfield-faq-and-roi.md)** - Planning, rollout, and investment guidance +- **[Brownfield examples](brownfield-examples.md)** - Three concrete modernization patterns -### Secondary Use Case: Spec-Kit & OpenSpec Integration +### Cross-bundle workflows -- **[Spec-Kit Journey](speckit-journey.md)** - Adding enforcement to Spec-Kit projects -- **[Spec-Kit Comparison](speckit-comparison.md)** - Understand when to use each tool -- **[OpenSpec Journey](openspec-journey.md)** 🆕 ⭐ **START HERE** - Complete integration guide with visual workflows: DevOps export (✅), bridge adapter (⏳), brownfield modernization -- **[Use Cases](use-cases.md)** - Real-world scenarios (brownfield primary, Spec-Kit secondary) +- **[Workflows](workflows.md)** - Consolidated workflow index +- **[Cross-module chains](cross-module-chains.md)** - Backlog -> code -> spec -> govern flows +- **[Daily DevOps routine](daily-devops-routine.md)** - Morning standup to end-of-day release checks +- **[CI/CD pipeline](ci-cd-pipeline.md)** - Local and CI gate order +- **[Command chains reference](command-chains.md)** - Short validated command sequences -### General Guides +### Focused workflow guides + +- **[AI IDE workflow](ai-ide-workflow.md)** - Bundle-owned prompt/template bootstrap with `specfact init ide` +- **[Contract testing workflow](contract-testing-workflow.md)** - Specmatic validate, backward compatibility, tests, and mocks +- **[Agile/Scrum workflows](agile-scrum-workflows.md)** - Backlog ceremonies and persona flows +- **[Team collaboration workflow](team-collaboration-workflow.md)** - Persona export/import and lock management + +### General guides -- **[Workflows](workflows.md)** - Common daily workflows - **[IDE Integration](ide-integration.md)** - Set up slash commands in your IDE - **[CoPilot Mode](copilot-mode.md)** - Using `--mode copilot` on CLI commands -- **[DevOps Adapter Integration](devops-adapter-integration.md)** 🆕 - Integrate with GitHub Issues, Azure DevOps, Linear, Jira for backlog tracking -- **[Backlog Refinement](backlog-refinement.md)** 🆕 **NEW FEATURE** - AI-assisted template-driven refinement for standardizing work items with persona/framework filtering, sprint/iteration support, and DoR validation -- **[Specmatic Integration](specmatic-integration.md)** - API contract testing with Specmatic (validate specs, generate tests, mock servers) +- **[DevOps Adapter Integration](devops-adapter-integration.md)** - Integrate with GitHub Issues, Azure DevOps, Linear, Jira for backlog tracking +- **[Backlog Refinement](backlog-refinement.md)** - AI-assisted template-driven refinement with filtering and DoR checks +- **[Specmatic Integration](specmatic-integration.md)** - API contract testing with Specmatic - **[Troubleshooting](troubleshooting.md)** - Common issues and solutions - **[Installing Modules](installing-modules.md)** - Install, list, show, search, enable/disable, uninstall, and upgrade modules - **[Module Marketplace](module-marketplace.md)** - Discovery priority, trust vs origin semantics, and security model @@ -33,40 +39,30 @@ Practical module-owned guides for official bundles, adapters, publishing, and de - **[Publishing modules](publishing-modules.md)** - Package, sign, and publish modules to a registry - **[Module Signing and Key Rotation](module-signing-and-key-rotation.md)** - Public key placement, signing workflow, CI verification, rotation, and revocation runbook - **[Competitive Analysis](competitive-analysis.md)** - How SpecFact compares to other tools -- **[Operational Modes](../reference/modes.md)** - CI/CD vs CoPilot modes (reference) +- **[Operational Modes](../reference/modes.md)** - CI/CD vs CoPilot modes ## Quick Start -### Modernizing Legacy Code? ⭐ PRIMARY - -1. **[Integration Showcases](../examples/integration-showcases/)** ⭐ **START HERE** - Real bugs fixed via VS Code, Cursor, GitHub Actions integrations -2. **[Brownfield Engineer Guide](brownfield-engineer.md)** ⭐ - Complete modernization guide -3. **[The Brownfield Journey](brownfield-journey.md)** ⭐ - Step-by-step workflow -4. **[Use Cases - Brownfield](use-cases.md#use-case-1-brownfield-code-modernization-primary)** ⭐ - Real-world examples - -### For IDE Users +### Modernizing legacy code -1. **[IDE Integration](ide-integration.md)** - Set up slash commands in your IDE -2. **[Use Cases](use-cases.md)** - See real-world examples +1. **[Brownfield modernization](brownfield-modernization.md)** +2. **[Brownfield examples](brownfield-examples.md)** +3. **[Cross-module chains](cross-module-chains.md)** -### For CLI Users +### Running daily delivery workflows -1. **[CoPilot Mode](copilot-mode.md)** - Using `--mode copilot` for enhanced prompts -2. **[Operational Modes](../reference/modes.md)** - Understanding CI/CD vs CoPilot modes -3. **[DevOps Adapter Integration](devops-adapter-integration.md)** 🆕 - GitHub Issues and backlog tracking -4. **[Backlog Refinement](backlog-refinement.md)** 🆕 **NEW** - AI-assisted template-driven refinement with filtering, DoR validation, and preview/write safety -5. **[Specmatic Integration](specmatic-integration.md)** - API contract testing workflow +1. **[Daily DevOps routine](daily-devops-routine.md)** +2. **[Command chains reference](command-chains.md)** +3. **[CI/CD pipeline](ci-cd-pipeline.md)** -### For Spec-Kit & OpenSpec Users (Secondary) +### Working from an IDE -1. **[Tutorial: Using SpecFact with OpenSpec or Spec-Kit](../getting-started/tutorial-openspec-speckit.md)** ⭐ **START HERE** - Complete beginner-friendly step-by-step tutorial -2. **[Spec-Kit Journey](speckit-journey.md)** - Add enforcement to Spec-Kit projects -3. **[OpenSpec Journey](openspec-journey.md)** 🆕 ⭐ - Complete OpenSpec integration guide with DevOps export and visual workflows -4. **[DevOps Adapter Integration](devops-adapter-integration.md)** 🆕 - Export change proposals to GitHub Issues -5. **[Use Cases - Spec-Kit Migration](use-cases.md#use-case-2-github-spec-kit-migration-secondary)** - Step-by-step migration +1. **[AI IDE workflow](ai-ide-workflow.md)** +2. **[IDE Integration](ide-integration.md)** +3. **[Workflows](workflows.md)** -## Need Help? +### Contract-focused work -- 💬 [GitHub Discussions](https://github.com/nold-ai/specfact-cli/discussions) -- 🐛 [GitHub Issues](https://github.com/nold-ai/specfact-cli/issues) -- 📧 [hello@noldai.com](mailto:hello@noldai.com) +1. **[Contract testing workflow](contract-testing-workflow.md)** +2. **[Specmatic Integration](specmatic-integration.md)** +3. **[Spec bundle overview](/bundles/spec/overview/)** diff --git a/docs/guides/ai-ide-workflow.md b/docs/guides/ai-ide-workflow.md index 07c3384..5287a71 100644 --- a/docs/guides/ai-ide-workflow.md +++ b/docs/guides/ai-ide-workflow.md @@ -6,29 +6,56 @@ redirect_from: - /guides/ai-ide-workflow/ --- -# Legacy Workflow Note +# AI IDE Workflow Guide -This page described older `specfact plan`, `specfact generate`, `specfact contract`, or `specfact sdd constitution` workflows that are not part of the current public mounted CLI in this repository. The detailed command examples previously documented here were removed because they no longer match the command surface exposed by `specfact --help`. +This guide covers the current IDE-assisted workflow for bundle-owned prompts and templates. The key rule is simple: bootstrap resources through the CLI, not by copying files from legacy core-owned paths. -Use the current mounted entrypoints instead: +## 1. Bootstrap the repository and IDE resources -- `specfact project --help` -- `specfact project sync --help` -- `specfact code --help` -- `specfact code review --help` -- `specfact spec --help` -- `specfact govern --help` -- `specfact backlog --help` -- `specfact module --help` +```bash +specfact init --profile solo-developer +specfact init ide --repo . --ide cursor +``` + +`specfact init ide` exports prompts from core plus installed modules. Re-run it after bundle upgrades or when you install an additional workflow bundle. -When you need exact syntax, verify against live help in the current release, for example: +## 2. Confirm the modules that own the prompts you need ```bash -specfact project sync bridge --help -specfact code repro --help -specfact code validate sidecar --help -specfact spec validate --help -specfact govern enforce --help +specfact module install nold-ai/specfact-backlog +specfact module install nold-ai/specfact-govern +specfact module install nold-ai/specfact-code-review ``` -This page needs a full rewrite around the mounted command groups before task-level workflow examples can be published again. +Typical ownership: + +- Backlog refinement and ceremony prompts come from the Backlog bundle +- Govern presets and policy-oriented prompt flows come from the Govern bundle +- Review house-rules flows come from the Code Review bundle + +## 3. Run the CLI step that emits or consumes the prompt + +Examples: + +```bash +specfact backlog ceremony refinement github --preview --labels feature +specfact code review run src --scope changed --no-tests +specfact project sync bridge --adapter github --mode export-only --repo . --bundle legacy-api +``` + +These commands are the source of truth. The IDE should support them, not replace them. + +## 4. Refresh resources after upgrades + +```bash +specfact module upgrade --all +specfact init ide --repo . --ide cursor --force +``` + +Use `--force` when you intentionally want regenerated editor files to replace the previous export. + +## Related + +- [Workflows index](/workflows/) +- [Cross-module chains](/guides/cross-module-chains/) +- [Backlog bundle overview](/bundles/backlog/overview/) diff --git a/docs/guides/brownfield-engineer.md b/docs/guides/brownfield-engineer.md index 0eb6e88..cb9a640 100644 --- a/docs/guides/brownfield-engineer.md +++ b/docs/guides/brownfield-engineer.md @@ -4,20 +4,5 @@ title: Modernizing Legacy Code (Brownfield Engineer Guide) permalink: /brownfield-engineer/ redirect_from: - /guides/brownfield-engineer/ +redirect_to: /guides/brownfield-modernization/ --- - -# Legacy Workflow Note - -This page referenced command groups or workflow steps that are no longer part of the current public mounted CLI in this repository. The old examples were removed to avoid directing readers to unavailable commands. - -Use the current mounted entrypoints instead: - -- `specfact project --help` -- `specfact project sync --help` -- `specfact code --help` -- `specfact code review --help` -- `specfact spec --help` -- `specfact govern --help` -- `specfact backlog --help` - -For exact syntax, verify against live help in the current release before copying examples. diff --git a/docs/guides/brownfield-examples.md b/docs/guides/brownfield-examples.md new file mode 100644 index 0000000..b87ba77 --- /dev/null +++ b/docs/guides/brownfield-examples.md @@ -0,0 +1,51 @@ +--- +layout: default +title: Brownfield Examples +permalink: /guides/brownfield-examples/ +--- + +# Brownfield Examples + +These examples give you three concrete modernization patterns you can adapt without relying on the removed legacy `docs/examples` tree. + +## Example 1. Legacy API intake + +Use this when an undocumented repository needs a bundle baseline before any release work: + +```bash +specfact code import legacy-api --repo . +specfact code analyze contracts --repo . --bundle legacy-api +specfact spec validate --bundle legacy-api +``` + +Outcome: the team gets a project bundle, contract visibility, and an initial validation pass. + +## Example 2. Backlog to modernization handoff + +Use this when backlog items must be refined before the modernization work is synchronized or exported: + +```bash +specfact backlog ceremony refinement github --preview --labels feature +specfact backlog verify-readiness --adapter github --project-id owner/repo --target-items 123 +specfact project sync bridge --adapter github --mode export-only --repo . --bundle legacy-api +``` + +Outcome: backlog items are standardized before they drive bundle changes. + +## Example 3. Promotion gate for a risky refactor + +Use this when a refactor changed contracts or bundle state and you need a release gate: + +```bash +specfact spec backward-compat api/openapi.yaml --previous api/openapi.v1.yaml +specfact spec generate-tests api/openapi.yaml +specfact govern enforce sdd legacy-api --no-interactive +``` + +Outcome: compatibility, generated test artifacts, and bundle enforcement are checked in one flow. + +## Related + +- [Brownfield modernization](/guides/brownfield-modernization/) +- [Cross-module chains](/guides/cross-module-chains/) +- [Contract testing workflow](/guides/contract-testing-workflow/) diff --git a/docs/guides/brownfield-faq-and-roi.md b/docs/guides/brownfield-faq-and-roi.md new file mode 100644 index 0000000..8e12616 --- /dev/null +++ b/docs/guides/brownfield-faq-and-roi.md @@ -0,0 +1,66 @@ +--- +layout: default +title: Brownfield FAQ and ROI +permalink: /guides/brownfield-faq-and-roi/ +--- + +# Brownfield FAQ and ROI + +This page merges the brownfield FAQ and ROI guidance into one planning reference. + +## What is the minimum safe starting point? + +Start with a project bundle plus IDE resource bootstrap: + +```bash +specfact init --profile solo-developer +specfact init ide --repo . --ide cursor +specfact code import legacy-api --repo . +``` + +That gives you a repeatable baseline without needing to modernize the whole codebase at once. + +## How should teams estimate the effort? + +A practical sequence is: + +1. Import the repo into a bundle. +2. Analyze current contract coverage. +3. Validate the contracts you already have. +4. Add enforcement only when the bundle state is stable enough for promotion. + +The commands that anchor those phases are: + +```bash +specfact code analyze contracts --repo . --bundle legacy-api +specfact spec validate --bundle legacy-api +specfact govern enforce sdd legacy-api --no-interactive +``` + +## Where does the ROI usually appear first? + +The earliest gains usually come from: + +- faster understanding of legacy structure after `code import` +- less manual contract drift checking once `spec validate` is in the loop +- fewer late-stage release surprises when `govern enforce sdd` becomes part of promotion + +## How do teams avoid drift between CLI and IDE resources? + +Refresh exported IDE assets from the installed bundles instead of storing copied prompt files: + +```bash +specfact init ide --repo . --ide cursor --force +``` + +## When is the workflow worth formalizing in CI? + +Once the team is repeatedly running local validation and enforcement, move the same sequence into CI so release checks are deterministic. + +See [CI/CD pipeline](/guides/ci-cd-pipeline/) for the repository gate order. + +## Related + +- [Brownfield modernization](/guides/brownfield-modernization/) +- [Brownfield examples](/guides/brownfield-examples/) +- [Daily DevOps routine](/guides/daily-devops-routine/) diff --git a/docs/guides/brownfield-faq.md b/docs/guides/brownfield-faq.md index 09cb8d3..43029c4 100644 --- a/docs/guides/brownfield-faq.md +++ b/docs/guides/brownfield-faq.md @@ -4,374 +4,5 @@ title: Brownfield Modernization FAQ permalink: /brownfield-faq/ redirect_from: - /guides/brownfield-faq/ +redirect_to: /guides/brownfield-faq-and-roi/ --- - -# Brownfield Modernization FAQ - -> **Frequently asked questions about using SpecFact CLI for legacy code modernization** - ---- - -## General Questions - -### What is brownfield modernization? - -**Brownfield modernization** refers to improving, refactoring, or migrating existing (legacy) codebases, as opposed to greenfield development (starting from scratch). - -SpecFact CLI is designed specifically for brownfield projects where you need to: - -- Understand undocumented legacy code -- Modernize without breaking existing behavior -- Extract specs from existing code (code2spec) -- Enforce contracts during refactoring - ---- - -## Code Analysis - -### Can SpecFact analyze code with no docstrings? - -**Yes.** SpecFact's code2spec analyzes: - -- Function signatures and type hints -- Code patterns and control flow -- Existing validation logic -- Module dependencies -- Commit history and code structure - -No docstrings needed. SpecFact infers behavior from code patterns. - -### What if the legacy code has no type hints? - -**SpecFact infers types** from usage patterns and generates specs. You can add type hints incrementally as part of modernization. - -**Example:** - -```python -# Legacy code (no type hints) -def process_order(user_id, amount): - # SpecFact infers: user_id: int, amount: float - ... - -# SpecFact generates: -# - Precondition: user_id > 0, amount > 0 -# - Postcondition: returns Order object -``` - -### Can SpecFact handle obfuscated or minified code? - -**Limited.** SpecFact works best with: - -- Source code (not compiled bytecode) -- Readable variable names -- Standard Python patterns - -For heavily obfuscated code, consider: - -1. Deobfuscation first (if possible) -2. Manual documentation of critical paths -3. Adding contracts incrementally to deobfuscated sections - -### What about code with no tests? - -**SpecFact doesn't require tests.** In fact, code2spec is designed for codebases with: - -- No tests -- No documentation -- No type hints - -SpecFact extracts specs from code structure and patterns, not from tests. - ---- - -## Contract Enforcement - -### Will contracts slow down my code? - -**Minimal impact.** Contract checks are fast (microseconds per call). For high-performance code: - -- **Development/Testing:** Keep contracts enabled (catch violations) -- **Production:** Optionally disable contracts (performance-critical paths only) - -**Best practice:** Keep contracts in tests, disable only in production hot paths if needed. - -### Can I add contracts incrementally? - -**Yes.** Recommended approach: - -1. **Week 1:** Add contracts to 3-5 critical functions -2. **Week 2:** Expand to 10-15 functions -3. **Week 3:** Add contracts to all public APIs -4. **Week 4+:** Add contracts to internal functions as needed - -Start with shadow mode (observe only), then enable enforcement incrementally. - -### What if a contract is too strict? - -**Contracts are configurable.** You can: - -- **Relax contracts:** Adjust preconditions/postconditions to match actual behavior -- **Shadow mode:** Observe violations without blocking -- **Warn mode:** Log violations but don't raise exceptions -- **Block mode:** Raise exceptions on violations (default) - -Start in shadow mode, then tighten as you understand the code better. - ---- - -## Edge Case Discovery - -### How does CrossHair discover edge cases? - -**CrossHair uses symbolic execution** to explore all possible code paths mathematically. It: - -1. Represents inputs symbolically (not concrete values) -2. Explores all feasible execution paths -3. Finds inputs that violate contracts -4. Generates concrete test cases for violations - -**Example:** - -```python -@icontract.require(lambda numbers: len(numbers) > 0) -@icontract.ensure(lambda numbers, result: min(numbers) > result) -def remove_smallest(numbers: List[int]) -> int: - smallest = min(numbers) - numbers.remove(smallest) - return smallest - -# CrossHair finds: [3, 3, 5] violates postcondition -# (duplicates cause min(numbers) == result after removal) -``` - -### Can CrossHair find all edge cases? - -**No tool can find all edge cases**, but CrossHair is more thorough than: - -- Manual testing (limited by human imagination) -- Random testing (limited by coverage) -- LLM suggestions (probabilistic, not exhaustive) - -CrossHair provides **mathematical guarantees** for explored paths, but complex code may have paths that are computationally infeasible to explore. - -### How long does CrossHair take? - -**Typically 10-60 seconds per function**, depending on: - -- Function complexity -- Number of code paths -- Contract complexity - -For large codebases, run CrossHair on critical functions first, then expand. - ---- - -## Modernization Workflow - -### How do I start modernizing safely? - -**Recommended workflow:** - -1. **Extract specs** (`specfact code import`) -2. **Add contracts** to 3-5 critical functions -3. **Run CrossHair** to discover edge cases -4. **Refactor incrementally** (one function at a time) -5. **Verify contracts** still pass after refactoring -6. **Expand contracts** to more functions - -Start in shadow mode, then enable enforcement as you gain confidence. - -### What if I break a contract during refactoring? - -**That's the point!** Contracts catch regressions immediately: - -```python -# Refactored code violates contract -process_payment(user_id=-1, amount=-50, currency="XYZ") - -# Contract violation caught: -# ❌ ContractViolation: Payment amount must be positive (got -50) -# → Fix the bug before it reaches production! -``` - -Contracts are your **safety net** - they prevent breaking changes from being deployed. - -### Can I use SpecFact with existing test suites? - -**Yes.** SpecFact complements existing tests: - -- **Tests:** Verify specific scenarios -- **Contracts:** Enforce behavior at API boundaries -- **CrossHair:** Discover edge cases tests miss - -Use all three together for comprehensive coverage. - -### What's the learning curve for contract-first development? - -**Minimal.** SpecFact is designed for incremental adoption: - -**Week 1 (2-4 hours):** - -- Run `specfact code import` to extract specs (10 seconds) -- Review extracted project bundle -- Add contracts to 3-5 critical functions - -**Week 2 (4-6 hours):** - -- Expand contracts to 10-15 functions -- Run CrossHair on critical paths -- Set up pre-commit hook - -**Week 3+ (ongoing):** - -- Add contracts incrementally as you refactor -- Use shadow mode to observe violations -- Enable enforcement when confident - -**No upfront training required.** Start with shadow mode (observe only), then enable enforcement incrementally as you understand the code better. - -**Resources:** - -- [Brownfield Engineer Guide](brownfield-engineer.md) - Complete walkthrough -- [Integration Showcases](../examples/integration-showcases/) - Real examples -- [Getting Started](../getting-started/README.md) - Quick start guide - ---- - -## Integration - -### Does SpecFact work with GitHub Spec-Kit? - -**Yes.** SpecFact complements Spec-Kit: - -- **Spec-Kit:** Interactive spec authoring (greenfield) -- **SpecFact:** Automated enforcement + brownfield support - -**Use both together:** - -1. Use Spec-Kit for initial spec generation (fast, LLM-powered) -2. Use SpecFact to add runtime contracts to critical paths (safety net) -3. Spec-Kit generates docs, SpecFact prevents regressions - -See [Spec-Kit Comparison Guide](speckit-comparison.md) for details. - -### Can I use SpecFact in CI/CD? - -**Yes.** SpecFact integrates with: - -- **GitHub Actions:** PR annotations, contract validation -- **GitLab CI:** Pipeline integration -- **Jenkins:** Plugin support (planned) -- **Local CI:** Run `specfact govern enforce` in your pipeline - -Contracts can block merges if violations are detected (configurable). - -### Does SpecFact work with VS Code, Cursor, or other IDEs? - -**Yes.** SpecFact's CLI-first design means it works with **any IDE or editor**: - -- **VS Code:** Pre-commit hooks, tasks, or extensions -- **Cursor:** AI assistant integration with contract validation -- **Any editor:** Pure CLI, no IDE lock-in required -- **Agentic workflows:** Works with any AI coding assistant - -**Example VS Code integration:** - -```bash -# .git/hooks/pre-commit -#!/bin/sh -uvx specfact-cli@latest govern enforce stage --preset balanced -``` - -**Example Cursor integration:** - -```bash -# Validate AI suggestions before accepting -cursor-agent --validate-with "uvx specfact-cli@latest enforce stage" -``` - -See [Integration Showcases](../examples/integration-showcases/) for real examples of bugs caught via different integrations. - -### Do I need to learn a new platform? - -**No.** SpecFact is **CLI-first**—it integrates into your existing workflow: - -- ✅ Works with your current IDE (VS Code, Cursor, etc.) -- ✅ Works with your current CI/CD (GitHub Actions, GitLab, etc.) -- ✅ Works with your current tools (no new platform to learn) -- ✅ Works offline (no cloud account required) -- ✅ Zero vendor lock-in (OSS forever) - -**No platform migration needed.** Just add SpecFact CLI to your existing workflow. - ---- - -## Performance - -### How fast is code2spec extraction? - -**Typical timing**: - -- **Small codebases** (10-50 files): ~10 seconds to 1-2 minutes -- **Medium codebases** (50-100 files): ~1-2 minutes -- **Large codebases** (100+ files): **2-3 minutes** for AST + Semgrep analysis -- **Large codebases with contracts** (100+ files): **15-30+ minutes** with contract extraction, graph analysis, and parallel processing (8 workers) - -The import process performs AST analysis, Semgrep pattern detection, and (when enabled) extracts OpenAPI contracts, relationships, and graph dependencies in parallel, which can take significant time for large repositories. - -### Does SpecFact require internet? - -**No.** SpecFact works 100% offline: - -- No cloud services required -- No API keys needed -- No telemetry (opt-in only) -- Fully local execution - -Perfect for air-gapped environments or sensitive codebases. - ---- - -## Limitations - -### What are SpecFact's limitations? - -**Known limitations:** - -1. **Python-only** (JavaScript/TypeScript support planned Q1 2026) -2. **Source code required** (not compiled bytecode) -3. **Readable code preferred** (obfuscated code may have lower accuracy) -4. **Complex contracts** may slow CrossHair (timeout configurable) - -**What SpecFact does well:** - -- ✅ Extracts specs from undocumented code -- ✅ Enforces contracts at runtime -- ✅ Discovers edge cases with symbolic execution -- ✅ Prevents regressions during modernization - ---- - -## Support - -### Where can I get help? - -- 💬 [GitHub Discussions](https://github.com/nold-ai/specfact-cli/discussions) - Ask questions -- 🐛 [GitHub Issues](https://github.com/nold-ai/specfact-cli/issues) - Report bugs -- 📧 [hello@noldai.com](mailto:hello@noldai.com) - Direct support - -### Can I contribute? - -**Yes!** SpecFact is open source. See [CONTRIBUTING.md](https://github.com/nold-ai/specfact-cli/blob/main/CONTRIBUTING.md) for guidelines. - ---- - -## Next Steps - -1. **[Brownfield Engineer Guide](brownfield-engineer.md)** - Complete modernization workflow -2. **[ROI Calculator](brownfield-roi.md)** - Calculate your savings -3. **[Examples](../examples/)** - Real-world brownfield examples - ---- - -**Still have questions?** [Open a discussion](https://github.com/nold-ai/specfact-cli/discussions) or [email us](mailto:hello@noldai.com). diff --git a/docs/guides/brownfield-journey.md b/docs/guides/brownfield-journey.md index 63d62b7..aef4846 100644 --- a/docs/guides/brownfield-journey.md +++ b/docs/guides/brownfield-journey.md @@ -4,20 +4,5 @@ title: Brownfield Modernization Journey permalink: /brownfield-journey/ redirect_from: - /guides/brownfield-journey/ +redirect_to: /guides/brownfield-modernization/ --- - -# Legacy Workflow Note - -This page referenced command groups or workflow steps that are no longer part of the current public mounted CLI in this repository. The old examples were removed to avoid directing readers to unavailable commands. - -Use the current mounted entrypoints instead: - -- `specfact project --help` -- `specfact project sync --help` -- `specfact code --help` -- `specfact code review --help` -- `specfact spec --help` -- `specfact govern --help` -- `specfact backlog --help` - -For exact syntax, verify against live help in the current release before copying examples. diff --git a/docs/guides/brownfield-modernization.md b/docs/guides/brownfield-modernization.md new file mode 100644 index 0000000..02c570f --- /dev/null +++ b/docs/guides/brownfield-modernization.md @@ -0,0 +1,72 @@ +--- +layout: default +title: Brownfield Modernization +permalink: /guides/brownfield-modernization/ +--- + +# Brownfield Modernization + +This guide consolidates the previous brownfield engineer and journey pages into one current flow based on the command surface that ships in this repository. + +## 1. Prepare the repository and installed resources + +```bash +specfact init --profile solo-developer +specfact init ide --repo . --ide cursor +``` + +The IDE bootstrap matters because backlog refinement, review prompts, and other workflow resources are bundle-owned payloads. Do not rely on legacy prompt files outside the installed modules. + +## 2. Import the legacy codebase into a project bundle + +```bash +specfact code import legacy-api --repo . +``` + +This creates or refreshes the project bundle that the later workflow stages use. + +## 3. Analyze contract and validation coverage + +```bash +specfact code analyze contracts --repo . --bundle legacy-api +``` + +Use this to identify where the codebase already has contract signals and where modernization work still needs enforcement. + +## 4. Sync or export project state when outside tools are involved + +```bash +specfact project sync bridge --adapter github --mode export-only --repo . --bundle legacy-api +``` + +Use the bridge layer when you need to exchange bundle state with GitHub, Azure DevOps, OpenSpec, or another supported adapter. + +## 5. Validate the extracted or maintained contracts + +```bash +specfact spec validate --bundle legacy-api --force +``` + +If you are working from a single contract file instead of a bundle, validate that file directly with `specfact spec validate api/openapi.yaml`. + +## 6. Enforce readiness before promotion + +```bash +specfact govern enforce sdd legacy-api --no-interactive +``` + +Run this before promotion or release to ensure the bundle, manifest, and contract state still agree. + +## Suggested cadence + +1. Import and analyze first. +2. Add or refine contracts where the analysis shows gaps. +3. Validate contracts after every meaningful refactor. +4. Use bridge sync only when external tools must stay aligned. +5. Run SDD enforcement before promotion, release, or handoff. + +## Related + +- [Brownfield FAQ and ROI](/guides/brownfield-faq-and-roi/) +- [Brownfield examples](/guides/brownfield-examples/) +- [Codebase bundle overview](/bundles/codebase/overview/) diff --git a/docs/guides/brownfield-roi.md b/docs/guides/brownfield-roi.md index 3e31f8e..8b1368c 100644 --- a/docs/guides/brownfield-roi.md +++ b/docs/guides/brownfield-roi.md @@ -4,229 +4,5 @@ title: Brownfield Modernization ROI with SpecFact permalink: /brownfield-roi/ redirect_from: - /guides/brownfield-roi/ +redirect_to: /guides/brownfield-faq-and-roi/ --- - -# Brownfield Modernization ROI with SpecFact - -> **Calculate your time and cost savings when modernizing legacy Python code** - -**CLI-First Approach**: SpecFact works offline, requires no account, and integrates with your existing workflow (VS Code, Cursor, GitHub Actions, pre-commit hooks). No platform to learn, no vendor lock-in. - ---- - -## ROI Calculator - -Use this calculator to estimate your savings when using SpecFact CLI for brownfield modernization. - -### Input Your Project Size - -**Number of Python files in legacy codebase:** `[____]` -**Average lines of code per file:** `[____]` -**Hourly rate:** `$[____]` per hour - ---- - -## Manual Approach (Baseline) - -### Time Investment - -| Task | Time (Hours) | Cost | -|------|-------------|------| -| **Documentation** | | | -| - Manually document legacy code | `[files] × 1.5-2.5 hours` | `$[____]` | -| - Write API documentation | `[endpoints] × 2-4 hours` | `$[____]` | -| - Create architecture diagrams | `8-16 hours` | `$[____]` | -| **Testing** | | | -| - Write tests for undocumented code | `[files] × 2-3 hours` | `$[____]` | -| - Manual edge case discovery | `20-40 hours` | `$[____]` | -| **Modernization** | | | -| - Debug regressions during refactor | `40-80 hours` | `$[____]` | -| - Fix production bugs from modernization | `20-60 hours` | `$[____]` | -| **TOTAL** | **`[____]` hours** | **`$[____]`** | - -### Example: 50-File Legacy App - -| Task | Time (Hours) | Cost (@$150/hr) | -|------|-------------|-----------------| -| Manually document 50-file legacy app | 80-120 hours | $12,000-$18,000 | -| Write tests for undocumented code | 100-150 hours | $15,000-$22,500 | -| Debug regression during refactor | 40-80 hours | $6,000-$12,000 | -| **TOTAL** | **220-350 hours** | **$33,000-$52,500** | - ---- - -## SpecFact Automated Approach - -### Time Investment (Automated) - -| Task | Time (Hours) | Cost | -|------|-------------|------| -| **Documentation** | | | -| - Run code2spec extraction | `0.17 hours (10 min)` | `$[____]` | -| - Review and refine extracted specs | `8-16 hours` | `$[____]` | -| **Contract Enforcement** | | | -| - Add contracts to critical paths | `16-24 hours` | `$[____]` | -| - CrossHair edge case discovery | `2-4 hours` | `$[____]` | -| **Modernization** | | | -| - Refactor with contract safety net | `[baseline] × 0.5-0.7` | `$[____]` | -| - Fix regressions (prevented by contracts) | `0-10 hours` | `$[____]` | -| **TOTAL** | **`[____]` hours** | **`$[____]`** | - -### Example: 50-File Legacy App (Automated Results) - -| Task | Time (Hours) | Cost (@$150/hr) | -|------|-------------|-----------------| -| Run code2spec extraction | 0.17 hours (10 min) | $25 | -| Review and refine extracted specs | 8-16 hours | $1,200-$2,400 | -| Add contracts to critical paths | 16-24 hours | $2,400-$3,600 | -| CrossHair edge case discovery | 2-4 hours | $300-$600 | -| **TOTAL** | **26-44 hours** | **$3,925-$6,625** | - ---- - -## ROI Calculation - -### Time Savings - -**Manual approach:** `[____]` hours -**SpecFact approach:** `[____]` hours -**Time saved:** `[____]` hours (**`[____]%`** reduction) - -### Cost Savings - -**Manual approach:** `$[____]` -**SpecFact approach:** `$[____]` -**Cost avoided:** `$[____]` (**`[____]%`** reduction) - -### Example: 50-File Legacy App (Results) - -**Time saved:** 194-306 hours (**87%** reduction) -**Cost avoided:** $26,075-$45,875 (**87%** reduction) - ---- - -## Industry Benchmarks - -### IBM GenAI Modernization Study - -- **70% cost reduction** via automated code discovery -- **50% faster** feature delivery -- **95% reduction** in manual effort - -### SpecFact Alignment - -SpecFact's code2spec provides similar automation: - -- **87% time saved** on documentation (vs. manual) -- **100% detection rate** for contract violations (vs. manual review) -- **6-12 edge cases** discovered automatically (vs. 0-2 manually) - ---- - -## Additional Benefits (Not Quantified) - -### Quality Improvements - -- ✅ **Zero production bugs** from modernization (contracts prevent regressions) -- ✅ **100% API documentation** coverage (extracted automatically) -- ✅ **Hidden edge cases** discovered before production (CrossHair) - -### Team Productivity - -- ✅ **60% faster** developer onboarding (documented codebase) -- ✅ **50% reduction** in code review time (contracts catch issues) -- ✅ **Zero debugging time** for contract violations (caught at runtime) - -### Risk Reduction - -- ✅ **Formal guarantees** vs. probabilistic LLM suggestions -- ✅ **Mathematical verification** vs. manual code review -- ✅ **Safety net** during modernization (contracts enforce behavior) - ---- - -## Real-World Case Studies - -### Case Study 1: Data Pipeline Modernization - -**Challenge:** - -- 5-year-old Python data pipeline (12K LOC) -- No documentation, original developers left -- Needed modernization from Python 2.7 → 3.12 -- Fear of breaking critical ETL jobs - -**Solution:** - -1. Ran `specfact code import` → 47 features extracted in 12 seconds -2. Added contracts to 23 critical data transformation functions -3. CrossHair discovered 6 edge cases in legacy validation logic -4. Enforced contracts during migration, blocked 11 regressions -5. Integrated with GitHub Actions CI/CD to prevent bad code from merging - -**Results:** - -- ✅ 87% faster documentation (8 hours vs. 60 hours manual) -- ✅ 11 production bugs prevented during migration -- ✅ Zero downtime migration completed in 3 weeks vs. estimated 8 weeks -- ✅ New team members productive in days vs. weeks - -**ROI:** $42,000 saved, 5-week acceleration - -### Case Study 2: Integration Success Stories - -**See real examples of bugs fixed via integrations:** - -- **[Integration Showcases](../examples/integration-showcases/)** - 5 complete examples: - - VS Code + Pre-commit: Async bug caught before commit - - Cursor Integration: Regression prevented during refactoring - - GitHub Actions: Type mismatch blocked from merging - - Pre-commit Hook: Breaking change detected locally - - Agentic Workflows: Edge cases discovered with symbolic execution - -**Key Finding**: 3 of 5 examples fully validated, showing real bugs fixed through CLI integrations. - ---- - -## When ROI Is Highest - -SpecFact provides maximum ROI for: - -- ✅ **Large codebases** (50+ files) - More time saved on documentation -- ✅ **Undocumented code** - Manual documentation is most expensive -- ✅ **High-risk systems** - Contract enforcement prevents costly production bugs -- ✅ **Complex business logic** - CrossHair discovers edge cases manual testing misses -- ✅ **Team modernization** - Faster onboarding = immediate productivity gains - ---- - -## Try It Yourself - -Calculate your ROI: - -1. **Run code2spec** on your legacy codebase: - - ```bash - specfact code import legacy-api --repo ./your-legacy-app - ``` - -2. **Time the extraction** (typically < 10 seconds) - -3. **Compare to manual documentation time** (typically 1.5-2.5 hours per file) - -4. **Calculate your savings:** - - Time saved = (files × 1.5 hours) - 0.17 hours - - Cost saved = Time saved × hourly rate - ---- - -## Next Steps - -1. **[Integration Showcases](../examples/integration-showcases/)** - See real bugs fixed via VS Code, Cursor, GitHub Actions integrations -2. **[Brownfield Engineer Guide](brownfield-engineer.md)** - Complete modernization workflow -3. **[Brownfield Journey](brownfield-journey.md)** - Step-by-step modernization guide -4. **[Examples](../examples/)** - Real-world brownfield examples - ---- - -**Questions?** [GitHub Discussions](https://github.com/nold-ai/specfact-cli/discussions) | [hello@noldai.com](mailto:hello@noldai.com) diff --git a/docs/guides/ci-cd-pipeline.md b/docs/guides/ci-cd-pipeline.md new file mode 100644 index 0000000..54144a5 --- /dev/null +++ b/docs/guides/ci-cd-pipeline.md @@ -0,0 +1,73 @@ +--- +layout: default +title: CI/CD Pipeline +permalink: /guides/ci-cd-pipeline/ +--- + +# CI/CD Pipeline + +This guide maps the repository quality gates to a workflow you can run locally and in GitHub Actions. + +## 1. Keep local resources aligned + +When workflow prompts or templates are bundle-owned, refresh the IDE export after module changes: + +```bash +specfact init ide --repo . --ide cursor --force +``` + +Install the repository hooks locally so the same guardrails run before you push: + +```bash +pre-commit install +pre-commit run --all-files +``` + +## 2. Run the repository quality gates locally + +The repository gate order is: + +```bash +hatch run format +hatch run type-check +hatch run lint +hatch run yaml-lint +hatch run verify-modules-signature --require-signature --payload-from-filesystem --enforce-version-bump +hatch run contract-test +hatch run smart-test +hatch run test +``` + +Use the same order locally before pushing changes that affect docs, bundles, or registry metadata. + +## 2.1 CI/CD stage mapping + +Map the local commands to the pipeline stages this repository enforces: + +- Pre-commit stage: `pre-commit run --all-files` +- Quality gates stage: `hatch run format` -> `hatch run type-check` -> `hatch run lint` -> `hatch run yaml-lint` +- Release-readiness stage: `hatch run verify-modules-signature --require-signature --payload-from-filesystem --enforce-version-bump` +- Validation stage: `hatch run contract-test` -> `hatch run smart-test` -> `hatch run test` + +## 3. Add scoped workflow checks while developing + +```bash +specfact code review run docs/guides/cross-module-chains.md --no-tests +specfact govern enforce sdd legacy-api --no-interactive +``` + +These commands complement the repository gates when your branch specifically changes workflow docs or bundle enforcement behavior. + +## 4. Build the docs site before publishing + +```bash +bundle exec jekyll build --destination ../_site +``` + +Run this when you changed published documentation so link, redirect, and front-matter issues are caught before PR review. + +## Related + +- [Workflows index](/workflows/) +- [Command reference](/reference/commands/) +- [Cross-module chains](/guides/cross-module-chains/) diff --git a/docs/guides/command-chains.md b/docs/guides/command-chains.md index 1f1055a..5c512f8 100644 --- a/docs/guides/command-chains.md +++ b/docs/guides/command-chains.md @@ -4,29 +4,83 @@ title: Command Chains Reference permalink: /guides/command-chains/ --- -# Legacy Workflow Note +# Command Chains Reference -This page described older `specfact plan`, `specfact generate`, `specfact contract`, or `specfact sdd constitution` workflows that are not part of the current public mounted CLI in this repository. The detailed command examples previously documented here were removed because they no longer match the command surface exposed by `specfact --help`. +Use this page when you need a short, validated command chain for a common task. Each chain uses current mounted commands and links to the deeper workflow guide that explains the decision points. -Use the current mounted entrypoints instead: +## 1. Bootstrap a workflow-ready repository -- `specfact project --help` -- `specfact project sync --help` -- `specfact code --help` -- `specfact code review --help` -- `specfact spec --help` -- `specfact govern --help` -- `specfact backlog --help` -- `specfact module --help` +```bash +specfact init --profile solo-developer +specfact init ide --repo . --ide cursor +specfact module install nold-ai/specfact-backlog +``` + +Use this before any workflow that depends on bundle-owned prompts or templates. + +Related: [AI IDE workflow](/guides/ai-ide-workflow/) -When you need exact syntax, verify against live help in the current release, for example: +## 2. Brownfield intake and contract discovery ```bash -specfact project sync bridge --help -specfact code repro --help -specfact code validate sidecar --help -specfact spec validate --help -specfact govern enforce --help +specfact code import legacy-api --repo . +specfact code analyze contracts --repo . --bundle legacy-api +specfact spec validate --bundle legacy-api --force ``` -This page needs a full rewrite around the mounted command groups before task-level workflow examples can be published again. +Use this when you need a project bundle, contract-coverage visibility, and a first validation pass for a legacy codebase. + +Related: [Brownfield modernization](/guides/brownfield-modernization/) + +## 3. Refine backlog work before sync/export + +```bash +specfact backlog ceremony refinement github --preview --labels feature +specfact backlog verify-readiness --adapter github --project-id owner/repo --target-items 123 +specfact project sync bridge --adapter github --mode export-only --repo . --bundle legacy-api +``` + +Use this chain when backlog items must be standardized and readiness-checked before you export or sync them into project artifacts. + +Related: [Cross-module chains](/guides/cross-module-chains/) + +## 4. Specmatic validation and compatibility + +```bash +specfact spec validate api/openapi.yaml +specfact spec backward-compat api/openapi.yaml --previous api/openapi.v1.yaml +specfact spec generate-tests api/openapi.yaml +``` + +Use this chain when you are validating a contract update and need generated test coverage before release review. + +Related: [Contract testing workflow](/guides/contract-testing-workflow/) + +## 5. Daily review and cleanup + +```bash +specfact backlog ceremony standup github +specfact code review run docs/guides/cross-module-chains.md --no-tests +specfact govern enforce sdd legacy-api --no-interactive +``` + +Use this chain to review backlog state, run a scoped quality review, and validate release readiness on a bundle before you stop for the day. + +Related: [Daily DevOps routine](/guides/daily-devops-routine/) + +## 6. CI-ready local gate run + +```bash +hatch run format +hatch run type-check +hatch run lint +hatch run yaml-lint +hatch run verify-modules-signature --require-signature --payload-from-filesystem --enforce-version-bump +hatch run contract-test +hatch run smart-test +hatch run test +``` + +Use this chain as the full required pre-push gate order so the local run matches the repository CI quality gates. + +Related: [CI/CD pipeline](/guides/ci-cd-pipeline/) diff --git a/docs/guides/contract-testing-workflow.md b/docs/guides/contract-testing-workflow.md index 2872fa4..0ba3b8d 100644 --- a/docs/guides/contract-testing-workflow.md +++ b/docs/guides/contract-testing-workflow.md @@ -6,29 +6,52 @@ redirect_from: - /guides/contract-testing-workflow/ --- -# Legacy Workflow Note +# Contract Testing Workflow -This page described older `specfact plan`, `specfact generate`, `specfact contract`, or `specfact sdd constitution` workflows that are not part of the current public mounted CLI in this repository. The detailed command examples previously documented here were removed because they no longer match the command surface exposed by `specfact --help`. +This workflow uses the current `specfact spec` command group for Specmatic-backed validation and mock flows. -Use the current mounted entrypoints instead: +## 1. Validate the current contract -- `specfact project --help` -- `specfact project sync --help` -- `specfact code --help` -- `specfact code review --help` -- `specfact spec --help` -- `specfact govern --help` -- `specfact backlog --help` -- `specfact module --help` +```bash +specfact spec validate api/openapi.yaml +``` + +Use `--bundle ` when you want to validate all contracts attached to a project bundle instead of a single file. + +## 2. Check backward compatibility before release + +```bash +specfact spec backward-compat api/openapi.yaml --previous api/openapi.v1.yaml +``` + +Run this before publishing a changed contract or promoting a release candidate. + +## 3. Generate test suites from the spec + +```bash +specfact spec generate-tests api/openapi.yaml +``` + +This is the fastest way to turn a validated contract into executable Specmatic coverage. + +## 4. Start a mock server for integration testing + +```bash +specfact spec mock api/openapi.yaml +``` + +Use the mock server when downstream services or frontend integrations need a stable contract target before the real implementation is ready. -When you need exact syntax, verify against live help in the current release, for example: +## 5. Gate the release bundle ```bash -specfact project sync bridge --help -specfact code repro --help -specfact code validate sidecar --help -specfact spec validate --help -specfact govern enforce --help +specfact govern enforce sdd legacy-api --no-interactive ``` -This page needs a full rewrite around the mounted command groups before task-level workflow examples can be published again. +This ties contract validation back into release readiness for the bundle that owns the API. + +## Related + +- [Spec bundle overview](/bundles/spec/overview/) +- [Govern enforce](/bundles/govern/enforce/) +- [Cross-module chains](/guides/cross-module-chains/) diff --git a/docs/guides/cross-module-chains.md b/docs/guides/cross-module-chains.md new file mode 100644 index 0000000..dfd57a2 --- /dev/null +++ b/docs/guides/cross-module-chains.md @@ -0,0 +1,66 @@ +--- +layout: default +title: Cross-Module Chains +permalink: /guides/cross-module-chains/ +--- + +# Cross-Module Chains + +This guide documents current multi-bundle workflows that move work from backlog planning through code, spec validation, and release enforcement. + +## Prerequisite bootstrap + +Run these once per repository, and again after relevant bundle upgrades: + +```bash +specfact init --profile solo-developer +specfact init ide --repo . --ide cursor +``` + +`specfact init ide` is the supported bootstrap for bundle-owned prompts and templates used by backlog, review, and govern flows. + +## Chain 1. Backlog refinement -> bundle sync + +```bash +specfact backlog ceremony refinement github --preview --labels feature +specfact backlog verify-readiness --adapter github --project-id owner/repo --target-items 123 +specfact project sync bridge --adapter github --mode export-only --repo . --bundle legacy-api +``` + +Use this chain when work starts in an external backlog tool and must be cleaned up before it becomes a SpecFact project artifact. + +## Chain 2. Brownfield intake -> contract validation + +```bash +specfact code import legacy-api --repo . +specfact code analyze contracts --repo . --bundle legacy-api +specfact spec validate --bundle legacy-api --force +``` + +Use this chain after importing a legacy repository into a project bundle and before deeper refactoring starts. + +## Chain 3. Contract update -> release gate + +```bash +specfact spec backward-compat api/openapi.yaml --previous api/openapi.v1.yaml +specfact spec generate-tests api/openapi.yaml +specfact govern enforce sdd legacy-api --no-interactive +``` + +Use this chain when a contract changed and you want compatibility checks, generated coverage, and bundle enforcement before promotion. + +## Chain 4. Review loop for changed files + +```bash +specfact code review run src --scope changed --no-tests +specfact govern enforce stage --preset balanced +specfact govern enforce sdd legacy-api --no-interactive +``` + +Use this when a branch is ready for review and you want the review bundle plus govern bundle to agree on the gate posture. + +## Related + +- [Daily DevOps routine](/guides/daily-devops-routine/) +- [Command chains reference](/guides/command-chains/) +- [Backlog bundle overview](/bundles/backlog/overview/) diff --git a/docs/guides/daily-devops-routine.md b/docs/guides/daily-devops-routine.md new file mode 100644 index 0000000..92ea433 --- /dev/null +++ b/docs/guides/daily-devops-routine.md @@ -0,0 +1,62 @@ +--- +layout: default +title: Daily DevOps Routine +permalink: /guides/daily-devops-routine/ +--- + +# Daily DevOps Routine + +This guide shows a full work day that spans backlog, code review, contract validation, and enforcement. + +## 1. Morning standup and queue check + +```bash +specfact backlog ceremony standup github +``` + +Use this to see active work, blockers, and the items you should commit to next. + +Reference: [Backlog bundle overview](/bundles/backlog/overview/) + +## 2. Refine or verify work before development + +```bash +specfact backlog ceremony refinement github --preview --labels feature +specfact backlog verify-readiness --adapter github --project-id owner/repo --target-items 123 +``` + +Use refinement when the work item needs structure. Use readiness verification when you need a release- or planning-grade check. + +Reference: [Cross-module chains](/guides/cross-module-chains/) + +## 3. Development and bundle refresh + +```bash +specfact init ide --repo . --ide cursor +specfact code import legacy-api --repo . +``` + +Refresh IDE resources when the workflow depends on installed prompts, then import or refresh the project bundle before deeper validation. + +Reference: [AI IDE workflow](/guides/ai-ide-workflow/) + +## 4. Midday quality review + +```bash +specfact code review run src --scope changed --no-tests +specfact spec validate --bundle legacy-api +``` + +Run the review bundle on your changed files and validate the affected contracts while the context is still fresh. + +Reference: [Contract testing workflow](/guides/contract-testing-workflow/) + +## 5. End-of-day release readiness + +```bash +specfact govern enforce sdd legacy-api --no-interactive +``` + +Use this before pushing or opening a promotion-oriented PR so the bundle state, manifest, and contracts are checked together. + +Reference: [Govern enforce](/bundles/govern/enforce/) diff --git a/docs/guides/workflows.md b/docs/guides/workflows.md index 4864780..1ce4851 100644 --- a/docs/guides/workflows.md +++ b/docs/guides/workflows.md @@ -1,34 +1,50 @@ --- layout: default -title: Workflows (legacy note) +title: Workflows permalink: /workflows/ redirect_from: - /guides/workflows/ --- -# Legacy Workflow Note +# Workflows -This page described older `specfact plan`, `specfact generate`, `specfact contract`, or `specfact sdd constitution` workflows that are not part of the current public mounted CLI in this repository. The detailed command examples previously documented here were removed because they no longer match the command surface exposed by `specfact --help`. +This index collects the current workflow guides that are aligned to the mounted command surface shipped by the installed modules in this repository. -Use the current mounted entrypoints instead: +## Start here -- `specfact project --help` -- `specfact project sync --help` -- `specfact code --help` -- `specfact code review --help` -- `specfact spec --help` -- `specfact govern --help` -- `specfact backlog --help` -- `specfact module --help` - -When you need exact syntax, verify against live help in the current release, for example: +Run the bundle bootstrap steps before following any IDE-assisted or prompt-driven workflow: ```bash -specfact project sync bridge --help -specfact code repro --help -specfact code validate sidecar --help -specfact spec validate --help -specfact govern enforce --help +specfact init --profile solo-developer +specfact init ide --repo . --ide cursor ``` -This page needs a full rewrite around the mounted command groups before task-level workflow examples can be published again. +Use `specfact init ide` again after module upgrades so bundle-owned prompts and templates stay in sync with the CLI. + +## Brownfield modernization + +- [Brownfield modernization](/guides/brownfield-modernization/) for the end-to-end legacy-code modernization path +- [Brownfield FAQ and ROI](/guides/brownfield-faq-and-roi/) for planning, rollout, and investment questions +- [Brownfield examples](/guides/brownfield-examples/) for concrete example flows you can adapt + +## Cross-bundle delivery workflows + +- [Cross-module chains](/guides/cross-module-chains/) for backlog -> code -> spec -> govern handoffs +- [Daily DevOps routine](/guides/daily-devops-routine/) for morning standup through end-of-day review +- [CI/CD pipeline](/guides/ci-cd-pipeline/) for pre-commit, GitHub Actions, and release-stage quality gates +- [Command chains reference](/guides/command-chains/) for short command sequences grouped by goal + +## Focused deep dives + +- [AI IDE workflow](/guides/ai-ide-workflow/) for prompt/bootstrap-aware IDE usage +- [Contract testing workflow](/guides/contract-testing-workflow/) for Specmatic validation, compatibility, test generation, and mocks +- [Agile/Scrum workflows](/guides/agile-scrum-workflows/) for backlog ceremonies and persona flows +- [Team collaboration workflow](/guides/team-collaboration-workflow/) for persona export/import and lock-based editing + +## Bundle references used by these workflows + +- [Backlog bundle overview](/bundles/backlog/overview/) +- [Project bundle overview](/bundles/project/overview/) +- [Codebase bundle overview](/bundles/codebase/overview/) +- [Spec bundle overview](/bundles/spec/overview/) +- [Govern bundle overview](/bundles/govern/overview/) diff --git a/openspec/changes/docs-10-workflow-consolidation/TDD_EVIDENCE.md b/openspec/changes/docs-10-workflow-consolidation/TDD_EVIDENCE.md new file mode 100644 index 0000000..67464c3 --- /dev/null +++ b/openspec/changes/docs-10-workflow-consolidation/TDD_EVIDENCE.md @@ -0,0 +1,129 @@ +# TDD Evidence + +## Verification Evidence + +### 0. Failing evidence + +Pre-implementation failing snapshot from the branch state before the new workflow guides were added. The failing condition was the missing `docs/guides/daily-devops-routine.md` page. + +Command run against the pre-implementation state: + +```bash +python3 -m pytest tests/unit/docs/test_docs_review.py::test_daily_devops_routine_exists -q +``` + +Recorded failure excerpt: + +```text +FAILED tests/unit/docs/test_docs_review.py::test_daily_devops_routine_exists - AssertionError: assert False +1 failed in 0.12s +``` + +### 1. Command surface verification + +Verified the command examples used in the new workflow pages against live `--help` output on 2026-03-27: + +- `specfact spec --help` +- `specfact spec validate --help` +- `specfact backlog ceremony standup --help` +- `specfact backlog refine --help` +- `specfact backlog verify-readiness --help` +- `specfact code import --help` +- `specfact code analyze contracts --help` +- `specfact code review run --help` +- `specfact project sync bridge --help` +- `specfact govern enforce --help` +- `specfact govern enforce sdd --help` +- `specfact init ide --help` + +### 2. Internal docs validation + +Command run: + +```bash +python3 -m pytest tests/unit/docs/test_docs_review.py -q +``` + +Result: + +- `16 passed` +- only pre-existing repository warnings remained for unrelated docs front matter and legacy authored links + +### 2.1 Internal link evidence for task 5.3 + +Targeted commands run: + +```bash +python3 -m pytest tests/unit/docs/test_docs_review.py::test_authored_internal_docs_links_resolve_to_published_docs_targets -q +python3 -m pytest tests/unit/docs/test_docs_review.py::test_daily_devops_routine_bundle_links -q +``` + +Result: + +- `3 passed` +- authored internal links for the restructured docs set resolved successfully +- the daily routine page explicitly linked each step to a bundle command reference page + +### 3. Legacy prompt/template path verification + +Searched the new workflow-guide set for legacy core-owned prompt/template path patterns (`.cursor/`, `.claude/`, `.specify/`, `.github/prompts`, `.github/instructions`, `.specfact/prompts`). + +Result: + +- no legacy core-owned prompt or template paths were referenced in the new workflow docs + +### 4. Acceptance item 5.4: `bundle exec jekyll build` with zero warnings + +Verification statement: + +- At `2026-03-27T22:27:11+01:00`, `bundle exec jekyll build --destination ../_site` completed successfully for this branch. +- The command output contained the normal Jekyll build summary and no warning lines on stdout/stderr. + +Terminal excerpt: + +```text +Configuration file: /home/dom/git/nold-ai/specfact-cli-modules-worktrees/feature/docs-10-workflow-consolidation/docs/_config.yml + Source: /home/dom/git/nold-ai/specfact-cli-modules-worktrees/feature/docs-10-workflow-consolidation/docs + Destination: /home/dom/git/nold-ai/specfact-cli-modules-worktrees/feature/docs-10-workflow-consolidation/_site + Incremental build: disabled. Enable with --incremental + Generating... + Jekyll Feed: Generating feed for posts + done in 1.479 seconds. + Auto-regeneration: disabled. Use --watch to enable. +``` + +### 5. `specfact code review run` clean pass + +Command run: + +```bash +specfact code review run \ + tests/unit/docs/test_missing_command_docs.py \ + tests/unit/docs/test_bundle_overview_cli_examples.py \ + --no-tests +``` + +Result: + +- `Review completed with no findings.` +- `Verdict: PASS | CI exit: 0 | Score: 120 | Reward delta: 40` + +### 6. Repository quality gates + +Completed in repository order: + +```bash +hatch run format +hatch run type-check +hatch run lint +hatch run yaml-lint +hatch run verify-modules-signature --require-signature --payload-from-filesystem --enforce-version-bump +hatch run contract-test +hatch run smart-test +hatch run test +``` + +Result: + +- all commands exited successfully on `feature/docs-10-workflow-consolidation` +- `contract-test`, `smart-test`, and `test` each passed the full `420` test cases diff --git a/openspec/changes/docs-10-workflow-consolidation/specs/cross-module-workflow-docs/spec.md b/openspec/changes/docs-10-workflow-consolidation/specs/cross-module-workflow-docs/spec.md index cd2009b..93c0d77 100644 --- a/openspec/changes/docs-10-workflow-consolidation/specs/cross-module-workflow-docs/spec.md +++ b/openspec/changes/docs-10-workflow-consolidation/specs/cross-module-workflow-docs/spec.md @@ -1,4 +1,4 @@ -## ADDED Requirements +# ADDED Requirements ### Requirement: Workflow docs SHALL cover current cross-module flows and setup prerequisites Workflow documentation SHALL show valid multi-bundle command chains and include resource-bootstrap steps when migrated bundle-owned prompts or templates are prerequisites. diff --git a/openspec/changes/docs-10-workflow-consolidation/specs/daily-devops-routine-docs/spec.md b/openspec/changes/docs-10-workflow-consolidation/specs/daily-devops-routine-docs/spec.md new file mode 100644 index 0000000..df63f57 --- /dev/null +++ b/openspec/changes/docs-10-workflow-consolidation/specs/daily-devops-routine-docs/spec.md @@ -0,0 +1,12 @@ +# ADDED Requirements + +### Requirement: Workflow docs SHALL document a current daily development routine + +Workflow documentation SHALL provide a complete day-level routine that links standup, backlog refinement, development, review, and release readiness to the current bundle command surface. + +#### Scenario: Daily routine covers a full work day + +- **GIVEN** the `daily-devops-routine` workflow doc +- **WHEN** a user reads the page +- **THEN** it shows morning standup, refinement, development, review, and end-of-day patterns +- **AND** each step links to the relevant bundle command reference diff --git a/openspec/changes/docs-10-workflow-consolidation/tasks.md b/openspec/changes/docs-10-workflow-consolidation/tasks.md index 890ad1d..48e2a17 100644 --- a/openspec/changes/docs-10-workflow-consolidation/tasks.md +++ b/openspec/changes/docs-10-workflow-consolidation/tasks.md @@ -1,29 +1,29 @@ ## 1. Change Setup -- [ ] 1.1 Update `openspec/CHANGE_ORDER.md` with `docs-10-workflow-consolidation` entry -- [ ] 1.2 Add `cross-module-workflow-docs` and `daily-devops-routine-docs` capability specs +- [x] 1.1 Update `openspec/CHANGE_ORDER.md` with `docs-10-workflow-consolidation` entry +- [x] 1.2 Add `cross-module-workflow-docs` and `daily-devops-routine-docs` capability specs ## 2. Brownfield Consolidation -- [ ] 2.1 Merge brownfield-engineer + brownfield-journey into `workflows/brownfield-modernization.md` -- [ ] 2.2 Merge brownfield-faq + brownfield-roi into `workflows/brownfield-faq-and-roi.md` -- [ ] 2.3 Merge 3 brownfield example files into `workflows/brownfield-examples.md` +- [x] 2.1 Merge brownfield-engineer + brownfield-journey into `docs/guides/brownfield-modernization.md` +- [x] 2.2 Merge brownfield-faq + brownfield-roi into `docs/guides/brownfield-faq-and-roi.md` +- [x] 2.3 Consolidate brownfield example flows into `docs/guides/brownfield-examples.md` ## 3. New Workflow Docs -- [ ] 3.1 Write `workflows/cross-module-chains.md`: backlog -> code -> spec -> govern end-to-end flow -- [ ] 3.2 Write `workflows/daily-devops-routine.md`: morning standup -> refine -> commit -> review cycle -- [ ] 3.3 Write `workflows/ci-cd-pipeline.md`: CI integration with pre-commit hooks, GitHub Actions -- [ ] 3.4 Add bundle-owned prompt/template bootstrap steps where workflows depend on migrated resources +- [x] 3.1 Write `docs/guides/cross-module-chains.md`: backlog -> code -> spec -> govern end-to-end flow +- [x] 3.2 Write `docs/guides/daily-devops-routine.md`: morning standup -> refine -> commit -> review cycle +- [x] 3.3 Write `docs/guides/ci-cd-pipeline.md`: CI integration with pre-commit hooks, GitHub Actions +- [x] 3.4 Add bundle-owned prompt/template bootstrap steps where workflows depend on migrated resources ## 4. Update Existing -- [ ] 4.1 Validate and update `workflows/command-chains.md` against current command surface -- [ ] 4.2 Add redirects from old brownfield file paths to new merged locations +- [x] 4.1 Validate and update `docs/guides/command-chains.md` against current command surface +- [x] 4.2 Add redirects from old brownfield file paths to new merged locations ## 5. Verification -- [ ] 5.1 Verify all command examples in workflow docs match actual `--help` output -- [ ] 5.2 Verify workflow docs do not reference legacy core-owned prompt/template paths -- [ ] 5.3 Verify all internal links resolve -- [ ] 5.4 Run `bundle exec jekyll build` with zero warnings +- [x] 5.1 Verify all command examples in workflow docs match actual `--help` output +- [x] 5.2 Verify workflow docs do not reference legacy core-owned prompt/template paths +- [x] 5.3 Verify all internal links resolve (see `TDD_EVIDENCE.md` §2.1) +- [x] 5.4 Run `bundle exec jekyll build` with zero warnings diff --git a/openspec/specs/cross-module-workflow-docs/spec.md b/openspec/specs/cross-module-workflow-docs/spec.md new file mode 100644 index 0000000..8649488 --- /dev/null +++ b/openspec/specs/cross-module-workflow-docs/spec.md @@ -0,0 +1,26 @@ +# ADDED Requirements + +### Requirement: Workflow docs SHALL cover current cross-module flows and setup prerequisites + +Workflow documentation SHALL show valid multi-bundle command chains and include resource-bootstrap steps when migrated bundle-owned prompts or templates are prerequisites. + +#### Scenario: Cross-module chain covers full lifecycle + +- **GIVEN** the `cross-module-chains` workflow doc +- **WHEN** a user reads the page +- **THEN** it shows a complete flow such as backlog ceremony -> code import -> spec validate -> govern enforce +- **AND** each step shows the exact command with practical arguments + +#### Scenario: Workflow docs explain resource bootstrap before dependent flows + +- **GIVEN** a workflow doc that uses AI IDE prompts or backlog workspace templates +- **WHEN** a user reads the page +- **THEN** the workflow includes the supported resource bootstrap step such as `specfact init ide` +- **AND** it does not rely on legacy core-owned resource paths + +#### Scenario: CI pipeline doc covers automation patterns + +- **GIVEN** the `ci-cd-pipeline` workflow doc +- **WHEN** a user reads the page +- **THEN** it shows pre-commit hooks, GitHub Actions integration, and CI/CD stage mapping +- **AND** all SpecFact commands shown are valid and current diff --git a/openspec/specs/daily-devops-routine-docs/spec.md b/openspec/specs/daily-devops-routine-docs/spec.md new file mode 100644 index 0000000..df63f57 --- /dev/null +++ b/openspec/specs/daily-devops-routine-docs/spec.md @@ -0,0 +1,12 @@ +# ADDED Requirements + +### Requirement: Workflow docs SHALL document a current daily development routine + +Workflow documentation SHALL provide a complete day-level routine that links standup, backlog refinement, development, review, and release readiness to the current bundle command surface. + +#### Scenario: Daily routine covers a full work day + +- **GIVEN** the `daily-devops-routine` workflow doc +- **WHEN** a user reads the page +- **THEN** it shows morning standup, refinement, development, review, and end-of-day patterns +- **AND** each step links to the relevant bundle command reference diff --git a/tests/unit/docs/test_docs_review.py b/tests/unit/docs/test_docs_review.py index cf14807..9c2d76d 100644 --- a/tests/unit/docs/test_docs_review.py +++ b/tests/unit/docs/test_docs_review.py @@ -445,6 +445,24 @@ def _iter_guides_legacy_redirect_violations() -> list[str]: return violations +def test_daily_devops_routine_exists() -> None: + assert _repo_file("docs/guides/daily-devops-routine.md").is_file() + + +def test_daily_devops_routine_bundle_links() -> None: + text = _read_text(_repo_file("docs/guides/daily-devops-routine.md")) + expected_links = { + "Morning standup": "[Backlog bundle overview](/bundles/backlog/overview/)", + "Refinement": "[Cross-module chains](/guides/cross-module-chains/)", + "Development": "[AI IDE workflow](/guides/ai-ide-workflow/)", + "Review": "[Contract testing workflow](/guides/contract-testing-workflow/)", + "End-of-day": "[Govern enforce](/bundles/govern/enforce/)", + } + + for label, link in expected_links.items(): + assert link in text, f"{label} step is missing bundle command reference link {link}" + + def _extract_redirect_from_entries() -> dict[str, Path]: """Build map of redirect_from routes to the file that declares them.""" redirects: dict[str, Path] = {}