Skip to content

Pipelines

A pipeline is a named YAML file that describes a sequence of stages an AI agent walks through to deliver a piece of work — propose, review, brainstorm, apply, design, plan, build, change, accept. Pipelines are flat *.yml files resolved from two directories and executed stage-by-stage inside the goga container.

Pipelines ship six ready-to-use definitions:

Pipeline Purpose
development End-to-end development lifecycle: architecture, design, plan, accept
refinement Product definition and task refinement: define, discover, propose
bugfix Root-cause analysis and resolution for a defect
patch Refactoring or minimal change with a formalized plan
review Scoped review of code, contracts, docs, then lint/format/tests
sync Sync specifications and tests with the implementation

The shipped pipelines are described in detail in Shipped Pipelines.

This section documents the functional model of pipelines — what a pipeline-file is, what a workflow is, and how the two relate. For invocation flags, exit codes, and Docker mechanics, see the goga pipeline CLI reference.

Pipeline files vs workflows

The pipelines layer is split into two authoring surfaces:

  • Pipeline File — the base document. Defines the pipeline name, description, optional per-stage agent prompt overrides, and the ordered list of stages. Authored once per pipeline; lives in .goga/pipelines/<name>.yml (project) or ~/.goga/pipelines/<name>.yml (user).
  • Workflows — an optional layering document that extends a compiled pipeline at run time with a top-level prompt, per-stage agent / prompt overrides, loop expansion, stage skipping via skip, manual launch via manual, and new stages declared via extend. Authored per project; lives in .goga/workflows/<name>.yml (project-only).

A pipeline-file answers what the pipeline does. A workflow answers how the same pipeline should behave in this particular project without forking the base file.

Discovery

Pipelines are flat top-level *.yml files resolved from two directories:

Source Directory Origin
project <cwd>/.goga/pipelines/ Checked into / authored for the current project
user ~/.goga/pipelines/ Populated by goga connect from goga assets and goga_tool_* packages

Only top-level files are scanned — subdirectories are ignored, and .yaml files are excluded. When a name exists in both sources, the project source wins. A tool pipeline is namespaced as <tool>:<name>.yml — just a filename stem containing a colon — so it is resolved like any other bare name and the discovery scan picks it up verbatim. See Shipped Pipelines for the full installation algorithm.

Compilation overview

Each pipeline-file is compiled into a flow-file in a deterministic two-stage process owned by the goga/pipeline/compiler cell:

  1. Parse — parse_dsl reads the pipeline-file, validates the header (name, description, optional roles), and detects the body format (phases list or stages map).
  2. Serialize — serialize_flow applies per-format depends_on rules, merges any workflow overrides, embeds any extend stages, performs loop expansion, resolves the agent mode for each stage, and writes a byte-exact flow-file.

When a workflow is in scope, the compiler reconstructs the parsed body before building the output stages: extend entries inject new stages positioned via before/after, per-stage agent overrides choose which CLI agent runs the stage, per-stage prompt overrides layer additional context alongside the stage's own prompt, skip: true removes the stage and reconnects its dependents' depends_on, loop: N expands the stage into N chained copies, per-stage approve: auto|plan|dialog drives the afm auto-approval effects (interactive suppression and/or auto_approve emission), and per-stage manual: true|false forces or cancels the stage's manual launch mode (a stage-body trigger: manual compiles to the afm auto_run: false key — the stage pauses until launched). The pipeline-file itself can also carry before_script / script / after_script shell directives on any stage — compiled to the afm script_* keys — and a timeout directive (Go duration string) that compiles to the afm script_timeout key and bounds the stage's script action. See Workflows and Pipeline File — Script directives for the full semantics.

Where to next