Forge

Design guidance + execution system for Claude Code plugin development.

Forge helps you structure decisions about how to design or improve plugins, skills, agents, commands, hooks, and MCP components in a semantically correct way.

What Forge Is

Forge is a design guidance + execution system that:

• Structures evidence, variables, and trade-offs
• Executes only after user confirmation
• Follows a 9-phase operational workflow

What Forge Is NOT

Forge is NOT:

• A workflow enforcement tool (enforcement is optional)
• A skills provider (it reads existing skills)
• A decision maker (it presents options, user decides)

Quick Start

# Start the full workflow
/forge I want to add a validation hook

# Direct phase access
/forge analyze scripts/        # Codebase analysis
/forge design                  # Design options
/forge validate                # Validation check

# Show interactive menu
/forge

9-Phase Workflow

Phase	Name	Strict	Description
0	Input Normalization	YES	Normalize intent, identify scope
1	Semantic Routing	no	0-stage triage based on hints
2	Codebase Reality	no	Factual description of code
3	Mismatch Evaluation	no	Compare intent vs reality
4	Structured Questioning	YES	Collect decision variables
5	Option Synthesis	no	Propose options with trade-offs
6	Workflow Creation	no	Create workflow if needed
7	Execution	YES	Execute after confirmation
8	Validation	no	Final validation gate

Strict Phases

Phases 0, 4, and 7 are strict - they enforce tool restrictions:

• Phase 0: Must capture intent before proceeding
• Phase 4: Must follow Structured Dialogue Contract
• Phase 7: Requires user confirmation before execution

Commands

Command	Description
/forge	Main entry with routing
/diagnose	Direct Phase 2 (codebase analysis)
/design	Direct Phase 5 (options)
/workflow	Workflow management

Agents

Agent	Phase	Purpose
input-normalizer	0	Normalize intent
semantic-router	1	Triage routing
codebase-analyzer	2	Reality description
mismatch-evaluator	3	Intent vs reality
questioner	4	Structured questioning
option-synthesizer	5	Design options
workflow-manager	6	Workflow creation
execution-orchestrator	7	Confirmed execution
validator	8	Final validation

Structured Dialogue Contract

Phase 4 questions must follow this format:

Problem:
<mismatch or ambiguity>

Codebase:
<current design intent>

Evidence:
<specific observations>

Question:
<decision variable, NOT choice>

Question Intent:
<why this matters>

See references/structured-dialogue-contract.md for details.

Workflow Versioning

Workflows support dynamic versioning:

1. Create: Version = 1, Confirmed = false
2. Modify: Version++, Confirmed = false
3. Confirm: Confirmed = true, execution enabled
4. Execute: Follows workflow steps

If workflow is modified after confirmation, reconfirmation is required.

State Management

Forge uses a daemon for state management:

# Check state
python3 scripts/forge-state.py state

# Check phase
python3 scripts/forge-state.py phase

# Check workflow
python3 scripts/forge-state.py workflow

Hooks

Forge uses hooks for enforcement:

Hook	Purpose
SessionStart	Initialize state
UserPromptSubmit	Detect confirmation
PreToolUse	Phase-appropriate tools
PostToolUse	Phase completion
Stop	Validation check

Design Decisions

1. Essential phases strict from start: 0, 4, 7
2. Other phases latent + promotable: Can become strict when needed
3. Dynamic versioned daemon: Modification requires reconfirmation
4. Validation is fixed Phase 8: Always runs at termination
5. Methodology in agents: Phase logic encoded in agents
6. Questions collect variables: Never choices
7. 0-stage routing is triage: Identifies axes, not decisions
8. Workflow scope selective: Comprehensive when needed

Dogfooding

This implementation follows the Forge specification in plan.txt. The user will dogfood by running Forge on itself after completion.

Files

forge/
├── plugin.json           # Plugin manifest
├── commands/             # 4 commands
├── skills/               # 2 reference skills
├── agents/               # 9 phase agents
├── hooks/forge.json      # Hook configuration
├── scripts/              # Daemon and hook scripts
├── config/               # Phase definitions
└── references/           # Documentation

License

MIT