gdd-complete-cycle

name	gdd-complete-cycle
description	Cycle closeout command that marks CYCLES.md entry complete, archives pipeline artifacts to .design/archive/cycle-N/, generates EXPERIENCE.md, rebuilds the search index, and resets STATE.md. Use when a design cycle has shipped and you're ready to start the next one.
argument-hint	[<retrospective note>]
tools	Read, Write, Bash, AskUserQuestion

{{command_prefix}}complete-cycle

Closes the current cycle: marks CYCLES.md entry complete, archives pipeline artifacts, and clears STATE.md for the next cycle.

Steps

1. Load state: Read .design/STATE.md for the active cycle: ID. If empty/missing, error: "No active cycle - nothing to complete."

2. Retrospective: If no argument was passed, ask (AskUserQuestion): "Is cycle complete? Briefly describe what was achieved." Capture for CYCLES.md.

3. Update CYCLES.md: Find the current cycle entry, change **Status**: active to **Status**: complete, append a **Retrospective**: <note> line and **Ended**: <date>.

4. Archive artifacts: Create .design/archive/cycle-N/ via Bash mkdir -p. Copy these files into it (if present):

   • DESIGN.md
   • DESIGN-PLAN.md
   • DESIGN-CONTEXT.md
   • DESIGN-VERIFICATION.md
   • 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. 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):

   <!-- 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  >
   
   
   
   
   

6. Trigger reindex: if .design/search.db exists, rebuild the search index:

   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 archived. Run {{command_prefix}}new-cycle to start the next cycle."

Do Not

• Do not delete source files in src/ - only archive .design/ artifacts.
• Do not auto-start a new cycle - user invokes {{command_prefix}}new-cycle explicitly.

Step 6 - Update notice (post-closeout surface)

After the archive has been written and STATE.md has been cleared for the next cycle, emit the plugin-update banner if one is present:

[ -f .design/update-available.md ] && cat .design/update-available.md

Written by hooks/update-check.sh; suppressed mid-pipeline and when the latest release is dismissed.

COMPLETE-CYCLE COMPLETE