> ## Documentation Index
> Fetch the complete documentation index at: https://forgekit-docs-feature-windows-portable-hooks.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# The four-layer config compiler
> Author the substrate once; forge sync compiles it into each tool's native config. The four layers are how the brain is expressed; the compiler is how it is delivered.
You author the substrate once. `forge sync` compiles that source into each tool's native
config. The four layers are *how the brain is expressed*; the compiler is *how it is
delivered*.
```mermaid theme={null}
%%{init: {'theme':'base','themeVariables':{'primaryColor':'#201a15','primaryTextColor':'#f2ede7','primaryBorderColor':'#372c22','lineColor':'#f26430','secondaryColor':'#272019','tertiaryColor':'#171310','edgeLabelBackground':'#201a15','clusterBkg':'#171310','clusterBorder':'#4a3b2e','fontFamily':'ui-sans-serif, system-ui, sans-serif','fontSize':'14px'},'flowchart':{'curve':'basis','padding':10,'nodeSpacing':36,'rankSpacing':44}}}%%
flowchart TD
S["source/ · rules.json · substrate.json · mcp.json"] -->|"forge sync — content-hash + DO-NOT-EDIT headers"| N["native configs · CLAUDE.md · AGENTS.md · .cursor · .gemini · .aider"]
S -. configures .-> L
subgraph L["the four layers"]
direction LR
T["tools · model-invoked skills"]
C["crew · isolated sub-agents"]
G["guards · deterministic hooks"]
M["mcp · atlas + substrate server"]
end
```
## One source, many emitters
Author rules **once** (`source/rules.json`); a deterministic compiler (`forge sync`)
emits each tool's native format with a content-hash header, so drift is detectable and
re-running is a no-op. No rule is ever written twice. The canonical source is three
files:
| Source file | What it holds |
| ----------------------- | ---------------------------------------------------------------- |
| `source/rules.json` | The canonical engineering rules (git, testing, security, style). |
| `source/substrate.json` | Cognitive-substrate defaults — thresholds, routing, LLM knobs. |
| `source/mcp.json` | MCP server definitions emitted into each tool. |
## The four layers
Each layer is brand-named and emitted cross-tool.
`~/.forge/tools/` → `~/.claude/skills/`. Model-invoked skills, following the
`SKILL.md` standard (`name` + `description` frontmatter).
`~/.forge/crew/` → `~/.claude/agents/`. Isolated-context sub-agents such as scout,
verifier, and frontend-verifier.
`~/.forge/guards/` → `settings.json` hooks. **The only layer that *enforces* rather
than suggests.** A guard is a deterministic hook the model cannot drift from. Prose
rules in `CLAUDE.md` get acknowledged and then forgotten after compaction; a guard
does not. Every enforceable invariant belongs here.
Forge ships one stdio server (`src/cortex_mcp.js`) exposing 21 MCP tools: the
substrate checks (`substrate_check` / `predict_impact` / `assumption_gate` / …),
memory reads *and* writes (`forge_remember`, ledger ratify/retract), and ops/health.
Cross-cutting concerns thread through all four: **atlas** (the code graph), **lean**
(minimalism — shipped as both a tool and a Stop-guard, so it applies whether or not the
model invokes it), and **recall** (memory).
## Guard over prose
Rules the model can drift from live in prose; rules it must **never** break live in
guards (deterministic shell hooks). A guard can't be forgotten after context
compaction.
Move every enforceable invariant out of `CLAUDE.md` and into a guard; keep the prose
thin. This is the single most important discipline in Forge's design.
## The verified cross-tool emit matrix
Forge emits config for **ten tools**, plus an MCP server for Roo Code and VS Code. Each
row is confirmed against vendor docs.
| Tool | Native target | How Forge emits |
| ------------------ | --------------------------------------------------------- | --------------------------------------------------------------------- |
| **Claude Code** | `CLAUDE.md` (+ `.claude/rules/*.md`, `settings.json`) | Thin `CLAUDE.md` whose first line is `@AGENTS.md`; guards → settings |
| **Codex** | `AGENTS.md` native (32 KiB cap) | Canonical `AGENTS.md` at root **is** the source |
| **Cursor** | `AGENTS.md` + `.cursor/rules/*.mdc` | `AGENTS.md` for flat rules; `.mdc` when scoping is needed |
| **Gemini** | `GEMINI.md`, or `AGENTS.md` via `context.fileName` opt-in | Writes `.gemini/settings.json` to avoid a second copy |
| **Aider** | `CONVENTIONS.md` via `read:` in `.aider.conf.yml` | Emits `.aider.conf.yml` with `read: AGENTS.md` |
| **Copilot** | root `AGENTS.md` + `.github/copilot-instructions.md` | Relies on root `AGENTS.md`; optional `.github` pointer |
| **Windsurf/Devin** | `AGENTS.md` auto-discovered (caps 6k/12k chars) | Root `AGENTS.md` under caps; detects `.windsurf` vs `.devin` |
| **Zed** | first match of a precedence list incl. `AGENTS.md` | Emits `AGENTS.md`; doctor flags any shadowing legacy file |
| **Continue** | `.continue/rules/*.md` + `.continue/mcpServers/*.yaml` | Emits a rules file plus the Forge MCP server config |
| **OpenClaw** | execution-folder `AGENTS.md`; MCP registry is global | Relies on root `AGENTS.md`; writes `.openclaw/mcp.json` to apply once |
Roo Code and VS Code receive the Forge MCP server via `forge init` (`.roo/mcp.json`,
`.vscode/mcp.json`) rather than a rules file.
**OpenClaw MCP is a deliberate manual step.** OpenClaw stores servers in your global
`~/.openclaw/openclaw.json`, which Forge will not write to. `forge sync` leaves the
definition in `.openclaw/mcp.json`; register it with
`openclaw mcp add forge-cortex --command forge --arg cortex-mcp`, then verify with
`openclaw mcp doctor forge-cortex --probe`. Forge adds no OpenClaw hooks — rules reach
it through `AGENTS.md` project context and the MCP tools, nothing more.
**Char caps are real.** Codex truncates at 32 KiB, Windsurf at 6k/12k. `forge sync`
enforces a source size budget so a config never silently truncates.