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

::: info Where each command runs
The **Surface** column in every table below names exactly where a command runs:
`CLI` for a terminal `forge <name>` command, `/forge.<name>` for an agent skill,
or both when a command is available on each surface. Every stateful terminal
command reads and writes **`.forge/`** in the target repo; point it elsewhere
with `--cwd <repo>`.
:::

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

```mermaid
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 &amp; harness — any time"]
    X[analyze &middot; drift &middot; reconcile &middot; refine]
    H[verify-gate &middot; budget &middot; secscan &middot; trace &middot; 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.

| Command | Aliases | Surface | Description |
| --- | --- | --- | --- |
| `install` | — | CLI only | Detect the agents present on the machine and write the Forge command set into each one's native config (e.g. `.claude/commands/`). Backs up existing config first and is **idempotent**; scope with `--scope workspace`, preview with `--dry-run`. |
| `init` | — | CLI · `/forge.init` | Initialize this repo's **`.forge/config.yaml`** and the `.forge/` tree — run once per repository. The wizard walks defaults; `--yes` accepts them headlessly for CI. |
| `sync` | — | CLI only | Re-apply agent configs and skills to the current binary version. Run it after `upgrade` to converge managed files without a full reinstall. |
| `doctor` | — | CLI only | Environment health check — agent detection, `.forge/` presence and writability, embedded assets, and dependencies (Node, Engram, …) — the counterpart to `install`. Plain `doctor` is read-only; add `--fix` to attempt remediation of failed and warning dependency checks, then re-report. `--selftest` runs an in-process smoke test of the core commands instead, with no repository or dependency checks — the right one to run right after installing the binary, before a project exists. |
| `update` | — | CLI only | Report and fetch the latest available release. Does not touch `.forge/` state. |
| `upgrade` | — | CLI only | Apply a binary-only self-update. Does not touch `.forge/` state. |
| `restore` | — | CLI only | Roll back Forge-managed config to a previous snapshot — always recoverable to a known-good state. Forge snapshots automatically before every mutating operation, so there is no separate `backup` command to run first. |
| `uninstall` | — | CLI only | Remove Forge-managed files from this machine. A snapshot is captured automatically first, so `restore` can always roll it back. |
| `config explain` | — | CLI only | Print the fully resolved configuration and, for each value, the **origin layer** it came from (defaults, `config.yaml`, or the gitignored `config.local.yaml`). |

## 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](/guide/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.

| Command | Aliases | Surface | Description |
| --- | --- | --- | --- |
| `explore` | — | `/forge.explore` | Investigate the codebase and compare approaches before committing to a direction; writes `exploration.md` and consults memory for prior decisions. Run first on substantial or hot-path changes. |
| `propose` | — | `/forge.propose` | Turn exploration into intent — draft **`proposal.md`** with the scope, approach, and rationale, before you pin down exact requirements. |
| `specify` | `spec` | `/forge.specify` | Write the **delta spec** under `changes/<name>/specs/{domain}/spec.md` using **OpenSpec Given/When/Then** scenarios and **RFC-2119** language (MUST / SHOULD / MAY) — the testable contract the rest of the spine is measured against. |
| `clarify` | — | `/forge.clarify` | Resolve the open questions and ambiguities still in the spec before they leak into design and code. |
| `plan` | — | `/forge.plan` | Produce the technical design **`plan.md`** — architecture decisions, chosen approach, and trade-offs. Reads the spec and turns *what* into *how*. May also produce optional **`data-model.md`** and **`contracts/{interface-name}.md`** companions when the change introduces or modifies entities or external-facing interfaces. |
| `tasks` | — | `/forge.tasks` | Slice the design into an ordered, honest-status checklist **`tasks.md`** (`backlog` → `in-progress` → `blocked` → `done`); a task reaches `done` only when its acceptance scenarios pass under `verify`. Every task line carries a required 🟢/🟡/🟠/🔴 complexity tier and an optional `[P]` parallel marker, and the file closes with a machine-readable **`## Execution Graph`** (waves, blockers, critical path, hour estimates) that `estimate`, `roadmap`, and `swarm` all read. |
| `implement` | `apply`, `tdd` | `/forge.implement` | Execute the tasks with **strict TDD by default** (tests before implementation), updating task status in `tasks.md` as it goes and driving the breaker-guarded `verify` loop. |
| `swarm` | — | `/forge.swarm` | Wave-parallel alternative to `implement`, driven by `tasks.md`'s Execution Graph. Classifies non-critical-path tasks to a specialist type (interface/logic/data/test/infrastructure), previews the dispatch plan and waits for confirmation, dispatches up to 5 subagents per wave, runs a consensus checkpoint between waves, then executes critical-path tasks itself, sequentially, in the main thread. Its own engine — not an alias of `implement`. |
| `verify` | — | CLI · `/forge.verify` | Validate the implementation against the spec's acceptance scenarios plus configured tests and lint, writing **`verify-report.md`**. Read-only as a plain command; arms the circuit-breaker with `--change` (see [Harness](#harness)). |
| `archive` | — | CLI · `/forge.archive` | Promote a finished change — merge its delta spec into canonical **`.forge/specs/`** and move it into the dated, immutable `changes/archive/YYYY-MM-DD-<name>/` trail. **Blocked** until every task is `done`. |

