Refactor diagram handling, enhance formats, and add SVG templates

.agents/rules/devspec-workflow.md

@@ -18,7 +18,7 @@ Follow these rules:
 - Use `devspec/foundation/codebase-structure.md` for repository access requirements.
 - Keep product context in `devspec/foundation/project-context.md`, durable principles in `devspec/constitution.md`, and operational governance, compliance rules, enforcement details, and delivery gates in `devspec/foundation/rules.md`.
 - Use `devspec/adapters/validation-flows.md` for enterprise acceptance checks.
-- For `/devspec.diagram`, keep Mermaid as the default output and treat `format=svg` or `format=mermaid+svg` as canonical command input, not a separate workflow.
+- For `/devspec.diagram`, keep SVG as the default output and treat any non-duplicated `format=` combination of `svg`, `html`, and `mermaid` as canonical command input. Example: `format=svg`, `format=html`, `format=mermaid`, `format=svg+html`, `format=svg+mermaid`, `format=svg+html+mermaid`, `format=html+mermaid`.
 - Keep provider credentials, tokens, user settings, and secrets outside prompt, rule, skill, and artifact files.
 - Record unsupported Antigravity behavior as a limitation instead of changing workflow semantics.
 

.agents/skills/devspec-diagram.md

@@ -7,8 +7,9 @@ Execute canonical command `/devspec.diagram`.
 
 - Read `devspec/adapters/command-registry.md` for the command contract.
 - Read `.github/prompts/devspec.diagram.prompt.md` and `.github/agents/devspec.diagram.agent.md` as the source of intent.
-- Preserve Mermaid as the default output, pass through `format=svg` for SVG-only output, and pass through `format=mermaid+svg` for both Mermaid and SVG.
-- For SVG output, use `devspec/architecture/_template/process-flow-diagram.svg` for process-flow rows or explicit process-flow SVG requests, otherwise use `devspec/architecture/_template/architecture-diagram.svg`. Durable targets stay under `devspec/architecture/images/`, and validation follows `.github/prompts/PATTERNS.md#svg-output-pattern`.
+- Preserve SVG as the default output. Pass through any non-duplicated `format=` combination of `svg`, `html`, and `mermaid`; examples include `format=svg`, `format=html`, `format=mermaid`, `format=svg+html`, `format=svg+mermaid`, `format=svg+html+mermaid`, and `format=html+mermaid`.
+- For SVG output, select the matching template from `.github/prompts/PATTERNS.md#svg-output-pattern`, including architecture, process-flow, sequence, state/lifecycle, domain-model, journey-map, timeline-plan, quadrant-analysis, and mindmap templates. Durable targets stay under `devspec/architecture/images/`, and validation follows `.github/prompts/PATTERNS.md#svg-output-pattern`.
+- Keep every generated SVG and HTML diagram on the shared dark architecture-style visual contract from `.github/prompts/PATTERNS.md#svg-output-pattern`, including custom smaller SVGs. Do not produce white/default/simple diagram styling unless the user explicitly requests a light or custom theme.
 - Preserve required inputs, output artifacts, status values, gates, handoff order, and recovery behavior.
 - Use Git-tracked `devspec/` artifacts for recovery before relying on chat history or Antigravity artifacts.
 - Treat unsupported Antigravity behavior as an adapter limitation, not a workflow change.

.agents/skills/devspec-extract.md

@@ -8,7 +8,7 @@ Execute canonical command `/devspec.extract`.
 - Read `devspec/adapters/command-registry.md` for the command contract.
 - Read `.github/prompts/devspec.extract.prompt.md` and `.github/agents/devspec.extract.agent.md` as the source of intent.
 - Treat constitution changes as confirmation-gated candidates; route operational governance, compliance procedures, enforcement details, and delivery gates to `devspec/foundation/rules.md`.
-- Preserve `format=svg` and `format=mermaid+svg` as diagram generation preferences in queue notes; extraction remains queue-first and may generate at most one approved diagram artifact set only after the canonical approval gate.
+- Preserve any non-duplicated diagram `format=` combination of `svg`, `html`, and `mermaid` in queue notes; extraction remains queue-first and may generate at most one approved diagram artifact set only after the canonical approval gate.
 - Preserve required inputs, output artifacts, status values, gates, handoff order, and recovery behavior.
 - Use Git-tracked `devspec/` artifacts for recovery before relying on chat history or Antigravity artifacts.
 - Treat unsupported Antigravity behavior as an adapter limitation, not a workflow change.

