---

name: forge-analyzer description: Analyze vague user ideas and recommend architecture based on actual needs, not predefined categories. Front-end for clarifying ambiguous requests before routing to appropriate skillmaker tools. allowed-tools: ["Read", "Grep", "Glob", "Task", "AskUserQuestion"]

Forge Analyzer

Understands what users actually need, not what category their project fits into.

Philosophy

"What problem are you solving?" - not "Is this a skill or an agent?"

Architecture emerges from understanding, not from matching patterns to templates.

---

When to Use

Invoke this skill when:

• User has a vague or ambiguous request
• Wizard cannot determine the right route from pattern matching
• User says things like "I want to make something that..." or "I'm not sure what I need"
• Need to clarify requirements before creating skill/agent/command

---

Analysis Dimensions

Instead of categories, analyze along these dimensions:

1. State Complexity

| Question | Implication | |----------|-------------| | Does it need to remember across calls? | Persistent state needed | | Is state shared between components? | Centralized management | | Can it be stateless? | Simpler architecture |

2. Interaction Boundary

| Question | Implication | |----------|-------------| | Who initiates the interaction? | User → command/skill; System → hook/daemon | | How long does interaction last? | One-shot → skill; Ongoing → agent/session | | Does it need external systems? | External → MCP/API integration |

3. Context Requirements

| Question | Implication | |----------|-------------| | How much context does it need? | Large → isolated agent; Small → inline skill | | Is context shareable? | Shareable → skill; Isolated → subagent | | Does it build on previous context? | Building → session state; Fresh → stateless |

4. Execution Pattern

| Question | Implication | |----------|-------------| | Synchronous or async? | Sync → direct; Async → background/daemon | | Single task or workflow? | Single → function; Workflow → orchestration | | Needs human in the loop? | HITL → interactive; Autonomous → agent |

5. Integration Surface

| Question | Implication | |----------|-------------| | What triggers it? | User input → command; Tool use → hook; Time → cron | | What does it produce? | Text → response; Files → write; Actions → tool calls | | What does it consume? | Files → read; APIs → fetch; User → ask |

---

Analysis Process

Step 1: Gather Requirements

Ask open-ended questions:

AskUserQuestion:
  question: "What problem does this solve for you?"
  header: "Problem"
  options:
    - label: "Automate repetitive task"
      description: "Something I do often that could be automatic"
    - label: "Enforce a rule"
      description: "Prevent mistakes or ensure quality"
    - label: "Provide information"
      description: "Answer questions or give guidance"
    - label: "Connect systems"
      description: "Bridge between different tools/services"

Step 2: Map Dimensions

State:        [stateless] -------- [session] -------- [persistent]
Interaction:  [reactive] --------- [interactive] ---- [proactive]
Context:      [minimal] ---------- [moderate] ------- [extensive]
Execution:    [sync] ------------- [mixed] ---------- [async]
Integration:  [internal] --------- [hybrid] --------- [external]

Step 3: Derive Architecture & Route to Wizard

| Pattern | Dimension Profile | Wizard Route | |---------|------------------|--------------| | Skill (Knowledge) | Stateless + Minimal context + Sync | SKILL → skill-architect | | Skill (Tool) | State + Script needed + Sync | SKILL → skill-architect | | Agent | Extensive context + Any execution | AGENT → skill-orchestrator-designer | | Hook | Reactive + Rule enforcement + Sync | HOOK_DESIGN | | LLM Integration | External + Async + API | LLM_INTEGRATION | | Workflow | Multi-step + Mixed execution | COMMAND | | Hybrid | Conflicting requirements | architecture-smith agent |

---

Output Format

After analysis, recommend and route. Connection Plan is MANDATORY:

## Forge Analysis Result

### Problem Understanding
{Summary of what the user needs}

### Dimension Analysis
- State: {spectrum position} - {reason}
- Interaction: {spectrum position} - {reason}
- Context: {spectrum position} - {reason}
- Execution: {spectrum position} - {reason}
- Integration: {spectrum position} - {reason}

### Recommended Architecture
{Specific recommendation}

### Connection Plan (REQUIRED)
| Registration | Location | Status |
|--------------|----------|--------|
| {type} | {file path} | [ ] Pending |

Entry points:
- {How users/system will access this component}

### Next Step
1. Wire connections (registrations above)
2. Create component via: {Wizard route or agent}
3. Verify with validate_all.py

---

Integration with Wizard

After forge analysis completes:

| Architecture | Action | |--------------|--------| | Skill | Route to SKILL → Task(subagent_type: "skill-architect") | | Agent | Route to AGENT → Task(subagent_type: "skill-orchestrator-designer") | | Hook | Route to HOOK_DESIGN | | Complex/Hybrid | Task(subagent_type: "architecture-smith") for deep analysis |

---

Connectivity-First Design

CRITICAL: Every component must be connected at creation time, not validated later.

When creating ANY component, verify connectivity BEFORE implementation:

Connection Checklist

| Component Type | Must Connect To | Validation | |---------------|-----------------|------------| | Skill | wizard routes, marketplace.json agents | W046 unreferenced check | | Agent | plugin.json agents[], marketplace.json agents | E001 undefined agent | | Command | plugin.json commands[], marketplace.json commands | E002 undefined command | | Hook script | hooks/hooks.json matchers | W046 orphaned script | | Reference file | Parent SKILL.md or agent.md | W046 disconnected file |

Pre-Creation Questions

Before creating any component:

AskUserQuestion:
  question: "How will this component be accessed?"
  header: "Connectivity"
  options:
    - label: "Via wizard route"
      description: "Route pattern in wizard SKILL.md"
    - label: "Via command"
      description: "User runs /plugin:command"
    - label: "Via agent spawning"
      description: "Task(subagent_type: 'name')"
    - label: "Automatically via hooks"
      description: "Triggered by tool use patterns"

Connection Blueprint

When recommending architecture, ALWAYS include connection plan:

## Connection Plan

### 1. Entry Points
- Wizard route: `{pattern}` → ROUTE_NAME
- Command: `/plugin:{name}`
- Agent spawn: `Task(subagent_type: "{name}")`

### 2. Required Registrations
- [ ] plugin.json → agents[] or commands[]
- [ ] marketplace.json → agents[] or commands[]
- [ ] wizard SKILL.md → routing table (if applicable)
- [ ] hooks.json → matchers (if hook script)

### 3. Internal References
- Parent skill/agent → references/
- Skill loading: Skill("plugin:{name}")

Creation Workflow

1. Determine component type from dimension analysis
2. Generate connection blueprint
3. Present blueprint to user for confirmation
4. Create component WITH connections (not after)
5. Run validate_all.py to confirm connectivity

Why Connectivity-First?

| Approach | Problem | |----------|---------| | Create → Validate later | Orphaned components, W046 warnings, forgotten registration | | Create → Hope wizard finds it | Components invisible to routing | | Create → Manual wiring | Human error, inconsistent naming | | Connectivity-First | Components work immediately, no orphans |

---

Anti-Patterns

| Trap | Problem | Better Approach | |------|---------|----------------| | Category-first | "Is this a skill?" | "What does it need to do?" | | Template-matching | "This looks like X" | "What are the actual requirements?" | | Over-engineering | "Let's add flexibility" | "What's the minimum that works?" | | Under-engineering | "Just make it simple" | "What complexity is unavoidable?" | | Create-then-wire | Orphaned components | Wire first, create second |