Pipeline File

A pipeline-file is the base YAML document that defines a pipeline. It carries a header (name, description, optional overrides) and a body that lists the ordered stages of the pipeline.

Pipeline-files live at:

Source	Path
project	`<cwd>/.goga/pipelines/<name>.yml`
user	`~/.goga/pipelines/<name>.yml`

Only top-level *.yml files are scanned. Subdirectories are ignored and .yaml files are excluded. On name conflict, the project source wins.

Document shape

Every pipeline-file is a two-segment YAML document separated by a --- line:

<header>
---
<body>

The header is a YAML mapping with name, description, and an optional agents block (see Agents).
The body is either a YAML list (phases format) or a YAML dict (stages format).

A file without the --- separator is rejected at parse time with a structural error.

name: GogaFeature
description: "Feature implementation"
agents:        # optional block — see "Agents"
  planning: |
    Inline prompt that replaces the shipped default for the planning agent.

Field	Type	Required	Description
`name`	string	yes	Pipeline identifier, must be non-empty
`description`	string	yes	Short human-readable purpose
`agents`	map	no	Inline overrides for the four agent prompts. See Agents.

A header missing name or description is rejected with a structural error.

Body formats

The body can be authored in one of two shapes — both are first-class.

Phases format (list)

A YAML list of step mappings. Each item is keyed by name; depends_on is auto-generated by list position — the first step has no dependency, each subsequent step depends on the previous one.

- name: propose
  title: "Create the task from a user propose"
  interactive: true
  prompt: |
    Save the task file as `<git branch --show-current>.md`
  skills:
    - goga-propose

- name: task-review
  title: "Review of the created task"
  interactive: true
  prompt: |
    Review the task `<git branch --show-current>.md`
  skills:
    - goga-review-task

When a workflow applies loop: N to a phases stage, the expanded copies chain naturally via list position — the first copy inherits the original position, subsequent copies depend on their predecessor, and the next original step depends on the last expanded copy.

Stages format (dict)

A YAML mapping keyed by step id. Each value carries title and an optional explicit depends_on plus any extra fields. depends_on is passed through as-is, except that workflow loop expansion rewrites external references to a base name to the last expanded id.

propose:
  title: "Create the task from a user propose"
  interactive: true
  prompt: |
    Save the task file as `<git branch --show-current>.md`
  skills:
    - goga-propose

task-review:
  title: "Review of the created task"
  depends_on: [propose]
  interactive: true
  prompt: |
    Review the task `<git branch --show-current>.md`
  skills:
    - goga-review-task

Any other body shape (scalar, no separator, or an already-compiled flow-file shape) raises unsupported body format.

Stage fields

Both body formats accept the same set of fields per stage. The compiler preserves unknown fields verbatim — only the canonical fields below have assigned semantics:

Field	Type	Default	Description
`name`	string	— (required, phases only)	Stage identifier. In phases format the item's `name`; in stages the map key.
`title`	string	— (optional, recommended)	Display label emitted as the compiled stage's `name`.
`interactive`	bool	false	Whether the stage prompts for user input.
`prompt`	string	—	Stage-level prompt text; emitted as the compiled `prompt` field.
`skills`	list of strings	—	Skills the agent must apply at this stage.
`agents`	list of strings	autonomous mode when absent	Agent roles assigned to the stage. See Agents.
`depends_on`	list of strings	auto (phases) / none (stages)	Stage dependencies.

Body step `title` field

The body step carries a title field that becomes the compiled stage's display name. Use a short human-readable phrase — it is what end users see in stage listings.

Shipped pipelines

Goga ships three ready-to-use pipelines — feature, bugfix, patch — that cover the most common authoring lifecycles. See Shipped Pipelines for the per-pipeline walkthrough and how to use them as templates.

Agents

The pipeline-file carries agents in two distinct places, and they serve different purposes. A third agent concept exists in workflow-files and is intentionally different — see the comparison at the end of this section.

Where	Field	Type	Purpose
Header	`agents`	map	Replace shipped default prompts for the four agent roles.
Body stage	`agents`	list of strings	Choose which agent roles run the stage (its mode).
Workflow-file stage	`agent`	string	Choose which CLI agent runs the stage (e.g. codex, claude).

The rest of this section covers the first two — both live in the pipeline-file. The third is documented in Workflows.

The four agent roles

When a stage runs in coordinated mode (see below), the roles in its agents list execute in sequence — each role's output becomes the next role's input. Goga ships a default prompt for each of the four roles:

Role	Responsibility
`planning`	Read the task, decompose it into a verifiable plan, hand off. Does not execute the work.
`implementation`	Execute the plan task-by-task, including any required research, code, or analysis. Produces the deliverable.
`review`	Verify the deliverable against the plan and acceptance criteria. Approves or requests changes.
`summary`	Produce the final report for the run, covering every stage.

What each role does

planning decomposes the incoming task into an actionable plan with three sections: a numbered task list, the assumptions made along the way, and explicit acceptance criteria the work must meet. It does not perform the work itself — it hands the plan to the next role. It makes decisions autonomously rather than asking questions, and documents every non-obvious choice under assumptions.

implementation executes the plan top to bottom. For each task it decides the nature of the work — research, analysis, code, discussion — and acts accordingly. It runs the acceptance criteria checks before declaring the stage complete, and produces an honest report (not a false "done") when a criterion cannot be met.

