@hegemonart/get-design-done 1.41.5 → 1.43.0

package/skills/benchmark/SKILL.md

@@ -18,22 +18,22 @@ conventions are at `../../reference/shared-preamble.md#output-contract-reminders
 |------------|--------|
 | `/gdd:benchmark <component>` | Harvest + synthesize a single component |
 | `/gdd:benchmark --wave <N>` | Run a full wave (1 = Inputs, 2 = Containers, etc.) |
-| `/gdd:benchmark --list` | Show corpus coverage — which specs exist, which are pending |
+| `/gdd:benchmark --list` | Show corpus coverage - which specs exist, which are pending |
 | `/gdd:benchmark --refresh <component>` | Re-harvest a spec (for design-system version bumps) |
 
 ## Single-Component Flow (`/gdd:benchmark <component>`)
 
-1. **Check if spec exists** — `Glob("reference/components/<component>.md")`. If found and `--refresh` was not passed, confirm before overwriting.
+1. **Check if spec exists** - `Glob("reference/components/<component>.md")`. If found and `--refresh` was not passed, confirm before overwriting.
 
-2. **Harvest** — spawn `component-benchmark-harvester` with required-reading `@connections/design-corpora.md`, target component, raw-output path `.planning/benchmarks/raw/<component>.md`, and a salvage hint to `.planning/research/impeccable-salvage/`. Acceptance: raw harvest exists with ≥4 source sections.
+2. **Harvest** - spawn `component-benchmark-harvester` with required-reading `@connections/design-corpora.md`, target component, raw-output path `.planning/benchmarks/raw/<component>.md`, and a salvage hint to `.planning/research/impeccable-salvage/`. Acceptance: raw harvest exists with ≥4 source sections.
 
-3. **Synthesize** — spawn `component-benchmark-synthesizer` with required-reading `@.planning/benchmarks/raw/<component>.md`, `@reference/components/TEMPLATE.md`, `@reference/anti-patterns.md`. Output: `reference/components/<component>.md`. Also update `reference/components/README.md` (add entry in correct category). Acceptance: spec ≤350 lines, cites ≥4 systems, follows `TEMPLATE.md` sections, has a WAI-ARIA keyboard contract + a failing-example block.
+3. **Synthesize** - spawn `component-benchmark-synthesizer` with required-reading `@.planning/benchmarks/raw/<component>.md`, `@reference/components/TEMPLATE.md`, `@reference/anti-patterns.md`. Output: `reference/components/<component>.md`. Also update `reference/components/README.md` (add entry in correct category). Acceptance: spec ≤350 lines, cites ≥4 systems, follows `TEMPLATE.md` sections, has a WAI-ARIA keyboard contract + a failing-example block.
 
-4. **Report** — print spec path, line count, systems cited.
+4. **Report** - print spec path, line count, systems cited.
 
 ## Wave Mode (`/gdd:benchmark --wave <N>`)
 
-Read the wave definition from `reference/components/README.md` and run each component sequentially (not parallel — each harvest is network-bound and the raw files are large).
+Read the wave definition from `reference/components/README.md` and run each component sequentially (not parallel - each harvest is network-bound and the raw files are large).
 
 | Wave | Components |
 |------|-----------|
@@ -52,7 +52,7 @@ Same as single-component flow but skips the "already exists" guard. Use when a d
 
 ## Source List
 
-`../../connections/design-corpora.md` — 18 design systems with canonical URLs, licensing, and fallback chain (canonical → archive.org → Refero MCP → Pinterest MCP).
+`../../connections/design-corpora.md` - 18 design systems with canonical URLs, licensing, and fallback chain (canonical → archive.org → Refero MCP → Pinterest MCP).
 
 ## Output Artifacts
 

package/skills/bootstrap-ds/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gdd-bootstrap-ds
-description: "Bootstraps a design system for a GREENFIELD project that has none — no Figma, no tokens, no component library. Takes a brand input (primary color + optional secondary + tone tags + target framework) and emits a coherent OKLCH token system (color tints, modular type scale, 4pt/8pt spacing, radius + motion defaults) in 3 variants to pick from, then scaffolds proof components (button/input/card). Use at the start of a brand-new project, or when /gdd:discover finds no existing design system. Never invents a brand; never overwrites an existing DS."
+description: "Bootstraps a design system for a GREENFIELD project that has none - no Figma, no tokens, no component library. Takes a brand input (primary color + optional secondary + tone tags + target framework) and emits a coherent OKLCH token system (color tints, modular type scale, 4pt/8pt spacing, radius + motion defaults) in 3 variants to pick from, then scaffolds proof components (button/input/card). Use at the start of a brand-new project, or when /gdd:discover finds no existing design system. Never invents a brand; never overwrites an existing DS."
 argument-hint: "[--primary <color>] [--secondary <color>] [--tone <tags>] [--framework web|native-ios|native-android|flutter]"
 user-invocable: true
 tools: Read, Write, Bash, Glob, Grep, AskUserQuestion, Task
@@ -8,31 +8,31 @@ tools: Read, Write, Bash, Glob, Grep, AskUserQuestion, Task
 
 # /gdd:bootstrap-ds
 
-Greenfield design-system bootstrap. Closes the gap that GDD's `design-context-builder` assumes a design system already exists (in code or Figma) — a brand-new project has none. This skill is the **front door**: it collects a brand input and hands it to `agents/ds-generator.md`, which emits the token system + proof components per `reference/ds-bootstrap-rubric.md` (deterministic math in `scripts/lib/ds/token-scale.cjs`).
+Greenfield design-system bootstrap. Closes the gap that GDD's `design-context-builder` assumes a design system already exists (in code or Figma) - a brand-new project has none. This skill is the **front door**: it collects a brand input and hands it to `agents/ds-generator.md`, which emits the token system + proof components per `reference/ds-bootstrap-rubric.md` (deterministic math in `scripts/lib/ds/token-scale.cjs`).
 
 ## When to use
 
 - At the start of a brand-new project (no `tailwind.config`, no token file, no DS).
 - When `/gdd:discover` / `design-context-builder` reports **no existing design system** and the user opts to bootstrap one.
 
-If a design system **already exists**, do NOT run this — defer to `design-context-builder` (it maps the existing one). State that and stop.
+If a design system **already exists**, do NOT run this - defer to `design-context-builder` (it maps the existing one). State that and stop.
 
 ## Steps
 
 1. **Collect the brand input.** From flags, or via `AskUserQuestion` for anything missing:
-   - **primary** (required) — the brand color (hex / rgb / `oklch()`).
-   - **secondary** (optional) — a second brand color (emitted only if supplied — the rubric's ≤2-brand-colors rule).
-   - **tone tags** (optional) — `calm` / `corporate` / `editorial` / `playful` / `bold` (maps to the type ratio + chroma treatment).
-   - **target framework** (optional) — `web` (default) / `native-ios` / `native-android` / `flutter`. Detect from the project if absent (Phase 34 routing).
+   - **primary** (required) - the brand color (hex / rgb / `oklch()`).
+   - **secondary** (optional) - a second brand color (emitted only if supplied - the rubric's ≤2-brand-colors rule).
+   - **tone tags** (optional) - `calm` / `corporate` / `editorial` / `playful` / `bold` (maps to the type ratio + chroma treatment).
+   - **target framework** (optional) - `web` (default) / `native-ios` / `native-android` / `flutter`. Detect from the project if absent (Phase 34 routing).
 2. **Delegate to `ds-generator`** (via `Task`): it resolves the primary to OKLCH, runs `token-scale.cjs` for **3 variants** (conservative / balanced / bold), and presents them.
 3. **Pick a variant.** Surface the 3 variants (primary `500`, type ratio, spacing baseline, radius, feel); the user picks ONE.
 4. **Emit + scaffold (proposal → confirm).** `ds-generator` emits the chosen token set (role-named CSS custom properties + the framework mapping) and scaffolds **button / input / card** as a coherence proof. Nothing is written to `src/` without confirmation.
 
 ## Do Not
 
-- Do not invent a brand (no logomark, no typeface choice, no third brand color) — emit a token *system*, not an identity.
-- Do not overwrite an existing design system — defer to `design-context-builder`.
-- Do not add a color-conversion dependency — `token-scale.cjs` emits native CSS `oklch()`.
+- Do not invent a brand (no logomark, no typeface choice, no third brand color) - emit a token *system*, not an identity.
+- Do not overwrite an existing design system - defer to `design-context-builder`.
+- Do not add a color-conversion dependency - `token-scale.cjs` emits native CSS `oklch()`.
 
 ## Output
 

package/skills/brief/SKILL.md

@@ -5,7 +5,7 @@ argument-hint: "[--re-brief to redo intake on existing project]"
 tools: Read, Write, AskUserQuestion, mcp__gdd_state__frontmatter_update, mcp__gdd_state__set_status, mcp__gdd_state__update_progress, mcp__gdd_state__get
 ---
 
-# Get Design Done — Brief
+# Get Design Done - Brief
 
 **Role:** You are the Brief stage. Stage 1 of 5 in the get-design-done pipeline.
 
@@ -13,7 +13,7 @@ tools: Read, Write, AskUserQuestion, mcp__gdd_state__frontmatter_update, mcp__gd
 
 ---
 
-## Step 1 — Check for existing BRIEF.md
+## Step 1 - Check for existing BRIEF.md
 
 1. Read `.design/BRIEF.md` if it exists.
 2. Parse it into sections: Problem, Audience, Constraints, Success Metrics, Scope.
@@ -21,19 +21,19 @@ tools: Read, Write, AskUserQuestion, mcp__gdd_state__frontmatter_update, mcp__gd
 4. If `--re-brief` flag is passed, ignore existing answers and ask all five questions.
 5. Otherwise, only ask questions for unanswered sections.
 
-## Step 2 — Interview
+## Step 2 - Interview
 
 Ask the following one at a time using `AskUserQuestion`, only for unanswered sections:
 
-1. **Problem** — "What design problem are we solving? (user-facing outcome)"
-2. **Audience** — "Who is the primary audience? (role, device, context)"
-3. **Constraints** — "What constraints apply? (tech stack, brand, time, a11y requirements)"
-4. **Success Metrics** — "How will we measure success? (specific metrics or outcomes)"
-5. **Scope** — "What is in/out of scope for this cycle?"
+1. **Problem** - "What design problem are we solving? (user-facing outcome)"
+2. **Audience** - "Who is the primary audience? (role, device, context)"
+3. **Constraints** - "What constraints apply? (tech stack, brand, time, a11y requirements)"
+4. **Success Metrics** - "How will we measure success? (specific metrics or outcomes)"
+5. **Scope** - "What is in/out of scope for this cycle?"
 
 Do not proceed to the next question until the current one is answered.
 
-## Step 3 — Write .design/BRIEF.md
+## Step 3 - Write .design/BRIEF.md
 
 Write the brief with these sections, preserving any pre-existing answers:
 
@@ -62,15 +62,15 @@ Write the brief with these sections, preserving any pre-existing answers:
 </prior-research>
 ```
 
