Skip to content

Getting Started

Prerequisites

  • Python 3.10 or later and the pipx package manager
  • Docker — pipelines and builds execute inside an isolated container; docker info must succeed on the host
  • An AI agent — one of claude, codex, cursor, opencode, or qwen, with its credentials available on the host (a credential file such as ~/.claude/.credentials.json, or the agent's env variables — see Agents)
  • git (>= 2.40 for the topic exchange — goga topics update/propagate) — topics, history artifacts, and the default image name are derived from the repository

Install goga

pipx install goga

Connect to agent

Install skills into an agent:

goga connect <agent>

Upgrade goga

Move to a new goga release and re-sync every connected agent in one step — no need to call pip directly:

goga upgrade

To stay within your current version line, add --patch (latest patch of the installed minor line) or --minor (latest release of the installed major line). See goga upgrade for details.

Initialize a project

Run the interactive initialization wizard:

goga init

The wizard will prompt you for:

  1. Language — Select your project language: python, golang, kotlin, swift, or javascript
  2. Convention — Optionally download language-specific conventions from the goga-lang-conventions repository
  3. CODEMANIFEST usages — Optional named practices (key-value pairs) for your project
  4. CODEMANIFEST annotations — Optional free-text instructions for AI agents
  5. Build agent and environment — Confirm-gated (defaults to No). Decline to skip the build agent, or accept and choose an agent — claude, codex, cursor, opencode, or qwen — then set its env vars (agent-specific keys suggested first)
  6. Docker image — Choose whether to create a custom Dockerfile (suggested path .goga/Dockerfile):
  7. If you create a Dockerfile, the image is built from it, so you provide the base image for the FROM line (chosen from the language-specific list), and a built image name/tag (what goga build tags with docker build -t). The built image name defaults to <project-name>:latest, where <project-name> is derived from your git origin remote URL; when no git remote is available, no default is offered and the name is required.
  8. If you skip the Dockerfile, you pick a pre-built image to pull from the language-specific list (or enter a custom one).
  9. Pipeline agent and environment — Confirm-gated (defaults to No). Decline to skip the pipeline agent, or accept and choose an agent — claude, codex, cursor, opencode, or qwen — then set its env vars. Does not inherit the build agent — the two are collected independently
  10. Tools — Confirm-gated (defaults to No). Record name → version pairs in the config's top-level tools list (consumed by goga install bulk mode)
  11. Usages records — Confirm-gated (defaults to No). Record git dependencies (group, name, git URL, optional ref/root) in the config's top-level usages tree (consumed by goga usages sync)
  12. Tool blocks — Only with invited tools: the questions each invited tool declared, asked under its own heading

Invited tools are configured at initialization time with goga init -t <tool-name> (repeatable) — the tool contributes its own questions and its config files land under .goga/tools/<tool>/.

What goga init creates

.goga/
  config.yml              # Project configuration
  usages/
    conventions.md        # Language conventions (if downloaded)
  Dockerfile              # Optional, if you chose to create one (default location)
  tools/
    <tool>/               # Tool configs (per invited tool, goga init -t)

Starting from a template (optional)

Instead of the bare wizard, you can scaffold a project from a copier template first. Copier writes the template files plus a .goga/scaffold.yml state file, then the same questionnaire runs. Questions are skipped when the template already brought the corresponding artifact (.goga/config.yml or .goga/usages/conventions.md). During scaffolding, copier interactively asks every template question that has no programmatic answer (the project name is resolved from the git remote and supplied for you) — run it in a terminal, not a pipe/CI.

On --upgrade the survey is skipped and defaults are used:

# Latest commit on the template's default branch
goga init https://github.com/<you>/my-template.git

# Pin a ref via the URL fragment, or override it with --ref
goga init https://github.com/<you>/my-template.git#v1.0

To migrate a previously scaffolded project to a newer template version later, copier re-applies the recorded template from the state file (no onboarding):

goga init --upgrade            # re-apply at the recorded ref
goga init --upgrade --ref v2.0 # migrate to a specific ref

<tpl> and --upgrade are mutually exclusive; --ref requires one of them. See goga init for details.

Develop your first feature

Goga is built around an agent-driven development cycle. You do not write CODEMANIFEST files by hand — you describe the feature, and the agent produces the architecture, the contract files, the design, and the implementation plan. The cycle is organized as two workrounds — refinement (the product side) and development (the engineering side) — and can be driven in two ways: run it automatically with a single pipeline command, or step through it manually for full control over each artifact.

The full cycle:

specify → review(task)
   → prototype → review(arch)
      → apply → design → review(design)
         → plan → review(plan)
            → goga build
               → change (bugfix loop)
                  → accept

The cycle may open with discover when a hard-to-reverse decision needs settling before the task is formulated — define is the longest entry point of the refinement workround, and entering at discover skips product definition. For work that does not require deep technical elaboration, the shorter path starts directly at specify and cuts straight to change — see Workflow.

Automated cycle

The fastest path. Goga ships ready-to-use pipelines that run the workrounds inside an isolated container, with the credentials you provide (see Credentials in the container).

1. See what is available:

goga pipeline --list

* refinement
* development
* bugfix
* patch
* review
* sync

2. Inspect a pipeline before running it:

goga pipeline refinement --info

name: Refinement
description: Task refinement process

---

* define:
    title: Product definition & create PRD
* discover:
    title: Technical discovery & create ADR
* specify:
    title: Create task, specs & decomposition
* review:
    title: Review of the created task

3. Run the refinement workround, then development:

goga pipeline refinement
goga pipeline development

refinement walks the product side — define → discover → specify → review — and pauses at every communication stage to ask for your input before moving on. development picks up the reviewed task and walks the engineering side — prototype-architecture → architecture-review → apply-architecture → code-design → design-review → coding-plan → plan-review → commit-changes → accept-result. When the work does not need product elaboration, skip the early stages — for example, start refinement at discover:

goga pipeline refinement -s define

More shipped pipelines cover other lifecycles — see Shipped Pipelines. To run pipelines where no human is present (CI, schedulers), see Automation.

Manual cycle

If you want explicit control over each step instead of running the whole cycle automatically, formulate the task by hand:

/goga:specify <what you want to build>

The slash-command form requires a command-capable agent — see Slash commands.

The agent walks you through an interactive dialogue, then produces .goga/history/<year>/<topic>/task.md. From there, each subsequent command takes the previous artifact as input and produces the next one. See the Workflow section for the full algorithm of each step in both workrounds — refinement and development — including shortcut paths for smaller changes.

View

After the first task has produced cells on disk — for example, once you have run goga-apply (or /goga:apply in a command-capable agent — see above) and the cell structure exists — you can inspect the result.

Get a textual hierarchy of all cells:

goga schema

The hierarchy shows cells, their imports, and the connections between them — useful for verifying that the materialized architecture matches what you designed.

Next steps

  • Workflow — The agent-driven feature development cycle
  • Pipelines — The full functional model of pipelines
  • Configuration — Full config reference for .goga/config.yml
  • Cells — Cell structure, usages, and CODEMANIFEST DSL reference
  • CLI Reference — All available commands and options