diff --git a/.agents/rules/devspec-workflow.md b/.agents/rules/devspec-workflow.md index 1d0934e..58d0bc2 100644 --- a/.agents/rules/devspec-workflow.md +++ b/.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. diff --git a/.agents/skills/devspec-diagram.md b/.agents/skills/devspec-diagram.md index f89fef5..933d900 100644 --- a/.agents/skills/devspec-diagram.md +++ b/.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. diff --git a/.agents/skills/devspec-extract.md b/.agents/skills/devspec-extract.md index 8de55e1..988ff8f 100644 --- a/.agents/skills/devspec-extract.md +++ b/.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. diff --git a/.claude/skills/devspec-diagram/SKILL.md b/.claude/skills/devspec-diagram/SKILL.md index 95eb488..20758bf 100644 --- a/.claude/skills/devspec-diagram/SKILL.md +++ b/.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. diff --git a/.claude/skills/devspec-extract/SKILL.md b/.claude/skills/devspec-extract/SKILL.md index 528e0b9..e5c26f5 100644 --- a/.claude/skills/devspec-extract/SKILL.md +++ b/.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. diff --git a/.cursor/rules/devspec-workflow.mdc b/.cursor/rules/devspec-workflow.mdc index 1f8be62..2d83ecf 100644 --- a/.cursor/rules/devspec-workflow.mdc +++ b/.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`. diff --git a/.gemini/commands/devspec/diagram.toml b/.gemini/commands/devspec/diagram.toml index 5588a14..9dd7ac6 100644 --- a/.gemini/commands/devspec/diagram.toml +++ b/.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. diff --git a/.gemini/commands/devspec/extract.toml b/.gemini/commands/devspec/extract.toml index 0d2ceda..8e70486 100644 --- a/.gemini/commands/devspec/extract.toml +++ b/.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. diff --git a/.github/agents/devspec.diagram.agent.md b/.github/agents/devspec.diagram.agent.md index 077b947..9f4b2d8 100644 --- a/.github/agents/devspec.diagram.agent.md +++ b/.github/agents/devspec.diagram.agent.md @@ -1,6 +1,6 @@ --- name: "devspec.diagram" -description: "Use to generate or update one evidence-backed diagram, defaulting to Mermaid with opt-in SVG output, for architecture, workflows, journeys, sequences, states, timelines, planning views, or stable domain structures." +description: "Use to generate or update one evidence-backed diagram, defaulting to SVG with optional Mermaid and HTML output, for architecture, workflows, journeys, sequences, states, timelines, planning views, or stable domain structures." tools: [read, edit, search, vscode/askQuestions] model: ["GPT-5.4 (copilot)", "GPT-5.3-Codex (copilot)", "Claude Sonnet 4.6 (copilot)", "Claude Haiku 4.5 (copilot)"] user-invocable: true @@ -16,14 +16,18 @@ handoffs: You generate or update one diagram for a requested architecture, module, feature workflow, user journey, sequence, state, timeline, planning view, or stable domain subject. ## Constraints -- Follow the [Prerequisite Validation Pattern](../prompts/PATTERNS.md#prerequisite-validation-pattern), [Session Recovery Pattern](../prompts/PATTERNS.md#session-recovery-pattern), [Interactive Question Pattern](../prompts/PATTERNS.md#interactive-question-pattern), [Work-Item Target Pattern](../prompts/PATTERNS.md#work-item-target-pattern), [Multi-Repo Validation Pattern](../prompts/PATTERNS.md#multi-repo-validation-pattern), [Token Stewardship Pattern](../prompts/PATTERNS.md#token-stewardship-pattern), [Discovery Exclusion Pattern](../prompts/PATTERNS.md#discovery-exclusion-pattern), [Diagram Extraction Consistency Pattern](../prompts/PATTERNS.md#diagram-extraction-consistency-pattern), [SVG Output Pattern](../prompts/PATTERNS.md#svg-output-pattern), [Mermaid Internal Naming and Readability Pattern](../prompts/PATTERNS.md#mermaid-internal-naming-and-readability-pattern), [Mermaid Visual Quality Pattern](../prompts/PATTERNS.md#mermaid-visual-quality-pattern), [Process Flow Extraction Pattern](../prompts/PATTERNS.md#process-flow-extraction-pattern), [Exploration Recovery Pattern](../prompts/PATTERNS.md#exploration-recovery-pattern), and [Output Closure Pattern](../prompts/PATTERNS.md#output-closure-pattern). +- Follow the [Prerequisite Validation Pattern](../prompts/PATTERNS.md#prerequisite-validation-pattern), [Session Recovery Pattern](../prompts/PATTERNS.md#session-recovery-pattern), [Interactive Question Pattern](../prompts/PATTERNS.md#interactive-question-pattern), [Work-Item Target Pattern](../prompts/PATTERNS.md#work-item-target-pattern), [Multi-Repo Validation Pattern](../prompts/PATTERNS.md#multi-repo-validation-pattern), [Token Stewardship Pattern](../prompts/PATTERNS.md#token-stewardship-pattern), [Discovery Exclusion Pattern](../prompts/PATTERNS.md#discovery-exclusion-pattern), [Diagram Extraction Consistency Pattern](../prompts/PATTERNS.md#diagram-extraction-consistency-pattern), [Architecture Diagram Intake Pattern](../prompts/PATTERNS.md#architecture-diagram-intake-pattern), [Diagram Family Intake Pattern](../prompts/PATTERNS.md#diagram-family-intake-pattern), [SVG Output Pattern](../prompts/PATTERNS.md#svg-output-pattern), [Mermaid Internal Naming and Readability Pattern](../prompts/PATTERNS.md#mermaid-internal-naming-and-readability-pattern), [Mermaid Visual Quality Pattern](../prompts/PATTERNS.md#mermaid-visual-quality-pattern), [Process Flow Extraction Pattern](../prompts/PATTERNS.md#process-flow-extraction-pattern), [Exploration Recovery Pattern](../prompts/PATTERNS.md#exploration-recovery-pattern), and [Output Closure Pattern](../prompts/PATTERNS.md#output-closure-pattern). - Required user input is mandatory. - Apply the Work-Item Target Pattern only when the request is explicitly work-item-specific or clearly temporary for one work item, bug, or security issue. -- Generate exactly one diagram artifact set per run unless the user continues through the queue or explicitly requests process-flow batch generation. A `format=mermaid+svg` request is one artifact set with two output files. +- Generate exactly one diagram artifact set per run unless the user continues through the queue or explicitly requests process-flow batch generation. - Treat a clear `/devspec.diagram` request as approval to generate one diagram; ask only when target location, diagram type, scope, evidence, overwrite behavior, or queue continuation is ambiguous, using the matching `selection`, `clarification`, `approval`, or `continuation` intent. - Treat `/devspec.diagram Generate all process-flow diagrams` or equivalent wording as explicit batch-generation approval for eligible process-flow rows in `devspec/architecture/artifact-queue.md`. -- Parse optional output format tokens before generation. Supported tokens are `format=mermaid`, `format=svg`, and `format=mermaid+svg`; default to `mermaid` when absent. Ask one structured `clarification` question for any other `format=` value. +- Parse optional output format tokens before generation. Supported `format=` values contain one or more unique output types from `svg`, `html`, and `mermaid`, joined with `+`. Example: `format=svg`, `format=html`, `format=mermaid`, `format=svg+html`, `format=svg+mermaid`, `format=svg+html+mermaid`, `format=html+mermaid`. Default to `format=svg` when absent. Ask one structured `clarification` question for unknown or duplicated output types. +- Parse structured architecture-diagram input using `PATTERNS.md#architecture-diagram-intake-pattern`; fields such as `Application/System`, `Architecture style`, `Primary goal of diagram`, `Audience`, actors, components, stores, flows, boundaries, design rules, and output format are approved diagram input for one artifact set. +- Parse structured non-architecture diagram input using `PATTERNS.md#diagram-family-intake-pattern`; fields for sequence, state/lifecycle, domain model, journey, timeline/gantt, quadrant, and mindmap diagrams are approved diagram input for one artifact set when they match the selected diagram family. +- Treat editable SVG, SVG-only output, real SVG text, "Generate as SVG", "Generate this as SVG", or "not as a raster image" as the default `format=svg` unless the user explicitly requests an output combination containing `html` or `mermaid`. - Do not invent architecture, user behavior, service interactions, states, or dependencies; separate observed facts from assumptions. +- When structured input says not to add components not listed, treat listed actors, components, systems, and data stores as the complete visible node set unless a confirmed durable artifact conflict requires clarification. - Use the naming and layout guidance in `PATTERNS.md#diagram-extraction-consistency-pattern`, including the language-neutral default catalog when the request matches a catalog subject. - Use `PATTERNS.md#mermaid-internal-naming-and-readability-pattern` for Mermaid node ID, node label, edge label, class, method, layout, and anti-bloat rules. - Apply `PATTERNS.md#mermaid-visual-quality-pattern` fully (theme init, `classDef` palette, node shapes, subgraph boundaries, and guardrails) to every generated `flowchart` and `stateDiagram-v2`; apply complexity guardrails from that pattern to all other supported families. @@ -33,44 +37,46 @@ You generate or update one diagram for a requested architecture, module, feature - Keep runtime communication and compile-time project dependencies in separate diagrams; default to runtime or logical data flow unless the user explicitly requests a project dependency graph. - For logical architecture diagrams, exclude SDLC actors, CI/CD, build artifacts, and source-code project files; enforce sensible C4-style system boundaries and keep owned application databases inside the system boundary. - Avoid API, Swagger, tech stack, version, library, hosting, and framework boilerplate details in flowchart nodes unless the requested diagram specifically needs startup, request-pipeline, infrastructure-layer, or physical deployment detail. -- If the user asks for "only Mermaid", apply that restriction to the Mermaid content inside `Mermaid Diagram`; still preserve required devspec artifact metadata, source evidence, assumptions, and maintenance notes in the generated artifact. -- If the user requests `format=svg`, create or update the Markdown diagram artifact for metadata, evidence, assumptions, maintenance notes, queue linkage, and SVG target reference, but omit the Mermaid block content. Create the SVG under `devspec/architecture/images/dia-NNN-.svg` for durable diagrams or `devspec/work-items//images/.svg` for temporary work-item diagrams. -- If the user requests `format=mermaid+svg`, create or update both the Markdown Mermaid diagram artifact and the SVG image file. -- For SVG output, use `../../devspec/architecture/_template/process-flow-diagram.svg` when the request is explicitly a process-flow SVG or the matched queue row has `process-flow`, `business-process`, `user-journey`, `lifecycle-flow`, or `hybrid-user-to-data-operational-flow` tags. Use `../../devspec/architecture/_template/architecture-diagram.svg` for all other architecture, component, topology, dependency, domain, state, sequence companion, and general workflow SVGs. +- If the user asks for "only Mermaid", treat it as `format=mermaid` and apply that restriction to the Mermaid content inside the optional Markdown artifact. +- If the selected output set includes `svg`, create the SVG under `devspec/architecture/images/dia-NNN-.svg` for durable diagrams or `devspec/work-items//images/.svg` for temporary work-item diagrams. +- If the selected output set includes `mermaid`, create or update the optional Mermaid Markdown diagram artifact for metadata, evidence, assumptions, maintenance notes, queue linkage, and Mermaid content. +- If the selected output set includes `html`, create or update the optional standalone HTML file under `devspec/architecture/html/dia-NNN-.html` for durable diagrams or `devspec/work-items//html/.html` for temporary work-item diagrams. +- All generated SVG and HTML diagram visuals must follow the shared dark architecture-style visual contract from `PATTERNS.md#svg-output-pattern`: dark slate page, framed surface, subtle grid or dividers, monospace typography, semantic neon role colors, real text labels, arrows behind nodes, compact legends, and no white/default/simple styling unless the user explicitly requests a light or custom theme. +- For SVG output, select the template from `PATTERNS.md#svg-output-pattern`: `architecture-diagram.svg`, `process-flow-diagram.svg`, `sequence-diagram.svg`, `state-lifecycle-diagram.svg`, `domain-model-diagram.svg`, `journey-map-diagram.svg`, `timeline-plan-diagram.svg`, `quadrant-analysis-diagram.svg`, or `mindmap-diagram.svg`, using the most specific matching queue tags, explicit request, or diagram family. - Keep queue `Diagram type` as the logical diagram family. Choose the full Mermaid declaration for generated Mermaid content from queue notes, catalog guidance, or evidence, such as `flowchart LR`, `flowchart TD`, `flowchart BT`, `sequenceDiagram`, `stateDiagram-v2`, `erDiagram`, `gantt`, `quadrantChart`, `mindmap`, or `timeline`. - Prefer `flowchart LR` for relationship maps, dependency graphs, event flows, and pipelines; `flowchart TD` for context, topology, hierarchy, data movement, and risk grouping; `sequenceDiagram` for interactions over time; `journey` for user-facing flows; `stateDiagram-v2` for lifecycle behavior; `classDiagram` for stable domain or structural relationships; `erDiagram` for entity relationship models; `gantt` for sprint plans and release schedules; `timeline` for historical milestones and event sequences; `quadrantChart` for 2D priority or risk scoring; and `mindmap` for exploratory domain brainstorming when formal structure is not yet available. - Reuse matching queue metadata for subject, scope, diagram type, target location, evidence, and confidence instead of reclassifying from scratch unless the queued row is stale, contradicted, or incomplete. -- Store stable system, module, feature workflow, user journey, sequence, state, class/domain, process-flow, and cross-feature diagrams under `devspec/architecture/diagrams/dia-NNN-.md` by default. +- Store stable system, module, feature workflow, user journey, sequence, state, class/domain, process-flow, and cross-feature diagrams under `devspec/architecture/images/dia-NNN-.svg` by default. Store optional Mermaid Markdown companions under `devspec/architecture/diagrams/dia-NNN-.md` and optional HTML companions under `devspec/architecture/html/dia-NNN-.html`. - Store work-item diagrams only for explicit requests or clearly temporary bug reproduction, migration path, security incident or threat flow, implementation plan, or experiment flows that should not become durable architecture. - Keep `devspec/architecture/overview.md` limited to architecture context, diagram references, decision references, and architecture gaps or blockers. - Use `devspec/architecture/artifact-queue.md` as the resumable diagram queue. - For durable diagram files, write status only to `devspec/architecture/artifact-queue.md`; do not mirror queue status in the generated diagram file. -- For work-item `diagrams.md`, do not maintain a separate diagram index or status; write temporary work-item-specific diagram content under `Diagram Content` and keep diagram status from `devspec/glossary.md#artifact-status-values` in `devspec/architecture/artifact-queue.md`. +- For work-item diagrams, do not maintain a separate diagram index or status; write temporary SVG output under `images/`, optional Mermaid Markdown content under `Diagram Content`, optional HTML under `html/`, and keep diagram status from `devspec/glossary.md#artifact-status-values` in `devspec/architecture/artifact-queue.md`. - Update `Resume State` in the target diagram artifact, and `Workflow State` in `meta.md` only for work-item diagrams. - Update queue rows before asking for `confirmation`, `approval`, or `continuation`, after generation, or when evidence is missing. -- For process-flow batch generation, select only rows where `Tags` includes `process-flow`, status is `proposed` or `confirmed`, confidence is `observed` or `high-confidence`, target location matches `devspec/architecture/diagrams/dia-NNN-.md`, any recorded output format is valid, and `Next action or notes` records that duplicate check passed. +- For process-flow batch generation, select only rows where `Tags` includes `process-flow`, status is `proposed` or `confirmed`, confidence is `observed` or `high-confidence`, target location matches `devspec/architecture/images/dia-NNN-.svg` unless a non-SVG output set is explicitly requested, any recorded output format is valid, and `Next action or notes` records that duplicate check passed. - Generate process-flow batch rows in `DIA-*` order, never renumber existing rows, mark generated rows `generated`, and leave low-confidence, blocked, ambiguous, or duplicate rows queued with notes. - Ensure generated process-flow diagrams are end-to-end business or operational flows, not module call graphs. The hybrid user-to-data operational flow must include user entry points, application boundaries, services, data stores, validations, operational states, and outcomes without becoming a pure infrastructure or database diagram. - For process-flow SVGs, keep the happy path visually obvious, use distinct roles for start/end, manual, automated, integration, decision, exception, and artifact steps, draw exception paths as labeled dashed rose arrows, label loop-backs or rework paths, and avoid dangling branches. -- Before writing, check `devspec/architecture/diagrams/*.md`, `devspec/architecture/images/*.svg`, `devspec/architecture/overview.md`, `devspec/architecture/artifact-queue.md`, and relevant work-item `diagrams.md` and `images/*.svg` files for equivalent diagrams. -- Use `../../devspec/architecture/_template/diagram.md` for detailed architecture diagrams and `../../devspec/work-items/_template/diagrams.md` only for explicit or temporary work-item diagrams. -- Use the selected SVG template from `../../devspec/architecture/_template/architecture-diagram.svg` or `../../devspec/architecture/_template/process-flow-diagram.svg` as the starting point unless a documented constraint requires a smaller custom SVG. +- Before writing, check `devspec/architecture/images/*.svg`, `devspec/architecture/diagrams/*.md`, `devspec/architecture/html/*.html`, `devspec/architecture/overview.md`, `devspec/architecture/artifact-queue.md`, and relevant work-item `images/*.svg`, `diagrams.md`, and `html/*.html` files for equivalent diagrams. +- Use `../../devspec/architecture/_template/diagram.md` only when the selected output set includes `mermaid` for detailed architecture diagrams, `../../devspec/architecture/_template/diagram.html` only when the selected output set includes `html`, and `../../devspec/work-items/_template/diagrams.md` only when the selected output set includes `mermaid` for explicit or temporary work-item diagrams. +- Use the selected SVG template from `../../devspec/architecture/_template/` as the starting point unless a documented constraint requires a smaller custom SVG. A custom SVG must still preserve the shared dark visual contract. - Prefer existing devspec artifacts, queue rows, manifests, and targeted reads before broad search or Explore runs. - Never use an excluded diagram family from `PATTERNS.md#excluded-diagram-families`. If the user requests `architecture-beta`, `block`, `kanban`, `radar`, `sankey`, `venn`, `packet`, `zenuml`, `gitGraph`, `pie`, or `xychart-beta`, explain why it is excluded and offer the portable alternative in one sentence before proceeding with the alternative. ## Approach -1. Parse the requested subject, scope, audience, and diagram type. +1. Parse the requested subject, scope, audience, diagram type, and any structured architecture or diagram-family intake fields. 2. Read relevant architecture, foundation, queue, and work-item artifacts only when referenced. 3. Reconcile `Resume State`, existing queue rows, discovery exclusions, and optional exploration state. 4. Match the request to an existing queue row when possible, then reuse its scope, diagram type, subject, target location, evidence, and confidence. 5. Classify scope as `architecture`, `module`, `feature`, `workflow`, `user-journey`, or `work-item` only when no usable queue row exists. -6. Select the output format, diagram type, and Mermaid declaration when Mermaid output is selected, or ask one structured `selection` question when the format, diagram type, declaration, or target location is ambiguous. +6. Select the output format, diagram type, and Mermaid declaration when the selected output set includes `mermaid`, defaulting to `format=svg`, or ask one structured `selection` question when the format, diagram type, declaration, or target location is ambiguous. 7. Gather evidence with targeted reads, search, or Explore. 8. Check for an equivalent existing diagram before adding a queue row or writing output. 9. Add or update queue rows with scope, diagram type, subject, target location, evidence, confidence, status, tags, and next action or notes that include the duplicate-check result. 10. If the user requested process-flow batch generation, filter eligible process-flow rows and generate them in `DIA-*` order. 11. Otherwise, ask one structured `clarification`, `approval`, or `continuation` question for clarification, overwrite approval, or queue continuation when needed. -12. Generate selected output: for Mermaid, follow the Mermaid internal naming and visual quality rules; for SVG, follow the SVG Output Pattern, use the SVG template, avoid external assets and forbidden elements, and validate the file as XML before reporting success. Then write `Diagram Metadata`, selected diagram sections, `Source Evidence and Assumptions`, and any `Maintenance Notes` to the Markdown target, write the SVG target when selected, add or update the `overview.md` `Diagram Reference Index` row when the diagram is durable, mark generated queue rows `generated`, `skipped`, or `blocked`, and report per Output Format. +12. Generate selected output: for SVG, follow the SVG Output Pattern, use the SVG template, avoid external assets and forbidden elements, and validate the file as XML before reporting success; for Mermaid output, create the optional Markdown artifact and follow Mermaid internal naming and visual quality rules; for HTML output, use the HTML template and keep it standalone and static. Then write selected output targets, add or update the `overview.md` `Diagram Reference Index` row when the diagram is durable, mark generated queue rows `generated`, `skipped`, or `blocked`, and report per Output Format. ## Output Format - Diagram target location diff --git a/.github/agents/devspec.extract.agent.md b/.github/agents/devspec.extract.agent.md index 0a41a44..f7a4f2d 100644 --- a/.github/agents/devspec.extract.agent.md +++ b/.github/agents/devspec.extract.agent.md @@ -41,17 +41,17 @@ You create or refresh devspec extraction artifacts from supported repository sou - Use `devspec/foundation/extraction-state.md` only for the extraction queue, resume state, blockers, and confirmations. Keep extracted facts in target artifacts, reusable discovery methods in `devspec/foundation/exploration-state.md`, and diagram queue state in `devspec/architecture/artifact-queue.md`. - Write or update `devspec/architecture/overview.md` and relevant live `devspec/foundation/` files. - Use `devspec/architecture/_template/*.md` and `devspec/foundation/_template/*.md` as section contracts; initialize missing live files from templates, but do not overwrite existing live files from templates. -- During the `process-flows` extraction row, seed business-centric end-to-end process-flow candidates in `devspec/architecture/artifact-queue.md` when they meet the process-flow rubric and pass the equivalent-diagram check. Preserve requested output format notes when input includes `format=svg` or `format=mermaid+svg`; default remains `format=mermaid`. +- During the `process-flows` extraction row, seed business-centric end-to-end process-flow candidates in `devspec/architecture/artifact-queue.md` when they meet the process-flow rubric and pass the equivalent-diagram check. Preserve requested output format notes when input includes supported diagram format tokens; default remains `format=svg`. - Include process-flow rows for business workflows, user journeys, lifecycle flows, cross-service process sequences, and the default `Hybrid User-to-Data Operational Flow` when evidence supports user entry points through application boundaries, services, integrations, data stores, validations, operational states, and outcomes. - During the `diagram-candidates` extraction row, seed non-process-flow architecture, module, feature workflow, sequence, state, class/domain, and user-journey candidates in `devspec/architecture/artifact-queue.md` only when they meet the diagram extraction rubric and pass the equivalent-diagram check. - Use the language-neutral default catalog in `PATTERNS.md#default-diagram-candidate-catalog` when selecting diagram candidates. Do not create language-, framework-, vendor-, or platform-specific default subjects. - Treat `/devspec.extract` as queue-first discovery seeding for diagram candidates; recommend `/devspec.diagram` as the normal follow-up for generation. - Add queued candidates in queue order with ID, scope, diagram type, subject, target location, evidence, confidence, status, tags, and next action or notes that include the duplicate-check result. -- Use sequence-preserving naming for durable diagram candidates: `DIA-001` maps to subject `dia-001-`, Markdown target `devspec/architecture/diagrams/dia-001-.md`, and optional SVG target `devspec/architecture/images/dia-001-.svg`. Never renumber existing `DIA-*` rows or generated `dia-NNN-*` files. +- Use sequence-preserving naming for durable diagram candidates: `DIA-001` maps to subject `dia-001-`, default SVG target `devspec/architecture/images/dia-001-.svg`, optional Mermaid Markdown target `devspec/architecture/diagrams/dia-001-.md`, and optional HTML target `devspec/architecture/html/dia-001-.html`. Never renumber existing `DIA-*` rows or generated `dia-NNN-*` files. - Tag process-flow rows with `process-flow`, plus narrower tags such as `business-process`, `user-journey`, `lifecycle-flow`, or `hybrid-user-to-data-operational-flow` when they apply. -- Keep queue `Diagram type` limited to the logical diagram family. Record suggested Mermaid declarations such as `flowchart LR`, `flowchart TD`, or `sequenceDiagram`, plus output format tokens such as `format=svg` or `format=mermaid+svg`, in `Next action or notes` when they will help `/devspec.diagram`. -- When queueing process-flow or diagram candidates, record in queue notes that future Mermaid generation must follow `PATTERNS.md#mermaid-internal-naming-and-readability-pattern` and `PATTERNS.md#mermaid-visual-quality-pattern`, and future SVG generation must follow `PATTERNS.md#svg-output-pattern`. For process-flow SVG candidates, note that `/devspec.diagram` must use `devspec/architecture/_template/process-flow-diagram.svg`; for other SVG candidates, use `devspec/architecture/_template/architecture-diagram.svg`. Do not queue diagram families listed in `PATTERNS.md#excluded-diagram-families` such as `architecture-beta`, `block`, or `xychart-beta`; use the documented portable alternative instead. -- Ask one structured `approval` question before generating diagrams during extraction. Generate at most one confirmed diagram artifact set only if the user explicitly continues within the extraction run, update its queue status, then stop or ask one structured `continuation` question only when no higher-priority confirmation is pending. Honor `format=svg` and `format=mermaid+svg` only after this approval. +- Keep queue `Diagram type` limited to the logical diagram family. Record suggested Mermaid declarations such as `flowchart LR`, `flowchart TD`, or `sequenceDiagram` when the output set includes `mermaid`, plus requested output format tokens such as `format=svg`, `format=html`, `format=mermaid`, `format=svg+html`, `format=svg+mermaid`, `format=svg+html+mermaid`, or `format=html+mermaid`, in `Next action or notes` when they will help `/devspec.diagram`. +- When queueing process-flow or diagram candidates, record in queue notes that future Mermaid generation must follow `PATTERNS.md#mermaid-internal-naming-and-readability-pattern` and `PATTERNS.md#mermaid-visual-quality-pattern`, and future SVG generation must select the SVG template from `PATTERNS.md#svg-output-pattern`. Do not queue diagram families listed in `PATTERNS.md#excluded-diagram-families` such as `architecture-beta`, `block`, or `xychart-beta`; use the documented portable alternative instead. +- Ask one structured `approval` question before generating diagrams during extraction. Generate at most one confirmed diagram artifact set only if the user explicitly continues within the extraction run, update its queue status, then stop or ask one structured `continuation` question only when no higher-priority confirmation is pending. Honor requested diagram output formats only after this approval. - On rerun, resume `devspec/architecture/artifact-queue.md` before proposing duplicate candidates; when several queue items are pending, ask only about the next unresolved row. - Do not create ADR files unless the user explicitly asks and the decision has clear supporting evidence. When an ADR is needed, initialize it from `devspec/architecture/_template/decision.md` and create `devspec/architecture/decisions/` on demand. - For multi-repo inputs, produce an architecture overview, keep per-repository provenance visible, and use supplied labels as repository names and role candidates in `codebase-structure.md`. @@ -74,8 +74,8 @@ You create or refresh devspec extraction artifacts from supported repository sou 6. Use `Explore` only when targeted reads and search are insufficient for the active row. 7. Update the active target artifact with compact evidence-backed records, preserving manual content. 8. Record blockers, confirmations, or completion in `extraction-state.md` before asking, pausing, blocking, or moving to the next row. -9. For `process-flows`, update only `devspec/architecture/artifact-queue.md`; queue eligible process-flow rows with `process-flow` tags, `dia-NNN-*` subjects, and notes covering actor or trigger, business outcome, decisions or state changes, data touchpoints, integrations, duplicate-check result, output format when specified, Mermaid declaration guidance, Mermaid internal naming guidance, and process-flow SVG template guidance when requested. -10. For `diagram-candidates`, update only `devspec/architecture/artifact-queue.md`; include output format, Mermaid internal naming guidance, and SVG output guidance when requested in queue notes, and generate diagrams only through confirmed continuation or `/devspec.diagram`. +9. For `process-flows`, update only `devspec/architecture/artifact-queue.md`; queue eligible process-flow rows with `process-flow` tags, `dia-NNN-*` subjects, and notes covering actor or trigger, business outcome, decisions or state changes, data touchpoints, integrations, duplicate-check result, output format when specified, Mermaid declaration and internal naming guidance when the output set includes `mermaid`, and process-flow SVG template guidance when the output set includes `svg`. +10. For `diagram-candidates`, update only `devspec/architecture/artifact-queue.md`; include output format, Mermaid internal naming guidance when the output set includes `mermaid`, SVG output guidance when the output set includes `svg`, and HTML output guidance when the output set includes `html` in queue notes, and generate diagrams only through confirmed continuation or `/devspec.diagram`. 11. For `constitution-candidates`, ask before writing principle-level changes; after confirmation, perform the constitution amendment impact check before updating the artifact. 12. Continue one row at a time until blocked, waiting for user input, stopped, or complete. 13. Report per Output Format. diff --git a/.github/prompts/PATTERNS.md b/.github/prompts/PATTERNS.md index e043a33..f9dba6e 100644 --- a/.github/prompts/PATTERNS.md +++ b/.github/prompts/PATTERNS.md @@ -176,38 +176,154 @@ Standard stage-specific option sets: - Use this pattern when extraction proposes diagram candidates or `/devspec.diagram` generates or updates a diagram. - Queue only candidates backed by concrete repository evidence from owned routes, modules, workflows, state transitions, services, integrations, ADRs, docs, infrastructure, runtime config, or manifests. - Each queued candidate must include ID, scope, diagram type, subject, target location, evidence, confidence, status, tags, and next action or notes. Record the equivalent-diagram check result in `Next action or notes`. -- Diagram output format defaults to `mermaid`. Accept only `format=mermaid`, `format=svg`, or `format=mermaid+svg` in user input or queue notes. Ask one structured `clarification` question for unsupported `format=` values before writing output. +- Diagram output format defaults to `svg`. Accept `format=` values made from one or more unique output types from `svg`, `html`, and `mermaid`, joined with `+`. Example: `format=svg`, `format=html`, `format=mermaid`, `format=svg+html`, `format=svg+mermaid`, `format=svg+html+mermaid`, `format=html+mermaid`. Reject duplicated or unknown output types, such as `format=svg+svg`, `format=png`, or `format=pdf`, with one structured `clarification` question before writing output. +- Format examples: + - `/devspec.diagram runtime architecture` -> generate SVG only. + - `/devspec.diagram format=html runtime architecture` -> generate HTML only. + - `/devspec.diagram format=mermaid runtime architecture` -> generate Mermaid only, stored in the Markdown artifact. + - `/devspec.diagram format=svg+html runtime architecture` -> generate SVG and HTML only. + - `/devspec.diagram format=svg+mermaid runtime architecture` -> generate SVG and Mermaid only. + - `/devspec.diagram format=html+mermaid runtime architecture` -> generate HTML and Mermaid only; do not generate SVG. + - `/devspec.diagram format=svg+html+mermaid runtime architecture` -> generate all three output types. - Use stable IDs such as `DIA-001`, `DIA-002`, preserving existing IDs and assigning the next available number for new rows. - Keep subjects specific enough to become one diagram file. Use Title Case for display names and lowercase kebab-case for subject slugs. -- For durable architecture diagram queue rows, use the queue ID as the sequence anchor: `DIA-001` maps to subject `dia-001-`, Markdown target `devspec/architecture/diagrams/dia-001-.md`, optional SVG target `devspec/architecture/images/dia-001-.svg`, and display title `DIA-001 - `. +- For durable architecture diagram queue rows, use the queue ID as the sequence anchor: `DIA-001` maps to subject `dia-001-<diagram-name>`, default SVG target `devspec/architecture/images/dia-001-<diagram-name>.svg`, optional Mermaid Markdown target `devspec/architecture/diagrams/dia-001-<diagram-name>.md`, optional HTML target `devspec/architecture/html/dia-001-<diagram-name>.html`, and display title `DIA-001 - <Title Case Diagram Name>`. - Never renumber existing `DIA-*` rows, generated `dia-NNN-*` diagram files, or generated `dia-NNN-*` SVG files. New diagrams get the next available `DIA-*` ID and matching lowercase `dia-NNN-*` subject prefix. - Avoid language, framework, vendor, or platform names in default diagram subjects. Use language-specific evidence only as supporting evidence unless the user explicitly requests a specialized diagram. -- Prefer reusable architecture, module, feature, workflow, sequence, state, or user-journey diagrams over temporary work-item diagrams. Use work-item `diagrams.md` and optional `devspec/work-items/<work-item-folder>/images/<diagram-name>.svg` only for explicit or clearly temporary work-item-specific diagram content, and keep diagram status in `devspec/architecture/artifact-queue.md`. +- Prefer reusable architecture, module, feature, workflow, sequence, state, or user-journey diagrams over temporary work-item diagrams. Use work-item `images/<diagram-name>.svg` by default, optional work-item `diagrams.md`, and optional `html/<diagram-name>.html` only for explicit or clearly temporary work-item-specific diagram content, and keep diagram status in `devspec/architecture/artifact-queue.md`. - Use queue `Tags` for durable selection and batch processing. Process-flow rows must include `process-flow`; add narrower tags such as `business-process`, `user-journey`, `lifecycle-flow`, or `hybrid-user-to-data-operational-flow` when they apply. -- Use queue `Diagram type` for the logical diagram family only: `flowchart`, `sequenceDiagram`, `journey`, `stateDiagram`, `classDiagram`, `erDiagram`, `gantt`, `quadrantChart`, `mindmap`, or `timeline`. Record orientation such as `LR`, `TD`, or `BT` and output format such as `format=svg` or `format=mermaid+svg` in `Next action or notes` when useful. Write the full Mermaid declaration in the generated Markdown artifact when Mermaid output is selected. +- Use queue `Diagram type` for the logical diagram family only: `flowchart`, `sequenceDiagram`, `journey`, `stateDiagram`, `classDiagram`, `erDiagram`, `gantt`, `quadrantChart`, `mindmap`, or `timeline`. Record orientation such as `LR`, `TD`, or `BT` and output format in `Next action or notes` when useful. Examples: `format=svg`, `format=html`, `format=mermaid`, `format=svg+html`, `format=svg+mermaid`, `format=svg+html+mermaid`, `format=html+mermaid`. Write the full Mermaid declaration in the optional Mermaid Markdown artifact when Mermaid output is selected. - Use `flowchart LR` for relationship maps, dependency graphs, event flows, and pipelines. Use `flowchart TD` for context, topology, hierarchy, data movement, and risk grouping. Use `flowchart BT` only for optional layer dependency views where lower layers should appear as foundations. - Use `sequenceDiagram` for actor, service, workflow, or security interactions over time; `journey` for user-facing paths; `stateDiagram-v2` for lifecycle or status transitions; `classDiagram` for stable domain or structural relationships; and `erDiagram` for entity relationship models. - Use confidence values consistently: `observed` for directly supported code, docs, config, or ADR evidence; `high-confidence` for inference from multiple local evidence points; `low-confidence` only when useful but incomplete evidence must be recorded as an assumption. - Do not queue vague subjects, candidates without source evidence, duplicate or equivalent existing diagrams, or temporary work-item diagrams without an explicit request. - Use `blocked` when a diagram idea is useful but evidence is insufficient; use `skipped` only after the user declines generation. -- Before queueing or writing, check `devspec/architecture/artifact-queue.md`, `devspec/architecture/overview.md`, `devspec/architecture/diagrams/*.md`, `devspec/architecture/images/*.svg`, and relevant work-item `diagrams.md` and `images/*.svg` files for equivalent subject, scope, diagram type, or target location. +- Before queueing or writing, check `devspec/architecture/artifact-queue.md`, `devspec/architecture/overview.md`, `devspec/architecture/images/*.svg`, `devspec/architecture/diagrams/*.md`, `devspec/architecture/html/*.html`, and relevant work-item `images/*.svg`, `diagrams.md`, and `html/*.html` files for equivalent subject, scope, diagram type, or target location. - Avoid duplicate overview diagrams unless `devspec/architecture/overview.md` lacks a confirmed architecture context or diagram reference entry. - During `/devspec.extract`, seed candidates in `devspec/architecture/artifact-queue.md` and ask only about the next unresolved candidate after higher-priority confirmations. Generate diagrams later through `/devspec.diagram` unless the user explicitly continues through the confirmed queue. -- During `/devspec.extract`, honor `format=svg` and `format=mermaid+svg` as generation preferences only after explicit approval; extraction may generate at most one approved diagram artifact set before stopping or asking for continuation. -- During `/devspec.diagram`, reuse matching queue metadata instead of reclassifying the same subject from scratch. Generate exactly one evidence-backed diagram artifact set per run unless the user requests process-flow batch generation. A `mermaid+svg` request is one artifact set with both outputs. +- During `/devspec.extract`, honor requested diagram output formats as generation preferences only after explicit approval; extraction may generate at most one approved diagram artifact set before stopping or asking for continuation. +- During `/devspec.diagram`, reuse matching queue metadata instead of reclassifying the same subject from scratch. Generate exactly one evidence-backed diagram artifact set per run unless the user requests process-flow batch generation. + +## Architecture Diagram Intake Pattern + +- Use this pattern when `/devspec.diagram` receives structured architecture-diagram input with fields such as `Application/System`, `Architecture style`, `Primary goal of diagram`, `Audience`, `Users/Actors`, `Core components`, `External systems`, `Data stores`, `Key flows`, `Boundaries`, `Design rules`, or `Output format`. +- Treat structured architecture-diagram input as approved input for one `/devspec.diagram` artifact set. Continue to follow the [Diagram Extraction Consistency Pattern](#diagram-extraction-consistency-pattern), [SVG Output Pattern](#svg-output-pattern), [Mermaid Internal Naming and Readability Pattern](#mermaid-internal-naming-and-readability-pattern), [Mermaid Visual Quality Pattern](#mermaid-visual-quality-pattern), and duplicate checks before writing. +- Preserve SVG as the default output. Treat editable SVG, SVG-only output, real SVG text, "Generate as SVG", "Generate this as SVG", or "not as a raster image" as `format=svg` unless the user explicitly requests an output combination that includes `html` or `mermaid`. +- Map `Application/System` to diagram subject and title unless a matching queue row already supplies a durable subject. Map `Architecture style`, `Primary goal of diagram`, and `Audience` into diagram metadata, queue notes, source evidence or assumptions, and maintenance notes when they affect generation. +- Map `Users/Actors`, `Core components`, `External systems`, `Data stores`, and `Boundaries` to visible diagram content only when supported by user-confirmed input, existing `devspec/` artifacts, or repository evidence. Keep `Core components` as components with short labels; put responsibilities in evidence or assumptions unless a label can remain 1-4 words. +- Map `Key flows` to numbered arrows when SVG output is selected. For Mermaid output, keep edge labels short and omit visible step numbers unless the user explicitly requests numbered flows and the diagram remains readable. +- Map `Design rules` into layout guidance only when they do not conflict with canonical devspec rules. Preserve 16:9 landscape, clear left-to-right or top-to-bottom flow, grouped components, dashed boundaries, short labels, low connector crossings, and a legend for SVG output. +- If the input says `Do not add any components not listed above`, `Do not add components`, or equivalent, treat the listed components and systems as authoritative. Do not add inferred visible nodes; record missing but relevant repository evidence as assumptions, blockers, or maintenance notes instead. +- If structured input conflicts with confirmed architecture artifacts, ADRs, foundation rules, or repository evidence, record the conflict and ask one structured question only when choosing either source would materially change the diagram scope, security/compliance meaning, or target artifact. Otherwise prefer confirmed durable artifacts and record the user input as an assumption or note. +- Keep SVG architecture diagrams presentation-ready: 16:9 canvas, standalone XML, real `<text>` elements, numbered flow markers, dashed boundary boxes, short labels, and a legend. Never embed rasterized text. + +Compact neutral example: + +```text +/devspec.diagram + +Application/System: +Customer Portal + +Architecture style: +cloud-native + +Primary goal of diagram: +Explain runtime flow and data movement. + +Audience: +Developers and architects. + +Users/Actors: +- Customer +- Support agent + +Core components: +- Web app: user entry point +- API service: business operations +- Worker: asynchronous processing + +External systems: +- Identity provider: authentication +- Payment gateway: payments + +Data stores: +- Customer database: profiles and orders + +Key flows: +1. User signs in through the identity provider. +2. Web app calls the API service. +3. API service reads and writes customer data. +4. Worker processes asynchronous jobs. +5. API service sends payment requests to the gateway. + +Boundaries: +- Client boundary +- Application boundary +- External services boundary + +Design rules: +- Use a 16:9 landscape layout +- Use numbered arrows +- Use dashed boxes for boundaries +- Include a legend + +Output format: +Editable SVG. +``` + +## Diagram Family Intake Pattern + +- Use this pattern when `/devspec.diagram` receives structured non-architecture input for `sequenceDiagram`, `stateDiagram`, `classDiagram`, `erDiagram`, `journey`, `timeline`, `gantt`, `quadrantChart`, or `mindmap` content. +- Treat structured family-specific input as approved input for one `/devspec.diagram` artifact set. Continue to follow the [Diagram Extraction Consistency Pattern](#diagram-extraction-consistency-pattern), [SVG Output Pattern](#svg-output-pattern), [Mermaid Internal Naming and Readability Pattern](#mermaid-internal-naming-and-readability-pattern), [Mermaid Visual Quality Pattern](#mermaid-visual-quality-pattern), and duplicate checks before writing. +- Preserve SVG as the default output. Treat editable SVG, SVG-only output, real SVG text, "Generate as SVG", "Generate this as SVG", or "not as a raster image" as `format=svg` unless the user explicitly requests an output combination that includes `html` or `mermaid`. +- Map shared fields such as `Subject`, `Title`, `Purpose`, `Audience`, `Scope`, `Evidence`, `Source`, `Output format`, `Design rules`, and `Exclusions` into diagram metadata, queue notes, source evidence or assumptions, maintenance notes, and generated content when they affect generation. +- If structured input says `Do not add items`, `Use only listed items`, `Do not infer additional nodes`, or equivalent, treat the listed participants, states, entities, stages, milestones, plotted items, or topics as the complete visible set. Do not add inferred visible elements; record missing but relevant repository evidence as assumptions, blockers, or maintenance notes instead. +- If structured input conflicts with confirmed architecture artifacts, ADRs, foundation rules, or repository evidence, record the conflict and ask one structured question only when choosing either source would materially change the diagram scope, security/compliance meaning, lifecycle/state meaning, data/domain meaning, timeline meaning, scoring meaning, or target artifact. Otherwise prefer confirmed durable artifacts and record the user input as an assumption or note. +- Keep family-specific labels short and evidence-backed. Put long explanations in source evidence, assumptions, or maintenance notes rather than visible nodes, messages, states, cards, milestones, plotted labels, or branch labels. +- Use family-specific mappings only for fields that materially change visible diagram content: + +| Diagram family | Structured input fields to map | +| --- | --- | +| `sequenceDiagram` | `Participants`, `Actors`, `Systems`, `Messages`, `Steps`, `Happy path`, `Error path`, `Method labels`, `Collapsed intermediaries`, `Notes` | +| `stateDiagram` / lifecycle | `States`, `Start state`, `End state`, `Terminal states`, `Transitions`, `Events`, `Guards`, `Exception states`, `Rework states`, `State groups` | +| `classDiagram` / `erDiagram` / domain model | `Entities`, `Classes`, `Fields`, `Methods`, `Relationships`, `Cardinality`, `Aggregate boundaries`, `External entities`, `Ownership` | +| `journey` | `Actor`, `Persona`, `Stages`, `Actor touchpoints`, `System touchpoints`, `Decisions`, `Outcomes`, `Pain points`, `Status signals` | +| `timeline` / `gantt` | `Phases`, `Milestones`, `Dates`, `Periods`, `Dependencies`, `Gates`, `Risks`, `Owners`, `Release markers` | +| `quadrantChart` | `X axis`, `Y axis`, `Quadrant labels`, `Plotted items`, `Scores`, `Scoring meaning`, `Thresholds`, `Priority notes` | +| `mindmap` | `Central topic`, `Branch groups`, `Child topics`, `Relationships`, `Priority branches`, `Open questions`, `Notes` | ## SVG Output Pattern -- Use this pattern when `/devspec.diagram` or approved `/devspec.extract` continuation generates SVG output. -- Mermaid remains the default output. `format=svg` generates an SVG file and a metadata Markdown artifact without a Mermaid block. `format=mermaid+svg` generates both the Mermaid block and an SVG companion. `format=mermaid` is equivalent to the default. -- Store durable SVG files under `devspec/architecture/images/dia-NNN-<diagram-name>.svg`. Store temporary work-item SVG files under `devspec/work-items/<work-item-folder>/images/<diagram-name>.svg`. -- For SVG-only output, still create or update the Markdown diagram artifact for `Resume State`, `Diagram Metadata`, source evidence, assumptions, maintenance notes, queue row, and SVG target reference. Do not skip devspec metadata. -- Select the SVG template deterministically. Use `devspec/architecture/_template/process-flow-diagram.svg` when the queue row has `process-flow`, `business-process`, `user-journey`, `lifecycle-flow`, or `hybrid-user-to-data-operational-flow` tags, or when the request explicitly asks for a process-flow SVG. Use `devspec/architecture/_template/architecture-diagram.svg` for architecture, component, topology, dependency, domain, state, sequence companion, and general workflow SVGs. +- Use this pattern when `/devspec.diagram` or approved `/devspec.extract` continuation generates SVG, Mermaid, or HTML output. +- SVG is the default output. `format=svg` generates the SVG visual output plus required queue or overview metadata. Any accepted combination generates exactly the requested output types: `svg` for the SVG visual output, `mermaid` for the optional Markdown/Mermaid artifact, and `html` for the optional standalone HTML artifact. +- Store durable SVG files under `devspec/architecture/images/dia-NNN-<diagram-name>.svg`, optional Mermaid files under `devspec/architecture/diagrams/dia-NNN-<diagram-name>.md`, and optional HTML files under `devspec/architecture/html/dia-NNN-<diagram-name>.html`. Store temporary work-item SVG files under `devspec/work-items/<work-item-folder>/images/<diagram-name>.svg`, optional Mermaid content in `devspec/work-items/<work-item-folder>/diagrams.md`, and optional HTML files under `devspec/work-items/<work-item-folder>/html/<diagram-name>.html`. +- For SVG-only output, do not create a Markdown diagram artifact unless requested. Preserve resumability and evidence through `devspec/architecture/artifact-queue.md`, `devspec/architecture/overview.md` diagram references, SVG metadata elements, and queue notes. +- Select the SVG template deterministically from the matrix below. Use the most specific matching row by queue tags, explicit user request, or diagram family before falling back to `architecture-diagram.svg`; do not invent ad hoc SVG layouts when a matching template exists. + +| Diagram request, family, or tags | SVG template | +| --- | --- | +| Architecture, component, topology, dependency graph, API surface, event/message map, data ownership flow, deployment topology, configuration/secrets flow, risk/hotspot map, generic workflow map | `devspec/architecture/_template/architecture-diagram.svg` | +| `process-flow`, `business-process`, process-flow rows tagged `user-journey` or `lifecycle-flow`, `hybrid-user-to-data-operational-flow`, explicit process-flow SVG | `devspec/architecture/_template/process-flow-diagram.svg` | +| `sequenceDiagram`, interaction sequence, authentication/authorization sequence, critical workflow sequence | `devspec/architecture/_template/sequence-diagram.svg` | +| `stateDiagram`, `stateDiagram-v2`, lifecycle, status transition | `devspec/architecture/_template/state-lifecycle-diagram.svg` | +| `classDiagram`, `erDiagram`, domain model, domain structure, entity relationship | `devspec/architecture/_template/domain-model-diagram.svg` | +| `journey`, explicit user journey that is not a process-flow row | `devspec/architecture/_template/journey-map-diagram.svg` | +| `timeline`, `gantt`, release timeline, migration timeline, sprint or release plan | `devspec/architecture/_template/timeline-plan-diagram.svg` | +| `quadrantChart`, risk quadrant, priority quadrant, 2D scoring | `devspec/architecture/_template/quadrant-analysis-diagram.svg` | +| `mindmap`, domain capability mindmap, explicit brainstorming map | `devspec/architecture/_template/mindmap-diagram.svg` | + - Generated SVG files must be standalone XML with `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 WIDTH HEIGHT" role="img" aria-labelledby="title desc">`, inline `<defs>` and `<style>`, and no external assets. +- Generated SVG and HTML visual output must follow the shared devspec dark visual contract unless the user explicitly requests a light or custom theme: dark slate page background `#020617`, framed surface `#0f172a`, subtle grid or divider lines `#1e293b`, primary text `#f8fafc`, secondary text `#cbd5e1` or `#94a3b8`, Apache-2.0-distribution-safe monospace font stack `"JetBrains Mono", "Cascadia Code", monospace`, and the semantic role palette used by the Mermaid Visual Quality Pattern. Do not name proprietary system font fallbacks in generated SVG or HTML, and do not bundle, embed, or fetch font files unless their open-font license and required notices are included with the distribution. +- Do not generate white-background, default-renderer, or simple unstylized SVG/HTML diagrams for `/devspec.diagram`. If a renderer or diagram family cannot honor the dark visual contract, prefer generating the SVG companion as the canonical visual output and record the limitation in the Mermaid or HTML artifact notes. +- Use a 16:9 landscape SVG canvas by default, preferably `viewBox="0 0 1600 900"` for durable diagrams. Smaller custom SVGs are allowed only when documented constraints require them, and they must still keep the same dark chrome, monospace typography, role colors, line treatment, real `<text>` labels, and compact legend style. +- Keep process-flow, journey, state, sequence companion, domain, workflow, and architecture SVGs visually related: same dark background, grid, framed surface, title treatment, footer treatment, semantic role colors, and legend treatment. Preserve family-specific semantics such as process lanes, decisions, exceptions, loop-backs, actors, stores, and boundaries inside that shared style. - Do not include `<script>`, `<iframe>`, `<foreignObject>`, remote images, remote fonts, external stylesheets, secrets, tokens, credentials, internal-only URLs, or visible placeholder tokens in generated SVG output. - Keep visible SVG text short: noun labels for nodes, protocol or action labels for arrows, and no paragraphs. Use semantic colors consistently with the Mermaid visual palette. - Draw arrows behind nodes, keep labels clear of connectors, keep the legend outside major boundaries, and ensure the diagram remains readable at README width and when exported to PNG or PDF. - Before reporting success, validate the generated SVG as XML and check required root attributes, forbidden elements, unresolved placeholders, obvious text overlap, and evidence-backed content. +- For `format=html`, create a standalone `.html` file with escaped text, inline CSS, no scripts, no iframes, no remote assets, no remote fonts, no secrets, and no unresolved placeholders. Render the same evidence-backed diagram content as static HTML using the same dark visual contract as the SVG output. +- For `format=mermaid`, use `devspec/architecture/_template/diagram.md` for durable diagrams or `devspec/work-items/_template/diagrams.md` for temporary work-item diagrams, and include Mermaid content. ## Mermaid Internal Naming and Readability Pattern @@ -260,6 +376,7 @@ Standard stage-specific option sets: - Do not add `%%{init:...}%%` to `sequenceDiagram`, `journey`, `classDiagram`, `erDiagram`, `gantt`, `quadrantChart`, `mindmap`, or `timeline` blocks; those diagram families rely on renderer-managed defaults. - For `stateDiagram-v2`, include the init block only when the rendering context is confirmed to support it; omit it otherwise. +- Mermaid output is not the canonical visual target when renderer support conflicts with the shared dark visual contract. When a Mermaid family or host renderer cannot reliably enforce dark styling, keep the Mermaid syntactically portable, record the renderer limitation in notes, and use SVG or HTML output for the consistent architecture-style visual. ### Semantic `classDef` Palette @@ -325,39 +442,39 @@ Standard stage-specific option sets: - Include user journeys, lifecycle flows, cross-service process sequences, and hybrid user-to-data operational flows when they explain an end-to-end business process. - Do not treat pure structural maps, generic CRUD paths, deployment pipelines, CI/CD, authentication or configuration flows, or one-off work-item diagrams as process flows unless the user explicitly requests them. - Discover process-flow evidence from owned routes, controllers, service methods, state transitions, jobs, event handlers, tests, docs, ADRs, integration boundaries, domain terms, user-facing actions, data stores, validations, and business outcomes. -- Queue one row per distinct durable process flow, with `process-flow` in `Tags`, a `dia-NNN-<diagram-name>` subject, a matching Markdown target under `devspec/architecture/diagrams/`, and notes that name the actor or trigger, business outcome, major decisions or state changes, data touchpoints, integrations, duplicate-check result, suggested Mermaid declaration, and any requested SVG output format. +- Queue one row per distinct durable process flow, with `process-flow` in `Tags`, a `dia-NNN-<diagram-name>` subject, a default SVG target under `devspec/architecture/images/`, and notes that name the actor or trigger, business outcome, major decisions or state changes, data touchpoints, integrations, duplicate-check result, requested output format, process-flow SVG template guidance, and suggested Mermaid declaration when the output set includes `mermaid`. - Queue the default hybrid candidate when evidence can connect user entry points to application boundaries, services, integrations, data stores, validations, operational states, and outcomes: `Hybrid User-to-Data Operational Flow`, subject `dia-NNN-hybrid-user-to-data-operational-flow`, scope `workflow`, diagram type `flowchart`, declaration `flowchart TD`, tags `process-flow, business-process, hybrid-user-to-data-operational-flow`. - Use `observed` only when source evidence directly supports the process flow. Use `high-confidence` when multiple local evidence points support the flow. Use `low-confidence` for useful but incomplete process-flow candidates and leave them queued rather than generating them in batch mode. -- When `/devspec.diagram` receives a process-flow batch request, process eligible rows in `DIA-*` order. Eligible rows must include `process-flow`, have status `proposed` or `confirmed`, confidence `observed` or `high-confidence`, a target matching `devspec/architecture/diagrams/dia-NNN-<diagram-name>.md`, a valid output format when specified, and a passing duplicate check. +- When `/devspec.diagram` receives a process-flow batch request, process eligible rows in `DIA-*` order. Eligible rows must include `process-flow`, have status `proposed` or `confirmed`, confidence `observed` or `high-confidence`, a target matching `devspec/architecture/images/dia-NNN-<diagram-name>.svg` unless a non-SVG output set is explicitly requested, a valid output format when specified, and a passing duplicate check. - When SVG output is selected for a process flow, use `devspec/architecture/_template/process-flow-diagram.svg`. Keep the happy path visually obvious, use distinct visual roles for start/end, manual, automated, integration, decision, exception, and artifact steps, draw exception paths as labeled dashed rose arrows, label loop-backs or rework paths, and ensure every branch ends at a step, state, or loop-back. ### Default Diagram Candidate Catalog Use this language-neutral priority catalog for extraction. Queue a candidate only when concrete evidence exists and duplicate checks pass. -| Priority | Display name | Subject slug | Scope | Diagram type | Mermaid declaration | Default target | +| Priority | Display name | Subject slug | Scope | Diagram type | Mermaid declaration | Default SVG target | | --- | --- | --- | --- | --- | --- | --- | -| 1 | System Context | `dia-NNN-system-context` | architecture | `flowchart` | `flowchart TD` | `devspec/architecture/diagrams/dia-NNN-system-context.md` | -| 2 | Domain and Capability Map | `dia-NNN-domain-capability-map` | architecture | `flowchart` | `flowchart LR` | `devspec/architecture/diagrams/dia-NNN-domain-capability-map.md` | -| 3 | Repository and Ownership Map | `dia-NNN-repository-ownership-map` | architecture | `flowchart` | `flowchart LR` | `devspec/architecture/diagrams/dia-NNN-repository-ownership-map.md` | -| 4 | Runtime Containers | `dia-NNN-runtime-containers` | architecture | `flowchart` | `flowchart LR` | `devspec/architecture/diagrams/dia-NNN-runtime-containers.md` | -| 5 | Dependency Graph | `dia-NNN-dependency-graph` | architecture | `flowchart` | `flowchart LR` | `devspec/architecture/diagrams/dia-NNN-dependency-graph.md` | -| 6 | Component Interaction Map | `dia-NNN-component-interaction-map` | architecture | `flowchart` | `flowchart LR` | `devspec/architecture/diagrams/dia-NNN-component-interaction-map.md` | -| 7 | API Surface Map | `dia-NNN-api-surface-map` | module | `flowchart` | `flowchart TD` | `devspec/architecture/diagrams/dia-NNN-api-surface-map.md` | -| 8 | Event and Message Flow | `dia-NNN-event-message-flow` | workflow | `flowchart` | `flowchart LR` | `devspec/architecture/diagrams/dia-NNN-event-message-flow.md` | -| 9 | Data Ownership and Flow | `dia-NNN-data-ownership-flow` | architecture | `flowchart` | `flowchart TD` | `devspec/architecture/diagrams/dia-NNN-data-ownership-flow.md` | -| 10 | Critical Workflow Sequence | `dia-NNN-<workflow-slug>-sequence` | workflow | `sequenceDiagram` | `sequenceDiagram` | `devspec/architecture/diagrams/dia-NNN-<workflow-slug>-sequence.md` | -| 11 | Authentication and Authorization Flow | `dia-NNN-authentication-authorization-flow` | workflow | `sequenceDiagram` | `sequenceDiagram` | `devspec/architecture/diagrams/dia-NNN-authentication-authorization-flow.md` | -| 12 | Deployment Topology | `dia-NNN-deployment-topology` | architecture | `flowchart` | `flowchart TD` | `devspec/architecture/diagrams/dia-NNN-deployment-topology.md` | -| 13 | CI/CD Pipeline | `dia-NNN-cicd-pipeline` | workflow | `flowchart` | `flowchart LR` | `devspec/architecture/diagrams/dia-NNN-cicd-pipeline.md` | -| 14 | Configuration and Secrets Flow | `dia-NNN-configuration-secrets-flow` | architecture | `flowchart` | `flowchart TD` | `devspec/architecture/diagrams/dia-NNN-configuration-secrets-flow.md` | -| 15 | Risk and Hotspot Map | `dia-NNN-risk-hotspot-map` | architecture | `flowchart` | `flowchart TD` | `devspec/architecture/diagrams/dia-NNN-risk-hotspot-map.md` | -| 16 | Hybrid User-to-Data Operational Flow | `dia-NNN-hybrid-user-to-data-operational-flow` | workflow | `flowchart` | `flowchart TD` | `devspec/architecture/diagrams/dia-NNN-hybrid-user-to-data-operational-flow.md` | -| 17 | Release or Migration Timeline | `dia-NNN-release-migration-timeline` | architecture | `timeline` | `timeline` | `devspec/architecture/diagrams/dia-NNN-release-migration-timeline.md` | -| 18 | Sprint and Release Gantt | `dia-NNN-sprint-release-gantt` | workflow | `gantt` | `gantt` | `devspec/architecture/diagrams/dia-NNN-sprint-release-gantt.md` | -| 19 | Risk and Priority Quadrant | `dia-NNN-risk-priority-quadrant` | architecture | `quadrantChart` | `quadrantChart` | `devspec/architecture/diagrams/dia-NNN-risk-priority-quadrant.md` | -| 20 | Domain Capability Mindmap | `dia-NNN-domain-capability-mindmap` | architecture | `mindmap` | `mindmap` | `devspec/architecture/diagrams/dia-NNN-domain-capability-mindmap.md` | +| 1 | System Context | `dia-NNN-system-context` | architecture | `flowchart` | `flowchart TD` | `devspec/architecture/images/dia-NNN-system-context.svg` | +| 2 | Domain and Capability Map | `dia-NNN-domain-capability-map` | architecture | `flowchart` | `flowchart LR` | `devspec/architecture/images/dia-NNN-domain-capability-map.svg` | +| 3 | Repository and Ownership Map | `dia-NNN-repository-ownership-map` | architecture | `flowchart` | `flowchart LR` | `devspec/architecture/images/dia-NNN-repository-ownership-map.svg` | +| 4 | Runtime Containers | `dia-NNN-runtime-containers` | architecture | `flowchart` | `flowchart LR` | `devspec/architecture/images/dia-NNN-runtime-containers.svg` | +| 5 | Dependency Graph | `dia-NNN-dependency-graph` | architecture | `flowchart` | `flowchart LR` | `devspec/architecture/images/dia-NNN-dependency-graph.svg` | +| 6 | Component Interaction Map | `dia-NNN-component-interaction-map` | architecture | `flowchart` | `flowchart LR` | `devspec/architecture/images/dia-NNN-component-interaction-map.svg` | +| 7 | API Surface Map | `dia-NNN-api-surface-map` | module | `flowchart` | `flowchart TD` | `devspec/architecture/images/dia-NNN-api-surface-map.svg` | +| 8 | Event and Message Flow | `dia-NNN-event-message-flow` | workflow | `flowchart` | `flowchart LR` | `devspec/architecture/images/dia-NNN-event-message-flow.svg` | +| 9 | Data Ownership and Flow | `dia-NNN-data-ownership-flow` | architecture | `flowchart` | `flowchart TD` | `devspec/architecture/images/dia-NNN-data-ownership-flow.svg` | +| 10 | Critical Workflow Sequence | `dia-NNN-<workflow-slug>-sequence` | workflow | `sequenceDiagram` | `sequenceDiagram` | `devspec/architecture/images/dia-NNN-<workflow-slug>-sequence.svg` | +| 11 | Authentication and Authorization Flow | `dia-NNN-authentication-authorization-flow` | workflow | `sequenceDiagram` | `sequenceDiagram` | `devspec/architecture/images/dia-NNN-authentication-authorization-flow.svg` | +| 12 | Deployment Topology | `dia-NNN-deployment-topology` | architecture | `flowchart` | `flowchart TD` | `devspec/architecture/images/dia-NNN-deployment-topology.svg` | +| 13 | CI/CD Pipeline | `dia-NNN-cicd-pipeline` | workflow | `flowchart` | `flowchart LR` | `devspec/architecture/images/dia-NNN-cicd-pipeline.svg` | +| 14 | Configuration and Secrets Flow | `dia-NNN-configuration-secrets-flow` | architecture | `flowchart` | `flowchart TD` | `devspec/architecture/images/dia-NNN-configuration-secrets-flow.svg` | +| 15 | Risk and Hotspot Map | `dia-NNN-risk-hotspot-map` | architecture | `flowchart` | `flowchart TD` | `devspec/architecture/images/dia-NNN-risk-hotspot-map.svg` | +| 16 | Hybrid User-to-Data Operational Flow | `dia-NNN-hybrid-user-to-data-operational-flow` | workflow | `flowchart` | `flowchart TD` | `devspec/architecture/images/dia-NNN-hybrid-user-to-data-operational-flow.svg` | +| 17 | Release or Migration Timeline | `dia-NNN-release-migration-timeline` | architecture | `timeline` | `timeline` | `devspec/architecture/images/dia-NNN-release-migration-timeline.svg` | +| 18 | Sprint and Release Gantt | `dia-NNN-sprint-release-gantt` | workflow | `gantt` | `gantt` | `devspec/architecture/images/dia-NNN-sprint-release-gantt.svg` | +| 19 | Risk and Priority Quadrant | `dia-NNN-risk-priority-quadrant` | architecture | `quadrantChart` | `quadrantChart` | `devspec/architecture/images/dia-NNN-risk-priority-quadrant.svg` | +| 20 | Domain Capability Mindmap | `dia-NNN-domain-capability-mindmap` | architecture | `mindmap` | `mindmap` | `devspec/architecture/images/dia-NNN-domain-capability-mindmap.svg` | Optional evidence-specific diagrams may include `layered-architecture`, `<entity-slug>-lifecycle`, `<domain-slug>-domain-structure`, `background-jobs-schedulers`, or `<feature-slug>-workflow` when the user asks or repository evidence makes the specialized diagram more useful than a default catalog item. Catalog rows 17-20 are optional: queue them only when evidence shows a release plan, sprint timeline, 2D scoring need, or domain brainstorming gap that a core flowchart catalog item (rows 1-16) cannot adequately serve. diff --git a/.github/prompts/README.md b/.github/prompts/README.md index 70d0116..f05ac0d 100644 --- a/.github/prompts/README.md +++ b/.github/prompts/README.md @@ -47,8 +47,9 @@ Developers invoke registered slash commands from this directory. Agent names are - `PATTERNS.md#artifact-content-pattern`: shared structure rules for developer-facing artifacts, source labels, optional sections, and table/bullet/list usage. - `PATTERNS.md#task-quality-gate-pattern`: shared task planning, implementation, and review alignment rules for source refs, dependency order, granularity, blockers, validation evidence, and task-scope drift. - `PATTERNS.md#constitution-amendment-pattern`: confirmation-gated durable principle changes, artifact routing, consistency review, and placeholder safety. -- `PATTERNS.md#diagram-extraction-consistency-pattern`: shared diagram candidate, naming, output format, Mermaid declaration, SVG target, evidence, confidence, dedupe, tags, and diagram queue rules. -- `PATTERNS.md#svg-output-pattern`: standalone SVG output rules, folders, template selection, validation, and forbidden elements. +- `PATTERNS.md#diagram-extraction-consistency-pattern`: shared diagram candidate, naming, default SVG output, optional Mermaid or HTML output, evidence, confidence, dedupe, tags, and diagram queue rules. +- `PATTERNS.md#architecture-diagram-intake-pattern`: structured architecture prompt fields, editable SVG inference, authoritative listed-component handling, and compact neutral example. +- `PATTERNS.md#svg-output-pattern`: standalone SVG output rules, optional Mermaid or HTML outputs, folders, template selection, validation, and forbidden elements. - `PATTERNS.md#process-flow-extraction-pattern`: process-flow discovery, tagging, hybrid user-to-data operational flow, and batch-generation rules. - `../../devspec/constitution.md`: rare durable principles across work items and agents; principle-level changes require confirmation and consistency review. - `../../devspec/foundation/project-context.md`: product purpose, audiences, outcomes, scope, metrics, and product delivery context. @@ -84,7 +85,7 @@ See [Model recommendations](../../README.md#model-recommendations). Agent front | `devspec.tasks.prompt.md` | Break a ready brief into source-referenced executable implementation tasks with task-quality review, validation, and done criteria. | `tasks.md` | | `devspec.implement.prompt.md` | Implement pending tasks and record task-quality checks, task-row progress, implementation evidence, execution history, and handoff details. | `implement.md`, `tasks.md` status updates, code changes | | `devspec.review.prompt.md` | Review implemented work against the finalized brief, tasks, and implementation record. | `review.md` | -| `devspec.diagram.prompt.md` | Generate or update one evidence-backed diagram, defaulting to Mermaid with opt-in SVG output, or batch-generate queued process-flow diagrams. | `architecture/diagrams/dia-NNN-*.md` by default; optional `architecture/images/dia-NNN-*.svg` for `format=svg` or `format=mermaid+svg`; `architecture/overview.md` for high-level architecture diagrams; work-item `diagrams.md` and optional `images/*.svg` for explicit or clearly temporary work-item-specific diagram content | +| `devspec.diagram.prompt.md` | Generate or update one evidence-backed diagram, defaulting to SVG with optional Mermaid or HTML output, or batch-generate queued process-flow diagrams. | `architecture/images/dia-NNN-*.svg` by default; optional `architecture/diagrams/dia-NNN-*.md` for Mermaid and `architecture/html/dia-NNN-*.html`; `architecture/overview.md` for high-level diagram references; work-item `images/*.svg`, optional `diagrams.md`, and optional `html/*.html` for explicit or clearly temporary work-item-specific diagram content | ## Maintenance diff --git a/.github/prompts/devspec.diagram.prompt.md b/.github/prompts/devspec.diagram.prompt.md index 5cc26b7..13fbc1a 100644 --- a/.github/prompts/devspec.diagram.prompt.md +++ b/.github/prompts/devspec.diagram.prompt.md @@ -1,13 +1,13 @@ --- name: "devspec.diagram" -description: "Generate or update one evidence-backed diagram, defaulting to Mermaid with opt-in SVG output, or batch-generate queued process-flow diagrams." -argument-hint: "Describe the diagram subject, scope, diagram type, related work item, all process-flow diagrams, or optional format=svg / format=mermaid+svg" +description: "Generate or update one evidence-backed diagram, defaulting to SVG with optional Mermaid and HTML output, or batch-generate queued process-flow diagrams." +argument-hint: "Describe the diagram subject, scope, diagram type, related work item, all process-flow diagrams, or optional format=svg / format=html / format=mermaid / format=svg+html / format=svg+mermaid / format=svg+html+mermaid / format=html+mermaid" agent: "devspec.diagram" --- Generate or update one diagram for the requested subject, or batch-generate eligible queued process-flow diagrams when explicitly requested, using canonical naming, sequence-prefixed subject slugs, and diagram output guidance. -Mermaid is the default output. Use `format=svg` for SVG-only output and `format=mermaid+svg` for both Mermaid and SVG. +SVG is the default output. Use `format=` with one or more of `svg`, `html`, and `mermaid` joined by `+`. Example: `format=svg`, `format=html`, `format=mermaid`, `format=svg+html`, `format=svg+mermaid`, `format=svg+html+mermaid`, `format=html+mermaid`. Required user input: -${input:diagramInput:Describe the diagram subject, scope, diagram type, related work item, all process-flow diagrams, or optional format=svg / format=mermaid+svg} +${input:diagramInput:Describe the diagram subject, scope, diagram type, related work item, all process-flow diagrams, or optional format=svg / format=html / format=mermaid / format=svg+html / format=svg+mermaid / format=svg+html+mermaid / format=html+mermaid} diff --git a/.github/prompts/devspec.extract.prompt.md b/.github/prompts/devspec.extract.prompt.md index eb17fc5..9ebc123 100644 --- a/.github/prompts/devspec.extract.prompt.md +++ b/.github/prompts/devspec.extract.prompt.md @@ -1,11 +1,11 @@ --- name: "devspec.extract" description: "Create or refresh structured, evidence-backed devspec extraction state, constitution, architecture, foundation, process-flow, and diagram queue artifacts from current root, repository URLs, local repository paths, or named multi-repo sources." -argument-hint: "Optional: leave blank for current root, paste one repository URL/path, use Name - path pairs, or include format=svg / format=mermaid+svg for diagram output preference" +argument-hint: "Optional: leave blank for current root, paste one repository URL/path, use Name - path pairs, or include diagram format=svg / format=html / format=mermaid / format=svg+html / format=svg+mermaid / format=svg+html+mermaid / format=html+mermaid" agent: "devspec.extract" --- -Create or refresh `devspec/foundation/extraction-state.md`, `devspec/constitution.md`, `devspec/architecture/overview.md`, relevant live `devspec/foundation/*.md` artifacts, business-centric process-flow candidates, and language-neutral diagram queue candidates from supported repository sources. Mermaid remains the default diagram output; optional `format=svg` and `format=mermaid+svg` tokens are preserved as diagram generation preferences and honored only after explicit generation approval. Keep extracted output developer-facing, compact, evidence-backed, resumable, and structured. Treat constitution changes as confirmation-gated candidates and route operational gates, compliance procedures, enforcement details, and evolving governance requirements to `devspec/foundation/rules.md`. +Create or refresh `devspec/foundation/extraction-state.md`, `devspec/constitution.md`, `devspec/architecture/overview.md`, relevant live `devspec/foundation/*.md` artifacts, business-centric process-flow candidates, and language-neutral diagram queue candidates from supported repository sources. SVG is the default diagram output; optional Markdown and HTML format tokens are preserved as diagram generation preferences and honored only after explicit generation approval. Keep extracted output developer-facing, compact, evidence-backed, resumable, and structured. Treat constitution changes as confirmation-gated candidates and route operational gates, compliance procedures, enforcement details, and evolving governance requirements to `devspec/foundation/rules.md`. Optional user input: -${input:extractSources:Optional: leave blank for current root, paste one repository URL/path, use Name - path pairs, or include format=svg / format=mermaid+svg} +${input:extractSources:Optional: leave blank for current root, paste one repository URL/path, use Name - path pairs, or include diagram format=svg / format=html / format=mermaid / format=svg+html / format=svg+mermaid / format=svg+html+mermaid / format=html+mermaid} diff --git a/AGENTS.md b/AGENTS.md index c5a4285..657bd41 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,7 +10,7 @@ Before running or continuing any `devspec` workflow: 1. Read `devspec/adapters/command-registry.md` for the requested command. 2. Read the canonical Copilot prompt and agent files named in that registry row. -3. Follow `.github/prompts/PATTERNS.md` for shared workflow, recovery, output, discovery, and recommendation behavior. For diagram generation, also apply `PATTERNS.md#mermaid-visual-quality-pattern` (dark theme init, semantic `classDef` palette, role-appropriate node shapes, subgraph boundaries, complexity guardrails), `PATTERNS.md#mermaid-internal-naming-and-readability-pattern`, `PATTERNS.md#svg-output-pattern` when `format=svg` or `format=mermaid+svg` is requested, and `PATTERNS.md#excluded-diagram-families` (do not generate or queue excluded families such as `architecture-beta`; use the portable alternative). +3. Follow `.github/prompts/PATTERNS.md` for shared workflow, recovery, output, discovery, and recommendation behavior. For diagram generation, also apply `PATTERNS.md#mermaid-visual-quality-pattern` when Mermaid output is selected, `PATTERNS.md#mermaid-internal-naming-and-readability-pattern` when Mermaid output is selected, `PATTERNS.md#svg-output-pattern` when SVG output is selected or defaulted, and `PATTERNS.md#excluded-diagram-families` (do not generate or queue excluded families such as `architecture-beta`; use the portable alternative). 4. Recover from existing `devspec/` artifacts before relying on memory. 5. Preserve required inputs, output artifacts, status values, gates, handoff order, and recovery behavior. diff --git a/README.md b/README.md index 5bd6765..b386b80 100644 --- a/README.md +++ b/README.md @@ -69,7 +69,7 @@ Then run the work-item flow: /devspec.review ``` -Use `/devspec.clarify` only when a work item records a blocking question. Use `/devspec.diagram` when a diagram would clarify architecture, workflow, state, sequence, or domain behavior; Mermaid is the default, with opt-in SVG via `format=svg` or `format=mermaid+svg`. +Use `/devspec.clarify` only when a work item records a blocking question. Use `/devspec.diagram` when a diagram would clarify architecture, workflow, state, sequence, or domain behavior; SVG is the default, with optional Mermaid or HTML via `format=` combinations. Example: `format=svg`, `format=html`, `format=mermaid`, `format=svg+html`, `format=svg+mermaid`, `format=svg+html+mermaid`, `format=html+mermaid`. ## How It Works @@ -121,7 +121,7 @@ flowchart TD | `/devspec.tasks` | A ready brief needs executable tasks. | Work-item `tasks.md` | | `/devspec.implement` | Pending tasks should be implemented and recorded. | Work-item `implement.md` and code changes when applicable | | `/devspec.review` | Implemented work needs review against the finalized brief. | Work-item `review.md` | -| `/devspec.diagram` | A diagram should be created or updated. | Architecture or work-item Markdown diagram artifacts, with Mermaid by default and opt-in SVG images via `format=svg` or `format=mermaid+svg` | +| `/devspec.diagram` | A diagram should be created or updated. | Architecture or work-item SVG diagram artifacts by default, with optional Mermaid or HTML artifacts | For exact command contracts, see `devspec/adapters/command-registry.md`. @@ -154,7 +154,7 @@ Related docs: | --- | --- | | `devspec/constitution.md` | Rare durable project principles across all work items and agents; principle changes require explicit confirmation. | | `devspec/foundation/` | Product context, stack, structure, standards, operational rules, exclusions, and provider policy. | -| `devspec/architecture/` | Architecture overview, Markdown diagrams, optional SVG images, ADR templates, and artifact queue. | +| `devspec/architecture/` | Architecture overview, default SVG diagrams, optional Mermaid or HTML diagrams, ADR templates, and artifact queue. | | `devspec/work-items/` | One folder per feature, bug, or security work item. | | `devspec/adapters/` | Multi-agent registry, compatibility, validation, and governance docs. | | `docs/how-to/` | User manual with install, workflow, AI coding agent, multi-repo, provider, validation, and upgrade examples. | @@ -275,6 +275,7 @@ Project-owned files should be migrated or merged, not overwritten: - `devspec/architecture/*.md` - `devspec/architecture/diagrams/*.md` - `devspec/architecture/images/*.svg` +- `devspec/architecture/html/*.html` - `devspec/work-items/**` - `devspec/constitution.md` - `devspec/glossary.md` diff --git a/devspec/adapters/antigravity.md b/devspec/adapters/antigravity.md index 7f2a673..7997b46 100644 --- a/devspec/adapters/antigravity.md +++ b/devspec/adapters/antigravity.md @@ -26,7 +26,7 @@ Google Antigravity support is implemented through workspace rules under `.agents - `.agents/skills/devspec-*.md` provides command-like wrappers for each canonical command. - Each skill references `devspec/adapters/command-registry.md` and the matching Copilot prompt and agent files. - Preserve artifact boundaries: product context belongs in `devspec/foundation/project-context.md`, durable principles in `devspec/constitution.md`, and operational governance or delivery gates in `devspec/foundation/rules.md`. -- `/devspec.diagram` keeps Mermaid as the default output; pass `format=svg` for SVG-only output or `format=mermaid+svg` for both outputs without creating a separate Antigravity skill. +- `/devspec.diagram` defaults to SVG output. `format=` may contain any non-duplicated `+` combination of `svg`, `html`, and `mermaid`. Example: `format=svg`, `format=html`, `format=mermaid`, `format=svg+html`, `format=svg+mermaid`, `format=svg+html+mermaid`, `format=html+mermaid`. - Do not add Antigravity workflow files until the target workflow file location and format are confirmed for the team. - Antigravity artifacts, task lists, and implementation plans are transient helpers; Git-tracked `devspec/` artifacts remain canonical. diff --git a/devspec/adapters/claude-code.md b/devspec/adapters/claude-code.md index d17a5b2..7c4b65e 100644 --- a/devspec/adapters/claude-code.md +++ b/devspec/adapters/claude-code.md @@ -25,7 +25,7 @@ Claude Code support is implemented through project skills under `.claude/skills/ - Each skill is a thin wrapper around the canonical command registry. - Each skill references the matching Copilot prompt and agent files instead of redefining command behavior. - Dotted command names are preserved as canonical `devspec` vocabulary even when Claude invokes hyphenated skill names. -- `/devspec.diagram` keeps Mermaid as the default output; pass `format=svg` for SVG-only output or `format=mermaid+svg` for both outputs without creating a separate adapter command. +- `/devspec.diagram` defaults to SVG output. `format=` may contain any non-duplicated `+` combination of `svg`, `html`, and `mermaid`. Example: `format=svg`, `format=html`, `format=mermaid`, `format=svg+html`, `format=svg+mermaid`, `format=svg+html+mermaid`, `format=html+mermaid`. - Platform limitations belong in `devspec/adapters/compatibility-matrix.md`. ## Validation diff --git a/devspec/adapters/codex.md b/devspec/adapters/codex.md index 783e71b..5dd1ddd 100644 --- a/devspec/adapters/codex.md +++ b/devspec/adapters/codex.md @@ -15,7 +15,7 @@ OpenAI Codex support starts with root `AGENTS.md`, which gives Codex the always- - Read `AGENTS.md` and `devspec/adapters/command-registry.md` before executing a `devspec` workflow. - Preserve Copilot prompt and agent intent from the canonical files listed in the registry. - Use Git-tracked `devspec` artifacts for recovery and handoff decisions. -- `/devspec.diagram` keeps Mermaid as the default output; pass `format=svg` for SVG-only output or `format=mermaid+svg` for both outputs without creating a separate Codex command. +- `/devspec.diagram` defaults to SVG output. `format=` may contain any non-duplicated `+` combination of `svg`, `html`, and `mermaid`, such as `format=svg`, `format=html`, `format=mermaid`, `format=svg+html`, `format=svg+mermaid`, `format=svg+html+mermaid`, or `format=html+mermaid`, without creating a separate Codex command. - Treat Codex-specific slash commands, local/cloud modes, sandboxing, and approvals as platform mechanics, not workflow changes. ## Validation diff --git a/devspec/adapters/command-registry.md b/devspec/adapters/command-registry.md index 916232a..667c0dc 100644 --- a/devspec/adapters/command-registry.md +++ b/devspec/adapters/command-registry.md @@ -9,7 +9,7 @@ This registry is the provider-neutral contract for all `devspec` adapters. The G | `artifact-write` | May create or update `devspec/` artifacts only. | | `code-write` | May edit target repository code when the upstream work item and repository access allow it. | | `review-write` | May write review artifacts and report findings, but should not change implementation code. | -| `diagram-write` | May create or update Mermaid and opt-in SVG diagram artifacts and related queue state. | +| `diagram-write` | May create or update default SVG diagram artifacts, optional Markdown or HTML diagram artifacts, and related queue state. | ## Registered Commands @@ -27,7 +27,7 @@ This registry is the provider-neutral contract for all `devspec` adapters. The G | `/devspec.tasks` | Break a ready finalized brief into ordered executable implementation tasks with source refs, planning basis, task-quality review, validation, and done criteria. | `finalize.md` marked `ready`; optional task-planning input. | `.github/prompts/devspec.tasks.prompt.md` | `.github/agents/devspec.tasks.agent.md` | `devspec/work-items/<work-item-folder>/tasks.md` | `artifact-write` | `/devspec.implement` | | `/devspec.implement` | Implement pending tasks for the current ready work item, update implementation and task-quality checkpoints, and confirm after each task. | `finalize.md` marked `ready` and `tasks.md`; optional implementation or validation guidance. | `.github/prompts/devspec.implement.prompt.md` | `.github/agents/devspec.implement-task.agent.md` | `devspec/work-items/<work-item-folder>/implement.md`, task-row status updates in `tasks.md`, code changes when applicable | `code-write` | `/devspec.review` when complete | | `/devspec.review` | Review implemented work against the finalized brief, tasks, and implementation record, then record review outcome. | `finalize.md`, `tasks.md`, and `implement.md`; optional review focus. | `.github/prompts/devspec.review.prompt.md` | `.github/agents/devspec.review.agent.md` | `devspec/work-items/<work-item-folder>/review.md` | `review-write` | Return to `/devspec.implement` for changes or close the work item | -| `/devspec.diagram` | Generate or update one evidence-backed diagram, defaulting to Mermaid with opt-in SVG output, or batch-generate queued process-flow diagrams when explicitly requested. | Diagram subject, related work item, explicit process-flow batch request, and optional `format=svg` or `format=mermaid+svg` token. | `.github/prompts/devspec.diagram.prompt.md` | `.github/agents/devspec.diagram.agent.md` | `devspec/architecture/diagrams/dia-NNN-*.md`, optional `devspec/architecture/images/dia-NNN-*.svg`, `devspec/architecture/overview.md` for high-level diagrams, or work-item `diagrams.md` and optional work-item `images/*.svg` for temporary work-item diagrams | `diagram-write` | Continue the current workflow | +| `/devspec.diagram` | Generate or update one evidence-backed diagram, defaulting to SVG with optional Mermaid and HTML output, or batch-generate queued process-flow diagrams when explicitly requested. | Diagram subject, related work item, explicit process-flow batch request, and optional `format=` token containing one or more of `svg`, `html`, and `mermaid` joined by `+`. Example: `format=svg`, `format=html`, `format=mermaid`, `format=svg+html`, `format=svg+mermaid`, `format=svg+html+mermaid`, `format=html+mermaid`. | `.github/prompts/devspec.diagram.prompt.md` | `.github/agents/devspec.diagram.agent.md` | `devspec/architecture/images/dia-NNN-*.svg` by default, optional `devspec/architecture/diagrams/dia-NNN-*.md` for Mermaid, optional `devspec/architecture/html/dia-NNN-*.html`, `devspec/architecture/overview.md` for high-level diagram references, or work-item `images/*.svg`, optional `diagrams.md`, and optional `html/*.html` for temporary work-item diagrams | `diagram-write` | Continue the current workflow | ## Required Flow Gates diff --git a/devspec/adapters/gemini-cli.md b/devspec/adapters/gemini-cli.md index 83c5d40..88a719e 100644 --- a/devspec/adapters/gemini-cli.md +++ b/devspec/adapters/gemini-cli.md @@ -28,7 +28,7 @@ Gemini uses colon namespacing for project commands. Keep canonical dotted `/devs - Each TOML command is a thin wrapper around `devspec/adapters/command-registry.md`. - Each TOML command names the matching Copilot prompt and agent files as the source of intent. - Gemini CLI command arguments are passed through the native custom-command argument behavior. -- `/devspec.diagram` keeps Mermaid as the default output; pass `format=svg` for SVG-only output or `format=mermaid+svg` for both outputs without creating a separate Gemini command. +- `/devspec.diagram` defaults to SVG output. `format=` may contain any non-duplicated `+` combination of `svg`, `html`, and `mermaid`. Example: `format=svg`, `format=html`, `format=mermaid`, `format=svg+html`, `format=svg+mermaid`, `format=svg+html+mermaid`, `format=html+mermaid`. - Do not use Gemini shell injection in devspec command wrappers; let the agent read files through normal tool access and approvals. ## Enterprise Safety diff --git a/devspec/architecture/_template/architecture-diagram.svg b/devspec/architecture/_template/architecture-diagram.svg index 16bffa8..5b5ae2a 100644 --- a/devspec/architecture/_template/architecture-diagram.svg +++ b/devspec/architecture/_template/architecture-diagram.svg @@ -1,4 +1,4 @@ -<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 820" role="img" aria-labelledby="title desc"> +<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1600 900" role="img" aria-labelledby="title desc"> <title id="title">[DIAGRAM_TITLE] [DIAGRAM_DESCRIPTION] @@ -6,160 +6,215 @@ - - + + - + - + - - + + - + + + + + - + - - - + + + - [PROJECT_NAME] - [DIAGRAM_TITLE] - [DIAGRAM_DESCRIPTION] + [PROJECT_NAME] + [DIAGRAM_TITLE] + [DIAGRAM_DESCRIPTION] - - HTTPS - - OIDC - - Event + + + + 1 + + + Sign in + + + + + 2 + + + Request + + + + + 3 + + + Calls + + + + + 4 + + + Stores + + + + + 5 + + + Events - - - [SYSTEM_BOUNDARY] + + + [CLIENT_BOUNDARY] + + + + + [APPLICATION_BOUNDARY] - - External Systems + + [EXTERNAL_BOUNDARY] + + + + + [SECURITY_BOUNDARY] - - - Client App - User Entry - Replace me + + + User Client + Actor Entry + Replace me + + + + + + Security + Policy Checks + Replace me - - - - API Service - Business Logic - Replace me + + + + Core Service + Orchestration + Replace me - - - Data Store - Owned Data - Replace me + + + Data Store + Owned Data + Replace me - - - - Identity - Trust Boundary - Replace me + + + + Worker + Async Flow + Replace me - - - External API - Third Party - Replace me - - - - Legend - - Frontend / Client - - Backend / Service - - Data / Storage - - Security / Identity - - External - - - Generated by devspec - [DATE_OR_VERSION] + + + External API + Third Party + Replace me + + + + + Legend + + 1 + Numbered data or control flow + + Owned service + + Optional or async flow + + Boundary + + + Generated by devspec - [DATE_OR_VERSION] diff --git a/devspec/architecture/_template/artifact-queue.md b/devspec/architecture/_template/artifact-queue.md index 45c41e1..36b757c 100644 --- a/devspec/architecture/_template/artifact-queue.md +++ b/devspec/architecture/_template/artifact-queue.md @@ -2,7 +2,7 @@ Use this file as the resumable queue register for proposed and generated architecture diagrams. Keep generated diagram content in the target artifact; keep only queue metadata, evidence, confidence, status, output-format guidance, and next action or notes here. -Store high-level diagrams in `devspec/architecture/overview.md`, durable detailed Markdown diagram artifacts in `devspec/architecture/diagrams/dia-NNN-.md`, durable SVG images in `devspec/architecture/images/dia-NNN-.svg`, and temporary work-item diagrams in `devspec/work-items//diagrams.md` with optional SVG images under `devspec/work-items//images/`. +Store high-level diagram references in `devspec/architecture/overview.md`, durable SVG images in `devspec/architecture/images/dia-NNN-.svg` by default, optional Mermaid Markdown artifacts in `devspec/architecture/diagrams/dia-NNN-.md`, optional HTML diagram artifacts in `devspec/architecture/html/dia-NNN-.html`, and temporary work-item diagrams under `devspec/work-items//images/` with optional Mermaid `diagrams.md` or `html/*.html` companions. ## Diagram Queue Register @@ -19,9 +19,9 @@ Add rows only when extraction or `/devspec.diagram` identifies real diagram cand | Scope | Use `architecture`, `module`, `feature`, `workflow`, `user-journey`, or `work-item`. Prefer durable scopes over `work-item` unless the diagram is explicitly temporary or work-item-specific. | | Diagram type | Use the logical diagram family only: `flowchart`, `sequenceDiagram`, `journey`, `stateDiagram`, `classDiagram`, `erDiagram`, `gantt`, `quadrantChart`, `mindmap`, or `timeline`. Do not include orientation or output format here. | | Subject | Use a specific lowercase kebab-case subject that can map to one diagram file or one overview section. For queued architecture diagrams, prefix the subject with the lowercase queue ID, such as `dia-001-order-fulfillment-flow`. | -| Target location | Use `devspec/architecture/overview.md#diagram-reference-index` for high-level overview diagrams, `devspec/architecture/diagrams/dia-NNN-.md` for durable detailed Markdown artifacts, or `devspec/work-items//diagrams.md#diagram-content` for temporary work-item diagrams. Record SVG targets such as `devspec/architecture/images/dia-NNN-.svg` in `Next action or notes`. | +| Target location | Use `devspec/architecture/images/dia-NNN-.svg` for default durable SVG output, `devspec/architecture/overview.md#diagram-reference-index` for high-level overview references, `devspec/architecture/diagrams/dia-NNN-.md` for optional Mermaid Markdown artifacts, `devspec/architecture/html/dia-NNN-.html` for optional HTML artifacts, or work-item `images/`, `diagrams.md#diagram-content`, and `html/` targets for temporary work-item diagrams. Record companion targets in `Next action or notes`. | | Evidence | Name the source paths, docs, ADRs, queue request, or user-confirmed basis supporting the candidate. | | Confidence | Use `observed` for direct evidence, `high-confidence` for inference from multiple local evidence points, or `low-confidence` when useful but incomplete evidence needs assumptions before generation. | | Status | Use `devspec/glossary.md#artifact-status-values`; queue status belongs here, not in diagram indexes or generated diagram content. | | Tags | Use comma-separated lowercase tags such as `process-flow`, `business-process`, `user-journey`, `lifecycle-flow`, or `hybrid-user-to-data-operational-flow` when they apply. Leave blank only when no durable selection tag is useful. | -| Next action or notes | Record duplicate-check result, output format (`format=mermaid`, `format=svg`, or `format=mermaid+svg`), suggested Mermaid declaration such as `flowchart LR` or `sequenceDiagram`, SVG target when applicable, assumptions, blocker details, skip reason, or the next action needed. | +| Next action or notes | Record duplicate-check result, output format as one or more of `svg`, `html`, and `mermaid` joined with `+`. Examples: `format=svg`, `format=html`, `format=mermaid`, `format=svg+html`, `format=svg+mermaid`, `format=svg+html+mermaid`, `format=html+mermaid`. Include suggested Mermaid declaration such as `flowchart LR` or `sequenceDiagram` when the output set includes `mermaid`, SVG target, optional Mermaid or HTML targets, assumptions, blocker details, skip reason, or the next action needed. | diff --git a/devspec/architecture/_template/diagram.html b/devspec/architecture/_template/diagram.html new file mode 100644 index 0000000..483f393 --- /dev/null +++ b/devspec/architecture/_template/diagram.html @@ -0,0 +1,117 @@ + + + + + + [DIAGRAM_TITLE] + + + +
+
+
+
[PROJECT_NAME]
+