-Leave the `<prior-research>` block empty on a greenfield brief — it is filled by `/gdd:research-sync` (the `user-research-synthesizer`) when a research source is connected, and re-checked at verify. See `reference/design-variants.md` for the outcome loop.
+Leave the `<prior-research>` block empty on a greenfield brief - it is filled by `/gdd:research-sync` (the `user-research-synthesizer`) when a research source is connected, and re-checked at verify. See `reference/design-variants.md` for the outcome loop.
 
-## Step 4 — Bootstrap STATE.md (if missing)
+## Step 4 - Bootstrap STATE.md (if missing)
 
 <!-- BOOTSTRAP EXCEPTION: STATE.md does not exist yet — MCP tools require it to exist. Direct Write is intentional. All subsequent mutations use MCP. -->
 
-If `.design/STATE.md` does not exist, copy the template block from `reference/STATE-TEMPLATE.md` (between `==== BEGIN TEMPLATE ====` and `==== END TEMPLATE ====`) to `.design/STATE.md` via `Write`. Leave the `<ISO 8601 timestamp>` placeholders in-place — Step 5 stamps them via MCP. If STATE.md already exists, skip to Step 5.
+If `.design/STATE.md` does not exist, copy the template block from `reference/STATE-TEMPLATE.md` (between `==== BEGIN TEMPLATE ====` and `==== END TEMPLATE ====`) to `.design/STATE.md` via `Write`. Leave the `<ISO 8601 timestamp>` placeholders in-place - Step 5 stamps them via MCP. If STATE.md already exists, skip to Step 5.
 
-## Step 5 — Commit STATE.md initialization
+## Step 5 - Commit STATE.md initialization
 
 With `.design/STATE.md` seeded from the template:
 
@@ -78,16 +78,16 @@ With `.design/STATE.md` seeded from the template:
 2. Mark brief progress: call `mcp__gdd_state__update_progress` with `task_progress: "5/5"`, `status: "brief_complete"`.
 3. Set handoff status: call `mcp__gdd_state__set_status` with `status: "brief_complete"`.
 
