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.

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.

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 ​

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 — get the binary and configure your agents.
• Getting Started — walk one change end to end.
• The Workflow — the canonical SDD spine and adaptive depth.
• Project Structure — what lives under .forge/.
• Agents — the full list of supported agents.
• Git Providers & Related Repos — how a change reaches your host.
• Multi-Repo Workspace — one logical change across several repos.
• Enforcement Doctrine — what enforces, what only advises.

Getting Started

This quick start takes you from an empty terminal to a spec that is ready to build, and then on to a verified, archived change — all driven through your AI agent's slash commands. Reaching a ready spec takes about ten minutes; shipping the change takes as long as the work does.

New to the terms "spec" or "SDD"? Don't worry — you don't need a computer science degree to follow this page. Read on, and every unfamiliar word gets explained the first time it shows up.

The shape of the journey ​

flowchart LR
  I[Install] --> C[Configure agents] --> N[Init project]
  N --> F[Set foundations] --> R[Get a spec ready] --> S[Build, verify, deliver] --> D[Dashboard & metrics]

In plain words, that diagram says: you install one small program once, point it at the AI tools you already use, tell it a bit about your project's ground rules, then for every new feature you write a short plan (a "spec"), get it checked, build it, verify it actually works, and ship it — with a dashboard showing you the whole trail afterward.

Steps 1 to 4 are one-time setup — you do them once per machine and once per project, then mostly forget about them. Step 5 is the heart of Forge — turning an idea into a ready spec, something precise enough that an AI agent (or a teammate) can build it without guessing. Step 6 builds that spec into verified code and opens the merge or pull request on your git host.

1. Install the binary ​

Maistik Forge Kit is licensed software. With a license, your GitHub account has access to the private release repository: download the archive for your platform, extract it, and put forge on your PATH.

# macOS (Apple silicon), adjusted to the release you downloaded
tar -xzf forge_Darwin_arm64.tar.gz && sudo mv forge /usr/local/bin/forge

See Installation for every platform and for checksum verification, and Pricing if you do not have a license yet. Homebrew and Scoop are not yet published. Confirm the binary itself is healthy — this runs an in-process smoke test and does not need a project to check yet:

forge doctor --selftest

2. Configure your agents ​

Detect and configure the AI coding agents already on your machine:

forge install

Forge detects installed agents automatically (it never asks you to name them), backs up any existing configuration first, and is idempotent — meaning you can run it again and again, and it will not create duplicates or break anything each time. Every command below becomes available inside each configured agent as a /forge.<name> slash command — the same kind of /command shortcut you already type into Claude Code, Cursor, or whichever assistant you use, except now it triggers a Forge phase instead of a built-in feature of that tool.

See Supported Agents for the full list and per-agent notes, and Skills: Registry & Discovery for how Forge equips each agent with the right capabilities for the task at hand.

3. Initialize the project ​

From your project root, run the per-repository wizard:

forge init

This creates the .forge/ directory — the home for your specs, changes, and memory. Think of it as the project's own filing cabinet: every plan you write, every decision you make, and every change you ship gets a paper trail inside this one folder, right next to your code. For a non-interactive setup, pass --yes to accept sensible defaults. See Project Structure for a tour of what lands where, and Configuration to tune .forge/config.yaml.

With the project initialized, confirm everything is actually ready — agents detected, .forge/ writable, and every dependency (Node, Engram, …) installed:

forge doctor

A clean report means agents are configured, the project is initialized, and every dependency is present. Anything else is flagged with a fix hint — pass --fix to have Forge attempt the failed and warning dependency checks automatically:

forge doctor --fix

4. Set your foundations (run once) ​

Before writing feature specs, establish the standing truth your changes are measured against — the ground rules every future feature has to respect, so you're not re-deciding the same principles every single time you build something new. The foundation phases run once and set those ground rules:

/forge.constitution   define non-negotiable principles and constraints
/forge.security       define the security baseline
/forge.infra          define the infrastructure baseline
/forge.brand          define brand identity and voice
/forge.design         define the design system

At minimum, write a constitution. It is not just documentation — constitution conflicts are blocking findings that cap your quality score (more on that score in a moment), so a stale or missing constitution is a standing penalty on every spec you write afterward. See Change Governance for how foundations are enforced, and Persistent Memory for how Forge remembers decisions across changes.

5. Get your first spec ready ​

This is the core loop — the part of Forge you'll come back to for every single feature, bug fix, or change you make from now on. A change flows through the SDD spine; the first four phases take a raw idea and turn it into a ready spec before a line of code is written.

flowchart LR
  E[/forge.explore/] --> P[/forge.propose/]
  P --> S[/forge.specify/] --> C[/forge.clarify/] --> Ready([spec ready])

In plain words: you optionally look around the codebase first, then write down what you want to build, turn that into a precise requirements document, tighten up anything ambiguous, and only then does Forge consider the spec "ready."

Explore (optional) — investigate the codebase and weigh approaches before committing:

/forge.explore how should we add rate limiting to the public API?

Propose — capture the intent, scope, and approach as a change proposal:

/forge.propose add rate limiting to the public API

Specify — write the delta spec: requirements in RFC-2119 language (MUST/SHOULD/MAY) with Given/When/Then acceptance scenarios:

/forge.specify

Clarify — resolve ambiguity and strengthen the spec; answers are encoded back into it:

/forge.clarify

Is the spec actually ready? ​

"Ready" is not a feeling — Forge measures it, so you're never left guessing whether you've written "enough" spec. Score the spec against the reproducible 100-point rubric:

forge analyze

A ready spec has a complete skeleton (every required section filled in), clear requirements, a scenario for every requirement, and no constitution conflict. See Quality Gates for the full rubric, and check /forge.status any time to see where the change sits on the spine.

6. From a ready spec to a shipped change ​

With the spec ready, build it. Strict TDD is the default, so tests come first — meaning the agent writes the test that proves a feature works before it writes the feature itself, the same discipline good human engineers already practice. If a change can't be verified this way, Forge will tell you rather than let it slip through unverified.

flowchart LR
  PL[/forge.plan/] --> T[/forge.tasks/] --> IM[/forge.implement/]
  IM --> V[/forge.verify/] --> A[/forge.archive/] --> D[forge deliver]

/forge.plan        write plan.md — the architecture and decisions
/forge.tasks       break the plan into an ordered, honest checklist
/forge.implement   build the tasks, tests first
/forge.verify      check the work against its acceptance scenarios
/forge.archive     merge the delta spec into canonical specs; seal the audit trail

As with the earlier phases, /forge.continue from the previous step already walked you through plan and tasks — /forge.implement is usually the first command in this block you actually type by hand.

Implementation and verification run inside the enforced harness — think of it as the safety rails and seatbelt on an otherwise very fast, very capable car: the AI agent still does the driving, but it cannot run through a red light without something stopping it and telling a human.

• The Guardrails Gate blocks a change that leaks secrets, PII, or prompt-injection strings — the automated equivalent of a colleague catching an API key accidentally committed in a pull request.
• The Verify Circuit-Breaker stops runaway verify/implement loops before they burn time and budget — if the agent gets stuck retrying the same failing test over and over, this cuts it off instead of letting it spin forever.
• The Spend Budget enforces a per-change ceiling on tokens, cost, and tool calls, so one runaway change can't quietly burn through your AI provider bill.

You can also verify directly from the terminal against a named change:

forge verify --change add-rate-limiting

Add --isolated and verification runs against an ephemeral copy of the repository — committed files plus your uncommitted edits — so a test or build the agent just wrote cannot corrupt your working tree. "Ephemeral" here just means temporary: a disposable copy Forge throws away afterward, not your real project files.

forge verify --change add-rate-limiting --isolated

That isolates the filesystem, not processes or the network. See Isolated Verification for exactly what it does and does not contain.

Hand the loop off (optional) ​

If you want the implement/verify cycle driven for you, forge run executes an agent command repeatedly and stops the moment an enforced gate opens, escalating to a human rather than retrying:

forge run --cmd 'claude -p "work the next task in tasks.md"'            # dry run — nothing executes
forge run --cmd '…' --change add-rate-limiting --max-iterations 3 --yes # execute

Ship it to your git host ​

Forge resolves which host this repo lives on — GitLab, GitHub, Gitea, Bitbucket — and speaks that host's terminology (so it says "pull request" on GitHub and "merge request" on GitLab, matching what you'd expect). Check what it resolved, then open the change request:

forge provider                             # what host is this, and which CLI?
forge deliver --dry-run                    # preview the exact glab/gh command
forge deliver --label forge --base main    # open the merge or pull request

The body is assembled from the change's proposal.md plus its task list, and delivery refuses while any task is not done (--allow-incomplete is the deliberate override, e.g. for an early --draft). You can also export the remaining tasks as issues on the same host:

forge issues create --change add-rate-limiting --dry-run

See Git Providers & Related Repos. If the work spans sibling repositories, forge workspace shows which repos a change touches, and --workspace runs deliver/issues create across all of them — see Multi-Repo Workspace.

7. View your dashboard ​

Forge generates a live, self-contained dashboard from your .forge/ state — no external service, no account to create, it just reads the same files sitting in your project. Serve it locally while you work:

forge docs serve

This opens a browser view of your specs, quality scores, task status, budget, breaker state, and the attributed session timeline — a readable, visual version of everything the CLI has been tracking all along. See the dashboard overview for a tour. Want to watch the whole lifecycle run end to end against a sample project first, with nothing at stake? Try The Sandbox.

The dashboard shows you one change. To ask whether the harness itself is earning its keep — across every feature you've ever shipped with it, not just the one you're looking at — roll the same recorded state up across every change, active and archived:

forge metrics            # readable rollup
forge metrics --json     # stable machine output for dashboards or CI

Verify pass rate, breaker openings, spend, waived secscan findings, timeline volume, contributors — the numbers that answer "is this actually helping, or just adding ceremony?" It adds no instrumentation of its own; it simply reads the state the gates already write as they run, so there's no separate tracking system to trust or misconfigure. See Harness Metrics, and Harness as MCP if you would rather your agent query all of this directly with forge mcp serve.

Explore related topics ​

Everything the quick start touched, grouped for a deeper read:

Agents & skills

• Supported Agents — which agents Forge configures and how.
• Skills: Registry & Discovery — how agents get the right capabilities.

The harness (enforced gates)

• Enforcement Doctrine — what is enforced vs. advisory, and why.
• The Guardrails Gate · Verify Circuit-Breaker · Spend Budget · Session Timeline

The harness (everything else)

• Bounded Autonomous Run — forge run, and why it stops instead of retrying.
• Isolated Verification — verify against an ephemeral copy, not your tree.
• Harness Metrics — whether the gates are earning their keep.
• Harness as MCP — let an agent query the gates (queryable, not enforcing).

Delivery & multi-repo

• Git Providers & Related Repos — forge provider, deliver, issues create.
• Multi-Repo Workspace — siblings, spanning changes, cross-repo delivery.
• Repo Adaptivity — the profile forge builds of your repository.

Specs, quality & governance

• The Workflow — the full SDD spine and adaptive depth.
• Quality Gates — the 100-point score that defines "ready".
• Change Governance — how foundations and gates hold the line.

Foundations & memory

• Foundation Phases — constitution, security, infra, brand, design.
• Persistent Memory · Drift & Reconcile

More

• Migration Importer — bring an existing Spec-Kit or OpenSpec project.
• The Sandbox — see the whole lifecycle run in one command.
• Command Reference · The forge CLI · Configuration

Stuck anywhere on this page, or something didn't behave the way it's described here? Open an issue on GitHub — it's the fastest way to reach the people building this.

Installation

Maistik Forge ships as a single Go binary named forge. The same binary runs on macOS, Linux, and Windows.

Telemetry ​

Forge sends anonymous usage and error telemetry to GitLab Observability, on by default. What's sent, every CLI invocation:

• Command name (e.g. init, implement, review)
• Forge version, OS, and architecture
• A random install ID (a UUID generated once on first run and stored in ~/.forge/state.json) — not tied to your name, email, or IP
• On failure: a best-effort-redacted error message (file paths are stripped)

Never sent: source code, file contents, repository names or contents, prompts, model output, API keys, or anything else from your project. Your AI coding agent's model calls and conversations are never touched by Forge, telemetry or otherwise.

You'll see a one-time notice printed the first time you run any forge command — on init, or on whatever command runs first after upgrading from a version that predates telemetry.

Opt out at any time:

export FORGE_NO_TELEMETRY=1

Requirements ​

Forge itself needs, at runtime:

• git, curl, Node ≥ 18, and npm — required.
• Homebrew — optional (macOS).

