devspec 0.1.1__tar.gz → 0.1.3__tar.gz

{devspec-0.1.1 → devspec-0.1.3}/.agents/rules/devspec-workflow.md

@@ -16,7 +16,9 @@ Follow these rules:
 - 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.
 - 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 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.1.3/.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.1 → devspec-0.1.3}/.agents/skills/devspec-extract.md

@@ -7,6 +7,8 @@ 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 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.1.1 → devspec-0.1.3}/.agents/skills/devspec-projectcontext.md

@@ -7,6 +7,7 @@ Execute canonical command `/devspec.projectcontext`.
 
 - Read `devspec/adapters/command-registry.md` for the command contract.
 - Read `.github/prompts/devspec.projectcontext.prompt.md` and `.github/agents/devspec.projectcontext.agent.md` as the source of intent.
+- Keep this command focused on product context; route durable principles to `devspec/constitution.md` and operational governance or delivery gates to `devspec/foundation/rules.md`.
 - 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.1.1 → devspec-0.1.3}/.agents/skills/devspec-rules.md

@@ -7,6 +7,7 @@ Execute canonical command `/devspec.rules`.
 
 - Read `devspec/adapters/command-registry.md` for the command contract.
 - Read `.github/prompts/devspec.rules.prompt.md` and `.github/agents/devspec.rules.agent.md` as the source of intent.
+- Keep this command focused on operational rules, compliance requirements, enforcement details, delivery gates, exceptions, and evolving governance; do not duplicate durable principles from `devspec/constitution.md` or product intent from `devspec/foundation/project-context.md`.
 - 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.1.3/.claude/skills/devspec-clarify/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: devspec-clarify
+description: Run /devspec.clarify using the canonical devspec command registry. Supports mono-repo and multi-repo workspaces. Works across GitHub Copilot, Claude Code, OpenAI Codex, Cursor, and other AI agents.
+---
+
+Execute canonical command `/devspec.clarify`.
+
+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.clarify.prompt.md` and `.github/agents/devspec.clarify.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.
+5. Honor multi-repo boundaries: when `devspec/foundation/codebase-structure.md` records multiple repositories, every task, artifact, and access requirement must name the target repository.
+
+Command input comes from the user's current message.
+
+Platform note: Claude Code may not register `/devspec.clarify` as a native slash command. Treat the command name as workflow intent and use this skill as the invocation mechanism. Record any unsupported behavior in `devspec/adapters/compatibility-matrix.md`.

devspec-0.1.3/.claude/skills/devspec-codebase-structure/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: devspec-codebase-structure
+description: Run /devspec.codebase-structure using the canonical devspec command registry. Supports mono-repo and multi-repo workspaces. Works across GitHub Copilot, Claude Code, OpenAI Codex, Cursor, and other AI agents.
+---
+
+Execute canonical command `/devspec.codebase-structure`.
+
+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.codebase-structure.prompt.md` and `.github/agents/devspec.codebase-structure.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.
+5. Honor multi-repo boundaries: when recording multiple repositories, capture per-repo work areas, boundaries, integration contracts, and access requirements as separate entries in `devspec/foundation/codebase-structure.md`.
+
+Command input comes from the user's current message.
+
+Platform note: Claude Code may not register `/devspec.codebase-structure` as a native slash command. Treat the command name as workflow intent and use this skill as the invocation mechanism. Record any unsupported behavior in `devspec/adapters/compatibility-matrix.md`.

devspec-0.1.3/.claude/skills/devspec-coding-standards/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: devspec-coding-standards
+description: Run /devspec.coding-standards using the canonical devspec command registry. Supports mono-repo and multi-repo workspaces. Works across GitHub Copilot, Claude Code, OpenAI Codex, Cursor, and other AI agents.
+---
+
+Execute canonical command `/devspec.coding-standards`.
+
+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.coding-standards.prompt.md` and `.github/agents/devspec.coding-standards.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.
+5. Honor multi-repo boundaries: when `devspec/foundation/codebase-structure.md` records multiple repositories, every task, artifact, and access requirement must name the target repository.
+
+Command input comes from the user's current message.
+
+Platform note: Claude Code may not register `/devspec.coding-standards` as a native slash command. Treat the command name as workflow intent and use this skill as the invocation mechanism. Record any unsupported behavior in `devspec/adapters/compatibility-matrix.md`.

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

