Enhance Mermaid diagram generation and SVG support with guidelines#24
Merged
Conversation
…semantic color coding
…ility in Mermaid diagrams
…al diagram types and improve documentation clarity
…onality and support for mono-repo and multi-repo workspaces. Update agent constraints to include visual quality standards for diagram generation and ensure adherence to naming conventions and exclusion patterns.
…y and ensure adherence to naming conventions and complexity guardrails.
- Updated `/devspec.diagram` command to support SVG output options, allowing users to specify `format=svg` for SVG-only or `format=mermaid+svg` for both Mermaid and SVG outputs. - Revised command registry to reflect the new SVG capabilities for diagram generation. - Enhanced documentation in various files to clarify the use of SVG alongside Mermaid diagrams, including updates to artifact queue, architecture diagrams, and README files. - Introduced a new SVG template for consistent styling and structure in generated diagrams. - Established guidelines for naming and storing SVG images in the architecture/images directory, ensuring clarity and organization. - Updated how temporary work-item diagrams are handled, including SVG storage locations and validation requirements.
…ship classification for SVG files
… files to ensure consistency and improve visual quality. Preserve SVG and Mermaid formats in queue notes, and update documentation to reflect these changes.
… clarifying file handling and distribution details for improved user guidance.
- Introduced separate SVG templates for architecture diagrams and process flows. - Updated documentation to reflect the new template paths and usage guidelines. - Modified tests to validate the new SVG templates and ensure they meet the required standards. - Ensured generated SVGs are standalone and adhere to XML validation rules.
…ssessments - Update prompts and handoffs in `devspec.clarify`, `devspec.finalize`, and `devspec.story` agents to improve user guidance and flow. - Introduce the Readiness Gap Scan Pattern in documentation to standardize readiness assessments before finalization. - Refine `finalize.md` template to ensure readiness gates are populated from the Readiness Gap Scan.
… product context, durable principles, and operational governance
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This pull request updates the devspec agent and skill documentation to clarify command boundaries, multi-repo support, diagram generation rules, and platform compatibility. The changes standardize how each skill describes its workflow, required inputs, and integration with multiple AI agents and repositories. There are also important clarifications on how to handle product context, durable principles, operational rules, and diagram formats across the devspec workflow.
Key changes include:
Skill Documentation and Multi-Repo Support:
.claude/skills/devspec-*/SKILL.mdfiles to clarify support for mono-repo and multi-repo workspaces, and to list compatibility with various AI agents (e.g., Copilot, Claude, OpenAI Codex, Cursor). Each skill now includes step-by-step workflow instructions, emphasizes cross-tool recovery, and documents platform-specific limitations.Diagram Generation and Format Handling:
format=svgandformat=mermaid+svg. SVG output now references specific template files for process-flow and architecture diagrams, and all generated SVGs must meet strict validation and security requirements.Command Boundaries and Routing:
devspec/foundation/project-context.md, durable principles indevspec/constitution.md, and operational rules, compliance, enforcement, and delivery gates indevspec/foundation/rules.md. Each command is now explicitly responsible for only its designated area.Extraction and Diagram Workflow Enhancements:
Platform Compatibility and Recovery:
These changes improve clarity, enforce stricter boundaries between different devspec commands, and ensure consistent behavior and documentation across all supported platforms and repository structures.