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:

Static Validation (fast, structural):

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

Semantic Validation (deep, intelligent):

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

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.

wizard