-Do NOT call `mcp__gdd_state__transition_stage` from brief — explore calls it on entry, keeping the transition atomic with the stage that owns the new state.
+Do NOT call `mcp__gdd_state__transition_stage` from brief - explore calls it on entry, keeping the transition atomic with the stage that owns the new state.
 
-## Step 6 — Inline glossary (CONTEXT.md) + ADR pointer
+## Step 6 - Inline glossary (CONTEXT.md) + ADR pointer
 
 When a fuzzy phrase is resolved or a new domain concept is named during the briefing
 interview: write to `./CONTEXT.md` IMMEDIATELY per `./../../reference/context-md-format.md`
 (H2 heading + body; lazy-create on first term; no batching). Glossary entries compound
-across cycles — token savings + naming consistency.
+across cycles - token savings + naming consistency.
 
-Project-shaping decisions surfaced in briefing can be promoted to an ADR — see
+Project-shaping decisions surfaced in briefing can be promoted to an ADR - see
 `./../../reference/adr-format.md` for the 3-criteria gate (hard-to-reverse AND
 surprising-without-context AND real-tradeoff). Routine choices stay in STATE.md.
 
@@ -112,16 +112,16 @@ Run this final spec-quality pass over `.design/BRIEF.md` before the brief→expl
 Do NOT transition to explore (or invoke `/gdd:explore`) until the brief artifact (default `.design/BRIEF.md`) is committed AND the user has approved it. If this project uses a custom `.design` location, read the artifact path from `.design/STATE.md` rather than assuming the default.
 </HARD-GATE>
 
-## Rationalizations — Thought to Reality
+## Rationalizations - Thought to Reality
 
 The excuses an agent invents to skip or shortcut the brief, and what each one actually costs the cycle:
 
 | Thought | Reality |
 |---------|---------|
 | "This brief is too simple to need a problem statement." | Skip the brief = guess at requirements, then redesign mid-design when the real problem surfaces. |
-| "The user told me what to build, I can skip the interview." | Unasked constraints (a11y, brand, stack) become rework — the five questions exist because each one has blown a past cycle. |
+| "The user told me what to build, I can skip the interview." | Unasked constraints (a11y, brand, stack) become rework - the five questions exist because each one has blown a past cycle. |
 | "I'll capture success metrics later in verify." | Verify has nothing to check against; an un-metricked brief produces an un-verifiable cycle. |
-| "Scope is obvious, I don't need an in/out line." | Undeclared scope is scope creep waiting to happen — the explore scan widens to fill the vacuum. |
+| "Scope is obvious, I don't need an in/out line." | Undeclared scope is scope creep waiting to happen - the explore scan widens to fill the vacuum. |
 | "I can answer all five questions for the user from context." | AskUserQuestion one-at-a-time exists because batched/assumed answers smuggle in wrong premises that compound downstream. |
 | "STATE.md bootstrap can wait." | Every later MCP mutation requires STATE.md to exist; skipping the bootstrap hard-blocks explore on entry. |
 

package/skills/budget/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gdd-budget
-description: "Forecasts GDD design-cycle spend before the bill arrives. Reads .design/telemetry/costs.jsonl (cost per cycle) + .design/budget.json (the project_cap), runs the pure cost-forecast model via agents/cost-forecaster.md, and projects the next N cycles — surfacing 'at the current rate you'll hit your $X project cap in Y cycles.' Supports --scenario best|typical|worst and --cycles N. Read-only — it forecasts and warns; it never spends, edits budget.json, or halts (the budget-enforcer hook halts). Use to sanity-check spend trajectory before a long run."
+description: "Forecasts GDD design-cycle spend before the bill arrives. Reads .design/telemetry/costs.jsonl (cost per cycle) + .design/budget.json (the project_cap), runs the pure cost-forecast model via agents/cost-forecaster.md, and projects the next N cycles - surfacing 'at the current rate you'll hit your $X project cap in Y cycles.' Supports --scenario best|typical|worst and --cycles N. Read-only - it forecasts and warns; it never spends, edits budget.json, or halts (the budget-enforcer hook halts). Use to sanity-check spend trajectory before a long run."
 argument-hint: "[--cycles N] [--scenario best|typical|worst]"
 user-invocable: true
 tools: Read, Bash, Grep, Glob, ToolSearch, Task
@@ -10,7 +10,7 @@ tools: Read, Bash, Grep, Glob, ToolSearch, Task
 
 Closes the long-horizon cost gap: Phase 10.1 per-task caps + Phase 26 per-runtime telemetry track
 *cost*, but nothing **forecasts** it. This skill projects the next N cycles of spend and tells you how
-many cycles you have before you hit your `project_cap`. **Read-only** — it forecasts and warns; it
+many cycles you have before you hit your `project_cap`. **Read-only** - it forecasts and warns; it
 never spends, never edits `budget.json`, and never halts (the Phase 25 budget-enforcer hook is the
 only thing that blocks a spawn). Contract: `../../reference/cost-governance.md`.
 
@@ -30,11 +30,11 @@ only thing that blocks a spawn). Contract: `../../reference/cost-governance.md`.
    `scripts/lib/budget/cost-forecast.cjs` model for the requested `--scenario`/`--cycles`, reads
    `project_cap_usd` from `.design/budget.json`, and computes cycles-to-cap.
 3. **Render.** Show: the scenario + its per-cycle rate, the best↔worst band, the projected total over
-   N cycles, and — when `project_cap_usd > 0` — **"at the `<scenario>` rate (~$X/cycle) you'll reach
+   N cycles, and - when `project_cap_usd > 0` - **"at the `<scenario>` rate (~$X/cycle) you'll reach
    your $`<cap>` project cap in `<Y>` cycles"** (or "not at this rate" when the trend is flat/down).
    When no cap is set, show the trajectory and note that `project_cap_usd` is unset (so the hook won't
    halt).
-4. **Do not act.** Never raise/lower the cap, never spend — GDD forecasts; the human sets the budget.
+4. **Do not act.** Never raise/lower the cap, never spend - GDD forecasts; the human sets the budget.
 
 ## Output
 

package/skills/cache-manager/SKILL.md

@@ -10,14 +10,14 @@ disable-model-invocation: true
 
 ## Role
 
