@hegemonart/get-design-done 1.59.3 → 1.59.5

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

@@ -0,0 +1,90 @@
+---
+name: gdd-new-skill
+description: "Scaffolds a new Phase-28.5 + Phase-50-compliant skill: gathers a name, a multi-paragraph v3 description, a lifecycle stage, an allowed-tools list, and optional composes_with neighbours, then writes scripts/skill-templates/<name>/SKILL.md from the pure generator. Use when adding a brand-new gdd skill and you want the frontmatter, length cap, and v3 description form correct from the first commit. Activates for requests involving authoring a skill, scaffolding a command, creating a new SKILL.md, or adding a slash command."
+argument-hint: "<skill-name>"
+tools: Read, Write, Bash, AskUserQuestion
+user-invocable: true
+---
+
+# {{command_prefix}}new-skill
+
+**Role:** Interactively scaffold a contract-compliant skill. Gather the fields, then write `scripts/skill-templates/<name>/SKILL.md` from the pure generator at `scripts/lib/manifest/scaffolder.cjs`. This skill writes ONE source file. It does NOT touch `scripts/lib/manifest/skills.json` and does NOT run the build; it prints the exact follow-up commands instead.
+
+Read `reference/skill-authoring-contract.md` first for the length cap, the frontmatter required fields, and the v3 description form.
+
+## Prompt strategy (clack with a fallback)
+
+Mirror the installer pattern in `scripts/install.cjs`: try `@clack/prompts` lazily, and degrade to `AskUserQuestion` (or plain text) when it is absent. Use this probe at the start:
+
+```bash
+node -e "try { require.resolve('@clack/prompts'); console.log('clack'); } catch { console.log('fallback'); }"
+```
+
+- `clack`: drive `clack.text`, `clack.select`, and `clack.confirm` from a short Node script.
+- `fallback`: ask the same questions with `AskUserQuestion` (one prompt per field), or read plain answers.
+
+Either way the answers feed the same record builder. Never block waiting on a TTY in a non-interactive run; fall back to `AskUserQuestion`.
+
+## Step 1 - Gather the fields
+
+1. **name**: the slug from `$ARGUMENTS` if present, else ask. Must match `^[a-z0-9][a-z0-9-._]*$`. Reject `scripts/skill-templates/<name>/` collisions.
+2. **description**: a multi-paragraph v3 form. Sentence one is what the skill does. Sentence two is `Use when <triggers>`. Sentence three is `Activates for requests involving <kw1>, <kw2>, <kw3>.` Keep it 20 to 1024 chars.
+3. **lifecycle stage**: pick one of brief / explore / plan / verify / ship / figma / token / report (free text allowed). This seeds the composition suggestions.
+4. **tools**: a comma list (for example `Read, Write, Bash`). Empty means inherit-all.
+5. **composes_with**: auto-suggest neighbours, then confirm. Compute the suggestion list:
+
+```bash
+node -e "
+const s = require('./scripts/lib/manifest/scaffolder.cjs');
+const m = require('./scripts/lib/manifest/skills.json');
+console.log(JSON.stringify(s.suggestComposesWith(process.argv[1], m.skills)));
+" "<name>"
+```
+
+Present the suggestions; let the user accept, edit, or clear them.
+
+## Step 2 - Length pre-check
+
+Before writing, estimate the body length. If the planned body would exceed about 100 lines, warn the user (the authoring contract warns at 100 and blocks at 250) and suggest extracting domain content into a co-located `scripts/skill-templates/<name>/<topic>.md` reference. The generated skeleton is small; the warning is for the prose the user will add next.
+
+## Step 3 - Write the file
+
+Build the record and render the file with the pure generator, then write it with the Write tool (not shell redirection):
+
+```bash
+node -e "
+const s = require('./scripts/lib/manifest/scaffolder.cjs');
+const rec = s.buildSkillRecord({
+  name: process.env.SK_NAME,
+  description: process.env.SK_DESC,
+  argumentHint: process.env.SK_HINT || undefined,
+  tools: process.env.SK_TOOLS || undefined,
+  userInvocable: process.env.SK_UI === 'true',
+  composesWith: (process.env.SK_COMPOSES || '').split(',').map(x => x.trim()).filter(Boolean),
+});
+process.stdout.write(s.renderSkillMd(rec));
+"
+```
+
+`buildSkillRecord` throws on an invalid name, an out-of-budget description, or a malformed tools list. Surface the thrown message to the user and re-prompt the offending field. Capture stdout and write it verbatim to `scripts/skill-templates/<name>/SKILL.md` via the Write tool.
+
+## Step 4 - Tell the user the follow-up
+
+The skill stops here by contract. Print the next two commands for the user to run after they add the manifest record:
+
+```
+1. Add a record for "<name>" to scripts/lib/manifest/skills.json
+   (description, argument_hint, tools, user_invocable; put composes_with in extra_frontmatter).
+2. npm run generate:skill-frontmatter && npm run build:skills
+```
+
+Note that `npm run generate:skill-frontmatter:check` and the skills-coverage test stay red until the manifest record exists; that is expected and is the maintainer's step.
+
+## Do Not
+
+- Do not edit `scripts/lib/manifest/skills.json`, `package.json`, or any reference doc.
+- Do not run `build:skills` or `generate:skill-frontmatter` for the user; print the commands.
+- Do not write the SKILL.md with shell redirection; use the Write tool so the content is exact.
+- Do not invent a description; require the v3 three-sentence form from the user.
+
+## NEW-SKILL COMPLETE

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

