@hegemonart/get-design-done 1.59.3 → 1.59.4

package/scripts/skill-templates/peer-cli-add/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: peer-cli-add
+description: "Guided ladder for adding a brand-new peer (not in the v1.27 capability matrix) to gdd's peer-CLI delegation layer. Walks the verification ladder, scaffolds an adapter, updates the capability matrix, and handles Windows quirks. Run when you discover a new peer CLI you want gdd to delegate to."
+argument-hint: "<new-peer-id> <peer-binary> <protocol: acp|asp>"
+tools: Read, Edit, Write, Bash, Grep
+---
+
+<!-- Procedural pattern adapted from greenpolo/cc-multi-cli's `multi-cli-anything` skill (Apache 2.0). See NOTICE for full attribution. -->
+
+# peer-cli-add
+
+## Role
+
+You add a brand-new peer-CLI to gdd's delegation layer. v1.27.0 ships 5 peers (codex, gemini, cursor, copilot, qwen). When the user wants a 6th - a peer that exists in the wild but isn't in our capability matrix - you walk them through the verification ladder and produce the 3-file footprint that integrates the peer cleanly. The procedural ladder, adapter scaffold shape, and verification gate live in `./peer-cli-protocol.md`.
+
+## Invocation Contract
+
+- **Required input:** `<new-peer-id>` (lowercase, e.g. `aider`), `<peer-binary>` (executable, e.g. `aider` or `aider.cmd`), `<protocol>` (`acp` or `asp`).
+- **Output:** a 3-file diff + a verification report.
+
+## Procedure
+
+### Step 1 - Verification ladder (no edits yet)
+
+Walk the four-rung ladder in `./peer-cli-protocol.md` §"Verification ladder":
+
+1. Binary on PATH (`which` / `where`).
+2. Handshake test (`initialize` JSON-RPC over stdin; capture reply).
+3. Model-ID `-preview`-suffix trap (capture model list).
+4. Windows quirks (confirm `spawn-cmd.cjs` picks up `.cmd`).
+
+Stop at the first failing rung. Do not proceed to scaffold a broken adapter.
+
+### Step 2 - Generate the adapter scaffold
+
+Copy one of `scripts/lib/peer-cli/adapters/{codex,gemini,cursor,copilot,qwen}.cjs` as the template (pick by protocol - ASP for `<protocol>=asp`, else ACP). Replace `ROLES_CLAIMED`, `ROLE_PREFIX`, `name`, `protocol` with the user's values from Step 1. The full adapter scaffold shape - `claims`, `dispatch`, exports - lives in `./peer-cli-protocol.md` §"Adapter scaffold shape" so consumers (codex/gemini/cursor/copilot/qwen) stay byte-similar.
+
+Write the result to `scripts/lib/peer-cli/adapters/<new-peer-id>.cjs`.
+
+### Step 3 - Three-file footprint
+
+Per `./peer-cli-protocol.md` §"Three-file footprint":
+
+1. New adapter at `scripts/lib/peer-cli/adapters/<new-peer-id>.cjs` (Step 2).
+2. Edit `scripts/lib/install/runtimes.cjs` - add `peerBinary` field (platform-aware: `<peer-binary>.cmd` on Windows, plain on POSIX).
+3. Edit `reference/peer-cli-capabilities.md` - add matrix row + per-peer section citing the Step 1 verification evidence.
+4. Edit `scripts/lib/peer-cli/registry.cjs` - append to `CAPABILITY_MATRIX` (and `KNOWN_PEERS` if separate).
+
+### Step 4 - Verification gate
+
+Run the four-check gate in `./peer-cli-protocol.md` §"Verification gate": `tsc --noEmit`, peer-cli tests, reference-registry round-trip, frontmatter validator. Any failure - surface error + offer revert.
+
+### Step 5 - Surface the summary
+
+```
+## peer-cli-add summary
+Added peer: <new-peer-id> (protocol: <protocol>)
+Roles claimed: <role-1>, <role-2>
+
+Files modified:
+✓ scripts/lib/peer-cli/adapters/<new-peer-id>.cjs (new)
+✓ scripts/lib/install/runtimes.cjs (added peerBinary entry)
+✓ reference/peer-cli-capabilities.md (added matrix row + per-peer section)
+✓ scripts/lib/peer-cli/registry.cjs (added to CAPABILITY_MATRIX)
+
+Verification:
+✓ tsc clean
+✓ existing peer-cli tests pass
+✓ reference-registry round-trip valid
+✓ frontmatter validator: 0 violations
+
+Next steps:
+- {{command_prefix}}peers to confirm the new peer appears in the matrix.
+- skills/peer-cli-customize/SKILL.md to wire delegate_to: <new-peer-id>-<role> on agents.
+- Phase 23.5 bandit needs ~5 cycles of data before a posterior recommendation surfaces.
+```
+
+## Edge cases
+
+See `./peer-cli-protocol.md` §"Edge cases" for: peer speaks neither protocol, claims unknown role, claims all roles (generalist), peer-ID conflicts, and testing-only peers.
+
+## Record
+
+Append one JSONL line to `.design/skill-records.jsonl`:
+
+```json
+{"skill": "peer-cli-add", "ts": "<ISO timestamp>", "new_peer": "<new-peer-id>", "protocol": "<protocol>", "roles_claimed": ["<role-1>"], "verification_passed": true}
+```