Some features shell out to external tools: forge memory / forge recall use the Engram binary, and the graphify codebase-memory provider needs its own tooling. Both degrade gracefully when absent, but the feature will not work without them.

Install the binary ​

Homebrew (macOS and Linux) ​

Forge also publishes a private Homebrew tap, as an alternative to downloading an archive by hand below. Like everything else in this section, it requires an active license: set HOMEBREW_GITHUB_API_TOKEN to a token from a GitHub account with collaborator access to the release repository — the Homebrew equivalent of the GITHUB_TOKEN/GH_TOKEN that scripts/install.sh reads (get access at maistik.studio).

export HOMEBREW_GITHUB_API_TOKEN=<your-token>
brew tap maistik-studio/forge https://github.com/Maistik-Studio/forge-kit
brew install forge

brew upgrade forge picks up new releases the same way.

brew install maistik-studio/forge/forge

Download a release ​

Once your account has access, open the release repository, pick the latest release, and download the archive for your platform:

github.com/Maistik-Studio/forge-kit/releases

Archives are named by platform and architecture, and every release ships a checksums.txt alongside them.

# macOS (Apple silicon), adjust the archive name to the release you downloaded
tar -xzf forge_Darwin_arm64.tar.gz
sudo mv forge /usr/local/bin/forge

# Linux (x86_64)
tar -xzf forge_Linux_x86_64.tar.gz
sudo mv forge /usr/local/bin/forge

On Windows, extract the .zip and put forge.exe on a directory in your PATH.

sudo chown -R $(whoami):admin /usr/local/bin

Verify the download ​

Every release publishes checksums.txt. Check your archive against it before running anything:

shasum -a 256 -c checksums.txt --ignore-missing

Keeping up to date ​

Once the binary is on your PATH, Forge updates itself from the same release channel:

forge update      # report what is available
forge upgrade     # replace managed tool binaries in place

Verify the install ​

forge version     # is it on your PATH?
forge doctor      # read-only ecosystem health check

forge doctor inspects your environment and reports problems without changing anything. To also smoke-test the binary end to end:

forge doctor --selftest

Configure your agents ​

Installing the binary does not touch your agents yet. To detect and configure the agents you already have:

forge init        # scaffold .forge/ and pick agents (wizard, or --yes)
forge install     # write the Forge command set into your agents

forge install detects installed agents automatically. It backs up any existing agent configuration first, then writes the Forge command set. The operation is idempotent: running it again converges to the same state.

Common flags:

forge install --scope workspace          # configure for this project only
forge install --agents claude,cursor     # limit to specific agents
forge install --dry-run                  # preview changes, write nothing

See Agents for the supported agents.

Keeping Forge up to date ​

forge update       # check for available updates
forge upgrade      # apply updates to managed tools (binary-only)

Note that forge upgrade updates managed tools; it does not run the install/sync pipelines. Forge also checks for updates automatically on most commands; run forge update explicitly to control when a new release is fetched.

sudo forge upgrade

Snapshots and cleanup ​

Every mutation Forge makes is snapshotted automatically, so changes are reversible. There is no separate backup command — backups are taken before any mutating operation.

forge restore --list      # list snapshots
forge restore latest      # roll back to the most recent
forge uninstall --all     # remove Forge-managed config

Next steps ​

• Getting Started — walk one change end to end.
• Introduction — understand what Forge is and why.
• Configuration — customize .forge/config.yaml.

Common Troubles

This page is a reference for errors forge can print on your own machine — not a status page for the service, since there isn't one. If your environment is behaving strangely and you don't see it below, run forge doctor first — it's a read-only check that catches most of the causes on this page before you have to go hunting:

forge doctor

Install & Upgrade ​

forge upgrade fails with "permission denied" ​

Symptom

extract forge: create /usr/local/bin/forge.new: open /usr/local/bin/forge.new: permission denied

Cause: /usr/local/bin is owned by root and the current user can't write to it.

Fix: run the upgrade elevated, or fix ownership once so you never need sudo for this again:

sudo forge upgrade

See the ownership fix under Install the binary.

Checksum mismatch on the downloaded archive ​

Symptom

checksum mismatch for forge_1.2.3_darwin_arm64.tar.gz:
  expected: <hex>
  got:      <hex>

Cause: the download was corrupted in transit, or a proxy/CDN between you and the release repository is serving mutated bytes.

Fix: retry the download. If it keeps failing, check whether you're behind a corporate proxy that rewrites binary responses, and try from a different network. See Verify the download.

checksums.txt unavailable ​

Symptom

checksum verification failed: checksums.txt unavailable: download https://api.github.com/.../checksums.txt: HTTP 404

Cause: no network connectivity, a GitHub outage, or a missing/invalid token against forge's private distribution repository.

Fix: check your connection first, then set a token:

export GITHUB_TOKEN=<your-token>
# or
gh auth login

Asset not found in a release ​

Symptom

asset "forge_1.2.3_linux_amd64.tar.gz" not found in github release v1.2.3

Cause: that release is still building, or that OS/architecture wasn't published for this tag.

Fix: wait a few minutes and retry, or download the asset manually from the releases page.

Windows: manual update required ​

Symptom: forge update reports a newer version is available but can't apply it automatically for a given managed tool.

Cause: not every tool supports in-place self-replacement on Windows the way forge itself does with its PowerShell installer.

Fix: download the release asset manually from the URL forge update prints, and replace the binary yourself.

Homebrew-Specific ​

forge: command not found after a clean brew install forge ​

Symptom

$ brew install forge
==> Fetching forge
==> Installing forge
🍺  forge was successfully installed!
$ forge version
zsh: command not found: forge

Cause: forge collides with an unrelated homebrew-core formula (arrayfire/forge, a C++ visualization library that ships no CLI binary). If brew tap maistik-studio/forge https://github.com/Maistik-Studio/forge-kit was skipped, or ran but failed silently because HOMEBREW_GITHUB_API_TOKEN wasn't set (the release repository is private), brew install forge resolves against homebrew-core instead. Homebrew reports success because that install genuinely succeeded — it just installed the wrong package.

Fix:

brew uninstall forge
export HOMEBREW_GITHUB_API_TOKEN=<your-token>   # GitHub token, not GitLab
brew tap maistik-studio/forge https://github.com/Maistik-Studio/forge-kit
brew install forge

To avoid the ambiguity entirely, always install fully qualified:

brew install maistik-studio/forge/forge

Untrusted tap ​

Symptom

Homebrew requires explicit trust for external taps. Trust only this Forge <formula/cask>, then retry:
  brew trust --formula gentleman-programming/tap/<tool>
  brew upgrade --formula <tool>

Cause: Homebrew now requires an explicit trust step for third-party taps before it will install or upgrade from them.

Fix: run the two commands forge printed — brew trust, then brew upgrade — and retry.

Linux sandbox failure ​

Symptom

Bubblewrap ... cannot create a rootless sandbox

Cause: unprivileged user namespaces are disabled at the kernel level, so Homebrew's Bubblewrap sandbox can't start.

Fix: enable user namespaces:

sudo sysctl -w kernel.unprivileged_userns_clone=1

As a last resort, skip the sandbox for this run:

HOMEBREW_NO_SANDBOX_LINUX=1 brew upgrade --formula <tool>

Network & Private-Repo Authentication ​

Private-repo authentication required ​

Symptom

private repo, no GitHub token configured — set GITHUB_TOKEN to check

private repo, no GitLab token configured — set GITLAB_TOKEN to check

Cause: forge's distribution repositories are private. Without a token, "the release doesn't exist" and "you're not authenticated" both come back as an HTTP 404, so forge reports the auth-required case rather than guessing.

Fix: set the token for whichever host the tool in question is distributed from:

export GITHUB_TOKEN=<your-token>   # or: gh auth login
export GITLAB_TOKEN=<your-token>   # CI_JOB_TOKEN is picked up automatically inside CI

GitHub API rate limit exceeded ​

Symptom

github API rate limit exceeded (HTTP 403)

Cause: unauthenticated GitHub API requests are capped at 60/hour per IP. Frequent forge status / forge sync calls, or a shared office IP, exhaust that quickly.

Fix: set GITHUB_TOKEN (raises the cap to 5,000/hour), or wait for the window to reset.

Configuration ​

Malformed .forge/config.yaml ​

Symptom

parse .forge/config.yaml: yaml: line 12: did not find expected key

Cause: hand-edited YAML with bad indentation or syntax.

Fix: fix the syntax, or avoid hand-editing entirely — use forge config edit for an interactive TUI. forge config explain shows the fully resolved values without editing anything.

Unknown config key ​

Symptom

"workflow.styct_tdd" is not a recognized config key; run `forge config explain` to see the resolved keys

Cause: a typo in a config key, usually from hand-editing.

Fix:

forge config explain

Find the correct key name and fix the typo.

Invalid review.gate value ​

Symptom

review.gate must be one of ci, off, pre-commit, pre-push, not "precommit"

Cause: an unsupported value was set for review.gate — the missing hyphen above is a common one.

Fix: use one of ci, off, pre-commit, or pre-push.

forge config edit without a terminal ​

Symptom

forge config edit needs an interactive terminal; use `forge config set <key> <value>` in scripts and CI

Cause: config edit is an interactive TUI and can't run in a script or CI job with no TTY attached.

Fix: use the non-interactive form instead:

forge config set <key> <value>

Unsupported flag value ​

Symptom

unsupported persona "gentelman"
unsupported preset "min"
unsupported sdd-mode "solo" (valid: single, multi)

Cause: an invalid value was passed to --persona, --preset, --components, --skills, or --sdd-mode — often a typo.

Fix: run forge install --help to see the valid IDs for each flag.

Backups & Restore ​

Corrupted backup manifest ​

Symptom

unmarshal manifest ".forge/backups/upgrade-.../manifest.json": invalid character '\x00' looking for beginning of value

Cause: the backup was interrupted mid-write — disk full, process killed, or power loss during the snapshot.

Fix: use a different, uncorrupted backup:

forge restore --list

Delete the corrupt backup directory under .forge/backups/.

No matching backup ID ​

Symptom

backup "20260101T000000Z" not found — use `forge restore --list` to see available backups

Fix:

forge restore --list

Pick an ID from the printed list.

No backups available ​

Symptom

no backups available to restore

Cause: this is expected on a fresh install, or if backups were disabled with --no-backup on the operation that ran. It isn't a bug.

Pre-upgrade backup fails, but the upgrade proceeds anyway ​

Symptom

pre-upgrade backup failed — upgrade will run without a backup: create archive ".../snapshot.tar.gz": open .../snapshot.tar.gz: no space left on device

Cause: the backups directory is on a full or read-only volume. This is intentionally non-fatal — forge upgrades anyway rather than blocking you on a backup failure.

Fix: free up disk space, or fix permissions on the backups directory, if you want the safety net back for the next operation.

Dependencies & Environment ​

Missing agent runtime dependency ​

Symptom: forge blocks the install for a given agent, e.g.:

Node.js / npm is required but 'npm' was not found in PATH...
Kimi requires Astral uv, but 'uv' was not found in PATH...
Pi requires the 'pi' executable in PATH before installing Forge Pi packages

Cause: each agent has its own runtime prerequisite that forge checks before writing its configuration.

Fix:

sudo npm install -g prompts unexpectedly ​

Symptom: forge silently runs npm install -g under sudo, prompting for your password when you didn't expect it.

Cause: on Linux, with a distro-packaged Node (not installed via nvm, fnm, or volta), npm's global install prefix is root-owned — forge prepends sudo so the install can succeed at all.

Fix: install Node via nvm, fnm, or volta instead of your distro's package. That makes npm's global prefix user-writable, and forge stops needing sudo for this.

OpenCode plugin: no package manager found ​

Symptom

OpenCode plugin <pkg> can be upgraded from ~/.config/opencode, but no supported package manager is available in PATH. Install bun or npm, then run update tools again.

Cause: neither bun nor npm is on PATH, so forge has nothing to run the upgrade with.

Fix: install Node.js (for npm) or Bun.

Go missing or too old ​

Symptom

Go 1.24+ is required to install Engram but was not found in PATH
Go 1.24+ is required to install Engram but found go1.20.
Go modules are disabled (GO111MODULE=off).

Cause: the Engram memory backend is installed via go install, which needs a recent Go toolchain with modules enabled.

Fix: install or upgrade Go from go.dev/dl, and if needed:

export GO111MODULE=on

GGA upgrade: git clone failure ​

Symptom

git clone gentleman-guardian-angel: exit status 128 (output: ...)

Cause: git isn't installed, there's no network connectivity, or the release tag doesn't exist yet (this can happen briefly right after a release).

Fix: install git, check your connection, and retry — if it's a just-published release, wait a few minutes first.

