/gaia plan

Plan a complex feature by decomposing it into parallel workstreams with frozen interface contracts. /gaia plan does not implement anything. It produces a plan directory, then hands you a single copy-paste prompt to launch a fresh orchestrator session that executes the plan.

When to use it

Reach for /gaia plan when the work spans multiple files or modules, has identifiable parallel slices (UI plus service layer plus tests, or backend plus frontend plus migration), or benefits from isolating each slice in its own subagent context.

For one-line bug fixes or single-file edits, skip the planning ceremony and just edit.

For feature work that has not been clarified yet, run /gaia spec first. It chains into /gaia plan after save.

How to invoke

/gaia plan a feature description in plain English

Or, with a SPEC reference (typically passed automatically by /gaia spec):

/gaia plan SPEC-005: rework auth, see .gaia/local/specs/SPEC-005.md

If you invoke /gaia plan with no description, it asks for one before continuing.

What gets produced

/gaia plan writes a plan directory at:

.gaia/local/plans/<kebab-slug>/

The slug derives from the description. When invoked from a SPEC, the slug is prefixed with the SPEC id (e.g. spec-005-cards-layout) so plan-to-SPEC discovery is a one-line ls .gaia/local/plans/ | grep ^spec-005-. Slug collisions append -2, -3, and so on, so parallel invocations coexist without overwriting each other.

Inside the directory:

File	Purpose
`README.md`	Task graph: phase order, which tasks run in parallel within each phase, and the frozen interface contracts shared across tasks. References the source SPEC if there was one.
`ORCHESTRATOR.md`	Runbook for the orchestrator session that executes the plan. Branch policy, phase order with quality gates, sub-agent prompt templates, pre-merge audit obligation, git flow, stop conditions.
`KICKOFF.md`	The exact prompt a fresh Claude Code session reads to start orchestrating. Self-contained, no assumed context.
`task-<name>.md`	One per parallel workstream. Self-contained for a fresh-context sub-agent. Includes interface contracts, files to touch (with line-range hints), acceptance criteria, and dependencies on other tasks.
`SUMMARY.md`	Created and maintained by the orchestrator during execution. Append-only ledger of phase commits and sub-agent findings.

The flow

Description capture. If $ARGUMENTS is empty, the skill asks. If a SPEC reference is detected, the SPEC itself becomes the source of truth and the dispatch summary is just a label.
Model check. If the current session is not on Opus, the skill offers to spawn the planning agent on Opus 4.7. Plans benefit from the higher-capacity model.
Plan directory resolution. Slug is derived (or seeded from the SPEC id), suffixed on collision, then created under .gaia/local/plans/.
Planner dispatch. The skill spawns a general-purpose Agent restricted to writing inside the plan directory only. The planner reads wiki/concepts/Task Orchestration.md for the orchestration pattern, then writes the plan files directly to disk.
Verification. The skill confirms README.md, ORCHESTRATOR.md, KICKOFF.md, and at least one task-*.md exist. If anything is missing, the failure surfaces; no silent retry.
Hand-off. The skill prints the kickoff prompt as a fenced code block and tries to copy it to the system clipboard via pbcopy, wl-copy, xclip, xsel, clip.exe, or clip (whichever is available). The trailing line says whether the copy succeeded.

The kickoff prompt looks exactly like:

Read /abs/path/.gaia/local/plans/<slug>/KICKOFF.md and execute it.

Paste it into a fresh Claude Code session, started cold, to run the plan. The orchestrator’s behavior lives entirely in KICKOFF.md.

Orchestrator vs sub-agents

The orchestrator owns coordination. It is spawned in a fresh context after you paste the kickoff prompt. It commits, pushes, opens the PR, runs quality gates between phases, dispatches sub-agents, and never edits source files itself.

Sub-agents own implementation. The orchestrator dispatches one per task per phase with a fresh-context prompt. Each sub-agent edits files, then returns a structured summary that ends with a ## Notes for orchestrator section (findings, deviations from plan, follow-ups for after merge). Sub-agents never commit, push, or touch git.

The orchestrator merges sub-agent notes into SUMMARY.md after every phase, so context survives compression.

Pre-merge audit

Before any gh pr merge invocation, the orchestrator spawns the code-review-audit agent against the current branch. If the audit reports critical or unresolved important issues, the orchestrator stops and surfaces them. A clean pass writes a marker that a deny-hook reads to gate gh pr merge. The orchestrator does not wait for the deny-hook to fire; it spawns the agent proactively.

Branch policy

If the orchestrator starts on main, it asks how to isolate the work: a feature branch in place (recommended) or a linked git worktree (experimental). On any other branch, it assumes the current branch is the work branch and proceeds.

Stop conditions

The orchestrator stops on any sub-agent failure or quality-gate failure. It surfaces the failure, appends it to SUMMARY.md under a (HALTED) block, and waits for human direction. It does not “fix and continue.”

Quality gates between phases run pnpm typecheck && pnpm lint. A non-zero exit halts the run before the next phase dispatches.

Final summary and self-cleanup

After all implementation phases pass and the final commit is pushed, the orchestrator reads SUMMARY.md and prints a brief summary to the user: phases completed, sub-agents run, files touched, commits pushed (count plus short SHAs), PR URL, quality-gate status, and the highest-signal findings or deviations or follow-ups drawn from the ledger.

After the user confirms the PR is ready to merge, the orchestrator deletes its own plan folder. If .gaia/local/plans/ is gitignored (the GAIA default), the deletion is invisible to git and skipped from commit. Otherwise, the deletion lands as the final commit on the PR.

Worktree mode (experimental)

If the orchestrator chose worktree mode at branch policy, the post-merge phase confirms the merge via gh pr view <N> --json state, then calls ExitWorktree({action: "remove", discard_changes: true}). The merged-state confirmation is the primary signal that the work is preserved; discard_changes: true is correct because squash-merge produces unreachable commits on the worktree branch.

If the orchestrator was itself dispatched into an isolated subagent context, it cannot call ExitWorktree directly. It instead emits a copy-paste continuation prompt naming the absolute worktree path and the merged-state details, then stops. The user pastes that prompt into a fresh top-level session to complete the cleanup.

/gaia spec is the upstream of /gaia plan. The chain-trigger after spec save dispatches /gaia plan automatically when accepted.