devspec 0.1.2__tar.gz → 0.2.0__tar.gz

{devspec-0.1.2 → devspec-0.2.0}/.agents/rules/devspec-workflow.md

@@ -13,12 +13,12 @@ Follow these rules:
 - Preserve the original intent of the canonical Copilot prompt and agent files named in the registry.
 - Use Git-tracked `devspec/` artifacts for recovery before relying on chat history, Antigravity artifacts, memory, or task lists.
 - Preserve required inputs, output artifacts, status values, gates, handoff order, and recovery behavior.
-- Preserve structured question behavior from `.github/prompts/PATTERNS.md#interactive-question-pattern`; if clickable options are unavailable, render the same option labels as text and preserve the recommended option.
+- Preserve structured question behavior from `.github/prompts/PATTERNS.md#interactive-question-pattern`: show interactive multiple-choice options when Antigravity can render them, otherwise render the identical options as text; include an example for every option and `Custom Answer`; ask one question at a time; and preserve the recommendation with its justification.
 - Use `devspec/glossary.md` for status values.
 - 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.
 

devspec-0.2.0/.agents/skills/devspec-changerequest.md

@@ -0,0 +1,13 @@
+---
+name: devspec-changerequest
+description: Run /devspec.changerequest using the canonical devspec command registry and Copilot reference contract.
+---
+
+Execute canonical command `/devspec.changerequest`.
+
+- Read `devspec/adapters/command-registry.md` for the command contract.
+- Read `.github/prompts/devspec.changerequest.prompt.md` and `.github/agents/devspec.changerequest.agent.md` as the source of intent.
+- Preserve required inputs, artifact outputs, status values, gates, handoff order, and recovery behavior.
+- Use Git-tracked `devspec/` artifacts for recovery before relying on chat history or Antigravity artifacts.
+- Append accepted `CR-###` scope to existing work-item artifacts; do not create a CR-specific Markdown file or rewrite baseline history.
+- Treat unsupported Antigravity behavior as an adapter limitation, not a workflow change.

devspec-0.2.0/.agents/skills/devspec-diagram.md

@@ -0,0 +1,17 @@
+---
+name: devspec-diagram
+description: Run /devspec.diagram using the canonical devspec command registry and Copilot reference contract.
+---
+
+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 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.
+
+Command input comes from the user's current message.

{devspec-0.1.2 → devspec-0.2.0}/.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.

devspec-0.2.0/.claude/skills/devspec-changerequest/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: devspec-changerequest
+description: Run /devspec.changerequest using the canonical devspec command registry. Records one missed related requirement for a finalized work item without rewriting baseline history.
+---
+
+Execute canonical command `/devspec.changerequest`.
+
+1. Read `AGENTS.md` for canonical workflow, no-intent-drift, cross-tool recovery, and structured question rules.
+2. Read `devspec/adapters/command-registry.md` for this command's required input, outputs, mutation level, and next handoff.
+3. Read `.github/prompts/devspec.changerequest.prompt.md` and `.github/agents/devspec.changerequest.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, and output closure.
+5. Preserve baseline rows and prior evidence; append accepted `CR-###` scope only to existing work-item artifacts.
+
+Command input comes from the user's current message.

{devspec-0.1.2 → devspec-0.2.0}/.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.

{devspec-0.1.2 → devspec-0.2.0}/.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.

{devspec-0.1.2 → devspec-0.2.0}/.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`.

devspec-0.2.0/.gemini/commands/devspec/changerequest.toml

@@ -0,0 +1,13 @@
+description = "Run canonical /devspec.changerequest from Gemini CLI."
+prompt = """
+Execute canonical command `/devspec.changerequest`.
+
+Before acting:
+1. Read `devspec/adapters/command-registry.md` and use the `/devspec.changerequest` row as the command contract.
+2. Read `.github/prompts/devspec.changerequest.prompt.md` and `.github/agents/devspec.changerequest.agent.md` as the protected source of intent.
+3. Follow `.github/prompts/PATTERNS.md` for shared workflow, recovery, output, and recommendation behavior.
+4. Recover from existing Git-tracked `devspec/` artifacts before relying on Gemini session memory.
+5. Preserve baseline history and append accepted `CR-###` scope only to existing work-item artifacts.
+6. 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.

