Maistik Forge

Appearance

Buy a license
Download PDF

Introduction ​

In one sentence: Forge is a small program that teaches the AI coding assistant you already use to plan before it builds, and to prove its work before you ship it — instead of taking its word for it.

Maistik Forge is a single static Go binary — forge — that brings spec-driven development to the AI coding agents you already use. It is the union of two ideas: a methodology scaffolder and a stateful runtime platform. Forge folds a spec-driven scaffolding and command surface into a durable Go runtime chassis, so you get both the discipline of a well-defined workflow and the durability of a real state machine.

New here? A quick glossary before the jargon starts
  • Spec-driven development (SDD): write a short, precise plan (a "spec") before any code, so the agent builds against something concrete instead of a vague prompt. Full explanation in Getting Started.
  • Static Go binary: one self-contained program file, no installer, no separate runtime to set up — you download it and run it.
  • Stateful runtime: Forge remembers things between runs (specs, decisions, task status) by writing them to plain files on disk, rather than forgetting everything the moment a command finishes.

At a glance

  • Binary: forge — one static executable, no runtime
  • Config directory: .forge/
  • What it does: configures 24 AI coding agents — plus a generic adapter — to follow one spec-driven workflow
  • What it is not: an agent installer or a hosted service

What Forge does ​

Forge configures the AI coding agents already on your machine so they all speak the same spec-driven language. It detects your installed agents (it never asks you to name them) and writes a unified command set to each one, translated into that agent's native format. Twenty-four agents have dedicated adapters — Claude Code is the recommended one — and a generic adapter covers anything else. The forge binary itself is a deterministic tool with its own terminal commands; alongside it, Forge writes a family of /forge.* agent slash-commands into each configured agent. These two authoring surfaces overlap, but the SDD spine, foundation authoring, and most cross-cutting commands run only as /forge.* agent skills — there is no forge specify terminal command. A third, read-only surface sits beside them: forge mcp serve exposes the harness over MCP so an agent can query what forge knows. It authors nothing and enforces nothing — see Harness as MCP.

Forge also adapts to the repository it is run in rather than applying one fixed setup everywhere. It builds a repo profile — stack, test and lint commands, git host, size — and it is provider-native: GitLab, GitHub, Gitea, and Bitbucket each plug in through the same adapter layer, so forge deliver opens a merge request or a pull request in that host's own terminology. Projects that span several repositories declare their siblings under repo.related, and forge workspace shows which of them a given change actually touches.

Underneath the commands is a stateful engine that tracks your project's specs, in-flight changes, task status, spend, and timeline on disk under .forge/. That state survives context compaction, agent restarts, and team handoffs, because it lives in files you can read, diff, and commit.

Three surfaces, one on-disk state

The deterministic forge binary and the /forge.* agent skills both read and write the same .forge/ state on disk. They are not the same command set, though: /forge.specify, for example, is an agent skill with no forge specify terminal equivalent. Reach for the binary for its deterministic terminal commands (setup, analysis, harness gates, delivery); drive the SDD spine from your agent. The MCP server is the third surface and the odd one out: it is read-only, and each of its tools delegates to the same forge command you would run in a terminal, so it cannot drift from the CLI.

What Forge is not ​

  • Not an agent installer. Forge configures agents you already have; it does not download or run them.
  • Not a model. Forge has no LLM and cannot write code. Even forge run — the one command that drives an autonomous loop rather than configuring one — executes an agent command you supply with --cmd, and its job is to stop that loop the moment an enforced gate opens. It is dry-run by default and bounded on purpose.
  • Not a hosted service. Everything runs locally from a single binary.
  • Sends anonymous telemetry. Command name, Forge version, OS/arch, and a random install ID — never your code, file contents, or secrets. API keys are read from your environment only and are never persisted — local secrets stay local. Opt out with FORGE_NO_TELEMETRY=1; see Installation.

Guiding principles ​

Forge's design follows a small set of principles that show up everywhere in the product:

  • Zero-config default, full override. Forge works with no configuration at all, but every default can be overridden through .forge/config.yaml.
  • Convention over configuration. Sensible conventions mean you rarely need to configure anything to get started.
  • Everything is a module. Every unit of behavior installs, verifies, and rolls back the same way.
  • Prompts are data, engine is code. Agent prompts are declarative data; the engine that orchestrates them is deterministic Go code.
  • Idempotent and reversible. Operations converge to the same state when repeated, and every mutation is snapshotted so it can be undone.
  • Agent-agnostic core, per-agent adapters. A single core model is translated to each agent's native command format by per-agent adapters.

How the pieces fit ​

What's "MCP"?

Short for Model Context Protocol — an open standard that lets an AI agent ask a program (like Forge) structured questions and get structured answers back, instead of scraping raw text. forge mcp serve is Forge speaking that protocol so your agent can query harness state directly, in its own words, without you running a CLI command and pasting the output back in.

The deterministic forge binary and the /forge.* agent skills both operate on the same .forge/ state on disk. Where a command exists on both surfaces you can pick whichever fits the moment; the SDD spine (/forge.specify and its siblings), foundation authoring, and most cross-cutting commands run only as /forge.* agent skills. The MCP server reads that same state and never writes it. Two adapter layers hang off the engine and should not be confused: agent adapters translate the command set into each coding agent's native format, while git provider adapters translate delivery — issues, merge and pull requests — into each host's CLI and vocabulary.

Next steps ​