nold-ai · djm81 · Mar 27, 2026 · Mar 27, 2026 · Mar 27, 2026
diff --git a/docs/guides/README.md b/docs/guides/README.md
@@ -1,72 +1,68 @@
 # 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
 - **[Custom registries](custom-registries.md)** - Add, list, remove registries; trust levels and priority
 - **[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
@@ -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
@@ -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
@@ -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
@@ -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/)