@@ -0,0 +1,19 @@
+---
+name: devspec-diagram
+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`.
+
+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.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 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.
+
+Command input comes from the user's current message.
+
+Platform note: Claude Code may not register `/devspec.diagram` as a native slash command. Treat the command name as workflow intent and use this skill as the invocation mechanism. Record any unsupported behavior in `devspec/adapters/compatibility-matrix.md`.

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

@@ -0,0 +1,17 @@
+---
+name: devspec-extract
+description: Run /devspec.extract using the canonical devspec command registry. Backfills foundation and architecture artifacts from local paths, GitHub, Azure DevOps, GitLab, or named multi-repo sources. Works across GitHub Copilot, Claude Code, OpenAI Codex, Cursor, and other AI agents.
+---
+
+Execute canonical command `/devspec.extract`.
+
+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.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 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.
+
+Platform note: Claude Code may not register `/devspec.extract` as a native slash command. Treat the command name as workflow intent and use this skill as the invocation mechanism. Record any unsupported behavior in `devspec/adapters/compatibility-matrix.md`.

devspec-0.1.3/.claude/skills/devspec-finalize/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: devspec-finalize
+description: Run /devspec.finalize using the canonical devspec command registry. Supports mono-repo and multi-repo workspaces. Works across GitHub Copilot, Claude Code, OpenAI Codex, Cursor, and other AI agents.
+---
+
+Execute canonical command `/devspec.finalize`.
+
+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.finalize.prompt.md` and `.github/agents/devspec.finalize.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.
+5. Honor multi-repo boundaries: when `devspec/foundation/codebase-structure.md` records multiple repositories, every task, artifact, and access requirement must name the target repository.
+
+Command input comes from the user's current message.
+
+Platform note: Claude Code may not register `/devspec.finalize` as a native slash command. Treat the command name as workflow intent and use this skill as the invocation mechanism. Record any unsupported behavior in `devspec/adapters/compatibility-matrix.md`.

devspec-0.1.3/.claude/skills/devspec-implement/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: devspec-implement
+description: Run /devspec.implement using the canonical devspec command registry. The only code-write command - edits target repository code when the upstream work item and repository access allow it. Supports mono-repo and multi-repo workspaces. Works across GitHub Copilot, Claude Code, OpenAI Codex, Cursor, and other AI agents.
+---
+
+Execute canonical command `/devspec.implement`.
+
+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 (`code-write`), and next handoff.
+3. Read `.github/prompts/devspec.implement.prompt.md` and `.github/agents/devspec.implement-task.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.
+5. Honor multi-repo boundaries: when `devspec/foundation/codebase-structure.md` records multiple repositories, every implementation task must name the target repository and required access level before writing any code.
+
+Command input comes from the user's current message.
+
+Platform note: Claude Code may not register `/devspec.implement` as a native slash command. Treat the command name as workflow intent and use this skill as the invocation mechanism. This command requires `code-write` access - confirm repository permissions before proceeding. Record any unsupported behavior in `devspec/adapters/compatibility-matrix.md`.

devspec-0.1.3/.claude/skills/devspec-projectcontext/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: devspec-projectcontext
+description: Run /devspec.projectcontext using the canonical devspec command registry. Supports mono-repo and multi-repo workspaces. Works across GitHub Copilot, Claude Code, OpenAI Codex, Cursor, and other AI agents.
+---
+
+Execute canonical command `/devspec.projectcontext`.
+
+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.projectcontext.prompt.md` and `.github/agents/devspec.projectcontext.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.
+5. Honor multi-repo boundaries: when `devspec/foundation/codebase-structure.md` records multiple repositories, every task, artifact, and access requirement must name the target repository.
+
+Command input comes from the user's current message.
+
+Platform note: Claude Code may not register `/devspec.projectcontext` as a native slash command. Treat the command name as workflow intent and use this skill as the invocation mechanism. Record any unsupported behavior in `devspec/adapters/compatibility-matrix.md`.