package/scripts/skill-templates/peer-cli-add/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/scripts/skill-templates/peer-cli-customize/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: peer-cli-customize
+description: "Rewire role->peer mappings on a per-agent basis. File-edit-driven (touches frontmatter delegate_to: per agent), no runtime config layer. Run when you want a specific agent to delegate to a different peer than the default capability-matrix mapping suggests."
+argument-hint: "[<agent-name>] [<new-delegate-target>]"
+tools: Read, Edit, Bash, Grep
+---
+
+<!-- Procedural pattern adapted from greenpolo/cc-multi-cli's `customize` skill (Apache 2.0). See NOTICE for full attribution. -->
+
+# peer-cli-customize
+
+## Role
+
+You help the user rewire which peer-CLI delegate handles which agent's calls. The mechanism is direct file-edits to agent frontmatter (`delegate_to:` field added in Plan 27-06) - there is no runtime config layer. Your job is to make this safe and validatable. The rewire discipline (per-edit validation, three frontmatter cases, validator gate) lives in `./../peer-cli-add/peer-cli-protocol.md` §"Rewire discipline" so the procedure stays canonical across consumers.
+
+## Invocation Contract
+
+- **Optional input**: agent-name + new delegate target. If absent, the skill runs in interactive discovery mode.
+- **Output**: a diff summary listing each `agents/*.md` file modified, the old vs new `delegate_to:` value, and the validation result.
+
+## Procedure
+
+### Step 1 - Show current state
+
+Read the capability matrix from `scripts/lib/peer-cli/registry.cjs#describeCapabilities()`. Surface the 5 peers and their claimed roles to the user. Then scan `agents/*.md` and grep for `delegate_to:` frontmatter values. Render a two-column table (`Agent | delegate_to (current)`) listing every agent's current setting (or `(unset)` for absent fields).
+
+### Step 2 - Confirm rewire intent
+
+Accept the user's explicit `<agent-name> <new-delegate-target>` arguments OR ask: "Which agent do you want to rewire? What should `delegate_to:` become?"
+
+Valid `<new-delegate-target>` values:
+
+- `<peer>-<role>` from the capability matrix (e.g., `gemini-research`, `codex-execute`, `cursor-debug`, `cursor-plan`, `copilot-review`, `copilot-research`, `qwen-write`).
+- `none` - explicit opt-out.
+- Empty / `(unset)` - remove the field entirely; revert to default behavior.
+
+### Step 3 - Validate the proposed rewire
+
+Cross-check against the capability matrix per `./../peer-cli-add/peer-cli-protocol.md` §"Rewire discipline":
+
+1. The peer must exist in the matrix.
+2. The role must be in the peer's `claims` list.
+3. Runtime allowlisting (`peer_cli.enabled_peers`) is a runtime concern, NOT a frontmatter validation concern.
+
+If validation fails, surface the error and stop. Do not edit the file.
+
+### Step 4 - Apply the edit
+
+Use the `Edit` tool. Three cases (per `./../peer-cli-add/peer-cli-protocol.md` §"Rewire discipline"):
+
+- **Field absent, user wants to add:** insert `delegate_to: <new-target>` into frontmatter (between `default-tier:` and the next field, or at the end of frontmatter).
+- **Field present, user wants to change:** replace the value; preserve indentation.
+- **Field present, user wants to remove:** delete the entire `delegate_to:` line.
+
+### Step 5 - Re-validate
+
+Run `npm run validate:frontmatter`. Confirm the modified agent passes. If validation fails, surface the error and offer to revert (re-run `Edit` with inverse old/new strings).
+
+### Step 6 - Surface a diff summary
+
+```
+## Rewire summary
+✓ design-verifier: delegate_to: gemini-research → cursor-debug
+✓ design-reflector: delegate_to (unset) → codex-execute
+
+frontmatter validator: 0 violations (40 files checked)
+Next time these agents are spawned, session-runner dispatches through the new peer.
+
+Verify: {{command_prefix}}peers (shows updated allowlist + capability matrix).
+```
+
+## Edge cases
+
+See `./../peer-cli-add/peer-cli-protocol.md` §"Edge cases" for: rewire-to-unmatrixed-peer (direct user to `peer-cli-add` first), rewire-to-unclaimed-role (refuse with helpful list), bulk-rewire (require explicit confirmation), validator-fails-post-edit (revert and surface).
+
+## Cross-references
+
+- `./../peer-cli-add/peer-cli-protocol.md` - rewire discipline, three frontmatter cases, edge cases.
+- `scripts/validate-frontmatter.ts` (Plan 27-06) - `delegate_to` validation.
+- `scripts/lib/peer-cli/registry.cjs` (Plan 27-05) - capability matrix.
+- `skills/peer-cli-add/SKILL.md` - for adding a NEW peer (this skill rewires among existing peers).
+
+## Record
+
+After execution, append one JSONL line to `.design/skill-records.jsonl`:
+
+```json
+{"skill": "peer-cli-customize", "ts": "<ISO timestamp>", "agents_rewired": ["design-verifier", "design-reflector"], "validator_passed": true}
+```

package/scripts/skill-templates/peers/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: gdd-peers
+description: "Discover peer-CLI capability matrix - which of {codex, gemini, cursor, copilot, qwen} are installed, allowlisted in .design/config.json, and (if Phase 23.5 has data) their cost/quality delta vs local. Single command, no flags. Read by users investigating delegation setup."
+argument-hint: ""
+tools: Read, Bash
+---
+
+# gdd-peers
+
+## Role
+
+You are a deterministic discovery skill. You do not spawn agents and do not delegate to peers. You read `scripts/lib/install/runtimes.cjs`, `scripts/lib/peer-cli/registry.cjs`, `.design/config.json`, and (optionally) `.design/telemetry/posterior.json` (canonical path declared by `bandit-router.cjs`'s `DEFAULT_POSTERIOR_PATH`), then emit a single Markdown table summarizing peer-CLI status. Protocol-level handshake details live in `./../peer-cli-add/peer-cli-protocol.md`.
+
+## Invocation Contract
+
+- **Input**: none. The skill takes no arguments.
+- **Output**: a Markdown capability-matrix table to stdout. The table is the entire output.
+
+## Procedure
+
+### 1. Load runtime + capability matrix
+
+Read `scripts/lib/install/runtimes.cjs` (14 entries; 5 carry `peerBinary`) and `scripts/lib/peer-cli/registry.cjs#describeCapabilities()`. The canonical declared matrix:
+
+| Peer    | Roles claimed            | Protocol |
+|---------|--------------------------|----------|
+| codex   | execute                  | ASP      |
+| gemini  | research, exploration    | ACP      |
+| cursor  | debug, plan              | ACP      |
+| copilot | review, research         | ACP      |
+| qwen    | write                    | ACP      |
+
+### 2. Detect installation
+
+For each peer, run `which <peerBinary>` (POSIX) or `where <peerBinary>` (Windows). Exit 0 → installed; non-zero → not installed.
+
+### 3. Read allowlist
+
+Read `.design/config.json#peer_cli.enabled_peers` (array of peer-IDs). Default `[]` (opt-in required). Missing file or path = empty.
+
+### 4. (Optional) Read posterior reward-delta
+
+Once Phase 27.5 has fired across enough spawns, `.design/telemetry/posterior.json` carries per-`(agent, bin, delegate, tier)` arms with measured reward. For each peer-id:
+
+1. Filter `arms` array: `peerArms` where `delegate === <peer-id>`; `localArms` where `delegate === 'none'` OR `delegate === undefined` (Phase 23.5 legacy slice treated as local-call).
+2. Require `peerArms` and `localArms` both non-empty. Else `(no data yet)`.
+3. Compute pooled means: `mean = sum(alpha) / (sum(alpha) + sum(beta))` over each slice.
+4. `delta_pct = (peerMean - localMean) / localMean`.
+5. Require `sum(arm.count)` ≥ 3 in each slice. Else `(no data yet)`.
+6. Render: `+X% reward` (delta > 0.01), `-X% reward` (delta < -0.01), or `~equal` (`abs(delta) < 0.01`), where `X = round(abs(delta_pct) * 100)`.
+
+Reward is the Phase 23.5 lexicographic (correctness first, cost tiebreaker - see `scripts/lib/bandit-router.cjs` `computeReward()`). Cost-only deltas live in `cost-arbitrage.cjs` (Phase 26-06).
+
+### 5. Render the table
+
+```
+## Peer-CLI Capability Matrix
+
+| Peer    | Installed | Allowlisted | Claimed roles            | Posterior delta vs local |
+|---------|-----------|-------------|--------------------------|--------------------------|
+| codex   | ✓         | ✓           | execute                  | -12% reward              |
+| gemini  | ✓         | ✓           | research, exploration    | -8% reward               |
+| cursor  | ✗         | ✗           | debug, plan              | (not installed)          |
+| copilot | ✓         | ✗           | review, research         | (opt-in disabled)        |
+| qwen    | ✓         | ✓           | write                    | (no data yet)            |
+
+> Tip: Enable peers via `.design/config.json#peer_cli.enabled_peers`.
+> See `reference/peer-cli-capabilities.md` for the full capability matrix.
+> See `skills/peer-cli-customize/SKILL.md` to rewire role->peer mappings per agent.
+```
+
+**Third-column rules** (top-down precedence):
+
+- `Installed = ✗` → `(not installed)`.
+- `Allowlisted = ✗` → `(opt-in disabled)`.
+- Posterior missing → `(no data yet)`.
+- < 3 pulls per side → `(no data yet)`.
+- Else compute the reward-delta per Step 4.
+
+### 6. Done
+
+The table IS the output. No follow-up prose. Users act on it: `(opt-in disabled)` → enable in `.design/config.json`; `(not installed)` → install the peer CLI; concrete deltas → trust the bandit or override per-agent via `skills/peer-cli-customize`.
+
+## Cross-references
+
+- `./../peer-cli-add/peer-cli-protocol.md` - ACP/ASP handshake + adapter scaffold (procedure ref shared with peer-cli-add/customize).
+- `./reference/peer-cli-capabilities.md` (Plan 27-05) - full capability matrix doc.
+- `scripts/lib/peer-cli/registry.cjs` (Plan 27-05), `scripts/lib/install/runtimes.cjs` (Plan 27-11), `skills/peer-cli-customize/SKILL.md`, `skills/peer-cli-add/SKILL.md`.
+
+## Record
+
+Append one JSONL line to `.design/skill-records.jsonl`:
+
+```json
+{"skill": "gdd-peers", "ts": "<ISO timestamp>", "peers_detected": ["codex"], "peers_allowlisted": ["codex"], "had_posterior": false}
+```

package/scripts/skill-templates/pencil-write/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: gdd-pencil-write
+description: "Update local `.pen` source files with design decisions from `.design/DESIGN-CONTEXT.md` by dispatching the `design-pencil-writer` agent in one of two modes (annotate / roundtrip). Use when the user has completed a design pipeline cycle and wants the decisions reflected in their `.pen` files. Operates proposal->confirm with `--dry-run`."
+argument-hint: "<annotate|roundtrip> [--dry-run]"
+user-invocable: true
+tools: Read, Write, Bash, Grep, Glob
+---
+
+# gdd-pencil-write
+
+Dispatches the `design-pencil-writer` agent to write design decisions back to `.pen` spec files. Unlike Figma/paper.design, pencil.dev keeps `.pen` YAML specs as the project's git-tracked source of truth; no MCP is required and every write is committed atomically. The probe pattern (file-based, no ToolSearch) and integration contract are documented at `../../connections/pencil-dev.md`.
+
+## Usage
+
+```
+/get-design-done pencil-write <mode> [--dry-run]
+```
+
+Modes:
+- `annotate` - append DESIGN-DEBT findings as comments to the relevant `.pen` files
+- `roundtrip` - update `.pen` spec frontmatter (design-tokens, state) from verified implementation
+
+There is no `tokenize` mode; `.pen` files are source-of-truth specs, not derived artifacts.
+
+Flags:
+- `--dry-run` - emit the proposal without writing or committing any `.pen` changes
+
+## Prerequisites
+
+1. pencil.dev workspace detected; one or more `.pen` files in `cwd` (no MCP install required):
+   ```bash
+   find . -name "*.pen" -not -path "*/node_modules/*" | head -5
+   ```
+2. `.design/DESIGN-CONTEXT.md` exists (run `discover` first). For `annotate` mode, `.design/DESIGN-DEBT.md` is also required. For `roundtrip` mode, `.design/DESIGN-VERIFICATION.md` is also required.
+3. `.design/STATE.md` `<connections>` shows `pencil-dev: available`. If `not_configured`, no `.pen` files were found at probe time; re-run `discover` or `connections` after adding `.pen` specs.
+
+## Required Reading
+
+Read `.design/STATE.md` and `.design/DESIGN-CONTEXT.md` before dispatching the agent.
+
+## Dispatch
+
+```
+Task("design-pencil-writer", """
+mode: <annotate|roundtrip>
+dry_run: <true|false>
+required_reading:
+  - .design/STATE.md
+  - .design/DESIGN-CONTEXT.md
+""")
+```
+
+Pass `mode` from the first positional argument; `dry_run` from `--dry-run`.
+Wait for the agent's completion marker before returning.

package/scripts/skill-templates/pin/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: gdd-pin
+description: "Writes standalone shortcut aliases for a gdd skill across installed harness skill dirs. Use when you want a skill directly discoverable as its own command in every installed runtime."
+argument-hint: "<skill-name>"
+tools: Read, Bash
+---
+
+# {{command_prefix}}pin
+
+**Role:** Write a standalone shortcut alias (a small SKILL.md stub) for one gdd skill into every installed harness `skills/` directory, so that skill is directly discoverable as its own command in each runtime (Claude Code, Codex, Cursor, Gemini, and the rest).
+
+Each pinned stub starts with the marker line `<!-- gdd-pinned-skill source=<skill> -->`, then carries frontmatter (name, description, argument-hint, tools) pulled from the manifest source of truth, then a one-line body pointing back at the canonical skill. Stubs are written atomically (temp file plus rename), so a failed write never leaves a half-written file.
+
+## Steps
+
+1. **Read the argument.** The skill name to pin comes from `$ARGUMENTS` (for example `darkmode`). If it is empty, ask the user which skill to pin and stop.
+
+2. **Run the pin CLI.** Invoke the shipped script, passing the skill name. The plugin root resolves via `CLAUDE_PLUGIN_ROOT` (falling back to the current directory when that variable is absent):
+
+    ```bash
+    node "${CLAUDE_PLUGIN_ROOT:-$(pwd)}/scripts/lib/pin/cli.cjs" pin "<skill-name>"
+    ```
+
+    The CLI detects every harness `skills/` directory that exists under the current project (`.claude/skills`, `.cursor/skills`, and so on) and writes the stub into each. Pass `--user` to also create the harness directories that do not exist yet:
+
+    ```bash
+    node "${CLAUDE_PLUGIN_ROOT:-$(pwd)}/scripts/lib/pin/cli.cjs" pin "<skill-name>" --user
+    ```
+
+3. **Report the result.** The CLI prints one line per harness it wrote to, plus any skips. Relay that summary verbatim. Exit codes: 0 means at least one stub was written, 1 means nothing was written (no harness dirs found, suggest `--user`), 2 means an error (for example an unknown skill name).
+
+## Do Not
+
+- Do not hand-write the stub files. Always go through the CLI so the marker, the manifest-sourced frontmatter, and the atomic write stay consistent.
+- Do not pin a skill that is not in the manifest. The CLI rejects unknown skill names with exit code 2; surface that error rather than inventing a stub.
+
+## PIN COMPLETE

package/scripts/skill-templates/plan/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: plan
+description: "Stage 3 of 5 orchestrator that reads DESIGN-CONTEXT.md, runs optional research (phase-researcher / pattern-mapper / assumptions-analyzer / synthesizer), spawns design-planner + design-plan-checker, and writes DESIGN-PLAN.md. Use when DESIGN-CONTEXT.md is locked and you need a wave-ordered execution plan. Activates for requests involving breaking design work into steps, sequencing implementation, or planning a build."
+argument-hint: "[--auto] [--parallel]"
+user-invocable: true
+tools: Read, Write, Bash, Glob, Task, AskUserQuestion, ToolSearch, mcp__gdd_state__get, mcp__gdd_state__transition_stage, mcp__gdd_state__add_decision, mcp__gdd_state__add_must_have, mcp__gdd_state__update_progress, mcp__gdd_state__set_status, mcp__gdd_state__add_blocker, mcp__gdd_state__checkpoint, mcp__gdd_state__probe_connections
+---
+
+# Get Design Done - Plan
+
+**Stage 3 of 5** in the get-design-done pipeline. Thin orchestrator. All planning intelligence lives in `agents/design-planner.md`.
+
+Full procedure detail: `./plan-procedure.md`.
+
+---
+
+## Stage entry
+
+1. `mcp__gdd_state__transition_stage` with `to: "plan"`. Gate failure surfaces `error.context.blockers`; do not advance.
+2. `mcp__gdd_state__get` -> snapshot `state` for `<position>`, `<connections>`, `<must_haves>`, `<blockers>`, `<decisions>`. Do not re-read STATE.md directly.
+3. Abort only if `.design/DESIGN-CONTEXT.md` is missing - that is the true prerequisite, not STATE.md.
+
+---
+
+## Flags + parallelism
+
+- `--auto` -> `auto_mode=true` (skip approvals, skip optional research).
+- `--parallel` -> `parallel_mode=true` (planner fills `Touches:`/`Parallel:` fields).
+- **Parallelism decision**: read `.design/config.json` + `reference/parallelism-rules.md`. Plan pipeline is inherently sequential (researcher -> pattern-mapper -> planner -> checker) so the expected verdict is **serial** (rule 1). Record via `mcp__gdd_state__update_progress` with `status: "plan_parallelism_decided: batch_size=<N>, reason=<short-reason>"`.
+
+## Probe Chromatic connection
+
+Probe `chromatic` (CLI presence + `CHROMATIC_PROJECT_TOKEN` check; auto-`unavailable` if `storybook: not_configured`), then write status via `mcp__gdd_state__probe_connections` (single-entry array, never edit `<connections>` directly). Detail: `./plan-procedure.md` §Probe Chromatic connection.
+
+When `chromatic: available`, run change-risk scoping before writing DESIGN-PLAN.md: identify token/component files in scope from DESIGN-CONTEXT.md, run `npx chromatic --trace-changed=expanded --dry-run`, count story files that depend on changed source files, and pass the story count to the design-planner spawn prompt. Detail: `./plan-procedure.md` §Chromatic Change-Risk Scoping.
+
+---
+
+## Step 1 - Optional Research (skip if `auto_mode`)
+
+Complexity heuristic: DESIGN-CONTEXT.md `<domain>` spans 3+ scopes OR `<decisions>` count > 6 -> spawn `design-phase-researcher` -> `.design/DESIGN-RESEARCH.md` (~100 lines, ~2 min). Wait for `## RESEARCH COMPLETE`, then `update_progress` `task_progress: "1/3"`. Full prompt: `./plan-procedure.md` §Step 1.
+
+## Step 1.5 - Pattern Mapping (mandatory, brownfield protection)
+
+Spawn `design-pattern-mapper` -> `.design/DESIGN-PATTERNS.md` (classify by design concern, not by code architecture - no controllers/services/middleware vocabulary). Wait for `## MAPPING COMPLETE`. Full prompt: `./plan-procedure.md` §Step 1.5.
+
+## Step 1.6 - Assumptions Analysis (skip if `auto_mode`)
+
+If assumptions analysis is enabled: spawn `design-assumptions-analyzer` -> surfaces hidden design assumptions with confidence + evidence. Wait for `## ANALYSIS COMPLETE`. Full prompt: `./plan-procedure.md` §Step 1.6.
+
+## Step 1.7 - Synthesize pre-plan inputs (Plan 10.1-04, D-13/D-15)
+
+If 2+ pre-plan agents ran (Step 1, 1.5, 1.6), invoke `Skill("synthesize", { outputs, directive, output_shape: "markdown" })` to merge their outputs into `.design/DESIGN-PREPLAN-BRIEF.md` (~150 lines, per-source headers preserved). Add the brief to the planner's `<required_reading>` in Step 2. If only one agent ran, skip. Full call signature + parallel-synthesizer note: `./plan-procedure.md` §Step 1.7.
+
+**Research-synthesis persistence:** for each D-XX the synthesizer produces, `mcp__gdd_state__add_decision`; for each M-XX, `mcp__gdd_state__add_must_have`. Issue sequentially (lockfile-bound). Detail: `./plan-procedure.md` §Research-synthesis persistence.
+
+---
+
+## Step 2 - Plan
+
+Spawn `design-planner` with `<required_reading>` covering STATE.md, DESIGN-CONTEXT.md, DESIGN-PATTERNS.md, plus (conditionally) DESIGN-RESEARCH.md, DESIGN-ASSUMPTIONS.md, DESIGN-PREPLAN-BRIEF.md (preferred when 1.7 ran), all `.design/sketches/*/WINNER.md`, all `.design/spikes/*/FINDINGS.md`, and all `./.claude/skills/design-*-conventions.md` + `~/.claude/gdd/global-skills/*.md` (project-local D-XX overrides globals). Wait for `## PLANNING COMPLETE`, then `update_progress` `task_progress: "2/3"`. Full prompt + conditional include syntax: `./plan-procedure.md` §Step 2.
+
+## Step 3 - Check
+
+Spawn `design-plan-checker` to validate DESIGN-PLAN.md against DESIGN-CONTEXT.md across 5 dimensions: requirement coverage, task completeness, wave ordering, must-have derivation, auto-mode compliance. Wait for `## PLAN CHECK COMPLETE`, then `update_progress` `task_progress: "3/3"`. On `## PLAN CHECK RESULT: ISSUES FOUND` + BLOCKER: offer revise/accept/abort (`auto_mode`: auto-accept WARN, abort on BLOCKER). Full prompt + branching: `./plan-procedure.md` §Step 3.
+
+---
+
+## Stage exit
+
+1. `mcp__gdd_state__set_status` -> `"plan_complete"`.
+2. `mcp__gdd_state__checkpoint` - stamps `last_checkpoint` and finalizes 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.
+
+## After Completion
+
+Print: plan tasks (N waves, M total tasks), files written (`.design/DESIGN-PLAN.md`, plus `.design/DESIGN-RESEARCH.md` if research ran), next step `/get-design-done:design`.
+
+## Spec self-review (before transition)
+
+Run this final spec-quality pass over `.design/DESIGN-PLAN.md` before the plan→design transition:
+- Placeholder scan: no TBD / TODO / `<placeholder>` / lorem left in the artifact.
+- Internal consistency: sections don't contradict each other.
+- Scope check: nothing in the artifact exceeds (or silently drops) the agreed scope.
+- Ambiguity check: every requirement/decision is specific enough to act on without a follow-up question.
+
+<HARD-GATE>
+Do NOT transition to design (or invoke `{{command_prefix}}design`) until `.design/DESIGN-PLAN.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
+
+The reasons an agent gives to skip planning or rush DESIGN-PLAN.md, and what each one costs:
+
+| Thought | Reality |
+|---------|---------|
+| "This change is small, I can design straight from DESIGN-CONTEXT.md." | Plan-skipped tasks blow scope per cycle telemetry; the plan gate is for the typical case, not the exception you think you're in. |
+| "Pattern mapping is brownfield ceremony, I'll skip it." | Step 1.5 is mandatory because an unmapped brownfield is where the executor silently re-implements an existing pattern. |
+| "The plan-checker will just rubber-stamp it, skip the spawn." | The checker's 5 dimensions (coverage, wave order, must-have derivation) catch the gaps you can't see in your own plan. |
+| "I'll let the planner infer wave ordering at design time." | Unordered waves serialize work that could parallelize - or worse, run dependent tasks concurrently and corrupt the tree. |
+| "Research is overkill for this scope." | The complexity heuristic exists precisely because agents under-estimate scope; skipping research on a 3+-scope domain guarantees a mid-design surprise. |
+| "I can record decisions in DESIGN-PLAN.md prose instead of D-XX." | Prose decisions never reach STATE.md, so verify's integration-checker can't trace them and flags them orphaned. |
+
+## PLAN COMPLETE