菜单
Surgically updates the messaging consumer input specs (`<stem>.messaging/<consumer>.md`) after a domain or commands-diagram change. Invoke with: /messaging-spec:update-specs <domain_diagram>
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Umbrella catalog of the project's Mermaid class-diagram conventions (domain, commands, queries, ops kinds), organized by theme. Each theme lives in a sibling folder's index.md. Load when AUTHORING, editing, or REVIEWING a diagram in this project — the docs give the canonical authoring rule and the matching review lens (what is canonical and must not be flagged).
Umbrella catalog of all rest-api-spec pattern references. Each pattern lives in a sibling folder of this file — `<pattern-name>/` containing `index.md` (the pattern doc) plus an optional `examples.md` companion. Load to resolve pattern names to their reference docs by path instead of per-pattern skill invocations.
Initializes the project-wide application-layer scaffolding (project package discovery, src/<pkg>/application/, src/<pkg>/infrastructure/, src/<pkg>/infrastructure/services/, src/tests/fakes/, and a minimal src/tests/conftest.py). Invoke with: /application-spec:init-application
Initializes the project-wide domain scaffolding (project package discovery, src/<pkg>/domain/ with shared/, src/tests/ with conftest and unit/). Aggregate-agnostic — run once per project before any @domain-spec:code-generator invocation. Invoke with: /init-domain
Initializes the project-wide messaging scaffolding (project package discovery, src/<pkg>/messaging/ as an empty aggregator package, and a canonical Click __main__.py skeleton). Invoke with: /messaging-spec:init-messaging
Initializes the project-wide persistence scaffolding. Invoke with: /init-persistence
| name | update-specs |
| description | Surgically updates the messaging consumer input specs (`<stem>.messaging/<consumer>.md`) after a domain or commands-diagram change. Invoke with: /messaging-spec:update-specs <domain_diagram> |
| argument-hint | <domain_diagram> |
| allowed-tools | Read, Bash, Agent |
You are a messaging consumer-spec update orchestrator. Given a domain diagram and its sibling commands application-service diagram, refresh the existing per-consumer specs under <dir>/<stem>.messaging/ in place — for every consumer whose internal Table 2 subscriptions intersect a changed domain event, or whose %% Messaging - <consumer> block rows / bound handler signatures / referenced external event classes changed in the commands diagram, re-run event-tables-writer then event-fields-writer to regenerate Tables 2–3 from the current diagrams; for every consumer that subscribes (as internal) to a domain event that was removed or renamed and the corresponding %% Messaging row was not also dropped from the commands diagram, abort that consumer with reconcile instructions and skip it; then emit <dir>/<stem>.messaging/updates.md. Do not rerun the full @messaging-spec:code-generator pipeline, do not touch the diagram files, and do not ask for confirmation before writing.
This skill is the messaging-side counterpart to /update-specs (domain), /persistence-spec:update-specs, /application-spec:update-specs, and /rest-api-spec:update-specs. Design rationale lives in notes/spec-updater-approach.md, notes/update-types.md, notes/updates-report.md, and notes/commands-queries-integration-approach.md; the load-bearing idea is a thin multi-axis dispatcher, not a surgical splicer — every consumer-spec table is a pure snapshot, fully regeneratable from the diagrams, so "update Table 3 for consumer C" is "re-run event-fields-writer <commands_diagram> C". There are no new agents — this skill orchestrates the two existing writers (event-tables-writer, event-fields-writer) plus the existing messaging-updates-writer, and consumes the cross-plugin application-spec:commands-updates-detector and application-spec:ops-updates-detector reports.
The orchestrator consumes three update reports — one per axis — and unions their dispatch signals:
<dir>/<stem>.domain/updates.md, produced by domain-spec:updates-detector (expected on disk; not invoked here).<dir>/<stem>.application/commands-updates.md, produced by application-spec:commands-updates-detector (invoked at Step 0 below). The path is owned by application-spec's per-aggregate folder; messaging-spec reads it but never writes there. See spec-core:naming-conventions for the cross-plugin path policy.<dir>/<stem>.application/ops-updates.md, produced by application-spec:ops-updates-detector (invoked at Step 0 below). A consumer's handler bindings may now live in a %% Messaging - <consumer> block inside an ops diagram (<stem>.ops.<op-name>.md), and an ops method may change signature — both ripple into Table 2/3 exactly as commands-diagram deltas do. The ops report is one aggregate-wide file covering every ops diagram; messaging reads it but never writes there. Schema owned by spec-core:update-reports (ops schema).The queries-diagram axis is not consumed — messaging is command-side only, and there is no per-consumer subscription to query-side operations.
The orchestrator never re-diffs any diagram itself.
Per spec-core:naming-conventions, given <domain_diagram> at <dir>/<stem>.md:
<dir> = directory containing the diagrams.<stem> = the canonical aggregate stem (domain filename with .md stripped); must satisfy ^[a-z][a-z0-9-]*$.<plugin_dir> = <dir>/<stem>.messaging — the per-plugin folder for messaging-spec.<commands_diagram> = <dir>/<stem>.commands.md — passed to the writer agents.| File | Role | Touched by |
|---|---|---|
<dir>/<stem>.domain/updates.md | input — domain delta report (must already exist) | not modified |
<dir>/<stem>.commands.md | input — hand-authored commands diagram (must already exist) | not modified |
<dir>/<stem>.application/commands-updates.md | input — commands-diagram delta report | produced by application-spec:commands-updates-detector at Step 0 |
<dir>/<stem>.application/ops-updates.md | input — ops-diagram delta report | produced by application-spec:ops-updates-detector at Step 0 |
<plugin_dir>/<consumer>.md × N | the consumer specs being updated (at least one must exist) | event-tables-writer + event-fields-writer (per affected consumer) |
<plugin_dir>/updates.md | output — messaging delta report | messaging-updates-writer |
Every agent derives <dir> / <stem> from the path it receives per spec-core:naming-conventions. The writer agents (event-tables-writer, event-fields-writer) take <commands_diagram> <consumer_name>; messaging-updates-writer and application-spec:commands-updates-detector take <domain_diagram> (= $ARGUMENTS[0]). Reconstruction by string substitution is forbidden — recover <dir> / <stem> per the naming-conventions recovery rule, then build sibling paths from it.
This skill keeps no runtime state between agents. messaging-updates-writer recovers the pre-update consumer specs via git show HEAD:<file> per consumer and recomputes the per-consumer abort list itself from the domain updates.md ∩ each consumer's internal Table 2 rows — the same derivation this orchestrator uses in Step 3, with the same inputs and rule — so there is nothing for the orchestrator to capture or hand along.
Derive <dir> and <stem> from $ARGUMENTS[0] per spec-core:naming-conventions. <stem> must satisfy ^[a-z][a-z0-9-]*$; if not, hard-fail with: ERROR: <domain_diagram> path does not yield a valid aggregate stem (must match ^[a-z][a-z0-9-]*$). Using Bash (test -f, ls):
0a. If <dir>/<stem>.domain/updates.md is missing → hard-fail:
ERROR: <dir>/<stem>.domain/updates.md not found. The messaging updater consumes the domain
updates report; it is not the first-run pipeline. Run `/update-specs <domain_diagram>` (or
`@updates-detector <domain_diagram>`) first, or run `@messaging-spec:code-generator <domain_diagram> <consumer_name>`
per consumer to regenerate the consumer specs and code from scratch.
0b. If <dir>/<stem>.commands.md is missing → hard-fail:
ERROR: <dir>/<stem>.commands.md not found. The commands application-service diagram is a required
hand-authored input — `event-tables-writer`, `event-fields-writer`, and `application-spec:commands-updates-detector`
all read it. Restore the file, or run `@messaging-spec:code-generator <domain_diagram> <consumer_name>` per consumer
after authoring it.
0c. Enumerate consumer specs: every <dir>/<stem>.messaging/*.md except updates.md (ls "<dir>/<stem>.messaging"/*.md 2>/dev/null, drop updates.md). If <dir>/<stem>.messaging/ is absent or yields zero consumer specs → true no-op: print
No messaging consumer specs under <stem>.messaging/ — nothing to update.
and exit (success). Do not create the folder, do not invoke any agent, do not write updates.md — there is no consumer spec to update and no report to refresh. (This is the file-presence gate that makes the skill safe to wire unconditionally into the tail of domain /update-specs.) X1 (consumer added — %% Messaging - <C> block declared on the commands diagram but no consumer spec on disk) is handled later, in Step 7, as a WARNING: routing the operator to @messaging-spec:code-generator; this skill never invokes consumer-spec-initializer or consumer-scaffolder for an X1 consumer. The Step 0c exit therefore fires only when the per-aggregate <stem>.messaging/ folder is entirely empty (or absent).
Do not synthesize any input file.
--detectors-fresh is set)Cascade-mode shortcut. If $ARGUMENTS contains the literal token --detectors-fresh (the /spec-core:update-specs orchestrator passes it as the second positional arg when it runs the rest-api/messaging wave after the application wave, whose Step 0g already produced the commands-axis report), the application-spec commands detector report is already on disk and byte-stable. In that case:
Bash:
test -f "<dir>/<stem>.application/commands-updates.md"
ERROR: --detectors-fresh was passed but <dir>/<stem>.application/commands-updates.md does
not exist. The caller is contractually required to produce the commands-axis report before
invoking /messaging-spec:update-specs in cascade mode. Drop the --detectors-fresh flag to
let this skill produce the report itself, or run `/spec-core:update-specs <domain_diagram>`
(which runs the application wave first, then this skill with the flag) — or
`/application-spec:update-specs <domain_diagram>` to produce it.
(The queries-axis report — <stem>.application/queries-updates.md — is also produced by application's Step 0g alongside the commands report, but messaging never reads it, so its presence is not checked here.)
Standalone invocations (without --detectors-fresh) take the default path below.
Default path. After 0a–0c pass, invoke application-spec:commands-updates-detector with prompt $ARGUMENTS[0] (the domain diagram path — the detector derives the sibling commands diagram via spec-core:naming-conventions).
The detector writes <dir>/<stem>.application/commands-updates.md or hard-fails with an ERROR: line. If it hard-fails, abort the orchestrator with that detector's ERROR: line repeated verbatim; the operator's recovery path (the message itself directs to @application-spec:specs-generator <domain_diagram>) applies here.
Wait for the detector to return successfully before proceeding to the ops detector below.
The queries detector is irrelevant to messaging (no per-consumer subscription is driven by query-side operations) and would be wasted work.
--detectors-fresh)Invoke application-spec:ops-updates-detector with prompt $ARGUMENTS[0]. This runs on both the default and the cascade (--detectors-fresh) paths, because --detectors-fresh is the application-spec orchestrator's promise that it produced the commands/queries axis reports — it does not produce the ops report, so messaging produces it here regardless. The detector is cheap to re-run (it fast-paths on a combined-digest match when no ops diagram changed) and is a true no-op (writes _None_) when the aggregate has zero ops diagrams.
The detector writes <dir>/<stem>.application/ops-updates.md or hard-fails with an ERROR: line. If it hard-fails, abort the orchestrator with that ERROR: line repeated verbatim. Wait for it to return successfully before proceeding to Step 1.
Read both reports — <dir>/<stem>.domain/updates.md and <dir>/<stem>.application/commands-updates.md. They are the orchestrator's single source of truth for this step — do not re-derive anything from any diagram. Use Bash (grep) and Read to extract, per axis:
Domain axis (from <stem>.domain/updates.md; the exact bullet formats are owned by spec-core:update-reports (domain schema)):
domain.degraded_baseline — whether the ## Summary block contains a line beginning _warning: HEAD .domain.stereotype_changed — class names listed under ## Class Lifecycle → Stereotype Changed (one bullet per class). Empty when the heading is absent or its body is _None._-style.domain.removed_classes — bullets under ## Class Lifecycle → Removed, each - `ClassName` `<<Stereotype>>`; capture (class_name, stereotype) per bullet.domain.added_classes — bullets under ## Class Lifecycle → Added, each - `ClassName` `<<Stereotype>>` (the — <N> attributes, <N> methods suffix is informational; ignore for dispatch); capture (class_name, stereotype) per bullet.domain.event_attr_deltas — for each ### -style class block under ## Per-Class Changes whose stereotype string contains Event (<<Event>> / <<Domain Event>>), the set of attributes its **Members:** bullets report as Attribute added: / Attribute removed:. Ignore Attribute changed: (a retype is byte-neutral for Table 3, which records names not types) and all method bullets.domain.removed_or_renamed_events — <<Event>> / <<Domain Event>> names in domain.removed_classes (a domain-event rename is reported as removed (old) + added (new), so the old name lands here); plus, best-effort, any <Old> from a : emits <Old> → : emits <New> label-rename line anywhere in the report.domain.added_events — <<Event>> / <<Domain Event>> names in domain.added_classes.domain.aggregate_root_touched — true iff a <<Aggregate Root>>-stereotyped class appears in domain.removed_classes, or in domain.stereotype_changed (either bucket), or in both domain.removed_classes and domain.added_classes (a rename).domain.affected_categories — bullets under ## Affected Categories, in the order they appear (a _None._ body means empty); used only to colour the no-op message.domain.orphan_prose — whether ## Orphan Prose Changes is present with a non-empty body (the synthetic ### Preamble block counts); used only to colour the no-op message.Commands-diagram axis (from <stem>.application/commands-updates.md; the exact bullet formats are owned by spec-core:update-reports (application-axis schema)):
commands.degraded_baseline — whether the ## Summary block contains a line beginning _warning: HEAD .commands.affected_categories — bullets under ## Affected Categories, in the order they appear. The literal body _None._ means empty.commands.messaging_markers — for each ### <consumer-name>-style block under ## Messaging Markers, capture the consumer name and its per-row deltas: row_added / row_removed / row_changed lines, plus the (consumer added) / (consumer removed) suffix on the heading. Each block becomes one entry { consumer, status ∈ {added, removed, modified}, rows_added, rows_removed, rows_changed }.commands.external_event_changes — for each ### -style block under ## External Domain Events, the event-class name and whether its **Members:** block has any Attribute added: / Attribute removed: / Attribute changed: bullets. Plus the names listed under ## Class Lifecycle → Added / → Removed whose stereotype is <<Domain Event>>.commands.changed_methods — for each ### <method>-style block under ## Per-Method Changes, the method name and whether its **Signature:**, **Surface:**, **Messaging:**, or **Prose — ...** sub-section is present. We dispatch on the presence of a **Signature:** change (the only sub-section that affects an on_<event> handler's Table 3).Ops-diagram axis (Read <stem>.application/ops-updates.md; the exact formats are owned by spec-core:update-reports (ops schema)). Unlike the commands report's flat ## Messaging Markers / ## Per-Method Changes sections, the ops report wraps everything in one ## Service: \`block per touched ops service, with### Messaging Markersand### Per-Method Changes nested **one heading level deeper** (#### and#### ``respectively). Extract, unioned across **all**## Service:` blocks:
ops.degraded_baseline — whether the ## Summary block contains a line beginning _warning: HEAD .ops.affected_categories — bullets under ## Affected Categories, in order. The literal body _None._ means empty.ops.messaging_markers — for each #### <consumer-name>-style block under any service's ### Messaging Markers, capture the consumer name and its per-row deltas (row_added / row_removed / row_changed, plus the (consumer added) / (consumer removed) heading suffix). Each block becomes one entry { consumer, status ∈ {added, removed, modified}, rows_added, rows_removed, rows_changed }. When the same consumer appears under more than one service's Messaging Markers (a consumer that binds methods on two ops services), merge the entries: union the row sets and treat the status as modified unless every contributing block is added (then added) or every is removed (then removed).ops.changed_methods — for each #### \`-style block under any service's ### Per-Method ChangeswhoseSignature:sub-section is present (a signature change), capture the method name. These drive the M4-analog dispatch (an ops handler whose method signature changed needs its Table 3 regenerated). Ops methods are free-named (noton_), so the match against a consumer's Command Methodcolumn is by exact method name, not by theon_` convention.The ops report's own structural hard-fails (ops service class renamed, multi-anchor) abort the detector at Step 0d-ops and surface verbatim — they never reach this step. The orchestrator sees a _warning:_ on the ops axis only when an ops diagram's HEAD baseline was degraded.
The structural hard-fails the commands detector itself enforces (anchor missing/renamed, multi-anchor, stereotype change inside the commands diagram) never reach the orchestrator — the detector aborts at Step 0d and the orchestrator surfaces its ERROR: verbatim. The orchestrator only sees a _warning:_ on the commands axis when HEAD was degraded.
Apply the gates below per axis. Each gate sets a per-axis disable flag (domain_axis_disabled, commands_axis_disabled, ops_axis_disabled) and emits a WARNING: line describing what was skipped; the run continues if any other axis is still enabled. Only the aggregated 1.all gate aborts the orchestrator.
Each gate disables only the domain axis and emits a WARNING: (not ERROR:). Evaluate in order and stop at the first match.
| Gate | Trigger | Action |
|---|---|---|
| 1.dom.a | domain.degraded_baseline true | Set domain_axis_disabled = true; emit WARNING: domain axis disabled — HEAD baseline is degraded (multiple or missing Mermaid blocks at HEAD per <stem>.domain/updates.md). Domain-driven dispatch is skipped for this run; run @messaging-spec:code-generator <domain_diagram> <consumer_name> per consumer to regenerate against a clean baseline. |
| 1.dom.b | domain.aggregate_root_touched and the aggregate root appears in domain.removed_classes without a same-name entry in domain.added_classes, or the aggregate root appears in domain.stereotype_changed | Set domain_axis_disabled = true; emit WARNING: domain axis disabled — the aggregate root was removed or re-stereotyped in <stem>.domain/updates.md; the whole diagram set (and every consumer under <stem>.messaging/) is invalid. Reconcile the diagrams, then re-run @messaging-spec:code-generator <domain_diagram> <consumer_name> per consumer. |
| 1.dom.c | domain.aggregate_root_touched via a rename (the aggregate root appears in both domain.removed_classes and domain.added_classes) | Set domain_axis_disabled = true; emit WARNING: domain axis disabled — the aggregate root was renamed in <stem>.domain/updates.md; this cascades to <stem>.commands.md's class names + filename, the <stem>.messaging/ folder, the %% Messaging markers' <Source> cells, and the <pkg>.domain.<root_snake> import root in generated code. Rename the diagrams + folder, reconcile the markers, then re-run @messaging-spec:code-generator <domain_diagram> <consumer_name> per consumer. |
| 1.dom.d | domain.stereotype_changed non-empty (the aggregate-root case is already handled by 1.dom.b; this covers <<Domain Event>> ⇄ other re-classifications that invalidate internal subscriptions) | Set domain_axis_disabled = true; emit WARNING: domain axis disabled — class(es) <names> have stereotype changes in <stem>.domain/updates.md. A stereotype change moves a class to a different pattern catalog. Reconcile the diagrams, then re-run @messaging-spec:code-generator <domain_diagram> <consumer_name> per affected consumer. (Surface every offending name, not just the first.) |
Domain-axis hard-fails are severe enough for messaging that the WARNING text directs the operator to the per-consumer init pipeline — an aggregate-root rename cascades into the <stem>.messaging/ folder name, the import root, and the %% Messaging markers' <Source> cells, none of which this skill rewrites.
Note: unlike /persistence-spec:update-specs and /application-spec:update-specs, this skill does not treat a <<Repository>> interface lifecycle change as a gate trigger — repositories and domain services are byte-neutral for the consumer spec (Tables 1–3 model the event surface, not the persistence or service wiring).
Each gate disables only the commands axis and emits a WARNING:.
| Gate | Trigger | Action |
|---|---|---|
| 1.cmd.a | commands.degraded_baseline true | Set commands_axis_disabled = true; emit WARNING: commands-diagram axis disabled — HEAD baseline is degraded (multiple or missing Mermaid blocks at HEAD per <stem>.application/commands-updates.md). Commands-diagram-driven dispatch is skipped for this run. |
The commands detector itself hard-fails on stereotype change, anchor rename, multi-anchor — those never reach the orchestrator.
Each gate disables only the ops axis and emits a WARNING:.
| Gate | Trigger | Action |
|---|---|---|
| 1.ops.a | ops.degraded_baseline true | Set ops_axis_disabled = true; emit WARNING: ops-diagram axis disabled — an ops diagram's HEAD baseline is degraded (multiple or missing Mermaid blocks at HEAD per <stem>.application/ops-updates.md). Ops-diagram-driven dispatch is skipped for this run. |
The ops detector itself hard-fails on an ops service-class rename or multi-anchor — those never reach the orchestrator. When the aggregate has zero ops diagrams the ops report is a _None._ no-op and this gate never fires.
If domain_axis_disabled AND commands_axis_disabled AND ops_axis_disabled are all true, abort the orchestrator with:
ERROR: both input axes are disabled by preflight gates (see WARNING lines above). The orchestrator
cannot regenerate any consumer. Resolve the underlying conditions or run @messaging-spec:code-generator
<domain_diagram> <consumer_name> per consumer to rebuild the consumer specs and code from scratch.
No writes; no downstream agents are invoked (no messaging-updates-writer either — there is no transition to describe).
For each consumer spec <dir>/<stem>.messaging/<C>.md (the <C> enumerated in Step 0c — the basename minus .md, a kebab-case identifier like inventory-sync):
Read it and locate the ### Table 2: Events to Consume section (shape owned by messaging-spec:event-tables-template). If the body is the empty-state placeholder (*No events consumed by this consumer.*), the row list is empty. Otherwise parse the | Event Name | Type | Source Destination | Command Class | Command Method | table into rows { event_name, type ∈ {external, internal}, source_destination, command_class, command_method } (strip backticks from each cell).internal_subs[C] = the set of event_name for rows whose type is internal, each paired with its full row (so command_class / source_destination / command_method are available for the abort instructions). The on-disk Table 2 faithfully mirrors the commands diagram's %% Messaging - <C> markers — this orchestrator does not parse the commands diagram's Mermaid; the commands detector already did that, and Step 1 reads its report.external_subs[C] = the set of event_name for rows whose type is external. Used in Step 4 to fan out M7 (external event attribute changes) to consumers that subscribe to the affected event.If a working-tree consumer spec is so malformed that its ### Table 2: heading cannot be located, hard-fail with: ERROR: <stem>.messaging/<C>.md is malformed; cannot locate the Table 2 heading. Re-generate it via @messaging-spec:code-generator <domain_diagram> <C>.
Note: a %% Messaging - <C> block that the commands diagram declares but no <stem>.messaging/<C>.md exists for is not added to the consumer set here. That is X1 (consumer added), surfaced as a Step 7 WARNING directing the operator to @messaging-spec:code-generator. The orchestrator never invokes consumer-spec-initializer or consumer-scaffolder; those belong to the init pipeline. Conversely, an existing consumer spec whose %% Messaging - <C> block has been removed from the commands diagram is X2 (consumer orphaned), surfaced as a Step 7 WARNING recommending the operator delete the now-orphaned file.
Compute the per-consumer dangling set:
dangling[C] := internal_subs[C] ∩ domain.removed_or_renamed_events # existing rule
- rows_already_removed_from_commands[C] # deduct already-reconciled commands rows
- rows_already_removed_from_ops[C] # deduct already-reconciled ops rows
Where rows_already_removed_from_commands[C] is the set of internal-event names that the commands report (commands.messaging_markers) flags as row_removed or row_changed (old-side event name) under ### <C>, and rows_already_removed_from_ops[C] is the same set derived from the ops report (ops.messaging_markers) under #### <C>. If commands_axis_disabled (resp. ops_axis_disabled), the corresponding set is empty (the deduction collapses to the existing rule for that axis).
Rationale: if the operator's edit covered both diagrams — dropped the <<Domain Event>> class from the domain diagram and removed the corresponding <HandlerClass> --() <E> : handles (...) row from the %% Messaging - <C> block (in either the commands diagram or an ops diagram) — the consumer is no longer dangling, just regenerating. Without the deduction, a coordinated edit would still abort the consumer.
For every consumer with dangling[C] ≠ ∅ (after deduction), add <C> to the aborted set and hold the per-consumer reconcile text. This is not a whole-skill hard-fail — every non-dangling consumer still proceeds through Steps 4–5. event-fields-writer would fail to resolve a removed/renamed internal event class; and even if it didn't, the consumer's Table 2 (and the commands diagram's %% Messaging marker) would still name an event the domain diagram no longer declares — only reconciling the hand-authored marker fixes that.
If the commands report's commands.messaging_markers also flags the entire %% Messaging - <C> block as (consumer removed) (X2) for the same consumer, the consumer is reported under the X2 WARNING (Step 7), not under abort: the operator's reconcile instruction for a removed consumer block is "delete the now-orphaned consumer spec file", not "reconcile the markers". A consumer falls through to abort only when the block survives but a specific internal row dangles.
Per-consumer reconcile text (one per dangling event <E>, using that row's <CommandClass> / <Source> / <on_method> cells; surfaced in Step 7's closing summary; messaging-updates-writer also renders it in updates.md):
consumer <C> subscribes to internal event <E>, which was removed/renamed in <stem>.domain/updates.md.
Reconcile the `%% Messaging - <C>` block in the diagram that declares it — <stem>.commands.md for a
`<CommandClass> --() <E> : handles (<Source>, <on_method>)` line (and the on_<E> handler on <AggregateRoot>Commands),
or the relevant <stem>.ops.<op-name>.md for a `<OpsClass> --() <E> : handles (<Source>, <method>)` line (and that
ops method) — then re-run `@event-tables-writer <commands_diagram> <C>` and `@event-fields-writer <commands_diagram> <C>`
(or `@messaging-spec:code-generator <domain_diagram> <C>`).
Existing dispatch (domain axis only) was:
affected := { <C> ∉ aborted : internal_subs[C] ∩ keys(event_attr_deltas) ≠ ∅ }
Extended to a three-way union across both axes, treating disabled axes as contributing the empty set:
# Domain-axis contribution (existing rule, axis-gated)
domain_affected = ∅ if domain_axis_disabled else
{ <C> ∉ aborted : internal_subs[C] ∩ keys(domain.event_attr_deltas) ≠ ∅ }
# Commands-diagram-axis contribution (new)
commands_affected = ∅ if commands_axis_disabled else (
# X3 / X4 / X5: row added / removed / changed inside an existing consumer's
# %% Messaging block (and the block as a whole was not removed)
{ <C> : <C> ∈ existing_consumers ∧ commands.messaging_markers[C].status == "modified"
∧ (rows_added ∪ rows_removed ∪ rows_changed) ≠ ∅
∧ <C> ∉ aborted }
∪
# M7: external event attribute change ripples into Table 3 of every consumer
# whose Table 2 has an `external` row referencing the changed event
{ <C> : external_subs[C] ∩ commands.external_event_changes ≠ ∅
∧ <C> ∉ aborted }
∪
# M4 filtered: a `methods` change is a messaging signal only if the affected
# handler is bound by a %% Messaging row of an existing consumer. Walk
# commands.changed_methods (anchor public methods with **Signature:** sub-section)
# and intersect with each existing consumer's command_method column.
{ <C> : ∃ method ∈ commands.changed_methods :
method.has_signature_change
∧ ∃ row ∈ Table 2(<C>) : row.command_method == method
∧ <C> ∉ aborted }
)
# Ops-diagram-axis contribution (new) — parallels the commands axis, minus M7
# (ops diagrams declare no external <<Domain Event>> classes; external events live
# on the commands diagram, so the external-event ripple stays a commands-axis signal)
ops_affected = ∅ if ops_axis_disabled else (
# ops X3 / X4 / X5: row added / removed / changed inside an existing consumer's
# %% Messaging block declared in an ops diagram (block as a whole not removed)
{ <C> : <C> ∈ existing_consumers ∧ ops.messaging_markers[C].status == "modified"
∧ (rows_added ∪ rows_removed ∪ rows_changed) ≠ ∅
∧ <C> ∉ aborted }
∪
# ops M4: an ops method whose signature changed ripples into Table 3 of every
# consumer whose Table 2 has a row binding that method (Command Method == method
# name; ops methods are free-named, matched exactly, not via the on_<event> rule)
{ <C> : ∃ method ∈ ops.changed_methods :
∃ row ∈ Table 2(<C>) : row.command_method == method
∧ <C> ∉ aborted }
)
# Three-way union (domain + commands-diagram + ops-diagram)
affected = domain_affected ∪ commands_affected ∪ ops_affected
Notes on the per-category mapping (## Affected Categories → consumer impact):
messaging-markers X1 (consumer added) — never enters affected; surfaced as a Step 7 WARNING (the consumer-spec init route is @messaging-spec:code-generator).messaging-markers X2 (consumer removed) — never enters affected; surfaced as a Step 7 WARNING (the operator deletes the orphaned consumer-spec file).messaging-markers X3 / X4 / X5 (row changes within an existing consumer) — enters commands_affected via the first set in the union.external-domain-events (external event attribute change) — enters commands_affected via the M7 set in the union.methods (anchor public method change) — enters commands_affected only via the M4-filter set in the union (the method is bound by a %% Messaging row). Most anchor-method changes are not handler changes; most methods signals do not fire messaging-axis dispatch.dependencies / raised-exceptions / external-interfaces / surface-markers — silently ignored (not messaging-relevant); they contribute neither to affected nor to a Step 7 WARNING.domain.added_events) affects no consumer — a new event is a subscription candidate, declared by a %% Messaging marker (a commands-axis concern). Informational only; messaging-updates-writer records it as a warning in updates.md.external-event rows are wholly outside the domain axis — their classes are declared on the commands diagram, not the domain diagram — so they never enter domain_affected. They reach the orchestrator only via the M7 set.If affected is empty and aborted is empty and no X1 / X2 advisory fired → Tier-3 no-op: skip Step 5, go straight to Step 6 (emit the report so <stem>.messaging/updates.md always exists after a successful run), then Step 7 with the no-op summary line, and exit.
Process the consumers in affected (the aborted ones are skipped — Step 3 already recorded them). Within a consumer the work is two sequential agents (Table 2 first, since Table 3 references Table 2's rows); across consumers the work is parallel (independent files). Run two rounds:
Round 1 — event-tables-writer (Table 2 refresh). Emit one Agent call per affected consumer in a single message — messaging-spec:event-tables-writer with prompt <commands_diagram> <C>. It re-parses the %% Messaging - <C> markers and re-renders Table 2 in place; it is a no-op for a domain-only change (markers unchanged) but catches the case where the operator already reconciled the commands diagram before invoking this skill. Cheap and idempotent. Wait for every call to complete.
Round 2 — event-fields-writer (Table 3 regen). Emit one Agent call per affected consumer in a single message — messaging-spec:event-fields-writer with prompt <commands_diagram> <C>. It rebuilds Table 3 wholesale: the Command Parameter column from <AggregateRoot>Commands.on_<event> signatures in the commands diagram, the external-row Event Field values from the foreign <<Domain Event>> decls in the commands diagram, and the internal-row Event Field values by best-match against the current <<Domain Event>> attribute lists in the domain diagram — re-flagging low-confidence sub-blocks in italic prose. Wait for every call to complete.
Neither writer needs a spec-core:target-locations-finder report — that is a code-gen concern; the spec writers operate purely on the diagrams and the consumer-spec file.
If a writer aborts on a given consumer, record it (its consumer spec is left in whatever partial state the writer reached) and continue with the remaining consumers — the updater does not roll back already-processed consumers, and re-running /messaging-spec:update-specs after the operator reconciles the indicated diagram idempotently completes the update. Do not abort the whole skill for a per-consumer writer failure; surface it as a WARNING: line in Step 7.
Invoke messaging-spec:messaging-updates-writer with prompt $ARGUMENTS[0] (the domain diagram path). It diffs every working-tree consumer spec against git HEAD, cross-references the sibling domain updates.md, classifies each consumer (updated | aborted | unaffected), derives the ## Affected Artifacts footer mechanically, and writes <dir>/<stem>.messaging/updates.md (always — even on the Tier-3 no-op, where every consumer renders unaffected and the footer is the header row only). It recovers everything it needs from disk + git + the sibling domain updates.md; the orchestrator passes nothing else (the writer recomputes the same abort list this skill computed in Step 3 — same inputs, same rule, byte-identical).
This step runs on every successful run that got past Step 0 (i.e. at least one consumer spec exists) — including the Tier-3 no-op. It does not run on the Step 0c "no consumers" no-op (there is no folder to write into and nothing to report), nor on any Step 0 / Step 1.all hard-fail (there is no transition to describe; the operator gets only the ERROR: line).
If the writer reports a failure, abort and emit a single ERROR: line repeating its message. The consumer specs are already in their final post-update state by this point — re-running the orchestrator (or just @messaging-updates-writer standalone) idempotently produces the report.
Note: at v1 the writer does not consume commands-updates.md for source attribution or render X1 (needs-init) / X2 (orphaned) advisory blocks inside updates.md — those signals are surfaced via Step 7 WARNING: lines only. A future writer extension may add the advisory blocks; the v1 orchestrator's contract is unchanged either way.
Print one summary line (each invoked agent already printed its own per-step report; add no commentary beyond this line and the WARNING: lines below).
Build <axis_summary> first — a comma-separated list (in canonical order: domain, commands-diagram, ops-diagram) of axes that contributed at least one trigger to a dirty-consumer flag (domain via domain_affected, commands via commands_affected, ops via ops_affected). An axis whose flag-contribution was the empty set (either disabled, or its triggers all resolved to empty) does not appear in <axis_summary>. Use + (space-plus-space) as the separator when multiple axes contributed (e.g. domain + commands-diagram + ops-diagram).
Build the per-outcome counts from Step 3 / 4 / 5:
<k> = consumers in affected that completed Step 5 cleanly (Tables 2–3 regenerated).<f> = consumers a Step 5 writer aborted on.<m> = len(aborted) (Step 3).<n> = discovered − <k> − <f> − <m> (consumers untouched this run — neither dirty nor dangling).<i> = X1 consumers (new %% Messaging - <C> block, no consumer spec on disk yet). Count derived from commands.messaging_markers and ops.messaging_markers entries with status == "added" (dedupe a consumer that appears in both axes — count it once).<o> = X2 consumers (existing consumer spec, every %% Messaging - <C> block dropped). Count derived from commands.messaging_markers and ops.messaging_markers entries with status == "removed" for a consumer in existing_consumers. A consumer is X2 only when no surviving %% Messaging - <C> block remains across all diagrams — if the commands diagram dropped the block but an ops diagram still declares one (or vice versa), the consumer is modified/regenerating, not orphaned.affected and aborted and X1 and X2 all empty)domain.orphan_prose is true: No messaging consumer-spec updates required. Orphan prose changes detected — review <stem>.domain/updates.md. Emitted <stem>.messaging/updates.md.No messaging consumer-spec updates required (no subscribed internal domain event changed and no commands-diagram delta affected any consumer; see <stem>.messaging/updates.md for any informational warnings). Emitted <stem>.messaging/updates.md.Processed <stem>.messaging/ — <k> consumer(s) regenerated (<names>), <f> failed (<names>),
<m> aborted (<names>), <n> unaffected, <i> need init (<names>), <o> orphaned (<names>);
triggers: <axis_summary>; emitted <stem>.messaging/updates.md.
Drop any clause whose count is zero. Then append the per-consumer WARNING lines:
<E>:
WARNING: <reconcile text> — the Step 3 text with <C> / <E> / <CommandClass> / <Source> / <on_method> filled from that consumer's dangling Table 2 row and <stem> / <commands_diagram> from the path derivation. Leave <AggregateRoot> literal (the operator knows their aggregate root — the orchestrator does not parse the domain diagram for the root name).WARNING: <agent> failed on consumer <C>: <message> — reconcile the indicated diagram and re-run /messaging-spec:update-specs.<C> (consumer added — a new %% Messaging - <C> block declared in the commands diagram or an ops diagram, no consumer spec on disk), append:
WARNING: a diagram declares new %% Messaging - <C> block with no consumer spec on disk — run @messaging-spec:code-generator <domain_diagram> <C> to initialize the consumer spec and scaffold its code-side artifacts.<C> (consumer orphaned — every %% Messaging - <C> block removed from the commands diagram and all ops diagrams, consumer spec still on disk), append:
WARNING: consumer spec <stem>.messaging/<C>.md exists but no %% Messaging - <C> block remains in <stem>.commands.md or any <stem>.ops.<op-name>.md. Delete <stem>.messaging/<C>.md (and the matching messaging/<C>/ subpackage via @messaging-spec:code-generator follow-up) once the operator is sure the consumer should be retired.If any preflight axis was disabled (Step 1.dom / 1.cmd fired), the WARNING: line(s) for those gates are emitted before the summary so the operator sees what got skipped. The summary itself still runs.
ERROR: line repeated verbatim. No rollback — re-running after fixing the trigger re-invokes the detector.messaging-updates-writer either — there is no transition to describe). The WARNING lines for each disabled axis are emitted before the aggregated ERROR. Operator runs @messaging-spec:code-generator <domain_diagram> <consumer_name> per consumer.WARNING: in Step 7 and (in a future writer extension) recorded in updates.md. Operator-action items, not blockers — the run continues for every existing consumer.WARNING: line per affected consumer./messaging-spec:update-specs after fixing the trigger is the supported recovery path — every step is idempotent on stable inputs:
event-tables-writer, event-fields-writer) regenerates Tables 2–3 wholesale from the current diagrams on every call (output stable modulo LLM nondeterminism in event-fields-writer's best-match prose).messaging-updates-writer) is a pure HEAD-vs-working-tree diff and overwrites updates.md from scratch./messaging-spec:update-specs cannot retry through are the Step 0 missing-input cases (0a, 0b) and the Step 1.all total-abort gate. Each error message directs the operator to the correct fix — /update-specs / @updates-detector for the missing domain report, diagram-restore for the missing commands diagram, @messaging-spec:code-generator <domain_diagram> <consumer_name> per consumer for everything else.Re-running /messaging-spec:update-specs against unchanged inputs (working-tree consumer specs unchanged versus HEAD, same domain updates.md, same commands diagram) produces:
internal subscriptions intersect the changed-domain-event set, nothing is dangling, and the commands report fires no X3/X4/X5/M7/M4-filtered signal.event-fields-writer's best-match flags (git diff noise, not a correctness failure).There are no sentinel comments — every consumer-spec table is a snapshot; re-running over an unchanged input set simply reproduces the same content. (Unlike /persistence-spec:update-specs's <!-- appended-from updates-hash:<hash> -->, there is no append-only log to guard.)
@messaging-spec:code-generator. In particular it never re-runs consumer-spec-initializer; Table 1 is hand/prefix-derived and a domain or commands-diagram change never touches it.<domain_diagram> and does not invoke domain-spec:updates-detector — the domain updates.md is expected on disk before this skill runs.application-spec:queries-updates-detector — messaging is command-side only and queries-axis deltas have no consumer-spec ripple.<stem>.md, <stem>.commands.md, <stem>.queries.md) or any ## Artifacts index — those siblings are linked from the original pipeline runs.%% Messaging - <C> block (X1). The orchestrator surfaces X1 as a Step 7 WARNING: directing the operator to @messaging-spec:code-generator <domain_diagram> <C>, which already owns the end-to-end init pipeline (consumer-spec-initializer → consumer-scaffolder → implementers → tests).%% Messaging - <C> block (X2). The orchestrator's contract is "the skill writes inside specs, not deletes spec files" — an orphaned spec may carry hand-authored notes worth preserving before deletion. X2 is surfaced as a Step 7 WARNING: recommending the operator delete the file.<<Command>> class. Domain <<Command>> changes ripple into generated command-handlers / command-replies / command-dispatchers code only, reconciled by @messaging-spec:code-generator, not by this updater. (A known modeling gap, not a bug.)@messaging-spec:code-generator (per consumer) via the Step 1.dom WARNINGs. Domain-axis dispatch is disabled, not aborted, so a clean commands-axis edit still proceeds.surface-markers category that may appear on the commands-updates report — that drives /rest-api-spec:update-specs. This orchestrator silently ignores it.dependencies / raised-exceptions / external-interfaces categories on the commands report — those drive /application-spec:update-specs. Silently ignored here.<<Domain Event>> removed/renamed leaves the commands-diagram %% Messaging marker (and the on_<event> handler) dangling, which only the operator can reconcile; the skill surfaces an abort-and-reconcile instruction (Step 3) and skips that consumer for this run. Exception: if the operator already removed the corresponding %% Messaging row from the commands diagram in the same edit, Step 3's deduction rule recognizes the reconciliation and the consumer regenerates cleanly.event-fields-writer does re-derive its own italic low-confidence flags around Table 3 from scratch on each run; that is by design.) Untouched consumers' specs are preserved byte-identically.messaging/<consumer>/events.py, handlers.py, dispatcher.py, the containers.py / entrypoint.py / __main__.py wiring, the constants.py constants, the handler integration tests) — that is the /messaging-spec:update-code skill, which consumes the <stem>.messaging/updates.md this skill emits./spec-core:update-specs (after that orchestrator's application wave). In that cascade mode /spec-core:update-specs passes --detectors-fresh as the second positional arg (it does so only when the application wave left the commands-axis detector report on disk), signalling that the report is current; Step 0d of this skill takes the cascade-mode shortcut and skips its own commands detector invocation. When <stem>.messaging/ is absent or holds no consumer specs this skill still prints a one-line "nothing to update" and exits cleanly, so a missing messaging layer never aborts the cascade — and /spec-core:update-specs runs this skill in parallel with /rest-api-spec:update-specs, so a messaging hard-fail does not abort that sibling either; each runs to completion and prints its own report. Standalone invocation (without --detectors-fresh) follows the default Step-0d detector-invocation path.