-You are the deterministic cache-key computer and cache-manifest writer for the optimization layer. You do not spawn agents, and you do not make model calls. You read agent paths, input file paths, and input file contents; you compute a stable SHA-256 key; you look that key up in `.design/cache-manifest.json`; you return a hit (cached result + `cache_hit: true`) or a miss. On spawn completion, the orchestrator calls you again to persist the result. You are Layer B of the two-layer cache (D-08). Layer A — Anthropic's 5-min prompt cache — is not owned by you; it's owned by the shared-preamble ordering convention in `agents/README.md`.
+You are the deterministic cache-key computer and cache-manifest writer for the optimization layer. You do not spawn agents, and you do not make model calls. You read agent paths, input file paths, and input file contents; you compute a stable SHA-256 key; you look that key up in `.design/cache-manifest.json`; you return a hit (cached result + `cache_hit: true`) or a miss. On spawn completion, the orchestrator calls you again to persist the result. You are Layer B of the two-layer cache (D-08). Layer A - Anthropic's 5-min prompt cache - is not owned by you; it's owned by the shared-preamble ordering convention in `agents/README.md`.
 
 ## Invocation Contract
 
 ### Phase 1: compute-key
 
-- **Input**: `{agent_path: string, input_file_paths: string[]}` — `agent_path` is the absolute or repo-relative path to the `agents/<name>.md` file; `input_file_paths` is the sorted-unique list of files the agent will read.
-- **Output**: `{input_hash: string}` — 64-character lowercase SHA-256 hex.
+- **Input**: `{agent_path: string, input_file_paths: string[]}` - `agent_path` is the absolute or repo-relative path to the `agents/<name>.md` file; `input_file_paths` is the sorted-unique list of files the agent will read.
+- **Output**: `{input_hash: string}` - 64-character lowercase SHA-256 hex.
 - **Algorithm**: canonicalize inputs, concat with newline separators, SHA-256 (see Deterministic Input-Hash Algorithm below).
 
 ### Phase 2: lookup
@@ -33,18 +33,18 @@ You are the deterministic cache-key computer and cache-manifest writer for the o
 
 ### Phase 4: write-result-on-completion
 
-- **Input**: `{input_hash: string, agent: string, result: string, ttl_seconds: number}` — `ttl_seconds` defaults to `.design/budget.json.cache_ttl_seconds` (3600 if budget.json absent).
+- **Input**: `{input_hash: string, agent: string, result: string, ttl_seconds: number}` - `ttl_seconds` defaults to `.design/budget.json.cache_ttl_seconds` (3600 if budget.json absent).
 - **Behavior**: open `.design/cache-manifest.json` (create if missing), set key `input_hash` → `{agent, result, written_at, ttl_seconds, expires_at}`, write file. `written_at` is `new Date().toISOString()`. `expires_at` is `written_at + ttl_seconds` as ISO.
 
 ## Deterministic Input-Hash Algorithm
 
-The canonical reference implementation (single source of truth; `hooks/budget-enforcer.js` imports the same primitive via a shared helper) lives in `./cache-policy.md#deterministic-input-hash-algorithm-layer-b` — it documents the JS implementation, the maintainer notes (sorted-unique paths, MISSING-file sentinel, agent-path bust behavior), the manifest shape, and TTL semantics in one place. Conform to the algorithm exactly so the hook and any orchestrator agree byte-for-byte.
+The canonical reference implementation (single source of truth; `hooks/budget-enforcer.js` imports the same primitive via a shared helper) lives in `./cache-policy.md#deterministic-input-hash-algorithm-layer-b` - it documents the JS implementation, the maintainer notes (sorted-unique paths, MISSING-file sentinel, agent-path bust behavior), the manifest shape, and TTL semantics in one place. Conform to the algorithm exactly so the hook and any orchestrator agree byte-for-byte.
 
 ## Integration Points
 
 - **`hooks/budget-enforcer.js`** (Plan 10.1-01) reads the manifest on every Agent spawn. The hook already calls `cacheLookup(agent, inputHash)` against `.design/cache-manifest.json`. This skill is the authority on how `inputHash` is computed so the hook and any orchestrator agree byte-for-byte.
 - **Orchestrators** (e.g., `skills/map/`, `skills/discover/`, `skills/plan/`) invoke Phase 1 (compute-key) + Phase 4 (write-result-on-completion) around each Agent spawn they launch. Phase 2 + Phase 3 are executed by the hook.
-- **Warm-cache command** (`skills/warm-cache/SKILL.md`, Task 02) does not touch Layer B — it only primes Anthropic's 5-min prompt cache (Layer A). Do not confuse the two.
+- **Warm-cache command** (`skills/warm-cache/SKILL.md`, Task 02) does not touch Layer B - it only primes Anthropic's 5-min prompt cache (Layer A). Do not confuse the two.
 
 ## Failure Modes
 

package/skills/cache-manager/cache-policy.md

@@ -16,8 +16,8 @@ so the SKILLs stay under the 100-line cap.
 
 The two layers (D-08):
 
-- **Layer A** — Anthropic's 5-min prompt cache (owned by `warm-cache`). Keyed on shared-preamble-first prompt prefix. No project-local state.
-- **Layer B** — explicit `.design/cache-manifest.json` (owned by `gdd-cache-manager`). Keyed on deterministic SHA-256 of `(agent-path, sorted-input-file-paths, input-content-hashes)`. Per-repo state.
+- **Layer A** - Anthropic's 5-min prompt cache (owned by `warm-cache`). Keyed on shared-preamble-first prompt prefix. No project-local state.
+- **Layer B** - explicit `.design/cache-manifest.json` (owned by `gdd-cache-manager`). Keyed on deterministic SHA-256 of `(agent-path, sorted-input-file-paths, input-content-hashes)`. Per-repo state.
 
 ## Deterministic Input-Hash Algorithm (Layer B)
 
@@ -56,9 +56,9 @@ function computeInputHash(agentPath, inputFilePaths) {
 
 Notes for maintainers:
 
-- **Sorted-unique paths** — ordering must be stable; caller is expected to de-duplicate. If the same path appears twice the hash still matches as long as caller pre-dedupes before invoking.
-- **Missing file** — the string `MISSING` is used in place of the content hash so a missing dependency doesn't silently collide with an empty file (empty file's SHA-256 is `e3b0c44...`). Missing-file hashes naturally miss on the next read because the real file has a different content hash.
-- **Agent-path** — agents changing their own body (role, tools, output contract) invalidate all their cache entries automatically because the agent file's content is not hashed; but the `agent_path` string is concatenated. Upgrading agents between versions naturally busts the cache only when the path changes. Plan 10.1-04 (shared preamble extraction) is expected to slightly adjust agent bodies — consumers should treat the first post-10.1 run as a full cache miss, which is the intended behavior.
+- **Sorted-unique paths** - ordering must be stable; caller is expected to de-duplicate. If the same path appears twice the hash still matches as long as caller pre-dedupes before invoking.
+- **Missing file** - the string `MISSING` is used in place of the content hash so a missing dependency doesn't silently collide with an empty file (empty file's SHA-256 is `e3b0c44...`). Missing-file hashes naturally miss on the next read because the real file has a different content hash.
+- **Agent-path** - agents changing their own body (role, tools, output contract) invalidate all their cache entries automatically because the agent file's content is not hashed; but the `agent_path` string is concatenated. Upgrading agents between versions naturally busts the cache only when the path changes. Plan 10.1-04 (shared preamble extraction) is expected to slightly adjust agent bodies - consumers should treat the first post-10.1 run as a full cache miss, which is the intended behavior.
 
 ## Manifest Shape (Layer B)
 

