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

::: details 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](/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.
:::

::: info 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](/harness/mcp).

Forge also adapts to the repository it is run in rather than applying one fixed
setup everywhere. It builds a [repo profile](/features/adaptivity) — 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](/features/providers), 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`](/features/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.

::: tip 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`](/harness/autonomous-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](/installation#telemetry).

## 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

::: details 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.
:::

```mermaid
flowchart TD
  CLI[forge CLI] --> Engine[Stateful Go engine]
  Slash[/forge.* slash commands/] --> Engine
  MCP[forge mcp serve — read-only] --> Engine
  Engine --> State[.forge/ on-disk state]
  Engine --> Adapters[Per-agent adapters]
  Engine --> Providers[Git provider adapters]
  Adapters --> Agents[24 AI coding agents]
  Providers --> Hosts[GitLab · GitHub · Gitea · Bitbucket]
  Engine --> Related[Related repos in the workspace]
  State --> Dashboard[Generated dashboard]
```

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

- [Installation](/installation) — get the binary and configure your agents.
- [Getting Started](/getting-started) — walk one change end to end.
- [The Workflow](/guide/workflow) — the canonical SDD spine and adaptive depth.
- [Project Structure](/guide/project-structure) — what lives under `.forge/`.
- [Agents](/guide/agents) — the full list of supported agents.
- [Git Providers & Related Repos](/features/providers) — how a change reaches your host.
- [Multi-Repo Workspace](/features/workspace) — one logical change across several repos.
- [Enforcement Doctrine](/harness/overview) — what enforces, what only advises.