Forge Wizard - Smart Routing System

This skill provides intelligent routing for all Forge operations, ensuring correct agent namespacing via explicit forge: prefixes.

Critical: Agent Namespacing

ALWAYS use explicit forge: namespace when invoking Forge agents:

# CORRECT - Uses Forge's validator
Task:
  subagent_type: "forge:validator"
  prompt: "Validate plugin structure..."

# WRONG - May invoke any plugin's validator
Task:
  subagent_type: "validator"
  prompt: "..."

This prevents agent confusion when multiple plugins are active (e.g., forge + skillmaker).

---

Routing Table

Input Pattern	Agent	Task Invocation
(empty)	-	Show interactive menu
analyze|examine|describe|diagnose|debug	codebase-analyzer	forge:codebase-analyzer
mismatch|compare|intent vs	mismatch-evaluator	forge:mismatch-evaluator
question|clarify|ask	questioner	forge:questioner
options|design|propose|suggest	option-synthesizer	forge:option-synthesizer
workflow|steps|sequence|procedure	workflow-manager	forge:workflow-manager
execute|implement|do it	execution-orchestrator	forge:execution-orchestrator
validate|verify|check|full verify	validator	Two-layer validation
create|new|build|add	input-normalizer	forge:input-normalizer (start full workflow)
refactor|improve|optimize|review	input-normalizer	forge:input-normalizer (understand first)
(other)	input-normalizer	forge:input-normalizer

---

Route Implementations

Route: Validate / Full Verify

Two-Layer Validation Flow:

1. Static Validation (fast, structural):

   python3 ${CLAUDE_PLUGIN_ROOT}/scripts/validate_all.py --json
   

2. Semantic Validation (deep, intelligent):

   Task:
     subagent_type: "forge:validator"
     prompt: |
       Validate plugin schema, structure, and invariants.
       Check: plugin.json, marketplace.json, frontmatter, hooks.json
   

3. Combine Results: Synthesize findings from both layers.

See: references/route-validate.md

Route: Analyze / Diagnose

Direct to Phase 2:

Task:
  subagent_type: "forge:codebase-analyzer"
  prompt: |
    Analyze existing plugin code and describe reality.
    Focus on: {user's target}

See: references/route-analyze.md

Route: Design / Options

Direct to Phase 5:

Task:
  subagent_type: "forge:option-synthesizer"
  prompt: |
    Synthesize design options with trade-offs.
    Requirements: {user's requirements}

See: references/route-design.md

Route: Create / Full Workflow

Start at Phase 0:

Task:
  subagent_type: "forge:input-normalizer"
  prompt: |
    Normalize user intent for: {user's description}
    Extract: problem statement, success criteria, constraints

Then proceed through phases 0-8 as needed.

See: references/route-create.md

Route: Refactor / Improve

Analyze first, then design:

# Step 1: Understand current state
Task:
  subagent_type: "forge:codebase-analyzer"
  prompt: "Analyze {target} to understand current implementation"

# Step 2: Design improvements
Task:
  subagent_type: "forge:option-synthesizer"
  prompt: "Propose refactoring options based on analysis"

See: references/route-refactor.md

---

Interactive Menu

When /forge is called without arguments, present:

Forge - Design Guidance System

What would you like to do?

1. Analyze    - Describe what existing code does (Phase 2)
2. Design     - Propose design options for a feature (Phase 5)
3. Create     - Full workflow from intent to execution (Phase 0-8)
4. Refactor   - Improve existing code (Analyze + Design)
5. Full Verify - Two-layer validation (Static + Semantic)

Enter number or describe your intent:

Use AskUserQuestion with these options:

AskUserQuestion:
  questions:
    - question: "What would you like to do?"
      header: "Action"
      options:
        - label: "Analyze"
          description: "Describe what existing code does (Phase 2)"
        - label: "Design"
          description: "Propose design options for a feature (Phase 5)"
        - label: "Create"
          description: "Full workflow from intent to execution (Phase 0-8)"
        - label: "Full Verify"
          description: "Two-layer validation (Static + Semantic)"
      multiSelect: false

---

Agent Reference

Agent	Namespace	Purpose
input-normalizer	forge:input-normalizer	Normalize user intent (Phase 0)
semantic-router	forge:semantic-router	Route intent to phases (Phase 1)
codebase-analyzer	forge:codebase-analyzer	Describe code reality (Phase 2)
mismatch-evaluator	forge:mismatch-evaluator	Compare intent vs reality (Phase 3)
questioner	forge:questioner	Structured questioning (Phase 4)
option-synthesizer	forge:option-synthesizer	Design options (Phase 5)
workflow-manager	forge:workflow-manager	Create workflows (Phase 6)
execution-orchestrator	forge:execution-orchestrator	Execute designs (Phase 7)
validator	forge:validator	Validate results (Phase 8)

---

Strict Phase Rules

Some phases have strict requirements:

Phase	Strict	Requirement
0	Yes	Must capture intent before proceeding
4	Yes	Must follow Structured Dialogue Contract
7	Yes	Must have explicit user confirmation

Never skip strict phases or bypass their requirements.