package/skills/check-update/SKILL.md

@@ -14,7 +14,7 @@ tools: Read, Write, Bash, Task
 | Flag | Effect |
 |------|--------|
 | *(none)* | Print cached state. If cache is older than 24h, trigger `--refresh` implicitly. |
-| `--refresh` | Invoke `hooks/update-check.sh --refresh` — bypasses the 24h TTL and re-fetches immediately. |
+| `--refresh` | Invoke `hooks/update-check.sh --refresh` - bypasses the 24h TTL and re-fetches immediately. |
 | `--dismiss` | Write `update_dismissed: "<latest_tag>"` to `.design/config.json` atomically and delete `.design/update-available.md`. Sticky until a newer release ships. |
 | `--prompt` | Spawn `design-update-checker` agent (Haiku) to produce a 3–5-line "what this release changes for you" summary. Does not alter the banner or cache. |
 
@@ -34,7 +34,7 @@ Flags combine: `--refresh --prompt` is valid (re-fetch, then enrich). `--dismiss
 
 3. **Read cache.** After any optional refresh, read `.design/update-cache.json`. If missing: print `No cache. Network may be unreachable or the hook has not run yet. Try /gdd:check-update --refresh.` and exit.
 
-4. **`--dismiss` path** (if set): Compute new config contents and write atomically via the env-prefix Python heredoc pattern below. The pattern is load-bearing — passing variables as trailing `KEY=VALUE` argv treats them as `sys.argv`, not `os.environ`. Use env-prefix form only.
+4. **`--dismiss` path** (if set): Compute new config contents and write atomically via the env-prefix Python heredoc pattern below. The pattern is essential - passing variables as trailing `KEY=VALUE` argv treats them as `sys.argv`, not `os.environ`. Use env-prefix form only.
 
     ```bash
     CONFIG_PATH=".design/config.json"
@@ -86,10 +86,10 @@ Flags combine: `--refresh --prompt` is valid (re-fetch, then enrich). `--dismiss
 
 ## Do Not
 
-- Do not fetch from GitHub directly — always go through `hooks/update-check.sh --refresh` so caching + state-guard + dismissal logic stays in one place.
+- Do not fetch from GitHub directly - always go through `hooks/update-check.sh --refresh` so caching + state-guard + dismissal logic stays in one place.
 - Do not modify `.design/update-available.md` except to delete on `--dismiss`.
-- Do not rewrite `.design/config.json` wholesale — the atomic Python rewrite preserves every unknown key (D-14).
-- Do not pass variables to the Python heredoc via trailing `KEY=VALUE` argv — env-prefix form only.
+- Do not rewrite `.design/config.json` wholesale - the atomic Python rewrite preserves every unknown key (D-14).
+- Do not pass variables to the Python heredoc via trailing `KEY=VALUE` argv - env-prefix form only.
 
 ## Completion marker
 

package/skills/compare/SKILL.md

@@ -5,7 +5,7 @@ argument-hint: ""
 user-invocable: true
 ---
 
-# gdd-compare — Baseline vs Result Delta
+# gdd-compare - Baseline vs Result Delta
 
 Standalone delta command. Computes the difference between the scan baseline (`DESIGN.md`) and the verification result (`DESIGN-VERIFICATION.md`), and flags design drift for any regression not covered by an explicit task in `DESIGN-PLAN.md`. Writes one artifact: `.design/COMPARE-REPORT.md`.
 
@@ -15,10 +15,10 @@ For the full step-by-step methodology (score parsing, set arithmetic for anti-pa
 
 ## Scope
 
-This command is **standalone** — not a pipeline stage:
+This command is **standalone** - not a pipeline stage:
 
 - Scoped strictly to delta between two existing files (COMP-02): `DESIGN.md` (baseline, from scan) and `DESIGN-VERIFICATION.md` (result, from verify).
-- Does NOT require or implement a snapshot mechanism — multi-run history is deferred to V2-06.
+- Does NOT require or implement a snapshot mechanism - multi-run history is deferred to V2-06.
 - Does NOT mutate any pipeline artifact (`DESIGN.md`, `DESIGN-VERIFICATION.md`, `DESIGN-SUMMARY.md`, `DESIGN-CONTEXT.md`, `DESIGN-PLAN.md`, `.design/STATE.md`).
 - Writes exactly ONE file: `.design/COMPARE-REPORT.md`.
 - Output artifact prefix `COMPARE-REPORT` is distinct from the pipeline namespace (`DESIGN-*.md`). No naming conflict.
@@ -27,15 +27,15 @@ This command is **standalone** — not a pipeline stage:
 
 ## Pre-Flight Checks (Pitfall 3)
 
-Required files — abort if either is missing:
+Required files - abort if either is missing:
 
 - `.design/DESIGN.md` missing → `"No baseline found. Run /get-design-done scan first."`
 - `.design/DESIGN-VERIFICATION.md` missing → `"No verification result found. Run /get-design-done verify first to produce DESIGN-VERIFICATION.md."`
 
 **Optional files (graceful degradation if absent):**
 
-- `.design/DESIGN-CONTEXT.md` — used for must-have delta. If missing, skip the Must-Have Status section and emit note: `"Must-have delta skipped: DESIGN-CONTEXT.md not found."`
-- `.design/DESIGN-PLAN.md` — used for drift detection. If missing, skip DRIFT flagging and emit note: `"Drift detection skipped: no DESIGN-PLAN.md."`
+- `.design/DESIGN-CONTEXT.md` - used for must-have delta. If missing, skip the Must-Have Status section and emit note: `"Must-have delta skipped: DESIGN-CONTEXT.md not found."`
+- `.design/DESIGN-PLAN.md` - used for drift detection. If missing, skip DRIFT flagging and emit note: `"Drift detection skipped: no DESIGN-PLAN.md."`
 
 Confirm `.design/` directory exists. If absent: `mkdir -p .design/`.
 
@@ -45,13 +45,13 @@ Probe `preview` connection per `../../reference/shared-preamble.md#connection-ha
 
 ## Workflow
 
