Copilot Flow

# Automated Feature Development Flow

Orchestrate the full feature development lifecycle: design → review → implement → test → check → PR → review fix. Pauses at key checkpoints for human confirmation. Uses `flow.md` to persist state for resumability across model switches or interruptions.

## Input

$ARGUMENTS = Feature name and requirements description

**Options (appended to $ARGUMENTS):**

- `--from {phase}` — Resume from a specific phase: `design`, `implement`, or `pr`. Defaults to auto-detect from `flow.md`.
- `--skip-design` — Skip design phase entirely (for small changes).

## Flow State File

At startup, check for `docs/specs/{feature}/flow.md`:
- **If it exists**: read current `phase` and `step`, resume from there (unless `--from` is explicitly provided)
- **If it does not exist**: create it and start from the beginning

Update `flow.md` after every completed step:

```markdown
## Flow State

phase: {design|implement|pr|done}
step: {current step name}
review_round: {N}/{max}
last_action: {action description}
next_action: {what to do next}

## Log
- {timestamp} {action}: {result}

Phases

Phase 1: Design (skipped if --skip-design)

0. Branch check: if on main, create feature branch via /copilot-branch logic
   → Update flow.md: phase=design, step=branch

1. Execute /copilot-design logic
   → Generate docs/specs/{feature}/design.md + review.md
   → Update flow.md: step=design-created

2. Call external Agent (per CLAUDE.md AI Role Assignment) to review the design:
   → Agent reads design.md + review.md + CLAUDE.md
   → Agent appends review findings to review.md
   → Update flow.md: step=review-round-N

3. Read review.md
   → If blocking issues: update design.md, go to step 2
   → If no blocking issues: Agent appends DESIGN APPROVED

4. Loop until DESIGN APPROVED or 3 rounds reached
   → If 3 rounds exhausted with unresolved blocking issues:
      Update flow.md: step=blocked-design-review
      STOP and report: "Design review did not converge after 3 rounds. Human escalation needed."

⏸ CHECKPOINT: Display design summary and review history.
   Update flow.md: phase=design, step=checkpoint-passed
   Ask: "Design approved. Proceed to implementation? [Y/n]"
   → On reject: stop and report current state

Phase 2: Implement (entry point for --from implement)

0. Branch check: if on main, create feature branch via /copilot-branch logic

1. Execute /copilot-dev logic
   → Implement code according to design.md
   → Check off task items in design.md
   → Log decisions to decisions.md
   → git add + git commit (do NOT push)
   → Update flow.md: step=dev-done

2. Execute /copilot-ut logic
   → Generate tests for the implemented code
   → git add + git commit (do NOT push)
   → Update flow.md: step=ut-done

3. Execute /copilot-check logic
   → Run typecheck + lint + format
   → If failures: attempt auto-fix, then re-check
   → If type errors remain: Update flow.md: step=blocked-typecheck
      STOP and report for manual resolution
   → Update flow.md: step=check-done

4. Execute /copilot-review-code logic
   → Local code review on the diff vs main
   → Appends Round 1 to docs/specs/{feature}/review-code.md
   → Update flow.md: step=review-round-1, review_round=1/3

5. If /copilot-review-code found blocking issues:
   a. Execute /copilot-dev "fix review: {feature}"
      → Reads review-code.md latest round for blocking issues
      → Fix issues + git commit (do NOT push)
   b. Re-run /copilot-check
   c. Re-run /copilot-review-code (auto-detects --last mode)
      → Appends Round N+1 to review-code.md
   d. Update flow.md: step=review-round-N, review_round=N/3
   e. Loop until CODE REVIEW APPROVED marker appears (max 3 rounds)
   f. If 3 rounds exhausted: Update flow.md: step=blocked-code-review
      STOP and report for human decision

⏸ CHECKPOINT: Display implementation summary, test results, review results.
   Update flow.md: phase=implement, step=checkpoint-passed
   Ask: "Implementation complete, checks and review pass. Proceed to PR? [Y/n]"
   → On reject: stop and report current state

Phase 3: PR & Review (entry point for --from pr)

1. Execute /copilot-pr logic
   → Quality gate (check) + create Draft PR
   → Update flow.md: phase=pr, step=pr-created

2. Report: "PR created. Trigger CI review with @claude review or @codex review in the PR."

⏸ CHECKPOINT: Wait for user to confirm CI review is complete.
   Ask: "Has CI review completed? [Y/n]"

3. Execute /copilot-review-fetch logic
   → Fetch and append Round N to docs/specs/{feature}/review-pr.md
   → Update flow.md: step=review-fetched, review_round=N/3

4. If blocking issues exist in review-pr.md latest round:
   a. Execute /copilot-review-fix logic
      → Reads review-pr.md current round blocking only
      → Appends fix report to review-pr.md
   b. Report: "Fixes pushed. Trigger another review round."
   c. Go to step 2 (max 3 rounds)
   d. If 3 rounds exhausted: Update flow.md: step=blocked-pr-review
      STOP and report for human decision

5. If PR REVIEW APPROVED marker present in review-pr.md:
   Update flow.md: phase=done, step=ready-to-merge
   Report: "PR approved. Ready to merge."

Flow Diagram

/copilot-flow "auth module with OAuth"

  ┌─ Phase 1: Design ──────────────────────────┐
  │ Auto: create design.md                       │
  │ Auto: Agent reviews ←→ Claude updates        │
  │ Auto: loop until APPROVED (max 3 rounds)     │
  │ ⏸ Pause: confirm design before implementing  │
  └──────────────────────────────────────────────┘
                       ↓ user confirms
  ┌─ Phase 2: Implement ────────────────────────┐
  │ Auto: implement code + commit (no push)      │
  │ Auto: generate tests + commit (no push)      │
  │ Auto: run quality checks + auto-fix          │
  │ Auto: review → fix → commit loop (3x)        │
  │      (all tracked in review-code.md)         │
  │ ⏸ Pause: confirm code before opening PR      │
  └─────────────────────────────────────────