@@ -0,0 +1,68 @@
+---
+name: gdd-next
+description: "Routes to the next pipeline stage based on current STATE.md position"
+tools: Read, Write, mcp__gdd_status, mcp__gdd_phase_current, mcp__gdd_plans_list
+disable-model-invocation: true
+---
+
+# Get Design Done - Next
+
+**Role:** Lightweight router. Read `.design/STATE.md` and recommend the next command.
+
+---
+
+## Logic
+
+Two paths - MCP preferred when available, file-read fallback otherwise.
+
+### MCP path (preferred)
+
+When `mcp__gdd_phase_current` is exposed (Phase 27.7+, registered via `npx @hegemonart/get-design-done --register-mcp`):
+
+1. Call `mcp__gdd_status` (no args) → `{phase, branch, last_decisions, last_completed_plans, blocker_count}`. Gives cycle + branch context for the output block in one call.
+2. Call `mcp__gdd_phase_current` (no args) → `{phase, stage, task_progress, status}`. Use `stage` to drive the routing table below.
+3. (Optional) Call `mcp__gdd_plans_list` (no args) → current phase plans + status, to identify the next incomplete plan and refine the recommendation.
+4. If `mcp__gdd_status` returns a "STATE.md missing" error, print: "No STATE.md found. Run `{{command_prefix}}new-project` to initialize, or `@get-design-done brief` to start the pipeline." and stop. Otherwise, skip to the routing table.
+
+Two to three MCP calls = full routing decision (~3s, ~32k tokens - Storybloq benchmark).
+
+### File-read path (fallback)
+
+When MCP tools are not available, fall back to the legacy flow:
+
+1. Check if `.design/STATE.md` exists.
+   - **No STATE.md** → Print: "No STATE.md found. Run `{{command_prefix}}new-project` to initialize, or `@get-design-done brief` to start the pipeline."
+2. If STATE.md exists, parse frontmatter `stage:` field. Proceed to the routing table.
+
+This path loads the same context in 1–2 file reads (~20s, ~46.5k tokens - file-reading baseline).
+
+## Routing table
+
+Map the `stage` (from either path above) to the next recommended command:
+
+| Current `stage:` | Recommendation |
+|---|---|
+| `brief` | Run `@get-design-done explore` to scan and interview |
+| `explore` | Run `@get-design-done plan` to create design plan |
+| `plan` | Run `@get-design-done design` to execute design tasks |
+| `design` | Run `@get-design-done verify` to audit and verify |
+| `verify` | Pipeline complete. Run `{{command_prefix}}new-cycle` for next cycle or `{{command_prefix}}ship` to create PR |
+
+## Output
+
+Print the recommendation as a single formatted block:
+
+```
+━━━ Next step ━━━
+Current stage: <stage>
+Status: <status>
+→ <recommendation>
+━━━━━━━━━━━━━━━━━━
+```
+
+## Do Not
+
+- Do not modify STATE.md.
+- Do not invoke the next stage automatically - only recommend.
+
+## NEXT COMPLETE

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

