Goal Tree Workflow

Orchestrates multi-task projects as hierarchical goal trees. Decomposes a user's objective into goals and tasks, dispatches work via workspace sessions, and synthesizes results into PRs.

Hard Rules

These apply in ALL modes (coordinator-backed or bootstrap). Do not violate these regardless of context pressure. The three principles are generative — derive behavior from them rather than memorizing specific restrictions.

Isolation

Work happens in worktrees via scripts. Source repos and shared state are never modified directly.

• Source repos (~/src/github/) stay on main. Create a worktree via create-node-workspace.sh before editing any repo file. Repo paths in project CLAUDE.md are SOURCE locations, not working directories.
• Use scripted paths for infrastructure: create-node-workspace.sh for workspaces, create-tmuxp-session.sh for sessions. No raw git worktree add or tmux new-session.
• Batch work into scripts. Each major phase should be one script execution, not a long chain of individual shell commands.

Phase Gates

Think → confirm → act. Each phase has appropriate tools. Do not bleed across phase boundaries.

• Strategic phases are text-only. During OODA orient/propose, next-cycle conversation, spec refinement, or any discussion about what to do: no tool calls, no file edits, no implementation. If the user mentions a tactical item during strategy, capture it as a proposed node — do not act on it. Transition to execution only after direction is confirmed.
• Conversation is incremental. During strategic phases, advance through dialogue — don't accumulate context into summary structures. If you're about to present a "summary so far" or "proposed frame," ask: could I advance with one question instead? Summaries close; questions advance. Prefer advancing.
• The tree is the only path to execution. When direction is confirmed, the next step is always to register nodes in the coordinator — never to start implementing directly. New work → proposed nodes → coordinator registration → dispatch pipeline. There is no shortcut from conversation to implementation that bypasses the tree.
• Conversation before decomposition, decomposition before execution. Confirm the spec before decomposing. Get tree approval before creating files, issues, or directories.
• Plan before implementing. Every task gets planning-workflow or a PLAN.md before code changes. Do not jump from reading code to writing code.
• Recognize dispatch signals. When the operator says "dispatch a workspace", "create a workspace for this", or similar during conversation, load operations/discuss-dispatch.md and follow its lifecycle. After workspace creation, the main thread writes ONLY to DESIGN.md — no implementation.

Flow

Ready work dispatches immediately, in parallel. Minimize blocking. Be decisive during execution.

• Independent nodes dispatch as parallel workspace sessions. Sequential dispatch of independent nodes is a protocol violation.
• Dispatch ready nodes immediately. Conversation about node B does NOT block dispatching node A if A's spec is clear and dependencies are met.
• During execution, propose and act — checkpoints belong at phase boundaries (spec confirmation, tree approval, dispatch rounds), not after every thought. State assumptions and proceed; the user will redirect if needed.
• Auto-continue the OODA loop. When ready nodes are exhausted in an open-ended project, immediately run operations/next-cycle.md. Do not stop and ask "what next?"
• Risk ordering is a tie-break, not a gate. When several ready nodes could dispatch in the same round and their relative order is a free choice, list/dispatch the reversible or low-blast-radius ones ahead of irreversible or high-blast-radius ones (destructive infra changes, state migrations, anything that can't be cleanly rolled back via git). This only orders nodes within the round — every ready node still dispatches immediately per the rule above; it is never a reason to hold one back pending another's review.

Layer Model

The goal tree encodes layer ownership via structure. See references/layer-model.md for the full reference.

Key rule: leaf-vs-non-leaf determines the layer, not absolute depth. Depth encodes L1 decomposition granularity.

• L2 owns the objective, evaluates L1 cycle outcomes
• L1 owns decomposition and dispatch, evaluates L0 task outputs (spec-driven evaluation)
• L0 owns implementation within a workspace session, follows task-workflow

No coordinator schema change is needed — layer is derived from parent_id chain and children presence.

Core Concepts

Goal Tree: Hierarchical decomposition of an objective into goals (decomposable) and tasks (implementable leaves). Persisted via the coordinator API.

Coordinator as backend: The coord CLI (scripts/coord) is the interface. Reads and writes go through it. Env: COORDINATOR_URL (default http://localhost:4000), COORDINATOR_TOKEN (required).

Bootstrap mode: When the coordinator is unavailable OR the host opts into the bootstrap backend (GOAL_TREE_BACKEND=work), use GOAL.md + TodoWrite for task tracking. All other conventions still apply — worktrees, scripted sessions, parallel dispatch via workspace sessions. Once the coordinator is running (coordinator-backed hosts), register the remaining tree and switch to the normal loop.

Environment detection: Operations should check the environment before selecting a backend. Use scripts/detect-env.sh which outputs "work" (bootstrap → GOAL.md) or "personal" (coordinator). See lib/env-detection.md for details.

Worktree isolation: Every task gets a node workspace with repo worktrees on a per-node branch. Source repos are never modified directly.

OODA loop: Sessions follow Observe → Orient → Decide → Act. Resume and status operations use OODA preambles — narrative summaries of capability/performance/gaps rather than raw data dumps. During Quick Observe (next-cycle.md), check $PROJECT_DIR/.active-nodes for dispatched nodes awaiting completion — look for merged PRs, inbox messages, or dead tmux sessions. See operations/discuss-dispatch.md step 5 for detection logic.

Commands

Legacy aliases: /start-project, /resume-project, /finish-project, /close-project still work.

Execution Flow

Start: Load operations/start-project.md — conversation → spec confirmation → decomposition → approval → coordinator registration (or bootstrap) → execution.

Resume: Load operations/resume-project.md — OODA preamble (observe state, orient to strategy) → conversation → execute-tree loop.

Execute (coordinator mode): Load operations/execute-tree.md — loop: select ready nodes → dispatch decisions → create workspace sessions → monitor via tmux → collect results → update coordinator → repeat.

Execute (bootstrap mode): TodoWrite tracks tasks. The dispatch pipeline still applies:

1. Identify independent tasks (no unmet dependencies)
2. Create node workspaces via scripts/create-node-workspace.sh
3. Dispatch independent tasks as parallel workspace sessions (use operations/dispatch-node.md for workspace creation and tmux startup)
4. Monitor sessions, commit results, advance to next batch
5. Once coordinator is available, register tree and switch modes

Bootstrap mode is NOT an excuse for serial dispatch. Use parallel workspace sessions even without the coordinator.

Dispatch strategy (per-node):

• Clear spec (any complexity) → Workspace session
• Needs conversation first → Discuss-dispatch (conversation → workspace session)
• Needs human judgment → Escalate

Operations Reference

Load on-demand as needed:

References

Scripts

Called by operations — use these instead of raw commands:

Prefer scripts over pipelines: Before composing jq/python pipelines, check if a script above already provides the data. See docs/reference/command-simplification.md for common patterns and alternatives.