.claude/skills/devspec-diagram/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: devspec-diagram
-description: Run /devspec.diagram using the canonical devspec command registry. Generates evidence-backed diagrams, defaulting to Mermaid with opt-in SVG output, for architecture, workflows, journeys, sequences, states, timelines, and planning views. Supports mono-repo and multi-repo workspaces. Works across GitHub Copilot, Claude Code, OpenAI Codex, Cursor, and other AI agents.
+description: Run /devspec.diagram using the canonical devspec command registry. Generates evidence-backed diagrams, defaulting to SVG with optional Mermaid and HTML output, for architecture, workflows, journeys, sequences, states, timelines, and planning views. Supports mono-repo and multi-repo workspaces. Works across GitHub Copilot, Claude Code, OpenAI Codex, Cursor, and other AI agents.
 ---
 
 Execute canonical command `/devspec.diagram`.
@@ -9,7 +9,7 @@ Execute canonical command `/devspec.diagram`.
 2. Read `devspec/adapters/command-registry.md` for this command's required input, outputs, mutation level, and next handoff.
 3. Read `.github/prompts/devspec.diagram.prompt.md` and `.github/agents/devspec.diagram.agent.md` as the authoritative source of command intent and behavior.
 4. Apply `.github/prompts/PATTERNS.md` for shared behavior: interactive questions, prerequisite validation, session recovery, discovery exclusions, and output closure, including `PATTERNS.md#diagram-extraction-consistency-pattern`, `PATTERNS.md#svg-output-pattern`, `PATTERNS.md#mermaid-internal-naming-and-readability-pattern`, `PATTERNS.md#mermaid-visual-quality-pattern`, `PATTERNS.md#process-flow-extraction-pattern`, and `PATTERNS.md#excluded-diagram-families`.
-5. Treat Mermaid as the default output. Pass through `format=svg` for SVG-only output and `format=mermaid+svg` for both Mermaid and SVG; unsupported `format=` values require clarification.
+5. Treat SVG as the default output. Pass through any non-duplicated `format=` combination of `svg`, `html`, and `mermaid`; examples include `format=svg`, `format=html`, `format=mermaid`, `format=svg+html`, `format=svg+mermaid`, `format=svg+html+mermaid`, and `format=html+mermaid`. Unsupported or duplicated `format=` values require clarification.
 6. For every generated Mermaid `flowchart` or `stateDiagram-v2`: open with the dark theme init block, declare the semantic `classDef` palette for roles present, use role-appropriate node shapes, wrap boundaries of 3+ nodes in named `subgraph` blocks, draw cross-subgraph arrows after all `end` keywords, assign `classDef` classes in a batch block at the end, and verify node count stays within complexity guardrails. Never use an excluded family such as `architecture-beta`; substitute the documented portable alternative.
 7. For SVG output, use `devspec/architecture/_template/process-flow-diagram.svg` for process-flow rows or explicit process-flow SVG requests, otherwise use `devspec/architecture/_template/architecture-diagram.svg`. Write durable images under `devspec/architecture/images/`, and validate generated SVG as standalone XML with no scripts, iframes, foreignObject, external assets, secrets, or unresolved placeholders.
 8. Honor multi-repo boundaries: when `devspec/foundation/codebase-structure.md` records multiple repositories, scope diagram evidence to the correct repository boundary.

.claude/skills/devspec-extract/SKILL.md

@@ -9,7 +9,7 @@ Execute canonical command `/devspec.extract`.
 2. Read `devspec/adapters/command-registry.md` for this command's required input, outputs, mutation level, and next handoff.
 3. Read `.github/prompts/devspec.extract.prompt.md` and `.github/agents/devspec.extract.agent.md` as the authoritative source of command intent and behavior.
 4. Apply `.github/prompts/PATTERNS.md` for shared behavior: interactive questions, prerequisite validation, session recovery, output closure, and specifically `PATTERNS.md#discovery-exclusion-pattern`, `PATTERNS.md#diagram-extraction-consistency-pattern`, `PATTERNS.md#svg-output-pattern`, and `PATTERNS.md#process-flow-extraction-pattern`. Do not queue diagram families listed in `PATTERNS.md#excluded-diagram-families` (such as `architecture-beta`) when seeding `devspec/architecture/artifact-queue.md`; use the documented portable alternative instead.
