Agile Workflow

Agile Workflow Orchestrator

A skill that guides agents through structured agile development workflows by intelligently invoking commands in sequence. Uses checkpoint-based flow control to auto-progress between steps while pausing at key decision points.

Note: This is a platform-agnostic, git-only workflow. For PR-based workflows with specific platforms, use:

• gitea-workflow for Gitea repositories
• github-agile for GitHub repositories

When to Use This Skill

Use this skill when:

• Starting work for the day ("run morning standup", "start my day")
• Working on a task ("implement next task", "continue working")
• Completing a development cycle ("finish this task", "prepare PR")
• Running sprint ceremonies ("start sprint", "end sprint", "retrospective")
• Resuming interrupted work ("what's next", "where was I")

Do NOT use this skill when:

• Running a single specific command (use that command directly)
• Just checking status (use /status directly)
• Only doing code review without full cycle (use /review-code directly)
• Researching or planning without implementation

Prerequisites

Before using this skill:

• Git repository initialized with worktree support
• Context network with backlog structure at context-network/backlog/
• Task status files at context-network/backlog/by-status/*.md

Workflow Types Overview

WORKFLOW TYPES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

TASK CYCLE (Primary)     DAILY                SPRINT
──────────────────────   ──────────────────   ──────────────────
sync                     Morning:             Start:
  ↓                        sync --last 1d       sync --all
next → [CHECKPOINT]        status --brief       groom --all
  ↓                        groom --ready        plan sprint-goals
implement                                       status
  ↓                      Evening:
[CHECKPOINT]               checklist          End:
  ↓                        discovery            sync --sprint
review-code                sync --last 1d       retrospective
review-tests                                    audit --sprint
  ↓                                             maintenance --deep
[CHECKPOINT]
  ↓
apply-recommendations (if issues)
  ↓
merge-prep → [CHECKPOINT]
  ↓
merge-complete
  ↓
update-backlog & status
  ↓
END
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

State Detection

The skill determines current workflow state automatically. No manual tracking needed.

Detection Signals

State Matrix

STATE DETECTION LOGIC
─────────────────────────────────────────────────────────────
Check                           → State           → Next Step
─────────────────────────────────────────────────────────────
No worktree, no in-progress     → IDLE            → sync, next
Worktree exists, uncommitted    → IMPLEMENTING    → continue implement
Worktree exists, all committed  → READY_REVIEW    → review-code
Reviews complete, ready to merge→ MERGE_READY     → merge-prep
Branch merged, worktree exists  → CLEANUP         → merge-complete
─────────────────────────────────────────────────────────────

For detailed detection algorithms, see references/state-detection.md.

Invocation Patterns

# Auto-detect state and continue from where you are
/agile-workflow

# Start specific workflow phase
/agile-workflow --phase task-cycle
/agile-workflow --phase daily-morning
/agile-workflow --phase daily-evening
/agile-workflow --phase sprint-start
/agile-workflow --phase sprint-end

# Resume work on specific task
/agile-workflow --task TASK-123

# Preview what would happen without executing
/agile-workflow --dry-run

Task Cycle Phase

The primary workflow for completing a single task from selection to merge.

Step 1: Sync Reality

Ensure context network matches actual project state.

Run: sync --last 1d --dry-run
Purpose: Detect drift between documented and actual state
Output: Sync report showing completions, partial work, divergences

Step 2: Select Task

Identify the next task to work on.

Run: next
Purpose: Find highest priority ready task
Output: Task ID, title, branch name suggestion

CHECKPOINT: TASK_SELECTED

• Pause to confirm task selection
• User can accept or choose different task
• On accept: continue to implementation

Step 3: Implement

Test-driven development in isolated worktree.

Run: implement [TASK-ID]
Purpose: Create worktree, write tests first, implement, verify
Output: Working implementation with passing tests

CHECKPOINT: IMPL_COMPLETE

• Pause after implementation completes
• Show test results and coverage
• On success: continue to review

Step 4: Review

Quality validation of implementation.

Run: review-code --uncommitted
Run: review-tests --uncommitted
Purpose: Identify quality issues, security concerns, test gaps
Output: Review reports with issues and recommendations

CHECKPOINT: REVIEWS_DONE

• Display combined review results
• If critical issues: must address before continuing
• If no issues: auto-continue to PR prep
• User decides: apply recommendations now or defer

Step 5: Apply Recommendations (Conditional)

Address review findings intelligently.

Run: apply-recommendations [review-output]
Purpose: Apply quick fixes now, defer complex changes to tasks
Output: Applied fixes + created follow-up tasks

Step 6: Prepare Merge

Validate and prepare for merge to main.

Run: merge-prep
Purpose: Validate implementation, run final checks, prepare for merge
Output: Ready to merge to main

CHECKPOINT: MERGE_READY

• Display validation results
• Show files that will be merged
• On all checks pass: continue to merge
• On failure: stop, address issues

Step 7: Complete Merge

Merge to main and cleanup.

Run: merge-complete
Purpose: Merge to main, delete branch, remove worktree, update status
Output: Task marked complete, cleanup done

Step 8: Update Backlog and Project Status

Persist progress to source-of-truth documentation.

Run: Part of merge-complete (Phase 6)
Purpose: Update epic file (task → complete), unblock dependents, update project status
Output: Backlog and project status reflect actual progress

Why this step matters: Without it, completed tasks remain marked "ready" in backlog files and project status stays stale. Internal tracking files are session-scoped; the backlog and status files are the persistent source of truth.

For detailed task-cycle instructions, see references/phases/task-cycle.md.

Daily Phase

Quick sequences for start and end of workday.

Morning Standup (~5 min)

Run sequence:
1. sync --last 1d --dry-run   # What actually happened yesterday
2. status --brief --sprint    # Current sprint health
3. groom --ready-only         # What's ready to work on

Output: Clear picture of today's priorities

Evening Wrap-up (~10 min)

Run sequence:
1. checklist                  # Ensure nothing lost
2. discovery                  # Capture learnings
3. sync --last 1d            # Update task statuses

Output: Knowledge preserved, state synchronized

For detailed daily instructions, see references/phases/daily.md.

Sprint Phase

Ceremonies for sprint boundaries.

Sprint Start (~60 min)

Run sequence:
1. sync --all                 # Full reality alignment
2. groom --all               # Comprehensive grooming
3. plan sprint-goals         # Architecture and goals
4. status --detailed         # Baseline metrics

Output: Sprint plan with groomed, ready backlog

Sprint End (~90 min)

Run sequence:
1. sync --sprint             # Final sprint sync
2. retrospective             # Capture learnings
3. audit --scope sprint      # Quality review
4. status --metrics          # Sprint metrics
5. maintenance --deep        # Context network cleanup

Output: Sprint closed, learnings captured, ready for next

For detailed sprint instructions, see references/phases/sprint.md.

Checkpoint Handling

Checkpoints are pauses for human decision-making.

Checkpoint Behavior

At each checkpoint: 1. Summarize what just completed 2. Show key results and any issues 3. Present next steps 4. Wait for user input

Checkpoint Responses

Auto-Continue Conditions

Some checkpoints can auto-continue when conditions are met:

For detailed checkpoint handling, see references/checkpoint-handling.md.

Command Reference

Each workflow step uses embedded command instructions:

Example: Complete Task Cycle

Scenario: Start of day, implement next available task

Invocation:

/agile-workflow --phase task-cycle

Flow:

Agent: Detecting current state...
       No worktree found, checking ready tasks...

Agent: Running sync --last 1d --dry-run
       [Sync output: 0 tasks completed but undocumented]

Agent: Running next
       Found: TASK-042 - Add user preferences endpoint
       Priority: High | Size: Small | Branch: task/TASK-042-preferences

       ╔═══════════════════════════════════════════╗
       ║  CHECKPOINT: Task Selection               ║
       ╠═══════════════════════════════════════════╣
       ║  Selected: TASK-042                       ║
       ║  Proceed with implementation?             ║
       ║                                           ║
       ║  [continue] [stop] [other task]           ║
       ╚═══════════════════════════════════════════╝

User: continue

Agent: Creating worktree at .worktrees/TASK-042/
       Running implement TASK-042
       [Implementation proceeds with TDD...]

       Tests: 12 passing
       Coverage: 87%
       Build: Success

       ╔═══════════════════════════════════════════╗
       ║  CHECKPOINT: Implementation Complete      ║
       ╠═══════════════════════════════════════════╣
       ║  All tests passing, ready for review      ║
       ║  Proceed to code review?                  ║
       ║                                           ║
       ║  [continue] [stop]                        ║
       ╚═══════════════════════════════════════════╝

[Flow continues through review, merge...]

Limitations

• Requires context network with specific backlog structure
• Git-only workflow (no PR integration - for PR workflows use gitea-workflow or github-agile)
• Single-task focus (parallel task work not orchestrated)
• Best suited for solo development or trusted team direct-to-main workflows

Related Skills

• gitea-workflow - For Gitea repositories with PR integration
• github-agile - For GitHub repositories with PR integration
• skill-maker - Create new skills following agentskills.io spec
• research-workflow - For research tasks before implementation

State Transition Matrix

Quick reference for workflow state transitions (git-only version).

State Definitions

Transition Triggers

IDLE ─────────────────────────────────────────────────────────────────────────
  │
  │ [next: task selected]
  ▼
IMPLEMENTING ─────────────────────────────────────────────────────────────────
  │
  │ [implement: complete with passing tests]
  ▼
READY_FOR_REVIEW ─────────────────────────────────────────────────────────────
  │
  │ [review-code, review-tests: complete]
  ▼
IN_REVIEW ────────────────────────────────────────────────────────────────────
  │
  ├──[issues found] ──► IMPLEMENTING (loop back)
  │
  │ [no issues OR issues fixed]
  ▼
MERGE_READY ──────────────────────────────────────────────────────────────────
  │
  │ [merge-prep: validation passed]
  │ [merge-complete: merge to main]
  ▼
CLEANUP ──────────────────────────────────────────────────────────────────────
  │
  │ [merge-complete: cleanup done]
  ▼
COMPLETED ────────────────────────────────────────────────────────────────────
  │
  │ [next task cycle]
  ▼
IDLE

Detection Signals by State

Valid Transitions Only

Transitions that should NOT happen:

• IDLE → anything except IMPLEMENTING
• IMPLEMENTING → MERGE_READY (must go through review)
• IN_REVIEW → COMPLETED (must merge first)
• Any state → COMPLETED without going through CLEANUP

Recovery from Invalid States

If state detection finds inconsistent signals:

1. Worktree exists but task marked complete

• Branch was merged outside workflow
• Action: Clean up worktree

2. No worktree but task marked in-progress

• Worktree was deleted manually
• Action: Recreate worktree or reset task status

3. Branch merged but worktree still exists

• merge-complete wasn't run
• Action: Run merge-complete to cleanup

4. Branch exists without worktree

• Work started on different machine
• Action: Create worktree from branch

Checkpoint Mapping

Workflow Diagrams

Visual representations of agile-workflow phases.

Complete Workflow Overview

                         AGILE WORKFLOW OVERVIEW
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

                    ┌────────────────────────────────────┐
                    │           SPRINT CYCLE             │
                    │                                    │
    ┌───────────────┴───────────────┐                    │
    │        SPRINT START           │                    │
    │  sync → groom → plan → status │                    │
    └───────────────┬───────────────┘                    │
                    │                                    │
                    ▼                                    │
    ┌───────────────────────────────────────────────┐   │
    │              DAILY CYCLE                      │   │
    │                                               │   │
    │   ┌────────────────────────────────────┐     │   │
    │   │        MORNING STANDUP             │     │   │
    │   │  sync → status → groom             │     │   │
    │   └────────────────┬───────────────────┘     │   │
    │                    │                          │   │
    │                    ▼                          │   │
    │   ┌────────────────────────────────────┐     │   │
    │   │         TASK CYCLES                │     │   │
    │   │                                    │     │   │
    │   │  ┌──────────────────────────────┐ │     │   │
    │   │  │ sync → next → implement →    │ │     │   │
    │   │  │ review → apply → merge-prep →│ │     │   │
    │   │  │ merge-complete               │ │     │   │
    │   │  └──────────────────────────────┘ │     │   │
    │   │       (repeat as needed)          │     │   │
    │   └────────────────┬──────────────────┘     │   │
    │                    │                          │   │
    │                    ▼                          │   │
    │   ┌────────────────────────────────────┐     │   │
    │   │        EVENING WRAP-UP             │     │   │
    │   │  checklist → discovery → sync      │     │   │
    │   └────────────────────────────────────┘     │   │
    │                                               │   │
    └───────────────────────────────────────────────┘   │
                    │                                    │
                    ▼ (repeat daily)                     │
                    │                                    │
    ┌───────────────┴───────────────┐                    │
    │         SPRINT END            │                    │
    │  sync → retro → audit →       │                    │
    │  status → maintenance         │                    │
    └───────────────────────────────┘                    │
                    │                                    │
                    └────────────────────────────────────┘

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Task Cycle Detail

                           TASK CYCLE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

                         ┌─────────┐
                         │  START  │
                         └────┬────┘
                              │
                              ▼
                    ┌─────────────────┐
                    │      sync       │ Reality check
                    └────────┬────────┘
                              │
                              ▼
                    ┌─────────────────┐
                    │      next       │ Select task
                    └────────┬────────┘
                              │
                              ▼
               ╔══════════════════════════╗
               ║  CHECKPOINT              ║
               ║  Task Selection          ║
               ╚════════════╤═════════════╝
                            │
                            ▼
                    ┌─────────────────┐
                    │   implement     │ TDD in worktree
                    └────────┬────────┘
                              │
                              ▼
               ╔══════════════════════════╗
               ║  CHECKPOINT              ║
               ║  Implementation Done     ║
               ╚════════════╤═════════════╝
                            │
              ┌─────────────┴─────────────┐
              ▼                           ▼
    ┌─────────────────┐         ┌─────────────────┐
    │  review-code    │         │  review-tests   │
    └────────┬────────┘         └────────┬────────┘
              └─────────────┬─────────────┘
                            │
                            ▼
               ╔══════════════════════════╗
               ║  CHECKPOINT              ║
               ║  Reviews Complete        ║
               ╚════════════╤═════════════╝
                            │
                   ┌────────┴────────┐
                   │  Has issues?    │
                   └────────┬────────┘
                      Yes   │   No
                       ▼    │    │
        ┌────────────────┐  │    │
        │ apply-recomm.  │  │    │
        └───────┬────────┘  │    │
                └─────┬─────┘    │
                      │◄─────────┘
                      ▼
                    ┌─────────────────┐
                    │   merge-prep    │ Validate
                    └────────┬────────┘
                              │
                              ▼
               ╔══════════════════════════╗
               ║  CHECKPOINT              ║
               ║  Merge Ready             ║
               ╚════════════╤═════════════╝
                            │
                            ▼
                    ┌─────────────────┐
                    │ merge-complete  │ Merge + cleanup
                    └────────┬────────┘
                              │
                              ▼
                         ┌─────────┐
                         │   END   │
                         └─────────┘

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Daily Sequences

                     DAILY SEQUENCES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

    MORNING (~5 min)              EVENING (~10 min)
    ────────────────              ─────────────────

    ┌─────────────┐               ┌─────────────┐
    │ sync        │               │ checklist   │
    │ --last 1d   │               │             │
    │ --dry-run   │               │             │
    └──────┬──────┘               └──────┬──────┘
           │                             │
           ▼                             ▼
    ┌─────────────┐               ┌─────────────┐
    │ status      │               │ discovery   │
    │ --brief     │               │             │
    │ --sprint    │               │             │
    └──────┬──────┘               └──────┬──────┘
           │                             │
           ▼                             ▼
    ┌─────────────┐               ┌─────────────┐
    │ groom       │               │ sync        │
    │ --ready     │               │ --last 1d   │
    │ -only       │               │             │
    └──────┬──────┘               └──────┬──────┘
           │                             │
           ▼                             ▼
    "Ready to work"               "Day complete"

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Sprint Sequences

                     SPRINT SEQUENCES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

    SPRINT START (~60 min)        SPRINT END (~90 min)
    ──────────────────────        ────────────────────

    ┌─────────────┐               ┌─────────────┐
    │ sync --all  │               │ sync        │
    │             │               │ --sprint    │
    └──────┬──────┘               └──────┬──────┘
           │                             │
           ▼                             ▼
    ┌─────────────┐               ┌─────────────┐
    │ groom --all │               │retrospective│
    │             │               │             │
    └──────┬──────┘               └──────┬──────┘
           │                             │
           ▼                             ▼
    ┌─────────────┐               ┌─────────────┐
    │ plan        │               │ audit       │
    │ sprint-goals│               │ --scope     │
    │             │               │ sprint      │
    └──────┬──────┘               └──────┬──────┘
           │                             │
           ▼                             ▼
    ┌─────────────┐               ┌─────────────┐
    │ status      │               │ status      │
    │ --detailed  │               │ --metrics   │
    │             │               │ --detailed  │
    └──────┬──────┘               └──────┬──────┘
           │                             │
           ▼                             ▼
    "Sprint ready"                ┌─────────────┐
                                  │ maintenance │
                                  │ --deep      │
                                  └──────┬──────┘
                                         │
                                         ▼
                                  "Sprint closed"

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

State Flow Diagram

                        STATE TRANSITIONS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

    ┌──────────┐
    │   IDLE   │◄──────────────────────────────────────┐
    └────┬─────┘                                       │
         │ [next]                                      │
         ▼                                             │
    ┌──────────────┐                                   │
    │ IMPLEMENTING │◄──────────────────────┐           │
    └──────┬───────┘                       │           │
           │ [complete]                    │           │
           ▼                               │           │
    ┌──────────────────┐                   │           │
    │ READY_FOR_REVIEW │                   │           │
    └──────┬───────────┘                   │           │
           │ [review]                      │           │
           ▼                               │           │
    ┌──────────────┐                       │           │
    │  IN_REVIEW   │───[issues]────────────┘           │
    └──────┬───────┘                                   │
           │ [clean]                                   │
           ▼                                           │
    ┌──────────────┐                                   │
    │ MERGE_READY  │                                   │
    └──────┬───────┘                                   │
           │ [merge-prep]                              │
           │ [merge-complete]                          │
           ▼                                           │
    ┌──────────────┐                                   │
    │   CLEANUP    │                                   │
    └──────┬───────┘                                   │
           │ [complete]                                │
           ▼                                           │
    ┌──────────────┐                                   │
    │  COMPLETED   │                                   │
    └──────┬───────┘                                   │
           │                                           │
           └───────────────────────────────────────────┘

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Checkpoint Handling Reference

Pause/resume behavior at workflow checkpoints.

Overview

Checkpoints are moments in the workflow where human review and decision-making is valuable. The skill pauses at these points, presents information, and waits for user direction.

Checkpoint Types

Decision Checkpoints

Require explicit user choice between options.

Examples:

• TASK_SELECTED: Confirm or change task
• REVIEWS_DONE: Fix issues now or defer

Validation Checkpoints

Verify a condition before proceeding.

Examples:

• IMPL_COMPLETE: All tests passing?
• MERGE_READY: All validations passing?

Information Checkpoints

Present status for awareness.

Examples:

• Post-sync summary
• Review results display

Checkpoint Definitions

TASK_SELECTED

Triggers after: next command

Display:

╔═══════════════════════════════════════════════════════╗
║  CHECKPOINT: Task Selection                           ║
╠═══════════════════════════════════════════════════════╣
║  Selected: [TASK-ID] - [Task Title]                   ║
║  Priority: [Level]                                    ║
║  Size: [Estimate]                                     ║
║  Branch: [suggested-branch]                           ║
║                                                       ║
║  Proceed with implementation?                         ║
╚═══════════════════════════════════════════════════════╝

User Options:

• continue / yes → Proceed to implement
• other / different → Return to task selection
• stop / pause → Exit workflow

Auto-Continue: Never (always requires confirmation)

---

IMPL_COMPLETE

Triggers after: implement command completes

Display:

╔═══════════════════════════════════════════════════════╗
║  CHECKPOINT: Implementation Complete                  ║
╠═══════════════════════════════════════════════════════╣
║  Tests: [X] passing, [Y] failing                      ║
║  Coverage: [Z]%                                       ║
║  Build: [PASS/FAIL]                                   ║
║  Lint: [PASS/FAIL]                                    ║
║                                                       ║
║  Ready for code review?                               ║
╚═══════════════════════════════════════════════════════╝

User Options:

• continue → Proceed to reviews
• back → Continue implementing
• stop → Exit workflow (save state)

Auto-Continue Condition:

• All tests passing AND
• Build succeeds AND
• Lint passes

If all conditions met, can auto-continue with brief countdown.

---

REVIEWS_DONE

Triggers after: review-code and review-tests complete

Display:

╔═══════════════════════════════════════════════════════╗
║  CHECKPOINT: Reviews Complete                         ║
╠═══════════════════════════════════════════════════════╣
║  Code Review:                                         ║
║    Critical: [A] | High: [B] | Medium: [C] | Low: [D] ║
║  Test Review:                                         ║
║    Critical: [E] | High: [F] | Medium: [G] | Low: [H] ║
║                                                       ║
║  [If issues exist:]                                   ║
║  Top Issue: "[issue description]"                     ║
║                                                       ║
║  How to proceed?                                      ║
╚═══════════════════════════════════════════════════════╝

User Options:

• fix all → Apply all recommendations
• fix critical → Fix critical/high only, defer rest
• defer all → Create tasks, proceed to PR
• stop → Exit workflow

Auto-Continue Condition:

• No critical issues AND
• No high issues
• (Auto-continue to PR prep)

Blocking Condition:

• Critical issues present → MUST fix before PR

---

MERGE_READY

Triggers after: merge-prep command

Display:

╔═══════════════════════════════════════════════════════╗
║  CHECKPOINT: Ready to Merge                           ║
╠═══════════════════════════════════════════════════════╣
║  Task: [TASK-ID] - [title]                            ║
║  Branch: task/[TASK-ID]-description                   ║
║                                                       ║
║  Validation:                                          ║
║  - Tests: PASSED                                      ║
║  - Lint: PASSED                                       ║
║  - Build: PASSED                                      ║
║                                                       ║
║  Ready to merge to main?                              ║
╚═══════════════════════════════════════════════════════╝

User Options:

• merge → Proceed to merge
• stop → Exit (branch remains)

Auto-Continue Condition:

• All validation checks passed

Blocking Conditions:

• Tests failed → Must fix
• Build failed → Must fix

---

MERGED

Triggers after: merge-complete merge step

Display:

╔═══════════════════════════════════════════════════════╗
║  CHECKPOINT: Merged                                   ║
╠═══════════════════════════════════════════════════════╣
║  Task: [TASK-ID] - [Title]                            ║
║  Commit: [commit-hash]                                ║
║                                                       ║
║  Cleanup:                                             ║
║  - [x] Merged to main                                 ║
║  - [x] Branch deleted                                 ║
║  - [x] Worktree removed                               ║
║  - [x] Task marked complete                           ║
║                                                       ║
║  Task cycle complete!                                 ║
╚═══════════════════════════════════════════════════════╝

User Options:

• next → Start another task cycle
• done → Exit workflow

Auto-Continue: Never (natural end of cycle)

---

Checkpoint Behavior Protocol

Standard Flow

1. COMMAND COMPLETES
        │
        ▼
2. GATHER CHECKPOINT DATA
   - Collect relevant metrics
   - Determine status
   - Check auto-continue conditions
        │
        ▼
3. DISPLAY CHECKPOINT
   - Show formatted checkpoint box
   - Present options
        │
        ▼
4. WAIT FOR INPUT
   - Parse user response
   - Map to action
        │
        ▼
5. EXECUTE ACTION
   - Continue to next step
   - Loop back to previous
   - Exit with state preserved

Auto-Continue Logic

if autoConditionsMet AND userPrefersAutoFlow:
    display "Auto-continuing in 5 seconds..."
    display "[Press any key to pause]"

    wait 5 seconds with interrupt check

    if no interrupt:
        proceed to next step
    else:
        show full checkpoint options

Interrupt Handling

At any checkpoint, user can:

• Type response to take action
• Type stop to exit
• Press Ctrl+C to abort

State is preserved on any exit.

---

Checkpoint Configuration

User Preferences

Users may configure checkpoint behavior:

# .agile-workflow/config.yaml
checkpoints:
  auto_continue: true          # Enable auto-continue when safe
  auto_continue_delay: 5       # Seconds before auto-continue
  verbose: false               # Show detailed checkpoint info
  require_confirmation:
    - TASK_SELECTED            # Always confirm these
    - MERGE_READY

Per-Invocation Override

# Disable auto-continue for this run
/agile-workflow --no-auto

# Maximum verbosity
/agile-workflow --verbose

# Skip non-critical checkpoints
/agile-workflow --fast

---

State Preservation

When workflow is interrupted at a checkpoint:

1. Current State Saved

• Detected workflow state
• Task context
• Last completed step
• Pending action

2. Resume Information

• How to continue: /agile-workflow (auto-detects)
• What will happen: [next step description]

3. No Work Lost

• All git commits preserved
• All files in worktree preserved
• PR remains open if created
• Context network updated

---

Error at Checkpoint

When an error occurs:

╔═══════════════════════════════════════════════════════╗
║  ERROR: [Error Type]                                  ║
╠═══════════════════════════════════════════════════════╣
║  [Error description]                                  ║
║                                                       ║
║  Suggested Resolution:                                ║
║  1. [Step to fix]                                     ║
║  2. [Step to fix]                                     ║
║                                                       ║
║  After fixing, run: /agile-workflow                   ║
║  (State will be detected automatically)               ║
╚═══════════════════════════════════════════════════════╝

Errors don't lose state - workflow can resume after fixing the issue.

Apply Recommendations Command Reference

Triage and apply recommendations from reviews.

Purpose

Analyze recommendations from code/test reviews and intelligently split them into immediate actions (apply now) and deferred tasks (create follow-up).

When Used in Workflow

• Task Cycle: After reviews, when issues were found
• Conditionally invoked based on review results

Common Invocation Patterns

apply-recommendations [review-output]
apply-recommendations --quick-only    # Only low-risk fixes
apply-recommendations --defer-all     # Convert all to tasks
apply-recommendations --dry-run       # Preview without applying

Core Principle: Smart Triage

Not all recommendations are equal. Some should be fixed immediately, others need planning. The decision matrix:

APPLY NOW if ALL of:

• Effort: Trivial or Small
• Risk: Low or (Medium with good test coverage)
• Dependencies: Independent or Local
• Clear fix is obvious
• Won't break existing functionality

DEFER TO TASK if ANY of:

• Effort: Large
• Risk: High
• Dependencies: System or Team
• Requires design decisions
• Needs performance benchmarking
• Could introduce breaking changes

Assessment Criteria

Effort Required

• Trivial: < 5 minutes, single line changes
• Small: 5-30 minutes, single file
• Medium: 30-60 minutes, 2-3 files
• Large: > 60 minutes, multiple files/systems

Risk Level

• Low: Style, documentation, isolated cleanup
• Medium: Logic changes, refactoring with tests
• High: Architecture, external APIs, data handling

Dependencies

• Independent: Can be done in isolation
• Local: Requires understanding of immediate context
• System: Requires broader architectural knowledge
• Team: Needs discussion or approval

Category Handling

Critical Security Issues → ALWAYS APPLY NOW

• Hardcoded secrets/credentials
• SQL injection vulnerabilities
• XSS vulnerabilities
• Exposed sensitive data

High Priority Bugs → USUALLY APPLY NOW

• Null reference errors
• Unhandled promise rejections
• Memory leaks (if isolated)
• Clear logic errors

Code Quality → SELECTIVE

Apply Now:

• Dead code removal
• Obvious duplications (< 10 lines)
• Simple variable renames
• Missing error handling (simple cases)

Defer:

• Large-scale refactoring
• Architecture changes
• Complex abstraction creation

Test Improvements → USUALLY APPLY NOW

• Adding missing assertions
• Fixing tautological tests
• Improving test names
• Fixing test isolation

Documentation → APPLY NOW

• Adding missing comments
• Updating incorrect docs
• Clarifying confusing names

Output Format

# Recommendation Application Report

## Summary
- Total recommendations: X
- Applied immediately: Y
- Deferred to tasks: Z

## Applied Immediately

### 1. [Recommendation Title]
**Type**: [Security/Bug/Quality/Test/Documentation]
**Files Modified**:
- `path/to/file.ts` - [What changed]
**Risk**: Low

## Deferred to Tasks

### High Priority

#### Task: [Clear Task Title]
**Original Recommendation**: [What was recommended]
**Why Deferred**: [Reason]
**Effort Estimate**: [Size]
**Created at**: `/tasks/[type]/[filename].md`

## Validation
- [ ] All tests pass
- [ ] Linting passes
- [ ] No regressions detected

## Next Steps
1. Review applied changes
2. Run full test suite
3. Review high-priority deferred tasks

Quality Guidelines

1. Never break working code - If unsure, defer 2. Maintain test coverage - Add tests for bug fixes 3. Preserve behavior - Refactoring shouldn't change functionality 4. Document decisions - Explain why items were deferred 5. Incremental progress - Many small improvements > one risky change

Orchestration Notes

After applying recommendations:

• If all applied successfully: ready for PR prep
• If issues remain: loop back to review
• Deferred tasks are created but don't block workflow

Discovery Command Reference

Capture learning moments and insights in the context network.

Purpose

Document insights as they happen, preventing knowledge loss and building institutional memory. Create discovery records, update location indexes, and maintain learning paths.

When Used in Workflow

• Daily Evening: Capture learnings from the day
• Post-Task: After completing implementation
• Ad-hoc: Any "aha moment" during development

When to Create Discovery Records

Invoke when:

• Spent >5 minutes figuring out how something works
• Read >3 files to understand one feature
• Had an "aha!" moment about system design
• Discovered why something was implemented a certain way
• Found the actual location of important functionality
• Mental model of a component changed

Discovery Documentation Process

Phase 1: Trigger Assessment

Identify discovery type:

Complexity Triggers:

• Multi-file understanding sequences
• Non-obvious component interactions
• Surprising implementation approaches

Navigation Triggers:

• Finding key entry points
• Understanding component organization
• Discovering configuration patterns

Understanding Triggers:

• Mental model evolution
• Assumption corrections
• Pattern recognition

Phase 2: Record Creation

Create record at /discoveries/records/YYYY-MM-DD-###.md:

# Discovery: [Brief Title]

**Date**: YYYY-MM-DD
**Context**: [What task/exploration led to this]

## What I Was Looking For
[1-2 sentences about the original goal]

## What I Found
**Location**: `path/to/file:lines`
**Summary**: [One sentence explaining what this does/means]

## Significance
[Why this matters for understanding the system]

## Connections
- Related concepts: [[concept-1]], [[concept-2]]
- Implements: [[pattern-name]]
- See also: [[related-discovery]]

## Keywords
[Terms someone might search for]

Phase 3: Location Index Updates

When discovering key code locations: 1. Check existing indexes in /discoveries/locations/ 2. Add new locations with file paths and line numbers 3. Explain significance 4. Include navigation patterns

Phase 4: Learning Path Updates

When understanding evolves significantly: 1. What did you think before? 2. What do you understand now? 3. What changed your understanding?

Update or create learning path to show progression.

Quality Guidelines

For Discovery Records

• Be Specific: Include exact file paths and line numbers
• Include Context: Explain what led to exploration
• Use Keywords: Think about search terms
• Connect to Existing: Link to related concepts

For Location Indexes

• Keep Current: Update paths when code moves
• Explain Significance: Not just locations, but why they matter
• Include Navigation Hints: Help others explore

Integration with Development

During Development Tasks

• Create records for "figuring out" moments
• Update location indexes for new key areas
• Note architecture understanding evolution

During Debugging

• Document root cause discoveries
• Record surprising behavior explanations
• Note workarounds and rationale

During Code Review

• Create records for reusable patterns
• Document insights from others' approaches
• Record "I didn't know you could do that" moments

Maintenance Schedule

• Daily: Review and link related discoveries
• Weekly: Update learning paths, organize records
• Monthly: Consolidate into primary documentation

Orchestration Notes

Discovery is typically an end-of-workflow activity:

• Run after task completion to capture learnings
• Run during daily wrap-up
• Creates valuable context for future work

Groom Command Reference

Transform context network's task list into actionable backlog.

Purpose

Refine tasks from "planned" status to "ready" status by ensuring they have clear acceptance criteria, proper scoping, and all dependencies resolved.

When Used in Workflow

• Sprint Start: Comprehensive grooming of all tasks
• Daily Morning: Check what's ready for today
• Task Selection: Before /next to ensure tasks are properly prepared

Common Invocation Patterns

groom                     # Groom all tasks
groom --ready-only       # Only show tasks that are ready
groom --blocked          # Focus on identifying/unblocking blocked tasks
groom --stale 7          # Re-groom tasks older than 7 days
groom --generate-sprint  # Create sprint plan from groomed tasks

Grooming Process

Phase 1: Task Inventory

Scan task sources:

• /planning/sprint-*.md
• /planning/backlog.md
• /tasks/**/*.md
• /decisions/**/*.md (for follow-up actions)
• Files with "TODO:", "NEXT:", "PLANNED:" markers

