Cycle

---
description: "[ADD v{{VERSION}}] Plan and execute a work cycle — select features, assess parallelism, define validation"
argument-hint: "[--plan | --status | --complete | --milestone] [milestone M{N}]"
allowed-tools: [Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion, Task, TodoWrite]
references: ["learning-reference.md", "swarm-protocol.md", "maturity-matrix.md", "skill-epilogue.md", "rules/telemetry.md", "rules/model-roles.md"]
---

# ADD Cycle Command v{{VERSION}}

Cycles are the operational unit of ADD work. They batch features, assess dependencies, plan parallelism, and define validation criteria before execution. This command manages the full cycle lifecycle: planning, status checks, and completion/retrospective.

---

## Overview: What is a Cycle?

A **cycle** is the next batch of work before a human checkpoint. It:
- Picks features from the current milestone's hill chart
- Maps dependencies (what must serialize vs. what can parallelize)
- Assigns agents and effort estimates
- Defines per-item and overall validation criteria
- Ranges from 1-7 days depending on maturity and scope

**Cycle outputs:**
- `.add/cycles/cycle-{N}.md` — the cycle plan (generated by `--plan`)
- Updated milestone hill chart (filled in by `--status` and `--complete`)
- `.add/learnings.md` checkpoint entries (filled in by `--complete`)

---

## Pre-Flight: Context & Setup

All cycle commands start by reading context:

1. **Read `.add/config.json`** to find current maturity level
   - This governs cycle scope, parallelism limits, and documentation depth
2. **Read active milestone** from `docs/milestones/`
   - Find the current milestone (look for `Status: IN_PROGRESS`, or the most recent)
   - Fail gracefully if no active milestone (prompt to create one first)