-1. **Parse Category Scores** — extract baseline + result score tables, normalize names, flag unmatched. Detail: `./compare-rubric.md#step-1--parse-category-scores`.
-2. **Compute Score Delta** — `delta = result - baseline`, classify (`improvement`/`no_change`/`regression`). Detail: `./compare-rubric.md#step-2--compute-score-delta-comp-03`.
-3. **Anti-Pattern Delta** — set arithmetic on baseline vs result anti-pattern sets (resolved / new / unchanged). Detail: `./compare-rubric.md#step-3--anti-pattern-delta`.
-4. **Must-Have Pass/Fail Change** — read `<must_haves>` from `DESIGN-CONTEXT.md`, status from `DESIGN-VERIFICATION.md`. Detail: `./compare-rubric.md#step-4--must-have-passfail-change`.
-5. **Design Drift Detection (COMP-04)** — build coverage map from `DESIGN-PLAN.md` `Type:` fields; for each `regression` not in coverage_map → emit `DRIFT: [category] ...`. Detail: `./compare-rubric.md#step-5--design-drift-detection-comp-04`.
-6. **Screenshot Delta (preview: available only)** — capture per-route screenshots to `.design/screenshots/{before,after}/<route>.png`. Detail: `./compare-rubric.md#step-5b--screenshot-delta-when-preview-available`.
-7. **Write `.design/COMPARE-REPORT.md`** — full template at `./compare-rubric.md#step-6--compare-reportmd-template`.
+1. **Parse Category Scores** - extract baseline + result score tables, normalize names, flag unmatched. Detail: `./compare-rubric.md#step-1--parse-category-scores`.
+2. **Compute Score Delta** - `delta = result - baseline`, classify (`improvement`/`no_change`/`regression`). Detail: `./compare-rubric.md#step-2--compute-score-delta-comp-03`.
+3. **Anti-Pattern Delta** - set arithmetic on baseline vs result anti-pattern sets (resolved / new / unchanged). Detail: `./compare-rubric.md#step-3--anti-pattern-delta`.
+4. **Must-Have Pass/Fail Change** - read `<must_haves>` from `DESIGN-CONTEXT.md`, status from `DESIGN-VERIFICATION.md`. Detail: `./compare-rubric.md#step-4--must-have-passfail-change`.
+5. **Design Drift Detection (COMP-04)** - build coverage map from `DESIGN-PLAN.md` `Type:` fields; for each `regression` not in coverage_map → emit `DRIFT: [category] ...`. Detail: `./compare-rubric.md#step-5--design-drift-detection-comp-04`.
+6. **Screenshot Delta (preview: available only)** - capture per-route screenshots to `.design/screenshots/{before,after}/<route>.png`. Detail: `./compare-rubric.md#step-5b--screenshot-delta-when-preview-available`.
+7. **Write `.design/COMPARE-REPORT.md`** - full template at `./compare-rubric.md#step-6--compare-reportmd-template`.
 
 ---
 