forge doctor reports a missing ecosystem dependency ​

Symptom

node not found in PATH...
gga binary not found

Cause: a feature you've configured — MCP stdio servers, the review gate, Engram memory — needs a CLI tool that isn't installed.

Fix:

forge doctor --fix

Or install the missing tool yourself and re-run forge doctor.

Still stuck? ​

Run the full self-test for a deeper check than the read-only default:

forge doctor --selftest

If that doesn't explain what you're seeing, double check the Installation steps, or open an issue on GitHub — it's the fastest way to reach the people building this.

Security

Forge is a local static binary, not a hosted service. Nothing about its architecture requires trusting a third party with your source code, and the questions below are answered by what the binary actually does, not by policy.

Why this matters for the decision to buy ​

A team adopting an AI coding agent is already trusting that agent's own model provider with its code. Forge does not add a second party to that trust relationship — it adds a local, inspectable layer of enforcement on top of a tool you've already decided to use. Nothing here is a claim about certifications Forge does not hold: no SOC 2, no SSO, no SCIM today. This page lists exactly what the architecture does and does not do, and it will be updated the day any of that changes.

See also: compliance and the EU AI Act position for where Forge sits in the regulatory picture, not just the technical one.

Enterprise

Past the Team seat limit it is Enterprise, and we price it with you — on your real headcount, not a per-seat list price stretched past where it was designed to work.

Who this is for ​

• Past 10 developers. Team covers one license for up to 10 developers on one invoice. The 11th developer is an Enterprise conversation, not a bigger Team invoice.
• Under 10, but procurement has questions before anyone can pay. A security review, a vendor questionnaire, or a signed order form instead of a card — that's an Enterprise conversation regardless of headcount.

Seats count developers, not machines. Run forge on every CI runner, every pre-commit hook, and every autonomous loop you like — enforcing the harness everywhere is the point of it, and none of that adds a seat.

What's included beyond Team ​

• Everything in Team
• More than 10 developers, priced on real headcount
• Security review and procurement paperwork
• Custom license terms, MSA, and DPA
• Air-gapped and offline distribution
• Named support channel with an SLA
• Multi-year terms

How buying works ​

Enterprise is quoted per organization and bought under a signed order form — evaluation and cancellation terms are part of that conversation, not fixed in advance the way Solo and Team's checkout is. Billing is in USD, annual or multi-year. Access to the release repository is granted per developer, so onboarding a new hire is a short message either way.

What we don't have yet ​

Stated plainly rather than implied: Forge does not have SSO, SCIM, or a SOC 2 report today. This page lists exactly what's real — if your evaluation needs one of those, say so up front and we'll tell you honestly where that stands rather than after a security review finds out for you. See also Security for the full architecture picture.

Talk to us ​

Book a call, or start from pricing if you want to see where Team tops out first.

Foundation phases

Most Forge phases describe a single change. Five do not. The foundation phases — constitution, security, infra, brand, design — establish standing project truth: the ground rules every later change operates within. You run them once, early, before the per-change spine gets busy. This page explains what each one establishes, where it writes, why it comes first, and the one place a foundation phase reaches forward and grips the rest of the workflow.

Run once, then build on top ​

The SDD spine — explore → propose → specify → clarify → plan → tasks → implement → verify → archive — runs per change. The foundation phases are different in kind. They are not steps in a change; they are the context a change is measured against. Set them first, and every change that follows inherits them.

flowchart LR
  subgraph Foundation["Foundation (run once)"]
    K[constitution]
    S[security]
    I[infra]
    B[brand]
    D[design]
  end
  Foundation --> Spine
  subgraph Spine["Per-change spine (run every change)"]
    E[explore] --> P[propose] --> SP[specify] --> Mid[… clarify · plan · tasks · implement …] --> V[verify] --> A[archive]
  end

Scaffold them from the forge init wizard ​

The interactive forge init wizard has a Foundation step: a checklist of these same five phases, asking which ones to scaffold now. forge init cannot run an interactive slash command itself — each phase gathers project context from you before it writes anything — so checking a box does not draft the file during init. Instead, once the wizard finishes, forge init prints the exact /forge.* command for every phase you checked, ready to run immediately after. Leave one unchecked and run its command later, whenever you actually reach it — nothing about the checklist is binding.

The five phases ​

Only two of these phases — brand and design — have deterministic forge seed commands. The other three (constitution, security, infra) are authored entirely through their /forge.* agent slash-commands; there is no forge constitution, forge security, or forge infra terminal command. See Commands for the full surface.

Constitution ​

/forge.constitution defines the project's non-negotiable principles and constraints — the articles every change must respect. Modularity, test-first, simplicity, observability, the technology choices you refuse to relitigate. It is the most load-bearing artifact Forge holds, and the only foundation phase that reaches into scoring — see The constitution caps your score.

Security ​

/forge.security defines the project's security posture — the baseline that declares what authentication, authorization, rate-limiting, and secrets handling every flow must satisfy. This is the advisory half of Forge's security story. The enforcing half is the forge secscan gate, which statically scans a change's files for leaked secrets, PII, and prompt-injection strings and returns a non-zero exit on unwaived findings. The baseline says what "secure" means; the gate refuses to bless a change that violates it.

Infra ​

/forge.infra defines the infrastructure baseline — the standing spec for development, production, CI/CD, observability, and disaster recovery. It is the source of truth deployment files derive from, not the other way around. Once set, any change that assumes a service, environment, or capability the baseline does not declare is drift the reconciler can catch.

Brand ​

/forge.brand defines brand identity and voice — the color palette, typography, spacing scale, and design tokens the product speaks in. The CLI seeds it: forge brand writes .forge/design/brand.md if it does not already exist, then your agent authors the real content through the slash command.

Design ​

/forge.design defines the design system — the component specs, states, accessibility requirements, and token references built on top of the brand. forge design seeds both .forge/design/brand.md and .forge/design/design-system.md. Design references brand, so brand comes first.

What they write under .forge/ ​

Foundation artifacts are plain files, like everything else Forge tracks. They live under .forge/ and belong in version control so the whole team shares one standing truth.

The constitution caps your score ​

The constitution is not just documentation — it is wired into quality scoring. forge analyze produces a 100-point quality score for the current state, and constitution conflicts are blocking findings that cap that score. A change that violates a declared principle cannot post a clean number, no matter how polished it is otherwise.

That has a direct consequence: a stale constitution quietly drags down every assessment. If your principles have moved and the document has not, analyze scores your work against yesterday's truth. Revisit the constitution whenever your constraints change, so the score reflects reality rather than drift against an outdated article.

Foundations feed reconciliation ​

The foundations are also the yardsticks the reconciler measures new specs against. When you write or change a spec, reconciliation checks it for constitution violations, security-baseline misalignment, infrastructure assumptions the baseline does not cover, and brand or design inconsistency — and constitution violations cannot be deferred. Set the foundations well and /forge.reconcile has something firm to hold every later change to. See Drift and reconcile.

Next steps ​

• Drift and reconcile — how foundations keep later specs honest.
• The workflow — the per-change spine foundations sit under.
• Commands — every foundation command, CLI and slash.
• Best practices — keep the constitution current, commit .forge/.

The Workflow

Forge is built around one canonical spec-driven development (SDD) spine. Every change flows through the same phases, and the only thing that varies is how much of the spine a given change actually traverses. This page explains the spine, the foundation phases that run once, adaptive depth, and how artifacts are produced and promoted.

This is a reference page — it goes deep, on purpose, so you can look up exactly what a phase or gate does. If you just want a first walkthrough, read Getting Started instead and come back here later.

The canonical SDD spine ​

There is exactly one spine, in this order:

flowchart LR
  E[explore] --> P[propose] --> S[specify] --> PL[plan]
  PL --> T[tasks] --> I[implement]
  I --> V[verify] --> A[archive]

explore → propose → specify → plan → tasks → implement → verify → archive

Every change is a subset of this spine — never a different one. Adaptive depth (below) decides where a change enters the spine, but the ordering and semantics of the phases never change.

Where review sits ​

Bounded adversarial review is not a tenth phase either. It is the gate that stands between a finished implementation and every delivery boundary — commit, push, pull request, and release:

flowchart LR
  I[implement] --> RS[review start]
  RS --> RF[review finalize]
  RF --> R[content-bound receipt]
  R --> V[verify]
  V --> RV[review validate --gate]
  RV --> A[archive]
  RV --> D[forge deliver]

review start opens right after implement, not after verify: independent final verification requires an already-active review transaction, so verify stays blocked until a review has been started and reaches a final-verification-ready state. review validate --gate is then re-run at every later boundary against the same content-bound receipt.

Three commands, and only the first one opens anything:

forge review start                     # freeze scope, derive risk tier, lenses, budget
forge review finalize --result <file>  # record lens results and evidence
forge review validate --gate <gate>    # check the receipt against a boundary

start freezes the target and selects lenses deterministically by risk — zero for a docs-only diff, exactly one focus lens for an ordinary change, the full 4R set for a hot path or a diff over 400 changed lines. finalize records the lens results and produces a content-bound receipt.

validate is then run at each boundary, with one of five gates:

A gate that cannot validate reports why, and each answer has exactly one correct response — none of them is "run the gate again":

Where deliver sits ​

forge deliver is not a tenth phase. It opens the merge or pull request on whichever host this repo lives on, and it is a terminal command rather than a spine phase — the spine describes the state of the spec and the work, not the state of a review on your git host.

It does share archive's readiness gate, though: delivery refuses while any task is not done, listing the blockers and exiting non-zero, with --allow-incomplete as the deliberate override for opening a --draft early. So the two are siblings rather than sequential — you can archive without delivering, or open a draft MR before archiving:

flowchart LR
  V[verify] --> A[archive]
  V --> D[forge deliver]

forge issues create sits in the same place: it exports a change's remaining tasks as issues on the same resolved host, and can run at any point once tasks.md exists.

Foundation phases (run once) ​

Some phases establish standing project truth rather than describing a single change. These foundation phases run once and set the ground rules the spine operates within:

• constitution — the project's non-negotiable principles and constraints.
• security — the security posture and requirements.
• infra — the infrastructure baseline.
• brand — brand identity and voice.
• design — the design system and conventions.

The forge init wizard's Foundation step lets you pick which of these to scaffold right away; it prints the matching /forge.* command for each one you check as your next steps. See Foundation Phases for what each one establishes and where it writes.

Adaptive depth ​

"Adaptive" runs on two independent axes, and it is worth keeping them apart:

Per change: how much spine to run ​

Forge triages each change to decide how much ceremony it needs. This is per-change triage, not a per-project mode you switch on — different changes in the same project take different paths.

flowchart TD
  Start{Triage the change} -->|Trivial| Fast[fast-forward: implement -> verify]
  Start -->|Standard| Std[specify -> plan -> tasks -> implement -> verify -> archive]
  Start -->|Substantial / Hot-path| Full[explore -> ... -> archive full spine]

Per repo: what is relevant here at all ​

The other half of "adaptive" is about the repository rather than the change. Forge builds a repo profile — stack (from marker files like go.mod or Cargo.toml), the test and lint commands verify will use, the resolved git provider, related repos, and a rough size band — and uses it to decide what is relevant here:

forge profile

The visible payoff is skill pruning: guidance that requires a stack this repo does not have is reported as skipped, so the agent's context isn't padded with Terraform advice in a repo with no infrastructure.

Test-driven by default ​

Strict TDD is the default posture: tests are written before the implementation they cover. Specifications use OpenSpec Given/When/Then scenarios combined with RFC-2119 language (MUST / SHOULD / MAY) so requirements are precise and testable.

Changes flow through .forge/changes/ ​

Every change lives in its own directory under .forge/changes/ while it is in flight. When a change passes verify and is archived, its delta specs are promoted into the canonical specs under .forge/specs/, and the change itself moves into the immutable archive.

flowchart LR
  Change[.forge/changes/<name>/] --> Verify[verify]
  Verify --> Archive[archive]
  Archive --> Specs[.forge/specs/ canonical]
  Archive --> Trail[changes/archive/YYYY-MM-DD-<name>/]

Phase-to-artifact map ​

Each phase produces a specific artifact on disk:

See Project Structure for the full on-disk layout of a change directory.

Cross-cutting commands ​

Some commands are not phases at all — they are cross-cutting, callable at any time, and non-destructive:

• analyze — produces a 100-point quality score for the current state.
• drift — detects code-vs-spec drift, classified as Ghost (code with no spec), Phantom (spec with no code), or Mutated (code and spec disagree).
• reconcile — brings code and specs back into agreement.
• refine — improves an existing artifact in place.
• recall — surfaces prior specs and decisions relevant to what you are about to write. Advisory: it informs, it never blocks.

