メニュー
Surgically updates the application service specs (`commands.specs.md`, `queries.specs.md`, `services.md`) from domain/diagram changes. Invoke with: /application-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 application service specs (`commands.specs.md`, `queries.specs.md`, `services.md`) from domain/diagram changes. Invoke with: /application-spec:update-specs <domain_diagram> |
| argument-hint | <domain_diagram> |
| allowed-tools | Read, Bash, Agent |
You are an application spec update orchestrator. Given a domain diagram and its sibling commands/queries application-service diagrams (plus any <dir>/<stem>.ops.<op-name>.md ops orchestration diagrams), refresh the existing <dir>/<stem>.application/commands.specs.md, <dir>/<stem>.application/queries.specs.md, every dirty <dir>/<stem>.application/ops.<op-name>.specs.md, and <dir>/<stem>.application/services.md in place — invoke the three app-service-axis update detectors (commands, queries, ops), re-run only the dirty side's / dirty ops service's writers, re-enrich application exceptions, re-run services-finder, and emit <dir>/<stem>.application/updates.md (plus the ops detector's <dir>/<stem>.application/ops-updates.md). Do not rerun the full @application-spec:specs-generator pipeline, do not touch the diagram files, and do not ask for confirmation before writing.
This is a pure single-plugin updater — it touches only the <stem>.application/ siblings and invokes only application-spec agents. It does not cascade to rest-api or messaging. Cross-layer propagation is owned by /spec-core:update-specs <domain_diagram>, which runs this skill (its application wave) before the rest-api/messaging wave so the three detector reports this skill produces are on disk when those leaves read them. Run /spec-core:update-specs for a full cross-layer update; run this skill directly for an application-only update.
This skill is the application-side counterpart to /update-specs (domain) and /persistence-spec:update-specs. Design rationale lives in notes/spec-updater-approach.md, notes/update-types.md, notes/updates-report.md, notes/commands-queries-detectors-approach.md, notes/commands-queries-update-types.md, notes/commands-queries-updates-report.md, and notes/commands-queries-integration-approach.md; the load-bearing idea is per-side snapshot regen — every section of <side>.specs.md is a pure snapshot, so the surgical unit of work is one full side, not one method block. Commands and queries are independent; a delta on any of the three input axes touches at most one or both.
The orchestrator consumes four update reports — one per axis — and unions their dispatch signals:
<dir>/<stem>.domain/updates.md, produced by domain-spec:updates-detector (consumed if present; absent ⇒ the domain axis is treated as no-change per Step 0a — never invoked or produced here).<dir>/<stem>.application/commands-updates.md, produced by application-spec:commands-updates-detector (invoked at Step 0 below).<dir>/<stem>.application/queries-updates.md, produced by application-spec:queries-updates-detector (invoked at Step 0 below).<dir>/<stem>.application/ops-updates.md, produced by application-spec:ops-updates-detector (invoked at Step 0h below). One aggregate-wide report covering every <dir>/<stem>.ops.<op-name>.md; absent/empty when the aggregate declares no ops services. This skill produces the ops report for its own dispatch; the rest-api / messaging updaters re-invoke the detector themselves (it is outside the --detectors-fresh promise) and fast-path on its digest sentinel.The orchestrator never re-diffs any diagram itself.
This skill is the single producer of the three app-service-axis detector reports (commands-updates.md, queries-updates.md, ops-updates.md) that the rest-api and messaging updaters consume. It produces them at Step 0 for its own dispatch; the /spec-core:update-specs orchestrator sequences this skill before the rest-api/messaging wave precisely so those reports are on disk (and byte-stable) when the leaves read them under --detectors-fresh. This skill itself never invokes rest-api or messaging — it only produces the reports they depend on. Its behaviour is identical whether invoked standalone (for a commands/queries/ops-diagram change) or as the application wave of /spec-core:update-specs.
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).<plugin_dir> = <dir>/<stem>.application — the per-plugin folder for application-spec.| File | Role | Touched by |
|---|---|---|
<dir>/<stem>.domain/updates.md | input — domain delta report (optional — absent ⇒ domain axis treated as no-change, see Step 0a) | not modified |
<dir>/<stem>.commands.md | input — hand-authored commands diagram (must already exist) | not modified |
<dir>/<stem>.queries.md | input — hand-authored queries diagram (must already exist) | not modified |
<dir>/<stem>.ops.<op-name>.md | input — hand-authored ops diagram(s), zero or more (optional) | not modified |
<plugin_dir>/commands-updates.md | input — commands-diagram delta report | produced by commands-updates-detector at Step 0 |
<plugin_dir>/queries-updates.md | input — queries-diagram delta report | produced by queries-updates-detector at Step 0 |
<plugin_dir>/ops-updates.md | input+output — ops-diagram delta report (one aggregate-wide file) | produced by ops-updates-detector at Step 0h |
<plugin_dir>/commands.specs.md | spec being updated (must already exist) | deps-writer commands + commands-methods-writer (per-side fragments) → application-exceptions-specifier → specs-merger commands (when commands dirty) |
<plugin_dir>/queries.specs.md | spec being updated (must already exist) | deps-writer queries + queries-methods-writer (per-side fragments) → application-exceptions-specifier → specs-merger queries (when queries dirty) |
<plugin_dir>/ops.<op-name>.specs.md | spec being updated, one per dirty ops service | deps-writer ops <op-name> + ops-methods-writer (per-service fragments) → application-exceptions-specifier → specs-merger ops <op-name> (when that ops service is dirty); deleted when its diagram was removed |
<plugin_dir>/services.md | spec being updated (must already exist) | services-finder (always — Step 6) |
<plugin_dir>/updates.md | output — application delta report (commands/queries axis) | application-updates-writer |
<domain_diagram>, <commands_diagram>, and <queries_diagram> are read by the invoked agents; this orchestrator never modifies them. Every agent derives <dir> / <stem> from $ARGUMENTS[0] per spec-core:naming-conventions — pass $ARGUMENTS[0] verbatim as the prompt to each.
This skill keeps no runtime state between agents. The updates writer recovers the pre-update specs via git show HEAD:<spec_file> for each of the three spec files and reads the three on-disk delta reports for axis-tagged source attribution, so there is nothing for the orchestrator to capture or hand along.
This skill writes only inside <dir>/<stem>.application/. The downstream <dir>/<stem>.rest-api/ and <dir>/<stem>.messaging/ folders are written by their own layer updaters when /spec-core:update-specs sequences them after this skill — never here.
Derive <dir> and <stem> from $ARGUMENTS[0] per spec-core:naming-conventions. <stem> must satisfy ^[a-z][a-z0-9-]*$. Using Bash (test -f), verify the input files in this order:
0a. If <dir>/<stem>.domain/updates.md is missing → do not hard-fail. The domain report is an optional input: set domain_report_absent = true, emit the WARNING below, and continue with the commands/queries-diagram axes only. This skill never produces the domain report itself (it does not invoke domain-spec:updates-detector), so absence is handled by suppressing the domain axis, not by synthesizing the file:
WARNING: <dir>/<stem>.domain/updates.md absent — domain axis treated as no-change. The
commands/queries-diagram axes still drive this update. If the domain diagram actually changed,
run `@updates-detector <domain_diagram>` (or `/update-specs <domain_diagram>`) first so
domain-driven application changes are not silently skipped.
When domain_report_absent is true: skip the domain-axis extraction in Step 1, bind every domain-axis value to its empty default (domain.affected_categories = [], domain.per_class_changes = false, all ## Class Lifecycle lists empty, domain.degraded_baseline = false, domain.orphan_prose = false), and the domain-axis gates (1.dom.a–d) cannot fire. The downstream application-updates-writer (Step 7) already tolerates an absent domain report — its domain-axis Source delta probe is skipped and the Summary's Domain updates source renders _none_.
0b. If <dir>/<stem>.application/commands.specs.md is missing → hard-fail:
ERROR: <dir>/<stem>.application/commands.specs.md not found. The application updater is not the
first-run pipeline. Run `@application-spec:specs-generator <domain_diagram>` to create the spec.
0c. If <dir>/<stem>.application/queries.specs.md is missing → hard-fail:
ERROR: <dir>/<stem>.application/queries.specs.md not found. The application updater is not the
first-run pipeline. Run `@application-spec:specs-generator <domain_diagram>` to create the spec.
0d. If <dir>/<stem>.application/services.md is missing → hard-fail:
ERROR: <dir>/<stem>.application/services.md not found. The application updater is not the
first-run pipeline. Run `@application-spec:specs-generator <domain_diagram>` to create the spec.
0e. 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. Restore the file or run `@application-spec:specs-generator <domain_diagram>`
after authoring it.
0f. If <dir>/<stem>.queries.md is missing → hard-fail:
ERROR: <dir>/<stem>.queries.md not found. The queries application-service diagram is a required
hand-authored input. Restore the file or run `@application-spec:specs-generator <domain_diagram>`
after authoring it.
Do not synthesize any of these files.
After 0a–0f run (0a never aborts — it only records domain_report_absent; 0b–0f hard-fail on a missing input), fan out the two detectors in a single message so they run concurrently. Pass $ARGUMENTS[0] (the domain diagram path) as the prompt to each — the detectors derive their own sibling diagrams via spec-core:naming-conventions.
application-spec:commands-updates-detector with prompt $ARGUMENTS[0].application-spec:queries-updates-detector with prompt $ARGUMENTS[0].Each detector writes its own report (<plugin_dir>/commands-updates.md, <plugin_dir>/queries-updates.md) or hard-fails with an ERROR: line. The detectors share <plugin_dir> only — both use mkdir -p idempotently, so the parallel pattern is safe.
This skill is the single producer of these two reports: it always produces them here, on every invocation, for its own dispatch. There is no concurrent producer to race with — rest-api / messaging only read them, and /spec-core:update-specs sequences this skill before them — so there is no cascade-mode shortcut here; the detectors run every time. (A stray --detectors-fresh token in $ARGUMENTS is harmless: this orchestrator only ever reads $ARGUMENTS[0], so the flag is simply ignored and the detectors run anyway.)
If either detector hard-fails, abort the orchestrator with that detector's ERROR: line repeated verbatim. The other detector's output (if it completed) is left on disk for the next run; no rollback is performed. The same @application-spec:specs-generator <domain_diagram> recovery path the detectors themselves direct to applies here.
Wait for both detectors to return successfully before proceeding to Step 0h.
Invoke application-spec:ops-updates-detector with prompt $ARGUMENTS[0]. This skill is the producer of <plugin_dir>/ops-updates.md. The detector globs <dir>/<stem>.ops.*.md, diffs each against HEAD, and writes the aggregate-wide report — fast-pathing on its digest sentinel when no ops diagram changed and writing a header-only no-op report (No changes detected. / _None._ / empty Affected Artifacts) when the aggregate declares zero ops diagrams. It hard-fails with an ERROR: line on a structural problem (anchor renamed, multi-anchor, unreadable diagram); on hard-fail, abort the orchestrator with that line verbatim. Producing the report here is what lets this skill regenerate the dirty ops specs at Steps 3/5 and lets /update-code's application brief-writer see the ops deltas; the rest-api / messaging updaters re-invoke the detector themselves and fast-path on the now-current sentinel.
This step runs sequentially after 0g (it shares <plugin_dir> and uses mkdir -p idempotently). Wait for it to return before proceeding to Step 1.
Read all four reports — <dir>/<stem>.domain/updates.md, <plugin_dir>/commands-updates.md, <plugin_dir>/queries-updates.md, <plugin_dir>/ops-updates.md. They are the orchestrator's single source of truth for this step — do not re-derive anything from any diagram. When domain_report_absent (Step 0a) is true, skip the domain report read entirely and bind every domain-axis value below to its empty default (the 1.dom gates then cannot fire); the commands/queries/ops reports are still read. Use Bash (grep) and Read to extract, per axis:
Domain axis (from <stem>.domain/updates.md):
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; the exact bullet format is owned by spec-core:update-reports (domain schema)). 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.affected_categories — bullets under ## Affected Categories, in the order they appear. The literal body _None._ means empty.domain.per_class_changes — whether ## Per-Class Changes is present with at least one ### -style class block. Used for the dispatch step's prose-or-member proxy.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.domain.repo_class_lifecycle — whether any bullet under ## Class Lifecycle → Added or → Removed carries the stereotype <<Repository>>.Commands-diagram axis (from <plugin_dir>/commands-updates.md):
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 vocabulary is owned by spec-core:update-reports (application-axis schema). The literal body _None._ means empty.Queries-diagram axis (from <plugin_dir>/queries-updates.md):
queries.degraded_baseline — whether the ## Summary block contains a line beginning _warning: HEAD .queries.affected_categories — bullets under ## Affected Categories. The literal body _None._ means empty.Ops-diagram axis (from <plugin_dir>/ops-updates.md; schema owned by spec-core:update-reports (ops schema)):
ops.degraded_baseline — whether the ## Summary block contains any line beginning _warning: HEAD .ops.touched_services — one entry per ## Service: \`block present in the report. Capture(, lifecycle)wherelifecycleisremovedwhen the heading is annotated(service removed), addedwhen annotated(service added), else changed. A report whose Summary is No changes detected.(or which has zero service blocks) yields an empty list. This is the orchestrator's ops dispatch input — the ops report wraps per-service blocks, so (unlike the aggregate-wide commands/queries## Affected Categories`) the dirty unit is the service, not a category.The structural hard-fails the detectors themselves enforce (anchor missing/renamed, multi-anchor, stereotype change inside the app-service diagram) never reach the orchestrator — the detector aborts at Step 0 and the orchestrator surfaces its ERROR: verbatim. The orchestrator only sees a _warning:_ on an app-service 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, queries_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:).
| 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). Run @application-spec:specs-generator <domain_diagram> to regenerate the domain-driven half from scratch. |
| 1.dom.b | domain.stereotype_changed non-empty | 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. Run @application-spec:specs-generator <domain_diagram> to regenerate from scratch. (surface every offending name) |
| 1.dom.c | Any bullet in domain.removed_classes has stereotype <<Aggregate Root>> | Set domain_axis_disabled = true; emit WARNING: domain axis disabled — aggregate root <ClassName> is listed under Class Lifecycle → Removed in <stem>.domain/updates.md. The <AggregateRoot>Commands / <AggregateRoot>Queries services lose their anchor; an aggregate-root rename also moves the diagram filenames. Rename the diagrams (<stem>.md, <stem>.commands.md, <stem>.queries.md) and the <stem>.application/ folder, then run @application-spec:specs-generator <domain_diagram>. |
| 1.dom.d | domain.repo_class_lifecycle true | Set domain_axis_disabled = true; emit WARNING: domain axis disabled — a <<Repository>> interface was added or removed per <stem>.domain/updates.md. A new repository requires a fresh dependency selection. Run @application-spec:specs-generator <domain_diagram>. |
Only one of 1.dom.a–1.dom.d fires per run (whichever is first); evaluate in order and stop at the first match.
Note: the orchestrator does not pre-check the narrower cases the methods writers also abort on (a missing save(...) on the command repo, an aggregate-root method renamed/removed under the application diagrams' canonical shape, a domain <<Service>> removed/stereotype-changed while still referenced by the commands diagram, a query-side external-interface operation renamed/removed, a query-repo finder rename that breaks the same-name match). The methods writers themselves abort on these and surface a one-sentence error directing the operator to reconcile the relevant application-service diagram. The orchestrator surfaces that error verbatim from Step 3.
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. |
Each gate disables only the queries axis and emits a WARNING:.
| Gate | Trigger | Action |
|---|---|---|
| 1.qry.a | queries.degraded_baseline true | Set queries_axis_disabled = true; emit WARNING: queries-diagram axis disabled — HEAD baseline is degraded (multiple or missing Mermaid blocks at HEAD per <stem>.application/queries-updates.md). Queries-diagram-driven dispatch is skipped for this run. |
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 regeneration is skipped for this run. |
When ops_axis_disabled is true, bind ops.touched_services to the empty list for dispatch (the ops-updates.md report is still emitted by Step 0h and still consumed by the rest-api / messaging updaters and /update-code; only this skill's own ops-spec regeneration is suppressed).
If domain_axis_disabled AND commands_axis_disabled AND queries_axis_disabled are all true and ops.touched_services is empty (after the 1.ops gate), abort the orchestrator with:
ERROR: all input axes are disabled by preflight gates (see WARNING lines above). The orchestrator
cannot regenerate any side. Resolve the underlying conditions or run @application-spec:specs-generator
<domain_diagram> to rebuild the application specs from scratch.
No writes; no downstream agents are invoked. (A live ops axis — ops.touched_services non-empty with ops_axis_disabled false — keeps the run alive even when all three commands/queries-feeding axes are disabled: the orchestrator can still regenerate the dirty ops specs.)
Compute two booleans from the values captured in Step 1, treating disabled axes as contributing the empty set:
# Domain axis (existing rules, but axis-gated; absent report ⇒ empty contribution)
domain_commands_triggers = ∅ if (domain_axis_disabled or domain_report_absent) else
(set(domain.affected_categories) & {"aggregates", "value-objects", "repositories-services"}) ∪
({"prose-proxy"} if domain.per_class_changes else ∅)
domain_queries_triggers = ∅ if (domain_axis_disabled or domain_report_absent) else
(set(domain.affected_categories) & {"data-structures", "repositories-services"}) ∪
({"prose-proxy"} if domain.per_class_changes else ∅)
# Commands-diagram axis (per-side by construction — commands report only describes the commands side)
commands_axis_triggers = ∅ if commands_axis_disabled else
set(commands.affected_categories) & {"methods", "dependencies", "raised-exceptions", "external-interfaces"}
# Queries-diagram axis (per-side by construction — queries report only describes the queries side)
queries_axis_triggers = ∅ if queries_axis_disabled else
set(queries.affected_categories) & {"methods", "dependencies", "raised-exceptions", "external-interfaces"}
# Union
commands_dirty = (domain_commands_triggers ∪ commands_axis_triggers) != ∅
queries_dirty = (domain_queries_triggers ∪ queries_axis_triggers ) != ∅
# Ops axis (per-service by construction — one ops report block per touched service; no category union)
dirty_ops = [] if ops_axis_disabled else [op for (op, life) in ops.touched_services if life in {"added", "changed"}]
removed_ops = [] if ops_axis_disabled else [op for (op, life) in ops.touched_services if life == "removed"]
Rationale (category-level dispatch):
Domain axis:
aggregates and value-objects can only affect the commands side (factory seeded-fields, postcondition prose, Requires Aggregate State, child-collection re-index). Queries methods go through DTOs and are byte-neutral on these.data-structures can only affect the queries side (Returns shape-hint prose at most). Command methods always return <AggregateRoot> and never name a TypedDict.repositories-services can affect either side — Command<X>Repository finder churn and referenced-<<Service>> method-signature changes drive the commands side; Query<X>Repository finder churn and query-side external-interface operation churn drive the queries side. Without finer-grained class identification we mark both sides dirty; the unaffected side's regen is byte-stable on stable inputs and only contributes diff noise.per_class_changes non-empty is treated as a prose proxy — the methods writers re-read the domain diagram's surrounding prose as advisory description, and a class-keyed prose change might nudge a Purpose / postcondition / collaborator-hint / status-gating / External-Interface-hint clause. We err on the side of regenerating both sides; the typical outcome is byte-stable output modulo LLM prose drift.domain-events and commands (the domain-message-dataclass category) never appear in application method specs — domain.affected_categories ⊆ {domain-events, commands} alone leaves both flags false.App-service axes (per-side by construction):
methods / dependencies / raised-exceptions / external-interfaces all map to commands-side regen.surface-markers and messaging-markers categories that may appear on a commands report are owned by /rest-api-spec:update-specs and /messaging-spec:update-specs respectively; this orchestrator silently ignores them (no commands_dirty contribution, no log line).Ops axis (per-service by construction):
## Service: block per touched service, so dispatch is per-service, not per-category: every service whose diagram changed against HEAD (lifecycle added or changed) is regenerated wholesale, exactly as a dirty commands/queries side is regenerated wholesale. This mirrors the commands/queries "regenerate the whole side" philosophy — a surface- or messaging-only ops change (which leaves the ops spec byte-stable) re-runs the ops writers and produces byte-stable output modulo LLM prose drift, the same accepted diff-noise cost the commands/queries side already pays. A removed service is not regenerated — its ops.<op-name>.specs.md is deleted (Step 3).services.md (Step 6's services-finder includes ops services), so the DI/fake/containers/conftest wiring for ops dependency changes flows through updates.md via the commands/queries Affected-Artifacts derivation — this skill does not special-case it.If commands_dirty and queries_dirty are both false and dirty_ops and removed_ops are both empty → Tier 4 no-op. Skip Steps 3–6 and jump straight to Step 7 (emit the report) so a <stem>.application/updates.md always exists after a successful run; the writer sees the working-tree specs unchanged versus HEAD and emits an all-_no changes_ report. Then run Step 8 (the no-op summary line) and exit. Note that even on this no-op the three detector reports from Step 0 are on disk and current — a domain-axis change that is byte-neutral for the application specs can still be live for rest-api or messaging (a pure domain-event attribute change is a Tier-4 no-op here but fires the messaging updater; a domain <<Command>> parameter-type change is a no-op here but can fire the rest-api request-fields writer), so /spec-core:update-specs still runs the rest-api/messaging wave after this skill regardless of this skill's no-op.
If at least one of commands_dirty / queries_dirty is true, or dirty_ops / removed_ops is non-empty, proceed to Step 3.
For each dirty side, fan out the writer agents in parallel. Emit all selected agent calls in a single message so they run concurrently. Pass $ARGUMENTS[0] (the domain diagram path) as the prompt to each — the writers derive their own sibling diagrams via spec-core:naming-conventions.
If commands_dirty:
application-spec:deps-writer with prompt $ARGUMENTS[0] commands.application-spec:commands-methods-writer with prompt $ARGUMENTS[0].If queries_dirty:
application-spec:deps-writer with prompt $ARGUMENTS[0] queries.application-spec:queries-methods-writer with prompt $ARGUMENTS[0].For each <op-name> in dirty_ops (one writer pair per dirty ops service — same fan-out the ops half of @application-spec:specs-generator uses):
application-spec:deps-writer with prompt $ARGUMENTS[0] ops <op-name>.application-spec:ops-methods-writer with prompt $ARGUMENTS[0] <op-name>.Fan out all selected writers — the commands pair, the queries pair, and the 2×N ops writers — together in a single message (the same parallel pattern @application-spec:specs-generator uses today). Wait for every selected writer to complete before proceeding.
Removed ops services. For each <op-name> in removed_ops (its diagram was deleted at HEAD→working-tree), no writer runs — instead delete the stale merged spec and any leftover fragments via Bash so Step 6's services-finder glob and the downstream /update-code brief no longer see it:
rm -f "<plugin_dir>/ops.<op-name>.specs.md" \
"<plugin_dir>/ops.<op-name>.deps.md" \
"<plugin_dir>/ops.<op-name>.methods.md" \
"<plugin_dir>/ops.<op-name>.exceptions.md"
(The ops-updates.md report from Step 0h already records the service as (service removed), which is what drives /update-code to remove the on-disk application/<agg>/<op_snake>.py and its tests — this Bash deletion only cleans up the spec siblings.)
Each writer regenerates its fragment from current inputs (the domain diagram + its side's application-service diagram) and writes <plugin_dir>/<side>.deps.md / <plugin_dir>/<side>.methods.md / <plugin_dir>/<side>.exceptions.md (stub) inside <dir>/<stem>.application/. The writers do not read the prior <side>.specs.md. A side's ## Dependencies is byte-stable on any domain-only change (it's a pure function of the application-service diagram); re-running the deps writer is an LLM-drift cost we accept rather than a correctness requirement, but is required because the merger consumes the on-disk fragment.
The methods writers may abort with a one-sentence error rather than producing a fragment. The conditions are:
commands-methods-writer aborts when an aggregate-root method that a command method resolves to has been renamed/removed (Step 5c match fails), when the chosen load-step finder has no remaining subset (Step 5d), or when a domain <<Service>> referenced by the commands diagram is missing/stereotype-changed (Step 4).queries-methods-writer aborts when a Query<AggregateRoot>Repository finder a query method needs has been renamed/removed (Step 5e same-name match fails), or when an external-interface operation a hint references no longer resolves (Step 5a).deps-writer ops <op-name> / ops-methods-writer abort with their own one-sentence error when the named <op-name>'s ops diagram is malformed (missing/duplicate brace-body anchor, an unresolvable collaborator/<<Service>> reference, or a method-flow that cannot be parsed). The orchestrator surfaces that error verbatim — the operator reconciles the indicated <stem>.ops.<op-name>.md and re-runs.If any writer reports a failure, abort the workflow and emit a single ERROR: line repeating its message verbatim. Do not run downstream agents — the spec is left partially regenerated and re-running /application-spec:update-specs after the operator reconciles the indicated application-service diagram (or ops diagram) idempotently completes the update. The other writers (if launched in parallel) may have completed; their fragments are left on disk to be re-consumed (or replaced) on a subsequent successful run.
After all Step 3 writers return successfully, invoke application-spec:application-exceptions-specifier with prompt $ARGUMENTS[0] <op-name-1> <op-name-2> … — the domain diagram followed by every <op-name> in dirty_ops, space-separated (when dirty_ops is empty, just $ARGUMENTS[0]). The agent processes both fixed commands/queries sides in one call and additionally enriches each passed ops.<op-name>.exceptions.md stub; it auto-skips any side or ops service whose <side>.exceptions.md / ops.<op-name>.exceptions.md is absent (its existing disk-presence contract). Pass only the dirty_ops op-names (not every ops service on disk) so the enricher rewrites exactly the ops services Step 3 just regenerated — a clean ops service has no fragment on disk and is correctly skipped.
Because Step 3 only writes fragments for the dirty side and the dirty ops services, an unaffected side's / clean ops service's <side>.exceptions.md / ops.<op-name>.exceptions.md is not on disk (deleted by the prior specs-generator / merger run), and the enricher leaves that side's <side>.specs.md / ops.<op-name>.specs.md untouched. This is the load-bearing reason per-side / per-service regen requires no contract change to existing agents — the disk-presence check the enricher already performs is exactly the per-side scoping the updater needs.
If the enricher reports a failure, abort and emit a single ERROR: line repeating its message.
After the enricher returns, fan out the merger(s) in parallel for the dirty side(s) and every dirty ops service. Emit the selected Agent calls in a single message:
application-spec:specs-merger with prompt $ARGUMENTS[0] commands (if commands_dirty).application-spec:specs-merger with prompt $ARGUMENTS[0] queries (if queries_dirty).application-spec:specs-merger with prompt $ARGUMENTS[0] ops <op-name> for each <op-name> in dirty_ops.Each commands/queries merger consolidates its side's <side>.deps.md + <side>.methods.md + <side>.exceptions.md into <plugin_dir>/<side>.specs.md (overwriting the prior file) and deletes the consumed fragments. Each ops merger does the same for its ops.<op-name>.{deps,methods,exceptions}.md fragments, writing <plugin_dir>/ops.<op-name>.specs.md with top heading # <X> (the verbatim braced class name read from <dir>/<stem>.ops.<op-name>.md). Any unaffected side / clean ops service's .specs.md is left byte-identical.
If a merger reports a failure, abort and emit a single ERROR: line repeating its message. The other mergers (if running in parallel) may complete; the orchestrator does not roll back.
After all merger(s) return, enumerate the aggregate's ops services so the finder can preserve them. services-finder rewrites services.md in full and no longer self-discovers ops — so it must be handed the op-names, or every ops-contributed service and consumer would be dropped from the report. Glob the surviving merged ops specs via Bash — this reflects the current set after Step 3 deleted any removed_ops specs and Step 5 (re)wrote the dirty_ops specs, so a removed ops service correctly drops out of services.md and a regenerated one is re-read with its (possibly changed) dependency/consumer set:
ls "<plugin_dir>"/ops.*.specs.md 2>/dev/null
For each match, derive <op-name> by stripping the ops. prefix and the .specs.md suffix from the basename (both <stem> and <op-name> are dot-free kebab, so the split is unambiguous). Then invoke application-spec:services-finder with prompt $ARGUMENTS[0] <op-name-1> <op-name-2> … — the domain diagram followed by every enumerated <op-name>, space-separated (when there are none, just $ARGUMENTS[0]). It re-reads the freshly merged commands/queries specs, each passed side's ops.<op-name>.specs.md, and the domain diagram, and rewrites <plugin_dir>/services.md.
This step always runs after Step 5 (regardless of which sides were dirty). Reasons:
## Dependencies → Domain Services bullet, which changes the services report.## Dependencies → External Interfaces bullet on the queries side.<<Service>> lifecycle that was validated against the application diagrams in Tier 1 may still need the report regenerated to drop or re-include the service.services-finder is a pure function of the merged specs + the domain diagram; re-running it on a stable input is byte-stable modulo LLM drift in prose summaries.
If the agent reports a failure, abort and emit a single ERROR: line repeating its message.
Invoke application-spec:application-updates-writer with prompt $ARGUMENTS[0]. It diffs the working-tree specs (commands.specs.md, queries.specs.md, services.md) against git HEAD, classifies the per-section deltas, reads the three on-disk delta reports (<stem>.domain/updates.md, <plugin_dir>/commands-updates.md, <plugin_dir>/queries-updates.md) for axis-tagged Source delta enrichment, derives the ## Affected Artifacts table mechanically, and writes <dir>/<stem>.application/updates.md (always — even on Tier 4 no-op, where every section after ## Summary renders _no changes_ and the Affected Artifacts table has no data rows).
The writer recovers everything it needs from disk + git + the three sibling delta reports; the orchestrator passes nothing else.
This step runs on every successful run, including the Tier 4 no-op early-exit case (Step 2). The consumer's contract (the /application-spec:update-code flow, sequenced by the cross-layer /spec-core:update-code) requires the report to always exist after a successful run.
If the writer reports a failure, abort and emit a single ERROR: line repeating its message. The application specs are already in their final post-update state by this point — re-running the orchestrator (or just the updates writer agent standalone) idempotently produces the report.
Print one summary line. The shape depends on the dispatch outcome.
Build <axis_summary> first — a comma-separated list (in canonical order: domain, commands-diagram, queries-diagram, ops-diagram) of axes that contributed at least one dirty signal. The ops-diagram axis appears when dirty_ops or removed_ops is non-empty. An axis whose contribution was the empty set (disabled, or its triggers all resolved to empty) does not appear.
Tier 4 no-op (commands/queries clean and dirty_ops/removed_ops both empty):
domain.orphan_prose is true: No application spec updates required. Orphan prose changes detected — review <stem>.domain/updates.md. Emitted <stem>.application/updates.md.No application spec updates required (no application-relevant changes on any axis). Emitted <stem>.application/updates.md.At least one side or ops service dirty:
Updated <stem>.application/{<files>} (<dispatch_clause>; triggers: <axis_summary>) and emitted <stem>.application/updates.md.
Where:
<files> is a comma-separated list, in canonical order: commands.specs.md (when commands_dirty), queries.specs.md (when queries_dirty), one ops.<op-name>.specs.md per <op-name> in dirty_ops, services.md (always — Step 6 always runs).<dispatch_clause> joins the active sub-clauses with ; : regenerated commands side / regenerated queries side / regenerated both sides (matching the commands/queries dirty-flag combination, omitted when neither fired), regenerated <N> ops service(s) (when dirty_ops non-empty), and removed <M> ops service(s) (when removed_ops non-empty). At least one sub-clause is always present on this path.<axis_summary> examples: domain, commands-diagram, ops-diagram, domain + ops-diagram, commands-diagram + queries-diagram, domain + commands-diagram + queries-diagram + ops-diagram. Use + (space-plus-space) as the separator.If any preflight axis was disabled (Step 1.dom / 1.cmd / 1.qry 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.
Do not emit additional commentary — each invoked agent already printed its own per-step report. This is the last step — there is no rest-api/messaging re-cascade here. When this skill runs as the application wave of /spec-core:update-specs, that orchestrator runs the rest-api/messaging wave afterward, passing --detectors-fresh because the three detector reports this skill produced at Step 0 are on disk and current (even on the Tier-4 no-op).
ERROR: line repeated verbatim. Any detector report that completed (including the ops report from 0h, or the commands/queries reports from 0g) is left on disk. Re-running after fixing the trigger re-runs all three detectors. No rollback.@application-spec:specs-generator.ERROR: line and exits the workflow. Do not chain further agents on top of a failed step. The orchestrator does not roll back partial writes./spec-core:update-specs, not this skill. When this skill hard-fails, that orchestrator still runs the rest-api/messaging wave (their detector flag is decided by disk state — see /spec-core:update-specs), and those leaves handle a missing/partial detector report themselves. Re-run /application-spec:update-specs (or /spec-core:update-specs) after reconciling the trigger./application-spec:update-specs after fixing the trigger is the supported recovery path — every step is idempotent on stable inputs:
deps-writer ops <op-name>/ops-methods-writer pair per dirty ops service, and a Bash deletion of each removed ops service's spec siblings (output stable modulo LLM nondeterminism).application-exceptions-specifier) is deterministic from method flows + raising-method identity params; idempotent on stable input.specs-merger) is mechanical — concatenates fragments in a fixed order, deletes consumed fragments. Re-running on identical fragments yields identical output.services-finder) regenerates services.md from current inputs; byte-stable on stable inputs modulo LLM prose drift.application-updates-writer) is a pure HEAD-vs-working-tree diff and overwrites updates.md from scratch; reads the three delta reports for source attribution./application-spec:update-specs cannot retry through are the Step 0 missing-input cases (0b–0f; 0a is no longer a failure — an absent domain report degrades the domain axis to no-change with a WARNING) and the total-abort gate (1.all). Each error message directs the operator to the correct fix — diagram-restore-or-rename for the missing input diagrams, @application-spec:specs-generator for everything else.Re-running /application-spec:update-specs against unchanged inputs (working-tree specs unchanged versus HEAD, same domain updates.md, same <stem>.commands.md / <stem>.queries.md) produces:
git diff noise, not a correctness failure).There are no sentinel comments in <plugin_dir>/updates.md beyond those the writer emits per application-spec:updates-report-template. Unlike persistence-spec's <!-- appended-from updates-hash:<hash> --> (which guards the append-only migrations log), every section here is a snapshot — re-running over unchanged inputs simply reproduces the same content.
<stem>.application/{commands,queries}.specs.md or services.md end-to-end — that is @application-spec:specs-generator. In particular it does not invoke a scaffolder (the files already exist).<domain_diagram> and does not invoke (or produce) domain-spec:updates-detector's report — the domain updates.md is consumed if present, and an absent report degrades the domain axis to no-change (Step 0a, with a WARNING) rather than hard-failing.<stem>.md, <stem>.commands.md, <stem>.queries.md) or any Artifacts index — those siblings are linked from the original @application-spec:specs-generator run.surface-markers or messaging-markers categories that may appear on the commands-diagram updates report — those drive /rest-api-spec:update-specs and /messaging-spec:update-specs respectively. This orchestrator ignores them for its own dispatch (no commands_dirty contribution); they are picked up by the rest-api / messaging updaters from the detector reports this skill produces, when /spec-core:update-specs runs those leaves after this skill.save(...) on the command repo, an aggregate-root method renamed under the application diagrams' canonical shape, a referenced <<Service>> removed, a query-repo finder rename that breaks a same-name match, an external-interface operation rename). The methods writers abort with their own one-sentence errors and the orchestrator surfaces them verbatim from Step 3.<side>.specs.md is preserved byte-identically (the chosen approach's main payoff); inside a regenerated side, manual edits are wholesale replaced.<aggregate>_commands.py, <aggregate>_queries.py, the ops service modules <op_snake>.py, infrastructure stubs, test fakes, DI providers, conftest fixtures, application exception classes appended to the domain aggregate's exceptions.py, integration tests) — that is the per-layer /…-spec:update-code flow (sequenced cross-layer by /spec-core:update-code), which consumes the <stem>.application/updates.md and <stem>.application/ops-updates.md this skill emits.--detectors-fresh (it is the producer of all three detector reports, so it always runs the detectors itself; a stray flag is ignored). Cross-layer propagation is owned by /spec-core:update-specs, which runs this skill (its application wave) and then the rest-api/messaging wave, passing those leaves --detectors-fresh because this skill's Step 0 reports are on disk. This skill is independently invocable (the entry point for an application-only change) with identical behaviour either way: it always produces the commands/queries reports at Step 0g and the ops report at Step 0h and regenerates every dirty ops service's spec.