goga 1.1.0

A tool for working with the codemanifest specification — assembly, extension, and plan-building workflow

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. Formulate the first feature — describe what you want to create:

/goga:propose <what you want to create>

The example above uses Claude Code style. For other agents, invoke the skill directly: goga-propose.

4. Run the workflow — each subsequent command takes the previous artifact as input and produces the next one:

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

Reviews are optional at every stage. For smaller changes, use one of the shortcut paths described in the Workflow section.

To run the whole cycle stage-by-stage inside the goga container, use one of the shipped pipelines:

goga pipeline feature      # end-to-end feature lifecycle
goga pipeline bugfix       # root-cause analysis for a defect
goga pipeline patch        # refactoring or minimal change with a plan

Each pipeline is a flat YAML file; layer project-specific overrides on top via an optional workflow file.

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.

Three definitions ship with goga:

Pipeline	Purpose
feature	End-to-end feature implementation lifecycle
bugfix	Root-cause analysis and resolution for a defect
patch	Refactoring or minimal change with a formalized plan

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, and loop expansion — 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 three ready-to-use definitions — feature, bugfix, patch — installable via goga connect and overridable per-project via optional declarative workflow files at .goga/workflows/<name>.yml that layer per-stage agent/prompt overrides and loop-expansion on top of a pipeline at compile time (disable with --no-workflow)
• 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 agents overrides that customize the four agent prompts (planning/implementation/review/summary) per pipeline-file, 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.