devspec-0.1.3/.claude/skills/devspec-review/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: devspec-review
+description: Run /devspec.review using the canonical devspec command registry. Reviews implemented work for bugs, regressions, scope drift, security risks, and validation gaps. Supports mono-repo and multi-repo workspaces. Works across GitHub Copilot, Claude Code, OpenAI Codex, Cursor, and other AI agents.
+---
+
+Execute canonical command `/devspec.review`.
+
+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 (`review-write`), and next handoff.
+3. Read `.github/prompts/devspec.review.prompt.md` and `.github/agents/devspec.review.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.
+5. Honor multi-repo boundaries: when `devspec/foundation/codebase-structure.md` records multiple repositories, every task, artifact, and access requirement must name the target repository.
+
+Command input comes from the user's current message.
+
+Platform note: Claude Code may not register `/devspec.review` as a native slash command. Treat the command name as workflow intent and use this skill as the invocation mechanism. This command has `review-write` mutation level - it writes review artifacts only and must not change implementation code. Record any unsupported behavior in `devspec/adapters/compatibility-matrix.md`.

devspec-0.1.3/.claude/skills/devspec-rules/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: devspec-rules
+description: Run /devspec.rules using the canonical devspec command registry. Supports mono-repo and multi-repo workspaces. Works across GitHub Copilot, Claude Code, OpenAI Codex, Cursor, and other AI agents.
+---
+
+Execute canonical command `/devspec.rules`.
+
+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.rules.prompt.md` and `.github/agents/devspec.rules.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.
+5. Honor multi-repo boundaries: when `devspec/foundation/codebase-structure.md` records multiple repositories, every task, artifact, and access requirement must name the target repository.
+
+Command input comes from the user's current message.
+
+Platform note: Claude Code may not register `/devspec.rules` as a native slash command. Treat the command name as workflow intent and use this skill as the invocation mechanism. Record any unsupported behavior in `devspec/adapters/compatibility-matrix.md`.

devspec-0.1.3/.claude/skills/devspec-story/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: devspec-story
+description: Run /devspec.story using the canonical devspec command registry. Creates or updates a work item from a GitHub, Azure DevOps, Jira, or GitLab URL, identifier, or manual intake. Supports mono-repo and multi-repo workspaces. Works across GitHub Copilot, Claude Code, OpenAI Codex, Cursor, and other AI agents.
+---
+
+Execute canonical command `/devspec.story`.
+
+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.story.prompt.md` and `.github/agents/devspec.story.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.
+5. Honor multi-repo boundaries: when `devspec/foundation/codebase-structure.md` records multiple repositories, every task, artifact, and access requirement must name the target repository.
+
+Command input comes from the user's current message.
+
+Platform note: Claude Code may not register `/devspec.story` as a native slash command. Treat the command name as workflow intent and use this skill as the invocation mechanism. Record any unsupported behavior in `devspec/adapters/compatibility-matrix.md`.

devspec-0.1.3/.claude/skills/devspec-tasks/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: devspec-tasks
+description: Run /devspec.tasks using the canonical devspec command registry. Breaks a ready finalized brief into ordered executable implementation tasks. Supports mono-repo and multi-repo workspaces. Works across GitHub Copilot, Claude Code, OpenAI Codex, Cursor, and other AI agents.
+---
+
+Execute canonical command `/devspec.tasks`.
+
+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.tasks.prompt.md` and `.github/agents/devspec.tasks.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.
+5. Honor multi-repo boundaries: when `devspec/foundation/codebase-structure.md` records multiple repositories, every task must name its target repository and required access level before any implementation step.
+
+Command input comes from the user's current message.
+
+Platform note: Claude Code may not register `/devspec.tasks` as a native slash command. Treat the command name as workflow intent and use this skill as the invocation mechanism. Record any unsupported behavior in `devspec/adapters/compatibility-matrix.md`.

devspec-0.1.3/.claude/skills/devspec-techstack/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: devspec-techstack
+description: Run /devspec.techstack using the canonical devspec command registry. Supports mono-repo and multi-repo workspaces. Works across GitHub Copilot, Claude Code, OpenAI Codex, Cursor, and other AI agents.
+---
+
+Execute canonical command `/devspec.techstack`.
+
+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.techstack.prompt.md` and `.github/agents/devspec.techstack.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.
+5. Honor multi-repo boundaries: when `devspec/foundation/codebase-structure.md` records multiple repositories, every task, artifact, and access requirement must name the target repository.
+
+Command input comes from the user's current message.
+
+Platform note: Claude Code may not register `/devspec.techstack` as a native slash command. Treat the command name as workflow intent and use this skill as the invocation mechanism. Record any unsupported behavior in `devspec/adapters/compatibility-matrix.md`.

{devspec-0.1.1 → devspec-0.1.3}/.cursor/rules/devspec-workflow.mdc

@@ -18,6 +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 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.1.1 → devspec-0.1.3}/.gemini/commands/devspec/diagram.toml

@@ -8,7 +8,9 @@ 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. Treat Gemini-specific command syntax as platform mechanics, not a workflow change.
+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.
 
 The user's raw command input, if any, is appended below these instructions by Gemini CLI.
 """

{devspec-0.1.1 → devspec-0.1.3}/.gemini/commands/devspec/extract.toml

@@ -8,7 +8,8 @@ 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. Treat Gemini-specific command syntax as platform mechanics, not a workflow change.
+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.1.3/.github/agents/devspec.clarify.agent.md

@@ -0,0 +1,45 @@
+---
+name: "devspec.clarify"
+description: "Use to ask, resolve, and record one active blocking clarification at a time for the current devspec work item."
+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: Back to Work-Item Intake
+    agent: devspec.story
+    prompt: Revise work-item intake from this clarification.
+  - label: Continue to Finalize
+    agent: devspec.finalize
+    prompt: Create or update the implementation readiness brief.
+---
+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), [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.story`.
+- 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`.
+- 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.
+- If no blocking question remains, set `Pending user question` to `none` and record the next handoff in `Next required action`; return to `/devspec.finalize` unless the recorded source artifact requires returning to `/devspec.story`.
+
+## Approach
+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. Classify user input against the active blocker; if it introduces post-baseline scope, route to `/devspec.story`, 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.
+
+## Output Format
+- Work-item path updated
+- Blocking question or recorded answer
+- Impact and next step
+- Single registered command, handoff, file update, or structured question

devspec-0.1.3/.github/agents/devspec.diagram.agent.md

@@ -0,0 +1,90 @@
+---
+name: "devspec.diagram"
+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
+agents: [Explore]
+handoffs:
+  - label: Continue to Work-Item Intake
+    agent: devspec.story
+    prompt: Start or update a related devspec work item.
+  - label: Continue to Tasks
+    agent: devspec.tasks
+    prompt: Create or update related implementation tasks.
+---
+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), [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.
+- 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 `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.
+- Keep generated Mermaid concise: no `\n` or `<br>` line breaks in node or edge labels; put interaction context on 2-3 word edge labels.
+- Keep architectural flowcharts focused on one primary domain at a macro level, structurally unidirectional, and adjacent by layer. Do not include overloaded graphs, cross-layer arrows, decision diamonds, if/else paths, validation loops, error branches, UI micro-interactions, HTTP return codes, validation exceptions, or database error returns unless the user explicitly requests an algorithm or activity flowchart.
+- Use `sequenceDiagram` when exact step-by-step request and response behavior is required. Show messages only between distinct participants, default to the happy path, collapse pass-through API client helpers, and label messages with actual method names rather than paragraphs.
+- 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", 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/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, 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/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/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, 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 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 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
+- Diagram scope, diagram type, output format, Mermaid declaration when present, and SVG target when present
+- Confidence
+- Queue status
+- Tags
+- Evidence and assumptions
+- Blockers
+- Updated files
+- Single registered command, handoff, file update, or structured question