{devspec-0.1.2 → devspec-0.2.0}/.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.
 

{devspec-0.1.2 → devspec-0.2.0}/.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.

devspec-0.2.0/.github/agents/devspec.changerequest.agent.md

@@ -0,0 +1,34 @@
+---
+name: "devspec.changerequest"
+description: "Use to append one missed related requirement to a finalized-or-later work item as an immutable change request."
+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
+agents: []
+handoffs:
+  - label: Continue to Finalize
+    agent: devspec.finalize
+    prompt: Create or update the readiness brief for the active change request.
+  - label: Create Linked Work Item
+    agent: devspec.story
+    prompt: Create the independently scoped linked work item selected during change-request intake.
+---
+You append one missed, related completeness addition to an existing work item without rewriting baseline history.
+
+## Constraints
+- Follow the [Work-Item Target Pattern](../prompts/PATTERNS.md#work-item-target-pattern), [Work-Item Change Request Pattern](../prompts/PATTERNS.md#work-item-change-request-pattern), [Session Recovery Pattern](../prompts/PATTERNS.md#session-recovery-pattern), [Prerequisite Validation Pattern](../prompts/PATTERNS.md#prerequisite-validation-pattern), [Interactive Question Pattern](../prompts/PATTERNS.md#interactive-question-pattern), [Question Basis Pattern](../prompts/PATTERNS.md#question-basis-pattern), and [Output Closure Pattern](../prompts/PATTERNS.md#output-closure-pattern).
+- `meta.md` and `story.md` must exist, and the work-item status must be `finalized`, `tasks-planned`, `implementing`, `implemented`, `reviewing`, or `reviewed`.
+- If the baseline is not finalized, do not create a change request; route missing baseline information to `/devspec.story`, or `/devspec.clarify` when an active blocker already records the question.
+- Handle exactly one related completeness addition per run: missing description, acceptance criterion, functional requirement, nonfunctional requirement, or edge case for the same intended outcome.
+- Append the next `CR-###` to `story.md#change-requests` and append CR-scoped rows such as `CR-001-AC-001`, `CR-001-FR-001`, `CR-001-NFR-001`, or `CR-001-EDGE-001` to the existing story tables.
+- Do not create a dedicated change-request Markdown file. Use existing `meta.md`, `story.md`, and `decisions.md`; later lifecycle stages append their CR-scoped rows to existing `finalize.md`, `tasks.md`, `implement.md`, and `review.md`.
+- Do not rewrite baseline `Summary`, `Description`, `AC-*`, `FR-*`, `NFR-*`, `EDGE-*`, planning signals, completed tasks, implementation evidence, or review evidence.
+- If the request appears independent or unrelated, ask one structured `selection` question with `Append to the current work item` (example: add a missing invalid-input rule for an existing form), `Create a new linked work item` (example: add notifications to an implemented profile-edit story), and `Custom Answer` (example: explain another relationship). Show exactly one recommendation with its justification. Do not append a `CR-###` when a linked item is selected.
+- Update `Workflow State` in `meta.md` and `Resume State` in `story.md` before asking a target, relationship, or requirement question.
+- Keep any material change-request decision in `decisions.md`; do not duplicate the intake rows there.
+- Ask one structured question at a time and hand off to `/devspec.finalize` after accepting a related change request.
+
+## Approach
+1. Locate the existing work item and read `meta.md`, `story.md`, `decisions.md`, and downstream artifacts when present.
+2. Reconcile `Resume State` and validate that the baseline is finalized or later.
+3. Classify the submitted omission as related completeness scope or potentially independent scope.

{devspec-0.1.2 → devspec-0.2.0}/.github/agents/devspec.clarify.agent.md

@@ -9,6 +9,9 @@ handoffs:
   - label: Back to Work-Item Intake
     agent: devspec.story
     prompt: Revise work-item intake from this clarification.
+  - label: Capture Post-Baseline Change Request
+    agent: devspec.changerequest
+    prompt: Record the missed related requirement without rewriting baseline history.
   - label: Continue to Finalize
     agent: devspec.finalize
     prompt: Create or update the implementation readiness brief.
@@ -16,13 +19,14 @@ handoffs:
 You create or update `devspec/work-items/<work-item-folder>/clarify.md`.
 
 ## Constraints
-- Follow the [Work-Item Target Pattern](../prompts/PATTERNS.md#work-item-target-pattern), [Session Recovery Pattern](../prompts/PATTERNS.md#session-recovery-pattern), [Prerequisite Validation Pattern](../prompts/PATTERNS.md#prerequisite-validation-pattern), [Interactive Question Pattern](../prompts/PATTERNS.md#interactive-question-pattern), [Question Basis Pattern](../prompts/PATTERNS.md#question-basis-pattern), [Token Stewardship Pattern](../prompts/PATTERNS.md#token-stewardship-pattern), and [Output Closure Pattern](../prompts/PATTERNS.md#output-closure-pattern).
+- Follow the [Work-Item Target Pattern](../prompts/PATTERNS.md#work-item-target-pattern), [Work-Item Change Request Pattern](../prompts/PATTERNS.md#work-item-change-request-pattern), [Session Recovery Pattern](../prompts/PATTERNS.md#session-recovery-pattern), [Prerequisite Validation Pattern](../prompts/PATTERNS.md#prerequisite-validation-pattern), [Interactive Question Pattern](../prompts/PATTERNS.md#interactive-question-pattern), [Question Basis Pattern](../prompts/PATTERNS.md#question-basis-pattern), [Token Stewardship Pattern](../prompts/PATTERNS.md#token-stewardship-pattern), and [Output Closure Pattern](../prompts/PATTERNS.md#output-closure-pattern).
 - `story.md` must exist.
 - Update `Workflow State` in `meta.md` and `Resume State` in `clarify.md` before asking or resolving a blocking question.
 - Handle one independent blocker at a time.
 - Resolve the active blocker recorded in `story.md`, `finalize.md`, user input, or existing `clarify.md`; do not run the full Readiness Gap Scan in this command.
+- Do not use clarification to introduce post-baseline scope. If user input for a work item in `finalized`, `tasks-planned`, `implementing`, `implemented`, `reviewing`, or `reviewed` status changes scope instead of resolving the active blocker, record the routing reason in `clarify.md`, leave baseline intake unchanged, and hand off to `/devspec.changerequest`.
 - Preserve and apply the Question Basis Pattern for the active blocker.
-- For structured clarification questions, provide 2-5 meaningful and mutually exclusive options when possible, exactly one recommended option with a short reason, and `Custom Answer`.
+- For structured clarification questions, show interactive multiple-choice options or the identical text fallback; provide 2-5 meaningful and mutually exclusive context-specific options plus `Custom Answer`; when no two meaningful alternatives exist, offer `Provide the missing detail` plus `Custom Answer`; give every option a brief non-binding example; and identify exactly one recommended option with a clear justification.
 - Keep active and resolved blocker records only in `Clarification Log`; at most one row may be `open`.
 - Keep handoff and next-action state in `Resume State`, not in a separate outcome section.
 - When a resolved clarification changes intake, update the matching current `story.md` section (`Summary`, `Description`, `Acceptance Criteria`, `Functional Requirements`, `Nonfunctional Requirements`, `Edge Cases`, or `Planning Signals`) and reference that section in `Clarification Log`; do not recreate retired story sections or duplicate full intake content.
@@ -32,7 +36,7 @@ You create or update `devspec/work-items/<work-item-folder>/clarify.md`.
 1. Locate the target work item.
 2. Read `meta.md` when present, `story.md`, `finalize.md` when present, and existing `clarify.md`.
 3. Reconcile `Resume State`; keep any pending user question active and preserve the source artifact for the active blocker.
-4. Ask or resolve the active structured `clarification` question, then update `clarify.md` with `Resume State` and `Clarification Log`.
+4. Classify user input against the active blocker; if it introduces post-baseline scope, route to `/devspec.changerequest`, otherwise ask or resolve the active structured `clarification` question and update `clarify.md` with `Resume State` and `Clarification Log`.
 5. When a blocker is answered, update its `Clarification Log` row to `resolved`, `superseded`, or `withdrawn`, record the answer and impacted artifacts, and update any impacted upstream artifact by reference instead of duplicating full intake or finalization content.
 6. When no blocker remains open, update next action toward `/devspec.finalize` unless the recorded source artifact requires returning to `/devspec.story`.
 7. Report per Output Format.

{devspec-0.1.2 → devspec-0.2.0}/.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-<diagram-name>.svg` for durable diagrams or `devspec/work-items/<work-item-folder>/images/<diagram-name>.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-<diagram-name>.svg` for durable diagrams or `devspec/work-items/<work-item-folder>/images/<diagram-name>.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-<diagram-name>.html` for durable diagrams or `devspec/work-items/<work-item-folder>/html/<diagram-name>.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-<diagram-name>.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-<diagram-name>.svg` by default. Store optional Mermaid Markdown companions under `devspec/architecture/diagrams/dia-NNN-<diagram-name>.md` and optional HTML companions under `devspec/architecture/html/dia-NNN-<diagram-name>.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-<diagram-name>.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-<diagram-name>.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

{devspec-0.1.2 → devspec-0.2.0}/.github/agents/devspec.extract.agent.md

@@ -15,10 +15,10 @@ You create or refresh devspec extraction artifacts from supported repository sou
 ## 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), [Next Action Selection Pattern](../prompts/PATTERNS.md#next-action-selection-pattern), [Extraction State Pattern](../prompts/PATTERNS.md#extraction-state-pattern), [Explore and Memory Pattern](../prompts/PATTERNS.md#explore-and-memory-pattern), [Token Stewardship Pattern](../prompts/PATTERNS.md#token-stewardship-pattern), [Artifact Content Pattern](../prompts/PATTERNS.md#artifact-content-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).
 - Source input is optional. When source input is omitted or blank, ask one structured `selection` question before extraction using these options:
-  - `Use current project root`: extract from the active VS Code workspace or project root where the devspec command is being run. Recommend this when the user appears to be running devspec in the target repository.
-  - `Enter repo paths`: ask for one repository URL or local path, or named multi-repo paths such as `UI - D:\repo-ui, API - D:\repo-api`.
-  - `Cancel extraction`: stop extraction and record no artifact changes.
-  - `Custom Answer`: handle through the Interactive Question Pattern.
+  - `Use current project root`: extract from the active VS Code workspace or project root where the devspec command is being run. Example: use `D:\code\my-app` when it is the opened target repository. Recommend this when the user appears to be running devspec in the target repository.
+  - `Enter repo paths`: ask for one repository URL or local path, or named multi-repo paths. Example: `UI - D:\repo-ui, API - D:\repo-api`.
+  - `Cancel extraction`: stop extraction and record no artifact changes. Example: the user wants to gather repository paths before starting extraction.
+  - `Custom Answer`: accept another source instruction. Example: `Use only D:\code\api and skip the UI repository`.
 - Accept only the confirmed current project root, GitHub, Azure DevOps, or GitLab repository URLs, or local repository folder paths.
 - Treat remote inputs as repository URLs only; reject issue, pull request, merge request, work item, wiki, release, and pipeline URLs.
 - Support a single repository, a monorepo root, or multiple named related repositories.
@@ -35,23 +35,23 @@ You create or refresh devspec extraction artifacts from supported repository sou
 - Before writing a confirmed constitution change, run a lightweight impact check against `devspec/foundation/project-context.md`, `devspec/foundation/rules.md`, affected prompts, agents, templates, adapter guidance, and validation docs; record unresolved follow-ups explicitly.
 - Maintain a single active confirmation gate; do not ask constitution, process-flow candidate, diagram candidate, diagram generation, coding-standards conflict, or repository-access confirmations in the same response.
 - Confirmation priority is: source or access questions, conflicting extracted evidence, constitution principle changes, process-flow candidate approval, diagram candidate approval, then continuation or handoff.
-- Use `Proceed`, `Skip`, and `Custom Answer` for queue, generated artifact, retry, and workflow-continuation decisions; use `Yes`, `No`, and `Custom Answer` for binary confirmations.
+- Use `Proceed`, `Skip`, and `Custom Answer` for queue, generated artifact, retry, and workflow-continuation decisions; use `Yes`, `No`, and `Custom Answer` for binary confirmations. Present every option interactively when supported, attach a contextual example including one for `Custom Answer`, and show exactly one recommendation with its justification.
 - Create or update `devspec/foundation/extraction-state.md` from `devspec/foundation/_template/extraction-state.md` when extraction starts and is not canceled.
 - Process `devspec/foundation/extraction-state.md#extraction-queue` one row at a time in ID order. Keep exactly one row `active`, and update `Resume State`, the active row, and `Blockers and Confirmations` before asking, pausing, blocking, or handing off.
 - 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-<diagram-name>`, Markdown target `devspec/architecture/diagrams/dia-001-<diagram-name>.md`, and optional SVG target `devspec/architecture/images/dia-001-<diagram-name>.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-<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`, and optional HTML target `devspec/architecture/html/dia-001-<diagram-name>.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.

{devspec-0.1.2 → devspec-0.2.0}/.github/agents/devspec.finalize.agent.md

@@ -16,9 +16,10 @@ handoffs:
 You create or update `devspec/work-items/<work-item-folder>/finalize.md`.
 
 ## Constraints
-- Follow the [Work-Item Target Pattern](../prompts/PATTERNS.md#work-item-target-pattern), [Session Recovery Pattern](../prompts/PATTERNS.md#session-recovery-pattern), [Interactive Question Pattern](../prompts/PATTERNS.md#interactive-question-pattern), [Question Basis Pattern](../prompts/PATTERNS.md#question-basis-pattern), [Prerequisite Validation Pattern](../prompts/PATTERNS.md#prerequisite-validation-pattern), [Readiness Gap Scan Pattern](../prompts/PATTERNS.md#readiness-gap-scan-pattern), [Explore and Memory Pattern](../prompts/PATTERNS.md#explore-and-memory-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), [Exploration Recovery Pattern](../prompts/PATTERNS.md#exploration-recovery-pattern), and [Output Closure Pattern](../prompts/PATTERNS.md#output-closure-pattern).
-- Required upstream artifacts must exist before finalization; use `story.md#summary`, `story.md#description`, `story.md#acceptance-criteria`, `story.md#functional-requirements`, `story.md#nonfunctional-requirements`, `story.md#edge-cases`, and `story.md#planning-signals` as the source for intake narrative, requirements, acceptance criteria, dependencies, type-specific notes, risks, and blockers.
+- Follow the [Work-Item Target Pattern](../prompts/PATTERNS.md#work-item-target-pattern), [Work-Item Change Request Pattern](../prompts/PATTERNS.md#work-item-change-request-pattern), [Session Recovery Pattern](../prompts/PATTERNS.md#session-recovery-pattern), [Interactive Question Pattern](../prompts/PATTERNS.md#interactive-question-pattern), [Question Basis Pattern](../prompts/PATTERNS.md#question-basis-pattern), [Prerequisite Validation Pattern](../prompts/PATTERNS.md#prerequisite-validation-pattern), [Readiness Gap Scan Pattern](../prompts/PATTERNS.md#readiness-gap-scan-pattern), [Explore and Memory Pattern](../prompts/PATTERNS.md#explore-and-memory-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), [Exploration Recovery Pattern](../prompts/PATTERNS.md#exploration-recovery-pattern), and [Output Closure Pattern](../prompts/PATTERNS.md#output-closure-pattern).
+- Required upstream artifacts must exist before finalization; use `story.md#summary`, `story.md#change-requests`, `story.md#description`, `story.md#acceptance-criteria`, `story.md#functional-requirements`, `story.md#nonfunctional-requirements`, `story.md#edge-cases`, and `story.md#planning-signals` as the source for intake narrative, change requests, requirements, acceptance criteria, dependencies, type-specific notes, risks, and blockers.
 - Read `decisions.md` when present; use accepted work-item decisions as scope, planning, validation, rollout, or handoff inputs by referencing their `DEC-*` IDs.
+- When finalizing an accepted change request, set `Resume State` `Current item` to the active `CR-###` and append CR-scoped readiness, implementation brief, validation plan, and blocker rows. Preserve prior baseline and prior CR rows.
 - Run the Readiness Gap Scan before setting `finalize.md` to `ready`.
 - Set `Readiness Assessment` status to `ready` only when every required readiness gate is `ready` or `not applicable`; otherwise set it to `not ready`.
 - Mark the brief `not ready` while blockers remain or required repository access, foundation alignment, architecture alignment, compliance handling, or validation expectations are missing, ambiguous, conflicting, or unconfirmed.
@@ -29,6 +30,7 @@ You create or update `devspec/work-items/<work-item-folder>/finalize.md`.
 - Ensure every acceptance criterion, type-specific requirement, delivery gate, and material risk has validation coverage in `Validation Plan` or a blocking reason before marking `ready`.
 - For multi-repo work, record only repository readiness summary in `Implementation Brief`, including required repositories and whether access is confirmed, missing, or blocked; keep local paths and access requirement values in `../../devspec/foundation/codebase-structure.md`.
 - Do not invent missing requirements or silently change scope.
+- Do not rewrite baseline readiness, implementation brief, validation plan, or blocker rows to fit later change-request scope.
 - Use `Explore` when implementation context, analogous behavior, or impact areas need quick discovery.
 - Use session memory only for transient notes; `finalize.md` remains canonical.
 - Update `Workflow State` in `meta.md` and `Resume State` in `finalize.md` before marking `not ready`, asking for clarification, or handing off.
@@ -47,7 +49,7 @@ You create or update `devspec/work-items/<work-item-folder>/finalize.md`.
 2. Read `meta.md` when present, `decisions.md` when present, required upstream artifacts, and applicable foundation and architecture alignment sources.
 3. Reconcile `Resume State`, discovery exclusions, and optional exploration state.
 4. Use `Explore` when needed; persist meaningful discovery notes and unresolved assumptions before asking or writing.
-5. Run the Readiness Gap Scan, including foundation and architecture alignment, and map material gaps into readiness gates, `Implementation Brief`, `Validation Plan`, or blockers.
+5. Run the Readiness Gap Scan for the current item (`baseline` or active `CR-###`), including foundation and architecture alignment, and map material gaps into readiness gates, `Implementation Brief`, `Validation Plan`, or blockers.
 6. Resolve target selection or blockers through structured `selection` or `clarification` questions following the Interactive Question Pattern; use `/devspec.clarify` for the top blocking ambiguity when a separate clarification handoff is needed.
 7. Apply type-specific readiness gates and write `finalize.md` with `../../devspec/work-items/_template/finalize.md`.
 8. Report per Output Format.

{devspec-0.1.2 → devspec-0.2.0}/.github/agents/devspec.implement-task.agent.md

@@ -11,34 +11,40 @@ handoffs:
     prompt: Review the current implementation.
   - label: Start Another Work Item
     agent: devspec.story
+  - label: Capture Post-Baseline Change Request
+    agent: devspec.changerequest
+    prompt: Record a missed related requirement without rewriting baseline history.
     prompt: Start or update another devspec work item.
 ---
 You implement the current work item and update `devspec/work-items/<work-item-folder>/implement.md`.
 
 ## Constraints
-- Follow [PATTERNS.md](../prompts/PATTERNS.md), especially: Work-Item Target, Session Recovery, Interactive Question, Question Basis, Prerequisite Validation, Multi-Repo Validation, Token Stewardship, Minimum Necessary Implementation, Task Quality Gate, Discovery Exclusion, Exploration Recovery, and Output Closure.
+- Follow [PATTERNS.md](../prompts/PATTERNS.md), especially: Work-Item Target, Work-Item Change Request Pattern, Session Recovery, Interactive Question, Question Basis, Prerequisite Validation, Multi-Repo Validation, Token Stewardship, Minimum Necessary Implementation, Task Quality Gate, Discovery Exclusion, Exploration Recovery, and Output Closure.
 - `finalize.md` must be `ready` and `tasks.md` must exist.
 - Implement pending rows from `tasks.md#implementation-tasks` sequentially unless the user stops or skips.
+- For change-request implementation, implement only pending rows whose `Scope` matches the active `CR-###` unless the user explicitly directs otherwise; preserve baseline and prior CR evidence.
 - Validate target repository path and access before changing code or running validation for multi-repo tasks.
 - Stop before implementation when target repository access is missing, ambiguous, or unconfirmed; direct the user to `/devspec.codebase-structure`.
+- If newly discovered user scope is a missed related requirement after finalization, do not expand implementation silently; hand off to `devspec.changerequest`.
 - Do not edit repositories marked `reference-only`, `validation-only`, `release-coordination`, or `unavailable` without structured confirmation.
 - Do not run validation in repositories marked `reference-only`, `release-coordination`, or `unavailable` without structured confirmation.
 - Modify code when applicable and stay within finalized scope.
 - Keep the work item as the orchestration boundary and execute one repository-aware task checkpoint at a time.
 - For monorepos, distinguish tasks by target area, module, layer, or validation surface; for multi-repo work, every task must name target repository and access requirement.
 - Apply the Minimum Necessary Implementation Pattern before each task attempt, including confirming whether the task requires a code change.
-- Apply the Task Quality Gate Pattern before each task attempt, respecting `Depends on` and `Source refs` from `tasks.md`; record any task-quality blocker in `implement.md` and stop for the required structured question.
+- Apply the Task Quality Gate Pattern before each task attempt, respecting `Scope`, `Depends on`, and `Source refs` from `tasks.md`; record any task-quality blocker in `implement.md` and stop for the required structured question.
 - Use targeted reads and searches from `tasks.md` target areas before broad discovery.
 - Resume a `paused` current task when prerequisites still hold; ask one structured `resume` question for `stopped` or ambiguous state.
 - Update `implement.md` using `../../devspec/work-items/_template/implement.md`.
 - Apply implementation requirements from `../../devspec/foundation/rules.md#work-item-handling-rules`.
-- After each completed task, report completed and pending counts and ask one structured `continuation` question with `Proceed`, `Skip`, and `Custom Answer`.
-- If the same task exceeds three implementation or repair attempts, stop, explain the loop, and ask one structured `retry` question with `Proceed`, `Skip`, and `Custom Answer`.
+- After each completed task, report completed and pending counts and ask one structured `continuation` question with `Proceed` (example: continue to the next pending task), `Skip` (example: defer the next task with a recorded reason), and `Custom Answer` (example: stop after the current repository). Show exactly one recommendation with its justification.
+- If the same task exceeds three implementation or repair attempts, stop, explain the loop, and ask one structured `retry` question with `Proceed` (example: retry with the recorded safer method), `Skip` (example: leave the task blocked for later investigation), and `Custom Answer` (example: supply a new validation command). Show exactly one recommendation with its justification.
 - Record task attempt failures with failed method, reason, retry condition, and next safer method.
 - Record token telemetry before implementation and after completion when available; otherwise record it as unavailable.
 - If code changes are not applicable in the configured target repository, record that clearly.
 - Keep `Implementation Task Ledger`, `Implementation Execution Log`, and `Resume State` current after each task, validation run, blocker, pause, stop, or retry escalation.
 - Keep `tasks.md#implementation-tasks` `Status`, `Attempt count`, and `Last checkpoint` aligned with `implement.md` after each task attempt, validation result, blocker, skip, or completion.
+- Append implementation evidence and execution-log rows. Do not remove or rewrite prior baseline or prior CR evidence except to add explicit correction notes.
 - Keep `implement.md` recovery-focused; omit empty evidence and record only access checks, changes, validation, type-specific notes, risks, retries, blockers, telemetry, and handoff details.
 - Do not narrate rejected implementation options unless they explain a risk, blocker, retry, or review concern.
 - Record implementation progress in compact tables.
@@ -52,7 +58,7 @@ You implement the current work item and update `devspec/work-items/<work-item-fo
 5. Resolve target selection, blocker clarification, or multi-repo access before implementation.
 6. Record pre-run token telemetry or mark it unavailable.
 7. Apply type-specific work-item handling rules for bugs and security vulnerabilities.
-8. Select the next paused or pending task; if none remain, update `implement.md`, mark completion, and notify the user.
+8. Select the next paused or pending task for the active scope; if none remain, update `implement.md`, mark completion, and notify the user.
 9. Apply the Minimum Necessary Implementation Pattern and Task Quality Gate Pattern, implement the task when applicable, and run appropriate validation.
 10. Record reusable search, helper-command, repair, or validation methods.
 11. Update `implement.md` with access status, implementation task ledger, checkpoints, implementation execution log, changed files, validation, blockers, type-specific notes, counts, and confirmation outcome; update the matching task row in `tasks.md` when its status, attempt count, or checkpoint changed.

{devspec-0.1.2 → devspec-0.2.0}/.github/agents/devspec.review.agent.md

@@ -11,17 +11,23 @@ handoffs:
     prompt: Address the review findings.
   - label: Start Another Work Item
     agent: devspec.story
+  - label: Capture Post-Baseline Change Request
+    agent: devspec.changerequest
+    prompt: Record a missed related requirement without rewriting baseline history.
     prompt: Start or update another devspec work item.
 ---
 You review the current work item and update `devspec/work-items/<work-item-folder>/review.md`.
 
 ## Constraints
-- Follow [PATTERNS.md](../prompts/PATTERNS.md), especially: Work-Item Target, Session Recovery, Interactive Question, Question Basis, Prerequisite Validation, Token Stewardship, Minimum Necessary Implementation, Task Quality Gate, Discovery Exclusion, Exploration Recovery, and Output Closure.
+- If review reveals a missed related requirement rather than a defect in finalized scope, preserve the review record and hand off to `devspec.changerequest`.
+- Follow [PATTERNS.md](../prompts/PATTERNS.md), especially: Work-Item Target, Work-Item Change Request Pattern, Session Recovery, Interactive Question, Question Basis, Prerequisite Validation, Token Stewardship, Minimum Necessary Implementation, Task Quality Gate, Discovery Exclusion, Exploration Recovery, and Output Closure.
 - `finalize.md`, `tasks.md`, and `implement.md` must exist.
 - Review against the finalized brief, `tasks.md`, `implement.md`, and implemented changes, not a new plan.
+- For change-request review, review the active `CR-###` against its finalized rows, task rows, implementation evidence, and changed work while preserving prior baseline and prior CR review records.
 - Record findings with severity and required action when applicable.
 - Record task-quality, validation, scope, security, regression, and follow-up issues as `Review Findings`; use `Review Outcome` only for status, summary, scope alignment, validation coverage, task completion alignment, and type-specific summary notes.
 - Treat correctness, finalized scope, security, and validation coverage as primary review responsibilities; use the Minimum Necessary Implementation Pattern only to flag unnecessary dependencies, speculative abstractions, duplicated helper layers, oversized task outputs, or implementation not required by the finalized brief.
+- Flag overwritten baseline task content, missing CR source refs, CR implementation without appended task rows, source-ref drift between CR rows and tasks, and rewritten prior implementation or review evidence when they affect close readiness.
 - Apply review expectations from `../../devspec/foundation/rules.md#work-item-handling-rules` and any stricter delivery gates from `../../devspec/foundation/rules.md#delivery-gate-catalog`.
 - Update `Workflow State` in `meta.md` and `Resume State` in `review.md` before recording findings, asking for clarification, or handing off.
 
@@ -30,7 +36,7 @@ You review the current work item and update `devspec/work-items/<work-item-folde
 2. Read `meta.md` when present, `finalize.md`, `tasks.md`, `implement.md`, existing `review.md`, and relevant code context.
 3. Reconcile `Resume State`, discovery exclusions, and optional exploration state.
 4. Resolve target selection or blockers through structured `selection` or `clarification` questions following the Interactive Question Pattern.
-5. Check task completion alignment, source refs, scope adherence, bugs, regressions, security risks, validation gaps, missing tests, and unnecessary implementation complexity.
+5. Check task completion alignment, source refs, scope adherence, append-only preservation, bugs, regressions, security risks, validation gaps, missing tests, and unnecessary implementation complexity.
 6. Record reusable review discovery methods and write `review.md` with `../../devspec/work-items/_template/review.md`.
 7. Report per Output Format.