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

::: info One catalog, one install
Components, skills, personas, and SDD mode are all resolved by a single
`forge install` pass. The install is idempotent — run it again and it converges
to the same state. Preview any selection with `--dry-run` before you write
anything.
:::

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

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

| Component | ID | What it adds |
| --- | --- | --- |
| Engram | `engram` | Persistent cross-session memory |
| SDD | `sdd` | Spec-driven development workflow |
| Skills | `skills` | Curated coding skill library |
| Context7 | `context7` | Latest framework and library docs (MCP) |
| Persona | `persona` | Managed agent behavior and conversation tone |
| Permissions | `permissions` | Security-first defaults and guardrails |
| GGA | `gga` | AI provider switcher (the external `gga` tool) |
| OpenCode Theme | `opencode-theme` | Visual polish: OpenCode color theme |
| Claude Code Theme | `claude-code-theme` | Visual polish: Claude Code color theme |
| OpenCode Logo | `opencode-logo` | Visual polish: OpenCode home logo plugin |

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

::: warning External binary
Memory features shell out to the **Engram** binary. It degrades gracefully when
absent, but `forge memory` and `forge recall` will not work until Engram is on
your `PATH`. See [Memory](/concepts/memory).
:::

### 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](/guide/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](#the-bundled-skill-library) — 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](#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.

::: tip Security posture, not just a flag
Permissions covers the install-time guardrails. To define your project's broader
security posture as a first-class artifact, use the `/forge.security` agent skill
and see [Review](/features/review).
:::

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

```sh
gga init
gga install
```

### Visual polish

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

| Component | Applies to | Effect |
| --- | --- | --- |
| `opencode-theme` | OpenCode | Color theme overlay |
| `claude-code-theme` | Claude Code | Color theme overlay |
| `opencode-logo` | OpenCode | Home logo plugin |

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

| Preset | ID | What it bundles |
| --- | --- | --- |
| Dev Stack + Polish | `forge-full` | Every component — the full catalog plus all skills |
| Dev Stack | `ecosystem-only` | Core components (Engram, SDD, Skills, Context7, GGA) plus all skills, no visual polish |
| Memory Only | `minimal` | Engram plus the SDD skills — nothing else |
| Custom | `custom` | You choose components and skills by hand; existing persona and settings stay unmanaged |

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

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

| Persona | ID | Replies | Generated artifacts |
| --- | --- | --- | --- |
| Forge | `forge` | Mentor voice | Mentor voice |
| Forge, neutral artifacts | `forge-neutral-artifacts` | Mentor voice | Neutral |
| Neutral | `neutral` | Plain | Neutral |
| Custom | `custom` | User-supplied | Unmanaged |

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

::: info Persona needs its component
`--persona` takes effect only when the **Persona** component is installed. Under
the `custom` preset the persona layer stays unmanaged, so your own voice
configuration is preserved.
:::

```sh
forge install --persona forge-neutral-artifacts
```

::: info Legacy names still work
The persona `forge` was previously `gentleman` (and `forge-neutral-artifacts`
was `gentleman-neutral-artifacts`), and the `forge-full` preset was
`full-gentleman`. The old names are still accepted as **aliases**, so existing
scripts and configs keep working — but the `forge*` names are canonical now.
:::

## SDD modes

The **SDD mode** decides how the workflow phases execute.

| Mode | Flag | Execution |
| --- | --- | --- |
| Single | `--sdd-mode single` | All phases run in one conversation thread |
| Multi | `--sdd-mode multi` | Each phase runs in its own sub-agent |

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

::: warning Multi needs sub-agent support
`--sdd-mode multi` only applies to agents that can spawn sub-agents — **Claude
Code**, **OpenCode**, **Kilo Code**, **Kiro IDE**, and **Pi**. Other agents fall
back to single-thread execution. See [Agents](/guide/agents).
:::

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

| Skill | Priority |
| --- | --- |
| `sdd-init` | p0 |
| `sdd-explore` | p0 |
| `sdd-propose` | p0 |
| `sdd-spec` | p0 |
| `sdd-design` | p0 |
| `sdd-tasks` | p0 |
| `sdd-apply` | p0 |
| `sdd-verify` | p0 |
| `sdd-archive` | p0 |
| `sdd-onboard` | p0 |

### Workflow skills

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

| Skill | Priority |
| --- | --- |
| `go-testing` | p0 |
| `skill-creator` | p0 |
| `skill-improver` | p0 |
| `judgment-day` | p0 |
| `branch-pr` | p0 |
| `issue-creation` | p0 |
| `skill-registry` | p0 |
| `chained-pr` | p0 |
| `cognitive-doc-design` | p0 |
| `comment-writer` | p0 |
| `work-unit-commits` | p0 |

### Security skills

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

| Skill | Priority |
| --- | --- |
| `security-framework-mappings` | p1 |
| `llm-guardrails` | p1 |
| `security-headers-audit` | p1 |
| `serverless-security` | p1 |
| `terraform-security-audit` | p1 |
| `sbom-supply-chain` | p1 |
| `api-rate-limiting` | p1 |
| `devsecops-pipeline-scanning` | p1 |
| `secrets-management` | p1 |

After installing skills, `forge skill-registry refresh` rebuilds the index of
installed skills — triggers, scopes, and exact paths. See
[Skills](/features/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`:

| Channel | Cadence | Use it for |
| --- | --- | --- |
| `stable` | Released | Day-to-day work |
| `beta` | Pre-release | Early testing of upcoming changes |
| `nightly` | Bleeding edge | Latest builds, least tested |

```sh
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](/guide/configuration#agents).

## Next steps

- [Commands](/guide/commands) — the command set every component's install writes.
- [Agents](/guide/agents) — which agents receive the configuration.
- [Configuration](/guide/configuration) — set standing defaults for scope and personas.
- [Memory](/concepts/memory) — how the Engram component persists context.
- [Skills](/features/skills) — the skill library in depth.