| name | update-code |
| description | Persistence-layer code updater — the gather → implement → review flow that propagates domain/persistence deltas into the command-side repository source, plus the query-side repository patches. Invoke with: /persistence-spec:update-code <domain_diagram> [--review] |
| argument-hint | <domain_diagram> [--review] |
| allowed-tools | Read, Bash, Agent, AskUserQuestion |
You are the persistence-layer code updater. After /update-specs has refreshed <stem>.persistence/updates.md (and <stem>.domain/updates.md), this skill propagates those deltas into the persistence package source via gather → implement → review, plus a query-side phase the command-side chain never sees.
This skill is independently invocable (/persistence-spec:update-code <diagram> [--review]) and is run as part of Wave 2 of /spec-core:update-code (in parallel with application). It reads settled domain source; it edits only the persistence package; it never invokes another plugin.
Inputs & outputs
- Reads
<dir>/<stem>.persistence/updates.md (preflight) and resolves locations via @spec-core:target-locations-finder persistence. The agents own every other read.
- Two implement tracks write durable artifacts:
- Command-side —
@persistence-spec:code-change-writer writes code-changes.md + source edits (driven by code-brief.md).
- Query-side —
@persistence-spec:query-code-change-writer writes query-code-changes.md + source edits, driven by <stem>.domain/updates.md directly. It runs whenever this skill runs (the persistence layer is active by definition), detects the query signal itself, and records a clean no-op when the domain report carries no Query<X>Repository delta. The command-side brief/change chain has no input signal for query-repo concrete methods or invariant clauses — that is this track's job.
Workflow
Step 0 — Parse arguments
$ARGUMENTS carries <domain_diagram> [--review]. Set RUN_REVIEW=true iff --review is present anywhere; strip it and bind $DIAGRAM to the remaining positional. If none remains:
ERROR: /persistence-spec:update-code requires <domain_diagram>. Usage: /persistence-spec:update-code <domain_diagram> [--review]
Step 1 — Preflight
Derive <stem>/<dir> per spec-core:naming-conventions. Read <dir>/<stem>.persistence/updates.md. If missing, hard-fail:
ERROR: <stem>.persistence/updates.md not found. Run `/update-specs <domain_diagram>` before `/update-code`.
The query-side track also requires <dir>/<stem>.domain/updates.md; if it is missing, hard-fail with the same "run /update-specs first" guidance naming the domain report.
Step 2 — Resolve target locations
Invoke @spec-core:target-locations-finder persistence. Capture its table verbatim as <locations_report>. On failure, abort with ERROR: repeating its message.
Step 3 — Phase 1: gather (command-side)
Spawn @persistence-spec:code-brief-writer with prompt $DIAGRAM + <locations_report>. Wait. On hard-fail, abort with ERROR:. Probe test -f <dir>/<stem>.persistence/code-brief.md and bind <command_changed> to its presence (the brief-writer writes nothing on a command-side no-op).
Step 4 — Risk-tag checkpoint
If <command_changed> is false, skip to Step 5. Otherwise count Risk: risky rows in code-brief.md. If zero, proceed. If non-zero, fire one AskUserQuestion:
- Question:
<risky_count> persistence artifact(s) tagged \risky` (e.g. destructive migrations, pattern flips). Proceed?`
- Header:
Risky edits
- Options: 1.
Proceed (recommended) — apply Phase 2. 2. Abort — leave the brief on disk and stop.
On Abort, print and exit cleanly (the query-side track does not run on an abort — a declined checkpoint stops the whole layer):
Aborted persistence at risk checkpoint. Brief preserved at <stem>.persistence/code-brief.md.
Step 5 — Phase 2: implement (command-side)
If <command_changed>, spawn @persistence-spec:code-change-writer with the Phase-1 prompt shape. Wait. Per-artifact Status: failed rows do not abort; an agent-level hard-fail surfaces its ERROR: line (continue to Step 5.5 — the query track is independent).
Step 5.5 — Phase 2.5: implement (query-side)
Always — whether or not the command side changed — spawn @persistence-spec:query-code-change-writer with prompt $DIAGRAM + <locations_report>, after Step 5 has settled (Step 5 may have touched the same SqlAlchemyQuery<X>Repository file; the query track must see that settled state before layering its surgical patches). It reads <stem>.domain/updates.md, applies structural method deltas then invariant-clause patches, and always writes query-code-changes.md (a clean no-op log when there is no query-repo delta). Per-delta failures are logged as Status: failed; only an agent-level hard-fail surfaces an ERROR: line.
Step 6 — Phase 3: review (opt-in)
If RUN_REVIEW and <command_changed>, spawn @persistence-spec:code-review-writer with the Phase-1 prompt shape (it reviews the aggregate persistence file set, including the query repo). On hard-fail, surface its ERROR: line. (A query-only run with no command-side brief is not separately reviewed — the reviewer reads code-brief.md/code-changes.md, which a command-side no-op never produced.)
Step 7 — Outcome line
Bind <A_cmd> = Status: applied rows in code-changes.md (0 if absent); <A_qry> = Status: applied rows in query-code-changes.md. If <command_changed> is false AND <A_qry> == 0, print and exit:
No persistence code updates required.
Otherwise print exactly one outcome line:
Updated persistence code: applied <A_cmd> command + <A_qry> query edit(s)<failed_clause><review_clause>.
<failed_clause> = ; <F> failed summing failed rows across both logs when any exist; <review_clause> = ; reviewed: <clean|issues> from code-review.md when --review ran and the command side was reviewed, else empty.
Failure semantics
- An
ERROR: aborts the step and stops; on-disk artifacts survive. A no-op exit (Step 7) and a risk-gate abort (Step 4) are clean exits — but /spec-core:update-code treats a persistence abort/ERROR as not affecting rest-api/messaging (nothing reads persistence source).
- The command-side and query-side tracks are independent: a command-side hard-fail still lets the query track run, and vice versa. Both may touch
SqlAlchemyQuery<X>Repository; the Step 5-before-5.5 ordering plus the query track's per-method idempotence pre-check (def <name>( present → no-op) is the load-bearing safety against double-adding.
- Idempotent on stable inputs: re-running overwrites briefs/logs and pre-checks edit post-state.
What this skill deliberately does not do
- It does not edit outside the persistence package, read another layer's specs, or invoke another plugin. Cross-layer sequencing is owned by
/spec-core:update-code.
- It does not run migrations, run tests, or format code — those are change-writer concerns.
