@hegemonart/get-design-done 1.19.0 → 1.19.5

package/skills/complete-cycle/SKILL.md

@@ -22,8 +22,46 @@ Closes the current cycle: marks CYCLES.md entry complete, archives pipeline arti
    - `DESIGN-AUDIT.md`
    - `DESIGN-SUMMARY.md`
    Mark originals with a `<!-- archived to .design/archive/cycle-N/ -->` note at top (do not delete — next cycle will overwrite).
-5. **Clear STATE.md**: Set `cycle:` to empty string, reset `<decisions>` to a fresh empty section, reset `stage:` to `brief`.
-6. Print: "Cycle <N> archived. Run `/gdd:new-cycle` to start the next cycle."
+5. **Generate EXPERIENCE.md** (Haiku-tier writer step): Read cycle STATE decisions + `.design/DESIGN-VERIFICATION.md` (if present) + any `.design/reflections/*.md` from this cycle. Write `.design/archive/cycle-N/EXPERIENCE.md` using this structure (~100–200 lines, declarative-fact framing, prepend `reference/cycle-handoff-preamble.md` content):
+
+   ```markdown
+   <!-- archived cycle experience — reference, not current requests -->
+   # Cycle N — Experience
+
+   **Goal**: <one-line goal from STATE.md or CYCLES.md>
+   **Opened**: <start date>
+   **Ended**: <today>
+
+   ## Decisions Made
+
+   <list all D-XX decisions from STATE.md <decisions> block — one per line>
+
+   ## Learnings Graduated
+
+   <list all L-NN learnings surfaced or promoted this cycle>
+
+   ## What Died
+
+   <designs, approaches, or tasks that were started but abandoned — and why>
+
+   ## Surprises
+
+   <what was unexpected during this cycle>
+
+   ## Handoff to Next Cycle
+
+   <what the next cycle should know: active sketches, deferred tasks, unresolved questions>
+   ```
+
+   This file becomes the highest-priority source for the decision-injector hook in future sessions.
+
+6. **Trigger reindex**: if `.design/search.db` exists, rebuild the search index:
+   ```bash
+   node -e "require('./scripts/lib/design-search.cjs').reindex(process.cwd())" 2>/dev/null || true
+   ```
+
+7. **Clear STATE.md**: Set `cycle:` to empty string, reset `<decisions>` to a fresh empty section, reset `stage:` to `brief`.
+8. Print: "Cycle <N> archived. Run `/gdd:new-cycle` to start the next cycle."
 
 ## Do Not
 

package/skills/continue/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: gdd-continue
+description: "Alias for /gdd:resume — restore session context from the most recent checkpoint."
+argument-hint: "[<checkpoint-N>]"
+tools: Read, Write, Bash, Glob
+---
+
+@reference/retrieval-contract.md
+
+# /gdd:continue
+
+Alias for `/gdd:resume`. Delegates immediately to the resume skill with the same argument.
+
+This alias exists for discoverability — users familiar with `git continue` or similar conventions find `/gdd:continue` more intuitive than `/gdd:resume` after a pause.
+
+## Steps
+
+1. Forward the argument (if any) to the `/gdd:resume` skill logic.
+2. Execute all `/gdd:resume` steps exactly as documented in `skills/resume/SKILL.md`.
+
+The two commands are functionally identical. `/gdd:resume` is the canonical form; `/gdd:continue` is the convenience alias.
+
+## CONTINUE COMPLETE

package/skills/pause/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: gdd-pause
-description: "Write session handoff so work can resume in a new session without re-running completed stages."
+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, AskUserQuestion
+tools: Read, Write, Bash, AskUserQuestion
 ---
 
 @reference/retrieval-contract.md
@@ -10,35 +10,61 @@ tools: Read, Write, AskUserQuestion
 
 # /gdd:pause
 
-Captures enough state that a killed or stopped session can resume cleanly via `/gdd:resume`.
+Captures enough state that a killed or stopped session can resume cleanly via `/gdd:resume` or `/gdd: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 `/gdd:sketch`, compare, and resume an older snapshot via `/gdd:resume N`.
 
 ## Steps
 
-1. Read `.design/STATE.md`. Extract:
-   - Current `stage:` and `cycle:`
+1. **Read `.design/STATE.md`**. Extract:
+   - `stage:` and `cycle:`
    - Last activity timestamp
    - Completed tasks in the current pipeline run
-   - Open todos (from `.design/TODO.md` if present)
+   - Open todos (scan `.design/TODO.md` if present)
    - Active sketch/spike directories (scan `.design/sketches/` and `.design/spikes/` for in-progress markers)
-2. If no context argument was passed, ask (AskUserQuestion): "What are you in the middle of? (optional context to capture)"
-3. Write `.design/HANDOFF.md`:
+
+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. **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
-   # Session Handoff
-   **Paused**: <ISO timestamp>
+   # Checkpoint NN
+   **Saved**: <ISO timestamp>
    **Stage**: <stage>
-   **Cycle**: <cycle-N>
+   **Cycle**: <cycle>
    **In progress**: <task description + wave/index>
    **Next**: <next step>
-   **Context**: <user note>
+   **Context**: <user note or "none">
    **Active sketch**: <path or none>
    **Open todos**: <N items (see .design/TODO.md)>
    **Completed this session**: <list>
    ```
