docs(workflows): visualize the OpenSpec lifecycle

[clay-good]

Status

LGTM.

What was missing / the motivation

The workflow guide explained the OpenSpec lifecycle in prose and text examples, but it did not give readers a visual map of the workflow or show how the human, AI assistant, CLI, and project files interact.

Closes #439.

What it does

• Adds a Mermaid flowchart for the current fluid workflow, including optional explore, update, verify, sync, and archive paths.
• Adds a Mermaid sequence diagram showing the responsibilities of the human, AI assistant, OpenSpec CLI, and project files.
• Uses the current OPSX commands and skill-driven behavior rather than the legacy commands in the original issue draft.
• Pre-renders Mermaid as responsive, theme-aware SVG in the Fumadocs site, with readable source if the renderer throws.
• Preserves fenced Mermaid source in Copy Markdown, per-page LLM output, and llms-full.txt.

Proof it works

• pnpm run lint
• pnpm test: 3,474 tests passed across 119 files, including all CLI E2E journeys
• website pnpm run types:check
• website pnpm run build: 87 static pages generated successfully
• Production-output checks: both diagrams render as SVG; no raw Mermaid component or remote font import remains; both LLM exports contain the two original Mermaid fences
• Browser E2E: diagrams render in the built site without page overflow, remain readable on narrow screens through contained horizontal scrolling, and introduce no client-side Mermaid runtime
• Adversarial rendering checks: script and image markup remains escaped; malformed diagrams fall back to a code block; generated Google Fonts imports are removed without changing legitimate @import url(...) label text
• git diff --check

Notes / nits

The behavior change is limited to documentation and the documentation-site build. It adds MIT-licensed beautiful-mermaid, with EPL-2.0 elkjs and BSD-2-Clause entities transitives, to the docs build only. It does not change the OpenSpec CLI/runtime, schemas, generated agent instructions, or workflow behavior. Diagrams are rendered during the static build, so users do not download or run a Mermaid client library.

Summary by CodeRabbit

• New Features

  • Added support for rendering Mermaid diagrams in documentation with themed styling, accessibility metadata, scrolling, and a fallback view for rendering errors.
  • Mermaid diagrams are now supported directly in Markdown-based documentation.

• Documentation

  • Added a “Workflow at a Glance” guide describing the default workflow and optional exploration, verification, and synchronization steps.
  • Included diagrams illustrating workflow decisions and interactions between participants, tools, and project files.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

The change documents the OpenSpec workflow with Mermaid diagrams and adds Mermaid chart processing and rendering to the website MDX pipeline.

Changes

Mermaid workflow documentation and rendering

Layer / File(s)	Summary
Mermaid MDX processing website/source.config.ts, website/components/mdx.tsx, website/lib/source.ts	Registers Mermaid processing, exposes the Mermaid component, and converts valid placeholders to fenced Mermaid Markdown.
Mermaid chart rendering website/components/mermaid.tsx, website/package.json	Adds themed SVG rendering, accessibility metadata, scrolling, fallback code blocks, and the beautiful-mermaid dependency.
Workflow diagrams docs/workflows.md	Documents the default workflow and adds flowchart and sequence diagrams for optional steps and component interactions.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

• Fission-AI/OpenSpec#456: Adds related OpenSpec workflow documentation in a different documentation file.

Suggested reviewers: alfred-openspec

Sequence Diagram(s)

sequenceDiagram
  participant Markdown
  participant MDXPipeline
  participant Mermaid
  participant beautifulmermaid
  Markdown->>MDXPipeline: process Mermaid block
  MDXPipeline->>Mermaid: provide chart text
  Mermaid->>beautifulmermaid: render SVG
  beautifulmermaid-->>Mermaid: return SVG or error
  Mermaid-->>MDXPipeline: return SVG or fallback code block

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the documentation change and its focus on visualizing the OpenSpec lifecycle.
Linked Issues check	✅ Passed	The PR adds the requested workflow flowchart and sequence diagram, documents lifecycle steps, and preserves Mermaid content across outputs [#439].
Out of Scope Changes check	✅ Passed	The rendering component, dependency, and MDX changes directly support embedded Mermaid documentation and related output preservation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/docs-workflow-diagrams

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[cloudflare-workers-and-pages]

Deploying openspec-docs with    Cloudflare Pages

Latest commit:	4c74f40
Status:	✅  Deploy successful!
Preview URL:	https://3d4201f9.openspec-docs.pages.dev
Branch Preview URL:	https://codex-docs-workflow-diagrams.openspec-docs.pages.dev

View logs

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/workflows.md`:
- Around line 76-79: Update the /opsx:archive workflow sequence to show
synchronization as an optional confirmation branch rather than an unconditional
step. Document that --yes enables synchronization for non-interactive callers,
and keep the archive operation represented separately from the optional sync
flow.
- Around line 44-49: Update the workflow graph around Apply, Verify, Sync, and
Archive to add a direct Apply-to-Archive edge, while preserving the existing
optional Verify and Sync paths.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: fb3b742e-96e5-4e6c-a636-bc5f6831b770

📥 Commits

Reviewing files that changed from the base of the PR and between 45cca5d and a58a1f4.

📒 Files selected for processing (1)

• docs/workflows.md

[alfred-openspec]

The diagrams render correctly on GitHub, but the deployed Fumadocs preview shows both mermaid fences as raw syntax-highlighted code because the site has no Mermaid component or renderer: https://12ead95f.openspec-docs.pages.dev/docs/the-workflow. Please add docs-site rendering support or use a portable rendered asset so the lifecycle is actually visualized on both surfaces.

[clay-good]

Addressed the Fumadocs rendering request in d41f88e. The docs site now pre-renders both Mermaid diagrams as responsive, theme-aware SVG with a readable code fallback; Copy Markdown and LLM exports retain the original Mermaid fences. I verified the deployed preview at https://674b8a88.openspec-docs.pages.dev/docs/the-workflow (2 SVG diagrams, 0 raw Mermaid blocks, no remote font imports or page overflow), and all CI/security/CodeQL/CodeRabbit checks pass. @alfred-openspec, please re-review when convenient.

[clay-good]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[alfred-openspec]

Exact head 4c74f40 is clean. Both lifecycle diagrams match the current OPSX semantics, render as responsive SVGs on the docs site, fall back safely to source on render failure, and remain Mermaid source in LLM output. A fresh locked install, typecheck, production build, exact static-output checks, Cloudflare preview, and the full Linux/macOS/Windows/security matrix pass.