diff --git a/plugins/aidd-context/CATALOG.md b/plugins/aidd-context/CATALOG.md index f59d642e..1b8da9b5 100644 --- a/plugins/aidd-context/CATALOG.md +++ b/plugins/aidd-context/CATALOG.md @@ -166,7 +166,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [01-mermaid.md](skills/09-mermaid/actions/01-mermaid.md) | - | | `-` | [README.md](skills/09-mermaid/README.md) | - | | `references` | [mermaid-conventions.md](skills/09-mermaid/references/mermaid-conventions.md) | - | -| `-` | [SKILL.md](skills/09-mermaid/SKILL.md) | `Generate high-quality Mermaid diagrams from markdown content using a structured plan-validate workflow.` | +| `-` | [SKILL.md](skills/09-mermaid/SKILL.md) | `Generate a valid, high-quality Mermaid diagram from a written source through a plan, confirm, generate, review loop. Use when the user wants to turn an architecture, lifecycle, or flow description into a Mermaid diagram, or when another skill needs one. Not for other diagram formats like PlantUML or Graphviz, or for rendering a diagram to an image.` | #### `skills/10-learn` diff --git a/plugins/aidd-context/skills/09-mermaid/README.md b/plugins/aidd-context/skills/09-mermaid/README.md index b79de142..237a3503 100644 --- a/plugins/aidd-context/skills/09-mermaid/README.md +++ b/plugins/aidd-context/skills/09-mermaid/README.md @@ -1,59 +1,29 @@ -← [aidd-framework](../../../../README.md) / [aidd-context](../../README.md) +← [framework](../../../../README.md) / [aidd-context](../../README.md) -# 04 - Mermaid +# 09 - Mermaid -Generates a 100% valid, high-quality Mermaid diagram from a markdown source -through a structured plan-confirm-generate-review loop. Defaults to flow -direction `LR` and targets Mermaid 10.8.0+. +Generates a valid, high-quality Mermaid diagram from a written source through a plan, confirm, generate, review loop. ## When to use -- Turning a written description (architecture, lifecycle, flow) into a - Mermaid diagram. -- Producing a diagram to embed in an `INSTALL.md`, ADR, or memory file. -- Invoked by other aidd-context skills that need a diagram (e.g. - `01-bootstrap` calls this from action 04). +- Turning a written description (architecture, lifecycle, flow) into a Mermaid diagram. +- Producing a diagram to embed in an `INSTALL.md`, a decision record, or a memory file. +- When another skill needs a diagram (for example `01-bootstrap` calls it). -## When NOT to use +## When not to use -- For non-Mermaid diagram formats (PlantUML, Graphviz, draw.io). +- For other diagram formats (PlantUML, Graphviz, draw.io). - To freehand a diagram without a written source to plan from. -- To render or export a diagram to PNG/SVG - this skill produces fenced - Mermaid text only. +- To render or export to an image. This skill produces fenced Mermaid text only. -## How to invoke +## Flow -``` -Use skill aidd-context:09-mermaid -``` +One action with a six-step loop: get the source, plan, confirm the plan, generate, offer a review, review on confirm. The diagram is generated only from the confirmed plan, and never adds an element the user did not confirm. -The skill runs one action with a six-step loop: +## Requires -1. Ask for the document to convert. -2. Plan the diagram (components, parents/children, directions, relations, - labels). -3. Confirm the plan with the user. -4. Generate a 100% valid Mermaid diagram from the confirmed plan. -5. Offer a review. -6. Review on confirm: check syntax, empty/misplaced nodes, and suggest - improvements without adding elements absent from the confirmed plan. +A written source (a paragraph, a list, or a section) describing what to diagram. -## Outputs +## Details -- A fenced ```mermaid block containing a syntactically valid diagram that - parses against Mermaid 10.8.0+. -- An optional review note when the user accepts the review step. - -## Prerequisites - -- A markdown source (paragraph, list, or section) describing what to - diagram. -- Awareness of the project's Mermaid conventions (see - `references/mermaid-conventions.md`). - -## Technical details - -See [`SKILL.md`](SKILL.md) for the entry contract, -[`actions/01-mermaid.md`](actions/01-mermaid.md) for the full process, -and `references/mermaid-conventions.md` for the conventions enforced -during generation. +See [`SKILL.md`](SKILL.md) for the contract, [`actions/01-mermaid.md`](actions/01-mermaid.md) for the process, and [`references/mermaid-conventions.md`](references/mermaid-conventions.md) for the conventions and defaults every diagram follows. diff --git a/plugins/aidd-context/skills/09-mermaid/SKILL.md b/plugins/aidd-context/skills/09-mermaid/SKILL.md index de698fe4..34a35d57 100644 --- a/plugins/aidd-context/skills/09-mermaid/SKILL.md +++ b/plugins/aidd-context/skills/09-mermaid/SKILL.md @@ -1,14 +1,27 @@ --- name: 09-mermaid -description: Generate high-quality Mermaid diagrams from markdown content using a structured plan-validate workflow. +description: Generate a valid, high-quality Mermaid diagram from a written source through a plan, confirm, generate, review loop. Use when the user wants to turn an architecture, lifecycle, or flow description into a Mermaid diagram, or when another skill needs one. Not for other diagram formats like PlantUML or Graphviz, or for rendering a diagram to an image. --- -# Skill: mermaid +# Mermaid -Produces valid, structured Mermaid diagrams through iterative planning and user confirmation. +Produces a valid, structured Mermaid diagram from a written source by planning it, confirming the plan, generating, and offering a review. ## Actions -```markdown -@actions/01-mermaid.md -``` +| # | Action | Role | Input | +| --- | --------- | ------------------------------------------------------ | ---------------- | +| 01 | `mermaid` | Plan, confirm, generate, and review one diagram | a written source | + +Run action `01` and run its `## Test` before trusting the result. + +## Transversal rules + +- Plan before generating, and confirm the plan with the user. Block on the answer. +- Generate only what the confirmed plan holds. Never add a node or a relationship the user did not confirm. +- Follow the project's Mermaid conventions for every diagram. +- Output the diagram as a fenced block, never describe it in prose. + +## References + +- `references/mermaid-conventions.md`: the conventions and defaults every generated diagram follows. diff --git a/plugins/aidd-context/skills/09-mermaid/actions/01-mermaid.md b/plugins/aidd-context/skills/09-mermaid/actions/01-mermaid.md index 4e2ab6a4..bcb94d8f 100644 --- a/plugins/aidd-context/skills/09-mermaid/actions/01-mermaid.md +++ b/plugins/aidd-context/skills/09-mermaid/actions/01-mermaid.md @@ -1,35 +1,24 @@ # 01 - Mermaid -Produce a 100% valid, high-quality Mermaid diagram from a markdown document through a plan-confirm-generate-review loop. +Produce a valid, high-quality Mermaid diagram from a written source through a plan, confirm, generate, review loop. -## Inputs +## Input -```yaml -source: -``` +The written source to diagram: a paragraph, a list, or a section describing an architecture, a lifecycle, or a flow. Ask for it when it is not provided. -## Outputs +## Output -A Mermaid diagram fenced as ```mermaid + an optional review note. On first user message, the action prints the six numbered steps below as short bullets so the user knows what is coming. - -```mermaid - -``` +A Mermaid diagram in a fenced block, plus an optional review note. On the first message, list the steps below as short bullets so the user knows what is coming. ## Process -1. **Ask for the document to convert** when not already provided. -2. **Plan the diagram.** Analyze the source and write down a detailed plan identifying at least: - - Components (main elements, logical groups; use colors). - - Children and parent elements. - - Directions and hierarchies. - - Relationships (colors, connections, dependencies). - - Notes and labels per element when needed. -3. **Confirm the plan.** Ask the user "Do you confirm the plan?" and wait for explicit confirmation. -4. **Generate** the 100% valid Mermaid diagram from the plan. Flow direction defaults to `LR`. Minimum Mermaid version 10.8.0. Apply the conventions in `@../references/mermaid-conventions.md`. -5. **Offer a review.** Ask the user "Do you want me to review it?" and wait for an answer. -6. **Review on confirm.** Check syntax, look for empty or misplaced nodes, suggest improvements. Do NOT add any extra elements that were not in the confirmed plan. +1. **Get the source.** Ask for the document to diagram when it is not already provided. +2. **Plan.** Analyze the source and write a plan that names: the components and their logical groups, the parent and child elements, the directions and the hierarchy, the relationships (connections, dependencies), and the labels or notes each element needs. +3. **Confirm.** Ask the user to confirm the plan. Block on the answer. +4. **Generate.** Produce a valid Mermaid diagram from the confirmed plan, following the conventions and defaults in `@../references/mermaid-conventions.md`. +5. **Offer a review.** Ask whether the user wants a review, and wait. +6. **Review on confirm.** Check the syntax, look for an empty or misplaced node, and suggest improvements. Never add an element that was not in the confirmed plan. ## Test -The generated block is fenced with ```mermaid, parses without error against Mermaid 10.8.0+, follows the conventions in `@../references/mermaid-conventions.md`, and contains no nodes or relationships absent from the user-confirmed plan. +- The diagram is in a fenced Mermaid block, parses without error, follows the conventions reference, and holds no node or relationship absent from the confirmed plan. diff --git a/plugins/aidd-context/skills/09-mermaid/references/mermaid-conventions.md b/plugins/aidd-context/skills/09-mermaid/references/mermaid-conventions.md index 34f06a22..2aa0a037 100644 --- a/plugins/aidd-context/skills/09-mermaid/references/mermaid-conventions.md +++ b/plugins/aidd-context/skills/09-mermaid/references/mermaid-conventions.md @@ -1,45 +1,46 @@ # Mermaid generation rules +The Defaults, Header, Global, Naming, Links, and Styles sections apply to every diagram type. The States and Gantt sections apply only to their own type. For a type with no section here, the global rules still hold and the rest follows standard Mermaid syntax. + +## Defaults + +- Target Mermaid 10.8.0 or newer. +- Flow direction defaults to `LR` unless the source implies another. + ## Header -- Always have title in schema using "---" to define it +- Give the diagram a title through the `---` frontmatter block. ## Global -- NEVER use "\n" -- NEVER use "
" in labels +- Keep a label on one line. A literal `\n` renders as the characters, never use it. Prefer a shorter label over a `
` break. +- Use descriptive names, never `A` or `B`. +- Keep naming consistent across the diagram. ## States and nodes -- Define groups, parents, children -- Use fork and join states -- Use clear and concise names -- Use "choice" for conditions -- No standalone nodes -- No empty nodes +- Define groups, parents, and children where the source has them. +- Use fork and join (`<>`, `<>`) for parallel paths, and choice (`<>`) for a condition. +- No standalone node, no empty node. ## Naming -- Declare elements only (no links) at top -- Consistent naming throughout -- Descriptive names (no "A", "B") -- Node IDs: unquoted alphanumeric (`MyNode`, not `"MyNode"`) -- Labels: in brackets with quotes (`MyNode["My Label"]`) -- Replace ":" with "$" in state names +- Node ids are unquoted alphanumeric (`MyNode`, not `"MyNode"`). +- Labels go in brackets with quotes (`MyNode["My Label"]`). +- Keep `:` out of a state id, it delimits the state's description. Use a clean id and add a description on its own line if needed. ## Links -- Links made at bottom of diagram -- Use direction when possible -- "A -- text --> B" for regular links -- "A -.-> B" for conditional links -- "A ==> B" for self-loops +- Declare the elements first, then the links. +- Give the link a direction. +- `A -- text --> B` for a labeled link. +- `A -.-> B` for a dashed link, for example a conditional or optional path. +- `A ==> B` for a thick link, to emphasize a path. A self-loop is `A --> A`. ## Styles -- Do style unless specified by user +- Do not add styling unless the user asks for it. ## Gantt -- Use tags: `active`, `done`, `crit`, `milestone` -- Tags are combinable +- Use the tags `active`, `done`, `crit`, `milestone`. They combine.