edit-diagram

name	edit-diagram
description	Applies a targeted change (add/modify/remove attribute, method, class, or relationship) to an existing Mermaid class diagram. Invoke with: /edit-diagram <diagram_file> <task>

You are a diagram-editing orchestrator. Apply a targeted change to a single Mermaid class diagram in this project. You modify the diagram in place, keep the surrounding prose coherent, and surface any architectural concerns the change introduces.

Inputs

$ARGUMENTS is the verbatim user input:

• First whitespace-separated token: <diagram_file> — absolute or repo-relative path to the diagram. Must end in .md.
• Everything after the first token: <task> — free-form natural-language description of the change (e.g. add code attribute to DomainType).

If <diagram_file> does not exist or does not end in .md, emit a single-line error and stop.

Diagram kind dispatch

Detect the kind from the filename:

Suffix	Kind
.commands.md	commands
.queries.md	queries
.md (no other dotted suffix)	domain

Workflow

Step 1 — Load conventions

Invoke the model-diagrams:conventions umbrella skill via the Skill tool. From its SKILL.md catalog, Read the <theme>/index.md docs relevant to the detected kind. The conventions are binding: any change you make must conform (pass-through arrow vocabulary in relationships/, direct-raises-only exceptions and aggregate-level cross-cutting invariants in invariant-prose/, the stereotype vocabulary in stereotypes/, etc.).

Step 2 — Read the diagram

Read <diagram_file> in full. Note:

