goforge

A Polylith-style workspace tool for Go. goforge organizes a single Go module into reusable bricks — components (with a public interface package and a hidden internal/ implementation) and bases (entry-point layers) — composed into deployable projects. It scans the workspace, derives the brick dependency graph from Go imports, detects what changed since a stable git point, and validates and tests incrementally.

Worker types

Every component is classified along two axes (see principles.yaml):

• determinism — deterministic | non_deterministic
• effectfulness — pure | [input_effect] | [output_effect] | [input_effect, output_effect]

goforge check enforces effect propagation (a pure component may not depend on an effectful brick; a deterministic brick may not depend on a non_deterministic one), and goforge classify shows each brick's declared vs. effective worker type, propagated through its dependency closure.

Install

go install goforge.dev/goforge@latest

Commands

Command	Purpose
create	Scaffold a workspace, component, base, or project
info	Brick × project matrix, with changed bricks/projects marked (:loc for line counts)
check	Validate structure, the interface boundary, worker-type rules, and project deps
classify	Declared vs. effective worker type per brick
deps	Brick dependencies, forward and reverse (brick: / project:)
diff	Files, bricks, and projects changed since the stable point (since:)
test	Run tests for changed bricks/projects (:all, :dev, brick:, project:)
libs	Third-party libraries and which bricks use them
ws	Workspace as YAML data (get:KEY.PATH, out:FILE)
migrate	Bootstrap goforge config for an existing Go module
shell	Interactive command shell
version / help	Tool version / usage

Arguments use poly-style syntax: key:value and :flag, e.g. goforge create component name:user interface:api, goforge info :loc, goforge test :all. Add color-mode:none to disable ANSI color.

Quick start

goforge create workspace name:demo top-ns:com.demo module:goforge.dev/demo
cd demo
goforge create component name:user
goforge create base name:cli
goforge create project name:app
goforge check
goforge info

See scripts/e2e.sh for a full worked example.

Layout of a workspace

go.mod · workspace.yaml · principles.yaml
components/<name>/  <name>.go (interface) · internal/ (impl) · component.yaml
bases/<name>/       <name>.go · base.yaml
projects/<name>/    main.go · project.yaml
development/        deps.go (generated; imports every brick)