@@ -61,7 +61,7 @@ This command MUST NOT (per `../../reference/shared-preamble.md#output-contract-r
 
 - Write to `DESIGN.md`, `DESIGN-VERIFICATION.md`, `DESIGN-SUMMARY.md`, `DESIGN-CONTEXT.md`, `DESIGN-PLAN.md`, or `.design/STATE.md`.
 - Require or implement a snapshot system (V2-06 deferred).
-- Reinterpret or silently normalize category names that do not match between files — report mismatches in the Notes section.
+- Reinterpret or silently normalize category names that do not match between files - report mismatches in the Notes section.
 - Invoke `design-auditor` or any other pipeline agent.
 - Produce more than one output file: `.design/COMPARE-REPORT.md`.
 
@@ -77,6 +77,6 @@ After writing `.design/COMPARE-REPORT.md`, print a summary:
 Compare complete. Improvements: N. Regressions: M. Drift flags: K. See .design/COMPARE-REPORT.md.
 ```
 
-Where `N` = improvement count, `M` = regression count, `K` = DRIFT-flag count (0 if drift detection was skipped or no regressions). Do not summarize individual issues — the file contains the full detail.
+Where `N` = improvement count, `M` = regression count, `K` = DRIFT-flag count (0 if drift detection was skipped or no regressions). Do not summarize individual issues - the file contains the full detail.
 
 ## COMPARE COMPLETE

package/skills/compare/compare-rubric.md

@@ -7,24 +7,24 @@ tags: [compare, delta, drift, scoring, rubric, extracted]
 last_updated: 2026-05-18
 ---
 
-Source: extracted from `skills/compare/SKILL.md` (Phase 28.5 rework — D-10 extract-then-link).
-The skill's load-bearing workflow stays in `../skills/compare/SKILL.md`; this file holds the
+Source: extracted from `skills/compare/SKILL.md` (Phase 28.5 rework - D-10 extract-then-link).
+The skill's essential workflow stays in `../skills/compare/SKILL.md`; this file holds the
 delta-computation methodology, anti-pattern set arithmetic, drift-detection coverage map,
 and the `COMPARE-REPORT.md` template the skill writes.
 
-# Compare Rubric — Baseline vs Result Delta Methodology
+# Compare Rubric - Baseline vs Result Delta Methodology
 
-Detailed methodology for the `gdd-compare` standalone command — companion to
+Detailed methodology for the `gdd-compare` standalone command - companion to
 `../skills/compare/SKILL.md`. Read this file when executing a specific compare step (score
 delta math, anti-pattern set arithmetic, drift coverage map, report layout). The SKILL.md
-keeps the load-bearing pre-flight checks + step routing; this file holds the deep methodology.
+keeps the essential pre-flight checks + step routing; this file holds the deep methodology.
 
 See `./shared-preamble.md#output-contract-reminders` for the per-skill output discipline and
 `./audit-scoring.md` for the 0–10 category-scoring rubric the delta is computed against.
 
 ---
 
-## Step 1 — Parse Category Scores
+## Step 1 - Parse Category Scores
 
 **Extract baseline scores from `.design/DESIGN.md`:** locate the category score table (rows like `| Accessibility | 6/10 | ... |`). Parse each row: extract category name + numeric score. Store as `baseline_scores` map.
 
@@ -40,18 +40,18 @@ See `./shared-preamble.md#output-contract-reminders` for the per-skill output di
 - Result-only → flag `[UNMATCHED-RESULT]`, exclude from score delta.
 - Report all unmatched categories in the Notes section. Do NOT silently paper over mismatches.
 
-## Step 2 — Compute Score Delta (COMP-03)
+## Step 2 - Compute Score Delta (COMP-03)
 
 For each matched category: `delta = result_scores[category] - baseline_scores[category]`.
 
 Classify:
-- `improvement` — delta > 0
-- `no_change` — delta == 0
-- `regression` — delta < 0
+- `improvement` - delta > 0
+- `no_change` - delta == 0
+- `regression` - delta < 0
 
 Record per category: name, baseline score, result score, signed delta, classification. Collect regressed categories for drift detection in Step 5.
 
-## Step 3 — Anti-Pattern Delta
+## Step 3 - Anti-Pattern Delta
 
 Enumerate anti-patterns in both files (entries identified by BAN-*, SLOP-*, or labeled as anti-patterns). Collect identifiers or descriptions as sets.
 
@@ -70,13 +70,13 @@ unchanged = intersection of both sets
 
 Report all three groups in the output report.
 
-## Step 4 — Must-Have Pass/Fail Change
+## Step 4 - Must-Have Pass/Fail Change
 
 **Skip condition:** if `.design/DESIGN-CONTEXT.md` is absent → emit note and skip this section.
 
 Read `<must_haves>` from `DESIGN-CONTEXT.md` (each must-have has ID + description). Read pass/fail status from `DESIGN-VERIFICATION.md` (must-have status table). For each must-have: record `pass`, `fail`, or `not-evaluated`. If `DESIGN.md` contained a prior must-have status section, compute the change (`pass→fail`, `fail→pass`); otherwise report current status only.
 
-## Step 5 — Design Drift Detection (COMP-04)
+## Step 5 - Design Drift Detection (COMP-04)
 
 **Skip condition:** if `.design/DESIGN-PLAN.md` is absent → emit `"Drift detection skipped: DESIGN-PLAN.md not found."` in the Drift section.
 
@@ -95,9 +95,9 @@ Category-to-Type matching is case-insensitive and normalized.
 
 Emit `"No drift detected. All regressed categories are covered by tasks in DESIGN-PLAN.md."` if all regressed categories are covered. Emit `"No drift detected. No score regressions found."` if no regressions in Step 2.
 
-## Step 5B — Screenshot Delta (when preview: available)
+## Step 5B - Screenshot Delta (when preview: available)
 
-Check `preview` status from `.design/STATE.md <connections>` (written by the probe at stage entry — see `./shared-preamble.md#connection-handshake-summary`).
+Check `preview` status from `.design/STATE.md <connections>` (written by the probe at stage entry - see `./shared-preamble.md#connection-handshake-summary`).
 
 **If `preview: available`:**
 
@@ -110,7 +110,7 @@ Check `preview` status from `.design/STATE.md <connections>` (written by the pro
 
 **If `preview: unavailable` or `preview: not_configured`:** emit exactly `Screenshot delta skipped — preview not configured.`
 
-## Step 6 — COMPARE-REPORT.md Template
+## Step 6 - COMPARE-REPORT.md Template
 
 Output path: `.design/COMPARE-REPORT.md`. This file MUST NOT be written to any pipeline-reserved path.
 
@@ -168,4 +168,4 @@ If a section has no items (e.g., no anti-patterns in baseline), write "None."
 
 ---
 
-*Imported by: `../skills/compare/SKILL.md`. Maintained as part of Phase 28.5 (Bucket 2 rework — D-10).*
+*Imported by: `../skills/compare/SKILL.md`. Maintained as part of Phase 28.5 (Bucket 2 rework - D-10).*

package/skills/complete-cycle/SKILL.md

@@ -11,7 +11,7 @@ Closes the current cycle: marks CYCLES.md entry complete, archives pipeline arti
 
 ## Steps
 
-1. **Load state**: Read `.design/STATE.md` for the active `cycle:` ID. If empty/missing, error: "No active cycle — nothing to complete."
+1. **Load state**: Read `.design/STATE.md` for the active `cycle:` ID. If empty/missing, error: "No active cycle - nothing to complete."
 2. **Retrospective**: If no argument was passed, ask (AskUserQuestion): "Is cycle <N> complete? Briefly describe what was achieved." Capture for CYCLES.md.
 3. **Update CYCLES.md**: Find the current cycle entry, change `**Status**: active` to `**Status**: complete`, append a `**Retrospective**: <note>` line and `**Ended**: <date>`.
 4. **Archive artifacts**: Create `.design/archive/cycle-N/` via Bash `mkdir -p`. Copy these files into it (if present):
@@ -21,7 +21,7 @@ Closes the current cycle: marks CYCLES.md entry complete, archives pipeline arti
    - `DESIGN-VERIFICATION.md`
    - `DESIGN-AUDIT.md`
    - `DESIGN-SUMMARY.md`
-   Mark originals with a `<!-- archived to .design/archive/cycle-N/ -->` note at top (do not delete — next cycle will overwrite).
+   Mark originals with a `<!-- archived to .design/archive/cycle-N/ -->` note at top (do not delete - next cycle will overwrite).
 5. **Generate EXPERIENCE.md** (Haiku-tier writer step): Read cycle STATE decisions + `.design/DESIGN-VERIFICATION.md` (if present) + any `.design/reflections/*.md` from this cycle. Write `.design/archive/cycle-N/EXPERIENCE.md` using this structure (~100–200 lines, declarative-fact framing, prepend `reference/cycle-handoff-preamble.md` content):
 
    ```markdown
@@ -65,10 +65,10 @@ Closes the current cycle: marks CYCLES.md entry complete, archives pipeline arti
 
 ## Do Not
 
-- Do not delete source files in `src/` — only archive `.design/` artifacts.
-- Do not auto-start a new cycle — user invokes `/gdd:new-cycle` explicitly.
+- Do not delete source files in `src/` - only archive `.design/` artifacts.
+- Do not auto-start a new cycle - user invokes `/gdd:new-cycle` explicitly.
 
-## Step 6 — Update notice (post-closeout surface)
+## Step 6 - Update notice (post-closeout surface)
 
 After the archive has been written and STATE.md has been cleared for the next cycle, emit the plugin-update banner if one is present:
 

package/skills/connections/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gdd-connections
-description: "Interactive onboarding wizard for the 33 external integrations the pipeline supports — probes all (`figma`, `refero`, `preview`, `storybook`, `chromatic`, `graphify`, `pinterest`, `claude-design`, `paper-design`, `pencil-dev`, `21st-dev`, `magic-patterns`, `lazyweb`, `mobbin`, `slack`, `discord`, `linear`, `jira`, `notion`, `lottie`, `rive`, `framer`, `penpot`, `webflow`, `v0-dev`, `plasmic`, `builder-io`, `launchdarkly`, `statsig`, `growthbook`, `usertesting`, `maze`, `hotjar`), recommends based on project type, walks the user through setup (auto-run MCP install or copy-command fallback), writes results to `STATE.md <connections>`. Use after `/gdd:new-project` or whenever the user wants to add, inspect, or skip a connection. Re-runnable anytime."
+description: "Interactive onboarding wizard for the 33 external integrations the pipeline supports - probes all (`figma`, `refero`, `preview`, `storybook`, `chromatic`, `graphify`, `pinterest`, `claude-design`, `paper-design`, `pencil-dev`, `21st-dev`, `magic-patterns`, `lazyweb`, `mobbin`, `slack`, `discord`, `linear`, `jira`, `notion`, `lottie`, `rive`, `framer`, `penpot`, `webflow`, `v0-dev`, `plasmic`, `builder-io`, `launchdarkly`, `statsig`, `growthbook`, `usertesting`, `maze`, `hotjar`), recommends based on project type, walks the user through setup (auto-run MCP install or copy-command fallback), writes results to `STATE.md <connections>`. Use after `/gdd:new-project` or whenever the user wants to add, inspect, or skip a connection. Re-runnable anytime."
 argument-hint: "[list | <connection-name> | --auto]"
 user-invocable: true
 tools: Read, Write, Bash, Glob, Grep, AskUserQuestion, ToolSearch
@@ -29,21 +29,21 @@ For the 33 probe scripts (MCP + HTTP + CLI + file probes), bucket categorization
 
 ## State Integration
 
-1. Read `.design/STATE.md` — if missing, that's fine; this skill does not require a pipeline run.
-2. Read `.design/config.json` — if missing, use defaults. If `connections_onboarding` block is present with `pending_verification`, this is a resume — see Step 6.
-3. Read `connections.skip[]` from config — never re-prompt for skipped connections.
+1. Read `.design/STATE.md` - if missing, that's fine; this skill does not require a pipeline run.
+2. Read `.design/config.json` - if missing, use defaults. If `connections_onboarding` block is present with `pending_verification`, this is a resume - see Step 6.
+3. Read `connections.skip[]` from config - never re-prompt for skipped connections.
 4. Update `last_checkpoint` in STATE.md at skill exit if STATE.md exists.
 
 ---
 
 ## Workflow
 
-1. **Probe all 33 connections** — run every probe script per `./connections-onboarding.md#step-1--probe-all-33-connections`. MCP probes use `ToolSearch` first; HTTP / CLI / file probes follow non-MCP patterns. Merge results into `STATE.md <connections>` with the three-value schema (`available | unavailable | not_configured`) — never add new values.
-2. **Categorize + build summary** — bucket each probe result (available / recommended / optional / skipped / unavailable) using project-hint detection. Detail + recommendation mapping: `./connections-onboarding.md#step-2--bucket-categorization`.
-3. **Print summary table** — show buckets + value-prop one-liners (verbatim from `./connections-onboarding.md#step-3--summary-table`).
-4. **Route by mode** — `list` / `--auto` exits after summary; `<name>` jumps straight to Step 5; default mode opens an AskUserQuestion (configure recommended / pick one by one / configure all optional / re-check specific / exit). Routing detail: `./connections-onboarding.md#step-4--route-by-mode`.
-5. **Per-connection setup screen** — for each target: read `connections/<name>.md`, present the setup screen, AskUserQuestion (run now / copy-paste / skip / never ask). Auto-run only if reversible (see eligibility matrix). On success: append name to `connections_onboarding.pending_verification[]`. Detail: `./connections-onboarding.md#step-5--per-connection-setup-screen`.
-6. **Verification pass** — re-probe every name in `pending_verification[]`. Available → remove. `not_configured` → leave (needs session restart). `unavailable` → leave + note OAuth needed. Print "Setup complete" summary. Detail: `./connections-onboarding.md#step-6--verification-pass`.
+1. **Probe all 33 connections** - run every probe script per `./connections-onboarding.md#step-1--probe-all-33-connections`. MCP probes use `ToolSearch` first; HTTP / CLI / file probes follow non-MCP patterns. Merge results into `STATE.md <connections>` with the three-value schema (`available | unavailable | not_configured`) - never add new values.
+2. **Categorize + build summary** - bucket each probe result (available / recommended / optional / skipped / unavailable) using project-hint detection. Detail + recommendation mapping: `./connections-onboarding.md#step-2--bucket-categorization`.
+3. **Print summary table** - show buckets + value-prop one-liners (verbatim from `./connections-onboarding.md#step-3--summary-table`).
+4. **Route by mode** - `list` / `--auto` exits after summary; `<name>` jumps straight to Step 5; default mode opens an AskUserQuestion (configure recommended / pick one by one / configure all optional / re-check specific / exit). Routing detail: `./connections-onboarding.md#step-4--route-by-mode`.
+5. **Per-connection setup screen** - for each target: read `connections/<name>.md`, present the setup screen, AskUserQuestion (run now / copy-paste / skip / never ask). Auto-run only if reversible (see eligibility matrix). On success: append name to `connections_onboarding.pending_verification[]`. Detail: `./connections-onboarding.md#step-5--per-connection-setup-screen`.
+6. **Verification pass** - re-probe every name in `pending_verification[]`. Available → remove. `not_configured` → leave (needs session restart). `unavailable` → leave + note OAuth needed. Print "Setup complete" summary. Detail: `./connections-onboarding.md#step-6--verification-pass`.
 
 If `.design/config.json > connections_onboarding.pending_verification[]` is non-empty at entry → enter **resume flow**: run Step 6 immediately; if clean, exit; otherwise fall through to Step 3. Detail: `./connections-onboarding.md#resumability`.
 
@@ -58,7 +58,7 @@ Per `./connections-onboarding.md#do-not`:
 - Never run `claude mcp add` without explicit `"Run install command now"` confirmation.
 - Never auto-restart the Claude Code session.
 - Never re-prompt for names in `connections.skip[]`.
-- Never overwrite existing `<connections>` entries that this skill did not probe — merge only.
+- Never overwrite existing `<connections>` entries that this skill did not probe - merge only.
 
 ---