review audits the deliverable against the plan: every task actually done, every acceptance criterion met, the result matching the intent of the prompt, edge cases handled. It returns a single verdict — approved or needs_changes — with a list of critical blockers and a list of non-blocking suggestions.

summary reads the logs of every stage in the run and produces a final report: a one-paragraph overview, a per-stage breakdown of what happened, and any open issues carried over from review.

Body stage `agents` — choosing the stage mode

The per-stage agents field is a list of role names. A stage runs in one of two modes depending on whether the list is non-empty:

Autonomous mode — agents is absent, null, or an empty list []. The stage receives its task and decides for itself how to organize the work: which steps to take, in which order, and when the result is complete. Use this for stages that should not be decomposed ahead of time — research, free-form authoring, exploratory analysis.
Coordinated mode — agents is a non-empty list (e.g. [planning, implementation]). The listed roles run in sequence and organize the work for the incoming task: the planning agent decomposes the task into a verifiable plan, the implementation agent executes that plan, the review agent validates the result, and the summary agent produces the final report. Use this for stages where you want predictable, reviewable execution — feature builds, bug fixes, anything with acceptance criteria.

The two modes are mutually exclusive per stage — there is no hybrid. Authoring even a single-element list (agents: [planning]) is enough to switch the stage into coordinated mode; an authored non-empty value always wins.

Choosing between modes

Leave agents out for stages whose work cannot be planned ahead of time — exploratory research, free-form authoring, asking a question.
Author agents for stages whose work is structurally predictable — building a feature, fixing a bug, anything where you want a plan, execution, review, and a final report.

Examples

Autonomous mode — no agents field. The stage receives the prompt and organizes the work itself:

- name: research
  title: "Explore the codebase for prior art"
  prompt: |
    Find any existing implementations of feature flagging
    in this codebase and summarize what you find.

Coordinated mode — planning and implementation roles assigned. The stage decomposes the task into a plan, then executes it:

- name: ship
  title: "Build and ship artifacts"
  agents:
    - planning
    - implementation
  prompt: |
    Build the artifacts for the current branch and ship them.

Full lifecycle — all four roles. Useful for stages where you want end-to-end verification:

- name: deliver
  title: "Deliver the feature end-to-end"
  agents:
    - planning
    - implementation
    - review
    - summary
  prompt: |
    Implement the feature described in the task file, verify
    it meets the acceptance criteria, and produce a report.

Header `agents` — overriding the default prompts

The header-level agents block lets you replace the shipped default prompt for any of the four roles with an inline prompt of your own. An override fully replaces the default — it does not merge with it. When the block is absent or empty, the four shipped defaults are used unchanged.

The block accepts exactly four keys — one per role:

Key	Replaces shipped default prompt for role
`planning`	`planning`
`implementation`	`implementation`
`review`	`review`
`summary`	`summary`

Example:

name: GogaFeature
description: "Feature implementation"
agents:
  planning: |
    You are the planning agent for this feature pipeline.
    Break the work into reviewable steps.
  review: |
    Review each change against the feature's acceptance criteria.
---

Rules:

Only those four keys are valid. An unknown key is rejected at compile time with unknown agent in header.agents: <key>; valid keys: planning, implementation, review, summary.
Each value must be a string. A non-string value raises non-str value in header.agents.<key>.
An absent agents block and an empty agents: mapping are both treated identically — no overrides, the four shipped defaults are used unchanged.
Overrides are a pipeline-file-side artifact. They are not carried into the compiled flow-file — they are materialized into a separate prompts directory at run time.

How header and stage `agents` relate

The two pipeline-file agents declarations compose without collision:

The per-stage agents list decides which roles execute and in which order — i.e. the stage's mode.
The header-level agents map decides what each role's prompt says when it runs.

A stage running in coordinated mode picks up the header-level overrides for whatever roles appear in its list. If no override is supplied for a role, that role uses its shipped default. The header overrides do not add roles to a stage — they only change the prompt of roles already listed in the stage's agents field. A stage in autonomous mode (no agents field) is unaffected by header overrides.

Pipeline-file `agents` vs workflow-file `agent`

Aspect	Pipeline-file header `agents`	Pipeline-file stage `agents`	Workflow-file stage `agent`
Scope	Pipeline-wide default	Single stage	Single stage (overrides at run time)
Value	Map of role → prompt	List of role names	Single CLI agent name
Controls	The prompt text of each role	Which roles run, in which order (mode)	Which CLI binary runs the stage
Examples	`{planning: "...", review: "..."}`	`[planning, implementation]`	`codex`, `claude`, `opencode`

Use pipeline-file declarations for the stable structure of a pipeline (its roles and their prompts). Use workflow-file agent for per-project variation — running the same pipeline on different CLI agents without forking the pipeline-file. See Workflows for the full workflow-agent semantics.

Errors

Condition	Exception
`---` separator missing	`missing body separator`
Header missing `name` or `description`	`header missing name/description`
Unknown key in header `agents` block	`unknown agent in header.agents: <key>; valid keys: planning, implementation, review, summary`
Non-string value in header `agents.<key>`	`non-str value in header.agents.<key>`
Body shape is neither list nor dict	`unsupported body format`
Body has zero steps	`empty body`