3. **Milestone health check** — after loading the active milestone, check its status:
   - **No active milestone** (`planning.current_milestone` is null or file doesn't exist): Display "No active milestone found." Offer: run `/add:milestone --list` to see available milestones, `/add:milestone --switch <id>` to activate one, or `/add:milestone --create` to create a new one. STOP cycle planning until a milestone is active.
   - **Active milestone is COMPLETE** (all success criteria checked): Display "Current milestone {name} is COMPLETE." Scan `docs/milestones/` for NOT_STARTED milestones. If found, suggest switching. If none, suggest creating one. STOP cycle planning until milestone is switched.
   - **All features at DONE/VERIFIED** but milestone not formally complete: Display "All features in {name} appear complete. Consider closing this milestone with `/add:cycle --complete` or switching to the next one."
4. **Check for existing active cycle** in `.add/cycles/`
   - If one exists and last activity was < 3 days ago, assume it's still active
   - Otherwise, offer to archive and start fresh
5. **Verify prerequisites** (e.g., if POC maturity, skip some docs)
6. **Check for session handoff** — per the Session-Handoff Preflight in `${CLAUDE_PLUGIN_ROOT}/references/skill-epilogue.md`

---

## Command: /add:cycle --plan (default)

Plan the next cycle. Interactive, human-driven, agent-assisted.

### Step 1: Present the Current Milestone

Read the active milestone file and display:
- **Milestone name & goal**
- **Hill chart** (current positions)
- **Features list** (name, current position, spec link)
- **Remaining appetite** (how much time/runway is left in the milestone)

Example output:
```
Active Milestone: M8 — Authentication & Session Stability
Goal: Stabilize authentication system and reduce session timeout bugs by 90%
Remaining Appetite: ~5 days (started with 2 weeks, 9 days used)

Hill Chart:
  Auth Overhaul       ████████████████████░░░░░░░░░░░░░░░░  downhill — testing & edge cases
  Session Refresh     ████████████░░░░░░░░░░░░░░░░░░░░░░░░░  peak — figured out approach, starting implementation
  Mobile Logout       ████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░  uphill — design in progress, dependencies unclear

Feature Details:
  • Auth Overhaul (specs/auth-redesign.md) — SPECCED → Target: IN_PROGRESS
  • Session Refresh (specs/session-refresh.md) — SHAPED → Target: SPECCED
  • Mobile Logout (specs/mobile-logout.md) — SHAPED → Target: SPECCED
```

### Step 2: Interactive Interviews

Ask the human 1-by-1 questions. Number of questions varies by maturity (see cascade matrix in `${CLAUDE_PLUGIN_ROOT}/references/maturity-matrix.md`):
- POC: ~5 questions (fast)
- Alpha: ~8 questions (clarify core unknowns)
- Beta: ~12 questions (deep understanding)
- GA: ~15 questions (exhaustive edge cases)

**Core questions (all maturities):**

1. **"Which features should we advance this cycle?"**
   - Display options with current position → target position (e.g., "SPECCED → IN_PROGRESS")
   - Multiple selections allowed (unless blocking dependencies prevent it)
   - Suggested default: advance 1-2 features per cycle for POC, up to 3-6 for Beta/GA

2. **"How long will you be available / away?"**
   - Days available for async agent updates? (if away: reduces autonomy, adds checkpoints)
   - Impacts cycle scope: less availability = fewer features, more serialization
   - Can adjust maturity "away mode autonomy" as a result

3. **"Any features that must be serialized (dependencies)?"**
   - Auto-detect from specs (check each feature's spec for "depends on" links)
   - But human can override: "Actually, Session Refresh needs Auth Overhaul to finish first"
   - Build dependency graph → serialization plan

**UI Gate (all maturities, UI features only):**

After selecting features, check each selected feature's spec for UI components:
- Look for a non-empty Q8 answer in the spec
- OR acceptance criteria that reference screens, views, components, or flows

For each UI feature, check whether a signed-off UX artifact exists at `specs/ux/{feature-slug}-ux.md` with `Status: APPROVED`.

**If a UI feature has no approved UX artifact:**

At POC maturity, prompt:
```
{Feature name} has UI components but no signed-off design.

Options:
  A) Run /add:ux specs/{feature-slug}.md now (recommended — prevents rework)
  B) Skip and proceed (accepted risk — UI will be defined during implementation)
```

At Alpha+ maturity, block and require:
```
⚠ {Feature name} has UI components but no signed-off design.

Run /add:ux specs/{feature-slug}.md before including this feature in the cycle.
This gate exists to prevent implementation rework from late-breaking design changes.

Once the UX artifact is approved, re-run /add:cycle --plan.
```

If all UI features have approved artifacts (or no features have UI), continue without interruption.

**Additional questions (Alpha+):**

4. **"What's blocking or at-risk?"** — tap the milestone's risk table; any mitigations to pursue this cycle?

5. **"Are there edge cases we should focus on?"** — especially for downhill features (near VERIFIED); do we need QA or performance testing?

**Additional questions (Beta+):**

6. **"Who's reviewing this cycle? Any availability constraints?"** — Beta requires code review; GA requires 2 reviewers

7. **"Should we do a pre-deploy sanity check?"** — Beta/GA requires pre-deploy QA

8. **"Do any features need performance testing?"** — common in Beta/GA for downhill features

9. **"What's the rollback plan if things go sideways?"** — GA especially needs this upfront; feature flags? database migration reversibility?

**Additional questions (GA):**

10. **"Is there a customer impact window we should avoid?"** — peak usage hours to avoid deployments?

11. **"Should we split this cycle into two smaller ones?"** — GA favors smaller, more frequent cycles (less risk)

12. **"Are there compliance or audit implications?"** — any regulatory review needed before merge?

13. **"What's our monitoring/alerting strategy?"** — how will we detect failures post-deploy?

14. **"Do we need a communication plan to customers?"** — feature deprecation? beta label? known issues?

### Step 3: Assess Parallelism

Based on answers, determine what can run in parallel:

1. **Build dependency graph:**
   - "Session Refresh needs Auth Overhaul to finish" → serialization edge
   - "Mobile Logout is independent" → can run parallel to the others
   - Visualize: `Auth Overhaul → Session Refresh`, `Mobile Logout (parallel)`

2. **Check maturity parallelism limits:**
   - POC: 1 serial agent (no parallelism)
   - Alpha: 1-2 agents (minimize coordination)
   - Beta: 2-4 agents (with file reservations)
   - GA: 3-5 agents (strict coordination, merge sequence)

3. **Recommend agent allocation:**
   - "Feature A (Auth Overhaul) → Agent 1"
   - "Feature B (Session Refresh) → Agent 1 (waits for Feature A) or Agent 2 if available?"
   - "Feature C (Mobile Logout) → Agent 2 or Agent 3 (independent)"

4. **Plan file reservations** (Beta/GA):
   - Which agent owns which files?
   - Example: `Agent 1: src/auth/*, src/session/*` + `Agent 2: src/mobile/logout/*`
   - Avoids merge conflicts, enables parallel work without constant rebasing

5. **Define merge sequence** (Beta/GA):
   - Which feature merges first?
   - Usually: infrastructure first, then dependent features
   - Example: `Auth Overhaul → Session Refresh → Mobile Logout`

### Step 4: Generate Cycle Plan

Create `.add/cycles/cycle-{N}.md` from `${CLAUDE_PLUGIN_ROOT}/templates/cycle-plan.md`, filling every section (work items, dependencies & serialization, parallel strategy, validation criteria, autonomy & checkpoints, notes) with the answers from Steps 1-3.

**Depth varies by maturity:**
- **POC:** Minimal (just work items + serial note)
- **Alpha:** Brief (work items, dependencies, validation)
- **Beta:** Full (all sections, parallel strategy, risks)
- **GA:** Exhaustive (all sections, merge sequence, monitoring plan, rollback strategy)

---

## Command: /add:cycle --status

Check the progress of the active cycle in real-time.

### Step 1: Read Active Cycle

Load `.add/cycles/cycle-{N}.md` (most recent or explicitly named).

### Step 2: Scan Feature Positions

For each work item in the cycle:
1. **Check the spec** (e.g., `specs/auth-redesign.md`)
   - How many acceptance criteria are marked done?
   - Any open TODOs or questions?
2. **Check test status**
   - Run test suite, capture pass/fail rate
   - Estimate % complete based on passing tests
3. **Check PR status** (if applicable)
   - Is code up for review? Approved? Merged?

### Step 3: Update Hill Chart

Move each feature's position on the milestone's hill chart:
- Still doing discovery? → still "uphill"
- Tests written, waiting on implementation? → "peak"
- Code mostly done, in review/QA? → "downhill"

Example:
```
Auth Overhaul       ████████████████████████░░░░░░░░░░  downhill — 4/5 tests passing, PR in review
Session Refresh     ████████████████░░░░░░░░░░░░░░░░░░░░  peak — spec finalized, starting TDD cycle
```

### Step 4: Report Status

Display:
- **What's done:** Features at/past target position
- **What's in progress:** Features making progress, ETA
- **What's blocked:** Features not advancing, reason
- **Overall cycle progress:** % of validation criteria met
- **Suggestion:** If all criteria met, suggest `/add:cycle --complete`

Example report:
```
Cycle 8 Status (as of 2026-02-07)

✅ Auth Overhaul: SPECCED → IN_PROGRESS (on track)
   • 4/5 acceptance criteria passed in tests
   • PR #142 in review (1 comment pending)
   • ETA: ready for merge tomorrow

🔄 Session Refresh: SHAPED → SPECCED (in progress)
   • Spec 80% written, mobile device edge case TBD
   • Waiting on dependency: Auth Overhaul merge
   • ETA: spec done by EOD Friday

✅ Mobile Logout: SHAPED → SPECCED (on track)
   • Spec complete and approved
   • Ready to start implementation cycle-9

---

Cycle Validation:
  • All features reached target position? 1/3 (Auth in progress, others specced)
  • All acceptance criteria met? 4/5 (Auth downhill, others still uphill)
  • Code review completed? Yes (Auth in progress)
  • Pre-deploy QA passed? Pending

Overall: 67% complete. On track to finish by cycle end.
Suggestion: Continue cycle, target completion by 2026-02-09.
```

---

## Command: /add:cycle --complete

Close the active cycle. Verify validation, update milestone, capture learnings.

### Step 1: Verify Cycle Validation Criteria

Check:
- [ ] All work items reached target position
- [ ] All per-item acceptance criteria verified
- [ ] Code review completed (if required by maturity)
- [ ] Pre-deploy QA passed (if required by maturity)
- [ ] No critical blockers or regressions

If any fails, **don't complete.** Report blockers and ask human to decide:
- Extend cycle to finish remaining work?
- Archive cycle as-is and start fresh cycle with leftover work?
- Downgrade some features (target positions)?

### Step 2: Update Milestone Hill Chart

Move all features to their new positions in `docs/milestones/M{X}-{name}.md`:
- Update hill chart percentages
- Update feature detail table (Position column)
- Mark cycle completion in cycle tracking table

Example:
```
| cycle-8 | Auth Overhaul (SPECCED→IN_PROGRESS), Session Refresh (SHAPED→SPECCED), Mobile Logout (SHAPED→SPECCED) | COMPLETE | All features on track. Auth ready for QA next cycle. |
```

### Step 3: Check Milestone Success Criteria

Now that cycle is done, did the milestone's success criteria improve?
- "All authentication specs passing in staging" → Is this now true?
- "Zero authentication-related bugs for 7 days" → How are we trending?

If milestone success criteria are now fully met, **suggest milestone closure.**

#### Maturity Promotion Check (evidence-based)

If milestone completion triggers a promotion suggestion, run an evidence scan before recommending it. Promotion requires evidence, not aspiration. The evidence items, scoring thresholds per transition, and promotion process are defined in `${CLAUDE_PLUGIN_ROOT}/references/maturity-matrix.md` — `/add:promote --check` is the canonical gap-analysis tool.

**If evidence supports promotion:**
```
Milestone M{N} complete. Evidence supports maturity promotion:
  Current: {ALPHA}
  Evidence score: {7}/10
  Recommendation: Promote to {BETA}

  Run /add:retro to formally promote (updates config, activates new rules).
```

**If evidence does NOT support promotion:** report the score, list the gaps for the target level, and suggest reassessing at the next `/add:retro`.

Do NOT auto-promote. Promotion is applied through `/add:retro` which updates config and records the change.

### Step 4: Archive Cycle & Checkpoint

Write a structured JSON learning entry to the appropriate learnings file. Follow the checkpoint process in `${CLAUDE_PLUGIN_ROOT}/references/learning-reference.md` (section: "How to Write a Checkpoint Entry"):

1. **Classify scope** — cycle retrospective insights are typically `project` scope (specific to this project's milestone), but process insights may be `workstation` or `universal`
2. **Write JSON entry** with:
   - `checkpoint_type`: `"retro"` (cycle completion is a mini-retro)
   - `category`: `"process"`
   - `title`: `"Cycle {N} complete: {summary}"`
   - `body`: Include cycle metrics (duration, features advanced, validation success, blockers), what worked, what was harder, and learnings for next cycle
3. **Regenerate** the markdown view

If the cycle produced multiple distinct learnings (e.g., a technical discovery AND a process insight), write separate entries with appropriate scope classification for each.

### Step 5: Present Next Options

After completing a cycle:

1. **If milestone is incomplete:** Offer to plan the next cycle (`/add:cycle --plan`)
2. **If milestone is complete:** Offer to close the milestone (`/add:milestone --close` or similar)
3. **If promotion is ready:** Highlight maturity promotion path

Example:
```
Cycle 8 complete! ✅

Milestone M8 progress:
  • Goal: Stabilize authentication & reduce session timeout bugs by 90%
  • Success Criteria: 5/5 met (all specs passing, 0 bugs for 7 days, mobile parity confirmed)
  • Status: READY TO CLOSE

Recommendation: Complete milestone M8, then run /add:retro to assess evidence-based promotion.

Options:
  /add:milestone --close M8
  /add:retro M8 (write retrospective, assess promotion)
  /add:cycle --plan M9 (plan next milestone's first cycle)
```

---

## Command: /add:cycle --milestone

Select a milestone before planning. Convenience shortcut that runs milestone selection inline, then continues to `--plan`.

### Step 1: List Available Milestones

Glob `docs/milestones/M*.md`. Display table with Status, Horizon, Features, Completion %, Target Maturity. Highlight current active milestone.

### Step 2: Ask for Selection

"Which milestone should we plan the next cycle for?"

Accept milestone ID (e.g., `M3-marketplace-ready` or `M3`). Validate it exists and is not COMPLETE.

### Step 3: Switch if Needed

If selection differs from `planning.current_milestone`:
- Run the same switch logic as `/add:milestone --switch` (safety checks, config update)
- Update `planning.current_milestone` and `planning.current_cycle` in config

### Step 4: Continue to --plan

Proceed with normal `/add:cycle --plan` flow using the newly active milestone.

---

## Swarm Coordination (Beta/GA Maturity)

When the cycle plan includes parallel work with 2+ agents, follow the full protocol in `${CLAUDE_PLUGIN_ROOT}/references/swarm-protocol.md` — worktree setup, file reservation maps, merge sequencing, and coordination rules all live there.

Cycle-specific notes:

- Every dispatch carries a MODEL tier and a BUDGET cap per the policy tables in
  `${CLAUDE_PLUGIN_ROOT}/references/swarm-protocol.md` (Resource Budgets +
  role → tier defaults, tiers per `rules/model-roles.md`). Mechanical work —
  frontmatter sweeps, generated-output regen, dashboard/SVG rendering — runs on
  the fast tier; reserve the architect tier for review and orchestration.
- The cycle plan's File Reservations and Merge Sequence sections (from the
  cycle-plan template) are the swarm's ownership map for this cycle. Each agent
  owns their reserved paths — no cross-agent edits without coordination.
- **WIP limits:** Beta allows 3-6 features per cycle (strict focus); GA adds
  explicit per-agent WIP limits (e.g., Agent-1: max 2 concurrent features). If
  the cycle plan exceeds limits, **split into smaller cycles.** Smaller is
  better for quality and coordination.

---

## Catch-Up Spike: Adoption Mode

When `/add:cycle` is called on a project newly adopting ADD, detect the gap and hand off to `/add:init`'s adoption mode rather than duplicating it here.

**Detection** — any of:
- No `.add/cycles/` directory exists
- No active milestone found
- Project maturity is "unspecified"

**Then offer:**
```
This project isn't yet structured for ADD cycles.
Run /add:init to bootstrap ADD adoption — it performs the gap analysis,
generates retroactive specs and a baseline catch-up milestone (M0), and
sets up quality gates and commit discipline.

Once /add:init completes, run /add:cycle --plan M0 to execute the
catch-up work in 1-2 intensive cycles, then resume normal cycles for M1+.
```

---

## Summary: Cycle Command Cheat Sheet

| Command | Purpose | Output |
|---------|---------|--------|
| `/add:cycle --plan` | Plan next cycle (interactive) | `.add/cycles/cycle-{N}.md` |
| `/add:cycle --status` | Check cycle progress | Report + updated hill chart |
| `/add:cycle --complete` | Close cycle + update milestone | Archived cycle + learnings checkpoint |
| `/add:cycle --milestone` | Select milestone before planning | Config update + cycle plan |
| `/add:cycle --plan M0` | Catch-up spike (new projects) | Catch-up milestone + cycle plan |

**Key principles:**
- **Maturity drives behavior.** POC cycles are fast & simple. GA cycles are detailed & checkpointed.
- **Cycles are the execution heartbeat.** Plan them with humans, execute with agents, verify together.
- **Parallelism is intentional.** Only when maturity + dependencies allow. File reservations prevent thrashing.
- **Learnings are captured.** Every cycle checkpoint feeds the next planning round.

End-of-skill epilogue: follow `${CLAUDE_PLUGIN_ROOT}/references/skill-epilogue.md` (observation + learning checkpoint + progress tracking).