@hegemonart/get-design-done 1.27.7 → 1.28.5

package/reference/palette-catalog.md

@@ -20,6 +20,8 @@ This catalog gives design agents and the brief-stage palette picker a pre-verifi
 
 **Step 4 — Adjust for brand uniqueness.** All values here are mid-point baselines. Shift the primary hue ±15°, adjust lightness ±10%, or introduce a proprietary tint to differentiate the brand. Do not use these hex values verbatim in production without at least one brand-distinguishing adjustment.
 
+**See:** [`./color-theory.md`](./color-theory.md) §Color Harmonies for the OKLCH model that grounds these hue-shift instructions (perceptual lightness preserved across hues; sRGB ±15° distorts perceived brightness asymmetrically across yellow/blue).
+
 **Step 5 — Verify pairing.** After choosing the palette, consult `reference/typography.md` for matching typeface pairings that reinforce the vertical's tone.
 
 ## WCAG Compliance Notes

package/reference/peer-cli-protocol.md

@@ -0,0 +1,161 @@
+---
+name: peer-cli-protocol
+type: heuristic
+version: 1.0.0
+phase: 28.5
+tags: [peer-cli, acp, asp, protocol, verification-ladder, add-peer, customize, cc-multi-cli]
+last_updated: 2026-05-18
+---
+
+<!-- Procedural patterns adapted from greenpolo/cc-multi-cli (Apache 2.0). See ../NOTICE for full attribution. -->
+
+# Peer-CLI Protocol — Add + Customize Procedures
+
+Procedural reference for the peer-CLI delegation layer. Centralizes the verification
+ladder, adapter scaffolding shape, rewire-discipline, and Windows quirks so the three
+peer-CLI skills (`peers`, `peer-cli-add`, `peer-cli-customize`) can cross-link rather
+than each carry the full procedure inline. See `./peer-protocols.md` for the protocol
+shape (JSON-RPC framing, initialize handshake, error envelope); this file is the
+procedure layer that sits above it.
+
+## Verification ladder (run before any code edit when adding a peer)
+
+When a user wants to add a brand-new peer to the capability matrix, walk these four
+rungs in order. Stop at the first rung that fails — do not proceed to scaffold a broken
+adapter.
+
+### Rung 1 — Binary on PATH
+
+`which <peer-binary>` (POSIX) or `where <peer-binary>` (Windows). If exit non-zero, stop
+and ask the user to install the peer first. Adapters cannot be tested without the binary.
+
+### Rung 2 — Handshake test
+
+Spawn the peer with the protocol entry point:
+
+- **ACP peers** — `<peer-binary> acp` (or whatever the peer documents — Gemini uses
+  `gemini acp`; some peers use a flag).
+- **ASP peers** — `<peer-binary> app-server` (Codex convention; other ASP peers may
+  differ).
+
+Send an `initialize` JSON-RPC message over stdin with `protocolVersion: '2025-06-18'`
+(ACP) or `service_name: 'gdd_peer_delegation'` (ASP). Capture the reply on stdout. A
+valid JSON-RPC response with `result.protocolVersion` (ACP) or `result.threadId` (ASP)
+means the peer speaks the protocol. No valid reply within 5 seconds means either
+wrong-protocol or non-standard entry point — stop and ask the user for the correct
+invocation.
+
+### Rung 3 — Model-ID `-preview`-suffix trap
+
+Many peers expose preview models with a `-preview` suffix (e.g., `gpt-5-preview` vs
+`gpt-5`). The suffix drifts: today's preview is tomorrow's GA. Capture the peer's model
+list (most peers expose `<peer-binary> models` or similar) and document parent names in
+the new entry's `provider_model_id` field so the runtime-models entry survives the
+suffix flipping.
+
+### Rung 4 — Windows quirks
+
+If the peer-binary ends in `.cmd` and the user is on Windows, confirm
+`scripts/lib/peer-cli/spawn-cmd.cjs` will pick it up. That module handles `.cmd`
+detection per Plan 27-03 / D-04. Document any other Windows-specific quirks in the new
+adapter's leading comment.
+
+## Adapter scaffold shape
+
+Use the existing five adapters at `../scripts/lib/peer-cli/adapters/{codex,gemini,cursor,copilot,qwen}.cjs`
+as templates. Pick the closest match by protocol (ASP if `<protocol> = asp`, otherwise
+ACP). Each adapter exports:
+
+- `claims(role)` — boolean predicate against `ROLES_CLAIMED`.
+- `dispatch({command, args, cwd, env}, role, text, opts)` — async dispatch with optional
+  `opts.onNotification` callback.
+- `ROLES_CLAIMED` — array of role identifiers the peer claims.
+- `ROLE_PREFIX` — per-role prompt prefix object (empty string when no prefix needed).
+- `name`, `protocol` — string identifiers.
+
+Canonical skeleton (ACP variant; for ASP swap to `createAspClient` from `asp-client.cjs`):
+
+```js
+'use strict';
+const { createAcpClient } = require('../acp-client.cjs');
+
+const ROLES_CLAIMED = ['<role-1>', '<role-2>'];
+const ROLE_PREFIX = { '<role-1>': '', '<role-2>': '' };
+
+function claims(role) { return ROLES_CLAIMED.includes(role); }
+async function dispatch({ command, args, cwd, env }, role, text, opts) {
+  if (!claims(role)) throw new Error(`<peer-id> does not claim role: ${role}`);
+  const client = createAcpClient({ command, args, cwd, env });
+  try {
+    await client.initialize({ protocolVersion: '2025-06-18' });
+    return await client.prompt((ROLE_PREFIX[role] || '') + text, { onNotification: opts?.onNotification });
+  } finally { await client.close(); }
+}
+module.exports = { claims, dispatch, ROLES_CLAIMED, ROLE_PREFIX, name: '<peer-id>', protocol: '<protocol>' };
+```
+
+## Three-file footprint (peer add)
+
+A new peer integrates cleanly with a 3-file diff plus the capability-matrix doc:
+
+1. **`scripts/lib/peer-cli/adapters/<new-peer-id>.cjs`** — new adapter.
+2. **`scripts/lib/install/runtimes.cjs`** — add a `peerBinary` field (platform-aware:
+   `<binary>.cmd` on Windows, plain `<binary>` elsewhere).
+3. **`reference/peer-cli-capabilities.md`** — add a row to the capability matrix and a
+   per-peer section with the verification evidence from Rung 1–4 above.
+4. **`scripts/lib/peer-cli/registry.cjs`** — append to `CAPABILITY_MATRIX` (and
+   `KNOWN_PEERS` if separate).
+
+## Rewire discipline (customize)
+
+When rewiring `delegate_to:` on a specific agent's frontmatter:
+
+- Validate the new value against the capability matrix BEFORE editing the file. The
+  peer must exist; the role must be in the peer's `claims` list.
+- Three frontmatter cases: field absent + add it, field present + change it, field
+  present + remove it (revert to default).
+- Re-run `npm run validate:frontmatter` after every edit; offer to revert if it fails.
+- The peer must also be in `.design/config.json#peer_cli.enabled_peers` for dispatch
+  to fire at runtime — but that's a runtime concern, not a frontmatter validation
+  concern.
+
+## Verification gate (after any peer-CLI change)
+
+Run, in order, until each passes:
+
+1. `npx tsc --noEmit` — clean.
+2. `node --test tests/peer-cli-registry.test.cjs tests/peer-cli-adapters.test.cjs` —
+   no regression on existing tests.
+3. `node --test tests/reference-registry.test.cjs` — capability-matrix doc is in
+   `reference/registry.json`.
+4. `npm run validate:frontmatter` — no agent's `delegate_to:` field is broken.
+
+Any failure: surface the error and offer to revert.
+
+## Edge cases
+
+- **Peer speaks neither ACP nor ASP** — gdd v1.27 ships only those two protocols. Stop
+  and document the gap in `.design/RESEARCH.md` for a future phase.
+- **Peer claims a role no existing peer claims** — fine, capability matrix is open. But
+  document the role in `peer-cli-capabilities.md` so future peers can compete on it.
+- **Peer claims ALL roles** (generalist) — accept, but flag in the per-peer section.
+  Generalist peers are usually weaker than specialist peers; the bandit will sort it
+  out via measurement.
+- **Peer-ID collides with an existing peer** — fail. Peer-IDs must be globally unique.
+- **Rewire target peer not in capability matrix** — direct user to `peer-cli-add` first;
+  do not allow the frontmatter edit until the peer exists in the matrix.
+- **Rewire target role peer does not claim** — refuse with a list of what the peer DOES
+  claim. Suggest a closer match when obvious.
+
+## Cross-references
+
+- `./peer-protocols.md` — protocol-level reference (JSON-RPC framing, handshake shape).
+- `./peer-cli-capabilities.md` — capability matrix doc (per-peer claimed roles).
+- `../scripts/lib/peer-cli/registry.cjs` (Plan 27-05) — capability-matrix data source.
+- `../scripts/lib/peer-cli/adapters/*.cjs` (Plan 27-04) — adapter template.
+- `../scripts/lib/peer-cli/spawn-cmd.cjs` (Plan 27-03) — Windows `.cmd` handling.
+- `../scripts/lib/install/runtimes.cjs` (Plan 27-11) — `peerBinary` field per runtime.
+- `../skills/peers/SKILL.md` — discovery surface.
+- `../skills/peer-cli-add/SKILL.md` — add-peer flow.
+- `../skills/peer-cli-customize/SKILL.md` — rewire flow.
+- `../NOTICE` — Apache 2.0 attribution to greenpolo/cc-multi-cli.

