background: false is the default. Use foreground dispatch whenever the result determines the current answer or next action.- Use
background: true only for independent work. If this turn must consume a background result, call observe exactly once with action: "wait" and a bounded timeout before continuing; never continue independently while the result is pending.
- Otherwise end the turn and wait for the automatic
teammate-complete notification. Do not rely on SendMessage, team_msg, or hook callbacks as completion signals.
- Never silently ignore an unfinished dispatch.
Terminology: this command uses 'session' throughout. The underlying workflow file (fork.md) may use 'milestone' as a legacy alias for 'session'. Treat them as equivalent: --session maps to workflow's -m, state.json.sessions[] maps to state.json.milestones[].
--base <ref>: git ref (branch, tag, or commit hash) to fork from. Default: HEAD.
Modes (Fork / Sync), flags (--session, --base, --sync), session resolution, worktree layout, and artifact scoping are defined in workflow fork.md.
Fork and sync algorithm steps are defined in workflow fork.md.
Gates (MANDATORY, BLOCKING)
Fork mode:
GATE 1: Validation → Worktree Creation
- REQUIRED: Session resolved from
state.json.sessions[] by session_id or intent slug.
- REQUIRED: No existing active worktree for this session (E008).
- REQUIRED: Not running inside a worktree (E003).
- BLOCKED if: session not found (E006), already forked (E008), or running inside worktree (E003).
GATE 2: Worktree Creation → Artifact Copy
- REQUIRED: Git worktree created with branch (
session/{slug}).
- REQUIRED: Shared
.workflow/ files copied (project.md, config.json, specs/).
- BLOCKED if missing: worktree creation failed or shared files not copied — do not proceed to artifact scoping.
GATE 3: Artifact Copy → Completion
- REQUIRED: [@ask] user prompt confirmation before registry writes — show session scope, worktree path, and state entries to be written. User must confirm or abort.
- REQUIRED:
worktree-scope.json written with session scope (after confirmation).
- REQUIRED: Scoped
state.json written (only this session's data) (after confirmation).
- REQUIRED:
worktrees.json registry updated in main worktree (after confirmation).
- BLOCKED if missing: scope marker, scoped state, or registry update absent — worktree is unusable without these.
Sync mode:
GATE: Sync → Completion
- REQUIRED: Git merge main into worktree branch completed.
- REQUIRED: Shared artifacts re-copied.
- BLOCKED if: merge has unresolved conflicts or shared artifacts failed to copy.
| Condition |
Suggestion |
| Fork complete |
cd {wt.path}, then route step analyze through /maestro-next or the canonical receipt-chained session open -> session chain insert --command analyze --arg "<goal>" -> run next flow |
| Fork + automated |
`teammate({ agent: "general", taskType: "development", tasks: [{ prompt: "run full lifecycle for session" }], cwd: "{wt.path}" }) |
| Sync complete |
Resume work in worktree |
| Sync conflicts found |
Resolve manually, then retry |
|
|
Sync mode:
1---2name: maestro-fork-23description: "Create or sync session worktree for parallel dev Arguments: --session <session_id> [--base <ref>] [--sync]"4---56<teammate_contract>78- `background: false` is the default. Use foreground dispatch whenever the result determines the current answer or next action.9- Use `background: true` only for independent work. If this turn must consume a background result, call `observe` exactly once with `action: "wait"` and a bounded timeout before continuing; never continue independently while the result is pending.10- Otherwise end the turn and wait for the automatic `teammate-complete` notification. Do not rely on `SendMessage`, `team_msg`, or hook callbacks as completion signals.11- Never silently ignore an unfinished dispatch.1213</teammate_contract>1415<required_reading>16~/.maestro/workflows/run-mode.md17</required_reading>1819<purpose>20Create or sync a session-level git worktree for parallel development.21Supports `--sync` mode to pull latest main changes into an active worktree.22</purpose>2324<deferred_reading>25- [worktrees.json](~/.maestro/templates/worktrees.json) — read when updating registry26- [worktree-scope.json](~/.maestro/templates/worktree-scope.json) — read when writing scope marker27</deferred_reading>2829<context>30$ARGUMENTS -- session ID (or slug) and optional flags.3132Terminology: this command uses 'session' throughout. The underlying workflow file (fork.md) may use 'milestone' as a legacy alias for 'session'. Treat them as equivalent: `--session` maps to workflow's `-m`, `state.json.sessions[]` maps to `state.json.milestones[]`.3334`--base <ref>`: git ref (branch, tag, or commit hash) to fork from. Default: HEAD.3536Modes (`Fork` / `Sync`), flags (`--session`, `--base`, `--sync`), session resolution, worktree layout, and artifact scoping are defined in workflow `fork.md`.37</context>3839<execution>40Follow '~/.maestro/workflows/fork.md' completely.4142Fork and sync algorithm steps are defined in workflow `fork.md`.4344### Gates (MANDATORY, BLOCKING)4546**Fork mode:**4748**GATE 1: Validation → Worktree Creation**49- REQUIRED: Session resolved from `state.json.sessions[]` by session_id or intent slug.50- REQUIRED: No existing active worktree for this session (E008).51- REQUIRED: Not running inside a worktree (E003).52- BLOCKED if: session not found (E006), already forked (E008), or running inside worktree (E003).5354**GATE 2: Worktree Creation → Artifact Copy**55- REQUIRED: Git worktree created with branch (`session/{slug}`).56- REQUIRED: Shared `.workflow/` files copied (project.md, config.json, specs/).57- BLOCKED if missing: worktree creation failed or shared files not copied — do not proceed to artifact scoping.5859**GATE 3: Artifact Copy → Completion**60- REQUIRED: [@ask] user prompt confirmation before registry writes — show session scope, worktree path, and state entries to be written. User must confirm or abort.61- REQUIRED: `worktree-scope.json` written with session scope (after confirmation).62- REQUIRED: Scoped `state.json` written (only this session's data) (after confirmation).63- REQUIRED: `worktrees.json` registry updated in main worktree (after confirmation).64- BLOCKED if missing: scope marker, scoped state, or registry update absent — worktree is unusable without these.6566**Sync mode:**6768**GATE: Sync → Completion**69- REQUIRED: Git merge main into worktree branch completed.70- REQUIRED: Shared artifacts re-copied.71- BLOCKED if: merge has unresolved conflicts or shared artifacts failed to copy.7273</execution>7475<completion>76### Next-step routing7778| Condition | Suggestion |79|-----------|-----------|80| Fork complete | `cd {wt.path}`, then route step `analyze` through `/maestro-next` or the canonical receipt-chained `session open` -> `session chain insert --command analyze --arg "<goal>"` -> `run next` flow |81| Fork + automated | `teammate({ agent: "general", taskType: "development", tasks: [{ prompt: "run full lifecycle for session" }], cwd: "{wt.path}" }) |82| Sync complete | Resume work in worktree |83| Sync conflicts found | Resolve manually, then retry |84</completion>8586<error_codes>87| Code | Severity | Condition | Recovery |88|------|----------|-----------|----------|89| E001 | error | Project not initialized | Run maestro-init first |90| E002 | error | No roadmap found | Route step `roadmap` through `/maestro-next` or the canonical receipt-chained self-start flow |91| E003 | error | Running inside a worktree | Run from main worktree |92| E004 | error | No session ID provided | Provide `--session <session_id>` |93| E005 | error | No sessions defined in state.json | Route step `roadmap` through `/maestro-next` or the canonical receipt-chained self-start flow |94| E006 | error | Session not found in state.json.sessions[] | Check available sessions |95| E007 | error | No active worktree for session (--sync) | Check worktrees.json |96| E008 | error | Session already has active worktree | Merge or cleanup first |97</error_codes>9899<success_criteria>100Fork mode:101- [ ] Session resolved from state.json.sessions[]102- [ ] Git worktree created with branch (`session/{slug}`)103- [ ] Shared `.workflow/` files copied (project.md, config.json, specs/)104- [ ] Session artifacts copied (matched by session/milestone name from workflow)105- [ ] `worktree-scope.json` written with session scope106- [ ] Scoped `state.json` written (only this session's data)107- [ ] `worktrees.json` registry updated in main worktree108- [ ] Session lifecycle recorded in worktrees.json registry (fork_sessions entry)109- [ ] Summary displayed with next-step commands110111Sync mode:112- [ ] Git merge main into worktree branch113- [ ] Shared artifacts re-copied (project.md, config.json, specs/)114- [ ] Conflicts reported if any115</success_criteria>
catlog22