A second group is read-only by construction — these commands report what forge sees and write nothing at all:

• profile — the repo profile: stack, test/lint commands, provider, size, and which skills are relevant here.
• provider — the resolved git host for this repo and every related repo, with the CLI each one uses.
• workspace — this repo plus its declared siblings, their active changes, and the changes that span more than one of them.
• metrics — the harness rollup across every change, active and archived: verify pass rate, breaker, budget, waivers, timeline.

Because they are non-destructive, you can run these freely at any point without disturbing an in-flight change.

Review belongs to neither group. review validate --gate <gate> is one of Forge's four enforced controls: it fails closed, and a non-zero exit means the loop stops and escalates rather than retries. See Where review sits above.

Honest task status ​

Task status in Forge is deliberately honest. A task moves through these states:

• backlog — not started.
• in-progress — being worked.
• blocked — cannot proceed.
• done — and only when its acceptance scenarios pass under verify.

Next steps ​

• Commands — every command, as CLI and slash command.
• Configuration — override defaults like strict_tdd and adaptive_depth.
• Project Structure — where artifacts live on disk.
• Circuit-breaker — how verify loops are bounded.
• Git Providers & Related Repos — deliver and issues create.
• Repo Adaptivity — the per-repo half of "adaptive".
• Adversarial Review — risk tiers, refuters, and the receipt.
• Bounded Autonomous Run — driving the loop, and stopping it.

The Sandbox

The sandbox is a one-command, real-scenario tour of the entire forge lifecycle. It builds the actual forge binary, stages a realistic sample project, and drives it through import, scoring, every enforced gate, and the dashboard build — asserting at each step that the gates fire exactly the way they do in production. It is both the fastest way to see forge work end to end and the repository's end-to-end safety net.

Two entry points ​

Both drive the same 9-step scenario against the same fixtures, so they never drift:

The script runs every step even if an earlier one failed, prints one PASS/FAIL line per assertion, and exits non-zero if any assertion failed — so a single run reports every problem rather than stopping at the first.

The 9-step lifecycle ​

flowchart LR
  B[build] --> S[stage] --> I[import] --> A[analyze]
  A --> SC[secscan BLOCK] --> W[waive] --> BU[budget EXCEEDED]
  BU --> V[verify breaker] --> D[trace + docs]

Each step asserts a specific, observable outcome. The gate steps are the point: they deliberately expect a non-zero exit to prove the gate blocks.

1. build — compile the forge binary to out/bin/forge.
2. stage — copy the acme-shop fixture into a fresh work directory.
3. import — map the .specify/ project into .forge/ and assert the change directories were created. See Migration Importer.
4. analyze — run the portfolio health rollup and a single-spec score, asserting the quality score is non-trivial.
5. secscan — scan the planted secret and assert the guardrails gate BLOCKS (exit non-zero).
6. secscan waive + rescan — waive the finding as a human would, and assert the rescan is now clean.
7. budget — accumulate spend, then cross the ceiling and assert the spend budget reports BUDGET EXCEEDED (exit non-zero).
8. verify breaker — force a verify failure so the circuit-breaker opens (exit non-zero), then --reset-breaker and assert it clears.
9. trace + docs — assert the session timeline aggregated the gate events, then build the offline dashboard and assert index.html was written.

The sample project ​

The fixture is a small but realistic .specify/ project, acme-shop, committed under scripts/sandbox/fixtures/:

acme-shop/
  .specify/
    memory/constitution.md            # a few real principles
    specs/001-checkout/{spec,plan,tasks}.md
    specs/002-auth/{spec,plan,tasks}.md
  src/
    checkout.js                       # secret-free
    config.js                         # a planted, clearly-fake AWS key

src/config.js contains an intentionally-fake AWS-style key. It is the trigger for step 5 — the thing the guardrails gate must catch. Everything else is authored so analyze produces a real, non-trivial quality score.

Inspecting the artifacts ​

make sandbox leaves a fully-populated .forge/ behind so you can explore the exact state the gates produced:

scripts/sandbox/out/work/
  .forge/
    changes/001-checkout/
      budget.yaml            # the spend ledger
      secscan.yaml           # the waiver from step 6
      session-log.jsonl      # the attributed timeline
      verify-attempts.yaml   # the circuit-breaker state
    site/index.html          # the generated dashboard

The run prints the path to the generated dashboard at the end — open it in a browser to see the same spec-viewer a real project produces.

Sandbox, selftest, and e2e ​

Forge ships three overlapping checks. They are complementary, not redundant:

Reach for the selftest to check the plumbing, the sandbox to see and inspect the experience, and make e2e in CI.

Extending it ​

The fixture and the driver are plain, versioned files:

• Add a spec or feature under scripts/sandbox/fixtures/acme-shop/.specify/.
• Add or adjust a step in scripts/sandbox/run.sh (each step asserts an exit code and records PASS/FAIL).
• Mirror any new assertion in e2e/sandbox_test.go so CI covers it too.

Keep the two entry points in lockstep: whatever the human sandbox demonstrates, the hermetic e2e test should assert.

Next steps ​

• The enforcement doctrine — the enforced gates the sandbox exercises.
• The forge CLI — the real commands each step drives.
• Migration Importer — the import step the sandbox runs first.
• Spec-Viewer Dashboard — the dashboard the final step builds.
• Getting the Most out of Forge — apply the workflow to your own repo.

Configuration

Forge follows a zero-config default, full override philosophy. It works with no configuration at all — but when you need to change something, everything is overridable through a single optional file: .forge/config.yaml.

Resolution order ​

Forge resolves configuration in four layers. Later layers win:

flowchart LR
  A[Built-in defaults] --> B[.forge/config.yaml]
  B --> C[.forge/config.local.yaml]
  C --> D[Environment & flags]

1. Built-in defaults — baked into the binary.
2. .forge/config.yaml — per-project overrides, committed with the repo.
3. .forge/config.local.yaml — per-machine overrides, gitignored.
4. Environment variables and per-invocation CLI flags — highest precedence.

Schema version ​

schema_version is the only top-level scalar key — it is not a section. It declares which version of the config schema the file is written against.

• schema_version (int) — current version is 1. Omit it and Forge assumes 1; there is no need to set it until a future schema revision exists.

schema_version: 1

Sections ​

All sections below are optional.

workflow ​

• strict_tdd (bool) — enforce tests-first. Default: true.
• adaptive_depth (bool) — let Forge triage per-change depth. Default: true.
• force_depth (trivial | standard | full) — pin depth for all changes. Default: unset — depth is decided per-change by adaptive_depth instead.
• phases (list) — override the phase list. Default: unset — Forge uses its built-in spine (explore, propose, specify, clarify, plan, tasks, implement, verify, archive).
• breaker_threshold (int) — how many consecutive forge verify failures open the per-change circuit breaker. Default: unset, which resolves to 3. forge verify --max-failures <n> overrides it for one run. See The Circuit Breaker.

workflow:
  strict_tdd: true               # default: true
  adaptive_depth: true           # default: true
  force_depth: standard          # default: unset (trivial|standard|full)
  breaker_threshold: 5           # default: unset -> 3
  phases:                        # default: unset -> built-in spine
    - explore
    - propose
    - specify
    - clarify
    - plan
    - tasks
    - implement
    - verify
    - archive

agents ​

• scope (global | workspace) — where agent config is written. Default: global.
• enabled (list) — restrict to specific agents. Default: unset — every detected/installed agent is enabled.

agents:
  scope: workspace               # default: global
  enabled:                       # default: unset (all detected agents)
    - claude-code
    - cursor
    - opencode

repo ​

Git-hosting context and related repositories. All optional — with no repo: section, the provider is auto-detected from the git remote. See Git Providers & Related Repos.

• provider (gitlab | github | gitea | bitbucket | generic) — force the provider, overriding remote-based auto-detection. Default: unset (auto-detect from the git remote).
• hosts (map) — map a self-hosted host to a provider kind, e.g. gitlab.example.com: gitlab. Default: unset (empty map).
• related (list) — sibling repos in a multi-repo project; each takes name, and a path (local checkout) or url, plus an optional provider override (else derived from the url/path). Default: unset (no related repos).

repo:
  provider: ""                   # empty = auto-detect from the remote
  hosts:
    gitlab.example.com: gitlab
  related:
    - name: api
      path: ../api
    - name: web
      url: https://github.com/acme/web

memory ​

• spec (engram) — backend for spec memory. Default: engram.
• codebase (engram | graphify | graphiti) — backend for codebase memory. Default: engram.
• team_sync (bool) — enable committable team memory export. Default: unset — detected as on iff the repo has a git remote.

memory:
  spec: engram                   # default: engram
  codebase: engram               # default: engram
  team_sync: true                # default: unset -> detected (on iff repo has a remote)

learn ​

• threshold (int) — pending-candidate ceiling used by forge learn review / promote to flag candidates as eligible. Default: unset (no ceiling — <= 0 also means no ceiling).
• auto_approve (bool) — allow forge learn promote to write without an explicit --approve. Default: false, so promotion stays human-gated.

learn:
  threshold: 20                  # default: unset (no ceiling)
  auto_approve: false            # default: false

budget ​

Ceilings the per-change spend ledger is enforced against. Each dimension is independent, and each is opt-in: unset (or <= 0) means no ceiling for that dimension — the ledger still accumulates, it just never blocks. The matching --max-* flag on forge budget record / forge budget check overrides the configured value for one run.

• max_tokens (int) — cap on the change's cumulative reported tokens. Default: unset (no ceiling).
• max_usd (float) — cap on the change's cumulative reported dollar spend. Default: unset (no ceiling). forge run has no flag for this one, so a ceiling here is the only way to enforce it inside the run loop.
• max_tool_calls (int) — cap on the change's cumulative reported tool calls. Default: unset (no ceiling).

Reaching exactly a limit is within budget; strictly over it blocks. See The Spend Budget.

budget:
  max_tokens: 500000             # default: unset (no ceiling)
  max_usd: 25.00                 # default: unset (no ceiling)
  max_tool_calls: 2000           # default: unset (no ceiling)

persona ​

Selects the standing persona and conversation language.

• mode (forge | forge-neutral-artifacts | neutral | custom) — the persona to apply. Defaults to neutral.
• language (string) — the conversation language, as a language code. Defaults to en.

The persona modes and the replies-vs-artifacts distinction are documented under Personas. The --persona flag on forge install overrides this for a single run.

persona:
  mode: forge
  language: en

docsite ​

Controls forge docsite publish — rendering forge's .forge/ state into a documentation site you already own. Every field is optional; with no docsite: section the generator and output directory are detected from files already on disk.

• target (auto | vitepress | docusaurus | mintlify | starlight | mkdocs | neutral) — which generator to emit for. Default: auto, which detects the generator from disk and falls back to neutral.
• out (string) — output directory, relative to the repo root. Default: unset, so it is derived from detection.
• pattern (string) — the information-architecture pattern for the generated site. Default: auto, which picks one from the project type.
• sections (list) — top-level sections to generate, in order. Default: [guide, reference, decisions].
• scaffold (bool) — let publish write the generator's config file when it is missing. Default: false, and never applies under target: auto. This gate is publish-only: install always scaffolds its own template set unconditionally, regardless of this key — running install is itself the explicit consent this gate exists to require of publish.
• llms_txt (bool) — also emit /llms.txt alongside the site. Default: true.
• auto_on_archive (bool) — regenerate the site during the archive phase. Default: false.
• exclude (list) — glob patterns kept out of the source scan. Default: ["**/*_test.go", "vendor/**", "node_modules/**"].

docsite:
  target: vitepress               # default: auto
  out: docs                       # default: unset (derived from detection)
  pattern: auto                   # default: auto
  sections:                       # default: [guide, reference, decisions]
    - guide
    - reference
    - decisions
  scaffold: true                  # default: false
  llms_txt: true                  # default: true
  auto_on_archive: false          # default: false
  exclude:                        # default: ["**/*_test.go", "vendor/**", "node_modules/**"]
    - "**/*_test.go"
    - "vendor/**"
    - "node_modules/**"

models ​

A per-phase map assigning a provider/model to phases such as explore, design, and implement. Default: unset (empty map) — each phase uses the coding agent's own default model unless a phase key here overrides it.

models:                           # default: unset (empty map)
  explore: anthropic/claude-opus
  design: anthropic/claude-opus
  implement: anthropic/claude-sonnet

mcp ​

• servers (list) — MCP servers to expose. Default: [context7].

mcp:
  servers:                        # default: [context7]
    - context7
    - filesystem

review ​

• gate (off | pre-commit | pre-push | ci) — when review runs. Any other value is treated as off, so the gate fails closed rather than activating an unknown mode. The init wizard's Review Gate step offers exactly these four modes. Default: off.
• provider — the review provider. Default: unset.