::: warning Archive is gated on honesty
`archive` is **blocked** while any task is `blocked` or not `done`. A successful
archive is a real signal that the change is finished and verified — it cannot be
run to paper over incomplete work.
:::

::: tip Two ways onto the spine: direct, or through the entry commands
Every spine phase is directly callable by name (`/forge.propose`, `/forge.specify`, …),
but `propose`, `specify`, `plan`, and `tasks` expect a change that already has
prior context — a proposal to write specs against, a spec to design against, and
so on. In practice most people never call those four directly. Instead:

- `/forge.new <description>` starts a change and gets you to a proposal.
- `/forge.continue` then walks the rest of the spine one phase at a time,
  resolving whichever phase comes next on its own.
- `/forge.ff <name>` blasts through all four planning phases back-to-back when
  the direction is already clear.

Call `propose`/`specify`/`plan`/`tasks` directly when you already know the
change name and want to redo a single phase — `explore`, `clarify`,
`implement`, `verify`, and `archive` are the ones you will type by name most
often. See [Entry commands](#entry-commands) below.
:::

### Entry commands

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

| Command | Aliases | Surface | Description |
| --- | --- | --- | --- |
| `onboard` | — | `/forge.onboard` | Guided walkthrough of a complete SDD cycle on a real change in your codebase — the fastest way to learn the spine hands-on. |
| `new` | `sdd-new` | `/forge.new` | Create a fresh change directory under `.forge/changes/<name>/` and triage its depth — runs `explore` (if warranted) then `propose`. |
| `ff` | `sdd-ff` | `/forge.ff` | Fast-forward all four **planning** phases back-to-back — `propose → specify → plan → tasks` — for a change whose direction is already clear. Interactive mode pauses for confirmation after each phase; auto mode runs straight through. Not to be confused with the *trivial-depth* auto-fast-forward in [adaptive triage](/guide/workflow#adaptive-depth), which skips planning entirely and jumps straight to `implement → verify`. |
| `continue` | `sdd-continue` | `/forge.continue` · CLI `forge sdd-continue` | Resume an in-flight change from wherever it left off — runs the next dependency-ready phase, one at a time. State lives in `state.yaml`, so a change survives context compaction and agent restarts. |
| `status` | — | `/forge.status` · CLI `forge sdd-status` | Print the phase rollup — what is done, what is next, per-task counts — that orchestrators route on. Read-only. |

## Cross-cutting

Callable at any time and **non-destructive**, so you can run them freely without
disturbing an in-flight change. See
[The Workflow](/guide/workflow#cross-cutting-commands).

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

::: warning `drift` is two different engines depending on the surface
`forge drift` (CLI) and `/forge.drift` (agent skill) share a command name but
**not an engine** — the same "share a name, not an engine" split as `forge
roadmap` vs. `/forge.roadmap` below. `forge drift` is a deterministic,
static-analysis-only classifier limited to exactly **three** categories:
**Ghost** (code, no spec), **Phantom** (spec, no code), **Mutated** (they
disagree) — fixed print order, plain-text output, same inputs always produce
the same result. `/forge.drift` detects those same three **plus a fourth,
Inverted** — an architecture/NFR contradiction that requires LLM judgment,
not something static analysis can determine — and renders its own emoji
legend (👻 Ghost, 👁 Phantom, 🔀 Mutated, 🔄 Inverted) instead of the CLI's plain
text. See [Drift and reconcile](/concepts/drift-and-reconcile) for what
Inverted means and why it cannot be deterministic.
:::

::: warning `roadmap` is two different things depending on the surface
`forge roadmap` (CLI) and `/forge.roadmap` (agent skill) share a name but
**not an engine** — the same "share a name, not an engine" split as
`forge.design` vs. `sdd-design`. `forge roadmap` is a deprecated CLI alias for
`forge board`'s deterministic, portfolio-wide phase-status matrix. `/forge.roadmap`
is an LLM-driven, **per-change** skill that sequences one change's task
execution graph into a value-first delivery order of vertical slices — it does
not touch the CLI matrix at all. See its row below for details.
:::

::: tip "Tier" means exactly one thing in forge-kit
The word "tier" refers to exactly one concept: the 🟢/🟡/🟠/🔴 task-complexity
marker on each `tasks.md` line (see the `tasks` row above). `health`'s
HIGH/MEDIUM/LOW/UNKNOWN risk classification (row below) and the dashboard's
derived urgency ranking are related-sounding but unrelated concepts — neither
is a "tier," and none of the three currently render on the same screen.
:::

| Command | Aliases | Surface | Description |
| --- | --- | --- | --- |
| `analyze` | — | CLI · `/forge.analyze` | Score spec quality on a reproducible **100-point** scale — a single `<spec-path>` or the whole `.forge/specs` portfolio. Read-only unless `--save`; `--json` for machine output. Constitution conflicts cap the score. |
| `health` | — | CLI · `/forge.health` | Portfolio-wide risk dashboard: every active change's phase progress, verify state, and a HIGH/MEDIUM/LOW/UNKNOWN risk classification, plus a prioritized action list. Read-only unless `--save`. Its own engine — not a rollup of `analyze`. |
| `estimate` | — | CLI · `/forge.estimate` | Idempotent refresh of `tasks.md`'s **Execution Graph** — recomputes waves, blockers, critical path, and hour estimates from the checklist's current tiers, and replaces only that JSON block. Never touches task descriptions or tiers; running it twice with no checklist changes is a no-op. |
| `drift` | — | CLI · `/forge.drift` | Detect code-vs-spec disagreement. The CLI deterministically classifies it into **three** categories — **Ghost** (code, no spec), **Phantom** (spec, no code), **Mutated** (they disagree); the skill additionally detects a fourth, judgment-based **Inverted** category. See the warning above for the split. |
| `reqid check` | — | CLI · `/forge.reqid` | **Advisory** scan of requirement IDs across `.forge/specs` and the active change: flags malformed IDs, duplicates, and IDs whose area prefix does not match the spec domain they live in. Reports only — it never rewrites an ID and never returns a blocking exit code. |
| `reconcile` | — | `/forge.reconcile` | The remedy for drift — bring code and specs back into agreement, walking each conflict interactively. |
| `refine` | — | `/forge.refine` | Improve an existing artifact in place — tighten a spec, design, or task list without starting a new change. |
| `pseudocode` | — | `/forge.pseudocode` | Draft pseudocode for a task before implementation. |
| `checklist` | — | `/forge.checklist` | Generate a review checklist for the current work. |
| `tests` | — | `/forge.tests` | Generate failing red-phase tests straight from the spec's Given/When/Then scenarios, mapped to their `REQ-<AREA>-NNN` requirement and classified contract/integration/unit. Never overwrites an existing test file — appends only new, non-duplicate tests — and writes `test-coverage.md`. Its own engine — not an alias of `implement`. |
| `levelup` | — | `/forge.levelup` | Suggest project-wide improvements. |
| `discover` | — | `/forge.discover` | Survey the codebase for existing capabilities. |
| `export` | — | `/forge.export` | Emit artifacts for use elsewhere. |
| `taskstoissues` | — | `/forge.taskstoissues` | Push `tasks.md` items into an external issue tracker. |
| `brainstorm` | — | `/forge.brainstorm` | Open-ended, unstructured ideation. |
| `board` | — | CLI | Derive the **phase-status board** from the active changes — one row per change, one column per SDD phase — and print it as markdown. Read-only; `--write` also saves `.forge/board.md`. The CLI `forge roadmap` alias is a **deprecated** name for this same command (prints a deprecation notice, defaults `--write` to the legacy `.forge/roadmap.md` path) — it is unrelated to the `/forge.roadmap` skill below. |
| `roadmap` | — | `/forge.roadmap` | **Per-change value-first delivery sequencing**, not the CLI matrix above. Reads the active change's `tasks.md` execution graph (waves/critical_path/blockers) and `spec.md` requirements, groups waves into vertical slices that each deliver one independently testable/usable capability, and sequences those slices by value/testability first, then context locality, always respecting `blockers` as a hard constraint. Writes `.forge/changes/{change}/roadmap.md`. Propose-and-confirm by default. Never presents dates, durations, or invented estimates. |
| `wireframe` | — | CLI only | Per-spec UI detection and deterministic wireframe scaffolding: reads `<spec-path>`, decides whether it describes a UI (keyword heuristic, overridable with `--ui` / `--no-ui`), and embeds a managed **`## Wireframe`** section (ASCII + Mermaid) into the spec. |

::: info `wireframe` writes into the spec
Every other command in this group is read-only. `wireframe` is the exception —
it injects a **managed section** into the target spec using the same
replace-or-append-once mechanism Forge uses for all managed blocks, so re-running
it is idempotent rather than additive.
:::

## 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](/harness/overview).

| Command | Aliases | Surface | Description |
| --- | --- | --- | --- |
| `verify --change <c>` | — | CLI · `/forge.verify` | Verify a named change under the **circuit-breaker**: a single `FAIL` exits `0` but increments the breaker; **N consecutive failures** (`--max-failures N`, else `workflow.breaker_threshold` in config, else 3) return non-zero so the loop stops. State in `changes/<c>/verify-attempts.yaml`; clear with `--reset-breaker`. Add `--isolated` to run the configured tests, lint, and spec read against an **ephemeral copy** of the working tree, so a destructive test cannot damage uncommitted work — it isolates the filesystem working tree only, not processes, network, or `$HOME`, and it requires a git repository. |
| `budget record\|check\|reset` | — | CLI · `/forge.budget` | Enforce a per-change **spend ceiling** against `changes/<c>/budget.yaml`. `record` accumulates reported spend and returns non-zero the moment a ceiling — a `--max-*` flag, else the matching `budget.*` config key — is **strictly** crossed; `check` is the read-only verdict; `reset` clears it. |
| `secscan scan\|waive\|reset` | — | CLI · `/forge.secscan` | Enforced static gate: `scan` flags leaked secrets, PII, and prompt-injection strings and returns non-zero on any **unwaived** finding; `waive` accepts one by **fingerprint**; `reset` clears findings. Scope with `--path`, `--min-severity`. |
| `trace record\|show` | — | CLI · `/forge.trace` | Per-change **session event timeline** in `changes/<c>/session-log.jsonl`. The breaker and budget gate emit into it automatically; `record` your own events, `show` the log. Observe-only — never a gate. |
| `docs build\|serve` | — | CLI · `/forge.docs` | `build` renders the offline, read-only spec-viewer from `.forge/` (`--publish` emits a Pages-ready `public/`). `serve` runs the embedded, **interactive** [web control panel](/features/web-ui) on `127.0.0.1:4321` — it can also run verify, archive, and clear gates. |
| `docsite install\|dev\|build\|publish` | — | CLI only | Two families under one noun. `install`/`dev`/`build` work on the generator Forge installs into **`.forge/` itself**: `install` scaffolds it, `dev` execs its dev server in the foreground, `build` runs its static build — one generated config, shared by both. `publish` renders forge's `.forge/` state into a **public** documentation site you already own (VitePress, Docusaurus, Starlight, Mintlify, MkDocs) — distinct from `docs`, which renders forge's internal dashboard, and from `install`'s own site. `publish` always derives fresh **from `.forge/specs\|changes`** first, then writes the site with ownership tracking; `--source-only` stops after staging, before any render. See [Documentation Site Generator](/features/docsite). |
| `panel` | — | CLI only | Launch the **observe-only** lifecycle control panel as a TUI — it reads state and never mutates it. |
| `hook post-tool-use` | — | CLI only | The **live-agent feeder**: your coding host calls it after each tool use, passing the hook payload on stdin, so real activity lands in the timeline and budget. Best-effort and deliberately fast and silent — it never triggers detection or self-update. See [Connect a live agent](/harness/live-agent-hooks). |
| `review start\|finalize\|validate` | — | CLI only | Bounded review lifecycle producing a **content-bound receipt**: `start` opens against current scope, `finalize` records lens results and evidence, `validate --gate <gate>` checks the receipt against a delivery gate and returns non-zero when the tree no longer matches. |
| `metrics` | — | CLI · `/forge.metrics` | Roll up the harness state Forge already records — verify pass rate and breaker activity, budget spend, secscan waivers, and timeline volume — across every change, to answer whether the harness is actually working. Read-only; `--json` for machine output. See [Harness Metrics](/harness/metrics). |
| `mcp serve` | — | CLI · `/forge.mcp` | Serve the read-oriented harness commands as **MCP tools** over a stdio JSON-RPC session, so an agent can query the gates directly. **Queryable, not enforcing** — a gate's refusal comes back as readable data; enforcement stays with the non-zero exits hooks and CI read. See [Harness as MCP](/harness/mcp). |
| `run` | — | CLI only | The **bounded autonomous loop**: drive an executor across repeated iterations and stop the moment an enforced gate opens. **Dry run is the default** — the plan prints and nothing executes without `--yes`. Bounded by `--max-iterations` (default 5, hard cap 50). Forge supplies no model: you name the command that performs one iteration with `--cmd`. See [Autonomous run](/harness/autonomous-run). |

::: warning Enforced gates block with a non-zero exit
`verify --change`, `budget`, `secscan`, and `review validate` are the controls
that **fail closed**. When one returns non-zero, the loop must stop and escalate
to a human — do not retry past it.
:::

```sh
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
```

::: warning `forge run` executes nothing without `--yes`
The first form above prints the plan — iterations, executor, gates — and exits
without running anything. That is the default and deliberate posture. `--yes`
arms it, `--max-iterations` bounds it (default 5, never above 50), and any
enforced gate opening stops the loop and returns non-zero for a human to pick
up. Forge ships no model of its own: whatever you pass to `--cmd` is the thing
that does the work.
:::

## 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](/guide/workflow#foundation-phases-run-once).

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

| Command | Aliases | Surface | Description |
| --- | --- | --- | --- |
| `constitution` | — | `/forge.constitution` | Capture the project's non-negotiable principles and constraints. Load-bearing: conflicts against it cap your `analyze` score, so keep it current. |
| `security` | — | `/forge.security` | Define the security posture and requirements the spine validates against. |
| `infra` | — | `/forge.infra` | Define the infrastructure baseline that deployment artifacts derive from. |
| `brand` | — | CLI (seed) · `/forge.brand` | Define brand identity and voice; `forge brand` seeds `.forge/design/brand.md`, then `/forge.brand` authors it. |
| `design` | — | CLI (seed) · `/forge.design` | Define the design system and conventions; `forge design` seeds the files under `.forge/design/`, then `/forge.design` authors them. |

::: tip Run these first, revisit rarely
Foundation phases establish standing truth. You run them once at project setup
and update them only when the ground rules genuinely change — not per change.
:::

## Platform

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

| Command | Aliases | Surface | Description |
| --- | --- | --- | --- |
| `import` | — | CLI · `/forge.import` | Migrate an existing **Spec-Kit** (`.specify`) or **OpenSpec** (`openspec`) project into `.forge/`, non-destructively. Unmapped content lands losslessly in `.forge/_imported/`; `site/` and `scripts/` are skipped unless `--include-generated`. |
| `migrate` | — | CLI · `/forge.migrate` | Bring an existing `.forge/changes/{name}/` folder created by an older forge-kit version up to date with the current artifact conventions (e.g. `design.md` → `plan.md`). Non-destructive, snapshotted, and idempotent — preview with `--dry-run`. |
| `memory save\|search\|context\|sync` | — | CLI only | Manage project memory — the committable **Engram team-sync export** under `.forge/memory/`, so accumulated context travels with the repo and every teammate benefits. |
| `recall` | — | CLI · `/forge.recall` | **Advisory** reader over memory: surfaces prior specs and decisions relevant to a change's intent to inform `explore` and `specify`. Not a gate — never blocks. |
| `skill-registry refresh` | — | CLI only | Rebuild `.forge/skill-registry.md` (the resolved set of skills the engine can delegate to) with a cache-hit fast path; `list` prints it. |
| `skill-discover` | — | CLI · `/forge.skill-discover` | **Two different tools sharing a name, not an engine.** `forge skill-discover` (CLI) searches external sources (skills.sh, community git registries) and installs into `.forge/skills/`. `/forge.skill-discover` (agent skill) is local-only and never installs anything — it profiles the project's stack and the active change's `spec.md`/`tasks.md`, matches against Forge's own embedded skill catalog, and suggests what might help; enabling a suggestion is a separate, explicit step. |
| `agent-build` | — | CLI · `/forge.agent-build` | Author a new skill/agent Markdown file from a description, validate it (a missing `## Rules` section is rejected), and install it across every configured agent adapter. The `/forge.agent-build` skill fronts the same CLI with a one-question-at-a-time interview and an explicit preview-then-confirm step before anything is written. |
| `profile` | — | CLI · `/forge.profile` | **Read-only** report of the repo-adaptivity profile Forge derives for this repo: detected stack, configured test/lint commands, git-hosting provider, size bucket, related repos, and which skills are relevant vs. skippable. Writes nothing. |
| `provider` | — | CLI · `/forge.provider` | **Read-only** report of the git-hosting provider Forge resolves for this repo (and any related repos), tying the provider adapters to the `repo:` section of `.forge/config.yaml`. It detects and reports — it never writes or calls a host API. Its one subcommand is `show`, which is also the default: `forge provider` and `forge provider show` are the same command. |
| `deliver` | — | CLI · `/forge.deliver` | Open a merge/pull request for a completed change **provider-natively** — the host resolved by `provider` supplies the argv, so the same command drives `glab mr` and `gh pr`. Refuses an incomplete change, mirroring `archive`, unless `--allow-incomplete`. Preview with `--dry-run`; `--workspace` delivers in every workspace repo carrying the change, each in isolation. |
| `issues create` | — | CLI only | Export the change's `tasks.md` to the resolved provider as one issue per not-yet-`done` task. `--dry-run` prints the exact commands without running them; `--label` tags them; `--workspace` runs the same export in every workspace repo carrying the change. |
| `workspace` | — | CLI · `/forge.workspace` | **Read-only** report of this repo plus every sibling under `repo.related` — each one's provider, location, and active changes — followed by the changes that span more than one repository. `--change <c>` instead reports which repos carry that change. |
| `extension` | — | CLI only | Manage third-party extensions against the embedded offline catalog: `list`, `search`, `info`, `add`, `remove`, `update`, `enable`, `disable`. `add` takes a catalog id, or a URL/path to install directly, bypassing the catalog. |
| `codegraph init` | — | CLI only | Initialize the codebase-graph provider for this project (`--cwd <project-root>`). A deliberately narrow, Forge-owned boundary used by generated agent guidance — it accepts no raw provider arguments. |
| `learn extract\|review\|promote\|reset` | — | CLI · `/forge.learn` | The **continuous-learning ledger**: `extract` mines a change's session log and diff for recurring patterns, `review` lists the candidates, `promote` writes eligible ones into memory (**human-gated — requires `--approve`**), `reset` clears the ledger. **Advisory, never a gate** — it never returns a blocking exit code. |

## Next steps

- [The Workflow](/guide/workflow) — the phases these commands drive.
- [The forge CLI](/reference/cli) — the terminal binary, real flags, and exit codes.
- [Components](/guide/components) — agents, skills, and personas the commands install.
- [Configuration](/guide/configuration) — tune command behavior.
- [Project Structure](/guide/project-structure) — where commands write under `.forge/`.
- [Harness overview](/harness/overview) — the runtime guardrails and enforced gates.