-4. Print: "Session paused. Run `/gdd:resume` to pick back up."
+
+5. **Update HANDOFF.md pointer**: write `.design/HANDOFF.md` with:
+   ```markdown
+   # Session Handoff (pointer)
+   Latest checkpoint: `.design/checkpoints/NN-<stage>-<ISO-date>.md`
+   Run `/gdd:resume` to restore, or `/gdd:resume N` for a specific checkpoint.
+   ```
+
+6. Print: "Checkpoint NN saved. Run `/gdd:resume` or `/gdd:continue` to pick back up."
 
 ## Do Not
 
-- Do not modify STATE.md itself — HANDOFF.md is the only write.
+- Do not modify STATE.md — checkpoints are the only write.
 - Do not abort in-progress sketches; just record them.
+- Do not delete previous checkpoint files.
 
 ## PAUSE COMPLETE

package/skills/recall/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: gdd-recall
+description: "Search cross-cycle memory: decisions, learnings, experience archives. Returns ranked matches."
+argument-hint: "<query> [--reindex]"
+tools: Read, Write, Bash
+---
+
+@reference/retrieval-contract.md
+
+# /gdd:recall
+
+Searches `.design/archive/`, `.design/learnings/LEARNINGS.md`, `.design/CYCLES.md`, and `STATE.md` decision blocks for the given query and returns ranked matches. Uses FTS5 when `better-sqlite3` is available, ripgrep next, Node fs scan as universal fallback.
+
+## Steps
+
+1. **Parse argument**: extract `<query>` and optional `--reindex` flag.
+   - If no query and no `--reindex`: print usage and exit.
+   - If `--reindex` only: rebuild the index (see step 3), then exit.
+
+2. **Check backend**: run
+   ```bash
+   node -e "const {backendName}=require('./scripts/lib/design-search.cjs');console.log(backendName())"
+   ```
+   Print a one-line notice: `Search backend: fts5 | ripgrep | node-grep`.
+
+3. **Reindex if requested**: run
+   ```bash
+   node -e "require('./scripts/lib/design-search.cjs').reindex(process.cwd())"
+   ```
+   Print: "Index rebuilt."
+
+4. **Search**: run
+   ```bash
+   node -e "
+   const s=require('./scripts/lib/design-search.cjs');
+   const r=s.search(process.argv[1], process.cwd(), {limit:20});
+   console.log(JSON.stringify(r));
+   " -- "<query>"
+   ```
+   Parse the JSON array of `{file, line, text}` objects.
+
+5. **Format results**: print in this shape:
+   ```
+   ## Recall: "<query>"  (N matches, backend: fts5)
+
+   ### 1. .design/archive/cycle-2/EXPERIENCE.md:42
+   > Decided to skip dark-mode token layer in cycle 2 — cost–benefit did not clear threshold
+
+   ### 2. .design/learnings/LEARNINGS.md:18
+   > L-03 · color · cited:4 · Color contrast failures cluster around interactive states, not surfaces
+   ```
+   Group by file. Truncate text at 120 chars. Cap at 20 results.
+
+6. **Signal relevance**: for every result whose text contains an `L-NN` learning ID, record a `surfaced` signal:
+   ```bash
+   node -e "
+   const rc=require('./scripts/lib/relevance-counter.cjs');
+   rc.record('L-NN','surfaced','.design');
+   "
+   ```
+
+7. **Empty result**: if no matches, print:
+   ```
+   No matches for "<query>" in cross-cycle memory.
+   Tip: run /gdd:recall --reindex if the archive has been updated since last index build.
+   ```
+
+## Do Not
+
+- Do not modify any source file.
+- Do not run git commands.
+- Do not write `.design/STATE.md`.
+
+## RECALL COMPLETE

package/skills/resume/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: gdd-resume
-description: "Restore session context from .design/HANDOFF.md and route to where work left off."
-argument-hint: ""
-tools: Read, Write, Bash, Glob
+description: "Restore session context from a numbered checkpoint. Lists available checkpoints when no argument given."
+argument-hint: "[<N>]"
+tools: Read, Write, Bash, Glob, AskUserQuestion
 ---
 
 @reference/retrieval-contract.md
@@ -10,31 +10,49 @@ tools: Read, Write, Bash, Glob
 
 # /gdd:resume
 
-Inverse of `/gdd:pause`. Reads the handoff file, prints a clear "you were here" summary, and routes to the next command.
+Inverse of `/gdd:pause`. Reads a checkpoint file, prints a clear "you were here" summary, and routes to the next command.
 
 ## Steps
 
