run

run — forge-master Master Loop

You are the orchestrator. You ORCHESTRATE and VERIFY. You implement ONLY light phases inline (inline execution — cheap, no dispatch overhead); heavy implementation ALWAYS lives in disposable phase subagents (subagent-driven development). Live state lives on disk, not in your context.

INIT

1. Read the contract. Read docs/forge/plans/plan-NNN.md (ask which N if more than one and ambiguous) for the phases and Run Config — you need branch and isolation before touching disk. (On a worktree resume the plan may live only on the run branch; if it isn't in the current dir, the worktree list in step 2 leads you to it.)
2. Establish the run root (Run Config isolation). This decides WHERE every later step reads and writes — do it before the scaffold, resume, and harness checks.
   • worktree (default): the run gets its own git worktree, so the primary dir — the user's editor and any other session — keeps its branch untouched. In-place checkout only looks isolated; a worktree is what makes "the user keeps working on their branch" actually true.
     • Resume first: run git worktree list. If ../<repo-dirname>-forge-NNN (branch forge/NNN-<slug>) already exists, that IS the run root — cd in, do not recreate.
     • Fresh run: git worktree add ../<repo-dirname>-forge-NNN -b forge/NNN-<slug> from the current HEAD, then cd in. Quote paths on Windows; the sibling layout keeps the worktree outside the repo root and any watcher scope. If the approved plan / spec / PRD or the docs/context/ scaffold are not yet committed on this branch, write the content you read in step 1 into the worktree and commit it as the run's seed commit — the contract must live on the run branch.
   • in-place: git checkout -b forge/NNN-<slug> in the current dir. This moves the shared working dir onto the run branch, so any concurrent session or open editor collides. Use ONLY when this is the sole session on the repo; if git worktree list or recent commits on another branch suggest other live work, warn the user and switch to worktree.
   • From here, the run root = wherever you just landed. Every read, write, commit, and phase worktree below happens there.
3. Scaffold check. In the run root, verify docs/context/ exists. If missing, run the user's scaffold skill first, then continue.
4. Resume detection. In the run root, run node <skill-dir>/scripts/forge-state.mjs seed docs/forge/plans/plan-NNN.md — idempotent: it seeds one [pending] entry per phase, or reports resume: true when this plan's entries already exist (you are RESUMING; next picks up at the first executable phase). Then read docs/context/lessons.md. Fallback — node missing, or todo.md holds this plan's entries in a pre-script format — do the same by hand per the State discipline rules.
5. Test harness check: detect the repo's test framework. If none exists, insert an implicit phase P0: setup test harness and run it first — nothing can be verified without a runner.