add-cycle

name	add-cycle
description	[ADD v0.11.0] Plan and execute a work cycle — select features, assess parallelism, define validation
argument-hint	[--plan | --status | --complete | --milestone] [milestone M{N}]

ADD Cycle Command v0.11.0

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 ~/.codex/add/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 ~/.codex/add/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 ~/.codex/add/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 ~/.codex/add/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 ~/.codex/add/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 ~/.codex/add/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 ~/.codex/add/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 ~/.codex/add/references/skill-epilogue.md (observation + learning checkpoint + progress tracking).