forge-analyzer

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