forge

Forge

A hook-enforced development workflow framework for Claude Code.

Forge provides a 6-phase software development lifecycle — Discover, Specify, Design, Implement, Review, Ship — where hooks guarantee workflow compliance, skills provide phase knowledge, and state is git-committed for cross-machine continuity.

Why Forge?

Claude Code skills are advisory — Claude can choose to follow them or not. In practice, multi-step workflows get steps skipped or abandoned midway.

Forge inverts this: hooks enforce, skills guide. The Stop hook blocks Claude from finishing until measurable criteria are met (tests pass, lint clean, build succeeds). Planning phases use softer enforcement with AI-judged quality gates.

Features

• Adaptive enforcement: Soft gates for planning (warn but allow), hard gates for execution (block until DoD met)
• Automated recovery: Retry with escalation — after N failed attempts, Forge escalates to the user with full context
• Pluggable standards: Configure your lint, test, build, and format commands per project
• Cross-machine state: .forge/ directory committed to git, resume anywhere
• Fast paths: Trivial fixes skip straight to implement, small changes skip discovery and design
• Parallel code review: Multi-dimension review agents (functionality, security, performance, test quality, maintainability)
• Project detection: Auto-detects Node.js, Python, Go, Rust, .NET and suggests config

Installation

As a Plugin (recommended)

In Claude Code:

/plugin marketplace add mhylle/claude-skills
/plugin install forge@claude-skills

All skills, agents, and hooks are registered automatically.

Manual Installation

git clone https://github.com/mhylle/claude-skills.git
cd claude-skills
./install.sh

Quick Start

In any project:

/forge init          # Detect project type, create .forge/config.json
/forge start         # Begin a full workflow at Discover phase
/forge fix "typo"    # Fast path: implement -> ship
/forge status        # Check current workflow state

Architecture

Hooks (Engine)              Skills (Knowledge)          Agents (Specialists)
├── Stop (hard/soft)        ├── /forge orchestrator     ├── forge-recovery
├── SessionStart            ├── discover                ├── forge-verifier
├── PreToolUse              ├── specify                 ├── forge-researcher
├── PostToolUse             ├── design                  └── forge-reviewer
├── UserPromptSubmit        ├── implement
└── PreCompact              ├── review
                            └── ship

Phase Model

Phase	Enforcement	What happens
Discover	Soft	Research the problem, explore the codebase, write RESEARCH.md
Specify	Soft	Write requirements with testable acceptance criteria
Design	Soft	Plan architecture, write ADRs for key decisions
Implement	Hard	Build with test-first development; tests/lint/build must pass
Review	Hard	Multi-dimension code review across 5 quality dimensions
Ship	Hard	Commit, push, create PR with generated description

Commands

Command	Description
/forge init	Initialize .forge/ in current project
/forge start [phase]	Start a new workflow
/forge status	Show current workflow state
/forge continue	Resume where you left off
/forge skip-to <phase>	Jump to a specific phase
/forge fix "desc"	Fast path for trivial fixes
/forge incident "desc"	Start incident investigation
/forge history	Show completed workflows
/forge sync-check	Validate state after git pull
/forge config	View/edit project config
/forge reset	Reset current workflow

Configuration

.forge/config.json is generated by /forge init based on your project type:

{
  "standards": {
    "test": "npm test",
    "lint": "npx eslint .",
    "build": "npm run build"
  },
  "enforcement": {
    "implement": "hard",
    "review": "hard"
  },
  "max_retries": 3
}

See configuration reference for all options.

Documentation

• Getting Started
• Configuration Reference
• Extending Forge
• Troubleshooting

Prerequisites

• Claude Code
• Node.js 18+

License

MIT