review:
  gate: pre-push                  # default: off (off|pre-commit|pre-push|ci)
  provider: anthropic             # default: unset

guardrails ​

• level (off | guarded | strict | bypass) — the permission posture. This is the key the forge init wizard writes. Default: unset, which resolves to the guarded posture.
• default_mode (guarded | bypass) — an accepted alias for level, so a file written against the published PRD schema works unchanged. Default: unset.

Only the value bypass changes behavior, and only when a config layer sets it explicitly — it is never selected automatically. Every other value, including an absent guardrails section, resolves to the guarded fail-safe posture:

• Guarded (default) — each agent is asked to confirm tool calls: Claude Code gets defaultMode: default, OpenCode/Kilocode get bash: "*": ask, and Codex gets approval_policy: on-request.
• Bypass — restores auto-accept (Claude Code bypassPermissions, Codex approval_policy: never) and, on Claude Code, installs a blocking PreToolUse hook for destructive git commands as the substitute for the confirmation that auto-accept removes.

The secrets deny-list overlay is injected in both postures. Other keys — posture, secrets.deny, destructive_actions — are accepted and carried through but not read; they illustrate the intended future shape only.

The wider guardrails story (the deny-list contents, the destructive-action hook, and forge secscan) is documented under The Guardrails Gate.

guardrails:
  level: guarded                  # default: unset -> guarded
  secrets:
    deny:
      - AWS_SECRET_ACCESS_KEY
      - STRIPE_SECRET_KEY

extensions ​

• A list of { id, version } entries for installed extensions. Default: unset (empty list — no extensions installed).

extensions:                       # default: unset (empty list)
  - id: forge-graphql
    version: 1.2.0
  - id: forge-terraform
    version: 0.4.1

Complete example ​

The following config.yaml shows non-default values across every section. Copy it as a starting point and delete anything you do not need — remember that every key is optional.

# .forge/config.yaml — every section and key is optional.

schema_version: 1               # config schema version (current: 1)

workflow:
  strict_tdd: true              # tests-first (default: true)
  adaptive_depth: true          # triage depth per change (default: true)
  force_depth: standard         # pin all changes to a depth: trivial|standard|full
  breaker_threshold: 5          # consecutive verify failures that open the breaker (unset = 3)
  phases:                       # override the phase list (advanced)
    - explore
    - propose
    - specify
    - clarify
    - plan
    - tasks
    - implement
    - verify
    - archive

agents:
  scope: workspace              # global|workspace (default: global)
  enabled:                      # restrict to specific agents
    - claude-code
    - cursor
    - opencode

repo:                           # omit entirely to auto-detect from the remote
  provider: gitlab              # gitlab|github|gitea|bitbucket|generic
  hosts:                        # map self-hosted hosts to a provider kind
    gitlab.example.com: gitlab
  related:                      # sibling repos in a multi-repo project
    - name: api
      path: ../api
    - name: web
      url: https://github.com/acme/web

memory:
  spec: engram                  # spec memory backend
  codebase: graphify            # engram|graphify|graphiti
  team_sync: true               # export committable team memory

learn:
  threshold: 20                 # pending-candidate ceiling (unset or <=0 = none)
  auto_approve: false           # keep `forge learn promote` human-gated (default)

budget:                         # per-change spend ceilings (unset or <=0 = none)
  max_tokens: 500000            # token ceiling
  max_usd: 25.00                # dollar ceiling
  max_tool_calls: 2000          # tool-call ceiling

persona:
  mode: forge                   # persona mode — see /guide/components#personas
  language: en

docsite:                        # `forge docsite publish` only — install/dev/build read
                                 # .forge/.docsite-install.json instead, never this section
  target: vitepress             # auto|vitepress|docusaurus|mintlify|starlight|mkdocs|neutral
  out: docs                     # output dir (default: derived from detection)
  pattern: auto                 # information-architecture pattern
  sections:                     # default: [guide, reference, decisions]
    - guide
    - reference
    - decisions
  scaffold: true                # write the generator config if missing (default: false)
  llms_txt: true                # also emit /llms.txt (default: true)
  auto_on_archive: false        # regenerate during archive (default: false)
  exclude:                      # kept out of the source scan
    - "**/*_test.go"
    - "vendor/**"
    - "node_modules/**"

models:                         # per-phase provider/model assignments
  explore: anthropic/claude-opus
  design: anthropic/claude-opus
  implement: anthropic/claude-sonnet

mcp:
  servers:                      # default: [context7]
    - context7
    - filesystem

review:
  gate: pre-push                # off|pre-commit|pre-push|ci
  provider: anthropic

guardrails:
  level: guarded                # off|guarded|strict|bypass; only bypass changes
                                # the permissions injected into each agent
  posture: ask                  # reserved: carried through, not read today
  secrets:
    deny:
      - AWS_SECRET_ACCESS_KEY
      - STRIPE_SECRET_KEY
  destructive_actions: ask      # reserved: carried through, not read today

extensions:
  - id: forge-graphql
    version: 1.2.0
  - id: forge-terraform
    version: 0.4.1

Environment variables ​

Select settings can be overridden at the highest precedence for CI or one-off runs — with a per-invocation CLI flag or a FORGE_* environment variable — without editing any file. Because these win over every file layer, they are ideal for temporarily forcing behavior in a pipeline. For example:

forge install --scope workspace           # override install scope for one run
forge install --channel beta              # override release channel for one run
FORGE_ACTOR="ci-bot" forge trace show --change c1   # attribute events in CI
FORGE_BUDGET_MAX_TOKENS=200000 forge run --change c1  # tighten the spend ceiling for one pipeline

Any two-level config key maps to a FORGE_* variable by upper-casing the path and replacing the dot with an underscore: workflow.breaker_threshold becomes FORGE_WORKFLOW_BREAKER_THRESHOLD, budget.max_usd becomes FORGE_BUDGET_MAX_USD.

The FORGE_INIT_* variables (FORGE_INIT_AGENTS, FORGE_INIT_PRESET, FORGE_INIT_SCOPE, FORGE_INIT_YES, …) drive forge init headlessly. For the full flag-and-environment surface, see the CLI reference.

Next steps ​

• The Workflow — what the workflow section controls.
• Agents — the agents the agents section enables.
• Commands — including config explain.
• CLI reference — every flag and its environment-variable equivalent.
• Best Practices — recommended settings.

Components

A component is a self-contained capability Forge can add to your agents — memory, a workflow, an MCP server, a persona layer, a security overlay, or visual polish. forge install reads a catalog of these components and writes only the ones you select into every detected agent. You pick components directly, or pick a preset that bundles a curated set. A persona and an SDD mode layer on top, shaping how the agent speaks and how the workflow runs.

Every knob below maps to a flag on forge install, a terminal command:

forge install --component engram,sdd,skills   # explicit components
forge install --skill sdd-init,go-testing      # explicit skills
forge install --preset forge-full              # a bundled set
forge install --persona forge                  # conversation tone
forge install --sdd-mode multi                 # per-phase sub-agents
forge install --scope workspace                # this project only
forge install --channel stable                 # release channel
forge install --dry-run                        # preview, write nothing

The singular and plural forms are interchangeable — --component and --components, --agent and --agents, --skill and --skills — and each accepts a comma-separated list.

The components ​

Ten components make up the catalog. Each is opt-in and independently installable.

Engram ​

Engram gives your agent memory that survives across sessions. It stores observations, searches them full-text, and recalls project context on demand — so an agent picks up where the last session left off instead of starting cold. Forge drives it through forge memory and forge recall.

SDD ​

SDD installs the spec-driven development workflow — the canonical phase spine from explore through archive, plus its entry and cross-cutting commands. This is the component that turns Forge from a config tool into a development methodology. Pair it with the Skills component to get the SDD skill files that back each phase. See The Workflow.

Skills ​

Skills injects a curated library of skill files into your agent's skills directory. These are the SDD, workflow, and security skills catalogued below — embedded in the binary and written out at install time. Narrow the set with --skill <list> or take the whole library.

Context7 ​

Context7 wires in an MCP server that serves live, version-current framework and library documentation. When your agent needs the current API for a dependency instead of a stale training snapshot, it queries Context7. It runs as a Model Context Protocol server, so agents with MCP support consume it natively.

Persona ​

Persona is the managed layer that controls agent behavior and conversation tone. Installing this component is what lets --persona take effect — it injects the selected persona's voice into your agent's configuration. See Personas for the available voices and the artifacts-vs-replies distinction.

Permissions ​

Permissions installs security-first defaults and guardrails — a sensitive-path deny list and safe defaults that stop an agent from reading secrets or credential files. The overlay applies to the adapters that support a permissions layer (Claude Code and OpenCode). Sensitive paths such as ~/.ssh/**, **/*.pem, **/*.key, **/.env*, and ~/.aws/credentials are denied by default.

GGA ​

GGA is an AI provider switcher — the external gga tool. Installing the component provisions the gga binary globally on your machine. It does not run project-level hook setup automatically; that stays an explicit per-repo decision. After the global install, enable it inside a project yourself:

gga init
gga install

Visual polish ​

Three components are pure cosmetics — install them for a coherent look, skip them with no functional loss.

Presets ​

A preset is a named bundle of components. Pick one with --preset instead of enumerating components by hand. Persona is chosen separately and applied independently of the preset.

flowchart TD
  FG["forge-full"] --> Core
  FG --> Polish
  EO["ecosystem-only"] --> Core
  MIN["minimal"] --> Mem
  CUST["custom"] --> Pick["your choices"]

  subgraph Core["Core components"]
    Engram
    SDD
    Skills
    Context7
    GGA
  end
  subgraph Polish["Visual polish"]
    OT["opencode-theme"]
    CT["claude-code-theme"]
    OL["opencode-logo"]
  end
  subgraph Mem["Memory only"]
    E2["engram"]
    S2["sdd skills"]
  end

Start from the preset closest to what you want, then add or drop individual components on the same command line. Explicit --component and --skill flags compose with the preset — the preset seeds the selection, the flags adjust it.

forge install --preset ecosystem-only --component opencode-theme
forge install --preset custom --component engram,sdd,skills,permissions

Personas ​

A persona controls how the agent talks. The distinction that matters is where the voice applies: to your conversation (replies, status, clarifying questions) versus to generated artifacts (specs, designs, tasks, code comments, UI copy).

• forge — the mentor voice everywhere. Warm, direct, opinionated in both conversation and the files it writes.
• forge-neutral-artifacts — keeps the mentor voice in replies but writes neutral artifacts. Use this when you want the coaching tone in chat but plain, register-neutral specs and comments in the repo.
• neutral — plain voice in both places. No persona flavor in replies or artifacts.
• custom — you supply the persona; Forge leaves it unmanaged and does not overwrite your existing voice configuration.

forge install --persona forge-neutral-artifacts

SDD modes ​

The SDD mode decides how the workflow phases execute.

• single runs the whole spine — explore, propose, spec, design, tasks, implement, verify, archive — inside a single thread. Simplest, works on every agent.
• multi dispatches each phase to a dedicated sub-agent, keeping one thin coordinating thread and isolating each phase's context. It compresses long workflows but requires an agent that supports sub-agents.

forge install --sdd-mode multi --agents claude-code,opencode

The bundled skill library ​

The Skills component ships a fixed library, embedded in the binary and written into your agent's skills directory. Skills are grouped by category and carry a priority — p0 skills install first, p1 skills follow. Take the whole library, or narrow it with --skill <list>.

SDD skills ​

The phase engine behind the SDD workflow — one skill per phase, plus init, onboard, and the fast-forward helpers.

Workflow skills ​

Testing, review, PR and issue hygiene, documentation, and commit discipline.

Security skills ​

Guardrails, audits, and supply-chain checks that back the /forge.security agent skill and the forge secscan command.

After installing skills, forge skill-registry refresh rebuilds the index of installed skills — triggers, scopes, and exact paths. See Skills.

Install scope and channel ​

Two flags decide where the configuration lands and which release you track.

Scope — --scope global|workspace:

• global (default) writes agent configuration to your user-level agent directories, so every project on the machine sees the Forge command set.
• workspace writes for the current project only, keeping the configuration local to this repository.

Channel — --channel stable|beta|nightly:

forge install --scope workspace --channel stable
forge install --scope global --channel beta

Scope is settable per install and also in .forge/config.yaml under agents. The flag wins for a single run; the config value is the standing default. See Configuration.

Next steps ​

• Commands — the command set every component's install writes.
• Agents — which agents receive the configuration.
• Configuration — set standing defaults for scope and personas.
• Memory — how the Engram component persists context.
• Skills — the skill library in depth.