[DIAGRAM_TITLE]

+

[DIAGRAM_DESCRIPTION]

+
+
+ [INLINE_SVG_OR_STATIC_DIAGRAM] +
+
Generated by devspec - [DATE_OR_VERSION]
+
+
+ + diff --git a/devspec/architecture/_template/diagram.md b/devspec/architecture/_template/diagram.md index e6c7c81..ea80876 100644 --- a/devspec/architecture/_template/diagram.md +++ b/devspec/architecture/_template/diagram.md @@ -1,6 +1,6 @@ # Architecture Diagram -Use this artifact for one durable architecture, module, feature, workflow, process-flow, user journey, sequence, state, or domain diagram. Mermaid is the default output; SVG output is opt-in with `format=svg` or `format=mermaid+svg`. Keep diagram status in `devspec/architecture/artifact-queue.md`; keep generated content references, supporting evidence, assumptions, and maintenance notes here. +Use this optional Markdown artifact for one durable Mermaid architecture, module, feature, workflow, process-flow, user journey, sequence, state, or domain diagram when the selected output set includes `mermaid`. SVG is the default diagram output and lives under `devspec/architecture/images/`; HTML is optional and lives under `devspec/architecture/html/`. Keep diagram status in `devspec/architecture/artifact-queue.md`; keep generated content references, supporting evidence, assumptions, and maintenance notes here when this Markdown artifact is created. ## Resume State @@ -27,17 +27,23 @@ Use this artifact for one durable architecture, module, feature, workflow, proce | Display title | `DIA-NNN - ` | | Scope | architecture, module, feature, workflow, user-journey | | Diagram type | flowchart, sequenceDiagram, journey, stateDiagram, classDiagram, erDiagram, gantt, quadrantChart, mindmap, timeline | -| Output format | mermaid, svg, mermaid+svg | +| Audience | developers, architects, security reviewers, operators, stakeholders, or user-provided audience | +| Purpose | runtime flow, deployment, security, dependencies, data movement, integration, or user-provided goal | +| Architecture style | monolith, microservices, event-driven, serverless, agentic workflow, multi-repo, cloud-native, or user-provided style | +| Output format | mermaid, svg+mermaid, html+mermaid, or svg+html+mermaid | | Mermaid declaration | flowchart TD, flowchart LR, flowchart BT, sequenceDiagram, journey, stateDiagram-v2, classDiagram, erDiagram, gantt, quadrantChart, mindmap, timeline | | SVG target | `devspec/architecture/images/dia-NNN-<diagram-name>.svg` when output format includes svg | +| HTML target | `devspec/architecture/html/dia-NNN-<diagram-name>.html` when output format includes html | | Subject | `dia-NNN-<diagram-name>` | | Confidence | observed, high-confidence, low-confidence | | Tags | | | Queue row | `devspec/architecture/artifact-queue.md#diagram-queue-register` | +When a request uses the structured architecture-diagram prompt format and the selected output set includes `mermaid`, reflect the provided system name, architecture style, purpose, audience, actors, components, stores, flows, boundaries, design rules, and output format in this metadata, the queue row notes, source evidence and assumptions, and generated diagram content. If the request uses structured non-architecture diagram input, reflect the matching sequence, state/lifecycle, domain model, journey, timeline/gantt, quadrant, or mindmap fields in this metadata, the queue row notes, source evidence and assumptions, generated Mermaid content, and any SVG or HTML companion output. If the request omits output format, use SVG-only output and do not create this Markdown artifact. + ## Mermaid Diagram -- Omit this section's diagram block when `Output format` is `svg`; keep the heading and record `Not generated; SVG-only output requested.`. +- Include this section only when the selected output set includes `mermaid`. SVG-only and HTML-only output should not create this Markdown artifact. - Keep durable `DIA-*` IDs and `dia-NNN-*` subjects in metadata and filenames only; Mermaid content uses simple internal naming. - Use short alphanumeric node IDs, double-quoted node labels of 1-4 words, and 2-3 word edge labels. Do not use `\n` or `<br>` inside node labels or edge labels. - Keep architectural flowcharts focused on one primary domain at macro level, structurally unidirectional, and adjacent by layer. Do not include overloaded graphs, cross-layer arrows, decision diamonds, UI micro-interactions, or return/error paths unless the diagram is explicitly an algorithm or activity flowchart. @@ -45,6 +51,7 @@ Use this artifact for one durable architecture, module, feature, workflow, proce - Keep runtime communication and compile-time project dependencies in separate diagrams. Logical architecture diagrams exclude SDLC actors and build artifacts, and keep owned application databases inside the system boundary. - Avoid API, Swagger, tech stack, version, library, hosting, and framework boilerplate details in flowchart nodes unless the diagram is specifically about startup, request-pipeline, infrastructure-layer, or physical deployment behavior. - Apply the Mermaid Visual Quality Pattern: (1) open flowcharts with the dark theme init block, (2) declare `classDef` entries for every role present, (3) use role-appropriate node shapes, (4) wrap boundaries of 3+ nodes in named `subgraph` blocks, (5) draw cross-subgraph arrows after all `end` keywords, (6) assign `classDef` classes in a batch block at the end, (7) keep node count <= 15. +- Mermaid renderers may ignore dark theme initialization for some families or hosts. When that happens, keep Mermaid portable and use the SVG or HTML companion as the canonical architecture-style visual output. ```mermaid %%{init: {'theme': 'dark', 'themeVariables': {'primaryColor': '#1e293b', 'primaryTextColor': '#f8fafc', 'lineColor': '#64748b', 'clusterBkg': '#0f172a', 'clusterBorder': '#334155'}}}%% @@ -88,18 +95,21 @@ flowchart TD class UserA actor ``` -## SVG Diagram +## Companion Outputs -- Use this section when `Output format` is `svg` or `mermaid+svg`. +- Use this section when `Output format` includes `svg` or `html`. - Store the durable SVG at `devspec/architecture/images/dia-NNN-<diagram-name>.svg`. -- Use `devspec/architecture/_template/process-flow-diagram.svg` for process-flow SVGs. Use `devspec/architecture/_template/architecture-diagram.svg` for all other SVG diagram output unless a documented constraint requires a smaller custom SVG. +- Store optional standalone HTML at `devspec/architecture/html/dia-NNN-<diagram-name>.html`. +- Select SVG templates from `.github/prompts/PATTERNS.md#svg-output-pattern`: `architecture-diagram.svg`, `process-flow-diagram.svg`, `sequence-diagram.svg`, `state-lifecycle-diagram.svg`, `domain-model-diagram.svg`, `journey-map-diagram.svg`, `timeline-plan-diagram.svg`, `quadrant-analysis-diagram.svg`, or `mindmap-diagram.svg`. Every template must preserve the shared dark architecture-style visual contract unless a documented constraint requires a smaller custom SVG. - Generated SVG must be standalone XML with inline styles and no external assets, `<script>`, `<iframe>`, `<foreignObject>`, remote fonts, remote images, secrets, credentials, internal-only URLs, or unresolved placeholders. +- Generated HTML must be standalone static HTML with inline styles and no external assets, `<script>`, `<iframe>`, remote fonts, remote images, secrets, credentials, internal-only URLs, or unresolved placeholders. - Validate the SVG as XML before reporting generation complete. | Field | Value | | --- | --- | | SVG target | | -| Template used | `devspec/architecture/_template/architecture-diagram.svg` or `devspec/architecture/_template/process-flow-diagram.svg` | +| HTML target | | +| Template used | `devspec/architecture/_template/<selected-svg-template>.svg` and optional `devspec/architecture/_template/diagram.html` | | Validation | pending | ## Source Evidence and Assumptions diff --git a/devspec/architecture/_template/domain-model-diagram.svg b/devspec/architecture/_template/domain-model-diagram.svg new file mode 100644 index 0000000..c7bfa13 --- /dev/null +++ b/devspec/architecture/_template/domain-model-diagram.svg @@ -0,0 +1,156 @@ +<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1600 900" role="img" aria-labelledby="title desc"> + <title id="title">[DIAGRAM_TITLE] - Domain Model Diagram + [DIAGRAM_DESCRIPTION] + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + [PROJECT_NAME] + [DIAGRAM_TITLE] + [DIAGRAM_DESCRIPTION] + + + + 1 + * + + Owns + + + 1 + * + + Uses + + + + Stores + + + + [CORE_DOMAIN] + + + + + [EXTERNAL_CONTEXT] + + + + + + + [Aggregate Root] + + id + + [business field] + + [status field] + + + + + + + [Child Entity] + + id + + [owned field] + + [rule field] + + + + + + + [External] + + ref + + [contract] + + [owner] + + + + + + [Repository / Store] + Persistence boundary + + + + + Legend + + Aggregate root + + Owned entity + + Relationship + 1..* + Cardinality + + + Generated by devspec - [DATE_OR_VERSION] + diff --git a/devspec/architecture/_template/journey-map-diagram.svg b/devspec/architecture/_template/journey-map-diagram.svg new file mode 100644 index 0000000..cd4473e --- /dev/null +++ b/devspec/architecture/_template/journey-map-diagram.svg @@ -0,0 +1,175 @@ + + [DIAGRAM_TITLE] - Journey Map Diagram + [DIAGRAM_DESCRIPTION] + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + [PROJECT_NAME] + [DIAGRAM_TITLE] + [DIAGRAM_DESCRIPTION] + + ACTOR + SYSTEM + OUTCOME + + + + 1. DISCOVER + Trigger and intent + + + + + 2. ACT + User action + + + + + 3. PROCESS + System work + + + + + 4. RESOLVE + Outcome visible + + + + + + + + + + + + + + + Need Appears + question / trigger + + + + + + Submit Input + manual step + + + + + + Process + validate + route + + + + + + Receive Result + decision / artifact + + + + + + Capture + store request + + + + + + Notify + external handoff + + + + Outcome: [business result, artifact, or user-visible state] + + + + + + + + + Legend + + Actor action + + System action + + Experience signal + + + Generated by devspec - [DATE_OR_VERSION] + diff --git a/devspec/architecture/_template/mindmap-diagram.svg b/devspec/architecture/_template/mindmap-diagram.svg new file mode 100644 index 0000000..78c5f63 --- /dev/null +++ b/devspec/architecture/_template/mindmap-diagram.svg @@ -0,0 +1,157 @@ + + [DIAGRAM_TITLE] - Mindmap Diagram + [DIAGRAM_DESCRIPTION] + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + [PROJECT_NAME] + [DIAGRAM_TITLE] + [DIAGRAM_DESCRIPTION] + + + + + + + + + + + + [CAPABILITY_GROUP_A] + + + + + [CAPABILITY_GROUP_B] + + + + + + [Central Topic] + domain / capability + Replace me + + + + + + [Service Topic] + owned behavior + + + + + + [Data Topic] + owned store + + + + + + [Policy Topic] + control / rule + + + + + + [External Topic] + outside boundary + + + + + + [Event Topic] + message / signal + + + + + + [Outcome Topic] + result / impact + + + + + Legend + + Capability + + Data topic + + Secondary branch + + + Generated by devspec - [DATE_OR_VERSION] + diff --git a/devspec/architecture/_template/overview.md b/devspec/architecture/_template/overview.md index 46d8b84..c17dbd0 100644 --- a/devspec/architecture/_template/overview.md +++ b/devspec/architecture/_template/overview.md @@ -18,7 +18,7 @@ Use this section for confirmed high-level diagrams in this file and links to dur | ID | Scope | Diagram type | Subject | Link or section | Usage notes | | --- | --- | --- | --- | --- | --- | -| | architecture, module, feature, workflow, user-journey | flowchart, sequenceDiagram, journey, stateDiagram, classDiagram, erDiagram | | `devspec/architecture/diagrams/dia-NNN-.md`, optional `devspec/architecture/images/dia-NNN-.svg`, or section anchor | | +| | architecture, module, feature, workflow, user-journey | flowchart, sequenceDiagram, journey, stateDiagram, classDiagram, erDiagram | | `devspec/architecture/images/dia-NNN-.svg`, optional `devspec/architecture/diagrams/dia-NNN-.md`, optional `devspec/architecture/html/dia-NNN-.html`, or section anchor | | ## Decision Reference Index diff --git a/devspec/architecture/_template/process-flow-diagram.svg b/devspec/architecture/_template/process-flow-diagram.svg index 3c7f704..f31c0e8 100644 --- a/devspec/architecture/_template/process-flow-diagram.svg +++ b/devspec/architecture/_template/process-flow-diagram.svg @@ -1,4 +1,4 @@ - + [PROCESS_NAME] - Process Flow [PROCESS_DESCRIPTION] @@ -6,82 +6,87 @@ - - + + - + - + - + @@ -92,178 +97,198 @@ - - + + - - + + - - + + + + + + - - - - - - PROCESS FLOW - [PROCESS_NAME] - [PROCESS_DESCRIPTION] - Owner: [OWNER_TEAM] - Version: [VERSION_OR_DATE] - - - - PREREQUISITES - - [Prerequisite 1] - - [Prerequisite 2] - - [Prerequisite 3] - - [Access / Tooling] - - - HAPPY PATH - - EXCEPTION / REWORK + + + + + + PROCESS FLOW + [PROCESS_NAME] + [PROCESS_DESCRIPTION] - Owner: [OWNER_TEAM] - Version: [VERSION_OR_DATE] + + + + PREREQUISITES + + [Prerequisite 1] + + [Prerequisite 2] + + [Prerequisite 3] + + [Access / Tooling] + + + HAPPY PATH + + EXCEPTION / REWORK - - trigger - - input - - validated - - Yes - - result - - done - - - No / Rejected - - rework needed - - optional monitor + + + Trigger + + + + Input + + + + Validate + + + + Yes + + + + Result + + + + Done + + + No / Rejected + + Rework needed + + Optional monitor - - - Start + + + Start - - - - 1 - USER - Manual Step - submit / review + + + + 1 + USER + Manual Step + submit / review - - - - 2 - SYSTEM - Automated Step - validate + process + + + + 2 + SYSTEM + Automated Step + validate + process - - - Decision? - Yes / No + + + Decision? + Yes / No - - - - 4 - API - Integration - external handoff + + + + 4 + API + Integration + external handoff - - - - 5 - SYSTEM - Finalize - notify + record + + + + 5 + SYSTEM + Finalize + notify + record - - - End + + + End - - - Reject / Escalate / Rework + + + Reject / Escalate / Rework - - [Output Artifact] - + + [Output Artifact] + + + + + + Legend + + Start / End + + Manual + + Automated + + Integration + + Decision - - LEGEND - - Start / End - - Manual - - Automated - - Integration - - Decision - - Exception path - - Loop-back + + + Flow Types + + Happy path + + Exception path + + Loop-back - - - Prerequisites - - [Required setup item 1] - - [Access / approval / configuration] - - [Policy or dependency] + + + Prerequisites + - [Required setup item 1] + - [Access / approval / configuration] - - - Inputs / Outputs - - Input: [source data / request] - - Output: [approved result / artifact] - - Branches: [approve / reject / rework] + + + Inputs / Outputs + - Input: [source data / request] + - Output: [approved result / artifact] - - - Tools and Integrations - - [Tool / system 1] - - [External API / service] - - [Notification / storage / audit] + + + Tools and Integrations + - [Tool / system 1] + - [External API / service] - [Process Name] - [Owner/Team] - [Version/Date] - Generated as standalone SVG + [Process Name] - [Owner/Team] - [Version/Date] - Generated by devspec diff --git a/devspec/architecture/_template/quadrant-analysis-diagram.svg b/devspec/architecture/_template/quadrant-analysis-diagram.svg new file mode 100644 index 0000000..ffc812c --- /dev/null +++ b/devspec/architecture/_template/quadrant-analysis-diagram.svg @@ -0,0 +1,126 @@ + + [DIAGRAM_TITLE] - Quadrant Analysis Diagram + [DIAGRAM_DESCRIPTION] + + + + + + + + + + + + + + + + + + + + + + + + + + [PROJECT_NAME] + [DIAGRAM_TITLE] + [DIAGRAM_DESCRIPTION] + + + + + + + + + + + + [X_AXIS_LOW] to [X_AXIS_HIGH] + [Y_AXIS_LOW] to [Y_AXIS_HIGH] + HIGH VALUE + Prioritize + STRATEGIC + Investigate + LOW RETURN + Defer + HIGH RISK + Mitigate + + + + + A + [Item A] + + + + + B + [Item B] + + + + + C + [Item C] + + + + + D + [Item D] + + + + + Legend + + Priority item + + Risk item + + Exploratory item + + + Generated by devspec - [DATE_OR_VERSION] + diff --git a/devspec/architecture/_template/sequence-diagram.svg b/devspec/architecture/_template/sequence-diagram.svg new file mode 100644 index 0000000..713b2c3 --- /dev/null +++ b/devspec/architecture/_template/sequence-diagram.svg @@ -0,0 +1,175 @@ + + [DIAGRAM_TITLE] - Sequence Diagram + [DIAGRAM_DESCRIPTION] + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + [PROJECT_NAME] + [DIAGRAM_TITLE] + [DIAGRAM_DESCRIPTION] + + + + + + + + + + + + + + + + 1 + + + Authenticate + + + + + 2 + + + Request + + + + + 3 + + + Persist + + + + + 4 + + + Notify + + + + Response + + + + [Actor] + Requester + + + + + [Client] + UI Boundary + + + + + [Service] + Application + + + + + [Data Store] + Persistence + + + + + [External] + Integration + + + + + Interaction Notes + Show happy-path messages between distinct participants; keep implementation detail out of labels. + + + + + Legend + + Synchronous call + + Return + + Security-sensitive step + + + Generated by devspec - [DATE_OR_VERSION] + diff --git a/devspec/architecture/_template/state-lifecycle-diagram.svg b/devspec/architecture/_template/state-lifecycle-diagram.svg new file mode 100644 index 0000000..706e55c --- /dev/null +++ b/devspec/architecture/_template/state-lifecycle-diagram.svg @@ -0,0 +1,175 @@ + + [DIAGRAM_TITLE] - State Lifecycle Diagram + [DIAGRAM_DESCRIPTION] + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + [PROJECT_NAME] + [DIAGRAM_TITLE] + [DIAGRAM_DESCRIPTION] + + + + [PRIMARY_LIFECYCLE] + + + + + [EXCEPTION_STATE] + + + + + + Create + + + + Submit + + + + Approve + + + + + Reject + + + + Revise + + + + + + + + + + Draft + Initial state + Editable + + + + + + In Review + Quality gate + Decision point + + + + + + Approved + Ready state + Locked + + + + + + + + + + + Rework + Resolve issues + + + + + Legend + + Normal state + + Exception + + Return or terminal flow + + Rejected transition + + + Generated by devspec - [DATE_OR_VERSION] + diff --git a/devspec/architecture/_template/timeline-plan-diagram.svg b/devspec/architecture/_template/timeline-plan-diagram.svg new file mode 100644 index 0000000..4923d1f --- /dev/null +++ b/devspec/architecture/_template/timeline-plan-diagram.svg @@ -0,0 +1,157 @@ + + [DIAGRAM_TITLE] - Timeline Plan Diagram + [DIAGRAM_DESCRIPTION] + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + [PROJECT_NAME] + [DIAGRAM_TITLE] + [DIAGRAM_DESCRIPTION] + + + + PLANNING + + + + + BUILD + + + + + VALIDATE + + + + + RELEASE + + + + + + [T1] + + [T2] + + [T3] + + [T4] + + + + Depends + + + Risk + + + + + + Plan Ready + [date / sprint] + + + + + + + Build Done + [date / sprint] + + + + + + + Validation Gate + [date / sprint] + + + + + + + Release + [date / sprint] + + + + + Legend + + Milestone + + Gate / risk + + Dependency + + + Generated by devspec - [DATE_OR_VERSION] + diff --git a/devspec/architecture/artifact-queue.md b/devspec/architecture/artifact-queue.md index 45c41e1..36b757c 100644 --- a/devspec/architecture/artifact-queue.md +++ b/devspec/architecture/artifact-queue.md @@ -2,7 +2,7 @@ Use this file as the resumable queue register for proposed and generated architecture diagrams. Keep generated diagram content in the target artifact; keep only queue metadata, evidence, confidence, status, output-format guidance, and next action or notes here. -Store high-level diagrams in `devspec/architecture/overview.md`, durable detailed Markdown diagram artifacts in `devspec/architecture/diagrams/dia-NNN-.md`, durable SVG images in `devspec/architecture/images/dia-NNN-.svg`, and temporary work-item diagrams in `devspec/work-items//diagrams.md` with optional SVG images under `devspec/work-items//images/`. +Store high-level diagram references in `devspec/architecture/overview.md`, durable SVG images in `devspec/architecture/images/dia-NNN-.svg` by default, optional Mermaid Markdown artifacts in `devspec/architecture/diagrams/dia-NNN-.md`, optional HTML diagram artifacts in `devspec/architecture/html/dia-NNN-.html`, and temporary work-item diagrams under `devspec/work-items//images/` with optional Mermaid `diagrams.md` or `html/*.html` companions. ## Diagram Queue Register @@ -19,9 +19,9 @@ Add rows only when extraction or `/devspec.diagram` identifies real diagram cand | Scope | Use `architecture`, `module`, `feature`, `workflow`, `user-journey`, or `work-item`. Prefer durable scopes over `work-item` unless the diagram is explicitly temporary or work-item-specific. | | Diagram type | Use the logical diagram family only: `flowchart`, `sequenceDiagram`, `journey`, `stateDiagram`, `classDiagram`, `erDiagram`, `gantt`, `quadrantChart`, `mindmap`, or `timeline`. Do not include orientation or output format here. | | Subject | Use a specific lowercase kebab-case subject that can map to one diagram file or one overview section. For queued architecture diagrams, prefix the subject with the lowercase queue ID, such as `dia-001-order-fulfillment-flow`. | -| Target location | Use `devspec/architecture/overview.md#diagram-reference-index` for high-level overview diagrams, `devspec/architecture/diagrams/dia-NNN-.md` for durable detailed Markdown artifacts, or `devspec/work-items//diagrams.md#diagram-content` for temporary work-item diagrams. Record SVG targets such as `devspec/architecture/images/dia-NNN-.svg` in `Next action or notes`. | +| Target location | Use `devspec/architecture/images/dia-NNN-.svg` for default durable SVG output, `devspec/architecture/overview.md#diagram-reference-index` for high-level overview references, `devspec/architecture/diagrams/dia-NNN-.md` for optional Mermaid Markdown artifacts, `devspec/architecture/html/dia-NNN-.html` for optional HTML artifacts, or work-item `images/`, `diagrams.md#diagram-content`, and `html/` targets for temporary work-item diagrams. Record companion targets in `Next action or notes`. | | Evidence | Name the source paths, docs, ADRs, queue request, or user-confirmed basis supporting the candidate. | | Confidence | Use `observed` for direct evidence, `high-confidence` for inference from multiple local evidence points, or `low-confidence` when useful but incomplete evidence needs assumptions before generation. | | Status | Use `devspec/glossary.md#artifact-status-values`; queue status belongs here, not in diagram indexes or generated diagram content. | | Tags | Use comma-separated lowercase tags such as `process-flow`, `business-process`, `user-journey`, `lifecycle-flow`, or `hybrid-user-to-data-operational-flow` when they apply. Leave blank only when no durable selection tag is useful. | -| Next action or notes | Record duplicate-check result, output format (`format=mermaid`, `format=svg`, or `format=mermaid+svg`), suggested Mermaid declaration such as `flowchart LR` or `sequenceDiagram`, SVG target when applicable, assumptions, blocker details, skip reason, or the next action needed. | +| Next action or notes | Record duplicate-check result, output format as one or more of `svg`, `html`, and `mermaid` joined with `+`. Examples: `format=svg`, `format=html`, `format=mermaid`, `format=svg+html`, `format=svg+mermaid`, `format=svg+html+mermaid`, `format=html+mermaid`. Include suggested Mermaid declaration such as `flowchart LR` or `sequenceDiagram` when the output set includes `mermaid`, SVG target, optional Mermaid or HTML targets, assumptions, blocker details, skip reason, or the next action needed. | diff --git a/devspec/architecture/diagrams/README.md b/devspec/architecture/diagrams/README.md index fc8e0f4..9dbb699 100644 --- a/devspec/architecture/diagrams/README.md +++ b/devspec/architecture/diagrams/README.md @@ -1,8 +1,8 @@ # Architecture Diagrams -Use this folder for durable Markdown diagram artifacts that are more specific than the high-level architecture context in `devspec/architecture/overview.md`. Mermaid is the default generated diagram content; SVG output is opt-in with `format=svg` or `format=mermaid+svg`. +Use this folder for optional durable Mermaid diagram artifacts, stored as Markdown files, that are more specific than the high-level architecture context in `devspec/architecture/overview.md`. SVG is the default generated diagram output and lives under `devspec/architecture/images/`; Mermaid is generated only when the requested output set includes `mermaid`, such as `format=mermaid`, `format=svg+mermaid`, `format=html+mermaid`, or `format=svg+html+mermaid`. -Store module, feature workflow, process-flow, user journey, sequence, state, class/domain, and cross-feature diagrams as one Markdown file per subject. Store durable SVG images under `devspec/architecture/images/dia-NNN-.svg` when requested. Track proposed, generated, skipped, or blocked diagram work with evidence, confidence, output format, and tags in `devspec/architecture/artifact-queue.md`. +Store optional module, feature workflow, process-flow, user journey, sequence, state, class/domain, and cross-feature Mermaid diagrams as one Markdown file per subject only when the output set includes `mermaid`. Store durable SVG images under `devspec/architecture/images/dia-NNN-.svg` by default and optional HTML under `devspec/architecture/html/dia-NNN-.html`. Track proposed, generated, skipped, or blocked diagram work with evidence, confidence, output format, and tags in `devspec/architecture/artifact-queue.md`. ## File and Queue Naming @@ -10,17 +10,17 @@ Use Title Case for diagram display names and lowercase sequence-prefixed kebab-c Keep default subjects language-neutral after the sequence prefix, such as `dia-NNN-system-context`, `dia-NNN-runtime-containers`, `dia-NNN-dependency-graph`, or `dia-NNN-authentication-authorization-flow`. Use `dia-NNN-hybrid-user-to-data-operational-flow` for the durable hybrid flow that connects user entry points, application boundaries, services, data stores, validations, operational states, and outcomes. -Queue `Diagram type` records the logical diagram family only. The generated diagram artifact records the output format, and records the full Mermaid declaration such as `flowchart LR`, `flowchart TD`, `sequenceDiagram`, `stateDiagram-v2`, or `erDiagram` when Mermaid output is selected. +Queue `Diagram type` records the logical diagram family only. Optional Mermaid artifacts record the full Mermaid declaration such as `flowchart LR`, `flowchart TD`, `sequenceDiagram`, `stateDiagram-v2`, or `erDiagram` when the selected output set includes `mermaid`. `DIA-*` IDs, `dia-NNN-*` subjects, and `dia-NNN-*` filenames are durable diagram file and diagram queue naming conventions. They must not leak into Mermaid internal naming or SVG visible labels unless they are part of metadata outside the diagram content. -## SVG Output +## Output Formats -- `/devspec.diagram ` generates Mermaid by default. -- `/devspec.diagram format=svg ` generates SVG-only visual output plus the required Markdown metadata artifact. -- `/devspec.diagram format=mermaid+svg ` generates both the Mermaid block and the SVG companion file. -- For SVG-only output, keep the Markdown artifact for resume state, metadata, evidence, assumptions, queue linkage, and SVG target reference. -- Use `devspec/architecture/_template/process-flow-diagram.svg` for process-flow SVG output, and `devspec/architecture/_template/architecture-diagram.svg` for other durable SVG output. Validate generated SVG as XML before reporting success. +- `/devspec.diagram ` generates SVG by default. +- `/devspec.diagram format=mermaid ` generates optional Markdown/Mermaid output. +- `/devspec.diagram format=html ` generates optional standalone HTML output. +- Output sets can contain any non-duplicated `+` combination of `svg`, `html`, and `mermaid`, such as `format=svg+html`, `format=svg+mermaid`, `format=html+mermaid`, or `format=svg+html+mermaid`. +- Select SVG templates from `.github/prompts/PATTERNS.md#svg-output-pattern` when the output set includes `svg`, and validate generated SVG as XML before reporting success. ## Mermaid Readability diff --git a/devspec/architecture/html/README.md b/devspec/architecture/html/README.md new file mode 100644 index 0000000..ea55815 --- /dev/null +++ b/devspec/architecture/html/README.md @@ -0,0 +1,20 @@ +# Architecture HTML Diagrams + +Use this folder for optional standalone HTML diagram artifacts generated by `/devspec.diagram` when the requested output set includes `html`, such as `format=html`, `format=svg+html`, `format=html+mermaid`, or `format=svg+html+mermaid`. + +SVG is the default diagram output and lives under `devspec/architecture/images/`. Mermaid Markdown output is optional and lives under `devspec/architecture/diagrams/`. + +## Naming + +- Use the same `DIA-*` sequence and lowercase subject prefix as the matching diagram queue row. +- `DIA-001 - Order Fulfillment Flow` maps to `devspec/architecture/html/dia-001-order-fulfillment-flow.html`. +- Never renumber existing `DIA-*` rows, SVG files, Mermaid Markdown artifacts, or HTML files. + +## Generation Rules + +- Use `devspec/architecture/_template/diagram.html` as the starting point unless a documented constraint requires a smaller custom HTML file. +- Keep HTML standalone and static: inline styles, no remote assets, no remote fonts, no scripts, no iframes, and no unresolved placeholders. +- Prefer embedding the generated SVG markup inline when the same artifact set includes SVG output. +- Keep visible labels short and evidence-backed. Do not include secrets, credentials, private keys, or internal-only URLs. + +Temporary work-item HTML diagrams belong under `devspec/work-items//html/`, with status still tracked in `devspec/architecture/artifact-queue.md`. diff --git a/devspec/architecture/images/README.md b/devspec/architecture/images/README.md index af52a64..75827ea 100644 --- a/devspec/architecture/images/README.md +++ b/devspec/architecture/images/README.md @@ -1,18 +1,18 @@ # Architecture Images -Use this folder for durable SVG diagram images generated by `/devspec.diagram` when the request or queue row includes `format=svg` or `format=mermaid+svg`. +Use this folder for durable SVG diagram images generated by `/devspec.diagram`. SVG is the default diagram output. -Mermaid remains the default diagram output. Durable Markdown diagram artifacts live under `devspec/architecture/diagrams/dia-NNN-.md`; SVG companion images live here as `dia-NNN-.svg`. +Optional Mermaid Markdown diagram artifacts live under `devspec/architecture/diagrams/dia-NNN-.md`. Optional standalone HTML artifacts live under `devspec/architecture/html/dia-NNN-.html`. ## Naming - Use the same `DIA-*` sequence and lowercase subject prefix as the matching diagram queue row. - `DIA-001 - Order Fulfillment Flow` maps to `devspec/architecture/images/dia-001-order-fulfillment-flow.svg`. -- Never renumber existing `DIA-*` rows, Markdown diagram artifacts, or SVG files. +- Never renumber existing `DIA-*` rows, SVG files, Mermaid Markdown artifacts, or HTML files. ## Generation Rules -- Use `devspec/architecture/_template/process-flow-diagram.svg` for process-flow SVGs. Use `devspec/architecture/_template/architecture-diagram.svg` for all other SVG diagram output unless a documented constraint requires a smaller custom SVG. +- Select the SVG template from `.github/prompts/PATTERNS.md#svg-output-pattern`; every SVG must keep the shared dark architecture-style visual contract unless a documented constraint requires a smaller custom SVG. - Keep SVG files standalone: inline styles, inline markers, no remote assets, no scripts, no iframes, and no `foreignObject`. - Keep visible labels short and evidence-backed. Do not include secrets, credentials, private keys, internal-only URLs, or unresolved placeholders in generated SVG files. - Validate generated SVG as XML before marking the queue row generated. diff --git a/devspec/architecture/overview.md b/devspec/architecture/overview.md index 46d8b84..c17dbd0 100644 --- a/devspec/architecture/overview.md +++ b/devspec/architecture/overview.md @@ -18,7 +18,7 @@ Use this section for confirmed high-level diagrams in this file and links to dur | ID | Scope | Diagram type | Subject | Link or section | Usage notes | | --- | --- | --- | --- | --- | --- | -| | architecture, module, feature, workflow, user-journey | flowchart, sequenceDiagram, journey, stateDiagram, classDiagram, erDiagram | | `devspec/architecture/diagrams/dia-NNN-.md`, optional `devspec/architecture/images/dia-NNN-.svg`, or section anchor | | +| | architecture, module, feature, workflow, user-journey | flowchart, sequenceDiagram, journey, stateDiagram, classDiagram, erDiagram | | `devspec/architecture/images/dia-NNN-.svg`, optional `devspec/architecture/diagrams/dia-NNN-.md`, optional `devspec/architecture/html/dia-NNN-.html`, or section anchor | | ## Decision Reference Index diff --git a/devspec/work-items/_template/diagrams.md b/devspec/work-items/_template/diagrams.md index e7cedca..e36e025 100644 --- a/devspec/work-items/_template/diagrams.md +++ b/devspec/work-items/_template/diagrams.md @@ -1,8 +1,8 @@ # Work-Item Diagrams -Use this file only for explicit or clearly temporary work-item diagrams. +Use this optional Markdown file only for explicit or clearly temporary work-item diagrams when the selected output set includes `mermaid`. -Reusable diagrams live under `devspec/architecture/diagrams/`; durable SVGs live under `devspec/architecture/images/`. `devspec/architecture/artifact-queue.md` owns diagram status. Temporary SVGs for this work item belong under `devspec/work-items//images/`. +Reusable default SVG diagrams live under `devspec/architecture/images/`; optional durable Mermaid Markdown diagrams live under `devspec/architecture/diagrams/`; optional durable HTML diagrams live under `devspec/architecture/html/`. `devspec/architecture/artifact-queue.md` owns diagram status. Temporary SVGs for this work item belong under `devspec/work-items//images/`; temporary HTML files belong under `devspec/work-items//html/`. ## Resume State @@ -28,20 +28,26 @@ Reusable diagrams live under `devspec/architecture/diagrams/`; durable SVGs live | Field | Value | | --- | --- | | Type | | -| Output format | mermaid, svg, mermaid+svg | +| Output format | mermaid, svg+mermaid, html+mermaid, or svg+html+mermaid | | Subject | | | SVG target | `devspec/work-items//images/.svg` when output format includes svg | +| HTML target | `devspec/work-items//html/.html` when output format includes html | | Queue source | `devspec/architecture/artifact-queue.md` | | Evidence sources | | | Confidence | observed, high-confidence, low-confidence | | Assumptions | none or listed below | | Notes | | -Follow `.github/prompts/PATTERNS.md#diagram-extraction-consistency-pattern`, `#mermaid-internal-naming-and-readability-pattern`, `#mermaid-visual-quality-pattern`, and `#svg-output-pattern` when generating content. +Follow `.github/prompts/PATTERNS.md#diagram-extraction-consistency-pattern`, `#mermaid-internal-naming-and-readability-pattern`, `#mermaid-visual-quality-pattern`, and `#svg-output-pattern` when generating content. Mermaid flowcharts must use the dark init block and semantic role palette; when a Mermaid renderer ignores theme settings, use SVG or HTML output as the canonical architecture-style visual and record the limitation in `Notes`. ```mermaid +%%{init: {'theme': 'dark', 'themeVariables': {'primaryColor': '#1e293b', 'primaryTextColor': '#f8fafc', 'lineColor': '#64748b', 'clusterBkg': '#0f172a', 'clusterBorder': '#334155'}}}%% flowchart TD + classDef gen fill:#1e293b,stroke:#64748b,color:#e2e8f0 + Placeholder["  "] + + class Placeholder gen ``` -For `format=svg`, omit the Mermaid block content and reference the generated SVG target above. For `format=mermaid+svg`, keep both the Mermaid block and SVG target reference. +Create this Markdown file only when the selected output set includes `mermaid`. For SVG-only or HTML-only output, store targets in the queue row and generated files instead. diff --git a/docs/how-to/README.md b/docs/how-to/README.md index 757df1f..d1d41ff 100644 --- a/docs/how-to/README.md +++ b/docs/how-to/README.md @@ -320,29 +320,34 @@ Use these examples as starting points. The command registry remains authoritativ | `/devspec.tasks` | Ready `finalize.md`; optional task-planning guidance | Work-item `tasks.md` | `/devspec.implement` | | `/devspec.implement` | Ready `finalize.md` and `tasks.md`; optional validation guidance | Work-item `implement.md` and code changes when allowed | `/devspec.review` | | `/devspec.review` | `finalize.md` and `implement.md`; optional review focus | Work-item `review.md` | Return to `/devspec.implement` for changes or close the work item | -| `/devspec.diagram` | Diagram subject, work item, explicit process-flow batch request, or optional `format=svg` / `format=mermaid+svg` | Architecture or work-item Markdown diagram artifacts, with Mermaid by default and opt-in SVG images | Continue the current workflow | +| `/devspec.diagram` | Diagram subject, work item, explicit process-flow batch request, or optional `format=` output combination using `svg`, `html`, and `mermaid` | Architecture or work-item SVG diagram artifacts by default, with optional Mermaid or HTML artifacts | Continue the current workflow | ## Diagrams -Use `/devspec.diagram` when a diagram would clarify architecture, workflow, state, sequence, domain behavior, user journey, or a work-item-specific flow. Mermaid is the default output. +Use `/devspec.diagram` when a diagram would clarify architecture, workflow, state, sequence, domain behavior, user journey, or a work-item-specific flow. SVG is the default output. Examples: ```text +/devspec.diagram runtime architecture /devspec.diagram checkout payment flow /devspec.diagram authentication state transitions /devspec.diagram batch-generate queued process-flow diagrams -/devspec.diagram format=svg checkout payment flow -/devspec.diagram format=mermaid+svg authentication state transitions +/devspec.diagram format=mermaid authentication state transitions +/devspec.diagram format=html runtime architecture +/devspec.diagram format=svg+html runtime architecture +/devspec.diagram format=svg+mermaid checkout payment flow +/devspec.diagram format=html+mermaid authentication state transitions +/devspec.diagram format=svg+html+mermaid runtime architecture ``` -Durable detailed Markdown diagram artifacts live under `devspec/architecture/diagrams/`. Durable SVG images live under `devspec/architecture/images/` when `format=svg` or `format=mermaid+svg` is requested. High-level architecture diagram references belong in `devspec/architecture/overview.md`. Temporary work-item-specific diagrams belong in `devspec/work-items//diagrams.md`, with temporary SVGs under `devspec/work-items//images/`. +Durable SVG images live under `devspec/architecture/images/` by default. Optional Mermaid diagram artifacts live as Markdown files under `devspec/architecture/diagrams/`. Optional standalone HTML diagrams live under `devspec/architecture/html/`. High-level architecture diagram references belong in `devspec/architecture/overview.md`. Temporary work-item-specific SVG diagrams belong under `devspec/work-items//images/`, with optional Mermaid in `diagrams.md` and optional HTML under `html/`. -Extraction may seed diagram candidates into `devspec/architecture/artifact-queue.md`. Use `/devspec.diagram` as the normal follow-up when a queued diagram should be generated. `/devspec.extract` preserves `format=svg` and `format=mermaid+svg` preferences in queue notes and may generate at most one approved diagram artifact set during extraction, matching the Mermaid approval gate. +Extraction may seed diagram candidates into `devspec/architecture/artifact-queue.md`. Use `/devspec.diagram` as the normal follow-up when a queued diagram should be generated. `/devspec.extract` preserves requested diagram format preferences in queue notes and may generate at most one approved diagram artifact set during extraction, matching the diagram approval gate. -Use `format=svg` for SVG-only visual output. The command still creates or updates the Markdown diagram artifact for resume state, metadata, evidence, assumptions, queue linkage, and SVG target reference. Use `format=mermaid+svg` when both the Mermaid block and SVG companion are needed. +Use `format=svg` or omit the format token for SVG output. Use `format=mermaid` when a Markdown/Mermaid artifact is needed. Use `format=html` when a standalone HTML artifact is needed. Example: `format=svg`, `format=html`, `format=mermaid`, `format=svg+html`, `format=svg+mermaid`, `format=svg+html+mermaid`, `format=html+mermaid`. -Generated Mermaid diagrams should follow the shared readability rules: +Optional generated Mermaid diagrams should follow the shared readability rules: - Keep `DIA-*` and `dia-NNN-*` names for the durable diagram file and diagram queue, not for Mermaid nodes. - Use short alphanumeric node IDs, double-quoted node labels of 1-4 words, no `\n` or `
` line breaks, and 2-3 word edge labels. @@ -360,7 +365,152 @@ flowchart LR ProviderSvc -->|"Reads Profile"| UserDb["User Database"] ``` -Generated SVG diagrams should be standalone XML created from `devspec/architecture/_template/architecture-diagram.svg` or, for process-flow SVGs, `devspec/architecture/_template/process-flow-diagram.svg`, with inline styles, no external assets, no `