@@ -0,0 +1,48 @@
+---
+name: gdd-note
+description: "Zero-friction idea capture during any stage. Appends to .design/NOTES.md. Subcommands: add, list, promote."
+argument-hint: "<add|list|promote> [text|line-number]"
+tools: Read, Write
+disable-model-invocation: true
+---
+
+# {{command_prefix}}note
+
+**Role:** Ephemeral design notes. Zero ceremony - no priority, no due date. Backing store: `.design/NOTES.md`.
+
+## File format
+
+```markdown
+# Design Notes
+
+- [2026-04-18 04:55] Consider revisiting the card border-radius after Phase 7 ships
+- [2026-04-18 05:10] [promoted → todo] Try a glassmorphism treatment for the sidebar
+```
+
+## Subcommands
+
+### add [text]
+Create `.design/NOTES.md` with header if missing. Append one line:
+```
+- [YYYY-MM-DD HH:MM] <text>
+```
+If text omitted, append a blank timestamped entry for the user to fill later:
+```
+- [YYYY-MM-DD HH:MM] 
+```
+
+### list
+Read `.design/NOTES.md`. Print each note line with its line number for use with `promote`.
+
+### promote [line-number]
+Read the note at that line. Delegate to `{{command_prefix}}todo add` by writing a new P2 entry into `.design/TODO.md` directly (format: `- [ ] [YYYY-MM-DD] <text>` under `## P2 — Normal`). Rewrite the original note line in NOTES.md with `[promoted → todo]` prefix before the text:
+```
+- [2026-04-18 05:10] [promoted → todo] <original text>
+```
+
+## Constraints
+
+- Never overwrite prior notes on `add`.
+- Preserve exact line order on `promote`.
+
+## NOTE COMPLETE