Extensions

An extension is a self-contained bundle of slash commands (and, additively, skills) that installs into a project and registers itself with every already-configured coding agent. This page is for authoring one. For the user-facing install/list/search/remove workflow, see the forge extension CLI reference.

Two kinds of extension ​

• Manifest-based — the standard kind, described on this page: an extension.yml plus the files it references, installed with forge extension add.
• Agent-built — the output of forge agent-build, which generates a skill from a natural-language description and registers it under the same .registry index (so it shows up in forge extension list/remove) without ever having an extension.yml. It is out of scope for authoring by hand and not covered further here.

Directory layout ​

A minimal extension source directory looks like this:

my-extension/
├── extension.yml
└── commands/
    └── run.md

extension.yml must sit directly inside the source directory you pass to forge extension add — it is read as <source>/extension.yml. Every other path a manifest declares (provides.commands[].file, provides.skills[].path, provides.config[].template) is resolved relative to that same source directory.

This source directory can live anywhere on disk — a sibling folder, a separate Git repo you're developing, /tmp, wherever. It has no required location relative to the project you're installing into.

Where it ends up ​

forge extension add copies that source directory into the target project at:

<root>/.forge/extensions/<id>/

<root> is resolved from --cwd if you pass it, otherwise it's simply the directory you ran forge extension add from — not a discovered project root. There is no upward search for a .forge/ directory or a .git root: running the command one level below your actual project creates a second, sibling .forge/extensions/ there. Always pass --cwd <project-root> (or run the command from the project root itself) when you're not already sitting in it.

Alongside .forge/extensions/<id>/ (the copied manifest + files), .forge/extensions/.registry is a single JSON file tracking every installed extension's version, source, manifest hash, install time, enabled/disabled state, and exactly which command files were written per agent.

The extension.yml manifest ​

schema_version must currently be exactly "1.0" — any other value is rejected. Unknown top-level or nested fields are silently ignored, not an error, so a manifest can carry forward-compatible extra fields safely.

extension block (required) ​

requires block (required) ​

At least one of speckit_version or forge_version must be set — an empty requires: {} is rejected.

provides block (required) ​

provides.commands[]

provides.skills[].path and provides.config[].template are validated with the same relative-path/no-traversal rule as commands[].file.

Top-level hooks and tags ​

• hooks is a map of event name (e.g. after_tasks) to {command, optional?, prompt?, description?, condition?}. It is parsed and stored, but nothing currently executes a hook — there is no lifecycle dispatch that looks a command up here and runs it. Treat it as reserved.
• tags is a list of strings used for catalog search/discovery.
• defaults is an arbitrary map, round-tripped through the manifest for a future config-merge feature; no merge logic is wired up today.

Path-traversal validation ​

Every manifest-supplied path (commands[].file, commands[].aliases[], skills[].path, config[].template) is checked before the extension is ever installed: an absolute path, a .. segment that would escape the extension's own directory, or (for aliases) any path separator at all, fails validation with a parse error. This is enforced twice — once in the manifest parser and again at the point each path is actually read from or written to disk.

A complete example ​

schema_version: "1.0"

extension:
  id: "my-extension"
  name: "My Extension"
  version: "1.0.0"
  description: "Adds a /forge.my-extension.run command"
  author: "Your Name"
  repository: "https://github.com/you/my-extension"
  license: "MIT"

requires:
  forge_version: ">=1.0.0,<2.0.0"

provides:
  commands:
    - name: "forge.my-extension.run"
      file: "commands/run.md"
      description: "Run the extension's main command"
      aliases: ["my-ext-run"]

tags:
  - "example"

With the referenced command file:

---
description: Run the extension's main command
---

Run: $ARGUMENTS

This mirrors the shape of the fixtures forge-kit's own test suite validates against (internal/extensions/testdata/compatible-extension, internal/extensions/testdata/speckit-v1-extension).

Commands: how they get registered ​

forge extension add renders each provides.commands[] entry (and each of its aliases) into the native command format of every coding agent that is already configured in the project — detected by whether that agent's top-level directory (e.g. .claude/, .cursor/) already exists at the repo root. An agent with no existing directory is skipped entirely; run forge init (or otherwise configure the agent) before installing an extension you expect it to pick up commands for.

The rendering does three things to each command's Markdown source:

1. Splits YAML frontmatter (description: ...) from the Markdown body.
2. Replaces $ARGUMENTS in the body with the target agent's own placeholder token (most agents also use $ARGUMENTS; Gemini CLI and Qwen Code use {{args}}).
3. Appends an HTML-comment footer recording which extension the command came from and where its config lives: <!-- Extension: <id> --> / <!-- Config: .forge/extensions/<id>/ -->.

Markdown-format agents (Claude Code, Cursor, Copilot, Windsurf, and others) get the rendered frontmatter + body written as <name>.md. TOML-format agents (Gemini CLI, Qwen Code) get a description = "..." / prompt = """...""" TOML file instead.

If a command file it needs to write already exists (created by something other than this extension), its prior content is captured before being overwritten and restored automatically if you later forge extension remove the extension — the extension's own footprint is removed, and whatever it clobbered is put back rather than deleted.

Installing ​

forge extension add ./my-extension

forge extension add <arg> accepts three forms, checked in this order:

