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 |