ADD Cycle Command v0.5.0

ADD Cycle Command v0.5.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. 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
4. Verify prerequisites (e.g., if POC maturity, skip some docs)

---

Command: /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):

• 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

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 testing? Performance testing?

Additional questions (Beta+):

6. "Who's reviewing this cycle? Any availability constraints?"

   • Maturity Beta requires code review; GA requires 2 reviewers
   • Schedule reviewer participation

7. "Should we do a pre-deploy sanity check?"

   • Beta/GA requires pre-deploy QA
   • Coordinate with QA team if separate

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 with:

# Cycle {N} — {CYCLE_TITLE}

**Milestone:** M{X} — {Milestone Name}
**Maturity:** {poc|alpha|beta|ga}
**Status:** PLANNED
**Started:** TBD
**Completed:** TBD
**Duration Budget:** {e.g., "3 days", "1 week"}

## Work Items

| Feature | Current Pos | Target Pos | Assigned | Est. Effort | Validation |
|---------|-------------|-----------|----------|-------------|------------|
| {FEATURE_1} | SPECCED | IN_PROGRESS | Agent-1 | ~4 hours | All acceptance criteria passing in tests |
| {FEATURE_2} | SHAPED | SPECCED | Agent-2 | ~2 hours | Spec complete, 2 reviewers sign off |

## Dependencies & Serialization

{Visual and text description of what must run serially}

Example:

Auth Overhaul (Agent-1) ↓ (Session Refresh depends on Auth completion) Session Refresh (Agent-1)

Mobile Logout (Agent-2) — parallel to above

## Parallel Strategy

{If maturity is Beta/GA}

### File Reservations
- **Agent-1:** src/auth/*, src/session/* (owns auth + session infrastructure)
- **Agent-2:** src/mobile/logout/* (owns logout UI)

### Merge Sequence
1. Auth Overhaul (infrastructure)
2. Session Refresh (depends on Auth)
3. Mobile Logout (independent, but benefits from stable Auth)

{If maturity is POC/Alpha: "Single-threaded execution. Features advance sequentially."}

## Validation Criteria

### Per-Item Validation
- {FEATURE_1}: {Acceptance criteria 1, 2, 3} + all tests passing
- {FEATURE_2}: {Acceptance criteria} + spec approved by human

### Cycle Success Criteria
- [ ] All features reach target position
- [ ] All acceptance criteria verified
- [ ] Code review completed (Alpha+)
- [ ] Pre-deploy QA passed (Beta+)
- [ ] No regressions in regression suite

## Agent Autonomy & Checkpoints

{Based on maturity + availability}

POC: Full autonomy. Agent executes cycle and updates status daily.

Alpha: High autonomy. Agent plans, executes, flags blockers async. Human checks in every 2 days.

Beta: Balanced. Human approves cycle plan at start, agent executes, human verifies results and signs off.

GA: Guided with checkpoints. Human approval at cycle start. Agent provides daily standup. Human approval before merge. Human approval before deploy.

## Notes

{Any other context: blockers, risks specific to this cycle, design decisions to confirm, etc.}

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: /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: /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.

Scan the project for:

Evidence Item	How to Check
Feature specs	specs/*.md exist for user-facing features
Test coverage	Run coverage tool, report actual %
CI/CD pipeline	.github/workflows/ or equivalent exists and passing
PR workflow	Git log shows merge commits from pull requests
Environment separation	Config shows 2+ deploy targets
Conventional commits	Last 20 commits follow feat:/fix:/docs: pattern
TDD evidence	Test file timestamps precede or match implementation
Branch protection	Protected branches on main/master
Release tags	Semantic version tags in git
Quality gates	Pre-commit hooks or CI checks configured

Scoring:

• POC → Alpha: 3+ items present
• Alpha → Beta: 6+ items present (specs, 50%+ coverage, CI, PR workflow required)
• Beta → GA: 9+ items present (80%+ coverage, protected branches, release tags, 30+ days stability required)

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:

Milestone M{N} complete. Maturity stays at {ALPHA}.
  Evidence score: {4}/10
  Missing for {BETA}: {list gaps}

  Address gaps, then reassess at 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 rules/learning.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 (/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:
  /milestone --close M8
  /add:retro M8 (write retrospective, assess promotion)
  /add:cycle --plan M9 (plan next milestone's first cycle)

---

Swarm Coordination (Beta/GA Maturity)

When cycle plan includes parallel work with 2+ agents:

Git Worktree Setup

Recommend creating separate worktrees for each agent:

git worktree add ../branch-auth origin/main  # Agent-1
git worktree add ../branch-session origin/main  # Agent-1
git worktree add ../branch-logout origin/main  # Agent-2

Agents work in separate worktrees, avoiding constant git pull coordination.

File Reservation Map

Generate a file ownership map for the cycle:

Agent-1:
  - src/auth/**
  - src/session/**
  - tests/auth-*.ts
  - tests/session-*.ts

Agent-2:
  - src/mobile/logout/**
  - tests/mobile-logout-*.ts

Rule: Each agent owns their reserved paths. No cross-agent edits without coordination.

Merge Sequence & Coordination

Define which features merge in what order. Recommend a PR merge sequence to the human:

1. Auth Overhaul (PR #142) → merge first (infrastructure)
2. Session Refresh (PR #143) → merge second (depends on Auth)
3. Mobile Logout (PR #144) → merge third (independent, but benefits from stable Auth)

Steps:
- Agent-1 completes Auth Overhaul PR, waits for approval
- Once merged, Agent-1 rebases Session Refresh PR on top of Auth
- Agent-2 rebases Mobile Logout PR on latest main
- Human reviews all 3 PRs in sequence
- Merge sequence: Auth → Session → Mobile (respects dependencies)

WIP Limits

Beta/GA maturity enforces WIP (work-in-progress) limits to prevent thrashing:

• Beta: 3-6 features per cycle (strict focus)
• GA: 3-6 features with explicit WIP limits per agent (e.g., Agent-1: max 2 concurrent features)

If 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 (no existing structure):

Detection

Check:

• No .add/cycles/ directory exists? OR
• No active milestone found?
• Project maturity is "unspecified"?

Then offer catch-up mode:

This project isn't yet structured for ADD cycles.
Want to run a catch-up spike to bootstrap?

This will:
1. Generate retroactive specs for existing features
2. Create a baseline milestone from current state
3. Set up quality gates & commit discipline
4. Plan cycle-1 with catch-up items

Takes ~2-4 hours depending on project size.

Step 1: Gap Analysis

Compare current project state against target maturity requirements:

Current State Assessment:
  • PRD: ❌ Missing (only CLAUDE.md exists)
  • Specs: ❌ Missing for 6 existing features
  • Quality Gates: ⚠️ Pre-commit lint only, no CI
  • Commit Discipline: ⚠️ Freeform (no conventional commits)
  • Tests: ⚠️ 42% coverage (target: 80% for Beta)
  • Milestones: ❌ Missing
  • Cycles: ❌ Missing

Target Maturity: Alpha (based on user feedback + stability)
→ Gaps: PRD, specs (critical paths), quality gates (add CI), TDD (critical paths)

Step 2: Create Catch-Up Milestone

Generate a special milestone: M0 — ADD Adoption Catch-Up

Features in catch-up cycle:

1. PRD Generation: Interview + write docs/PRD.md (adopt from CLAUDE.md + new questions)
2. Spec Generation: Retroactive specs for critical-path features (auth, core flows)
3. Quality Gate Setup: Configure pre-commit lint, CI pipeline (GitHub Actions, etc.)
4. Commit Discipline: Enable conventional commits (git hooks)
5. Test Coverage: Raise from 42% to 60%+ for critical paths
6. Milestone Structure: Rename/organize existing features into logical milestones

Step 3: Plan Catch-Up Cycle-1

Run /add:cycle --plan M0 and execute the catch-up work in 1-2 intensive cycles.

Step 4: Resume Normal Cycles

Once catch-up cycle completes, the project is "ADD ready":

• PRD + specs exist
• Quality gates active
• Test coverage acceptable
• Milestone structure in place

Then resume normal /add:cycle --plan 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 --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.