{devspec-0.1.1 → devspec-0.1.3}/.github/agents/devspec.extract.agent.md

@@ -13,7 +13,7 @@ handoffs:
 You create or refresh devspec extraction artifacts from supported repository sources.
 
 ## 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), [Mermaid Internal Naming and Readability Pattern](../prompts/PATTERNS.md#mermaid-internal-naming-and-readability-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), [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`.
@@ -30,8 +30,10 @@ You create or refresh devspec extraction artifacts from supported repository sou
 - Seed foundation artifacts with developer-useful records, not general theory: each item must name the applicable scope, source evidence, confidence, and the required action, handling, guidance, or blocker it creates.
 - Prefer summary and comparison tables for extracted stack, layout, boundary, standards, rule, and blocker details; use bullets only for short direct facts.
 - Omit optional foundation sections that have no extracted, confirmed, inferred, or blocked content.
-- Never write final `devspec/constitution.md` changes without structured confirmation; only update `Durable Principles` or `Amendment Policy`, and route operational gates or evolving rules to `devspec/foundation/rules.md`.
-- Maintain a single active confirmation gate; do not ask constitution, process-flow candidate, diagram candidate, Mermaid generation, coding-standards conflict, or repository-access confirmations in the same response.
+- Never write final `devspec/constitution.md` changes without structured confirmation; only update `Durable Principles`, `Amendment Policy`, or `Amendment Review`, and route operational gates, compliance procedures, enforcement details, or evolving governance requirements to `devspec/foundation/rules.md`.
+- Treat extracted constitution items as candidates until confirmed by the user. Do not infer principle changes from code evidence alone, and preserve existing principles unless the user explicitly confirms replacement or removal.
+- 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.
 - Create or update `devspec/foundation/extraction-state.md` from `devspec/foundation/_template/extraction-state.md` when extraction starts and is not canceled.
@@ -39,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.
+- 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 Mermaid 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.
+- 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>` and target `devspec/architecture/diagrams/dia-001-<diagram-name>.md`. 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 Mermaid family. Record suggested Mermaid declarations such as `flowchart LR`, `flowchart TD`, or `sequenceDiagram` in `Next action or notes` when orientation will help `/devspec.diagram`.
-- When queueing process-flow or diagram candidates, record that future generation must follow `PATTERNS.md#mermaid-internal-naming-and-readability-pattern`, including short node IDs, concise node and edge labels, single-concern scope, adjacent layering, implied returns, sequence happy paths, runtime/compile-time separation, system boundaries, and anti-bloat rules for API, Swagger, payload, and framework boilerplate details.
-- Ask one structured `approval` question before generating diagrams during extraction. Generate at most one confirmed diagram 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.
+- 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`.
@@ -72,9 +74,9 @@ 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, Mermaid declaration guidance, and Mermaid internal naming guidance.
-10. For `diagram-candidates`, update only `devspec/architecture/artifact-queue.md`; include Mermaid internal naming guidance in queue notes and generate diagrams only through confirmed continuation or `/devspec.diagram`.
-11. For `constitution-candidates`, ask before writing principle-level changes.
+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.