/gaia-planner

name: gaia-planner
description: Use when planning features or decomposing work into tasks from a brief

Gaia Planner

Plan creation from briefs. The planner reads a brief from the substrate DB, decomposes it into tasks defined by outcome and verification, and persists the plan back through the `gaia plan` CLI as markdown AND as one task row per task (`gaia task add`). The orchestrator owns task dispatch and execution.

The brief is authoritative intent (read this first)

The brief is the settled output of investigation and conversation between the user and the orchestrator. Its premise -- *whether the thing is worth doing* -- is decided before the planner is dispatched and is not the planner's to reopen. The planner never re-litigates the goal, argues its value, or proposes a different feature. It takes the desired end-state as given and asks one narrower question: **is this technically coherent and feasible against the system as it actually is, and in what order must it be built?**

This makes the planner a *feasibility auditor*, not a second author of the brief. Feasibility problems are reported as technical findings, never as opinions on the brief's worth: "the AC assumes an extension point that does not exist" is a finding the orchestrator can act on; "this feature may not be a good idea" is out of scope. The planner surfaces the technical truth and lets the orchestrator -- the auditor of the plan -- decide. Because the orchestrator audits the plan, the planner returns everything that audit needs: the feasibility findings, the assumptions it made where the brief was silent, the execution risks, and the rationale for the task ordering (see `reference.md`, Plan Structure) -- not just the task list.

The altitude principle

A plan defines each task by its **outcome plus how that outcome is verified** -- never by implementation nomenclature. Reference areas of the codebase loosely ("the brief CLI", "the approval module"); do not pin exact symbol names, file paths, or function signatures inside a task.

This is deliberate. Execution surfaces discoveries the planner cannot see: an approval gate fires and changes the command, byte-coding or a refactor moves a symbol, a downstream task lands a file somewhere the plan did not predict. A task that pins `hooks/modules/security/approval_grants.py:activate_db_pending_by_id` breaks the moment that symbol moves -- and worse, every downstream task that referenced the pinned name breaks with it. A task that says "the approval grant activation path" survives the move, because the executing agent resolves the specific against the live codebase.

The unit of planning is the **task with a testable outcome**, not the micro-step. This diverges on purpose from "2-5 minute steps with exact content" patterns: over-specifying the *how* at plan time transfers a guess into a contract the downstream cannot keep. Plan the *what* and the *proof*; let execution own the specifics.

DB is the source of truth

Briefs and plans live in the Gaia substrate database (`~/.gaia/gaia.db`). The planner reads briefs through `gaia brief show` and persists plan content through `gaia plan save`. Briefs and plans are **separate rows in separate tables** (`briefs`, `plans`); the `plans` row has `brief_id UNIQUE`, so there is exactly one plan per brief. There is no `plan.md` on disk and no `open_<feature>/` directory -- status is the `plans.status` column, not a directory name.

When in doubt: there is no file to read or write -- there is a CLI command to run.

When to Activate

• A brief exists in the DB and needs to become an execution plan.
• An existing plan needs revision or restructuring.

Process

Step 1: Read the brief from the DB

gaia brief show <name> --workspace=<ws> --json

`--workspace` defaults to the current workspace; pass it explicitly when the orchestrator gives you a workspace context. The JSON exposes objectives, ACs (id/description/evidence/artifact), constraints, and out-of-scope.

If the brief does not exist, return BLOCKED and tell the orchestrator to create one first via `brief-spec`. Do not search the filesystem -- the DB is authoritative.

Step 2: Survey before you decompose

Two checks come before sizing tasks. Skipping them produces a plan that re-builds what exists or specifies what cannot be built.

• **Overlap detection.** Check what already exists or is already done against

the live codebase before writing a task for it. A task that re-creates a component that ships today is waste the orchestrator will dispatch in good faith. Plan only the delta between the brief and what is built.

• **Technical feasibility.** Corroborate each intended outcome against the

actual implementation. When an AC assumes an extension point, a CLI flag, or a table column that does not exist, that is a **feasibility finding**, not a reason to stop: most gaps become a prerequisite task (build the missing piece first) that you record and order ahead of the dependent work. Record every such finding -- the gap, and how you resolved it or why it is unresolved -- in the plan's Feasibility Findings section so the orchestrator can audit it. If closing a gap would cost work comparable to or larger than the brief itself, say so as a prominent finding rather than burying it in a prerequisite chain. Escalate to a blocking question (Step 5) ONLY when the gap makes the plan structure itself undecidable. Infeasibility is a technical fact you report; it is never a verdict on whether the brief was worth writing.

Step 3: Decompose into tasks

For sizing rules, AC citation, agent routing, and the plan structure, see `reference.md`. The contract per task:

• **Defined by outcome + verification**, at task altitude (see the altitude

principle): a single unit of change with a testable outcome and the evidence that proves it. Not verbose (one task covering five outcomes loses the agent), not micro-impossible (a "task"