Goga

A new semantic layer between specification and implementation based on the CODEMANIFEST specification — helping humans and AI agents reason about project structure at a higher level of abstraction.

A full-fledged Specification-Driven Development (SDD) framework: describe cell contracts with a structured YAML DSL, validate them, extract contracts from source code, and drive an end-to-end agent workflow — propose, brainstorm, design, plan, build, change, and accept — under the hood.

Languages

                   

Agents

                   

Documentation · Getting Started · Workflow · Pipelines · Configuration

Install

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

Quick start

Start a new project from scratch and build your first feature end-to-end.

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

goga init

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. Ship the first feature — run the full SDD lifecycle in one command inside an isolated container, with agent credentials forwarded automatically:

goga pipeline feature

The feature pipeline walks all eleven stages — propose → task-review → brainstorm → architecture-review → apply-architecture → code-design → design-review → coding-plan → plan-review → commit-architecture → accept-result — pausing at every communication stage to ask for your input. Three more shipped pipelines cover other lifecycles:

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; layer project-specific overrides on top via an optional workflow file.

4. Drive the cycle by hand (optional) — if you want explicit control over each step instead of running the whole cycle automatically, 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. For smaller changes, use one of the shortcut paths described in the Workflow section.

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

goga schema | goga tool viewer

What is a cell?

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".

Anatomy of a contract

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.

Example

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.

Pipelines

A pipeline is a named YAML file describing 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 resolved from <cwd>/.goga/pipelines/ (project) and ~/.goga/pipelines/ (user); the project source wins on name conflicts.

Four definitions ship with goga:

goga pipeline feature

A pipeline-file answers what the pipeline does. A workflow file layers how the same pipeline should behave in this project — per-stage CLI agent, additional prompt context, skills overrides, loop expansion, stage skipping via skip, per-stage auto-approval via approve, and new stages via extend — without forking the base file.

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

Features

• Specification-Driven Development — Contracts are the source of truth; the agent workflow produces architecture, code, and tests from them
• CODEMANIFEST DSL — Describe cell contracts with types, routines, imports, usages, and annotations
• Agent workflow — Built-in cycle: propose → brainstorm → apply → design → plan → build → change → accept, with review checkpoints and shortcut paths for smaller changes
• Validation — AST-based linter with 21 document-level and 3 tree-level rules
• Language parsers — Extract contracts from Python, Go, Kotlin, Swift, and JavaScript via tree-sitter
• CLI toolkit — init, lint, build, schema, connect, install, upgrade, contract extraction, and pipeline commands
• Pipelines — flat YAML pipeline-files describing a named sequence of stages an AI agent walks through (propose → … → accept). Ships four ready-to-use definitions — feature, bugfix, patch, review — installable via goga connect and overridable per-project via optional declarative workflow files at .goga/workflows/<name>.yml that layer per-stage agent/prompt/skills overrides, loop-expansion, stage skipping via skip, per-stage auto-approval via approve, and new stages via extend on top of a pipeline at compile time (disable with --no-workflow); cap concurrency with goga pipeline <name> -p N (the maximum number of stages that may run in parallel, subject to the pipeline's dependency rules)
• Docker builds & pipelines — Execute build plans via ralphex and run pipelines in isolated containers, with automatic forwarding of AI-agent credentials (claude/codex/opencode), optional HTTP proxy / --add-host support for corporate environments, persistent pipeline state across runs, inline roles overrides that customize the three authorable agent prompts (planner/executor/reviewer, mapping to the planning/implementation/review stems) per pipeline-file — the summary prompt is always the shipped default, and an --update image refresh that builds from a project dockerfile: when declared (else pulls)

Documentation

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

Contributing

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.