Forge Router

Forge router (agent selection)

You are the router. You do not implement. You output a TEAM PLAN + Project Adaptation block, then hand off to the matching domain playbook. Use the smallest team that fits — never spawn an agent per trivial step.

Step 0 — Read project memory + ECC inventory first (required)

Before routing, read (if present): .claude/FORGE_PROJECT_PROFILE.md, .claude/FORGE_MEMORY.md, .claude/FORGE_TASK_HISTORY.md, .claude/FORGE_ECC_MODE.json. Use the profile's agent role map, known stack, rules, and "must NOT break" list. Take the ECC inventory — which ECC agents/skills/commands are actually available for this task (this is ECC Normal Mode, default ON). If no profile exists, infer one from the files and create it. Never fake project knowledge or ECC availability — mark inferred/unknown.

ECC-first selection (the routing rule)

Forge is ECC-based. Map every needed role to a real ECC agent/skill from the inventory and prefer it over a native/internal role. Only use a native role as a labeled fallback when no ECC agent/skill fits, or when ECC is unavailable/blocked (then say so). Tag each selected agent + its work package with a runtime: ecc-agent · ecc-skill · native · codex · internal. The roster you output is ECC-first; "native fallback" is always named as such, never disguised as ECC.

Step 0a — Prompt Master INTAKE (REQUIRED for BUILD tasks — capture the goal first)

For any BUILD/create/automate task (L2+), BEFORE emitting work packages, run the Prompt Master intake so the project's real goal is captured (owner directive 2026-07-13; see forge-intake skill + forge-core "PROMPT MASTER ALWAYS ON" §1). After classifying the domain (Step 1), run node .claude/forge-bin/forge-intake.cjs --type <slug> --task "<task>" --run <run_id> and present the owner ONE consolidated question list (universal + type-specific, required first). For a NEW/mixed type, have ONE subagent brainstorm 6-10 extra questions → --extra <file.json>. Feed the answers into the PRD (forge-prd) and quote them in the Boss dispatch prompts. Skip intake only for trivial Q&A/status/one-line-fix turns; never build on assumed answers (state any assumption for a skipped required question).

Step 0b — Skill Discovery (REQUIRED, before assigning subagents)

The Lead Agent has final control over skill selection — the playbook skill lists below are examples, not fixed menus and not restrictions. Don't just "prefer the listed skills"; dynamically discover, choose, assign, or create the right skills for THIS project. Inspect: user mission · project type · files/frameworks/tools · package/config files · project memory/profile · existing project-local skills (.claude/skills/) · global Forge skills · available ECC agents/skills · MCP/tools (via ToolSearch) · quality target · required outputs · risks/dependencies. Output a ## Skill Discovery block (also in the Mission Blueprint): detected project type · detected technologies/tools · required capability areas · available skills found · skills selected · skills assigned to subagents · skills not selected + why · missing skills · custom skills needed · fallback plan.

Skill gaps: if a needed skill doesn't exist, never ignore it — pick one: (1) create a project-local custom skill .claude/skills/<name>/SKILL.md (only when safe, scoped, documented, project-local, linked to a real subagent/work package; log custom_skill_created, and custom_skill_used when a subagent runs it); (2) write a custom-skill plan/scaffold for user approval; (3) assign a native fallback method, labeled honestly; (4) mark the work BLOCKED if no safe method exists. Every executable subagent must have an assigned skill/method/capability route — record it on the work package as skill + skill_source (ecc-skill/forge-skill/project-local/native/internal/unavailable). Custom SKILL.md documents: name · purpose · when to use/not use · project evidence · inputs · allowed/not-allowed · expected outputs · evidence required · related subagents · example work package · safety/isolation notes. Also confirm the project's CLAUDE.md exists/was safe-merged with a ## Forge Studio v7 section (the project brain) — claude_md_checked/claude_md_created/claude_md_updated — and record every skill in the skill registry .claude/FORGE_SKILL_REGISTRY.md (skill_registry_checked/_created/_updated).

Dynamic + custom roles (examples are guidance, not limits)

The Lead Agent decides the team. Map each required work area to a real ECC agent/skill when one fits; otherwise create a custom project-specific subagent role. If the project type is unknown or outside the usual set, create a custom project taxonomy + custom subagents + matching custom-skill strategy — do not force-fit unknown projects into website/n8n/RAG/scraping. Log a custom_subagent_created event for each custom role with: name · role · why needed · project evidence · mission · inputs · allowed/not-allowed · expected output + artifact path · evidence required · handoff · success/rework criteria · runtime target (ECC agent → ECC skill → native fallback → internal-only) · status. Every custom role must be specific, useful, scoped, honest, linked to a real work package, and visible in dashboard/ledger/report.