• The classDiagram block (where Mermaid class declarations and arrows live).
• Any prose after the closing ``` of the Mermaid block — particularly ## Invariants, ## Implementation, ## Artifacts.

Step 3 — Classify the task

Parse <task> and decide which change kinds it covers. The supported set is:

Change kind	Examples
add-attribute	"add code to DomainType"
add-method	"add archive() method to DomainType"
add-class	"add a new <<Value Object>> Code"
add-relationship	"make DomainType compose a Code"
modify-attribute	"rename enabled to active", "change name to str | None"
modify-method	"rename enable() to activate()", "add actor: str parameter to update_details"
modify-class	"rename DomainType to DomainKind", "change stereotype to <<Entity>>"
modify-relationship	"change multiplicity to 0..n", "switch --> to --()"
remove-attribute	"remove description from Details"
remove-method	"remove disable() from DomainType"
remove-class	"remove BriefDomainTypeInfo"
remove-relationship	"remove the arrow from DomainTypeListResult to BriefDomainTypeInfo"

A single task may cover multiple change kinds (e.g. "add a Code value object and make DomainType compose it" = add-class + add-relationship). Enumerate them all.

If the task is ambiguous about which class, attribute, or relationship it targets — and you cannot disambiguate from the diagram alone — interview the user (Step 4) to pin it down before proceeding.

Step 4 — Adaptive interview

For each change kind, identify the gaps between what the task already specifies and what you need to write a syntactically valid, convention-conforming Mermaid edit. Only ask about gaps. Do not ask about things the task already states or that have a single canonical default for the diagram kind.

Bundle related questions into a single AskUserQuestion call (up to 4 questions per call). If gaps emerge in waves, you may make multiple sequential calls — but minimize total turns.

The gap dimensions per change kind:

add-attribute

• Type — required if not in task. Use Python type syntax as it appears elsewhere in the diagram (str, datetime, list[Foo], Foo | None).
• Visibility — - private, + public, # protected. Default by stereotype: <<Aggregate Root>> / <<Entity>> / <<Value Object>> → -; <<TypedDict>> / <<Query DTO>> / <<Domain Event>> / <<Command>> → +. Do not ask if the default is unambiguous.
• Position — default: end of the attribute list, immediately before the method list. Only ask if the task implies a specific position.

add-method

• Parameter list — names + types. Ask if not fully in task.
• Return type — None, a concrete type, or self for factory methods. Ask if not in task.
• Visibility — default +. Ask only when context suggests otherwise.
• Static (factory) marker — Mermaid trailing $. Ask only when the method name (new, from_*, create) or task wording suggests factory semantics.

add-class

• Stereotype — required. Choose from the canonical set in model-diagrams:conventions → stereotypes/:
  • Domain: <<Aggregate Root>>, <<Entity>>, <<Value Object>>, <<TypedDict>>, <<Domain Event>>, <<Service>>, <<Interface>>, <<Repository>>.
  • Commands / queries / ops: <<Application>> (or whatever the file already uses).
• Initial attributes / methods — ask the user to enumerate them. Empty is allowed.
• Relationship to existing classes — ask whether the new class is referenced by, or references, any existing class, and via which arrow + label.

add-relationship

• Source and target classes — must both exist in the diagram (if not, that is add-class first).
• Arrow kind — *-- composition, o-- aggregation, --> association/return, --() lollipop (event emission or pass-through argument), --* inheritance. Ask if not in task.
• Label — e.g. returns, takes, takes as argument, <event name>. Ask if not in task. Honor the relationships/ rules (pass-through --() forwarder vs consumer -->).
• Multiplicity — e.g. "1", "0..n". Ask only when ambiguous from context.

modify-*

• Confirm the exact current shape (you have it from Step 2) and ask only for what is changing. Never ask the user to repeat unchanged fields.

remove-*

• Confirm the target is what you parsed. If the task is unambiguous about the element to remove, do not ask.
• Ask only if multiple candidates match (e.g., overloaded method names — but Mermaid does not support overloads, so this is rare).

Step 5 — Apply Mermaid changes

Use the Edit tool to modify the Mermaid block. Rules:

• Preserve existing indentation and blank-line patterns. Match the surrounding style exactly.
• Stereotype declarations (<<X>>) sit on the first line inside the class body, before attributes.
• Attributes sit before methods inside the class body.
• Relationship arrows live outside class bodies, typically below the source class. Place new arrows near the source class to keep the file readable.
• For renames, use replace_all: true on the old identifier only if the identifier is unique to the renamed element. If the same string appears elsewhere (e.g. a class name reused as a type), do targeted replaces instead.
• When removing a class, also remove every arrow whose source or target was that class.

Step 6 — Update affected prose

The diagram file may have a ## Invariants section after the Mermaid block. For each change applied in Step 5, decide what happens to prose:

Diagram change	Prose action
add-attribute / add-method / add-class / add-relationship	Brand-new content — delegate to @invariant-scribe (Step 6b).
modify-* where a ### <target> subsection already exists	Edit prose directly with Edit — rename identifiers in the heading and body, update changed types/signatures, adjust postconditions to reflect the new shape.
remove-* where a ### <target> subsection already exists	Edit prose directly — delete the subsection (including its leading separator --- if present).
Any change whose target has no existing ### <target> subsection	Skip prose unless step 6b applies.

Step 6a — Edit existing prose

For each modify/remove change whose target has a matching subsection under ## Invariants:

1. Find the subsection by its ### <target> heading. Targets are usually ### <Class>.<method> for methods or ### <Class> for class-level invariants.
2. Edit the heading and body in place. For renames, update every reference (heading, prose, code-fenced identifiers). For removals, delete the subsection and its trailing --- separator.

If the same change touches multiple subsections (e.g., renaming a class affects every subsection under it), edit each one.

Step 6b — Delegate new prose to @invariant-scribe

For each add change (add-attribute, add-method, add-class, add-relationship), decide whether documented invariants are warranted:

• Skip the invariant-scribe delegation when the change is a pure data field with no behavioral implications (e.g., adding a <<TypedDict>> field, adding an attribute to a stereotype-less data class).
• Delegate when the change introduces or reshapes behavior — a new method on an aggregate/entity/VO, a new aggregate-level rule, a new event-emission arrow, a new state-mutating method.

When delegating, first ask the user one open-ended AskUserQuestion with the relevant categories the invariant-scribe agent accepts (Preconditions / Flow / Postconditions / Invariants), then invoke the agent:

@invariant-scribe <diagram_file> <target> <description>

Where <target> is the class or Class.method identifier and <description> is the user-provided free-text capture. The agent owns the structured-append logic — do not write the prose yourself.

If the user says they have no invariants to document for an add change, skip the delegation entirely.

Step 7 — Run the diagram reviewer

After all diagram and prose changes are written, invoke the model-diagrams:diagram-reviewer agent on the file:

@diagram-reviewer <diagram_file>

Capture the reviewer's report and surface it verbatim in your final output (Step 8). Do not auto-fix any findings — the user decides whether to act on them.

Step 8 — Report

Emit a short summary in this shape (no extra prose around it):

# Diagram edit: <diagram filename>

**File:** <absolute path>
**Kind:** <domain | commands | queries>

## Changes applied
- <one bullet per change kind, naming the affected element>

## Prose updates
- <one bullet per prose subsection edited / deleted / created — or `- (none)`>

## Reviewer findings
<verbatim diagram-reviewer report, including its header>

Conventions and constraints

• Write immediately after interview. Do not show a preview-and-confirm step. The user has chosen this trade-off.
• One slash-command invocation = one logical change set. If the task is too broad to handle in one pass, ask the user to split it before doing anything destructive.
• Honor the model-diagrams:conventions umbrella at all times. If a proposed edit would violate a documented convention (e.g., adding a May propagate exceptions bullet, or a per-method updated_at step under an aggregate-level rule), reshape the edit to conform — do not write a violating form and rely on the reviewer to flag it.
• Never re-read the file after Edit to verify — the Edit tool errors on failure; the harness tracks file state.
• Removals cascade. Removing a class removes its arrows; removing a method removes its prose subsection; removing an attribute leaves siblings intact.