Help Center / Delegation Workflow

Delegation Workflow

The complete flow for delegating a coding task to Forge — from activation through output review and the post-session AGENTS.md update.

Step 1 — Activate Forge

1

Run /forge

Type /forge in Claude Code. Claude loads skills/forge/SKILL.md and executes the activation sequence:

2

Health check

Claude verifies: (1) the Forge binary is on PATH, (2) ~/forge/.credentials.json has a valid api_key, (3) ~/forge/.forge.toml has a valid provider_id and model_id, (4) OpenRouter (or MiniMax) is reachable, and (5) the configured model is available. Any failure halts activation with a specific error message.

3

Bootstrap AGENTS.md (first run only)

If ./AGENTS.md does not exist, Claude creates it with a project-specific template: Code Style, Testing, Git Workflow, Forge Behavior, and Project Conventions sections. If ~/forge/AGENTS.md doesn't exist, it creates that too.

4

Confirm activation

Claude writes a zero-byte marker to ~/.claude/.forge-delegation-active and confirms: "Forge delegation mode active." All subsequent coding tasks in this session will be delegated to Forge until you run /forge:deactivate.

Health check failing? See Troubleshooting → Health Check Failures for step-by-step fixes. The most common cause is a missing or misconfigured ~/forge/.credentials.json.

Step 2 — Compose Task Prompt

When you describe a task, Claude builds a structured 5-field prompt capped at 2,000 tokens:

task prompt structure
OBJECTIVE: One-sentence statement of what Forge must accomplish CONTEXT: Only relevant files + their current state DESIRED STATE: Specific, verifiable outcome (no ambiguity) SUCCESS CRITERIA: Checklist Claude uses to verify Forge succeeded INJECTED SKILLS: ≤2 bootstrap skills relevant to the task type
Claude writes this for you. You describe what you need in plain language. Claude translates that into the 5-field structure with the right specificity and skill selection.

Step 3 — Monitor Forge Output

Claude streams Forge's output and checks for three failure signals on every response:

  • Error signal — Error:, Failed:, fatal:, or non-zero exit
  • Wrong output — SUCCESS CRITERIA not satisfied on retry
  • Stall — Forge asks questions without making progress

If no failure signal is detected and SUCCESS CRITERIA are met, the task is complete — skip to Step 5.

Step 4 — Fallback Handling (on failure)

Failures trigger the three-level fallback ladder automatically — no user input required until L3:

L1

Guide — Reframe and retry once

Claude diagnoses the failure, rewrites the prompt with a tighter DESIRED STATE and code references, and resubmits. If this succeeds, jump to Step 5. If it fails, escalate to L2.

L2

Handhold — Decompose and sequence

Claude breaks the task into atomic subtasks (≤200 tokens each) and submits them one at a time. Up to 3 attempts. If any subtask fails 3 times, escalate to L3.

L3

Take over — Claude implements directly

Delegation restriction lifted. Claude implements the task. After completion, produces a DEBRIEF with TASK / FORGE_FAILURE / LEARNED / AGENTS_UPDATE fields to capture what happened and update AGENTS.md.

Step 5 — Output Review

Whether Forge succeeded or Claude took over at L3, Claude presents a structured output summary for your review. The summary is drawn from Forge's output block fields:

  • FILES_CHANGED — every file Forge created, modified, or deleted
  • ASSUMPTIONS — anything Forge inferred that wasn't explicit in the prompt (review these carefully)
  • PATTERNS_DISCOVERED — codebase conventions Forge noticed during the task
  • Test results — if Forge ran tests, pass/fail summary

Confirm the output looks correct. If something needs adjustment, describe the change in plain language — Claude will compose a new 5-field delegation prompt for the follow-up task. There is no need to re-activate; delegation mode remains active.

Always review ASSUMPTIONS. If Forge made an incorrect assumption (wrong env variable name, wrong test framework, etc.), correct it now. Claude will add the correction to AGENTS.md so Forge doesn't repeat the assumption.

Step 6 — AGENTS.md Update

After each task (success or L3 takeover), Claude runs the AGENTS.md mentoring loop. This is automatic — you don't need to trigger it.

What gets written

  • Successful tasks — PATTERNS_DISCOVERED and any user preferences expressed during review are extracted and written to ./AGENTS.md and ~/forge/AGENTS.md
  • L3 takeovers — the DEBRIEF's AGENTS_UPDATE field is applied directly, capturing what Forge failed on and what the correct approach is
  • Session log — a full evolution log is appended to docs/sessions/YYYY-MM-DD-session.md, recording every task, outcome, and AGENTS.md change from the session

Deduplication

Before every write, Claude runs a two-phase dedup check: exact substring match first, then semantic similarity. If either matches an existing AGENTS.md entry, the write is skipped — preventing duplicate or contradictory instructions from accumulating.

AGENTS.md three-tier write targets
# Global — applies to all projects ~/forge/AGENTS.md # Project — applies to this repo only ./AGENTS.md # Session log — audit trail docs/sessions/YYYY-MM-DD-session.md

Step 7 — Deactivate (optional)

Forge delegation mode persists for the entire session. You can delegate as many tasks as needed without re-running /forge. To return to direct Claude implementation:

/forge:deactivate

This removes the ~/.claude/.forge-delegation-active marker and restores normal Claude behavior. All AGENTS.md updates from the session are preserved and will be loaded on the next /forge invocation.

You don't have to deactivate between tasks. Forge delegation mode is designed to stay active for a full working session. Only deactivate if you specifically want Claude to implement something directly — for example, a quick one-liner that doesn't warrant the delegation overhead.
Core Concepts Command Reference