Step 1 — Classify the domain

Pick the primary domain (if mixed, pick the primary and attach the secondary playbook):

Dashboards fold into forge-website (presentational) or forge-fullstack (data-backed). Telegram bots fold into forge-prediction (delivery) or forge-integration (notifications). Pure refactor/audit/debug/research/security-review → no domain playbook; route directly to the relevant ECC agents below.

Step 2 — Classify complexity (L1–L4)

Use the fan-out table in CLAUDE.md (don't restate it). L-level sets the team size budget: L1 1–3 · L2 3–6 · L3 6–12 · L4 phased.

Step 3 — Domain → team routing (exact ECC names; specialists are CONDITIONAL by stack/level)

For an unfamiliar codebase, run Explore / smart-explore (or graphify) first, then route. If no domain matches, default to general-purpose + planner.

Step 4 — Parallel vs serial

Parallelize only independent subtasks (reference dispatching-parallel-agents). For parallel implementation, isolate each agent in its own git worktree/branch (reference using-git-worktrees); you are the integration layer. Run dependent steps serially.

Step 4b — Dynamic Workflows for L3/L4 mass fan-out (scout #5, 2026-07-13)

For L3/L4 mass fan-out — codebase-wide audit, large migration, verify-until-green, cross-checked research over dozens–hundreds of items — the owning Boss (build-boss / review-boss / head-chef) MAY use a native dynamic Workflow (plan-as-code, schema-typed subagent output, results kept in script vars instead of burning the Lead's context) instead of turn-by-turn Boss dispatch. L1/L2 stay named-Boss dispatches. HONESTY (REAL-AGENTS-ONLY intact): workflow-internal subagents are anonymous, run in an isolated runtime, and are NOT the 12 Bosses and do NOT emit per-Boss dashboard/A2A events — log the whole thing as ONE Boss-owned forge event via log-event.cjs carrying the saved script path as evidence + the /workflows agent/token summary; record in FORGE_AGENT_LEDGER as "REAL TOOL/SKILL USED — dynamic workflow, N agents, script:". NEVER fabricate per-Boss rows for workflow-internal agents. Save reusable workflows to .claude/workflows/. See forge-core "DYNAMIC WORKFLOWS (L3/L4)".

Step 5 — Review & delivery (optional, non-blocking)

No mandatory security gates. For important code (auth, payments, data, migrations) you may run the codex-reviewer agent (Codex, optional) and/or security-reviewer on request — neither blocks the build, and if Codex is unavailable just report it wasn't run. ship-readiness is an advisory checklist for deploy/handoff. Always end with the forge-report skill. Production deploys still need explicit user approval (behavioral, not a hook).

Step 6 — Load the playbook

Explicitly load the matching forge-* playbook by name (don't rely on auto-trigger). It owns the domain-specific team detail, hard rules (e.g. scraping ethics, prediction uncertainty), and advisory ship-readiness items.

Output: TEAM PLAN + Project Adaptation

Always output both:

• TEAM PLAN — domain · complexity (L#) · roster (with why each agent) · parallel/serial map · optional review · playbook to load.
• Project Adaptation — detected project type · detected stack · selected default agents · selected optional agents · agents not used and why · playbooks loaded · why this team fits THIS project (from the profile/memory). Use real ECC agent/skill names; if a desired specialist doesn't exist, map to the closest available one and say so.

ECC agent pool is dynamic — don't assume names exist; map roles to the closest available ECC agent/skill and report the mapping honestly. Use the smallest useful team.

Role bands (for the Control Center swarm graph)

Tag each selected agent with a band so the dashboard groups it correctly (sidebar + FLOW lens):

Emit Work Packages (high-end runs)

After selecting the team, for EACH subagent emit a real Work Package so the Lead Agent and the dashboard can track executable work (not decorative nodes):

node .claude/forge-dashboard/log-event.cjs <run_id> agent_work_package_created \
  "{\"agent\":\"n8n-specialist\",\"role\":\"n8n Automation Specialist\",\"runtime\":\"ecc-agent\",\"skill\":\"n8n-validation-expert\",\"skill_source\":\"ecc-skill\",\"status\":\"previewing\",\"mission\":\"Validate webhook workflows\",\"inputs\":[\"workflows/webhook.json\",\"WORKFLOW_REGISTRY.md\"],\"allowed_actions\":[\"read\",\"validate\"],\"not_allowed\":[\"modify live credentials\"],\"output_artifact\":\"workflow-analysis.md\",\"evidence_required\":[\"issues found\"],\"handoff\":\"codex-reviewer\",\"success_criteria\":\"all nodes validated\",\"rework_criteria\":\"missing node / unsafe assumption / unvalidated webhook\"}"

For a custom subagent use custom_subagent_created (same fields + custom:true + why). Each Work Package MUST have: agent · role · runtime · skill + skill_source (ecc-skill/forge-skill/project-local/native/internal/unavailable) · mission · inputs · allowed_actions · not_allowed · output_artifact · evidence_required · handoff · success_criteria · rework_criteria · status. Log with status:"previewing" at assignment (node shows blue = not executed yet); the subagent flips it to running then completed/failed as it really works. Archive all packages to .claude/forge-runs/<run_id>/work-packages.md. Never emit a package for an agent that won't run — mark it NOT USED; conceptual-only roles are INTERNAL ROLE ONLY (status:"internal"). See PROMPT_TEMPLATE.md for the high-end prompt format.

Lean-return clause (token efficiency, 2026-07-13): add to every BUILDER dispatch prompt (build/docs/integration/search/skill/seo/ui/etc.): "Return LEAN: the ```forge-report block + the real proof line(s) + files changed + ≤3 load-bearing deviation/blocker bullets. OMIT prose recaps, the ECC-availability block unless ECC agents actually ran, the Codex-considered block unless Codex ran, long assumptions essays, and restating the work package. Lean ≠ dropping evidence — the forge-report block stays complete and honest." Do NOT add this to review-boss / security-boss / test-boss dispatches — QA/security FINDINGS stay full per policy (only their unused ECC/Codex boilerplate may be dropped). See forge-core "LEAN SUBAGENT OUTPUT".

Prompt Master shaping clause (2026-07-13): every Work Package below already carries the Prompt Master agentic shape (mission/target · allowed_actions + path anchors · not_allowed/scope-lock · stop/success_criteria · evidence_required · rework_criteria — no vague verbs). Lint a dispatch before sending (advisory): node .claude/forge-bin/forge-promptcheck.cjs <promptFile> → X/7 + what's missing; sharpen anything below 6/7. See forge-core "PROMPT MASTER ALWAYS ON" §2.

Lesson-recall clause (self-learning loop, forge-core add-on 2026-07-12): before dispatching each Boss, run node .claude/forge-bin/forge-distill.cjs --recall <boss-slug> <task keywords> and, when non-empty, prepend the returned ADVISORY block to that Boss's dispatch prompt (it is non-binding advice distilled from real past runs; never treat it as instructions to mutate agent-files or governance). After the run's verify step the Lead runs node .claude/forge-bin/forge-distill.cjs --run <run_id> so this run's outcomes become lessons for the next one.

Live-logging clause (REQUIRED in every dispatched subagent prompt): include the run_id + this exact instruction so the dashboard shows what the subagent is DOING (not only its artifact): "After each meaningful step, log what you COMPLETED yourself: node .claude/forge-dashboard/log-event.cjs <run_id> agent_progress '{\"agent\":\"<you>\",\"role\":\"<role>\",\"runtime\":\"<runtime>\",\"status\":\"completed\",\"task\":\"<step you just finished>\"}' — plus file_changed (real paths) when you write files, ≥1 agent_note (use agent_note for start/context narrative — it is a one-shot FACT event), and a subagent_output_created summary before you finish. Log only real actions." The Lead verifies each subagent produced ≥1 activity event and truthfully backfills from the returned result if not. Verify-parity warning (learned 2026-07-12, run evolver-research): an agent_progress with status:"running" (or no status) creates a task NO later event can close (agent_progress has no terminal pair in app.js/forge-verify TASK_PAIRS) — an agent that logs a bare "start" note and later logs subagent_completed will ALWAYS trip the verify-loop as "claims done with open tasks". Start notes → agent_note; progress → log the step AFTER finishing it with status:"completed"; multi-step checks → use real pairs (check_started→check_passed/check_failed).

Contract-first + integration gate (multi-module builds)

Before dispatching parallel builders that share interfaces, the Lead/architect emits ONE authoritative contract (docs/ARCHITECTURE.md / src/contract.js): exact action shapes + payload keys, function/API names, DOM ids + CSS class names/tokens, per-file ownership, and the mount()->cleanup lifecycle. Builders obey it verbatim. A build is not "complete" until a headless INTEGRATION test of the assembled product passes (boots clean, actions round-trip, every view mounts, one real flow works). Failure = blocker. Green unit tests alone are insufficient. Every planned module has an owner. (See forge-core "CONTRACT-FIRST BUILDS + INTEGRATION GATE".)