package/reference/plan-procedure.md

@@ -0,0 +1,278 @@
+---
+name: plan-procedure
+type: meta-rules
+version: 1.0.0
+phase: 28.5
+tags: [plan, procedure, extracted, pipeline-stage, research, planner, checker]
+last_updated: 2026-05-18
+---
+
+Source: extracted from `skills/plan/SKILL.md` (Phase 28.5 rework — D-10 extract-then-link).
+The skill's load-bearing workflow stays in `../skills/plan/SKILL.md`; this file holds the
+detail the agent reaches for when executing a specific step (agent spawn prompts, chromatic
+scoping, synthesizer wiring, research-synthesis persistence, exploration artifact globbing).
+
+# Plan Procedure
+
+Detailed procedure for the get-design-done `plan` Stage 3 orchestrator. Companion to
+`../skills/plan/SKILL.md`. Read this file when executing a specific plan step; the
+SKILL.md keeps the load-bearing workflow + decision tree, this file holds the deep
+agent prompts and pre-plan research wiring.
+
+---
+
+## Stage entry
+
+1. `mcp__gdd_state__transition_stage` with `to: "plan"`.
+   - Gate failure surfaces `error.context.blockers` to the user; do not advance.
+2. `mcp__gdd_state__get` -> snapshot `state`. Use this snapshot for `<position>`, `<connections>`, `<must_haves>`, `<blockers>`, `<decisions>` in the current stage; do not re-read STATE.md directly.
+
+Abort with a clear error only if the user is trying to plan without DESIGN-CONTEXT.md — that is the true prerequisite, not STATE.md.
+
+## Flag Parsing
+
+Parse $ARGUMENTS:
+- `--auto` -> auto_mode=true (skip approvals, skip optional research)
+- `--parallel` -> parallel_mode=true (planner fills Touches:/Parallel: fields)
+
+## Parallelism Decision (before any multi-agent spawn)
+
+- Read `.design/config.json` `parallelism` (or defaults from `reference/config-schema.md`).
+- Apply rules from `reference/parallelism-rules.md`.
+- Plan's pipeline is inherently sequential (researcher -> pattern-mapper -> planner -> checker). Expected verdict: **serial** (rule 1).
+
+<!-- Parallelism decision is currently carried as the status string of an update_progress call. A dedicated tool may be added in a follow-on plan; until then, the status string is the canonical carrier. -->
+
+After the parallelism decision is made:
+- Call `mcp__gdd_state__update_progress` with `task_progress: "<current>/<total>"` and `status: "plan_parallelism_decided: batch_size=<N>, reason=<short-reason>"`.
+
+## Probe Chromatic connection
+
+Run at stage entry, after reading STATE.md:
+
+Step C1 — CLI presence:
+  Bash: command -v chromatic 2>/dev/null || npx chromatic --version 2>/dev/null
+  -> found -> proceed to Step C2
+  -> not found -> chromatic: not_configured (skip all Chromatic steps)
+
+Step C2 — Token check:
+  Bash: test -n "${CHROMATIC_PROJECT_TOKEN}"
+  -> true -> chromatic: available
+  -> false -> chromatic: unavailable
+
+Also check: if storybook: not_configured -> chromatic effectively unavailable (emit note, do not run).
+
+Write chromatic status to STATE.md `<connections>` via `mcp__gdd_state__probe_connections` — pass the single-entry probe result (`[{ name: "chromatic", status: "<verdict>" }]`). Do not edit `<connections>` directly.
+
+## Chromatic Change-Risk Scoping (when chromatic: available)
+
+Before writing DESIGN-PLAN.md, if chromatic: available:
+1. Identify token/component files to be changed (from DESIGN-CONTEXT.md scope)
+2. Run: Bash: npx chromatic --project-token $CHROMATIC_PROJECT_TOKEN --trace-changed=expanded --dry-run 2>&1
+3. Parse output — count story files that depend on changed source files
+4. Pass story count to design-planner.md (see design-planner.md Chromatic Change-Risk section)
+If unavailable: design-planner proceeds without story-count annotation.
+
+---
+
+## Step 1 — Optional Research (skip if auto_mode)
+
+Complexity heuristic: if DESIGN-CONTEXT.md `<domain>` spans 3+ scopes OR `<decisions>` count > 6 -> spawn design-phase-researcher. Otherwise skip.
+
+If spawning:
+
+```
+Task("design-phase-researcher", """
+<required_reading>
+@.design/STATE.md
+@.design/DESIGN-CONTEXT.md
+</required_reading>
+
+You are the design-phase-researcher agent. Identify the project type from DESIGN-CONTEXT.md
+and research relevant design patterns, pitfalls, and stack-specific conventions.
+
+Output file: .design/DESIGN-RESEARCH.md
+Target: ~100 lines, ~2 min budget.
+
+Emit `## RESEARCH COMPLETE` when done.
+""")
+```
+
+Wait for `## RESEARCH COMPLETE`. Call `mcp__gdd_state__update_progress` with `task_progress: "1/3"` and a short `status` summary.
+
+## Step 1.5 — Pattern Mapping (mandatory, brownfield protection)
+
+```
+Task("design-pattern-mapper", """
+<required_reading>
+@.design/STATE.md
+@.design/DESIGN-CONTEXT.md
+@reference/audit-scoring.md
+</required_reading>
+
+You are design-pattern-mapper. Grep the codebase for existing design patterns
+(color tokens, spacing scale, typography conventions, component styling) and
+write .design/DESIGN-PATTERNS.md. Classify by design concern — NOT by code
+architecture (no controllers, services, middleware vocabulary).
+
+Output file: .design/DESIGN-PATTERNS.md
+Emit `## MAPPING COMPLETE` when done.
+""")
+```
+
+Wait for `## MAPPING COMPLETE`. Call `mcp__gdd_state__update_progress` with `task_progress: "1/3"` and a short `status` summary.
+
+## Step 1.6 — Assumptions Analysis (optional, same flag as research)
+
+If assumptions analysis enabled (skip if auto_mode):
+
+```
+Task("design-assumptions-analyzer", """
+<required_reading>
+@.design/STATE.md
+@.design/DESIGN-CONTEXT.md
+@.design/DESIGN-PATTERNS.md
+</required_reading>
+
+You are design-assumptions-analyzer. Surface hidden design assumptions with
+confidence levels and evidence citations.
+
+Emit `## ANALYSIS COMPLETE` when done.
+""")
+```
+
+Wait for `## ANALYSIS COMPLETE`.
+
+## Step 1.7 — Synthesize pre-plan research inputs (Plan 10.1-04, D-13/D-15)
+
+If 2+ of the pre-plan research agents ran (`design-phase-researcher` Step 1, `design-pattern-mapper` Step 1.5, `design-assumptions-analyzer` Step 1.6), invoke synthesize to merge their outputs into a single compact brief. If only one ran, skip this step.
+
+    Skill("synthesize", {
+      outputs: [
+        (if Step 1 ran)   "=== from design-phase-researcher ===\n" + <read .design/DESIGN-RESEARCH.md>,
+        (if Step 1.5 ran) "=== from design-pattern-mapper ===\n"   + <read .design/DESIGN-PATTERNS.md>,
+        (if Step 1.6 ran) "=== from design-assumptions-analyzer ===\n" + <read .design/DESIGN-ASSUMPTIONS.md>
+      ],
+      directive: "Merge into a single compact pre-plan brief. Preserve per-source section headers so the planner can trace provenance. Consolidate duplicate recommendations with source tags. Target ~150 lines.",
+      output_shape: "markdown"
+    })
+
+Wait for `## SYNTHESIS COMPLETE`. Write to `.design/DESIGN-PREPLAN-BRIEF.md` (overwrite if present). Add `@.design/DESIGN-PREPLAN-BRIEF.md` to the planner's `<required_reading>` in Step 2 — individual files remain on disk for drill-down.
+
+**Parallel synthesizer note (future):** if a future plan variant spawns N parallel phase-researchers (e.g., one per project-type family), wire synthesize the same way as `skills/map/` Step 3.5.
+
+## Research-synthesis persistence (decisions + must-haves)
+
+When the synthesizer (design-phase-researcher / design-pattern-mapper / design-assumptions-analyzer) produces D-XX decisions and M-XX must-haves, persist each one through MCP instead of editing STATE.md directly.
+
+For each D-XX decision the synthesizer produces:
+- Call `mcp__gdd_state__add_decision` with `{ id: "D-XX", text: "...", status: "locked"|"tentative" }`.
+
+For each M-XX must-have the synthesizer produces:
+- Call `mcp__gdd_state__add_must_have` with `{ id: "M-XX", text: "...", status: "pending" }`.
+
+Issue these sequentially. Each call is event-emitting and lockfile-safe. Parallel issuance would serialize on the STATE.md lockfile with no throughput gain.
+
+## Step 2 — Plan
+
+```
+Task("design-planner", """
+<required_reading>
+@.design/STATE.md
+@.design/DESIGN-CONTEXT.md
+@reference/audit-scoring.md
+@.design/DESIGN-PATTERNS.md
+[@.design/DESIGN-RESEARCH.md — only include if research step ran]
+[@.design/DESIGN-ASSUMPTIONS.md — only include if assumptions analysis ran]
+[@.design/DESIGN-PREPLAN-BRIEF.md — include if Step 1.7 synthesize ran; planner prefers this compact brief over the individual files above]
+[@.design/sketches/*/WINNER.md — include all completed sketch winners if present]
+[@.design/spikes/*/FINDINGS.md — include all completed spike findings if present]
+[@./.claude/skills/design-*-conventions.md — include all project-local design conventions if present]
+[@~/.claude/gdd/global-skills/*.md — include all global skills if directory exists; global conventions inform but do not override project-local D-XX decisions]
+</required_reading>
+
+You are the design-planner agent. Read DESIGN-CONTEXT.md and produce .design/DESIGN-PLAN.md
+with wave-ordered tasks, acceptance criteria, and (if parallel mode) Touches:/Parallel: fields.
+
+Context:
+- Pipeline stage: plan
+- auto_mode: <true|false>
+- parallel_mode: <true|false>
+
+Output file: .design/DESIGN-PLAN.md
+Format: per agents/design-planner.md Output Format section.
+
+Emit `## PLANNING COMPLETE` when done.
+""")
+```
+
+Wait for `## PLANNING COMPLETE`. Call `mcp__gdd_state__update_progress` with `task_progress: "2/3"` and a short `status` summary.
+
+## Step 3 — Check
+
+```
+Task("design-plan-checker", """
+<required_reading>
+@.design/STATE.md
+@.design/DESIGN-PLAN.md
+@.design/DESIGN-CONTEXT.md
+</required_reading>
+
+You are the design-plan-checker agent. Validate DESIGN-PLAN.md will achieve DESIGN-CONTEXT.md
+brief goals across 5 dimensions: requirement coverage, task completeness, wave ordering,
+must-have derivation, auto mode compliance.
+
+Context:
+- auto_mode: <true|false>
+
+Output: structured result as response text (no file). Start with `## PLAN CHECK RESULT: PASS`
+or `## PLAN CHECK RESULT: ISSUES FOUND`.
+
+Emit `## PLAN CHECK COMPLETE` when done.
+""")
+```
+
+Wait for `## PLAN CHECK COMPLETE`. Call `mcp__gdd_state__update_progress` with `task_progress: "3/3"` and a short `status` summary.
+
+If `## PLAN CHECK RESULT: ISSUES FOUND` and any BLOCKER issues:
+- Present issues to user and offer: (a) revise plan now — re-spawn design-planner with issue list, (b) accept and proceed, (c) abort.
+- If auto_mode: auto-accept WARNING issues, abort on BLOCKER issues.
+
+## Stage exit
+
+1. Call `mcp__gdd_state__set_status` with `status: "plan_complete"`.
+2. Call `mcp__gdd_state__checkpoint` to stamp `last_checkpoint` and finalize the plan stage.
+
+The next stage (design) calls `mcp__gdd_state__transition_stage` on entry — this skill does NOT issue the transition itself, preserving the stage-owned-transition discipline established by brief->explore and explore->plan.
+
+## After Completion
+
+Print user-facing summary:
+- Plan tasks: N waves, M total tasks
+- Files: .design/DESIGN-PLAN.md (and .design/DESIGN-RESEARCH.md if research ran)
+- Next: `/get-design-done:design` to execute the plan
+
+---
+
+## Exploration artifacts & project-local conventions
+
+When building the planner spawn prompt, also glob for:
+- `.design/sketches/*/WINNER.md` — winning sketch rationale (informs directional tasks)
+- `.design/spikes/*/FINDINGS.md` — spike verdicts (inform task feasibility)
+- `./.claude/skills/design-*-conventions.md` — project-local design conventions
+
+Include each matching file in `<files_to_read>` / `<required_reading>` so the planner sees them when creating tasks. Spike findings from `.design/spikes/` inform task feasibility; sketch winners inform directional choice; project-local conventions override defaults.
+
+## --research mode (removed)
+
+V2-04 deferred the `--research` flag. Rationale: complexity of an additional
+agent spawn + Context7 integration outweighs the benefit of discover-stage
+auto-detect for most projects. Use /discover's Auto Mode for research-assisted
+discovery instead.
+
+The optional research step that already exists (Step 1, triggered by complexity
+heuristic: 3+ domain scopes OR 6+ decisions) covers the core use case without
+a separate CLI flag.
+
+If --research is reintroduced in a future version, define its scope in
+ROADMAP.md V2+ and update this section.