npm - @hegemonart/get-design-done - Versions diffs - 1.28.0 → 1.28.5 - Mend

@hegemonart/get-design-done 1.28.0 → 1.28.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (98) hide show

package/.claude-plugin/marketplace.json +2 -2
package/.claude-plugin/plugin.json +1 -1
package/CHANGELOG.md +78 -0
package/SKILL.md +1 -1
package/hooks/gdd-decision-injector.js +149 -3
package/package.json +1 -1
package/reference/adr-format.md +96 -0
package/reference/apply-reflections-procedure.md +68 -0
package/reference/architecture-vocabulary.md +102 -0
package/reference/cache-policy.md +126 -0
package/reference/compare-rubric.md +171 -0
package/reference/connections-onboarding.md +417 -0
package/reference/context-md-format.md +106 -0
package/reference/darkmode-audit-procedure.md +258 -0
package/reference/debug-feedback-loops.md +119 -0
package/reference/design-procedure.md +304 -0
package/reference/discover-procedure.md +204 -0
package/reference/explore-procedure.md +267 -0
package/reference/health-mcp-detection.md +44 -0
package/reference/health-skill-length-report.md +69 -0
package/reference/heuristics.md +84 -0
package/reference/milestone-completeness-rubric.md +87 -0
package/reference/peer-cli-protocol.md +161 -0
package/reference/plan-procedure.md +278 -0
package/reference/registry.json +169 -1
package/reference/registry.schema.json +1 -1
package/reference/router-rules.md +84 -0
package/reference/scan-procedure.md +731 -0
package/reference/shared-preamble.md +78 -6
package/reference/skill-authoring-contract.md +128 -0
package/reference/start-procedure.md +115 -0
package/reference/style-doc-procedure.md +150 -0
package/reference/threat-modeling.md +101 -0
package/reference/verify-procedure.md +512 -0
package/scripts/validate-skill-length.cjs +283 -0
package/skills/add-backlog/SKILL.md +1 -0
package/skills/analyze-dependencies/SKILL.md +33 -122
package/skills/apply-reflections/SKILL.md +1 -40
package/skills/audit/SKILL.md +3 -1
package/skills/bandit-status/SKILL.md +31 -66
package/skills/benchmark/SKILL.md +15 -55
package/skills/brief/SKILL.md +12 -1
package/skills/cache-manager/SKILL.md +3 -57
package/skills/check-update/SKILL.md +38 -75
package/skills/compare/SKILL.md +29 -269
package/skills/complete-cycle/SKILL.md +1 -1
package/skills/connections/SKILL.md +21 -427
package/skills/continue/SKILL.md +1 -0
package/skills/darkmode/SKILL.md +32 -287
package/skills/debug/SKILL.md +11 -8
package/skills/design/SKILL.md +27 -245
package/skills/discover/SKILL.md +26 -133
package/skills/discuss/SKILL.md +18 -2
package/skills/explore/SKILL.md +40 -205
package/skills/fast/SKILL.md +1 -0
package/skills/figma-write/SKILL.md +2 -2
package/skills/health/SKILL.md +11 -33
package/skills/help/SKILL.md +1 -0
package/skills/list-assumptions/SKILL.md +1 -0
package/skills/map/SKILL.md +8 -31
package/skills/new-cycle/SKILL.md +3 -1
package/skills/next/SKILL.md +1 -0
package/skills/note/SKILL.md +1 -0
package/skills/optimize/SKILL.md +21 -44
package/skills/pause/SKILL.md +1 -0
package/skills/peer-cli-add/SKILL.md +26 -108
package/skills/peer-cli-customize/SKILL.md +22 -42
package/skills/peers/SKILL.md +33 -57
package/skills/plan/SKILL.md +33 -220
package/skills/plant-seed/SKILL.md +1 -0
package/skills/pr-branch/SKILL.md +1 -0
package/skills/progress/SKILL.md +1 -7
package/skills/quality-gate/SKILL.md +34 -166
package/skills/quick/SKILL.md +1 -0
package/skills/reapply-patches/SKILL.md +1 -0
package/skills/recall/SKILL.md +1 -0
package/skills/resume/SKILL.md +1 -0
package/skills/review-backlog/SKILL.md +1 -0
package/skills/router/SKILL.md +3 -59
package/skills/scan/SKILL.md +36 -675
package/skills/settings/SKILL.md +1 -0
package/skills/ship/SKILL.md +1 -0
package/skills/sketch/SKILL.md +1 -1
package/skills/sketch-wrap-up/SKILL.md +13 -54
package/skills/spike/SKILL.md +1 -1
package/skills/spike-wrap-up/SKILL.md +12 -46
package/skills/start/SKILL.md +13 -112
package/skills/stats/SKILL.md +1 -0
package/skills/style/SKILL.md +18 -140
package/skills/synthesize/SKILL.md +1 -0
package/skills/timeline/SKILL.md +1 -0
package/skills/todo/SKILL.md +1 -0
package/skills/turn-closeout/SKILL.md +36 -56
package/skills/undo/SKILL.md +1 -0
package/skills/update/SKILL.md +1 -0
package/skills/verify/SKILL.md +42 -457
package/skills/warm-cache/SKILL.md +3 -35
package/skills/zoom-out/SKILL.md +26 -0