1. A URL (contains ://) — downloaded as a zip archive and extracted, bypassing the catalog entirely.
2. An existing local directory — used as-is. This is the form to use while developing an extension.
3. Anything else — looked up as a catalog ID (see Distribution below).

On success it prints:

installed extension "my-extension" (My Extension) v1.0.0

The extension is copied into .forge/extensions/<id>/, its commands are registered for every configured agent, and an entry is written to .forge/extensions/.registry recording its version, source, a sha256:<hex> hash of the installed manifest, install timestamp, and exactly which command files were written per agent (so forge extension remove can undo precisely that).

Re-adding an already-installed ID fails with extension "<id>" is already installed; remove it first.

Local development workflow ​

There is no --dev/watch/symlink mode — Install always does a full byte copy of the source directory (internal/extensions/engine.go's copyDir), and forge extension update only works against a catalog entry (see Version compatibility note below), so a local extension can't self-update. The loop is: edit source → remove → add.

1. Scaffold the source directory anywhere on disk:

   sh

   mkdir -p my-extension/commands

2. Write extension.yml at my-extension/extension.yml (see the manifest reference and complete example above).

3. Write each command file it references, e.g. my-extension/commands/run.md.

4. Install it into the project you want to test it in, passing an explicit --cwd if you're not standing in that project's root:

   sh

   forge extension add ./my-extension --cwd /path/to/target-project

5. Confirm what actually landed — the copied files, the registry entry, and which agents picked up the command:

   sh

   forge extension info my-extension --cwd /path/to/target-project

   Cross-check the rendered command file directly, e.g. /path/to/target-project/.claude/commands/forge.my-extension.run.md, to see the exact frontmatter/body/footer your agent will load.

6. Exercise the command in the target agent (e.g. run /forge.my-extension.run in Claude Code) to confirm it behaves as expected.

7. Iterate: edit the source files under my-extension/, then reinstall — there's no in-place update for a local install:

   sh

   forge extension remove my-extension --cwd /path/to/target-project
   forge extension add ./my-extension --cwd /path/to/target-project

8. Bump extension.version in the manifest once the extension is stable enough to distribute (see Distribution) — the version string is display-only for a local install (nothing compares it), but it's what forge extension update and forge extension info will show consumers once you publish it.

Version compatibility ​

requires.forge_version is a comma-separated list of AND'd clauses against major.minor.patch, e.g. >=1.0.0,<2.0.0. Supported operators: >=, <=, >, <, ==/=, !=.

• Set and not satisfied — install fails with: extension "<id>" requires forge <constraint>, but <version> is installed
• Malformed constraint — install fails with: extension "<id>" has invalid requires.forge_version "<constraint>": <parse error>
• Unset (an extension that only declares requires.speckit_version) — accepted unconditionally; a forge version is never compared against a Spec-Kit constraint.
• Running forge build has no known version (an unbuilt go run/dev build, where the version resolves to "dev") — the check is skipped and the extension is accepted regardless of its constraint.

Distribution ​

Today there are exactly two ways to distribute an extension: a local directory (forge extension add ./path) or a downloadable zip at a URL (forge extension add https://.../my-extension.zip, or a catalog entry whose download_url points at one). The zip is extracted and extension.yml is located either at the archive root or its first immediate subdirectory (matching how GitHub's own "Download ZIP" wraps a repo in a single <repo>-<ref>/ folder).

forge extension list|search|info read from an embedded catalog snapshot compiled into the forge binary — no network access is required for those to work. No project- or maintainer-facing process for submitting an extension to that catalog exists in the codebase today; distributing an extension outside your own project currently means sharing a URL or a Git repository people add directly.

Referencing an extension in .forge/config.yaml ​

.forge/config.yaml has its own, separate extensions: list:

extensions:
  - id: my-extension
    version: 1.0.0

This is a plain {id, version} record, merged across config layers and shown by forge config explain — it is not what actually installs, enables, or removes anything. The source of truth for what's really on disk is .forge/extensions/.registry, maintained entirely by forge extension add|remove|enable|disable. Nothing was found that auto-installs an extension from this config list; treat it as a declarative note of intent, not a trigger. See the Configuration guide's extensions section for the full config schema.

See also ​

• forge extension CLI reference — the list/add/remove/search/info/update/enable/disable subcommands.
• Configuration guide — the extensions: config key.

Commands

Forge exposes commands across two surfaces, and they are not the same set. The forge binary is a deterministic Go program with its own set of terminal commands — it is never in the LLM inference loop. Separately, Forge installs a family of /forge.* agent slash-commands (skills) into each configured agent. The two surfaces overlap for some commands, but many commands live on only one of them.

• Terminal forge <name> commands — the deterministic binary. Setup and lifecycle (install, init, sync, uninstall, restore, update, upgrade, doctor, config explain), analysis and status (analyze, health, drift, verify, archive, sdd-status, sdd-continue), the harness gates and runtime (budget, secscan, trace, docs, panel, review, hook, metrics, mcp serve, run), the brand/design seeds (brand, design), reporting (board, roadmap, wireframe), delivery (deliver, issues create), and the platform plumbing (import, migrate, memory, recall, skill-registry, skill-discover, extension, agent-build, learn, profile, provider, workspace, codegraph).
• /forge.* agent skills only — the SDD spine (explore, propose, specify, clarify, plan, tasks, implement), foundation authoring (constitution, security, infra), and most cross-cutting commands (reconcile, refine, pseudocode, checklist, levelup, discover, export, taskstoissues, brainstorm). There is no forge explore or forge reconcile terminal command — these run inside your agent.

Command map ​

Foundation sets the ground rules once. The spine drives each change from explore to archive. Cross-cutting and harness commands wrap the spine — safe to call at any point, or armed as gates around the implement → verify loop.

flowchart LR
  subgraph Foundation["Foundation — run once"]
    F[constitution / security / infra / brand / design]
  end
  subgraph Spine["Workflow spine — per change"]
    direction LR
    E[explore] --> P[propose] --> S[specify] --> C[clarify]
    C --> PL[plan] --> T[tasks] --> I[implement]
    I --> V[verify] --> A[archive]
  end
  subgraph Around["Cross-cutting & harness — any time"]
    X[analyze · drift · reconcile · refine]
    H[verify-gate · budget · secscan · trace · review]
  end
  F -.-> Spine
  Around -.-> Spine

Entry commands (onboard, new, ff, continue, status) drop you onto the spine at the right phase for the change in hand.

Setup ​

Bootstrap Forge, configure agents, and manage the binary and snapshots.

Setup is terminal only apart from init: these commands install, upgrade, and roll back the binary and its managed config, so they run in your shell rather than inside an agent. /forge.init is the single slash-command in this group.

Workflow spine ​

The canonical SDD phases, in the one order every change follows. A given change traverses a subset of the spine — adaptive depth picks the entry point, never a different ordering. See The Workflow for the full model.

The spine authoring phases (explore through implement) are /forge.* agent skills only — they have no terminal forge <name> form. verify and archive also exist as deterministic terminal commands.

Entry commands ​

Get onto the spine at the right phase for the change in hand.

Cross-cutting ​

Callable at any time and non-destructive, so you can run them freely without disturbing an in-flight change. See The Workflow.

analyze, health, drift, board, and wireframe are deterministic terminal commands; wireframe is the only one of those with no slash-command form. The rest of this group are /forge.* agent skills only — there is no forge reconcile or forge refine binary command.

Harness ​

Runtime guardrails around the implement → verify loop. The enforced gates return a non-zero exit to stop a runaway loop; a host hook or CI step reads that exit and halts. The four enforced controls are verify (circuit-breaker), budget (spend ceiling), secscan, and the review delivery gates. trace, docs, docsite, panel, metrics, and mcp serve are observe-only and never block. run drives the loop itself and obeys those gates rather than adding a new one. See the harness overview.

forge verify --change c1                 # FAIL exits 0, breaker 1/3
forge verify --reset-breaker --change c1 # clear after intervening
forge budget record --change checkout --tokens 600 --max-tokens 1000
forge secscan scan  --change checkout --path leak.txt
forge secscan waive --change checkout --fingerprint 0c9ab6bbabac
forge docs build --out public --publish
forge docsite install --target vitepress
forge docsite publish --target vitepress --out site
forge review validate --gate pre-commit
forge run --change checkout --cmd 'claude -p "implement the next open task"'
forge run --change checkout --cmd '...' --max-iterations 3 --yes

Foundation ​

Standing project truth — run once. These phases set the ground rules the spine operates within, rather than describing a single change. See The Workflow.

constitution, security, and infra are authored entirely through their /forge.* agent skills — there is no forge constitution, forge security, or forge infra terminal command. Only brand and design have deterministic forge seed commands, which write a starter file for the agent to author into.

Platform ​

Migration, memory, skills, repo and workspace detection, delivery, and review plumbing.

Next steps ​

• The Workflow — the phases these commands drive.
• The forge CLI — the terminal binary, real flags, and exit codes.
• Components — agents, skills, and personas the commands install.
• Configuration — tune command behavior.
• Project Structure — where commands write under .forge/.
• Harness overview — the runtime guardrails and enforced gates.

Project Structure

Forge keeps all of its per-project state under a single directory: .forge/. Everything there is plain files you can read, diff, and commit — which is why Forge's state survives context compaction, agent restarts, and team handoffs.

specs/ vs changes/ — the core distinction ​

Two directories carry most of the meaning, and they are easy to confuse. The one-line version:

• specs/ is what the system is. The canonical, settled truth — the current agreed-upon behavior of your project. The deterministic gates read from here: forge drift cross-references these specs against your code, and forge analyze scores these. You don't hand-edit them mid-work; they are the record of decisions already made.
• changes/ is what you are doing to it right now. One directory per in-flight change, each a self-contained workspace for a single unit of work (proposal, exploration, design, tasks, gate state — and a delta spec).

The word that ties it together is delta. The spec inside a change is not the whole truth — it describes only the slice that this change adds or alters. That is deliberate: it keeps every unit of work small, reviewable, and reversible. You reason about one change, not the entire system.

The two connect through promotion, and only in one direction. When every task in a change is Done, forge archive merges that change's delta spec into specs/ (so the canonical truth now reflects the change) and moves the change folder to changes/archive/. Work always flows changes/ → specs/, never the reverse.

Asking "what does this system do?" → read specs/. Asking "what's being worked on?" → look in changes/. A change is a renovation work order scoped to one room; specs/ is the as-built blueprint that gets amended once the work is signed off.

The .forge/ layout ​

.forge/
├── config.yaml            # optional per-project overrides
├── config.local.yaml      # gitignored, per-machine
├── memory/                # constitution, discovery memory, refinement notes
├── specs/{domain}/spec.md # canonical capability specs (promoted from changes/)
├── changes/
│   ├── archive/YYYY-MM-DD-<name>/   # immutable audit trail
│   └── <change-name>/
│       ├── state.yaml           # DAG state (survives compaction)
│       ├── exploration.md proposal.md plan.md tasks.md verify-report.md
│       ├── data-model.md         # (optional) entities, written by design phase
│       ├── contracts/            # (optional) {interface-name}.md per interface
│       ├── roadmap.md            # (optional) delivery sequencing, written by forge.roadmap
│       ├── test-coverage.md      # (optional) scenario -> test map, written by sdd-tests
│       ├── swarm-log.md          # (optional) wave dispatch record, written by sdd-swarm
│       ├── specs/{domain}/spec.md   # delta spec
│       ├── verify-attempts.yaml     # circuit-breaker state
│       ├── budget.yaml              # spend ledger
│       └── session-log.jsonl        # attributed timeline
├── templates/  skills/  extensions/  backups/  design/
├── site/                  # generated dashboard (forge docs)
└── _imported/             # lossless catch-all from `forge import`

What each part is ​

Top-level files ​

• config.yaml — the single optional per-project override file. Committed with the repo so the whole team shares it. See Configuration.
• config.local.yaml — per-machine overrides. Gitignored so machine-specific settings never leak into the shared config.

memory/ ​

forge init creates this directory empty. It fills up as you run the foundation and discovery commands: .forge/memory/constitution.md from /forge.constitution, project-discovery.md / current-architecture.md / current-capabilities.md / current-gaps.md from /forge.discover, and refinement-suggestions.md / knowledge-index.json as /forge.refine and other commands accumulate context over time. When memory.team_sync is enabled, it doubles as the Engram team-sync export — either way, it is committable, so project memory travels with the repository and every teammate benefits from the same accumulated context.

specs/{domain}/spec.md ​

The canonical capability specifications, organized by domain. These are the project's source of truth for behavior. Specs land here by being promoted from a change's delta spec when that change is archived.

changes/ ​

Home for changes — both in-flight and archived.

• archive/YYYY-MM-DD-<name>/ — the immutable audit trail. Once a change is archived it is frozen here, dated and named, as a permanent record.
• <change-name>/ — an in-flight change directory. Its contents:
  • state.yaml — the change's DAG state. It survives context compaction, so an interrupted change can always be resumed.
  • exploration.md, proposal.md, plan.md, tasks.md, verify-report.md — the phase artifacts (see the phase-to-artifact map).
  • data-model.md (optional) — entities and data structures, written by the design phase only when the change introduces or modifies any.
  • contracts/{interface-name}.md (optional) — one file per new or modified external-facing interface, written by the design phase when applicable. Both companions are skipped for purely internal changes.
  • roadmap.md (optional) — the task execution graph sequenced into a value-first delivery order of vertical slices, written by /forge.roadmap once tasks.md's execution graph exists.
  • test-coverage.md (optional) — a scenario -> REQ ID -> test file map for the RED-phase tests it generates, written by sdd-tests.
  • swarm-log.md (optional) — a wave-by-wave dispatch, specialist classification, and conflict record, written by sdd-swarm when it implements a change's tasks in parallel instead of sdd-apply's sequential path.
  • specs/{domain}/spec.md — the delta spec: the change's proposed additions/edits, merged into canonical specs/ on archive.
  • verify-attempts.yaml — the circuit-breaker state that bounds verify loops. See circuit-breaker.
  • budget.yaml — the spend ledger for this change.
  • session-log.jsonl — the attributed timeline of what happened, line by line.

Supporting directories ​

• templates/ — not created by forge init. It only appears when forge import specify brings over an existing Spec-Kit project's .specify/templates/; the foundation and spec commands draft their artifacts directly and never require it to exist.
• skills/ — project skills.
• extensions/ — installed extensions.
• backups/ — automatic snapshots taken before mutations (used by forge restore).
• design/ — design-system artifacts from the design foundation phase.

site/ ​

The generated dashboard, produced by forge docs. Serve it with forge docs serve to browse your specs, changes, tasks, budget, and timeline. See the dashboard overview.

_imported/ ​

A lossless catch-all populated by forge import. When you migrate an existing project, anything that does not yet map cleanly onto Forge's model lands here rather than being dropped. See migration.

Agent files live outside .forge/ ​

Not everything Forge writes lives under .forge/. Agent-specific directories are written wherever each agent expects them — for example .claude/commands/ and .claude/agents/ for Claude Code. This keeps Forge's own state cleanly separated from each agent's native configuration, and it is how the same unified command set appears natively inside every configured agent.

See Agents for how per-agent adapters map commands into each agent's native format.

Next steps ​

• The Workflow — how artifacts are produced and promoted.
• Configuration — the config.yaml / config.local.yaml files.
• Agents — where per-agent files are written.
• Dashboard — the site/ output.

Agents

Forge configures a superset of 24 AI coding agents — plus a generic adapter for anything else. Its core is agent-agnostic: a single unified command set is translated by per-agent adapters into each agent's native command format and directories. Every command is written as a /forge.<name> slash command in whatever form that agent expects.

Recommended: Claude Code ​

Claude Code is the recommended agent and has the fullest support:

• Subagents via the Task tool
• Output styles
• MCP (Model Context Protocol) servers
• Hooks

These capabilities let the harness integrate most deeply — the circuit-breaker, budget ledger, and attributed timeline can auto-populate from live agent activity. See live agent hooks.

Supported agents ​

Beyond Claude Code, Forge drives twenty-three more agents. Each receives the same /forge.<name> command set through its own adapter. The Sub-agents column marks the agents that can run the SDD workflow in --sdd-mode multi — one thin coordinating thread dispatching each phase to a dedicated sub-agent. The rest fall back to single-thread execution.

Claude Code supports sub-agents too — see above. See SDD modes for what multi changes.

The generic adapter ​

For anything not covered by a dedicated adapter, Forge provides a generic adapter — a bring-your-own command directory. Point it at a command directory and Forge writes the same /forge.<name> command set there, so even agents without first-class support can drive the Forge workflow.

How adapters work ​

flowchart TD
  Core[Agent-agnostic core] --> A1[Claude Code adapter]
  Core --> A2[Cursor adapter]
  Core --> A3[OpenCode adapter]
  Core --> A4[... 13 more adapters]
  Core --> Gen[generic adapter]
  A1 --> D1[.claude/commands/, .claude/agents/]
  A2 --> D2[Cursor native dirs]
  A3 --> D3[OpenCode native dirs]
  Gen --> DG[your command dir]

Each adapter translates the unified configuration into its agent's native command format and directories, and writes each command as a /forge.<name> slash command. Agent-specific files are written outside .forge/ — for example Claude Code's commands and subagents live under .claude/commands/ and .claude/agents/. See Project Structure.

Detecting and enabling agents ​

Forge detects which agents are installed on your machine — it never asks you to name them. forge install configures every detected agent by default. You can narrow that:

forge install --agents claude-code,cursor,opencode

Or restrict enabled agents in configuration:

agents:
  scope: workspace
  enabled:
    - claude-code
    - cursor

See Configuration for the full agents section.

Next steps ​

• Installation — run forge install to configure your agents.
• Commands — the command set every agent receives.
• Components — SDD modes and what multi needs.
• Project Structure — where agent files are written.
• Live agent hooks — connect the harness to your agent.

Best Practices

Getting the most out of Forge is less about configuration and more about leaning into the workflow. These practices help Forge do what it does best: keep your specs, code, and team in sync while protecting you from runaway loops and stale truth.

Let adaptive depth pick the ceremony ​

Adaptive depth triages each change and chooses how much of the spine it needs. Trust it — don't force a mode. A trivial docs fix fast-forwards; a payments change takes the full spine. Forcing every change to the same depth either adds friction to small work or under-scrutinizes risky work.

Keep the constitution current ​

The constitution is standing project truth, and it is load-bearing: constitution conflicts cap the analyze quality score. A stale constitution quietly drags down every quality assessment. Revisit it whenever your principles or constraints change, so the score reflects reality rather than drift against an outdated document.

Commit .forge/ so the team shares specs ​

Everything under .forge/ is plain files. Commit it so your whole team shares the same specs, changes, and memory. When .forge/ is versioned with the code, specs travel with the repository, in-flight changes can be resumed by anyone, and project memory compounds across the team.

Run the dashboard while you work ​

Keep the generated dashboard open as you work:

forge docs serve

It gives you a live view of specs, changes, task status, budget, and timeline — so you always know where a change stands. See the dashboard overview.

Connect the harness to your agent via hooks ​

Wire the harness into your agent with hooks so the runtime guardrails auto-populate from live activity. Once connected, the circuit-breaker, budget ledger, and attributed timeline fill in automatically as your agent works — no manual recording. See live agent hooks.

Use the circuit-breaker to stop runaway loops ​

Verification runs under a circuit-breaker that halts runaway verify/implement loops before they burn time and budget. Let it do its job, and tune it when a change legitimately needs more attempts. See circuit-breaker.

Run analyze and drift periodically ​

Make analyze and drift part of your rhythm, not just a final gate:

• analyze gives a 100-point quality score for the current state.
• drift surfaces Ghost (code with no spec), Phantom (spec with no code), and Mutated (code and spec disagree) divergence.

Catching drift early keeps specs/ trustworthy. See cross-cutting commands.

Archive completed changes ​

Archive changes as soon as they pass verify. Archiving promotes the change's delta specs into canonical specs/ and freezes the change in the immutable audit trail. Leaving finished work un-archived lets specs/ fall behind what the code actually does.

Migrate existing projects with forge import ​

Adopting Forge on an existing codebase? Migrate with forge import instead of rewriting. Import brings your project into Forge's model losslessly — anything that does not map cleanly lands in _imported/ rather than being lost — so you adopt the workflow without throwing away existing structure. See migration.

Summary ​

Next steps ​

• The Workflow — the spine these practices support.
• Configuration — settings referenced above.
• Circuit-breaker — bound your verify loops.
• Migration — adopt Forge on existing projects.

Spec-Driven Development

In plain words: most teams write code first and let the documentation catch up later — which means the docs quietly go stale the moment the code changes. SDD flips that: the plan (the "spec") is written and kept correct first, and the code is treated as something generated and checked against it, the way a house is built from a blueprint rather than the blueprint being redrawn after the fact to match whatever got built.

For decades, code has been king. Specifications served code — they were scaffolding you built and discarded once the "real work" began. PRDs guided development, design docs informed implementation, but every one of them was subordinate to the code itself.

Spec-Driven Development (SDD) inverts this. Specifications don't serve code — code serves specifications. The proposal isn't a guide for implementation; it's the source that generates it. The technical plan isn't a document that informs coding; it's the precise definition that produces the code. Forge is the runtime that makes that inversion enforceable rather than aspirational.

What SDD inverts ​

The traditional loop treats the spec as a lossy prelude. You write intent in prose, translate it by hand into code, and the moment the two diverge the code wins by default — because the code is what runs. The prose rots.

SDD flips the authority. The spec is the artifact you maintain; the code is its expression in one particular language and framework. Maintaining software means evolving specifications, then regenerating and verifying the code that satisfies them. A pivot stops being a manual rewrite and becomes a systematic regeneration.

graph LR
  Idea["Idea"] -->|dialogue| Spec["Specification"]
  Spec -->|clarify| Plan["Technical plan"]
  Plan -->|tasks| Exec["Task graph"]
  Exec -->|implement| Code["Code + tests"]
  Code -->|verify| Delivery["Validated delivery"]
  Delivery -->|archive| Canon["Canonical spec"]
  Canon -.->|next change| Spec

The three layers, kept separate ​

A specification artifact carries three distinct concerns. Collapsing them into one undifferentiated document is the failure mode that breaks spec-driven workflows the instant an upstream assumption pivots. Forge keeps them in separate, separable layers.

The load-bearing rule: scale and non-functional targets are intent, not implementation. "1M concurrent users" and "recover within 30s of an AZ failure" drive the architecture — so they are authored as intent, and the technical design consumes them rather than re-authoring them. That separability is what makes pivots cheap: swapping a deploy target invalidates only the implementation layer, never the intent or the contract above it.

The spine that carries the layers ​

Forge threads the three layers through one canonical SDD spine — the same ordered phases for every change:

flowchart LR
  E[explore] --> P[propose] --> S[specify] --> C[clarify]
  C --> PL[plan] --> T[tasks] --> I[implement]
  I --> V[verify] --> A[archive]

explore → propose → specify → clarify → plan → tasks → implement → verify → archive. Each phase writes a specific artifact — proposal.md, a delta spec, plan.md, tasks.md, verify-report.md — and every artifact is a file you can read, diff, and commit. The plan phase may also write optional data-model.md and contracts/{interface-name}.md companions alongside plan.md, when the change introduces or modifies entities or external-facing interfaces. specify and clarify author the intent and contract layers; plan derives the implementation layer; verify proves the code satisfies the contract before anything is promoted.

Every change is a subset of this spine, never a different one. Adaptive depth decides where a change enters — a typo fast-forwards to implement → verify; a bounded feature runs the Standard path; anything on a hot path or over 400 changed lines runs the full spine. The ordering never changes, only how much of it a given change traverses.

The constitutional foundation ​

At the base of every change sits a constitution — the immutable principles that govern how specifications become code. It is a foundation phase: you author it once with /forge.constitution, alongside the other standing-truth phases (security, infra, brand, design), and the spine operates within the ground rules it sets.

Typical articles read as constraints the model cannot argue its way past:

• Test-first — no implementation before its tests are written and approved.
• Simplicity — start simple; justify every added layer.
• Observability — everything inspectable and testable.
• Modularity — features begin as standalone, reusable units.

Principles are immutable; their application evolves through dated amendments. And the constitution is load-bearing in a mechanical sense: conflicts against it cap your analyze quality score, so a stale constitution quietly drags down every assessment until you bring it current.

How constraints beat prompts ​

The reason SDD produces stable specs is not exhortation — it's structure. Forge renders phase instructions and templates that constrain what the model is allowed to produce, and the harness verifies the parts that must not be left to narration.

• Preventing premature implementation. The spec phase forces WHAT and WHY and defers HOW, keeping the intent and contract layers stable as technologies change.
• Forcing explicit uncertainty. Open questions are marked, not guessed. A "login system" is flagged for /forge.clarify rather than silently assumed to mean email-and-password.
• Structured thinking. Checklists act as unit tests for the spec — nothing forgotten, every requirement testable.
• Constitutional gates. The plan phase must pass the constitution's gates — simplicity, anti-abstraction — before proceeding.

Drift is the enemy the spine defends against ​

Because the spec is authoritative, the only real risk is code and spec silently diverging. Forge names that risk and hunts it. /forge.drift classifies divergence into three kinds:

• Ghost — code with no spec behind it.
• Phantom — spec with no code implementing it.
• Mutated — code and spec that disagree.

/forge.reconcile brings the two back into agreement, and /forge.analyze produces a reproducible 100-point quality score you can track over time. These are cross-cutting and non-destructive — run them at any point without disturbing an in-flight change.

Promotion makes the spec canonical ​

A change lives in its own directory while in flight. Its spec is a delta spec — the slice of truth this change adds or alters. On archive, and only after verify passes, that delta is promoted into the canonical .forge/specs/{domain}/spec.md, and the change moves into the immutable archive.

flowchart LR
  Delta[".forge/changes/<name>/ delta spec"] --> Verify[verify]
  Verify --> Archive[archive]
  Archive --> Canon[".forge/specs/{domain}/spec.md"]
  Archive --> Trail["changes/archive/YYYY-MM-DD-<name>/"]

This is where the inversion becomes concrete. The canonical spec is not a record of what someone once intended — it is the accumulated, verified source of truth that the next change reads, extends, and regenerates from. Archive is gated on honesty: it stays blocked while any task is unfinished, so a promoted spec is always a real signal that the work behind it is done.

Traditional vs. SDD ​

The economics are the point. Under the traditional loop, documentation is a tax you pay before the real work and abandon afterward:

PRD (3 hours) → Design docs (3 hours) → Project setup (30 min)
→ Technical specs (4 hours) → Test plans (2 hours) → Implementation
Total documentation: ~12 hours — then it rots

Under SDD the same artifacts are produced in minutes, stay authoritative, and drive the code rather than trailing it:

/forge.specify (5 min) → /forge.clarify (5 min) → /forge.plan (5 min)
→ /forge.tasks (5 min) → /forge.analyze (2 min) → /forge.implement
Total documentation: ~15 minutes — and the docs are the source of truth

This is not about replacing developers or automating creativity. It's about amplifying human capability by automating mechanical translation — a tight loop where specification, design, and code evolve together, each iteration tightening the alignment between intent and implementation.

Next steps ​

• The workflow — the spine, foundation phases, and adaptive depth in practice.
• Commands — every phase as a CLI and /forge.* slash command.
• Persistent memory — how intent survives across sessions and teammates.
• The enforcement doctrine — where the methodology stops advising and starts enforcing.

Persistent memory

A spec-driven workflow only pays off if intent survives. The decision you made in clarify last Tuesday, the reason a domain boundary sits where it does, the bug that taught you to never retry a non-idempotent call — none of that can live only in a chat transcript that vanishes at the next context compaction. Forge gives every project a durable memory so that context accumulates instead of evaporating.

That memory is backed by Engram, a spec-memory store. Forge wires Engram into your configured agents and exposes it through first-class commands; Engram owns the store itself. This page explains what gets remembered, how it fills up across the SDD spine, how a team shares it, and exactly which Forge commands touch it.

What Forge wires vs. what Engram owns ​

The boundary is deliberate and worth stating up front, because it explains why Forge never invents a memory schema.

flowchart LR
  Phase["SDD phase / agent"] -->|save + search| Forge["forge memory / recall"]
  Forge -->|MCP tools| Engram["Engram backend"]
  Engram --> Disk[".forge/memory/ export"]
  Disk -->|commit| Git["Git — shared with the team"]

What memory remembers ​

The unit of memory is the observation — a discrete, retrievable fact distilled from the work. A save writes one; a search or recall reads them back by relevance. An observation is not a chat log. It's the distilled residue of a decision — "auth tokens are rotated every 15 minutes because of the AZ-failover requirement", "the payments domain owns idempotency keys, not the API layer" — the kind of thing you'd otherwise re-derive from scratch three sprints later.

The observations worth keeping fall into a few recurring kinds:

You interact with observations at the concept level through three operations — save, search, and pull-into-context — and never touch Engram's internal storage directly.

How memory fills up across the spine ​

You do not manage memory by hand for the common case. As each SDD phase runs, Forge's phase instructions have the agent save what it learned and recall what's relevant before it acts. Memory accumulates as a side effect of doing the work.

flowchart LR
  E[explore] -->|recall prior<br/>decisions| M[(Engram)]
  S[specify] -->|save intent<br/>+ open questions| M
  C[clarify] -->|save resolved<br/>ambiguities| M
  I[implement] -->|save decisions<br/>+ bug fixes| M
  V[verify] -->|save outcomes| M
  A[archive] -->|save the<br/>change summary| M
  M -.->|informs next change| E

• explore opens by recalling prior decisions relevant to the change's intent, so investigation starts from accumulated context rather than a blank slate.
• specify and clarify save the intent and the resolutions to open questions, so the why behind each requirement is retrievable, not just the what.
• implement saves the decisions and bug fixes made while writing code — the details that never make it into a spec but cost hours to rediscover.
• archive saves a summary of the finished change, closing the loop so the next explore inherits it.

Project detection keeps memory scoped ​

Memory is grouped by project, and Engram detects the project automatically — it reads your Git remote URL at startup, normalizes it, and uses that as the project name. Outside a Git repo it falls back to the directory name. You never label a project by hand, and the same repository stops accumulating memories under three slightly different names.

The commands that touch memory ​

Three surfaces reach the store. Use whichever fits the moment — they hit the same Engram backend.

For the exact subcommands and flags, see Commands. forge recall is intentionally read-only and non-blocking: it feeds context in, never gates a change.

# save a deliberate decision
$ forge memory save "payments domain owns idempotency keys"   # exit 0

# search before you re-derive something
$ forge memory search "idempotency"                           # exit 0

# pull it into a new change's exploration
$ forge recall                                                # exit 0

Team sharing by committing memory ​

Memory is local by default. To share the accumulated context of a project with your team, you export it and commit that export to Git. forge memory sync writes the shareable memory to .forge/memory/, and from there it is just files in your tree.

# after a work session, export memories into .forge/memory/
$ forge memory sync                                           # exit 0

# then commit them like any other project file
$ git add .forge/memory/ && git commit -m "share project memory"   # exit 0

A teammate who clones the repo gets that memory with it and starts with the full, accumulated context of the project — every decision, convention, and hard-won bug fix the team recorded. This is where memory pays off most: onboarding. A new contributor doesn't begin cold; they begin with the team's collective understanding already loaded, and the SDD spine keeps adding to it from their very first change.

Next steps ​

• Spec-driven development — why durable intent is the point of the whole method.
• The workflow — the spine whose phases populate memory.
• Commands — the full forge memory and forge recall surface.
• The enforcement doctrine — what Forge enforces, and why memory stays advisory.

Drift and reconcile

Specs and code want to diverge. You edit code under deadline and forget the spec; you draft a spec and never build it; a refactor changes a shape the spec still describes the old way. Left alone, that divergence — drift — makes .forge/specs/ untrustworthy, and an untrustworthy spec is worse than none. Forge gives you two commands to keep the two sides honest: /forge.drift detects divergence, and /forge.reconcile resolves it. Both are non-destructive to run, so you can call them freely at any point.

Drift is spec-versus-code divergence ​

Drift is any place where your specs and your code no longer describe the same system. forge drift — the CLI command — cross-references .forge/specs/ against the codebase and sorts every divergence into one of three classes.

flowchart TD
  Start{Compare spec <-> code} -->|code, no spec| G[Ghost]
  Start -->|spec, no code| P[Phantom]
  Start -->|both, shapes disagree| M[Mutated]