Every /forge invocation, SKILL.md section, .forge.toml option, bootstrap skill, and AGENTS.md format — all in one place.
| Command | Description |
|---|---|
| /forge | Activate Forge delegation mode. Runs health check, bootstraps AGENTS.md if absent, loads SKILL.md. |
| /forge:deactivate | Deactivate Forge delegation mode and return to direct Claude implementation. |
| /forge status | Show current activation state, model, and .forge.toml config summary. |
| /forge-history | List recent Forge conversations indexed by the progress-surface hook. Shows UUID, timestamp, tool counts, and token usage via forge conversation stats <uuid> --porcelain. |
| /forge-replay <uuid> | Replay a prior Forge conversation by UUID. Dumps the full transcript via forge conversation dump <uuid> --html for inspection. |
Three hooks ship in plugin.json and run automatically under the forge-delegation skill:
| Hook | Event | Description |
|---|---|---|
forge-delegation-enforcer.sh | PreToolUse (Write / Edit / NotebookEdit / Bash) | When delegation mode is active, rewrites forge -p calls to inject a UUID conversation ID and appends an entry to the idx file so each task is durably trackable. |
forge-progress-surface.sh | PostToolUse (Bash) | Parses Forge subprocess output and surfaces a compact STATUS block into the transcript so long-running delegations stream visible progress. |
validate-release-gate.sh | PreToolUse (Bash) | Release-safety guard. Blocks gh release create commands unless all four quality-gate-stage-N markers are present in ~/.claude/.sidekick/quality-gate-state. |
Every task delegated to Forge uses exactly these 5 fields, in this order:
| Field | Description | Limit |
|---|---|---|
| OBJECTIVE | One-sentence statement of what Forge must accomplish. No ambiguity. | 1 sentence |
| CONTEXT | Only files directly relevant to the task. No conversation history, no unrelated files. | ~600 tokens |
| DESIRED STATE | Specific, verifiable outcome. What the code/system looks like when done. | ~300 tokens |
| SUCCESS CRITERIA | Checklist Claude uses to verify Forge succeeded. Each item must be checkable. | 3–6 items |
| INJECTED SKILLS | ≤2 bootstrap skills relevant to the task type. | 1–2 skills |
Total prompt budget: 2,000 tokens max.
Created in the project root on first /forge invocation. Contains compaction settings only — Forge API credentials are stored globally in ~/forge/.credentials.json and ~/forge/.forge.toml.
~/forge/.forge.toml)The global config sets the provider and model. Two providers are supported:
~/forge/.credentials.json (API key) and ~/forge/.forge.toml (provider and model config), not in the project root. When Claude guides you through setup it writes these files automatically.Four skills are pre-installed at .forge/skills/ and available for injection:
| Skill | Path | Inject when… |
|---|---|---|
| testing-strategy | .forge/skills/testing-strategy/SKILL.md | Writing tests, TDD, test coverage tasks |
| code-review | .forge/skills/code-review/SKILL.md | Code quality, refactoring, review-driven changes |
| security | .forge/skills/security/SKILL.md | Auth, input validation, secrets handling |
| quality-gates | .forge/skills/quality-gates/SKILL.md | Multi-phase delivery, release prep |
Every Forge task response includes a structured output block with four mandatory fields. Claude reads these fields to verify success, update AGENTS.md, and detect failures.
| Field | Description |
|---|---|
| STATUS | SUCCESS or FAILURE. Claude checks this first — a FAILURE immediately triggers the fallback ladder. |
| FILES_CHANGED | List of every file Forge created, modified, or deleted during the task. Used for output review and session logging. |
| ASSUMPTIONS | Any assumptions Forge made that were not explicit in the task prompt. Claude surfaces these for user review. |
| PATTERNS_DISCOVERED | Codebase conventions, architecture patterns, or project quirks Forge noticed during the task. Claude extracts these for AGENTS.md. |
./AGENTS.md and ~/forge/AGENTS.md — this is how Forge's understanding of your codebase grows over time.AGENTS.md uses an action-oriented, categorized format. Claude extracts content from sessions and writes it under these categories:
Files created and managed by Sidekick:
| Path | Purpose |
|---|---|
| skills/forge/SKILL.md | Forge delegation instruction set (321 lines, 8 sections) |
| .forge.toml | API key and compaction config (gitignored) |
| ~/.claude/.forge-delegation-active | Active session state marker (zero-byte) |
| .forge/skills/*/SKILL.md | 4 bootstrap skills for injection |
| AGENTS.md | Project-level Forge standing instructions |
| ~/forge/AGENTS.md | Global cross-project Forge instructions |
| docs/sessions/ | Per-session AGENTS.md evolution logs |