-1. Try to read `.design/HANDOFF.md`. If missing, read `.design/STATE.md` and infer position from the `stage:` and `cycle:` fields.
-2. Print a summary in this exact shape:
+1. **Parse argument**:
+   - If argument is a number N → restore checkpoint N.
+   - If no argument → list available checkpoints and ask which to restore (see step 2).
+
+2. **List mode** (no argument):
+   ```bash
+   ls .design/checkpoints/ 2>/dev/null | sort -n
+   ```
+   If empty, fall back to reading `.design/HANDOFF.md` (legacy single-slot format).
+   If checkpoints exist, present the list and ask (AskUserQuestion):
+   "Which checkpoint would you like to restore? (enter number, or press Enter for the latest)"
+   Use the answer (or latest if Enter pressed) as N.
+
+3. **Read checkpoint**: load `.design/checkpoints/NN-*.md`. If not found, try `.design/HANDOFF.md` as legacy fallback.
+
+4. **Print summary** in this exact shape:
    ```
-   Last paused: <timestamp>
+   Checkpoint NN restored.
+   Saved: <timestamp>
    You were: <in-progress description>
    Next step: <next>
    Active sketch: <path or none>
    Open todos: <N>
    ```
-3. **Staleness check** — compare mtime of `.design/` artifacts vs `src/` (via Glob + Bash `stat` when available). If `src/` has commits/changes newer than the last pipeline artifact, warn: "Source has changed since last pipeline run — consider re-running explore or verify."
-4. **Route recommendation** based on stage:
-   - `brief` → "Run `@get-design-done brief`"
-   - `explore` → "Run `@get-design-done explore`"
-   - `plan` → "Run `@get-design-done plan`"
-   - `design` → "Run `@get-design-done design` to continue"
-   - `verify` → "Run `@get-design-done verify`"
-5. Do not auto-execute the next command — just recommend.
+
+5. **Staleness check**: compare mtime of `.design/` artifacts vs `src/` via Bash `stat` when available. If `src/` has commits newer than the checkpoint timestamp, warn:
+   "Source has changed since checkpoint NN — consider re-running explore or verify."
+
+6. **Route recommendation** based on checkpoint `Stage:` field:
+   - `brief` → "Run `/gdd:brief`"
+   - `explore` → "Run `/gdd:explore`"
+   - `plan` → "Run `/gdd:plan`"
+   - `design` → "Run `/gdd:design` to continue"
+   - `verify` → "Run `/gdd:verify`"
 
 ## Do Not
 
-- Do not delete HANDOFF.md (leave it; next `/gdd:pause` overwrites it).
+- Do not delete checkpoint files.
 - Do not modify STATE.md.
+- Do not auto-execute the next command — just recommend.
 
 ## RESUME COMPLETE

package/skills/timeline/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: gdd-timeline
+description: "Narrative retrospective across cycles: reads EXPERIENCE.md files and git log to produce a timeline view."
+argument-hint: "[<cycle-N> | <from>-<to> | all]"
+tools: Read, Bash, Glob
+---
+
+@reference/retrieval-contract.md
+@reference/cycle-handoff-preamble.md
+
+# /gdd:timeline
+
+Generates a narrative retrospective across one or more completed cycles by reading `.design/archive/cycle-N/EXPERIENCE.md` files and correlating with `git log`.
+
+## Steps
+
+1. **Parse argument**: accepted forms:
+   - `cycle-N` or `N` — single cycle
+   - `N-M` — inclusive range
+   - `all` or no argument — all archived cycles
+
+2. **Discover archives**: glob `.design/archive/cycle-*/EXPERIENCE.md`. Sort by cycle number. Filter to requested range.
+
+3. **For each cycle archive**:
+   a. Read `EXPERIENCE.md` — extract sections: Goal, Decisions made, Learnings graduated, What died, Handoff to next cycle.
+   b. Read `DESIGN-SUMMARY.md` (if present) for shipped artifacts list.
+   c. Run:
+      ```bash
+      git log --oneline --after="<cycle start date>" --before="<cycle end date>" -- .design/ 2>/dev/null | head -10
+      ```
+      to correlate with commits. Use dates from `EXPERIENCE.md` Opened/Ended headers if present.
+
+4. **Print timeline** in this shape:
+
+   ```
+   ## Timeline: Cycle 1 → Cycle 3
+
+   ---
+
+   ### Cycle 1 — <goal headline>
+
+   **Opened with**: <first meaningful action>
+   **Key decisions**: <D-XX summary>, <D-XX summary>
+   **Surprises**: <what was unexpected>
+   **What we'd do differently**: <retrospective note>
+   **Shipped**: <artifact list or "see DESIGN-SUMMARY.md">
+
+   ---
+
+   ### Cycle 2 — <goal headline>
+   ...
+   ```
+
+5. **No archives found**: print
+   ```
+   No archived cycles found in .design/archive/.
+   Complete a cycle first with /gdd:complete-cycle.
+   ```
+
+## Do Not
+
+- Do not modify any file.
+- Do not run git commands that write or stage (only `git log` for read).
+
+## TIMELINE COMPLETE