-5. Preserve `format=svg` and `format=mermaid+svg` as diagram generation preferences in queue notes. Extraction remains queue-first and may generate at most one approved diagram artifact set only after the canonical approval gate.
+5. Preserve any non-duplicated diagram `format=` combination of `svg`, `html`, and `mermaid` in queue notes. Extraction remains queue-first and may generate at most one approved diagram artifact set only after the canonical approval gate.
 6. For multi-repo extraction: process each repository source in sequence, apply discovery exclusions from `devspec/foundation/discovery-exclusions.md`, record per-repo evidence and status in `devspec/foundation/extraction-state.md`, and seed diagram candidates per-repo in `devspec/architecture/artifact-queue.md`.
 
 Command input comes from the user's current message.

.cursor/rules/devspec-workflow.mdc

@@ -18,7 +18,7 @@ Follow these rules:
 - Use `devspec/glossary.md` for status values.
 - Use `devspec/foundation/codebase-structure.md` for repository access requirements.
 - Use `devspec/adapters/validation-flows.md` for enterprise acceptance checks.
-- For `/devspec.diagram`, keep Mermaid as the default output and treat `format=svg` or `format=mermaid+svg` as canonical command input, not a separate workflow.
+- For `/devspec.diagram`, keep SVG as the default output and treat any non-duplicated `format=` combination of `svg`, `html`, and `mermaid` as canonical command input. Example: `format=svg`, `format=html`, `format=mermaid`, `format=svg+html`, `format=svg+mermaid`, `format=svg+html+mermaid`, `format=html+mermaid`.
 - Record unsupported platform behavior as a limitation instead of changing workflow semantics.
 
 Do not recommend unregistered commands such as `/devspec.plan`, `/devspec.architecture`, `/devspec.provider-integrations`, `/devspec.queue`, or `/devspec.decisions`.

.gemini/commands/devspec/diagram.toml

@@ -8,7 +8,7 @@ Before acting:
 3. Follow `.github/prompts/PATTERNS.md` for shared workflow, recovery, output, discovery, and recommendation behavior.
 4. Recover from existing Git-tracked `devspec/` artifacts before relying on Gemini session memory.
 5. Preserve required inputs, output artifacts, status values, gates, handoff order, and recovery behavior.
-6. Preserve Mermaid as the default output, pass through `format=svg` for SVG-only output, and pass through `format=mermaid+svg` for both Mermaid and SVG.
+6. Preserve SVG as the default output. Pass through any non-duplicated `format=` combination of `svg`, `html`, and `mermaid`; examples include `format=svg`, `format=html`, `format=mermaid`, `format=svg+html`, `format=svg+mermaid`, `format=svg+html+mermaid`, and `format=html+mermaid`.
 7. For SVG output, use `devspec/architecture/_template/process-flow-diagram.svg` for process-flow rows or explicit process-flow SVG requests, otherwise use `devspec/architecture/_template/architecture-diagram.svg`. Durable targets stay under `devspec/architecture/images/`, and validation follows `.github/prompts/PATTERNS.md#svg-output-pattern`.
 8. Treat Gemini-specific command syntax as platform mechanics, not a workflow change.
 

.gemini/commands/devspec/extract.toml

@@ -8,7 +8,7 @@ Before acting:
 3. Follow `.github/prompts/PATTERNS.md` for shared workflow, recovery, output, discovery, and recommendation behavior.
 4. Recover from existing Git-tracked `devspec/` artifacts before relying on Gemini session memory.
 5. Preserve required inputs, output artifacts, status values, gates, handoff order, and recovery behavior.
-6. Preserve `format=svg` and `format=mermaid+svg` as diagram generation preferences in queue notes; extraction remains queue-first and may generate at most one approved diagram artifact set only after the canonical approval gate.
+6. Preserve any non-duplicated diagram `format=` combination of `svg`, `html`, and `mermaid` in queue notes; extraction remains queue-first and may generate at most one approved diagram artifact set only after the canonical approval gate.
 7. Treat Gemini-specific command syntax as platform mechanics, not a workflow change.
 
 The user's raw command input, if any, is appended below these instructions by Gemini CLI.