/craft-cycle-complete

name: cycle-complete
description: "Complete a cycle. Triggers reflection if pending learnings, then archives."

Cycle Complete

Complete and archive a cycle. Ensures learnings are reflected before archiving.

When to Use

• All stories in the cycle are complete
• User explicitly ends cycle early
• Cycle has been abandoned and needs archival

Flow

Step 1: Verify Cycle State

Set `cycle_dir` to `.craft/cycles/${ACTIVE_CYCLE}`.

Use **Grep** with pattern `^status: complete`, path `$cycle_dir/stories/`, glob `*.md`, output_mode `files_with_matches` → count results → `stories_complete`.

Use **Glob** with pattern `$cycle_dir/stories/*.md` → count results → `stories_total`.

**If stories incomplete:** Use **AskUserQuestion**:

question: "[N] of [M] stories complete. End cycle anyway?"
header: "Cycle"
options:
  - label: "Complete cycle"
    description: "Archive incomplete stories to backlog"
  - label: "Continue working"
    description: "Finish remaining stories first"

---

Step 2: Check for Pending Learnings & Ungraduated Fixes

Use **Grep** with pattern `status: pending`, path `.craft/.learnings.yaml`, output_mode `count` → `pending_count`. If file doesn't exist, `pending_count = 0`.

Also count ungraduated fix records and the rule-pass threshold:

FIX_COUNT=$(bash "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/count-ungraduated-fixes.sh")
THRESHOLD=$(grep -m1 '^rule_pass_threshold:' "${CRAFT_PROJECT_ROOT:-.}/.craft/settings.yaml" 2>/dev/null | sed 's/^rule_pass_threshold:[[:space:]]*//')
THRESHOLD=${THRESHOLD:-10}

**If `pending_count > 0` OR `FIX_COUNT >= THRESHOLD`:**

Name the reason(s) that apply:

> "There are [N] pending learnings that haven't been converted to harness yet." > "[FIX_COUNT] fixes have accumulated since the last rule pass - reflect can mine them for graduation-worthy rules." > > "Reflect before archiving?"

Use **AskUserQuestion**:

question: "Reflect before archiving?"
header: "Reflect"
options:
  - label: "Yes, reflect now"
    description: "Run /craft:reflect (learnings drain and/or rule pass), then archive"
  - label: "Skip reflection"
    description: "Keep everything pending, just archive cycle"

**If "Yes, reflect now":** Run `/craft:reflect`, then continue to Step 3. Reflect owns the rule-pass offer - this step only routes into it, never presents the pass itself.

**If "Skip reflection":** Learnings remain in `.craft/.learnings.yaml` with `status: pending` and the fix watermark is untouched — both will be available for the next reflection.

---

Step 2b: Walkthrough Check (UI Cycles)

Check if the cycle has UI stories that should be walked through before archiving.

Use **Grep** with pattern `^type: ui`, path `$cycle_dir/stories/`, glob `*.md`, output_mode `files_with_matches` → count → `ui_stories`.

**If ui_stories > 0:**

> "This cycle has [N] UI stories. Running a walkthrough to check the live experience before archiving."

**Assemble the walkthrough brief** from what the orchestrator already knows:

1. **Dev server**: Read `project.md` for `package_manager` and dev scripts. Build the start command (e.g., `npm run dev`). Check common ports (5173, 3000, 8080) or parse from project config. 2. **URL**: Infer from project type. Static HTML → `file://` path or localhost. Next.js → `localhost:3000`. Vite → `localhost:5173`. Check project.md for hints. 3. **Test plan**: For each `type: ui` story, read the story file and extract:

• Feature name (from title)
• How to trigger it (from acceptance criteria or spark - e.g., "click Command 1 button")
• What should happen (from acceptance criteria - e.g., "recipe card appears with image and ingredients")

4. **Story context**: Include each UI story's spark (1-2 sentences) so the agent understands what was built.

**Pass the brief to the walkthrough-analyzer agent via Task:**

Brief:
  Dev server: [command to start, e.g., "npm run dev"]
  URL: [e.g., "http://localhost:5173"]

  Test plan:
    1. [Feature name]
       Trigger: [how to activate it]
       Expected: [what should happen]
    2. [Feature name]
       Trigger: [how to activate it]
       Expected: [what should happen]
    ...

  Story context:
    - [Story 1 title]: [spark]
    - [Story 2 title]: [spark]

**After the walkthrough agent returns:**

Write findings to `.craft/analysis/pending/walkthrough.yaml` using the template format.

**If blocks-ship findings > 0:**

Use **AskUserQuestion**:

question: "Walkthrough found [N] blocks-ship issues. Review before completing?"
header: "Walkthrough"
options:
  - label: "Review findings now"
    description: "See what was found before archiving"
  - label: "Complete anyway"
    description: "Archive the cycle, fix issues later"
  - label: "Fix first"
    description: "Don't complete yet - fix the issues"

If "Review findings now" → Show findings inline (severity-ranked), then re-ask complete/fix. If "Complete anyway" → Continue to Step 3. If "Fix first" → Run the **Walkthrough Fix Loop** below.

**If no blocks-ship findings but looks-wrong or feels-off findings exist:**

> "Walkthrough found [N] minor findings (no blockers). Continuing to archive. > Findings saved to `.craft/analysis/pending/walkthrough.yaml` for review."

Proceed to Step 3.

**If no findings at all:**

> "Walkthrough clean. Continuing to archive."

Proceed to Step 3.

---

Walkthrough Fix Loop

**CRITICAL: Do NOT create a new cycle.** The current cycle stays active. Fix stories go into the SAME cycle directory (`$cycle_dir/stories/`). The cycle is not complete until it passes the walkthrough clean. This is part of cycle completion, not a new piece of work.

Walkthrough findings come in two complexity levels. Handle each differently:

**Step F1: Apply quick fixes (complexity: quick-fix)**

Quick fixes are trivial edits - CSS properties, missing attributes, wrong values. The walkthrough agent provides a `fix_hint` for each one.

For each `quick-fix` finding (any severit