Goga

An open platform for building AI-SDLC. Declare the development process as pipelines, hire any CLI agent per stage, extend capabilities with tools. A full Specification-Driven Development (SDD) cycle ships in the box — and through tools and workflows the cycle can be extended, reshaped, or replaced with any other methodology.

Three pillars

⚙ Pipelines A declarative scenario of stages an agent walks through to deliver work, with communication checkpoints that switch between autonomous and human-in-the-loop execution. Any installed agent (Claude, Codex, Qwen, OpenCode, others) can be hired per stage.

🧩 Tools Pluggable capability packages. Any open-source tool or in-house methodology is packaged as goga-tool-* and lands in a shared catalog of skills and pipelines, all addressed uniformly.

📋 SDD The reference cycle shipped in the box: CODEMANIFEST contracts as the source of truth, an agent workflow from propose to accept. Use it as is, extend it through workflows, or replace it with your own methodology built from tools and pipelines.

AI development without a framework collapses into uncoordinated agent runs — the cycle cannot be reproduced, there are no managed approval checkpoints, and the methodology is locked into a single tool. goga is the framework: the process is declared, agents are interchangeable, methodologies are composable.

Languages

Python

JavaScript

Kotlin

Swift

Go

Agents

Claude

Codex

OpenCode

Cursor

Qwen

Documentation · Getting Started · Pipelines · Tools · Configuration

pipx install goga

goga build and goga pipeline launch a Docker container, so Docker must be installed and accessible on your host:

docker info

Connect goga to your agent

goga connect <agent>

To upgrade goga later and re-sync all connected agents, use:

goga upgrade

Start a new project from scratch and ship your first piece of work end-to-end.

1. Initialize the project — the interactive wizard sets up .goga/config.yml, language conventions, and (optionally) a Dockerfile:

goga init

