M2 complete, merge back

Maestro-Flow supports milestone-level parallel development based on git worktree. When a milestone is complete (even with lingering bugs), you can fork a worktree for the next milestone, develop on an independent branch, and merge back when finished.

Core Concepts

• One milestone = one worktree (phase-level parallelism within a milestone is not supported)
• Phases within a worktree still execute sequentially (analyze -> plan -> execute -> verify -> transition)
• .workflow/ is gitignored; it is explicitly copied into the worktree during fork

Main worktree (master)              Worktree (.worktrees/m2-production/)
├── .workflow/                      ├── .workflow/
│   ├── state.json                  │   ├── state.json (scoped)
│   ├── worktrees.json (registry)   │   ├── worktree-scope.json (marker)
│   └── phases/                     │   ├── roadmap.md (read-only copy)
│       ├── 01-auth/ ✅             │   └── phases/
│       ├── 02-kanban/ ✅           │       ├── 03-realtime/ (owned)
│       ├── 03-realtime/ [forked]   │       └── 04-billing/ (owned)
│       └── 04-billing/ [forked]    │
│                                   │   Execute normally here:
│   Fix M1 bugs on main             │   /maestro "phase 3"
│                                   │   (coordinator dispatches
│                                   │    analyze → plan → execute)

Command Quick Reference

Use Cases

Scenario 1: Milestone completed with bugs — start next without waiting

/maestro-session-seal                # M1 complete but has bugs
/maestro-fork -m 2                   # Fork M2 worktree

# Terminal A: Fix M1 bugs on main
cd /project

# Terminal B: Advance M2 in worktree
cd .worktrees/m2-production/
/maestro "phase 3"   # coordinator runs analyze → plan → execute

# M2 complete, merge back
/maestro-merge -m 2

Scenario 2: Long-lived worktree needs main fixes synced

/maestro-fork -m 2 --sync
# → git merge main (source sync) + re-copy project.md, roadmap.md, specs/

Scenario 3: Automate worktree development with delegate

/maestro-fork -m 2
maestro delegate "run full lifecycle for all phases" \
  --cd .worktrees/m2-production/ --mode write

Detailed Flows

Fork: Create Worktree

/maestro-fork -m 2

1. Validate: Project initialized, roadmap exists, not inside a worktree, M2 not already forked
2. Parse milestone: Read M2 info from state.json
3. Create worktree: git worktree add -b milestone/production .worktrees/m2-production HEAD
4. Copy .workflow/: Shared files (read-only) + Milestone phase directories
5. Write markers: worktree-scope.json (scope) + scoped state.json
6. Update main: worktrees.json registry + M2 marked "forked"

=== FORK COMPLETE ===
Session:    fork-20260418T143022
Base:       HEAD (abc1234)
Milestone:  M2 — Production
Branch:     milestone/production
Path:       .worktrees/m2-production
Phases:     3, 4

Sync: Synchronize Worktree

/maestro-fork -m 2 --sync

1. Find M2's worktree from worktrees.json
2. git merge main (source sync)
3. Re-copy shared files (artifact sync)
4. Report conflicts

Recommended timing: Main has bug fixes, shared files updated, periodic sync for long-lived worktrees.

Merge: Merge Worktree

/maestro-merge -m 2

Phase 1 — Git Merge: Registry check → validate completion → pre-merge → git merge --no-ff

Phase 2 — Artifact Sync (after Phase 1 succeeds): Copy phases back → patch state.json → update roadmap.md → cleanup worktree

Conflict handling:

git add <resolved-files>
git merge --continue
/maestro-merge --continue    # Continue Phase 2

Flags:

Scope Protection Mechanisms

Inside a worktree, new artifacts auto-belong to the milestone in worktree-scope.json. Modifying other milestones' artifacts is rejected.

Global Command Blocking

Dashboard Integration

maestro session status displays worktree status:

┌─────────────────────────────────────────┐
│ ACTIVE WORKTREES                        │
├─────────────────────────────────────────┤
│ M2 (Production) | milestone/production  │
│   Path: .worktrees/m2-production        │
│                                         │
│ Sync:  /maestro-fork -m 2 --sync        │
│ Merge: /maestro-merge -m 2              │
└─────────────────────────────────────────┘

┌─────────────────────────────────────────┐
│ WORKTREE MODE                           │
├─────────────────────────────────────────┤
│ Milestone: M2 (Production)             │
│ Branch:    milestone/production          │
│ Phases:    3, 4                          │
│ Main:      /path/to/project              │
└─────────────────────────────────────────┘

File Structure

Important Notes

1. Do not manually modify worktree-scope.json
2. Do not directly modify main's .workflow/ from within a worktree
3. Sync regularly to reduce conflicts
4. Ensure worktree is clean before merge (all changes committed)
5. One milestone can only have one worktree