Architecture Overview

Architecture Overview

claude-forge decomposes software development into isolated phases, each executed by a specialized subagent. The main agent acts as a thin orchestrator — routing work, presenting summaries, and managing state — while subagents handle all code reading and writing.

Component Diagram

How the Pieces Connect

SKILL.md (orchestrator)
  ├── calls mcp__forge-state__* MCP tools for state transitions
  ├── invokes agents/ by name via Agent tool
  └── hooks/ enforce constraints automatically
       ├── pre-tool-hook.sh  → blocks writes in Phase 1-2,
       │                        blocks git commit in parallel Phase 5,
       │                        blocks checkout to main/master
       ├── post-agent-hook.sh → warns on bad agent output
       ├── post-bash-hook.sh  → auto-commits summary.md + state.json (v1 legacy; v2 uses Engine exec action)
       └── stop-hook.sh       → blocks premature stop

Responsibility Matrix

Responsibility	Owner
Phase sequencing & control flow	SKILL.md (orchestrator)
State transitions	Go MCP server (mcp__forge-state__* tools)
Constraint enforcement	Hook scripts (automatic)
Domain expertise (analysis, design, code)	Agent .md files
Runtime parameters	Orchestrator → Agent prompt

Directory structure

claude-forge/
├── CLAUDE.md              ← AI agent guide (auto-loaded by Claude Code)
├── ARCHITECTURE.md        ← index (full docs in docs/architecture/)
├── BACKLOG.md             ← known issues, improvement candidates
├── README.md              ← project overview and quick start
├── .claude-plugin/
│   └── plugin.json        ← plugin metadata (name, version)
├── .claude/
│   └── rules/
│       ├── git.md         ← Git practices enforced in this repo
│       ├── shell-script.md ← Shell scripting conventions for *.sh files
│       └── docs.md        ← Documentation rules (SSOT, bilingual, VitePress)
├── agents/                ← 10 named agent definitions (.md files)
│   ├── README.md          ← agent roster with roles
│   ├── situation-analyst.md
│   ├── investigator.md
│   ├── architect.md
│   ├── design-reviewer.md
│   ├── task-decomposer.md
│   ├── task-reviewer.md
│   ├── implementer.md
│   ├── impl-reviewer.md
│   ├── comprehensive-reviewer.md
│   └── verifier.md
├── docs/
│   ├── _partials/         ← SSOT content fragments (included by docs/)
│   └── architecture/      ← architecture documentation (13 focused files)
├── hooks/
│   └── hooks.json         ← hook definitions (Setup, SessionStart, PreToolUse, PostToolUse, Stop)
├── mcp-server/            ← Go MCP server source (forge-state binary)
├── scripts/
│   ├── common.sh          ← shared find_active_workspace helper
│   ├── launch-mcp.sh      ← self-healing MCP launcher
│   ├── session-start-hook.sh ← dashboard URL display at session start
│   ├── pre-tool-hook.sh   ← read-only guard, commit blocking, checkout blocking
│   ├── post-agent-hook.sh ← agent output quality validation
│   ├── post-bash-hook.sh  ← auto-commits state.json+summary.md (v1 legacy)
│   ├── setup.sh           ← downloads forge-state-mcp binary from GitHub Releases
│   ├── stop-hook.sh       ← pipeline completion guard
│   └── test-hooks.sh      ← automated test suite (62 tests)
└── skills/
    └── forge/
        └── SKILL.md       ← orchestrator instructions (the main skill)

---