package/scripts/skill-templates/openrouter-status/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: gdd-openrouter-status
+description: "Read-only OpenRouter catalog + tier-mapping diagnostic - surfaces catalog freshness (fetched_at vs the 24h TTL), the last-fetch timestamp, the resolved opus/sonnet/haiku → model mappings (via the Phase-33.6 adapter), and a per-tier preview. Use when investigating which OpenRouter model a tier resolves to, or whether the catalog cache is fresh/stale. Phase 33.6 (v1.33.6) diagnostic - {{command_prefix}}openrouter-status."
+argument-hint: "[--refresh]"
+tools: Read, Bash
+disable-model-invocation: true
+---
+
+# gdd-openrouter-status
+
+## Role
+
+You are a deterministic, read-only diagnostic skill. You do **not** spawn agents and you do **not** modify the catalog cache. You read `.design/cache/openrouter-models.json` (the Phase-33.6-01 catalog cache) via `scripts/lib/openrouter/catalog-fetcher.cjs#readCatalog`, resolve the `opus`/`sonnet`/`haiku` tiers via `scripts/lib/tier-resolver-openrouter.cjs#resolve`, and emit a single Markdown status block. Read-only - to refresh the catalog you pass `--refresh` (a single opt-in fetch gated on `OPENROUTER_API_KEY`); there is no other mutation. See `connections/openrouter.md` for setup and `reference/openrouter-tier-mapping.md` for the resolution heuristic.
+
+This is `disable-model-invocation: true` (mirroring `skills/cache-manager/SKILL.md`): the skill is user-invoked only - the model must not auto-spawn it. It never makes a model call.
+
+## Invocation Contract
+
+- **Input**: optional `--refresh`. When absent, the skill is purely read-only (cache + resolve). When `--refresh` is set AND `OPENROUTER_API_KEY` is present, it calls the Phase-33.6-01 fetcher once to refresh the cache before reading; when `--refresh` is set but no key is present, it prints the empty-state/no-key message and does NOT fetch.
+- **Output**: a Markdown OpenRouter-status block to stdout. The block is the entire output.
+
+## Procedure
+
+### 1. (Optional) refresh
+
+If `--refresh` is set and `OPENROUTER_API_KEY` is present, run a single fetch to refresh the cache:
+
+```bash
+node -e "require('./scripts/lib/openrouter/catalog-fetcher.cjs').fetchCatalog().then(()=>{}).catch(()=>{})"
+```
+
+This is the ONLY mutation the skill performs, and only on explicit `--refresh`. The fetch never throws (D-08); a failure degrades to the existing cache.
+
+### 2. Read the catalog cache
+
+Read `.design/cache/openrouter-models.json` via `readCatalog`. Missing or empty → emit the empty-state message and stop:
+
+```
+## OpenRouter Status
+
+No OpenRouter catalog yet — set OPENROUTER_API_KEY and run a cycle, or `{{command_prefix}}openrouter-status --refresh`.
+
+Tier resolution is currently falling back to the native provider (graceful degrade — D-08).
+```
+
+### 3. Compute freshness
+
+Read `fetched_at` from the cache object and compare against the 24h TTL (D-02): `age = now - fetched_at`. `age < 24h` → **fresh**; otherwise → **stale** (a stale catalog still resolves - the adapter uses the last good cache).
+
+### 4. Resolve the tiers
+
+For each of `opus`, `sonnet`, `haiku`, resolve via the adapter (it reads `.design/config.json#openrouter_tier_overrides` and applies the heuristic over the cached catalog):
+
+```bash
+node -e "const r=require('./scripts/lib/tier-resolver-openrouter.cjs');for(const t of ['opus','sonnet','haiku'])console.log(t, '->', r.resolve(t) || '(null → native fallback)')"
+```
+
+A `null` for a tier means OpenRouter has no pick → the native provider resolves that tier (D-08). Note any tier that resolved from an explicit `openrouter_tier_overrides` pin vs the heuristic.
+
+### 5. Print the status block
+
+```
+## OpenRouter Status
+
+Catalog source: <source URL from cache>
+Last fetched:   <fetched_at>  (<fresh | stale> — TTL 24h)
+Models in catalog: <count>
+
+| Tier   | Resolved model id                | Source             |
+|--------|----------------------------------|--------------------|
+| opus   | <id or (null → native fallback)> | <override | heuristic> |
+| sonnet | <id or (null → native fallback)> | <override | heuristic> |
+| haiku  | <id or (null → native fallback)> | <override | heuristic> |
+
+> Resolution: override (`.design/config.json#openrouter_tier_overrides`) wins, else the closed-vs-open + pricing heuristic over the catalog.
+> A null resolution means tier resolution falls back to the native provider (D-08).
+> Read-only — this skill never modifies the cache; use `--refresh` to re-fetch (needs OPENROUTER_API_KEY).
+```
+
+## Completion marker
+
+End the output with:
+
+```
+## OPENROUTER-STATUS COMPLETE
+```

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

@@ -0,0 +1,97 @@
+---
+name: optimize
+description: "Reads .design/telemetry/costs.jsonl + .design/agent-metrics.json, runs rule-based analysis, writes .design/OPTIMIZE-RECOMMENDATIONS.md. Pure advisory - no auto-apply. User reviews + decides."
+argument-hint: "[--refresh] [--min-spawns=N]"
+user-invocable: true
+tools: Read, Bash, Grep, Write
+---
+
+# {{command_prefix}}optimize - Optimization Advisor
+
+## Role
+
+Read the telemetry ledger (`.design/telemetry/costs.jsonl`) and per-agent aggregate (`.design/agent-metrics.json`), apply a fixed set of rule-based heuristics, and emit recommendations to `.design/OPTIMIZE-RECOMMENDATIONS.md`. Never modify agent files, budget config, or cache state. Output is a markdown table of proposals the user reviews manually, mirroring Phase 11 `{{command_prefix}}apply-reflections`. **Advisory only**: never edits `agents/*.md`, `.design/budget.json`, `.design/cache-manifest.json`. Never makes model calls - every rule is deterministic. See `./reference/heuristics.md` §"Optimization rules" for the full rule catalog.
+
+## Refresh Step
+
+Before analysis, invoke the aggregator:
+
+```bash
+node --experimental-strip-types scripts/aggregate-agent-metrics.ts
+```
+
+Idempotent. If `--refresh` absent and `.design/agent-metrics.json` generated within 60s, skip.
+
+## Inputs
+
+- `.design/telemetry/costs.jsonl` - append-only; tolerant of malformed lines.
+- `.design/agent-metrics.json` - per-agent aggregate; source of truth for `cache_hit_rate`, `lazy_skip_rate`, `total_cost_usd`, `total_spawns`.
+- `agents/*.md` - frontmatter cross-reference for tier override churn + typical-duration drift.
+- `.design/budget.json` - `tier_overrides` table (optional).
+
+## Optional Arguments
+
+- `--refresh` - force aggregator refresh even if metrics file is fresh.
+- `--min-spawns=N` - only emit recommendations for agents with ≥ N spawns (default 5).
+
+## Rules
+
+Rule-based analysis. Full thresholds + emission templates in `./reference/heuristics.md` §"Optimization rules"; here, the short rule catalog:
+
+- **R1 - Low cache hit rate.** IF `total_spawns >= --min-spawns` AND `cache_hit_rate < 0.20` → propose batching + investigate shared-preamble ordering.
+- **R2 - Expensive + rarely lazy-skipped.** IF `total_cost_usd > 0.50` AND `lazy_skip_rate < 0.10` → propose adding a lazy gate at `agents/{agent}-gate.md` (Plan 10.1-04 pattern).
+- **R3 - Tier override churn.** IF measured `tier` differs from frontmatter `default-tier` for multiple rows → propose updating frontmatter or removing budget.json override.
+- **R4 - Typical duration drift.** IF measured `typical_duration_seconds` differs from frontmatter by > 50% → propose frontmatter update. (v1 only computes wall-clock duration if both spawn + complete rows have matching correlation IDs; otherwise flag "insufficient data".)
+
+## Output Format
+
+Write `.design/OPTIMIZE-RECOMMENDATIONS.md`:
+
+```markdown
+# Optimization Recommendations
+
+**Generated:** {ISO-8601 timestamp}
+**Telemetry rows analyzed:** {N}
+**Agents analyzed:** {M}
+**Min spawns threshold:** {--min-spawns value}
+
+> Advisory only. No changes have been applied. Review each proposal and apply manually via the suggested action.
+
+## Proposals
+
+| Rule | Agent | Current | Proposed | Rationale |
+|------|-------|---------|----------|-----------|
+| R1 | ... | ... | ... | ... |
+
+## Summary
+
+- R1 matches: {count}
+- R2 matches: {count}
+- R3 matches: {count}
+- R4 matches: {count}
+
+## OPTIMIZE COMPLETE
+```
+
+The `## OPTIMIZE COMPLETE` marker is the completion sentinel.
+
+## No Auto-Apply
+
+This skill **never modifies** `agents/*.md`, `.design/budget.json`, `.design/cache-manifest.json`, or any other configuration. **Never auto-applies** proposals. If the user wants to act, they do so manually. Discipline mirrors `{{command_prefix}}apply-reflections` from Phase 11.
+
+## Integration with Phase 11 Reflector
+
+The Phase 11 reflector (`agents/design-reflector.md`) reads both `costs.jsonl` and `agent-metrics.json` on its own cadence. `{{command_prefix}}optimize` is user-facing; the reflector is automation-facing. Outputs land in different files (`.design/OPTIMIZE-RECOMMENDATIONS.md` vs `.design/reflections/*.md`) and never collide.
+
+## Non-Goals
+
+- Does not make model calls (rule-based, deterministic).
+- Does not modify config.
+- Does not propose changes outside the four rules - future rules added by future phases.
+- Does not learn from history - Phase 11 reflector territory.
+
+## Failure Modes
+
+- Missing `.design/telemetry/costs.jsonl` → emit `No telemetry data yet — run {{command_prefix}}* commands to accumulate data, then retry.` + `## OPTIMIZE COMPLETE`.
+- Missing `.design/agent-metrics.json` after refresh → emit `Aggregator failed — check node --experimental-strip-types scripts/aggregate-agent-metrics.ts output manually.`
+- Zero rules matched → write `No recommendations — all agents within healthy thresholds.` + `## OPTIMIZE COMPLETE`.

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

@@ -0,0 +1,86 @@
+---
+name: gdd-override
+description: "Escalation surface for a risk-blocked action or a fact-force gate. Use when the Phase 56 risk gate blocked a writer action (suggested_action=block) and a reviewer has signed off, or when the first-write fact-force gate is holding a file you have legitimately reviewed. Activates for requests involving overriding a blocked edit, approving a high-risk change, or clearing a fact-force hold on a path."
+argument-hint: "<finding-id | factforce <path>> [--approver <who>] [--reason <text>]"
+user-invocable: true
+tools: Read, Write, Bash, Grep, Glob
+---
+
+# {{command_prefix}}override
+
+A risk-blocked action is hard: the Phase 56 risk gate routes `suggested_action=block`
+to `override` (see `scripts/lib/risk/route.cjs`), and the fact-force gate holds the
+first write to a file until its facts are read. This skill is the audited way past
+either hold. It mirrors `{{command_prefix}}unlock-decision`: a named approver plus a
+reason, recorded before anything is let through. Override is never silent.
+
+## Invocation
+
+| Command | Behavior |
+|---|---|
+| `{{command_prefix}}override <finding-id> --approver <who> --reason <text>` | Record a `D-XX` `override`-tagged decision in STATE.md `<decisions>` and let the risk-blocked action through. |
+| `{{command_prefix}}override factforce <path> --approver <who> --reason <text>` | Set `checked[path]` in the session fact-force state so the fact-force gate stops holding that path. |
+
+Both modes ask for a rationale: the audit trail is the reason override exists.
+
+## Steps
+
+1. **Parse args.** Mode is `factforce` when the first token is the literal `factforce`
+   (the next token is the `<path>`); otherwise the first token is a `<finding-id>`.
+   `--approver` is required (a non-empty name). Missing `--approver` prints the usage
+   and changes nothing. If `--reason` is absent, ASK for one (AskUserQuestion or a
+   prompt) before continuing: an override with no rationale is rejected.
+
+2. **Preview.** Show what will be written and stop for confirmation:
+   - finding mode: the decision entry from `overrideDecisionEntry(<id>, {approver, reason})`
+     (its `text`, `status: locked`, and `override` tag) plus the action it unblocks.
+   - factforce mode: the `<path>` that will gain `checked[path] = true` and the
+     session-state file it lands in.
+
+3. **Apply (finding mode).** Record the audited decision via the STATE writer
+   `mcp__gdd_state__add_decision` (it auto-assigns the next `D-N`). Pass the `text`
+   from the pure builder so the `override` tag is embedded and greppable:
+
+   ```bash
+   node -e '
+     const o = require("./scripts/lib/risk/override.cjs");
+     const [id, who, reason] = process.argv.slice(1);
+     const entry = o.overrideDecisionEntry(id, { approver: who, reason });
+     console.log(JSON.stringify(entry));
+   ' "<finding-id>" "<who>" "<reason>"
+   ```
+
+   Then call `mcp__gdd_state__add_decision` with `{ text: <entry.text>, status: "locked" }`.
+   The blocked action is now approved on the audit record; proceed with it.
+
+4. **Apply (factforce mode).** Set `checked[path]` in the session state file at
+   `<cwd>/.design/locks/factforce-<session_id>.json` (atomic tmp then rename), using
+   the pure helper so the shape matches what the fact-force gate reads:
+
+   ```bash
+   node -e '
+     const fs = require("fs"); const path = require("path");
+     const o = require("./scripts/lib/risk/override.cjs");
+     const [file, p] = process.argv.slice(1);
+     let state = {}; try { state = JSON.parse(fs.readFileSync(file, "utf8")); } catch {}
+     const next = o.setFactForceChecked(state, p);
+     fs.mkdirSync(path.dirname(file), { recursive: true });
+     const tmp = file + ".tmp";
+     fs.writeFileSync(tmp, JSON.stringify(next, null, 2) + "\n");
+     fs.renameSync(tmp, file);
+     console.log(JSON.stringify(next.checked));
+   ' "<cwd>/.design/locks/factforce-<session_id>.json" "<path>"
+   ```
+
+   The fact-force gate stops holding `<path>` for the rest of the session.
+
+5. **Report** the recorded approver, the reason, and either the new `D-XX` id (finding
+   mode) or the unblocked path (factforce mode).
+
+## Do Not
+
+- Do not skip the rationale: every override is audited.
+- Do not override a finding that the risk gate did not actually block.
+- Do not edit `scripts/lib/risk/route.cjs` or `compute-risk.cjs`: this skill consumes them.
+
+## OVERRIDE COMPLETE

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

@@ -0,0 +1,54 @@
+---
+name: gdd-paper-write
+description: "Push design decisions from `.design/DESIGN-CONTEXT.md` into the active paper.design canvas by dispatching the `design-paper-writer` agent in one of three modes (annotate / tokenize / roundtrip). Use when the user has completed a design pipeline cycle and wants the decisions reflected in their paper.design canvas. Operates proposal->confirm with `--dry-run`."
+argument-hint: "<annotate|tokenize|roundtrip> [--dry-run]"
+user-invocable: true
+tools: Read, Write, Bash, Grep, Glob
+---
+
+# gdd-paper-write
+
+Dispatches the `design-paper-writer` agent to write design decisions back to the active paper.design canvas. The shared probe pattern (ToolSearch → live call → STATE.md write) and connection handshake are documented at `../../reference/shared-preamble.md#connection-handshake-summary` and `../../connections/paper-design.md`.
+
+## Usage
+
+```
+/get-design-done paper-write <mode> [--dry-run]
+```
+
+Modes:
+- `annotate` - add design decision comments to canvas nodes
+- `tokenize` - sync CSS token values to paper.design node styles
+- `roundtrip` - write implementation status back as text/HTML layers
+
+Flags:
+- `--dry-run` - emit the proposal without executing any paper.design writes
+
+paper.design has no team-library concept, so there is no `--confirm-shared` flag. Every write still requires an explicit `yes` confirmation (unless `--dry-run` is set).
+
+## Prerequisites
+
+1. paper.design MCP registered. Install: `claude mcp add paper-design --transport http https://mcp.paper.design/sse` then restart the session. See `../../connections/paper-design.md` for the full probe pattern and budget rules.
+2. `.design/DESIGN-CONTEXT.md` exists (run `discover` first)
+3. `.design/STATE.md` `<connections>` shows `paper-design: available`. If `not_configured` or `unavailable`, the agent will STOP with a diagnostic.
+
+Budget: the agent tracks `budget_used` in STATE.md `<connections>` and warns when usage reaches 90/100 on the free tier.
+
+## Required Reading
+
+Read `.design/STATE.md` and `.design/DESIGN-CONTEXT.md` before dispatching the agent.
+
+## Dispatch
+
+```
+Task("design-paper-writer", """
+mode: <annotate|tokenize|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/pause/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: gdd-pause
+description: "Write a numbered checkpoint so work can resume in a new session without re-running completed stages."
+argument-hint: "[context note]"
+tools: Read, Write, Bash, AskUserQuestion, mcp__gdd_state__get, mcp__gdd_state__set_status, mcp__gdd_state__add_blocker, mcp__gdd_state__checkpoint
+disable-model-invocation: true
+---
+
+@reference/retrieval-contract.md
+@reference/cycle-handoff-preamble.md
+
+# {{command_prefix}}pause
+
+Captures enough state that a killed or stopped session can resume cleanly via `{{command_prefix}}resume` or `{{command_prefix}}continue`.
+
+Each invocation writes an **immutable numbered checkpoint** - it does not overwrite previous pauses. This enables branched cycles: you can pause, take a detour via `{{command_prefix}}sketch`, compare, and resume an older snapshot via `{{command_prefix}}resume N`.
+
+## Steps
+
+1. `mcp__gdd_state__get` → snapshot current pipeline state. Extract:
+   - Current `stage` and `cycle`
+   - `last_checkpoint` timestamp
+   - `task_progress` and `status` for the current run
+   - Open todos (from `.design/TODO.md` if present - this file is outside the MCP catalog, so `Read` is still used)
+   - Active sketch/spike directories (scan `.design/sketches/` and `.design/spikes/` for in-progress markers)
+
+2. **Determine checkpoint number**: run
+   ```bash
+   ls .design/checkpoints/ 2>/dev/null | grep -E '^[0-9]+' | sort -n | tail -1
+   ```
+   Next checkpoint = last number + 1 (or `01` if none exist).
+
+3. **Collect context**: if no context argument was passed, ask (AskUserQuestion):
+   "What are you in the middle of? (optional context to capture)"
+
+4. **Flip status via MCP** so `{{command_prefix}}resume` can detect the pause and recover the prior status:
+   1. `mcp__gdd_state__set_status` with `status: "paused:<prior-status>"` - the `paused:` prefix preserves the prior status for resume parsing.
+   2. If the user supplied a context/blocker message: `mcp__gdd_state__add_blocker` with `{ stage: <current>, date: <today>, text: <message> }`.
+   3. `mcp__gdd_state__checkpoint` to stamp `last_checkpoint` via MCP.
+
+5. **Write numbered checkpoint**: create `.design/checkpoints/` with `mkdir -p`, then write:
+   ```
+   .design/checkpoints/NN-<stage>-<ISO-date>.md
+   ```
+   e.g. `01-design-2026-04-24.md`
+
+   Content:
+   ```markdown
+   # Checkpoint NN
+   **Saved**: <ISO timestamp>
+   **Stage**: <stage>
+   **Cycle**: <cycle>
+   **In progress**: <task description + wave/index>
+   **Next**: <next step>
+   **Context**: <user note or "none">
+   **Active sketch**: <path or none>
+   **Open todos**: <N items (see .design/TODO.md)>
+   **Completed this session**: <list>
+   ```
+
+6. **Update HANDOFF.md pointer**: write `.design/HANDOFF.md` with:
+   ```markdown
+   # Session Handoff (pointer)
+   Latest checkpoint: `.design/checkpoints/NN-<stage>-<ISO-date>.md`
+   Run `{{command_prefix}}resume` to restore, or `{{command_prefix}}resume N` for a specific checkpoint.
+   ```
+
+7. Print: "Checkpoint NN saved. Run `{{command_prefix}}resume` or `{{command_prefix}}continue` to pick back up."
+
+## Do Not
+
+- Do not mutate STATE.md directly - all STATE.md writes go through the `gdd-state` MCP tools above. Checkpoint files + HANDOFF.md are sibling artifacts, written with `Write`.
+- Do not abort in-progress sketches; just record them.
+- Do not delete previous checkpoint files.
+- Do not call `mcp__gdd_state__transition_stage` - pause is status-only, never a stage transition.
+
+## PAUSE COMPLETE