Phase 2: Task Classification

Classify each task as:

• A: Claimed Complete - Marked done but needs follow-up
• B: Ready to Execute - Clear criteria, no blockers
• C: Needs Grooming - Vague requirements or missing context
• D: Blocked - Waiting on dependencies or decisions
• E: Obsolete - No longer relevant or duplicate

Phase 3: Reality Check

For each task, assess:

• Still needed? (Check against current project state)
• Prerequisites met? (Identify missing dependencies)
• Implementation clear? (Flag ambiguities)
• Success criteria defined? (Note what's missing)
• Complexity estimate: Trivial/Small/Medium/Large/Unknown

Phase 4: Task Enhancement

Transform vague tasks into actionable items with:

• Specific, measurable title
• Clear context and rationale
• Input/output specifications
• Acceptance criteria checklist
• Implementation notes
• Identified dependencies
• Effort estimate

Phase 5: Priority Scoring

Score tasks based on:

• User value (High/Medium/Low)
• Technical risk (High/Medium/Low)
• Effort (Trivial/Small/Medium/Large)
• Dependencies (None/Few/Many)

Output Format

# Groomed Task Backlog

## Ready for Implementation

### 1. [Specific Task Title]
**One-liner**: [What this achieves]
**Effort**: [Estimate]
**Files to modify**: [Key files]

<details>
<summary>Full Details</summary>

**Context**: [Why needed]
**Acceptance Criteria**:
- [ ] [Specific criterion]
- [ ] [Another criterion]

**Implementation Guide**:
1. [First step]
2. [Second step]

**Watch Out For**: [Pitfalls]
</details>

## Ready Soon (Blocked)

### [Task Title]
**Blocker**: [What's blocking]
**Prep work possible**: [What can be done now]

## Needs Decisions

### [Task Title]
**Decision needed**: [Specific question]
**Options**: [List with pros/cons]

## Summary Statistics
- Ready for work: Y
- Blocked: Z
- Archived: N

Red Flags to Identify

• Task has been "almost ready" for multiple sprints
• No one can explain what "done" looks like
• "Just refactor X" - usually hides complexity
• Task title contains "and" - should be split
• "Investigate/Research X" without concrete output

Orchestration Notes

Grooming updates happen on main branch (not feature branches) because:

• Backlog state is shared across all work
• Tasks need to be visible to all developers
• Status changes aren't implementation changes

Implement Command Reference

Test-driven development in isolated worktree.

Purpose

Implement a task using TDD methodology: write tests first, then implementation, in an isolated worktree to keep main branch clean.

When Used in Workflow

• Task Cycle: After task selection, the main development step

Invocation

implement [TASK-ID]       # Implement specific task in worktree

Core Principle: Test-First Development

NEVER write implementation code before writing tests. Tests define the contract and guide the implementation.

Implementation Process

Phase 1: Setup & Validation

1. Locate Planning Documents

• Find relevant plans in /context-network/planning/
• Review architecture in /context-network/architecture/
• Check decisions in /context-network/decisions/

2. Validate Requirements

• Confirm understanding of acceptance criteria
• Identify any ambiguities
• Check for missing specifications

3. Create Worktree

   git worktree add .worktrees/[TASK-ID] -b task/[TASK-ID]-description
   cd .worktrees/[TASK-ID]

Phase 2: Test-Driven Development (MANDATORY)

Write tests before ANY implementation code

1. Write Tests First

• Happy path tests - Core functionality
• Edge case tests - Boundary conditions
• Error tests - Failure scenarios
• Integration tests - Component interactions

2. Test Structure

   describe('ComponentName', () => {
     beforeEach(() => { /* Setup */ });
     afterEach(() => { /* Cleanup */ });

     describe('functionName', () => {
       it('should handle normal input correctly', () => {
         // Arrange
         const input = setupTestData();
         // Act
         const result = functionName(input);
         // Assert
         expect(result).toEqual(expectedOutput);
       });

       it('should throw error for invalid input', () => {
         // Test error conditions
       });
     });
   });

3. Run Tests (Red Phase)

• Confirm ALL tests fail appropriately
• Validate test assertions are meaningful
• DO NOT PROCEED until tests are failing correctly

Phase 3: Implementation (Only After Tests)

STOP! Have you written tests? If no, go back to Phase 2.

1. Minimal Implementation

• Write ONLY enough code to make the next test pass
• No premature optimization
• No features not covered by tests
• Focus on one test at a time

2. Implementation Order

• Run test - see it fail
• Write minimal code to pass
• Run test - see it pass
• Refactor if needed (tests still pass)
• Move to next test

3. Code Quality

• Proper separation of concerns
• Clear naming conventions
• SOLID principles
• Every public method must have tests

Phase 4: Refinement (Red-Green-Refactor)

1. Verify All Tests Pass (Green Phase)

• ALL tests must be green
• No skipped tests
• Coverage > 80% minimum

2. Refactor With Confidence

• Improve code structure (tests protect you!)
• Remove duplication
• Optimize performance
• Run tests after EVERY refactor

Phase 5: Integration

1. Wire Up

• Connect to existing systems
• Update configuration
• Add to dependency injection

2. Commit Changes

   git add .
   git commit -m "[TASK-ID]: Implement [feature]

   - Added tests for [functionality]
   - Implemented [component]
   - Updated configuration

   Co-Authored-By: Claude <noreply@anthropic.com>"

Output Format

## Implementation Complete: [Task Name]

### Summary
- **What**: [Brief description]
- **Why**: [Business/technical reason]
- **How**: [High-level approach]

### Changes Made
- `path/to/new/file.ts` - [Purpose]
- `path/to/modified/file.ts` - [What changed]

### Testing
- [ ] **Tests written BEFORE implementation**
- [ ] Unit tests passing
- [ ] Edge cases tested
- [ ] Error conditions tested
- Test coverage: [X]%
- Number of tests: [Count]

### Validation
- [ ] Linting passes
- [ ] Type checking passes
- [ ] Build succeeds

Quality Checklist

Before marking complete:

• [ ] Tests were written FIRST (not retrofitted)
• [ ] All acceptance criteria met
• [ ] Coverage > 80%
• [ ] All tests pass consistently
• [ ] Code follows project patterns
• [ ] No console.logs or debug code
• [ ] Error handling is comprehensive

Orchestration Notes

After implementation completes:

• CHECKPOINT: IMPL_COMPLETE - Pause to verify work
• Show test results, coverage, build status
• If all pass: ready to proceed to review
• If failures: must address before continuing

Maintenance Command Reference

Context network audit and cleanup.

Purpose

Systematically review and maintain the integrity of the context network, ensuring it remains valuable, navigable, and accurate.

When Used in Workflow

• Sprint End: Deep cleanup between sprints
• Weekly: Regular maintenance
• Ad-hoc: When network feels disorganized

Common Invocation Patterns

maintenance              # Standard maintenance
maintenance --deep       # Thorough cleanup

Audit Categories

1. Structural Integrity

File Organization:

• Verify standard directory structure
• Check planning docs are in context network (not project root)
• Ensure no build artifacts in context network
• Validate .context-network.md exists and is accurate

Node Size & Scope:

• Flag nodes > 1500 words (consider splitting)
• Identify sparse nodes < 200 words (consider consolidating)
• Verify single-concept focus per node

Naming Conventions:

• Consistent file naming patterns
• Accurate node titles
• No duplicate names

2. Relationship Network

Link Integrity:

• Verify bidirectional relationships
• Identify orphaned nodes
• Flag broken links
• Check relationship type consistency

Relationship Quality:

• Explicit relationship types (not just "relates to")
• Meaningful relationship descriptions
• Identify missing connections

Cross-Domain Connections:

• Adequate connections between domains
• Well-documented interface points

3. Content Accuracy

Project Alignment:

• Compare descriptions against actual project
• Flag outdated architecture descriptions
• Identify missing documentation

Temporal Accuracy:

• Verify metadata reflects actual update dates
• Identify stale content
• Flag nodes marked "Dynamic" that haven't changed

4. Navigation & Usability

Entry Points:

• Main discovery.md provides orientation
• Domain-specific entry points current
• Navigation guides accurate

Search & Discovery:

• Key terms in appropriate nodes
• Tag consistency
• Discovery records use effective keywords
• Location indexes current

5. Metadata Consistency

• Complete classification on all nodes
• Consistent date formatting
• Accurate stability ratings
• Proper confidence levels

Red Flags to Check

1. Planning documents in project root 2. Architecture diagrams outside context network 3. Orphaned nodes with no connections 4. Circular navigation paths 5. Missing bidirectional links 6. Stale "Dynamic" content 7. Undefined relationship types 8. Inconsistent classification schemes 9. Missing change history 10. Build artifacts in context network 11. Discovery records without keywords 12. Location indexes with stale paths 13. Learning paths not connected to discoveries 14. Obsolete content not archived

Output Format

# Context Network Audit Report - [Date]

## Executive Summary
- Overall health score
- Critical issues requiring attention
- Key recommendations

## Detailed Findings

### Structural Integrity
- [Issues with examples]
- [Severity ratings]
- [Recommended fixes]

### Relationship Network
- [Link integrity issues]
- [Missing connections]

### Content Accuracy
- [Outdated information]
- [Missing documentation]

### Navigation & Usability
- [Navigation issues]
- [Discovery problems]

## Prioritized Recommendations

### Critical (Address Immediately)
1. [Issue] → [Fix] → [Impact]

### High Priority (This Week)
1. [Issue] → [Fix] → [Impact]

### Medium Priority (This Month)
1. [Issue] → [Fix] → [Impact]

## Process Improvements
- [Workflow changes]
- [Automation opportunities]

Orchestration Notes

Maintenance is typically run:

• At workflow boundaries (sprint end, week end)
• Before major planning sessions
• When navigation feels difficult
• Ensures context network remains useful

Merge Complete Command Reference

Merge feature branch to main, cleanup worktree, and update task status.

Purpose

Complete the merge lifecycle: merge to main, cleanup branches and worktrees, mark task as complete.

When Used in Workflow

• Task Cycle: Final step after merge-prep validation

Prerequisites

• All validation checks passed in merge-prep
• Branch is up-to-date with main
• No merge conflicts

Completion Process

Phase 1: Pre-Merge Check

# Navigate to worktree
cd .worktrees/[TASK-ID]/

# Verify on correct branch
git branch --show-current  # Should be task/[TASK-ID]-*

# Verify clean state
git status --porcelain  # Should be empty

# Final test run
npm test
npm run build

Phase 2: Merge to Main

# Switch to main repo (not worktree)
cd /path/to/main/repo

# Update main
git checkout main
git pull --rebase origin main

# Merge feature branch (squash recommended)
git merge --squash task/[TASK-ID]-description

# Create merge commit with descriptive message
git commit -m "[TASK-ID]: [Task Title]

Implements [feature description].

Changes:
- [Change 1]
- [Change 2]

Tests: All passing
"

# Push to origin
git push origin main

Alternative: Standard merge (preserves commit history)

git merge --no-ff task/[TASK-ID]-description -m "[TASK-ID]: [Task Title]"
git push origin main

Phase 3: Worktree Cleanup

# Navigate out of worktree
cd /path/to/main/repo

# Remove worktree
git worktree remove .worktrees/[TASK-ID]/

# Verify removal
git worktree list

# Prune stale references
git worktree prune

Phase 4: Branch Cleanup

# Delete local feature branch
git branch -d task/[TASK-ID]-description

# Delete remote feature branch
git push origin --delete task/[TASK-ID]-description

Phase 5: Update Task Status

CRITICAL: After merge, status updates happen ON MAIN

# Ensure on main
git checkout main

# Update task file
# - Status: completed
# - Completed: [current date]
# - Merge commit: [commit hash]

# Update status indexes
# - Remove from in-progress.md
# - Add to completed.md

# Commit status update
git add context-network/backlog/
git commit -m "Complete: [TASK-ID] merged to main"
git push origin main

Note: This is the ONLY command that commits to main because:

• Feature branch has already been reviewed
• We're just recording completion in the backlog
• Feature branch and worktree no longer exist
• This is administrative bookkeeping

Phase 6: Update Backlog Epic File and Project Status

CRITICAL: Persist progress to source-of-truth documentation.

Without this phase, internal tracking (worker progress files, coordinator state) diverges from the backlog and project status files that humans and future sessions rely on.

# Ensure on main
git checkout main

Step 1: Update task status in the backlog epic file

# Locate the epic file that contains this task
# e.g., context-network/backlog/by-epic/E1-feature-name.md

# Change the task's status from "ready" (or "in-progress") to "complete"
# Update any completion metadata (date, commit hash)

Step 2: Update epic-level progress

# Recalculate the epic's completion count
# e.g., "Status: In Progress (22/28 complete)" → "Status: In Progress (23/28 complete)"
# If all tasks complete, update epic status to "Complete"

Step 3: Unblock dependent tasks

# Check if any tasks in the epic were blocked on the just-completed task
# If so, update their status from "blocked" to "ready"
# Example: If TASK-023 was blocked by TASK-022, and TASK-022 is now complete,
#          change TASK-023 status to "ready"

Step 4: Update project status file

# Update context/status.md (or equivalent project status file) with:
# - Current project phase
# - Epic progress table (tasks completed / total per epic)
# - Recently completed work
# - Active/upcoming work summary

Step 5: Commit documentation updates

git add context-network/backlog/ context/status.md
git commit -m "docs: Update backlog and project status after [TASK-ID] completion"
git push origin main

Why this phase exists: Internal tracking files (.coordinator/state.json, worker progress files) are ephemeral and session-scoped. The backlog epic files and project status are the persistent source of truth. Skipping this phase causes documented state to drift from reality — future sessions will see stale "ready" statuses for already-completed tasks.

Error Handling

Merge Conflicts

1. cd /path/to/main/repo
2. git checkout main
3. git pull
4. git merge --squash task/[TASK-ID]-description
5. Resolve conflicts
6. git add . && git commit
7. git push

Tests Fail on Main After Merge

# Revert the merge
git revert HEAD
git push origin main

# Return to worktree to fix
cd .worktrees/[TASK-ID]/
# Fix issues
# Re-run merge process

Worktree Already Removed

# Just clean up branch
git branch -D task/[TASK-ID]-description
git push origin --delete task/[TASK-ID]-description

Output Format

## Task Merged Successfully!

**Task:** [TASK-ID] - [Task Title]
**Commit:** [commit-hash]
**Status:** Completed

### Cleanup Complete
- [x] Merged to main
- [x] Feature branch deleted
- [x] Worktree removed
- [x] Task status updated
- [x] Backlog indexes updated
- [x] Epic file updated (task marked complete, dependents unblocked)
- [x] Project status file updated

### Next Available Tasks
[Top 3 ready tasks from backlog]

Rollback Procedure

If issues discovered after merge:

# Revert the merge commit
git revert [merge-commit-sha]
git push origin main

# Task will need to be reopened
# Update status back to in-progress

Orchestration Notes

After completion:

• Task cycle is complete
• Can immediately start next task cycle
• Consider running /discovery to capture learnings
• Consider /retrospective for larger tasks

Merge Prep Command Reference

Prepare and validate implementation before merging to main.

Purpose

Validate implementation, ensure all checks pass, and prepare for direct merge to main branch.

When Used in Workflow

• Task Cycle: After reviews and fixes, before merge

Prerequisites

• Task implementation complete in worktree
• All changes committed to feature branch
• Reviews complete with no blocking issues

Merge Preparation Process

Phase 1: Identify Context

# Check current branch
git branch --show-current

# Should be in worktree
pwd  # .worktrees/[TASK-ID]/

Phase 2: Validation Suite

ALL CHECKS MUST PASS before merging

1. Run Test Suite

   npm test
   npm run test:integration

2. Code Quality Checks

   npm run lint
   npm run typecheck

3. Build Verification

   npm run build

4. Coverage Check

• Ensure > 80% coverage for new code

Phase 3: Update from Main

Ensure feature branch is up-to-date with main:

# Fetch latest changes
git fetch origin main

# Check for conflicts
git merge origin/main --no-commit --no-ff
git merge --abort  # Just checking

# If no conflicts, actually merge
git merge origin/main -m "Merge main into task/[TASK-ID]"

Phase 4: Generate Merge Documentation

Create documentation for the merge (stored in commit message or task file):

## [TASK-ID]: [Task Title]

### Summary
[Brief description of what was implemented]

### Changes
- [Key change 1]
- [Key change 2]
- [Key change 3]

### Acceptance Criteria
[Copy from task file, mark completed items]
- [x] Criterion 1 completed
- [x] Criterion 2 completed

### Testing
- Unit tests: [count] added/modified
- Integration tests: [count] added/modified
- Coverage: [before]% → [after]%
- All tests passing

### Technical Notes
[Any important implementation details]

Phase 5: Final Push

# Push latest changes
git push origin task/[TASK-ID]-description

Validation Checklist

Before proceeding to merge:

• [ ] All tests pass
• [ ] Code coverage meets minimum (80%)
• [ ] Linting has no errors
• [ ] Type checking passes
• [ ] Build succeeds
• [ ] No debug code remains
• [ ] Documentation updated
• [ ] Commits are clean and descriptive
• [ ] Branch is up-to-date with main

Error Handling

If Tests Fail

1. Fix issues in worktree 2. Commit fixes 3. Re-run validation 4. Do NOT proceed until passing

If Merge Conflicts with Main

1. Merge main into feature branch 2. Resolve conflicts 3. Commit resolution 4. Re-run all tests 5. Push updated branch

If Not in Worktree

cd .worktrees/[TASK-ID]/
# Or error if task not in progress

Output Format

## Ready for Merge!

**Task:** [TASK-ID] - [Task Title]
**Branch:** task/[TASK-ID]-description
**Status:** Ready to merge

### Validation Results
- Tests: PASSED (X/X)
- Lint: PASSED
- TypeCheck: PASSED
- Build: PASSED
- Coverage: XX%

### Next Steps
Run merge-complete to merge to main

Orchestration Notes

After validation:

• CHECKPOINT: MERGE_READY - Confirm ready to merge
• All validation must pass
• Branch must be up-to-date with main
• On confirmation: ready for merge-complete

Next Command Reference

Identify the single next best task to work on from the groomed backlog.

Purpose

Select the highest priority ready task, providing just enough information to start implementation.

When Used in Workflow

• Task Cycle: After sync, before implement
• Ad-hoc: When asking "what should I work on?"

Invocation

next                      # Select next task from ready queue

Selection Process

Step 1: Load Ready Tasks

Read context-network/backlog/by-status/ready.md to get available tasks.

Step 2: Selection Logic

Priority Order: 1. Critical Priority tasks (if any) 2. High Priority tasks 3. Medium Priority tasks 4. Low Priority tasks

Within same priority level, prefer:

• Tasks with no dependencies over those with dependencies
• Smaller tasks (trivial/small) over larger ones (medium)
• Tasks that unblock other work
• Tasks in sequence (e.g., TASK-004-2 before TASK-004-3)

Step 3: Output

If ready task found:

**Next Task:** [TASK-ID] - [Task Title]

**Priority:** [Critical/High/Medium/Low]
**Size:** [trivial/small/medium]
**Branch:** [suggested-branch-name]

Start with: implement [TASK-ID]

If no ready tasks:

No tasks are currently ready for implementation.

Run groom to prepare tasks from the planned backlog.

What NOT to Do

• Don't load or display full task details
• Don't show multiple task options
• Don't provide extensive context about the task
• Don't analyze task content in depth
• Don't check dependencies (should already be resolved for ready tasks)

Output Format

Keep it minimal:

• Task ID
• Task title
• Priority and size
• Suggested branch name
• How to start

Orchestration Notes

After next completes:

• CHECKPOINT: TASK_SELECTED - Pause for user confirmation
• User can accept the suggestion or request different task
• On acceptance, proceed to implement with the task ID

Retrospective Command Reference

Post-task analysis and context network updates.

Purpose

Conduct retrospective analysis after completing a task to identify what should be captured in the context network and what adjustments need to be made.

When Used in Workflow

• Sprint End: Comprehensive sprint retrospective
• Post-Task: After significant task completion
• Weekly: End of week review

Domain Boundary Reminder

• Context Network: Planning, architecture, design, strategies
• Project Artifacts: Source code, configuration, tests, public docs

Retrospective Process

Phase 1: Task Review

Task Summary:

• What was the original objective?
• What was actually accomplished?
• Were there deviations from plan?

Decision Inventory:

• What architectural decisions were made?
• What trade-offs were considered?
• What alternatives were rejected and why?

Discovery Log:

• What unexpected challenges emerged?
• What new patterns were discovered?
• What assumptions proved incorrect?
• What discovery records were created?

Phase 2: Gap Analysis

Missing Documentation:

• Planning documents that would have helped?
• Design decisions not captured anywhere?
• New patterns that should be documented?
• Discovery records that would have saved time?

Outdated Information:

• Documentation that was incorrect?
• Nodes whose relationships changed?
• Confidence levels that need updating?

Relationship Gaps:

• Connections between nodes not documented?
• New cross-domain relationships discovered?
• Navigation paths that would help?

Phase 3: Update Requirements

For each gap, determine:

Update Type:

• New node creation
• Existing node modification
• Relationship establishment
• Navigation guide enhancement

Priority:

• Critical: Would cause immediate problems
• Important: Would improve future work significantly
• Nice-to-have: Enhances understanding

Phase 4: Execute Updates

New Node Creation:

## Node: [Title]

### Classification
- Domain: [Where it fits]
- Stability: [Change frequency]
- Confidence: [How certain]

### Key Content
[Essential information]

### Critical Relationships
- Depends on: [Prerequisites]
- Enables: [What it makes possible]

### Task Context
- Discovered during: [Task name]
- Relevance: [Why this matters]

Node Modification:

## Update for: [Node Title]

### What Changed
- Previous: [Old understanding]
- New: [Current understanding]
- Reason: [What led to change]

### Impact
- Affected relationships: [What needs review]
- Downstream implications: [What else needs updating]

Phase 5: Changelog Entry

## Retrospective: [Task Name] - [Date]

### Task Summary
- Objective: [Goal]
- Outcome: [Result]
- Key learnings: [Discoveries]

### Context Network Updates

#### New Nodes Created
- [Node Name]: [Brief description]

#### Discovery Records Created
- [YYYY-MM-DD-###]: [Description]

#### Nodes Modified
- [Node Name]: [What changed]

#### New Relationships
- [Source] → [Type] → [Target]: [Why it matters]

### Patterns and Insights
- Recurring themes: [What patterns emerged]
- Process improvements: [How to do better]
- Knowledge gaps: [What's still missing]

### Follow-up Recommendations
1. [Recommendation]: [Rationale]

Execution Checklist

• [ ] Reviewed all decisions made during task
• [ ] Identified planning/architecture content created
• [ ] Checked for outdated documentation encountered
• [ ] Documented new patterns discovered
• [ ] Created/updated relevant context network nodes
• [ ] Established important relationships
• [ ] Updated navigation guides
• [ ] Created changelog entry
• [ ] Identified follow-up improvements

Quality Checks

1. Placement: All planning docs in context network? 2. Relationships: Bidirectional links documented? 3. Classification: Accurate for all nodes? 4. Navigation: Would someone else find this? 5. Future Value: Will this save time later?

Orchestration Notes

Retrospective is an end-of-cycle activity:

• Run after significant task completion
• Run at sprint boundaries
• Ensures learning is captured before context is lost

Review Code Command Reference

Code quality review for maintainability, security, and best practices.

Purpose

Review code files for quality issues, security vulnerabilities, performance problems, and adherence to best practices.

When Used in Workflow

• Task Cycle: After implementation, before PR
• Ad-hoc: Code quality check at any time

Common Invocation Patterns

review-code               # Review all code
review-code --uncommitted # Only uncommitted changes
review-code --staged      # Only staged changes
review-code --branch      # All changes in current branch vs main
review-code --security    # Enhanced security focus
review-code --performance # Enhanced performance focus

Review Focus Areas

1. Code Quality and Maintainability

• Code duplication (DRY violations)
• Overly complex functions
• Proper separation of concerns
• Appropriate abstraction levels
• Code smells and anti-patterns

2. Security Vulnerabilities

• Hardcoded secrets, API keys, passwords
• Injection vulnerabilities (SQL, command, XSS)
• Unsafe type coercion or unvalidated inputs
• Authentication/authorization issues
• Insecure data handling

3. Performance Issues

• Inefficient algorithms or data structures
• Unnecessary loops or redundant computations
• Memory leaks or resource management issues
• Improper async/await usage
• Blocking operations

4. Error Handling

• Proper error handling and recovery
• Unhandled promise rejections
• Informative error messages
• Proper logging
• Graceful degradation

5. Code Standards

• Consistent naming conventions
• Proper typing (TypeScript) or type hints
• Single responsibility functions
• Design pattern usage
• SOLID principles

Common Anti-Patterns to Flag

Hardcoded Secrets:

// BAD
const API_KEY = "sk-1234567890abcdef";

SQL Injection:

// BAD
const query = `SELECT * FROM users WHERE id = ${userId}`;

Unhandled Promises:

// BAD
async function getData() {
  const result = await fetch('/api/data');
  return result.json();  // No error handling
}

Deep Nesting:

// BAD - Pyramid of doom
if (condition1) {
  if (condition2) {
    if (condition3) {
      // do something
    }
  }
}

Magic Numbers:

// BAD
if (user.age > 17) { /* ... */ }

Quality Thresholds

• Functions longer than 50 lines
• Files longer than 500 lines
• Cyclomatic complexity > 10
• Nesting depth > 4 levels
• Commented out code blocks
• TODO/FIXME without context

Output Format

## Code Review Summary

### Critical Issues (Security/Data Loss Risk)
- [Issues that could cause vulnerabilities or data loss]

### High Priority Issues (Bugs/Crashes)
- [Issues that could cause runtime errors]

### Medium Priority Issues (Maintainability)
- [Issues affecting code maintainability]

### Low Priority Issues (Style/Convention)
- [Minor improvements]

### Statistics
- Files reviewed: X
- Critical issues: A
- High priority: B
- Medium priority: C
- Low priority: D

### Top Recommendations
1. [Most critical improvement]
2. [Second priority]
3. [Third priority]

### Positive Findings
- [Well-written patterns observed]

Orchestration Notes

Review results feed into the REVIEWS_DONE checkpoint:

• Critical issues: must address before continuing
• High issues: strongly recommend addressing
• Medium/Low: can defer to tasks via apply-recommendations

Review Tests Command Reference

Unit test quality review for isolation, meaningfulness, and best practices.

Purpose

Review test files for quality issues including tautological tests, proper mocking, meaningful assertions, and test structure.

When Used in Workflow

• Task Cycle: After implementation, alongside code review
• Ad-hoc: Test quality assessment

Common Invocation Patterns

review-tests               # Review all test files
review-tests --uncommitted # Only uncommitted changes
review-tests --staged      # Only staged changes
review-tests --branch      # All changes in current branch
review-tests --coverage 80 # Minimum coverage threshold

Review Focus Areas

1. Tautological Tests Detection

• Tests that assert the same value they just set
• Tests that only verify mocked behavior
• Tests like: expect(true).toBe(true)
• Tests that pass even when implementation is broken

2. Proper Mocking and Isolation

• External dependencies mocked (databases, APIs, file systems)
• Only unit under test uses real implementation
• Mocks properly reset between tests
• No tests depending on external state

3. Meaningful Assertions

• Tests check actual behavior, not implementation details
• Assertions test the contract/interface
• Edge cases and error conditions verified
• Error messages and types tested

4. Test Structure and Clarity

• Test names clearly describe scenarios
• Arrange-Act-Assert structure
• Tests are independent and order-agnostic
• Proper setup/teardown usage

5. Coverage Quality

• Business logic thoroughly tested
• Edge cases, error paths, boundaries covered
• Not just happy path testing

Common Anti-Patterns to Flag

Direct Tautologies:

// BAD - Testing the assignment
const result = 5;
expect(result).toBe(5);

Mock-Only Tests:

// BAD - Testing the mock, not the component
mockService.getValue.mockReturnValue(42);
const result = component.getData();
expect(result).toBe(42);

Self-Referential Tests:

// BAD - Just testing constructor assignment
const user = new User({ name: 'John' });
expect(user.name).toBe('John');

Missing Isolation:

// BAD - Depends on external state
const data = await fetchFromRealDatabase();
expect(data).toBeDefined();

Quality Checks

• Testing private methods directly
• Testing implementation details
• Snapshot tests without clear purpose
• Missing negative test cases
• Tests with no assertions
• Tests that always pass

Examples of Good Tests

// GOOD - Tests actual behavior
it('should calculate discount correctly for premium users', () => {
  const calculator = new PriceCalculator();
  const result = calculator.calculatePrice({
    basePrice: 100,
    userType: 'premium'
  });
  expect(result).toBe(80); // 20% discount
});

// GOOD - Proper mocking with behavior verification
it('should handle API errors gracefully', async () => {
  mockApi.fetch.mockRejectedValue(new Error('Network error'));
  const service = new DataService(mockApi);

  await expect(service.getData()).rejects.toThrow('Failed to fetch data');
  expect(mockLogger.error).toHaveBeenCalledWith(
    'API call failed',
    expect.any(Error)
  );
});

Output Format

## Test Quality Review Summary

### Critical Issues (High Severity)
- [Issues that break test isolation or leave functionality untested]

### Poor Practices (Medium Severity)
- [Issues that reduce test effectiveness]

### Style Improvements (Low Severity)
- [Minor improvements and consistency issues]

### Statistics
- Test files reviewed: X
- Files with issues: Y
- Tautological tests found: Z
- Missing mocks: N

### Top Recommendations
1. [Most important improvement]
2. [Second priority]
3. [Third priority]

Orchestration Notes

Test review results combine with code review for REVIEWS_DONE checkpoint:

• Tautological tests: should fix (tests provide false confidence)
• Missing isolation: should fix (tests are unreliable)
• Style issues: can defer

Status Command Reference

Project health and progress reporting.

Purpose

Provide comprehensive overview of project health, progress, risks, and recommendations.

When Used in Workflow

• Daily Morning: Quick health check
• Sprint Start: Baseline status
• Sprint End: Sprint metrics

Common Invocation Patterns

status                    # Detailed report (default)
status --brief           # Quick summary (1-2 paragraphs)
status --sprint          # Focus on current sprint
status --metrics         # Include quantitative metrics
status --risks           # Emphasize risks and blockers

Assessment Process

Phase 1: Progress Evaluation

Task Status Analysis:

• Review /tasks/ for completion rates
• Check /planning/sprint-*.md for progress
• Analyze /planning/backlog.md for remaining work

Velocity Metrics:

• Tasks completed this period
• Tasks in progress
• Tasks blocked
• Completion rate vs plan

Phase 2: Health Indicators

Code Quality:

• Recent test coverage changes
• Technical debt accumulation
• Code complexity trends
• Recent audit findings

Documentation:

• Context network currency
• Documentation coverage
• Discovery records created
• Knowledge gaps identified

Process:

• Decision velocity
• Blocker resolution time
• Collaboration effectiveness

Phase 3: Risk Assessment

Current Risks:

• Technical risks and mitigation
• Schedule risks and impact
• Resource constraints
• External dependencies

Emerging Concerns:

• New technical debt
• Architectural drift
• Process breakdowns
• Knowledge silos

Phase 4: Recommendations

Immediate Actions:

• Critical issues to address
• Quick wins available
• Blockers to resolve

Strategic Adjustments:

• Process improvements
• Architecture refinements
• Resource reallocations

Output Format

# Project Status Report - [Date]

## Executive Summary
[1-2 paragraph overview]

## Progress Overview

### Current Sprint/Milestone
- **Goal**: [Objective]
- **Progress**: X/Y tasks (Z%)
- **Days Remaining**: N
- **Status**: On Track | At Risk | Behind

### Velocity
- **This Period**: X tasks completed
- **Average**: Y tasks/period
- **Trend**: Improving | Stable | Declining

## Key Accomplishments
- [Achievement 1]
- [Achievement 2]

## Current Focus
- [Priority 1]
- [Priority 2]

## Health Indicators

### Code Quality
- **Test Coverage**: X%
- **Technical Debt**: Low/Medium/High
- **Build Status**: Passing | Failing

### Documentation
- **Currency**: X% up-to-date
- **Coverage**: Y% documented

## Risks & Blockers

### Critical Issues
1. **[Issue]**
   - Impact: [Description]
   - Action: [What to do]

### Warnings
1. **[Concern]**
   - Risk: [What might happen]
   - Mitigation: [Prevention]

## Recommendations

### Immediate (This Week)
1. [Most urgent]
2. [Second priority]

### Short-term (This Sprint)
- [Process improvement]
- [Technical adjustment]

## Upcoming Milestones
- [Date] - [Milestone 1]
- [Date] - [Milestone 2]

Status Indicators

Use consistently:

• On Track / At Risk / Behind
• Improving / Stable / Declining
• Complete / In Progress / Waiting / Blocked

Orchestration Notes

Status provides context for workflow decisions:

• Morning: informs task selection
• Sprint boundaries: guides planning
• Risk-focused: prioritizes blockers

Sync Command Reference

Reality synchronization between context network and actual project state.

Purpose

Detect and correct drift between planned/documented state and actual project reality. Identifies work that's been completed but not documented, updates task statuses, and realigns the network with current state.

When Used in Workflow

• Task Cycle: First step to ensure starting from accurate state
• Daily Morning: Reality check before starting work
• Daily Evening: Capture actual progress made
• Sprint End: Full synchronization before retrospective

Common Invocation Patterns

sync                      # Full sync of all active plans
sync --last 1d           # Only check work from last day
sync --last 1w           # Only check work from last week
sync --dry-run           # Preview changes without applying
sync --verbose           # Include detailed evidence

Sync Process

Phase 1: Reality Assessment

Scan project artifacts: 1. List files changed in the timeframe 2. Identify new files/directories created 3. Review recent commits 4. Check test files for implemented features 5. Scan configuration changes 6. Review dependency updates

Phase 2: Plan Comparison

Load active plans from context network:

• Current sprint/milestone tasks
• Active project plans
• In-progress feature specifications
• Recent task handoffs
• Pending implementation items

Phase 3: Drift Detection

Identify completion patterns:

Definitely Completed:

• Planned file exists with expected structure
• Tests exist and reference the feature
• Configuration includes the component
• Integration points are connected

Partially Completed:

• Some but not all expected files exist
• Basic structure without full implementation
• Tests exist but incomplete

Divergent Implementation:

• Implementation exists but differs from plan
• Alternative approach taken
• Scope changed during implementation

Phase 4: Evidence Gathering

For each suspected completion, document:

• Direct evidence (files, tests, config)
• Supporting evidence (imports, references, commits)
• Counter-evidence (missing files, incomplete integration)
• Confidence assessment (High/Medium/Low)

Phase 5: Network Updates

Generate updates for:

• Task status changes
• New documentation needs
• Plan adjustments

Output Format

# Context Network Sync Report

## Sync Summary
- Planned items checked: X
- Completed but undocumented: Y
- Partially completed: Z
- Divergent implementations: N

## Completed Work Discovered

### High Confidence Completions
1. **[Feature Name]**
   - Evidence: [Brief summary]
   - Implementation location: [Path]
   - Action: Mark as complete

### Medium Confidence Completions
1. **[Feature Name]**
   - Evidence: [What we found]
   - Uncertainty: [What's unclear]
   - Recommended verification: [How to confirm]

## Network Updates Required
- [ ] Update task status for [items]
- [ ] Create documentation stubs for [features]
- [ ] Update progress indicators

## Recently Completed Tasks (Last 7 Days)
[List of tasks that may still appear as available but are actually done]

Orchestration Notes

After sync completes:

• If drift detected: summarize key findings for checkpoint
• If no drift: auto-continue to next workflow step
• Update checkpoint context with sync results

Daily Phase Reference

Morning and evening workflow sequences for daily development rhythm.

Overview

Daily sequences maintain alignment and capture knowledge at natural workflow boundaries.

Morning Standup (~5 minutes)

MORNING SEQUENCE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  START
    │
    ▼
┌───────────────────────┐
│ sync --last 1d        │ ─── What actually happened yesterday?
│ --dry-run             │
└───────────┬───────────┘
            │
            ▼
┌───────────────────────┐
│ status --brief        │ ─── Current sprint health
│ --sprint              │
└───────────┬───────────┘
            │
            ▼
┌───────────────────────┐
│ groom --ready-only    │ ─── What's ready to work on?
└───────────┬───────────┘
            │
            ▼
         OUTPUT
    "Today's Priorities"

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Step 1: Sync (Reality Check)

Command: sync --last 1d --dry-run

Purpose: Understand what actually got done yesterday vs what was planned.

What to look for:

• Tasks completed but not documented
• Work in progress status
• Any drift between plan and reality

Output: Sync report showing yesterday's actual progress

---

Step 2: Status (Health Check)

Command: status --brief --sprint

Purpose: Quick sprint health overview.

What to look for:

• Sprint progress percentage
• Any critical blockers
• Risk indicators
• Velocity trend

Output: 1-2 paragraph status summary

---

Step 3: Groom (Ready Queue)

Command: groom --ready-only

Purpose: See what's immediately actionable.

What to look for:

• Tasks ready for implementation
• Priority ordering
• Any quick wins
• Blocked tasks that might unblock soon

Output: List of ready tasks with priorities

---

Morning Output

After morning sequence, you should know:

• What was actually accomplished yesterday
• Current sprint health status
• What tasks are ready to work on today
• Any blockers to address

Recommended next step: Start task cycle with highest priority ready task

---

Evening Wrap-up (~10 minutes)

EVENING SEQUENCE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  START
    │
    ▼
┌───────────────────────┐
│ checklist             │ ─── Is anything important about to be lost?
└───────────┬───────────┘
            │
            ▼
┌───────────────────────┐
│ discovery             │ ─── Capture any learnings from today
└───────────┬───────────┘
            │
            ▼
┌───────────────────────┐
│ sync --last 1d        │ ─── Update task statuses
└───────────┬───────────┘
            │
            ▼
         OUTPUT
   "Day Complete Summary"

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Step 1: Checklist (Work Preservation)

Command: checklist

Purpose: Ensure nothing important is lost before ending the day.

What to check:

• Uncommitted changes that should be committed
• Notes that should be documented
• Decisions that need recording
• Work in progress that needs handoff notes

Output: Checklist of items to address

---

Step 2: Discovery (Knowledge Capture)

Command: discovery

Purpose: Document any insights or learnings from the day.

What to capture:

• "Aha moments" about the codebase
• Location discoveries (where things are)
• Pattern recognitions
• Assumption corrections

Output: Discovery records created

---

Step 3: Sync (Status Update)

Command: sync --last 1d

Purpose: Update task statuses to reflect actual work done.

What to update:

• Mark completed work as done
• Update in-progress estimates
• Document any partial completions
• Note blockers encountered

Output: Updated context network reflecting reality

---

Evening Output

After evening sequence, you should have:

• No lost work or uncommitted important changes
• Today's learnings captured in discovery records
• Task statuses reflecting actual progress
• Clear state for tomorrow's morning standup

---

Quick Reference Commands

# Full morning sequence
/agile-workflow --phase daily-morning

# Full evening sequence
/agile-workflow --phase daily-evening

# Individual commands
sync --last 1d --dry-run
status --brief --sprint
groom --ready-only
checklist
discovery
sync --last 1d

Cadence Recommendations

Morning is critical because it prevents duplicate work and ensures you're working on the right things.

Evening is recommended because knowledge capture is most effective when context is fresh.

Integration with Task Cycle

Daily sequences wrap around task cycles:

┌─────────────────────────────────────────────────┐
│               WORK DAY                          │
├─────────────────────────────────────────────────┤
│                                                 │
│  Morning Standup                                │
│       │                                         │
│       ▼                                         │
│  ┌─────────────────────────────────────────┐   │
│  │  Task Cycle 1                           │   │
│  │  (implement → review → PR)              │   │
│  └─────────────────────────────────────────┘   │
│       │                                         │
│       ▼                                         │
│  ┌─────────────────────────────────────────┐   │
│  │  Task Cycle 2 (optional)                │   │
│  │  (smaller task or continuation)         │   │
│  └─────────────────────────────────────────┘   │
│       │                                         │
│       ▼                                         │
│  Evening Wrap-up                                │
│                                                 │
└─────────────────────────────────────────────────┘

Sprint Phase Reference

Sprint boundary ceremonies: start and end sequences.

Overview

Sprint sequences ensure proper planning at the start and thorough closure at the end of each sprint.

Sprint Start (~60 minutes)

SPRINT START SEQUENCE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  START
    │
    ▼
┌───────────────────────┐
│ sync --all            │ ─── Full reality alignment
└───────────┬───────────┘
            │
            ▼
┌───────────────────────┐
│ groom --all           │ ─── Comprehensive grooming
└───────────┬───────────┘
            │
            ▼
┌───────────────────────┐
│ plan sprint-goals     │ ─── Define sprint objectives
└───────────┬───────────┘
            │
            ▼
┌───────────────────────┐
│ status --detailed     │ ─── Establish baseline
└───────────┬───────────┘
            │
            ▼
         OUTPUT
   "Sprint Plan Ready"

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Step 1: Full Sync

Command: sync --all

Purpose: Complete alignment between documentation and reality.

Actions:

• Review all in-progress work
• Identify any undocumented completions
• Clear out stale status entries
• Ensure backlog reflects truth

Duration: ~15 minutes

---

Step 2: Comprehensive Grooming

Command: groom --all

Purpose: Prepare all tasks for the sprint.

Actions:

• Review entire backlog
• Refine vague tasks into actionable items
• Add acceptance criteria
• Estimate complexity
• Identify dependencies
• Move tasks to ready status

Duration: ~25 minutes

---

Step 3: Sprint Planning

Command: plan sprint-goals

Purpose: Define what the sprint will accomplish.

Actions:

• Set sprint objective
• Select tasks for sprint
• Identify architecture needs
• Note dependencies and risks
• Create sprint plan document

Duration: ~15 minutes

---

Step 4: Baseline Status

Command: status --detailed

Purpose: Establish metrics baseline for sprint.

Actions:

• Document starting velocity
• Note current tech debt
• Record test coverage
• Capture documentation state

Duration: ~5 minutes

---

Sprint Start Output

After sprint start, you should have:

• Clean, aligned backlog
• Groomed, ready tasks
• Clear sprint objective
• Baseline metrics for comparison
• Sprint plan document

---

Sprint End (~90 minutes)

SPRINT END SEQUENCE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  START
    │
    ▼
┌───────────────────────┐
│ sync --sprint         │ ─── Final sprint sync
└───────────┬───────────┘
            │
            ▼
┌───────────────────────┐
│ retrospective         │ ─── Capture learnings
└───────────┬───────────┘
            │
            ▼
┌───────────────────────┐
│ audit --scope sprint  │ ─── Quality review
└───────────┬───────────┘
            │
            ▼
┌───────────────────────┐
│ status --metrics      │ ─── Sprint metrics
│ --detailed            │
└───────────┬───────────┘
            │
            ▼
┌───────────────────────┐
│ maintenance --deep    │ ─── Context network cleanup
└───────────┬───────────┘
            │
            ▼
         OUTPUT
   "Sprint Closed"

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Step 1: Final Sync

Command: sync --sprint

Purpose: Ensure all sprint work is documented.

Actions:

• Verify all completed tasks are marked done
• Identify any work that spilled over
• Update carryover items
• Clean up in-progress that finished

Duration: ~10 minutes

---

Step 2: Retrospective

Command: retrospective

Purpose: Capture sprint learnings.

Actions:

• Review accomplishments
• Document decisions made
• Capture discoveries
• Identify process improvements
• Update context network with insights
• Create retrospective record

Duration: ~25 minutes

---

Step 3: Quality Audit

Command: audit --scope sprint

Purpose: Review sprint's code quality.

Actions:

• Review all code added during sprint
• Identify quality issues
• Document technical debt added
• Note patterns (good and bad)
• Generate audit report

Duration: ~20 minutes

---

Step 4: Sprint Metrics

Command: status --metrics --detailed

Purpose: Capture sprint performance.

Actions:

• Calculate velocity (tasks/points completed)
• Compare to baseline
• Document coverage changes
• Note debt trends
• Record accomplishments

Duration: ~10 minutes

---

Step 5: Deep Maintenance

Command: maintenance --deep

Purpose: Between-sprint cleanup.

Actions:

• Audit context network structure
• Fix broken links
• Update stale content
• Archive completed work
• Improve navigation
• Clean up temporary files

Duration: ~25 minutes

---

Sprint End Output

After sprint end, you should have:

• All sprint work documented
• Learnings captured in retrospective
• Quality assessment on record
• Sprint metrics documented
• Clean context network for next sprint

---

Quick Reference Commands

# Sprint start sequence
/agile-workflow --phase sprint-start

# Sprint end sequence
/agile-workflow --phase sprint-end

# Individual commands
sync --all
groom --all
plan sprint-goals
status --detailed
sync --sprint
retrospective
audit --scope sprint
status --metrics --detailed
maintenance --deep

Cadence Recommendations

Both ceremonies are critical for maintaining:

• Clean handoffs between sprints
• Captured institutional knowledge
• Accurate velocity tracking
• Healthy context network

Sprint Rhythm

┌─────────────────────────────────────────────────────────┐
│                    SPRINT (2 weeks)                     │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  Sprint Start (Day 1)                                   │
│       │                                                 │
│       ▼                                                 │
│  ┌───────────────────────────────────────────────────┐ │
│  │  Week 1                                           │ │
│  │  ├── Daily Morning Standup                        │ │
│  │  ├── Task Cycles (implementation)                 │ │
│  │  └── Daily Evening Wrap-up                        │ │
│  └───────────────────────────────────────────────────┘ │
│       │                                                 │
│       ▼                                                 │
│  ┌───────────────────────────────────────────────────┐ │
│  │  Week 2                                           │ │
│  │  ├── Daily Morning Standup                        │ │
│  │  ├── Task Cycles (implementation)                 │ │
│  │  └── Daily Evening Wrap-up                        │ │
│  └───────────────────────────────────────────────────┘ │
│       │                                                 │
│       ▼                                                 │
│  Sprint End (Last Day)                                  │
│                                                         │
└─────────────────────────────────────────────────────────┘

Integration Notes

Sprint ceremonies nest around daily and task cycles:

• Sprint Start prepares the backlog for daily work
• Daily sequences maintain rhythm within the sprint
• Task cycles are the actual implementation work
• Sprint End closes out and prepares for next iteration

Task Cycle Phase Reference

Complete flow for implementing a single task from selection to merge (git-only version).

Overview

The task cycle is the primary workflow for development work. It takes a task from the ready queue through implementation, review, and merge directly to main.

TASK CYCLE FLOW
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  START
    │
    ▼
┌─────────┐
│  sync   │ ─── Reality check: align docs with actual state
└────┬────┘
     │
     ▼
┌─────────┐
│  next   │ ─── Select highest priority ready task
└────┬────┘
     │
     ▼
╔═══════════════════════════════════════════════════════╗
║  CHECKPOINT: TASK_SELECTED                            ║
║  • Display task details                               ║
║  • Confirm selection or choose different task         ║
╚═══════════════════════════════════════════════════════╝
     │
     ▼
┌─────────────┐
│  implement  │ ─── Create worktree, TDD, build
└──────┬──────┘
       │
       ▼
╔═══════════════════════════════════════════════════════╗
║  CHECKPOINT: IMPL_COMPLETE                            ║
║  • Show test results and coverage                     ║
║  • Verify build status                                ║
║  • Confirm ready for review                           ║
╚═══════════════════════════════════════════════════════╝
       │
       ▼
┌─────────────┐     ┌───────────────┐
│ review-code │ ──▶ │ review-tests  │
└──────┬──────┘     └───────┬───────┘
       │                    │
       └────────┬───────────┘
                │
                ▼
╔═══════════════════════════════════════════════════════╗
║  CHECKPOINT: REVIEWS_DONE                             ║
║  • Display combined review results                    ║
║  • Critical issues block progress                     ║
║  • User decides: fix now or defer                     ║
╚═══════════════════════════════════════════════════════╝
                │
       ┌───────┴───────┐
       │  Has issues?  │
       └───────┬───────┘
         Yes   │   No
          ▼    │    │
┌──────────────────┐│
│apply-recommend's ││
└────────┬─────────┘│
         │          │
         └────┬─────┘
              │
              ▼
┌─────────────┐
│ merge-prep  │ ─── Validate, prepare for merge
└──────┬──────┘
       │
       ▼
╔═══════════════════════════════════════════════════════╗
║  CHECKPOINT: MERGE_READY                              ║
║  • Display validation results                         ║
║  • Confirm ready to merge to main                     ║
╚═══════════════════════════════════════════════════════╝
       │
       ▼
┌───────────────┐
│ merge-complete│ ─── Merge, cleanup worktree, update task status
└──────┬────────┘
       │
       ▼
┌───────────────────┐
│ update-backlog    │ ─── Update epic file, unblock dependents,
│ & project status  │     update project status
└──────┬────────────┘
       │
       ▼
    END

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Step-by-Step Details

Step 1: Sync (Reality Check)

Command: sync --last 1d --dry-run

Purpose: Ensure context network matches reality before starting work.

Actions: 1. Check files changed recently 2. Compare against documented task statuses 3. Identify any completed but undocumented work 4. Report sync findings

Outputs:

• Sync report
• Any tasks that should be marked complete
• Warning if attempting duplicate work

Next Step: Proceed to task selection

---

Step 2: Next (Task Selection)

Command: next

Purpose: Identify the single best task to work on.

Actions: 1. Read ready task queue 2. Apply priority ordering 3. Select highest priority available task 4. Display task summary

Outputs:

• Task ID and title
• Priority and size
• Suggested branch name

Triggers Checkpoint: TASK_SELECTED

---

Checkpoint: TASK_SELECTED

Display:

╔═══════════════════════════════════════════════════════╗
║  CHECKPOINT: Task Selection                           ║
╠═══════════════════════════════════════════════════════╣
║  Selected: [TASK-ID] - [Task Title]                   ║
║  Priority: [High/Medium/Low]                          ║
║  Size: [trivial/small/medium]                         ║
║  Branch: task/[TASK-ID]-[description]                 ║
║                                                       ║
║  Proceed with implementation?                         ║
║  [continue] [other task] [stop]                       ║
╚═══════════════════════════════════════════════════════╝

User Responses:

• continue: Proceed to implement
• other task: Return to task selection
• stop: Exit workflow

---

Step 3: Implement (TDD Development)

Command: implement [TASK-ID]

Purpose: Test-driven implementation in isolated worktree.

Actions: 1. Create worktree at .worktrees/[TASK-ID]/ 2. Create feature branch task/[TASK-ID]-description 3. Write tests FIRST (mandatory) 4. Implement to make tests pass 5. Run full test suite 6. Verify build succeeds 7. Commit all changes

Outputs:

• Working implementation
• Passing tests
• Coverage report
• Build status

Triggers Checkpoint: IMPL_COMPLETE

---

Checkpoint: IMPL_COMPLETE

Display:

╔═══════════════════════════════════════════════════════╗
║  CHECKPOINT: Implementation Complete                  ║
╠═══════════════════════════════════════════════════════╣
║  Tests: 15 passing                                    ║
║  Coverage: 87% (+12% new code)                        ║
║  Build: SUCCESS                                       ║
║  Linting: PASS                                        ║
║                                                       ║
║  Ready for code review?                               ║
║  [continue] [back] [stop]                             ║
╚═══════════════════════════════════════════════════════╝

Auto-Continue Condition: All tests pass AND build succeeds

---

Step 4: Review (Quality Validation)

Commands: review-code --uncommitted, review-tests --uncommitted

Purpose: Validate implementation quality.

Actions: 1. Run code quality review 2. Run test quality review 3. Identify issues by severity 4. Generate recommendations

Outputs:

• Combined review report
• Issues categorized by severity
• Specific recommendations

Triggers Checkpoint: REVIEWS_DONE

---

Checkpoint: REVIEWS_DONE

Display:

╔═══════════════════════════════════════════════════════╗
║  CHECKPOINT: Reviews Complete                         ║
╠═══════════════════════════════════════════════════════╣
║  Code Review:                                         ║
║    Critical: 0 | High: 1 | Medium: 3 | Low: 5         ║
║  Test Review:                                         ║
║    Critical: 0 | High: 0 | Medium: 2 | Low: 1         ║
║                                                       ║
║  High Priority: "Missing error handling in UserAPI"   ║
║                                                       ║
║  How to proceed?                                      ║
║  [fix all] [fix critical/high] [defer all] [stop]    ║
╚═══════════════════════════════════════════════════════╝

Decision Logic:

• Critical issues: MUST fix before proceeding
• High issues: STRONGLY RECOMMENDED to fix
• Medium/Low: Can defer to follow-up tasks

---

Step 5: Apply Recommendations (Conditional)

Command: apply-recommendations [review-output]

Purpose: Intelligently apply fixes and create follow-up tasks.

Actions: 1. Triage recommendations 2. Apply quick fixes immediately 3. Create tasks for complex issues 4. Re-run validation

Outputs:

• Applied fixes summary
• Created follow-up tasks
• Updated validation status

Next Step: Proceed to merge prep

---

Step 6: Merge Prep (Validate for Merge)

Command: merge-prep

Purpose: Validate implementation and prepare for merge.

Actions: 1. Run full validation suite 2. Update from main branch 3. Verify no merge conflicts 4. Generate merge documentation 5. Confirm ready to merge

Outputs:

• Validation results
• Conflict check status
• Ready for merge confirmation

Triggers Checkpoint: MERGE_READY

---

Checkpoint: MERGE_READY

Display:

╔═══════════════════════════════════════════════════════╗
║  CHECKPOINT: Ready to Merge                           ║
╠═══════════════════════════════════════════════════════╣
║  Task: [TASK-ID] - [Task Title]                       ║
║  Branch: task/[TASK-ID]-description                   ║
║                                                       ║
║  Validation:                                          ║
║  - Tests: PASSED (15/15)                              ║
║  - Lint: PASSED                                       ║
║  - Build: PASSED                                      ║
║  - Conflicts: None                                    ║
║                                                       ║
║  Ready to merge to main?                              ║
║  [merge] [stop]                                       ║
╚═══════════════════════════════════════════════════════╝

Auto-Continue Condition: All validation passes

---

Step 7: Merge Complete (Merge and Cleanup)

Command: merge-complete

Purpose: Merge to main and clean up.

Actions: 1. Squash merge to main 2. Delete feature branch 3. Remove worktree 4. Update task status to completed 5. Update backlog indexes

Outputs:

• Merge confirmation
• Cleanup status
• Task completion record

Next Step: Update backlog and project status

---

Step 8: Update Backlog Epic File and Project Status

Command: Part of merge-complete (Phase 6)

Purpose: Persist progress to the source-of-truth documentation files so future sessions see accurate state.

Actions: 1. Update task status in the backlog epic file (ready → complete) 2. Recalculate epic-level progress counts 3. Unblock dependent tasks (blocked → ready) if their blockers are now complete 4. Update project status file (context/status.md) with current phase, epic progress, and recent changes 5. Commit and push documentation updates

Outputs:

• Updated epic file with accurate task statuses
• Newly unblocked tasks moved to ready
• Current project status reflecting actual progress

Why this step exists: Without it, internal tracking (.coordinator/state.json, worker progress files) diverges from the backlog and project status files. This caused 22 merged tasks to remain marked as "ready" in one real-world project.

Next Step: Workflow complete

---

Error Handling

Test Failures

• Stop at IMPL_COMPLETE checkpoint
• Must fix tests before proceeding
• Cannot skip to review

Merge Conflicts

• Stop at MERGE_READY checkpoint
• Pull latest main into worktree
• Resolve conflicts
• Push updates
• Continue to merge

Review Blocks

• Stop at REVIEWS_DONE checkpoint
• Address critical issues
• Cannot proceed with critical issues unfixed

Timing Expectations

Total: Variable based on task complexity