npx claudepluginhub mountainunicorn/add --plugin addThis skill is limited to using the following tools:
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.
Manages Hypo-Workflow cycles: creates new cycles with milestone sequences restarting at M0, tracks state/progress/reports/archives/summaries via /hw:cycle new/list/view/close commands.
Orchestrates full development sprint cycles from planning to PR creation using git workflows, sub-skills, and automated orchestration. Use for advancing projects via structured cycles.
Manages project milestones: create new cycles with phases, complete/archive versions, preview changes, audit integration, analyze gaps. For structured delivery checkpoints.
Share bugs, ideas, or general feedback.
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.
A cycle is the next batch of work before a human checkpoint. It:
Cycle outputs:
.add/cycles/cycle-{N}.md — the cycle plan (generated by --plan)--status and --complete).add/learnings.md checkpoint entries (filled in by --complete)All cycle commands start by reading context:
.add/config.json to find current maturity level
docs/milestones/
Status: IN_PROGRESS, or the most recent).add/cycles/
Plan the next cycle. Interactive, human-driven, agent-assisted.
Read the active milestone file and display:
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
Ask the human 1-by-1 questions. Number of questions varies by maturity (see cascade matrix):
Core questions (all maturities):
"Which features should we advance this cycle?"
"How long will you be available / away?"
"Any features that must be serialized (dependencies)?"
Additional questions (Alpha+):
"What's blocking or at-risk?"
"Are there edge cases we should focus on?"
Additional questions (Beta+):
"Who's reviewing this cycle? Any availability constraints?"
"Should we do a pre-deploy sanity check?"
"Do any features need performance testing?"
"What's the rollback plan if things go sideways?"
Additional questions (GA):
"Is there a customer impact window we should avoid?"
"Should we split this cycle into two smaller ones?"
"Are there compliance or audit implications?"
"What's our monitoring/alerting strategy?"
"Do we need a communication plan to customers?"
Based on answers, determine what can run in parallel:
Build dependency graph:
Auth Overhaul → Session Refresh, Mobile Logout (parallel)Check maturity parallelism limits:
Recommend agent allocation:
Plan file reservations (Beta/GA):
Agent 1: src/auth/*, src/session/* + Agent 2: src/mobile/logout/*Define merge sequence (Beta/GA):
Auth Overhaul → Session Refresh → Mobile LogoutCreate .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:
Check the progress of the active cycle in real-time.
Load .add/cycles/cycle-{N}.md (most recent or explicitly named).
For each work item in the cycle:
specs/auth-redesign.md)
Move each feature's position on the milestone's hill chart:
Example:
Auth Overhaul ████████████████████████░░░░░░░░░░ downhill — 4/5 tests passing, PR in review
Session Refresh ████████████████░░░░░░░░░░░░░░░░░░░░ peak — spec finalized, starting TDD cycle
Display:
/add:cycle --completeExample 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.
Close the active cycle. Verify validation, update milestone, capture learnings.
Check:
If any fails, don't complete. Report blockers and ask human to decide:
Move all features to their new positions in docs/milestones/M{X}-{name}.md:
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. |
Now that cycle is done, did the milestone's success criteria improve?
If milestone success criteria are now fully met, suggest milestone closure.
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:
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.
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"):
project scope (specific to this project's milestone), but process insights may be workstation or universalcheckpoint_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 cycleIf the cycle produced multiple distinct learnings (e.g., a technical discovery AND a process insight), write separate entries with appropriate scope classification for each.
After completing a cycle:
/add:cycle --plan)/milestone --close or similar)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)
When cycle plan includes parallel work with 2+ agents:
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.
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.
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)
Beta/GA maturity enforces WIP (work-in-progress) limits to prevent thrashing:
If cycle plan exceeds limits, split into smaller cycles. Smaller is better for quality and coordination.
When /add:cycle is called on a project newly adopting ADD (no existing structure):
Check:
.add/cycles/ directory exists? ORThen 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.
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)
Generate a special milestone: M0 — ADD Adoption Catch-Up
Features in catch-up cycle:
docs/PRD.md (adopt from CLAUDE.md + new questions)Run /add:cycle --plan M0 and execute the catch-up work in 1-2 intensive cycles.
Once catch-up cycle completes, the project is "ADD ready":
Then resume normal /add:cycle --plan for M1+.
| 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: