docs(workflows): visualize the OpenSpec lifecycle

docs/workflows.md

@@ -28,6 +28,75 @@ OPSX (fluid actions):
 
 > **Customization:** OPSX workflows are driven by schemas that define artifact sequences. See [Customization](customization.md) for details on creating custom schemas.
 
+## Workflow at a Glance
+
+The default workflow stays fluid: exploration and verification are optional, and
+you can update planning artifacts whenever implementation reveals something new.
+
+```mermaid
+flowchart TD
+    Idea["Idea or problem"] --> Explore["/opsx:explore<br/>(optional)"]
+    Idea --> Propose["/opsx:propose"]
+    Explore --> Propose
+    Propose --> Review{"Planning artifacts<br/>ready?"}
+    Review -->|"Refine"| Update["/opsx:update"]
+    Update --> Review
+    Review -->|"Implement"| Apply["/opsx:apply"]
+    Apply -->|"Plan changed"| Update
+    Apply --> Archive["/opsx:archive"]
+    Apply --> Verify["/opsx:verify<br/>(optional, custom selection)"]
+    Apply --> Sync["/opsx:sync<br/>(optional before archive)"]
+    Verify --> Verified{"Ready to archive?"}
+    Verified -->|"Fix implementation"| Apply
+    Verified -->|"Revise plan"| Update
+    Verified -->|"Ready"| Sync
+    Verified -->|"Ready"| Archive
+    Sync --> Archive
+```
+
+The AI assistant drives the workflow, while the CLI provides deterministic
+scaffolding, status, and artifact instructions:
+
+```mermaid
+sequenceDiagram
+    actor Human
+    participant Assistant as AI assistant
+    participant CLI as OpenSpec CLI
+    participant Files as Planning and implementation files
+
+    Human->>Assistant: /opsx:propose "change"
+    Assistant->>CLI: openspec new change
+    CLI->>Files: Scaffold change metadata
+    Assistant->>CLI: Request status and artifact instructions
+    CLI-->>Assistant: Build order, paths, and templates
+    Assistant->>Files: Write schema-defined planning artifacts
+    Assistant-->>Human: Present artifacts for review
+
+    Human->>Assistant: /opsx:apply
+    Assistant->>CLI: Request apply instructions
+    CLI-->>Assistant: Context files and task state
+    Assistant->>Files: Implement tasks and update checkboxes
+    Assistant-->>Human: Report implementation status
+
+    Human->>Assistant: /opsx:archive
+    Assistant->>CLI: Request archive inputs and artifact status
+    CLI-->>Assistant: Planning paths and artifact completion
+    Assistant->>Files: Read task state and compare delta specs
+    opt Delta specs exist
+        Assistant-->>Human: Offer to sync before archiving
+        alt Sync accepted
+            Human->>Assistant: Confirm sync
+            Assistant->>Files: Merge delta specs into main specs
+        else Sync skipped
+            Human->>Assistant: Archive without syncing
+        end
+    end
+    Assistant->>Files: Move the change into the archive
+    Assistant-->>Human: Report archive location and sync result
+
+    Note over Human,CLI: CLI alternative: openspec archive change-name --yes skips confirmation prompts; it still validates, then applies any delta specs and archives
+```
+
 ## Two Modes
 
 ### Default Quick Path (`core` profile)

website/components/mdx.tsx

@@ -2,6 +2,7 @@ import defaultMdxComponents from 'fumadocs-ui/mdx';
 import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
 import { Step, Steps } from 'fumadocs-ui/components/steps';
 import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';
+import { Mermaid } from '@/components/mermaid';
 import type { MDXComponents } from 'mdx/types';
 
 export function getMDXComponents(components?: MDXComponents) {
@@ -13,6 +14,7 @@ export function getMDXComponents(components?: MDXComponents) {
     Steps,
     Accordion,
     Accordions,
+    Mermaid,
     ...components,
   } satisfies MDXComponents;
 }

website/components/mermaid.tsx

@@ -0,0 +1,37 @@
+import { renderMermaidSVG } from 'beautiful-mermaid';
+import { CodeBlock, Pre } from 'fumadocs-ui/components/codeblock';
+
+export function Mermaid({ chart }: { chart: string }) {
+  try {
+    // beautiful-mermaid injects remote font imports; the site already provides Inter.
+    const svg = renderMermaidSVG(chart, {
+      bg: 'var(--color-fd-background)',
+      fg: 'var(--color-fd-foreground)',
+      transparent: true,
+    }).replace(/^\s*@import url\(['"]https:\/\/fonts\.googleapis\.com\/[^)]*\);\s*$/m, '');
+
+    return (
+      <figure>
+        <div
+          aria-label="Scrollable Mermaid diagram"
+          className="overflow-x-auto"
+          role="region"
+          tabIndex={0}
+        >
+          <div
+            aria-hidden="true"
+            className="[&_svg]:h-auto [&_svg]:max-w-full [&_svg]:min-w-[40rem]"
+            dangerouslySetInnerHTML={{ __html: svg }}
+          />
+        </div>
+        <figcaption className="sr-only">Mermaid diagram source: {chart}</figcaption>
+      </figure>
+    );
+  } catch {
+    return (
+      <CodeBlock title="Mermaid">
+        <Pre>{chart}</Pre>
+      </CodeBlock>
+    );
+  }
+}

website/lib/source.ts

@@ -1,4 +1,5 @@
 import { docs } from 'collections/server';
+import { renderPlaceholder } from 'fumadocs-core/mdx-plugins/remark-llms.runtime';
 import { loader } from 'fumadocs-core/source';
 import { icons } from 'lucide-react';
 import { createElement } from 'react';
@@ -37,8 +38,17 @@ export function getPageMarkdownUrl(page: (typeof source)['$inferPage']) {
 
 export async function getLLMText(page: (typeof source)['$inferPage']) {
   const processed = await page.data.getText('processed');
+  const markdown = await renderPlaceholder(processed, {
+    Mermaid({ attributes }) {
+      if (typeof attributes.chart !== 'string') return '';
+
+      return `\`\`\`mermaid
+${attributes.chart}
+\`\`\``;
+    },
+  });
 
   return `# ${page.data.title} (${page.url})
 
-${processed}`;
+${markdown}`;
 }

website/package.json

@@ -12,6 +12,7 @@
   },
   "dependencies": {
     "@orama/orama": "^3.1.18",
+    "beautiful-mermaid": "^1.1.3",
     "fumadocs-core": "^16.12.1",
     "fumadocs-mdx": "^15.2.1",
     "fumadocs-ui": "^16.12.1",

website/source.config.ts

@@ -1,5 +1,6 @@
 import { defineConfig, defineDocs } from 'fumadocs-mdx/config';
 import { metaSchema, pageSchema } from 'fumadocs-core/source/schema';
+import { remarkMdxMermaid } from 'fumadocs-core/mdx-plugins';
 import { z } from 'zod';
 
 // You can customize Zod schemas for frontmatter and `meta.json` here
@@ -12,7 +13,9 @@ export const docs = defineDocs({
     // page" link opens the real source rather than the generated mirror.
     schema: pageSchema.extend({ githubSource: z.string().optional() }),
     postprocess: {
-      includeProcessedMarkdown: true,
+      includeProcessedMarkdown: {
+        mdxAsPlaceholder: ['Mermaid'],
+      },
     },
   },
   meta: {
@@ -22,6 +25,6 @@ export const docs = defineDocs({
 
 export default defineConfig({
   mdxOptions: {
-    // MDX options
+    remarkPlugins: [remarkMdxMermaid],
   },
 });