edit-design

Reading workflow files (TOC protocol)

When you Read any file under .claude/workflow/ or .claude/skills/, follow the protocol in conventions.md §1.8:

1. Read the TOC region: from <!--Document index start--> to <!--Document index end--> (read to the closing delimiter, not a fixed line count). If the file has no TOC region (a file whose only ## heading is this bootstrap block carries none, per §1.8(d)), read the file in full.
2. Match TOC rows where Roles contains any of your roles (or your role is any, or the row's Roles is any) AND Phases contains any of your phases (or your phase is any, or the row's Phases is any).
3. Use Read(offset, limit) to read only matched sections; if no row matches your role/phase, the file holds nothing for you — do not read further.

Your role: orchestrator, planner, or final-designer (whichever invoked this skill). Your phase: determined by the auto-resume State in workflow.md § Startup Protocol.

Inline refs you find inside workflow files carry the same name:roles:phases suffix; apply file-level filtering before opening: a ref matches when any of your roles is in its roles and any of your phases is in its phases, your own any on either axis matches every ref on that axis, and a ref whose own roles or phases is any matches you. Backtick-wrapped refs carry no suffix; open or skip them at your discretion.

Section	Roles	Phases	Summary
§Two operational modes	orchestrator,planner,final-designer	1,4	Working mode edits the polished design; sync mode re-distills it from the mechanics companion.
§Skill inputs	orchestrator,planner,final-designer	1,4	The mutation kind, target file(s), and edit payload the skill consumes on each invocation.
§Cold-read scope and check-set by mutation kind	orchestrator,planner,final-designer	1,4	The per-mutation-kind table mapping each kind to its target files, cold-read scope, and mechanical check set.
§Workflow	orchestrator,planner,final-designer	1,4	The mutation loop: two shapes — the dual-clean multi-agent loop for the creation kinds, the single-agent loop for the interactive kinds.
§Step 1: Apply the edit	orchestrator,planner,final-designer	1,4	Spawn the code-grounded author for the creation kinds or edit inline for the interactive kinds; stamp only on the creation kinds.
§Step 1.5: Distillation (only for design-sync)	orchestrator,planner,final-designer	1,4	For design-sync only, re-distill the polished design from the current mechanics companion before the cold read.
§Step 2: Determine cold-read scope	orchestrator,planner,final-designer	1,4	Pick the cold-read scope (bounded or whole-doc) for this mutation kind from the check-set table.
§Step 3: Run mechanical checks	orchestrator,planner,final-designer	1,4	Run the mutation kind's mechanical checks (link resolution, stamp position, section presence) before the cold read.
§Step 4: Run the review sub-agents	orchestrator,planner,final-designer	1,4	Spawn the review roles: the per-round pair plus the S3-gated comprehension gate for creation kinds, or the single comprehension read for interactive kinds.
§Step 5: Merge findings	orchestrator,planner,final-designer	1,4	Merge the mechanical-check and review findings into one deduplicated list for the iterate step.
§Step 6: Iterate	orchestrator,planner,final-designer	1,4	Run the dual-clean inner loop for creation kinds or the single-agent fix loop for interactive kinds until findings clear or the cap is reached.
§Step 7: Append to the review log	orchestrator,planner,final-designer	1,4	Append the mutation's record to the design-mutations log, which is itself exempt from stamping.
§Step 8: Auto-suggest sync at N=5 (working mode only)	orchestrator,planner,final-designer	1	In working mode, suggest a design-sync once five mechanics edits have accumulated since the last sync.
§Step 9: Present to the user	orchestrator,planner,final-designer	1,4	Present the merged result and surviving findings to the user as the mutation's final output.
§Staleness reconciliation	orchestrator,planner,final-designer	1,4	The prompt shown when a request references a polished design that mechanics edits have since outpaced.
§Tools used	orchestrator,planner,final-designer	1,4	The tools the skill invokes: the mechanical-check script, Edit/Write, and the author and review-role spawns.
§When NOT to use this skill	orchestrator,planner,final-designer	1,4	The cases that bypass the mutation discipline: non-design files and pure workflow-artifact edits.
§Failure modes and recovery	orchestrator,planner,final-designer	1,4	How the skill recovers when a check fails, the cold read stalls, or the iteration budget is exhausted.
§Examples	orchestrator,planner,final-designer	1,4	Worked examples of a content edit and a section rename run through the full mutation discipline.
§Reference	orchestrator,planner,final-designer	1,4	On-demand pointers to the design-document rules, the file layout, and the mutation-kind definitions.

Apply an edit to design.md (or design-mechanics.md) through the mutation discipline defined in .claude/workflow/design-document-rules.md. The skill bundles (apply edit → auto-review → bounded iterate → present) into one atomic action so the structural rules are self-enforcing. On the creation kinds (phase1-creation, phase4-creation) the skill is a multi-agent orchestrator: it spawns the code-grounded author to write the document and runs the dual-clean inner loop (the cold readability auditor plus a per-round second check) followed by the cold comprehension gate. The interactive kinds keep the original single-agent shape (edit inline, one cold-read, iterate).

Stamp discipline. design.md and design-mechanics.md carry a line-1 <!-- workflow-sha: <40-char SHA> --> stamp written at creation only: by this skill on the phase1-creation and length-trigger-crossing kinds, or by /create-plan's planning-transition step when it seeds design.md directly. Every other mutation kind (content-edit, section-add, section-remove, section-rename, section-move, structural-rewrite, mechanics-edit, design-sync) leaves the stamp untouched and preserves its line-1 position; only creation, migration replay, and no-drift normalization write the stamp. The prepend is performed via Edit/Write against the now-existing file, not a shell redirect. design-mutations.md is deliberately excluded from stamping (see the review-log append step for the rationale). Phase 4 final artifacts (design-final.md, design-mechanics-final.md) are not stamped either; they survive the merge into develop where per-branch migration never applies. Format definition, parser idioms, and the paired SHA-computation idiom that the phase1-creation and length-trigger-crossing kinds copy verbatim are anchored in conventions.md:orchestrator,planner,final-designer:1,3A,3C,4 §1.6. Read that section for the single source of truth.

You MUST use this skill — not raw Edit/Write — for every modification to design.md / design-mechanics.md and for every Phase 4 creation of design-final.md / design-mechanics-final.md. That includes initial creation in Phase 1 (phase1-creation), interactive iteration ("add a section about X"), and Phase 4 production of the final committed artifacts (phase4-creation). The design is frozen after Phase 1 (design-document-rules.md Rule 15), so Phase 3 inline replanning never invokes this skill — replan design intent is recorded in the plan's Decision Records and the track narrative instead (see inline-replanning.md:orchestrator:3A,3C § Process).

Two operational modes

The skill supports two complementary workflows. Pick by where you are in the plan lifecycle:

• Working / sync (Phase 1 and large iterative revisions): mutation kinds phase1-creation, mechanics-edit, design-sync. design.md stays frozen between syncs as a stable reference; cold-read is deferred to sync.
• Direct mutation (small post-publication edits): mutation kinds content-edit, section-add, section-remove, section-rename, section-move, structural-rewrite, length-trigger-crossing. Full discipline runs on every mutation.

Phase 4 special case. Phase 4 produces design-final.md (and design-mechanics-final.md if the original had a mechanics companion). Use the phase4-creation kind — structurally similar to phase1-creation (one-shot creation, full discipline; one or both files depending on whether a mechanics companion is needed) but targeting the *-final.md paths and skipping plan / track-file ref propagation (those refs point at the original design.md, not at the new final artifact). No follow-up mechanics-edit / design-sync cycle: Phase 4 is committed once.

Full rationale, sub-phase diagram, and sync-trigger rules live in design-document-rules.md § Two-mode editing — working vs sync.

Skill inputs

The invoking agent supplies these when calling the skill:

Input	What it carries
design_path	Absolute path to design.md (or design-final.md in Phase 4).
design_mechanics_path	Absolute path to design-mechanics.md (or null if no companion).
plan_path	Absolute path to implementation-plan.md (for **Full design** link resolution).
plan_dir	Absolute path to the plan/ directory containing every plan/track-N.md track file (same purpose — each track file's ## Decision Log may carry **Full design** references that the cross-file ref check has to resolve).
target	design, mechanics, or both — the file(s) the edit touches. Threaded through to the script's --target flag verbatim. (No .md suffix — the script's argparse choices are design/mechanics/both.)
intended_edit	Either (old_string, new_string) for a focused edit, or full new content for a section-add / section-rewrite / file creation.
mutation_kind	One of the values listed in the mode table above.
changed_section	Title of the section being changed (for bounded cold-read scope). For section-rename, supply the new name. Optional for mechanics-edit and design-sync.
iteration_budget	Default 3 — max number of (apply → review) rounds.

If any required input is missing, ask the user before proceeding. The mutation discipline depends on the agent stating the mutation kind explicitly so the cold-read scope and check-set are correct; do not guess.

Cold-read scope and check-set by mutation kind

The --target column reads as a function of whether design-mechanics.md exists at the time of the mutation. When a value is written design \| both, resolve to design if the mutation touches only design.md (the common case for small designs without a mechanics companion) or both if the mutation also propagates into design-mechanics.md.

Mutation kind	Touches	Mechanical script --target	Cold-read scope
phase1-creation	design.md only when the design will not need a mechanics companion (small designs under ~5 sections), or both files when the design will exceed the length trigger / already plans for mechanics	design | both	whole-doc on design.md (mechanics is exempt from cold-read since it's agent-targeted)
mechanics-edit	mechanics only	mechanics	NONE — cold-read deferred to next design-sync
design-sync	both files (re-distill design.md from updated mechanics)	both	whole-doc on design.md, plus mechanics-link-resolution sweep
content-edit	design.md	design	bounded — changed section + 1-2 surrounding sections + Overview + (when present) Core Concepts
section-add	design.md	design	bounded — new section + Overview + (when present) Core Concepts + structure roadmap
section-remove	design.md (+ plan / track-file ref cleanup — **Full design** lines pointing at the removed section must be updated in the same mutation, otherwise **Full design** link resolution fails)	design	whole-doc
section-rename	design.md + (when mechanics exists) the matching section in design-mechanics.md + plan / track-file ref propagation	design | both	whole-doc
section-move	design.md	design	whole-doc
structural-rewrite	design.md + (when mechanics exists and any rename or split propagates) the matching sections in design-mechanics.md	design | both	whole-doc
length-trigger-crossing	both files (split into design-mechanics)	both	whole-doc
phase4-creation	design-final.md + (optional) design-mechanics-final.md	both if mechanics-final exists, else design	whole-doc on design-final.md (mechanics-final is exempt — agent-targeted long-form). Skip plan / track-file ref propagation: omit --plan-path / --plan-dir so the cross-file ref check is naturally skipped.

Periodic whole-doc check. Independent of mode: every Nth design-touching mutation (default N=5, counted from the review log) escalates the cold-read scope to whole-doc regardless of the kind. mechanics-edit mutations do NOT increment this counter.

Two distinct N=5 counters. Both fire at "5", but they count different things and trigger different actions; do not collapse them mentally:

Counter	Counts	Resets on	Triggers
Periodic whole-doc counter	All mutation log entries except mechanics-edit	Never resets — running modulo over the log	Cold-read scope is escalated to whole-doc for the current mutation, regardless of its declared scope
Working-mode counter	mechanics-edit entries since the most recent design-sync (or since phase1-creation if no sync has happened yet)	Resets to 0 on every design-sync	The skill surfaces "5 mechanics edits have accumulated since the last sync — want me to run design-sync?" at the next conversational turn (Step 8)

See design-document-rules.md:planner,final-designer:1,4 § Mutation discipline § Cold-read scope by mutation kind for the canonical statement of both counters.

Workflow

The high-level steps are the same across all mutation kinds; what differs is who does the work inside the apply and review steps, and how the cold-read pass is gated. Two shapes run under one frame:

• The creation kinds (phase1-creation and phase4-creation) run the dual-clean multi-agent loop. Step 1 spawns the code-grounded author instead of authoring inline; Step 4 spawns the per-round readability-auditor plus its second per-round check (the warm absorption check at phase1-creation, the fidelity check at phase4-creation), then, after the inner loop converges, the cold comprehension gate; Step 6 is the bounded dual-clean inner loop. These are the kinds the design-creation callers route through: create-plan Step 4a routes phase1-creation, create-final-design.md routes phase4-creation.
• Every other (interactive) mutation kind keeps the single-agent shape. Step 1 applies the edit inline; Step 4 spawns the cold comprehension gate (plus, on design-sync only, a cold readability-auditor prose pass so the re-distilled human-facing prose keeps its one prose owner, S4); Step 6 iterates on the merged findings. These kinds touch a frozen, already-reviewed design.md post-publication, so the author spawn buys nothing and the lighter loop is correct.

There is no in-skill adversarial pass on any kind. The decision/assumption challenge for phase1-creation was relocated onto the research log at the Phase 0 → 1 gate (D6, prompts/adversarial-review.md §Research-log-scoped review (Phase 0→1)), so for phase1-creation the Step 4 cold comprehension gate is gated behind that log-adversarial gate clearing (the S3 freeze-order gate; see Step 4) rather than preceded by a local adversarial step. Every other mutation kind runs its cold-read with no gate.

Step 1: Apply the edit

The apply step has two shapes. The creation kinds (phase1-creation, phase4-creation) spawn the code-grounded author to write the document; the skill never writes the seed content inline. Every interactive mutation kind (content-edit, section-add, section-remove, section-rename, section-move, structural-rewrite, length-trigger-crossing, mechanics-edit, design-sync) applies the edit inline with Edit/Write as before — read the target file first to satisfy the Edit precondition, then apply the focused edit or full-file rewrite. The stamp directives below apply to both shapes (the author writes content; the skill owns the line-1 stamp).

Spawn the author for the creation kinds. For phase1-creation and phase4-creation, decide the companion-file shape and the seed scope exactly as described below, then hand that decision to the design-author agent rather than writing the content yourself. The author is the sole writer of the document (.claude/agents/design-author.md): it reads the research log and the live codebase through PSI — never this authoring conversation — and drafts cold-readable prose for a reader who has only the finished document. The author write happens on round 1 of the inner loop and again on each later round against the auditor's flagged passages; the spawn mechanics, the params-file contract, and the ground-once-with-targeted-re-grounding lever live in Step 6 (the inner loop) where the per-round author re-spawn is wired. On round 1 the author writes the full seed; Step 1's job is to settle the companion-file and seed-scope decision the round-1 author spawn carries.

For phase1-creation: decide first whether the design needs a mechanics companion. Default is single file. Most designs (under ~5 sections, no # Part N headings, no anticipated long-form derivations) seed only design.md — pass target=design and leave design_mechanics_path=null. The author seeds design.md with Overview (concept-first elevator pitch), Core Concepts (when the doc will have Parts or ≥3 new domain terms), Class Design, Workflow, and TL;DR-shaped Part sections.

Seed both files only when the design genuinely needs the split — typically when the user has signaled it up front ("this will have a mechanics companion") or when a single-file seed would already exceed the 2,000-line / 50,000-token length trigger. In that case, pass target=both and design_mechanics_path=<abs path>; the author seeds design-mechanics.md with the long-form mechanism content that supports each design.md section, with section names matching between the two files from the start. A design that doesn't need mechanics on day 1 crosses into one later via length-trigger-crossing, not by retroactively re-running phase1-creation.

Stamp the seeded file(s) with an idempotency guard. Apply this directive after the initial Write lands the seeded content on disk; the presence check then runs against the just-written file. A missing file is treated identically to an unstamped file. phase1-creation is the canonical writer for design.md (and design-mechanics.md when target=both), but /create-plan's planning-transition step also writes design.md directly from its own template with the stamp already in place. Both invocation paths converge here, so the directive below must stamp an unstamped file and skip the prepend on an already-stamped one.

For each path the kind touches (design_path; design_mechanics_path as well when target=both), run the presence check from conventions.md:orchestrator,planner,final-designer:1,3A,3C,4 §1.6(a1):

head -1 <path> | grep -qE '<!-- workflow-sha: [0-9a-f]{40} -->'

A zero exit code means the file is already stamped — skip the prepend for that path (this is the post-/create-plan case, where design.md's line 1 already carries the stamp written by the planning-transition step's template, or the target=both case where /create-plan seeded the dual files and both files already carry the stamp). A non-zero exit code means the file is unstamped — compute $WORKFLOW_SHA via the §1.6(b) paired idiom and prepend <!-- workflow-sha: $WORKFLOW_SHA --> (followed by a newline) above the H1, then re-read the file to satisfy the next Edit precondition:

WORKFLOW_SHA="$(git log -1 --format=%H HEAD -- .claude/workflow .claude/skills .claude/agents)"
[ -z "$WORKFLOW_SHA" ] && WORKFLOW_SHA="$(git rev-parse HEAD)"

Compute $WORKFLOW_SHA at most once per invocation — when both paths need a stamp (a direct phase1-creation invocation outside /create-plan with target=both), reuse the same value so the two sibling files start life with matching stamps. The guard is symmetric across design_path and design_mechanics_path: a same-invocation run where /create-plan pre-stamped one file and the other was added after (an edge case the guard tolerates by design) is handled by the per-path presence check.

Cross-session target=both may produce non-matching stamps on design.md and design-mechanics.md when the phase1-creation invocation lands in a later session than /create-plan's preamble. The drift gate's no-drift normalization collapses the divergence on the next clean gate run, and the per-branch migration reunifies the stamps end-of-migration.

For phase4-creation: same as phase1-creation — the author writes the document — but the file paths are design-final.md and (optional) design-mechanics-final.md, and the content reflects what was actually built (not the planned design). The author grounds on the step and track episodes and the live code rather than the research log (the Phase 4 second check is fidelity, not absorption; see Step 6). The caller (prompts/create-final-design.md) is expected to have run the PSI-backed verification tables before invoking the skill, so each diagram element traces to a real code location. Do not pass --plan-path / --plan-dir (the cross-file ref check is naturally skipped; see the table above). Skip the idempotency-guarded stamp directive above. Phase 4 final artifacts are not stamped: see the Stamp-discipline blockquote at the top of this file and conventions.md §1.6(f).