package/reference/darkmode-audit-procedure.md ADDED Viewed

@@ -0,0 +1,258 @@
+---
+name: darkmode-audit-procedure
+type: meta-rules
+version: 1.0.0
+phase: 28.5
+tags: [darkmode, dark-mode, contrast, audit, procedure, extracted]
+last_updated: 2026-05-18
+---
+Source: extracted from `skills/darkmode/SKILL.md` (Phase 28.5 rework — D-10 extract-then-link).
+The skill's load-bearing routing + decision tree stays in `../skills/darkmode/SKILL.md`; this
+file holds the architecture-detection greps, contrast computation, anti-pattern grep
+snippets, and the `DARKMODE-AUDIT.md` report template.
+# Dark Mode Audit Procedure
+Detailed procedure for the `get-design-done:darkmode` standalone audit — companion to
+`../skills/darkmode/SKILL.md`. Read this file when executing a specific audit step
+(architecture detection, contrast computation, anti-pattern grep, report layout). The
+SKILL.md keeps the load-bearing pre-flight + step routing; this file holds the deep
+methodology.
+For the perceptual layer (APCA / WCAG 3 draft) sitting on top of the WCAG 2.1 ratios used
+in Step 2, see `./contrast-advanced.md`. For modern OKLCH-based dark token-pair generation,
+see `./color-theory.md` §OKLCH. For the cross-skill output discipline + connection-probe
+pattern, see `./shared-preamble.md#output-contract-reminders` and
+`./shared-preamble.md#connection-handshake-summary`.
+---
+## Step 1: Architecture Detection (DARK-02)
+Run all three architecture greps against `$SRC_ROOT`. Use `2>/dev/null` on each to suppress missing-directory errors.
+```bash
+# Architecture 1: CSS custom properties with dark media query
+arch1_count=$(grep -rEn "prefers-color-scheme.*dark|\.dark[[:space:]]*\{" "$SRC_ROOT" \
+  --include="*.css" --include="*.scss" 2>/dev/null | wc -l)
+# Architecture 2: Tailwind dark: prefix
+arch2_count=$(grep -rEn "dark:[a-z]" "$SRC_ROOT" \
+  --include="*.tsx" --include="*.jsx" --include="*.html" 2>/dev/null | wc -l)
+# Architecture 3: JS class toggle on <html> / <body>
+arch3_count=$(grep -rEn "classList.*dark|setAttribute.*dark|document\.documentElement" "$SRC_ROOT" \
+  --include="*.ts" --include="*.tsx" --include="*.js" 2>/dev/null | wc -l)
+```
+**Classification rules:**
+| Condition | Classification |
+|-----------|---------------|
+| All three counts < 3 | No dark mode — abort: "No dark mode implementation detected — nothing to audit." |
+| Exactly one count ≥ 3 | Primary architecture = that one |
+| Two or more counts ≥ 5 | Hybrid (list all detected architectures) |
+| One count ≥ 3, others < 5 | Primary = highest count |
+Record `ARCH_DETECTED` as one of: `Architecture 1 (CSS custom props)`, `Architecture 2 (Tailwind dark:)`, `Architecture 3 (JS class toggle)`, or `Hybrid`.
+---
+## Step 2: Contrast Audit (DARK-03)
+For the detected architecture, enumerate color token + background token pairs used in dark context, then compute WCAG contrast ratios.
+**Token extraction by architecture:**
+**Architecture 1 (CSS custom props):**
+```bash
+grep -rEn "\.dark[[:space:]]*\{|prefers-color-scheme.*dark" "$SRC_ROOT" \
+  --include="*.css" --include="*.scss" -A 30 2>/dev/null \
+  | grep -E "^\s*--[a-z].*:\s*#[0-9a-fA-F]{3,8}|^\s*--[a-z].*:\s*rgb"
+```
+**Architecture 2 (Tailwind dark:):**
+```bash
+grep -rEhon "dark:(bg|text)-[a-z0-9-]+" "$SRC_ROOT" \
+  --include="*.tsx" --include="*.jsx" --include="*.html" 2>/dev/null | sort -u
+```
+**Architecture 3 (JS class toggle):**
+```bash
+grep -rEn "\.dark[[:space:]]*\{" "$SRC_ROOT" \
+  --include="*.css" --include="*.scss" -A 30 2>/dev/null \
+  | grep -E "color|background"
+```
+**WCAG contrast computation:**
+Use the linearized-sRGB formula from `agents/design-executor.md` Type: accessibility (pre-calibrated — do not re-derive):
+1. Convert each hex channel to linear light: `c_lin = (c/255 ≤ 0.04045) ? c/255/12.92 : ((c/255 + 0.055)/1.055)^2.4`
+2. Relative luminance: `L = 0.2126 * R_lin + 0.7152 * G_lin + 0.0722 * B_lin`
+3. Contrast ratio: `(L_lighter + 0.05) / (L_darker + 0.05)`
+**Thresholds:**
+| Text type | Min ratio | Fail severity |
+|-----------|-----------|---------------|
+| Body text (< 18pt or < 14pt bold) | 4.5:1 | P0 (critical) |
+| Large text (≥ 18pt or ≥ 14pt bold) | 3:1 | P1 (major) |
+| UI component boundaries | 3:1 | P1 (major) |
+Flag every pair that fails its threshold. Include token names, hex values, computed ratio, and required ratio in the fix description.
+For pairs that pass WCAG 2.1 but feel wrong perceptually (thin mid-gray text, large saturated text, saturated-on-saturated), cross-check with the APCA Lc thresholds in `./contrast-advanced.md` and annotate `[APCA-mismatch]` in the fix description.
+---
+## Step 3: Token Override Completeness (DARK-04)
+Check that every light-mode color token has a corresponding dark-mode override.
+**Enumerate light-mode tokens:**
+```bash
+grep -rEhon "var\(--color-[a-z0-9-]+\)" "$SRC_ROOT" \
+  --include="*.css" --include="*.scss" --include="*.tsx" --include="*.jsx" 2>/dev/null \
+  | grep -oE "\-\-color-[a-z0-9-]+" | sort -u
+grep -rEhon "(bg|text|border|ring)-[a-z]+-[0-9]+" "$SRC_ROOT" \
+  --include="*.tsx" --include="*.jsx" 2>/dev/null | sort -u
+```
+**Check dark overrides (architecture-specific):**
+- Arch 1: Token appears in `.dark { --color-* }` block or `@media (prefers-color-scheme: dark) { --color-* }`
+- Arch 2: A `dark:` prefixed variant of the Tailwind class exists in the same file or a shared layout
+- Arch 3: Token appears in the dark CSS block activated by JS class toggle
+**Flag:** Any light-mode color token with no dark override → P1 (major). For OKLCH-based pair generation guidance, see `./color-theory.md` §OKLCH.
+---
+## Step 4: Dark-Specific Anti-Patterns (DARK-05)
+**Anti-pattern A: Images and SVGs without dark variant**
+```bash
+grep -rEn "<img[^>]+src=|<svg" "$SRC_ROOT" \
+  --include="*.tsx" --include="*.jsx" --include="*.html" --include="*.vue" 2>/dev/null \
+  | grep -v "dark\."
+```
+For each image/SVG found, check whether any of the following exist:
+- A sibling file with pattern `[name]-dark.{png,svg,webp}`
+- A `dark:hidden` / `dark:block` swap class pairing in the same component
+- A `<picture>` element with a `prefers-color-scheme: dark` source
+Flag images/SVGs with none of the above → P2 (minor).
+**Anti-pattern B: Pure-black backgrounds (BAN-05)**
+```bash
+grep -rEn "#000000|#000\b|rgb\([[:space:]]*0[[:space:]]*,[[:space:]]*0[[:space:]]*,[[:space:]]*0[[:space:]]*\)|background[^:]*:[[:space:]]*black" \
+  "$SRC_ROOT" --include="*.css" --include="*.scss" 2>/dev/null
+```
+Any match within a `.dark {}` block or `@media (prefers-color-scheme: dark)` context → P1 (major). Pure black (`#000000`) in dark mode causes visual harshness and fails accessibility in high-contrast conditions. Use near-black (`#0a0a0a` – `#1a1a1a`) instead.
+**Anti-pattern C: Missing forced-colors media query**
+```bash
+forced_count=$(grep -rEn "@media.*forced-colors" "$SRC_ROOT" \
+  --include="*.css" --include="*.scss" 2>/dev/null | wc -l)
+```
+If `forced_count` equals 0 → P2 (minor). The `forced-colors` media query ensures the design respects Windows High Contrast mode and similar OS accessibility overrides.
+---
+## Step 5: Meta Property Check (DARK-06)
+**color-scheme property:**
+```bash
+cs_count=$(grep -rEn "color-scheme" "$SRC_ROOT" public/ \
+  --include="*.html" --include="*.tsx" --include="*.css" 2>/dev/null | wc -l)
+```
+If `cs_count` equals 0 → P2 (minor).
+**prefers-color-scheme media query:**
+```bash
+pcs_count=$(grep -rEn "prefers-color-scheme" "$SRC_ROOT" public/ \
+  --include="*.html" --include="*.tsx" --include="*.css" 2>/dev/null | wc -l)
+```
+If `pcs_count` equals 0 → P2 (minor). Absence means the site ignores the OS-level dark mode preference.
+---
+## Step 5B: Dark Mode Rendering Screenshots (when preview: available)
+Check `preview` status from `.design/STATE.md <connections>` (per `./shared-preamble.md#connection-handshake-summary`).
+**If `preview: available`:**
+1. `preview_navigate` to the primary route (e.g., `http://localhost:3000/`).
+2. Capture light-mode: `preview_screenshot` → `.design/screenshots/darkmode/light.png`.
+3. Inject dark mode using the project's toggle mechanism (check `DESIGN-CONTEXT.md` D-XX decisions):
+   - Tailwind dark: `preview_eval("document.documentElement.classList.add('dark')")`
+   - data-theme: `preview_eval("document.documentElement.setAttribute('data-theme','dark')")`
+   - Custom class: `preview_eval("document.documentElement.classList.add('theme-dark')")`
+   - If mechanism is unknown: attempt Tailwind default first; note in `DARKMODE-AUDIT.md` which method was used.
+4. `preview_screenshot` → `.design/screenshots/darkmode/dark.png`.
+5. Record both paths (NOT base64) for embedding in `## Dark Mode Rendering` section.
+**If `preview: unavailable` or `preview: not_configured`:** omit `## Dark Mode Rendering` section entirely. Emit `Visual dark mode check skipped — preview not configured.` in Notes.
+---
+## Step 6: DARKMODE-AUDIT.md Template
+Output path: `.design/DARKMODE-AUDIT.md`.
+```markdown
+# Dark Mode Audit
+**Generated:** <ISO date>
+**Architecture detected:** <Architecture 1 (CSS custom props) | Architecture 2 (Tailwind dark:) | Architecture 3 (JS class toggle) | Hybrid | None>
+**Source scanned:** <SRC_ROOT>
+## Summary
+| Category | Status | Issues |
+|----------|--------|--------|
+| Contrast (DARK-03) | <pass / fail> | <count> |
+| Token Overrides (DARK-04) | <pass / fail> | <count> |
+| Anti-Patterns (DARK-05) | <pass / fail> | <count> |
+| Meta Properties (DARK-06) | <pass / fail> | <count> |
+## P0 Fixes (Critical — contrast failure on body text)
+- [CONTRAST] <token-pair>: ratio <X:1> — required 4.5:1. File: <path>
+## P1 Fixes (Major — large-text contrast / missing dark overrides / pure-black)
+- [CONTRAST-LARGE] <token-pair>: ratio <X:1> — required 3:1. File: <path>
+- [TOKEN-OVERRIDE] Missing dark override for <--token-name>. Light value: <hex>. File: <path>
+- [BAN-05] Pure-black background detected in dark context. File: <path>:line
+## P2 Fixes (Minor — missing SVG variants / forced-colors / meta props)
+- [SVG-DARK] <image.svg> has no dark variant. File: <path>
+- [FORCED-COLORS] No @media (forced-colors) block detected in any CSS file.
+- [COLOR-SCHEME] No color-scheme property or meta tag detected.
+- [PREFERS-COLOR-SCHEME] No prefers-color-scheme query detected.
+## P3 Fixes (Cosmetic)
+- <cosmetic issues, if any>
+## Dark Mode Rendering
+<Either side-by-side screenshot references, or "Visual dark mode check skipped — preview not configured.">
+## Notes
+This audit is read-only. It does NOT write scores back to DESIGN.md.
+To apply fixes, run the design pipeline and include dark mode decisions in DESIGN-CONTEXT.md.
+Score writeback (V2-05) is deferred.
+```
+If a priority bucket has no issues, omit that section or write "None."
+---
+*Imported by: `../skills/darkmode/SKILL.md`. Maintained as part of Phase 28.5 (Bucket 2 rework — D-10).*