You can also start from a copier template (goga init <template-url>, optionally pinned with #ref or --ref), and later migrate a scaffolded project with goga init --upgrade. See goga init for the full surface.

2. Open your agent — launch the agent you connected via goga connect (e.g., Claude Code) in the project directory. All goga-<command> skills are now available.

3. Run a pipeline — pick one of the shipped cycles and let goga walk the agent through its stages, pausing at every communication checkpoint for your input. Credentials for claude, codex, and opencode are detected on the host and forwarded into the container automatically:

goga pipeline feature       # the full SDD cycle: propose → … → accept
goga pipeline bugfix        # root-cause analysis and defect resolution
goga pipeline patch         # refactoring or minimal change with a plan
goga pipeline review        # scoped review of code, contracts, docs, then lint/format/tests

Each pipeline is a flat YAML file describing the stages; layer project-specific behavior on top via an optional workflow file (per-stage agent, additional skills, prompt context, loop expansion, auto-approval, stage skipping, new stages).

4. Drive the cycle by hand (optional) — if you want explicit control over each step instead of running a full pipeline, formulate the task and step through each command manually:

/goga:propose <what you want to create>

propose → brainstorm → apply → design → plan → goga build → change → accept

The slash-command form /goga:<command> works in agents that consume the goga command bundle — currently claude, opencode, and qwen (see goga connect). Codex and cursor do not register commands; in those agents invoke the skill directly: goga-propose (Codex uses the $ prefix — $goga-propose). Reviews are optional at every stage.

5. Visualize the result — once apply has produced cells on disk, inspect the architecture:

goga schema | goga tool viewer

A pipeline is a declarative scenario of stages an agent walks through to deliver a piece of work — propose, review, brainstorm, apply, design, plan, build, change, accept. A pipeline-file does not depend on any concrete agent: claude, codex, qwen, opencode, or any other installed wrapper can execute it. Stages with communication: true pause the run and ask for human input; without it they run autonomously.

A pipeline-file is a flat YAML document with a header and a list of stages:

name: Feature
description: End-to-end feature development
---

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

- name: brainstorm
  title: "Task-based architecture development"
  communication: true
  skills:
    - goga-brainstorm

- name: accept-result
  title: "Contracts & coverage audit"
  communication: true
  skills:
    - goga-accept

Four definitions ship with goga:

Pipelines are resolved from <cwd>/.goga/pipelines/ (project) and ~/.goga/pipelines/ (user); the project source wins on name conflicts.

goga pipeline feature            # run the full cycle (opens with discover)
goga pipeline feature -s discover # shorter run: skip discovery, start at propose
goga pipeline feature -p 4       # cap parallelism (subject to the pipeline's dependency rules)
goga pipeline feature --clean    # wipe persistent state for a fresh run

A running pipeline executes inside a Docker container, where its flows, run-state, and logs are written to a persistent host directory and survive across runs of the same pipeline on the same project and branch — so an interrupted run can be resumed.

A workflow-file (.goga/workflows/<name>.yml) configures and extends a compiled pipeline at run time, without touching the pipeline-file. Five levers, each with a short example.

agent — hire a different agent per stage. Authoring on codex, reviews on claude, no pipeline duplication:

stages:
  propose:
    agent: codex
  brainstorm:
    agent: codex
  architecture-review:
    agent: claude
  plan-review:
    agent: claude

loop — repeat a stage N times as chained copies. Multiple review passes with increasing depth:

stages:
  plan-review:
    loop: 2       # → plan-review-1 → plan-review-2, each depending on the previous

approve — auto-approve a stage. Three modes (auto / plan / dialog) drive two independent effects — suppression of interactive and emission of auto_approve:

stages:
  accept-result:
    approve: auto   # the stage will not prompt the user and will self-approve

skills — add skills to a stage. Merged with the pipeline stage's own skills (pipeline-first, deduplicated by value):

stages:
  brainstorm:
    skills: [acme-explore, acme-propose]

prompt — context, not command. To make a workflow prompt carry actual requirements, use labeled blocks (Requirements: / Constraints:); free-form prose is interpreted as background:

stages:
  propose:
    prompt: |
      Task formalization process.

      Requirements:
      - Examine all link connections between cells carefully.
      - Do not write code examples in the task.

      Constraints:
      - Do not build architecture in the task.

Additionally: skip: true removes a stage with transparent reconnection of dependents, and extend: adds brand-new stages with before/after positioning. The full model is in the Workflows documentation.

Run with a workflow:

goga pipeline feature                   # auto-match: .goga/workflows/feature.yml if present
goga pipeline feature --workflow custom # explicit
goga pipeline feature --no-workflow     # disable workflow application entirely

Read the full functional model in the Pipelines section of the docs.

A tool is a pluggable capability package. Any open-source tool or in-house methodology is packaged as a Python package under the goga_tool_ prefix and becomes part of the goga ecosystem: its skills land in a shared catalog at ~/.goga/skills/, its pipeline-files install at ~/.goga/pipelines/ with a namespace prefix, and everything lives side by side, addressed uniformly.

Tools are distributed as Python packages under the goga-tool- prefix. goga install targets the running interpreter's pip directly and re-syncs every already-connected agent after a successful pip — the new tool's skills and pipelines appear in ~/.goga/ and in each agent's symlink tree immediately:

# Install one tool, latest version
goga install <tool-name>

# Install a pinned or ranged version (four-form grammar)
goga install <tool-name> --version 1.0.x

# Install every tool declared under tools: in .goga/config.yml in one pip call
goga install

# Install a tool from a local source directory (no PyPI lookup)
goga install --local <path>

After installing, connect the tool to your agent (only required the first time, or to connect a new agent — goga install re-syncs already-connected agents automatically):

goga connect <agent>

Pass goga install --no-connect to opt out of post-install activation (CI/Docker escape-hatch). Pass goga install --sudo for system-Python installs requiring root.

See goga install for the full version-grammar rules and single/bulk/empty/local semantics.

Via CLI:

goga tool <name> [args...]

Via agent skill:

Invoke the /goga:tool <name> command (or goga-tool skill) in your agent session. The slash-command form works in claude, opencode, qwen; in Codex and cursor, invoke the skill directly — goga-tool (Codex: $goga-tool).

The following tools ship with goga out of the box — no separate install required. They are registered automatically once goga is installed and goga connect has been run.

Minimal layout, illustrated by a tool named acme that ships four subcommands — explore, propose, apply, archive — and one pipeline-file, with no top-level dispatcher skill:

goga_tool_acme/
├── __init__.py            # main(argv: list[str]) — CLI entry point
├── skills/
│   ├── acme-explore/
│   │   └── SKILL.md       # goga-tool-acme-explore
│   ├── acme-propose/
│   │   └── SKILL.md       # goga-tool-acme-propose
│   ├── acme-apply/
│   │   └── SKILL.md       # goga-tool-acme-apply
│   └── acme-archive/
│       └── SKILL.md       # goga-tool-acme-archive
└── pipelines/
    └── spec.yml           # → ~/.goga/pipelines/acme:spec.yml

A valid tool must:

• Be named with the goga_tool_ prefix (PyPI publication under goga-tool-)
• Contain a skills/ directory with at least one skill (each skill directory has a SKILL.md)
• Expose a main(argv: list[str]) function for CLI execution (optionally declaring a keyword-capable ast parameter to receive the project AST)
• A pipelines/ directory is optional; when present, its flat *.yml files are copied into ~/.goga/pipelines/ at goga connect time, namespaced as <tool>:<name>.yml

After publication, install into any project:

goga install acme
goga pipeline acme:spec            # namespaced pipeline from the tool

The subcommands become ordinary agent skills — goga-tool-acme-explore, goga-tool-acme-propose, goga-tool-acme-apply, goga-tool-acme-archive — that can be invoked directly (/goga:tool acme explore, goga-tool-acme-explore, or $goga-tool-acme-explore in Codex) or merged into any stage of any pipeline via skills: in a workflow-file. The acme cycle explore → propose → apply → archive can be run end-to-end through acme:spec, woven stage-by-stage into the SDD cycle, or composed into a custom pipeline where acme-propose runs next to goga-brainstorm.

The entry point may optionally declare a keyword-capable ast parameter to receive the project AST (loaded lazily from the current project root, only when declared). A tool that does not need the AST keeps the minimal main(argv) form and the AST is never built. See goga tool for the entry-point forms and opt-in rules.

When goga connect installs a tool, the prefix goga-tool-<tool-name>- is added to every skill and the result lives centrally under ~/.goga/skills/:

Rules:

• Use lowercase with hyphens as separators
• When a top-level dispatcher skill is wanted, name its directory exactly <tool-name> — it becomes the entry point invoked by /goga:tool <name> (or goga-tool / $goga-tool in agents without slash-command support). A tool that exposes only subcommands (like acme above) skips this directory.
• Name sub-skills descriptively using the <tool-name>-<purpose> pattern (e.g., mkdocs-discovery, mkdocs-validator)

Tool pipelines are namespaced on install. A file <name>.yml in a tool's pipelines/ directory is copied into ~/.goga/pipelines/ as <tool>:<name>.yml, where <tool> is the package name with the goga_tool_ prefix dropped and underscores normalized to hyphens (goga_tool_hello_world → hello-world):

Namespacing structurally prevents collisions — between a tool pipeline and an internal-source pipeline, and between two tools shipping the same name. See Shipped Pipelines for the full installation algorithm.

Read the full Tools model in the Tools section of the docs.

Out of the box, goga ships a full Specification-Driven Development (SDD) cycle. This is the three pillars in action: a pipeline-file describes the stages, tools supply skills, and CODEMANIFEST is the contract language used inside the stages. Use the cycle as is, extend it through workflows, or replace it with your own methodology built from tools and pipelines.

A cell is a directory that encapsulates a distinct responsibility domain with a well-defined API boundary. Each cell contains a CODEMANIFEST file describing its contract and an optional .usages/ directory with documentation for API consumers.

cell/
├── CODEMANIFEST       # YAML DSL describing the API contract
└── .usages/*.md       # Practices for working with the cell

The rule of thumb is one responsibility zone — one cell. A new cell is born when logic can be decoupled, owns distinct data models, must be reused, or can be stated in a single phrase without "and".

A CODEMANIFEST consists of three sections separated by ---:

• Header — Imports (types and usages from other cells), Usages (named practices), Annotations (global directives)
• Body — entities and routines that form the cell's public API
• Footer — Author, CreatedAt, Description

Cells expose three kinds of types:

• Entity types — objects with state and behavior (services, configurations, data models): properties + methods
• Routine types — single operations (transformers, factories, validators, parsers): no state
• Embedded types — re-exports of imported types: ->ExternalService

Specialization is expressed with the :: mutation syntax. The DSL stays language-agnostic — BaseEntity::ExtendedEntity may be realized through inheritance, composition, an adapter, or an interface implementation in the target language.

Imports:
  - Types:
      - AnotherCellType
    From: path/to/another_cell

Usages:
  conventions: .goga/usages/conventions.md

Annotations: |
  Use `conventions` when writing code.

---

"ParseInput(input: string) -> data:List<byte>":
  location: parser.py
  annotations: |
    Parses raw input into a byte buffer.
  
    `input`: raw request payload

"HTTPServer(name: String)":
  location: server.py
  properties:
    "host -> String": |
      Bind address for incoming connections.
  methods:
    "handleRequest(req: Request) -> resp:Response": |
      Dispatches a single HTTP request.

      Algorithm:
      1. Parse input from `req` with `ParseInput`
      2. Filter result by some logic
      3. Save filtered result in `resp`
      4. Return `resp` object

---

Author: Goga
CreatedAt: 01/01/26
Description: |
  HTTP entry point cell.

The SDD cycle is not monolithic — every part of it is extensible through the same workflow mechanisms described in the Pipelines section, applied to the shipped feature pipeline.

Add an external skill to a stage. brainstorm gains an extra skill from the acme tool alongside goga-brainstorm:

# .goga/workflows/feature.yml
stages:
  brainstorm:
    skills: [acme-explore]

Swap an SDD stage for an external equivalent. On architecture-review, switch to codex and run acme-explore against the spec; on apply-architecture, loop twice and pair goga-apply with acme-apply:

stages:
  architecture-review:
    agent: codex
    skills: [acme-explore]
  apply-architecture:
    loop: 2
    skills: [acme-apply]

Insert new stages from a tool's arsenal. Between propose and brainstorm, run acme-explore to walk the spec; after accept-result, run acme-archive to archive the delivered spec snapshot:

extend:
  spec-explore:
    after: [propose]
    before: [brainstorm]
    title: Spec exploration
    skills: [acme-explore]
    prompt: |
      Walk the current spec before architecture work begins.
  spec-archive:
    after: [accept-result]
    title: Archive spec
    skills: [acme-archive]
    prompt: |
      Archive the delivered spec snapshot.

Run a stage for two passes. plan-review with loop: 2 runs two sequential passes with increasing depth:

stages:
  plan-review:
    loop: 2

Finish autonomously. accept-result with approve: auto suppresses the user prompt and self-approves:

stages:
  accept-result:
    approve: auto

These are not special "SDD extension points" — they are exactly the same workflow mechanisms from the Pipelines section, applied to the SDD cycle. Combining tools and workflows, SDD can be compressed to propose → accept for prototypes or expanded with threat-modelling, security review, and compliance gates for production. Read the full functional model in the Workflow section of the docs.

goga build is a separate service that materializes a plan into code. Pipelines produce plans; Build executes them — and neither side is a special case of the other. A plan is handed to a ralph-loop running inside an isolated Docker container, which reads the plan, executes each task in sequence (declaration → contract tests → implementation → interface verification → logic tests → lint → review → approval), and writes the implementation into the project tree. CODEMANIFEST files stay read-only throughout — the contract is the source of truth, the build produces code that satisfies it.

goga build docs/plans/<topic>.md

The host side assembles the environment and launches the container; the in-container process then guards its environment, prepares the loop's working directory, and runs the loop with the plan as input. Credential files for claude, codex, and opencode are detected on the host and bind-mounted read-only into the container automatically (no flag), so the agent executing the plan runs with your live credentials.

Customize the run with the usual flags:

goga build plan.md --update               # refresh the image first (build from config dockerfile, else pull)
goga build plan.md --clean                # wipe persistent loop state for a fresh run
goga build plan.md -e ENV_VAR=value       # forward an extra env var into the container

A running build executes inside a Docker container, where its run-state and logs are written to a persistent host directory and survive across runs of the same project on the same branch — so an interrupted build can be resumed. Pass --clean (or -c) to wipe that state before launch for a fresh run. After the build, test the implementation manually.

See goga build for the full CLI reference, configuration, and exit codes.

Full documentation is available at qarium.github.io/goga.

After cloning, enable the local git hooks once:

make install-hooks

This installs two-layer protection against Co-Authored-By: trailers (project policy: no co-authorship in git history):

• commit-msg — blocks the commit at creation time.
• pre-push — blocks the push if any new commit being pushed contains the trailer (catches cases where the commit-msg hook was bypassed with --no-verify or not installed).

Bypass in rare intentional cases with git commit --no-verify / git push --no-verify.