package/reference/debug-feedback-loops.md ADDED Viewed

@@ -0,0 +1,119 @@
+---
+name: debug-feedback-loops
+type: heuristic
+version: 1.0.0
+phase: 28.5
+tags: [debug, feedback-loop, deterministic-signal, iterate-on-loop, mit-port, mattpocock]
+last_updated: 2026-05-18
+---
+Source: mattpocock/skills (MIT) — engineering/diagnose Phase 1 — adapted with permission. See `../NOTICE` for the full attribution block.
+# Debug Feedback Loops
+Build a feedback loop before any hypothesizing. A feedback loop is a deterministic, fast, agent-runnable pass/fail signal that tells you whether the bug is reproduced right now, every time, in well under a minute. Without it, debugging degenerates to speculation.
+**Do not proceed to Phase 2 (hypothesis generation) until you have a loop you believe in.**
+## The 10 construction paths
+Listed in priority order — try the cheaper, faster paths first. Each entry: when to reach for it, the shape of the loop, and the verification snippet.
+### 1. Failing test
+The strongest signal. Write the failing test in the project's native test framework (pytest, jest, vitest, go test, cargo test, junit, rspec). Assert the buggy behavior; run with watch mode if available. When the test goes green, the bug is fixed. Best case: reproduces in under 2 seconds, runnable by a fresh agent with one command.
+When to reach: the project already has a test runner the agent can invoke; the bug is in a unit/integration-testable code path; the symptom is expressible as a deterministic assertion.
+### 2. `curl` against a running endpoint
+For HTTP endpoints, a `curl` against the staging or local server with assertion on body/status. Pipe to `jq` for structured assertions. Cheap, reliable, framework-free. Wrap in a 3-line bash script so the loop is one command.
+When to reach: the bug is in an HTTP endpoint; the server is already runnable locally; the symptom shows up in response body/status/headers.
+### 3. CLI fixture
+For CLI tools, a small shell script that invokes the binary with fixture inputs and `grep`s for the symptom in stdout/stderr. Bash one-liner is enough; no test framework. Capture exit code, stdout, and stderr separately.
+When to reach: the bug is in a CLI tool; the symptom shows up in stdout/stderr/exit-code; the failure mode is reproducible from a fixed input.
+### 4. Headless browser
+For UI bugs, a Playwright or Puppeteer script that opens the page, performs the trigger action, and screenshots the symptom region. Compare against a known-good fixture or assert on a DOM selector's text/attribute. Use a deterministic seed for any randomness (animations, IDs, dates).
+When to reach: the bug is visible only in a rendered browser context; DOM-level inspection isn't enough; the symptom involves layout, paint, or interaction timing.
+### 5. Trace replay
+For bugs reproducible from a captured execution trace, replay the trace deterministically. `rr` on Linux for native binaries, record-and-replay plugins for some browsers, Chrome DevTools recording for web, or a captured production trace for distributed systems. Replays are bit-for-bit reproducible — the gold standard for non-deterministic bugs that have been captured once.
+When to reach: the bug is hard to reproduce live but you have a captured trace; the trace runtime is available; bit-identical replay is achievable.
+### 6. Throwaway harness
+Write a minimal `main()` that calls the buggy function with known inputs and prints the output. ~10 lines. Side-step framework startup costs entirely. Throw away when fixed. Useful when the test framework's setup is too heavy to iterate quickly.
+When to reach: the bug is in a single function with a clear input/output contract; framework setup dominates iteration time; you'd rather iterate on a 10-line script than wait for the framework to boot.
+### 7. Fuzz
+When the bug surfaces unpredictably, use property-based testing (Hypothesis, fast-check, jqwik) or AFL/libfuzzer for native code. The fuzzer narrows on the failing input across runs. Combine with a "minimize" pass to shrink the failing input to its smallest form.
+When to reach: the input space is exotic (parsers, serializers, network protocols); the bug isn't tied to a specific input you can name; you suspect a class of inputs but can't enumerate it.
+### 8. Bisect
+When you know "it worked on commit X, fails on commit Y," `git bisect` is the loop. Each iteration runs the test/curl/CLI from a higher path. Reproduces in O(log N) commits. Combine with `git bisect run <script>` to fully automate.
+When to reach: the bug regressed between two known commits; you have a binary pass/fail script from one of the earlier paths; you don't yet know which commit introduced the regression.
+### 9. Differential
+When you have two systems and one's correct, write a differential harness: feed the same input to both, assert outputs match. Cheap for migration bugs (old → new implementation) and protocol bugs (your client vs reference client). The harness becomes the regression test once the bug is fixed.
+When to reach: a known-good reference implementation exists; the buggy code is supposed to match the reference; input space is enumerable enough to drive both implementations side by side.
+### 10. HITL bash (Human In The Loop)
+Last resort. A documented sequence of bash commands a human runs that produces a pass/fail signal. Slower (human in the path), but better than no loop. The agent reads stdout/stderr; the human reads the screen and reports. Use only when no automatable signal is available — physical hardware, vendor portals, manual eyeball checks.
+When to reach: every other path is blocked by an unautomatable surface; the human cost is acceptable for the duration of the investigation; the loop will be retired or upgraded the moment any earlier path becomes possible.
+## Iterate on the loop itself
+The loop is a first-class artifact. Iterate on it before iterating on hypotheses. A 5-minute loop run 20 times costs 100 minutes; a 5-second loop run 20 times costs 100 seconds. Spending 30 minutes tightening the loop pays back inside the same session.
+- **Cache setup**: hoist expensive setup (DB seed, fixture load, container start) out of the loop body. Run the loop only on the fast inner part. Use `--no-rebuild`, persistent containers, or test-runner watch modes.
+- **Narrow scope**: if the loop runs the full test suite to verify one bug, narrow to just the failing test/group. Fewer side-effects, faster iterations. `pytest -k`, `jest -t`, `vitest --testNamePattern`, `go test -run` are your friends.
+- **Pin time**: when the bug is time-dependent, freeze the clock (`sinon.useFakeTimers`, `jest.useFakeTimers`, `freezegun`, `time-machine`). Removes wallclock as a variable.
+- **Seed RNG**: every random source gets a fixed seed in the loop. `Math.random`, `crypto.randomBytes`, `random.seed(...)`, `rand::SeedableRng`. Determinism over coverage — the loop must be bit-identical given the same code state.
+- **Isolate filesystem**: run in a `tmpdir`; reset between iterations. Avoids "fixed on my machine" via stale state. Bind-mount or copy fixtures into the tmpdir per iteration.
+- **Freeze network**: mock or record/replay all outbound calls (`nock`, `vcr`, `polly.js`, `mitmproxy --replay`). Real-network loops are non-deterministic by definition.
+The discipline: every iteration of the loop should be bit-identical given the same code state. If two iterations differ without a code change, the loop has a hidden input — find it and pin it before continuing.
+## Non-deterministic bugs
+Some bugs surface only sometimes. The goal is NOT a clean repro — the goal is to raise the reproduction rate to debuggable.
+- **Measure baseline rate**: run the loop N=20 times. Note pass/fail count. Record the rate so you can tell whether later changes helped.
+- **Raise stressors**: add concurrency, contention, memory pressure, network jitter (use `tc qdisc add dev lo root netem delay 100ms 50ms` on Linux, `Network Link Conditioner` on macOS). Re-measure.
+- **Target the suspect axis**: if you suspect a race, add a deterministic sleep at the suspect point and measure. If reproduction jumps to 100% with sleep, the race is in that region. If it stays at baseline, the race is elsewhere.
+- **A 30% reproduction rate is debuggable.** A 5% rate isn't — keep raising stressors until you cross 30%. At 30% you can iterate; at 5% you're guessing whether your fix helped or you got lucky.
+## When the loop is good enough
+The loop is good enough when:
+- It runs in under a minute (preferably under 10 seconds).
+- It's deterministic (or, for non-determinism, reproduces at least 30% of the time).
+- It's automatable — no human in the inner loop except by explicit choice (Path 10).
+- A fresh agent could pick up the loop and run it without context.
+Only after the loop is good enough should you proceed to hypothesizing the fix. The hypothesis cycle is governed by `./debugger-philosophy.md` (one variable at a time, do not stop at first plausible cause, the bug is where you didn't look).
+## Cross-references
+- `./debugger-philosophy.md` — companion framing; the hypothesis-cycle discipline that runs in Phase 2 once the loop is in place.
+- `../skills/debug/SKILL.md` — Phase 1 of the debug skill mandates this catalog before any hypothesis generation.
+- `../NOTICE` — full mattpocock/skills MIT attribution.

package/reference/design-procedure.md ADDED Viewed

@@ -0,0 +1,304 @@
+---
+name: design-procedure
+type: meta-rules
+version: 1.0.0
+phase: 28.5
+tags: [design, procedure, extracted, pipeline-stage, execute, wave-coordination]
+last_updated: 2026-05-18
+---
+Source: extracted from `skills/design/SKILL.md` (Phase 28.5 rework — D-10 extract-then-link).
+The skill's load-bearing workflow stays in `../skills/design/SKILL.md`; this file holds the
+detail the agent reaches for when executing a specific step (agent spawn prompts, wave
+coordination, executor STATE.md protocol, figma-write dispatch).
+# Design Procedure
+Detailed procedure for the get-design-done `design` Stage 4 orchestrator. Companion to
+`../skills/design/SKILL.md`. Read this file when executing a specific design step; the
+SKILL.md keeps the load-bearing wave-iteration workflow + decision tree, this file holds
+the full executor prompts and parallelism semantics.
+---
+## Stage entry
+1. Call `mcp__gdd_state__transition_stage` with `to: "design"`.
+   - Gate failure surfaces `error.context.blockers` to the user; do not advance.
+   - If the transition succeeds and the prior stage was already `design` with `status: in_progress`, this is a RESUME — use `task_progress` numerator as source of truth and skip tasks that already have a corresponding `.design/tasks/task-NN.md` file.
+2. Call `mcp__gdd_state__get` -> snapshot `state`; read `state.position.wave` to decide execution plan.
+Abort only if `.design/DESIGN-PLAN.md` is missing:
+> "No plan found. Run `/get-design-done:plan` first."
+---
+## Flag Parsing
+- `--auto` -> `auto_mode=true` (no mid-stage prompts; architectural deviations still stop the individual task but continue with remaining tasks)
+- `--parallel` -> `parallel_mode=true` (use worktree isolation for `Parallel: true` tasks)
+---
+## Pre-execution — Directionally-open check
+Scan DESIGN-PLAN.md for tasks marked as "directionally open" (exploration-appropriate — e.g., tasks whose acceptance criteria read "explore N directions" or "pick a visual approach"). If any are found, print:
+> "Tasks [IDs] appear directionally open — consider running `/gdd:sketch` first to explore variants before implementation."
+Skip if `auto_mode=true`.
+## Pre-execution — Project-local conventions
+When spawning the executor, include any `./.claude/skills/design-*-conventions.md` files in `<required_reading>` so the executor sees project-local design conventions (typography, color, layout, motion, component, interaction decisions codified from prior sketch wrap-ups). Also include any `~/.claude/gdd/global-skills/*.md` files if the directory exists — global skills are cross-project conventions that inform but do not override project-local D-XX decisions.
+---
+## .stories.tsx Stub (when storybook project detected)
+After every new component file is created by the design-executor:
+Step 1 — Check project detection (does not require server running):
+  Bash: ls .storybook/ 2>/dev/null || grep '"storybook"' package.json 2>/dev/null
+  -> Found -> storybook_project: true
+  -> Not found -> skip .stories.tsx emission
+Step 2 — When storybook_project: true, emit a CSF stub alongside the component:
+  File: `<same directory as component>/<ComponentName>.stories.tsx`
+  Content follows CSF format (see `connections/storybook.md` for full template):
+  - Import `Meta` and `StoryObj` from `@storybook/react`
+  - Import the new component
+  - `meta: Meta<typeof ComponentName>` with `title` and `parameters.a11y.test = 'error'`
+  - Export `Default`, `Primary`, `Disabled` story variants
+  Adjust `title` to match directory structure (e.g., `'Components/Button'` or `'Features/Auth/LoginForm'`)
+Note: the `.stories.tsx` stub is emitted whenever `storybook_project: true` regardless of whether
+the dev server is running. New components need stories even in offline/CI contexts.
+---
+## Step 1 — Parse DESIGN-PLAN.md
+Read `.design/DESIGN-PLAN.md`. Partition tasks by `## Wave N` heading. Within each wave, partition by `Parallel: true` vs `Parallel: false`. Compute `total_tasks` for `task_progress` denominator.
+If resuming: skip tasks where `.design/tasks/task-NN.md` already exists.
+---
+## Parallelism Decision (per wave, before spawning)
+For each wave:
+1. Read `.design/config.json` `parallelism` (or defaults from `reference/config-schema.md`).
+2. Collect candidates in the wave; check `Touches:`, `writes:`, `parallel-safe`, and `typical-duration-seconds` fields.
+3. Apply rules in order from `reference/parallelism-rules.md` (hard -> soft). Overlapping Touches split into sequential sub-waves.
+4. Record the parallelism decision for this wave via `mcp__gdd_state__update_progress` with `task_progress: "<completed>/<total>"` and `status: "design_wave_<N>_parallelism: <parallel|serial>, reason=<short-reason>"` — the status string is the canonical carrier (mirrors the plan-stage convention from Plan 20-09; a dedicated tool may be added in a follow-on plan).
+5. If `parallel`: spawn all candidates via concurrent `Task()` calls in one response. If `serial`: spawn sequentially.
+### Executor prompt template (applies to every spawned design-executor)
+Every spawned executor receives the following STATE.md contract in its prompt:
+> **STATE.md mutation protocol** — When you complete a task in your assigned batch, update STATE.md ONLY via the `gdd-state` MCP tools. Specifically:
+> - Report task progress: `mcp__gdd_state__update_progress` with your new `task_progress` fraction.
+> - Add blockers: `mcp__gdd_state__add_blocker` with `{ stage: "design", date: <today>, text: "..." }`.
+> - Resolve your own blockers on fix: `mcp__gdd_state__resolve_blocker` with the blocker id.
+>
+> Do NOT `Read` + `Write` `.design/STATE.md` directly — the MCP tools enforce the lockfile and emit mutation events. Direct writes corrupt parallel state.
+Inline this protocol block verbatim inside every design-executor prompt in both the parallel-batch and sequential-tail spawns below. Concurrent executors (Phase 10.1 parallel mode) each emit `update_progress` calls; the lockfile (Plan 20-01) and event stream (Plan 20-06) serialize them safely.
+## Step 2 — Wave-by-Wave Execution
+For each Wave in order (Wave 1, Wave 2, ...):
+### Parallel batch (if `parallel_mode=true` AND any `Parallel: true` tasks in wave)
+Report the partition before spawning:
+```
+=== Wave [N] — parallel mode ===
+Parallel batch ([N] tasks — spawning concurrently):
+  [01] [type]: [scope] — touches: [files]
+  [02] [type]: [scope] — touches: [files]
+Sequential tail ([N] tasks):
+  [03] [type]: [scope] — touches: [files]
+Spawning agents now...
+================================
+```
+Spawn ALL `Parallel: true` tasks in this wave as concurrent `Task()` calls in ONE response. Each call uses `isolation: "worktree"`:
+```
+Task("design-executor", """
+<required_reading>
+@.design/STATE.md
+@.design/DESIGN-PLAN.md
+@.design/DESIGN-CONTEXT.md
+@reference/[type-relevant].md
+</required_reading>
+You are the design-executor agent. Execute Task NN from DESIGN-PLAN.md.
+Prompt context:
+  task_id: NN
+  task_type: [type]
+  task_scope: [scope]
+  task_acceptance_criteria:
+    - [criterion 1]
+    - [criterion 2]
+  wave: N
+  is_parallel: true
+  auto_mode: [true|false]
+Write .design/tasks/task-NN.md and make an atomic commit `feat(design-NN): [type] — [scope]`.
+Emit `## EXECUTION COMPLETE` when done.
+""", subagent_type="design-executor", isolation="worktree")
+```
+Wait for all parallel tasks to emit `## EXECUTION COMPLETE`.
+**Merge worktrees** (preserved from v2.1.0 — do not redesign):
+```
+=== Parallel batch complete ===
+[check/warn/cross] Task 01 — [type]
+[check/warn/cross] Task 02 — [type]
+Merging worktrees...
+================================
+```
+Merge each worktree branch back into the working directory. Each agent touched non-overlapping files (guaranteed by the conflict check on `Touches:` fields). If an unexpected merge conflict appears, flag it and ask the user to resolve before continuing.
+After merge, roll up the batch's progress:
+- Call `mcp__gdd_state__update_progress` with `task_progress: "<completed>/<total>"` and `status: "design_wave_<N>_parallel_batch_complete"`.
+- Call `mcp__gdd_state__checkpoint` — records the wave boundary in `<timestamps>` and bumps `last_checkpoint`.
+### Sequential tail (Parallel: false tasks, or all tasks if `parallel_mode=false`)
+Announce each wave before starting:
+```
+=== Wave [N] — [N tasks] — sequential ===
+Tasks:
+  [01] [type]: [scope]
+  [02] [type]: [scope]
+==========================================
+```
+Run one at a time. Same `Task("design-executor", ...)` pattern with `is_parallel: false` (no worktree isolation):
+```
+Task("design-executor", """
+<required_reading>
+@.design/STATE.md
+@.design/DESIGN-PLAN.md
+@.design/DESIGN-CONTEXT.md
+@reference/[type-relevant].md
+</required_reading>
+You are the design-executor agent. Execute Task NN from DESIGN-PLAN.md.
+Prompt context:
+  task_id: NN
+  task_type: [type]
+  task_scope: [scope]
+  task_acceptance_criteria:
+    - [criterion 1]
+    - [criterion 2]
+  wave: N
+  is_parallel: false
+  auto_mode: [true|false]
+Write .design/tasks/task-NN.md and make an atomic commit `feat(design-NN): [type] — [scope]`.
+Emit `## EXECUTION COMPLETE` when done.
+""", subagent_type="design-executor")
+```
+After each task completes, call `mcp__gdd_state__update_progress` with the new `task_progress: "<completed>/<total>"` and `status: "design_wave_<N>_task_<NN>_complete"`.
+After the final sequential task of the wave, call `mcp__gdd_state__checkpoint` — records the wave boundary in `<timestamps>` and bumps `last_checkpoint`.
+---
+## Step 3 — Wave Checkpoint
+After each wave (unless `--auto` flag was passed):
+```
+=== Wave [N] complete ===
+  check [N] tasks complete
+  warn  [N] deviations (see .design/tasks/ files)
+Ready for Wave [N+1]? (yes / review first)
+=========================
+```
+Skip checkpoint if `auto_mode=true`.
+---
+## Step 4 — Handle Deviations
+After each wave, check task-NN.md files for `status: deviation`. If any found:
+- Call `mcp__gdd_state__get` -> read `state.blockers`; present affected task IDs and their blocker descriptions from the returned snapshot.
+- Offer: (a) stop stage, (b) continue remaining tasks
+- In `auto_mode`: continue automatically, log all deviations
+- When a blocker is addressed (fix committed by a follow-up task), call `mcp__gdd_state__resolve_blocker` with the blocker id to clear it from the live state.
+---
+## State Update (exit)
+1. Call `mcp__gdd_state__set_status` with `status: "design_complete"` — marks the stage completed without transitioning; verify calls `transition_stage` on its entry, keeping the transition atomic with the owning stage.
+2. Call `mcp__gdd_state__checkpoint` — stamps `last_checkpoint` and appends a `design_completed_at` entry to `<timestamps>`.
+---
+## After Completion
+Print summary:
+```
+=== Design stage complete ===
+Tasks: [N] complete / [M] total
+Deviations: [N]
+Commits: [git log --oneline since stage start]
+Next: /get-design-done:verify
+  -> Scores the result against baseline, checks must-haves,
+    runs NNG heuristic evaluation, and identifies gaps.
+==============================
+```
+---
+## Figma Write Dispatch (after design-executor completes)
+After design-executor has finished and DESIGN-PLAN.md tasks are complete:
+1. Read `figma:` status from `.design/STATE.md` `<connections>` (the unified remote MCP covers both reads and writes as of v1.0.7.1):
+   - If `figma: not_configured` or `figma: unavailable` or absent -> skip this block entirely (no prompt, no output)
+   - If `figma: available` -> proceed to step 2
+2. Offer the user a prompt:
+   ```
+   figma write-back is available — propagate design decisions back to Figma?
+   Modes: annotate (layer comments) | tokenize (variable bindings) | mappings (Code Connect)
+   Run figma-write? (y/N):
+   ```
+3. If user answers "y" or "yes":
+   - Ask which mode: annotate / tokenize / mappings (or all)
+   - Spawn `design-figma-writer` agent with the selected mode
+   - Pass `--dry-run` flag if user requests preview first
+4. If user answers "n", "N", or no response: skip silently.
+Note: This dispatch is always opt-in. The design stage never auto-runs figma-writer without user confirmation.