The Forger's Guide

01What is Forge?v3.0

We plan first. Not because we're slow — but because the time you 'save' by skipping planning you pay back ten times over in rework, architecture bugs, and code nobody understands.

Forge is a unified planning and construction system for building production-ready SaaS applications with Claude Code. It's a complete factory that takes you from idea to deployed code.

The Philosophy

The Complete Flow

02Installation & First Steps

Mac / Linux

Windows (WSL)

Step 0: What you need first

Before cloning Forge, you need three tools. If you already have them, skip to Step 1.

npm install -g @anthropic-ai/claude-code

claude --version

brew install node

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

node --version

Windows Users

Forge runs natively on macOS and Linux. On Windows, you need WSL 2 (Windows Subsystem for Linux). It takes about 5 minutes:

wsl --install

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs git

Setup in 4 Steps

git clone https://github.com/getforja/forge-pro.git ~/forge

# For zsh (macOS default)
echo "alias forge='cp -r ~/forge/. .'" >> ~/.zshrc
source ~/.zshrc

# For bash
echo "alias forge='cp -r ~/forge/. .'" >> ~/.bashrc
source ~/.bashrc

mkdir mi-saas && cd mi-saas
forge                           # Copy all infrastructure
npm install                     # Install dependencies
cp example.mcp.json .mcp.json  # Configure MCPs (add your keys)
npm run dev                     # Start dev server

claude .                        # Open Claude Code in the project
/forge-check                    # Verify everything is configured
/onboarding                     # Personalized route to get started

What does forge install?

03The Forge Flow (End-to-End)

Phase 1: Planning — /plan

The /plan command activates La Herreria, a pipeline of up to 10 skills that transform your idea into an executable Blueprint.

Total: 5-8 hours -> 10 professional documents. Times vary by idea complexity and user interactions.

Optional Skills

Depending on the Build Mode, the pipeline may include:

• —Lean Canvas — Quick BMC alternative for MVPs
• —Job Stories — Alternative to User Stories (When I... format)
• —Pre-Mortem — Risk analysis before building
• —Interview Script — Script for validating with real users

Phase 2: Construction — /build

The /build command takes the approved Blueprint and executes it. It asks how you want to build:

04Planning — La Herreria

The /plan command activates La Herreria, a pipeline of up to 10 skills that transform your idea into an executable Blueprint. Each skill produces a professional document.

The 10 Skills

Total: 5-8 hours → 10 professional documents. Times vary by project complexity.

Build Modes

La Herreria adapts to your project type:

Project Personalizationv2.8

The /forge-init command personalizes CLAUDE.md for your specific project. It adds an Active Project section, generates a project-specific README, and deactivates irrelevant skills based on your project type.

/forge-init

05El Crisol — Strategic Validationv2.5

El Crisol is an optional phase between /plan and /build. It runs 7 strategic analyses to validate your Blueprint before you invest time building. The output is an interactive HTML dashboard with a Build Confidence Score.

The 7 Analyses

Build Confidence Score

A weighted score from 1-10 across all 7 dimensions. It tells you whether to proceed, adjust, or pivot before writing code.

Output

El Crisol produces an interactive HTML dashboard with Bento Grid layout, Liquid Glass effects, and Chart.js visualizations. All 7 analyses in a single, shareable file.

06Build Modes

When you run /plan, La Herreria asks what you want to build. Each mode activates an optimized pipeline:

Mode Comparison

Building Blocks

5 Design Systems

07Command Reference

Main Pipeline

Setup & Orientation

Design Quality

Product Strategy

Business Intelligence

Engineering Workflow

Lifecycle

08The Golden Path (Single Stack)

They can have any color they want, as long as it's black.
Henry Ford — No technology choices are made. The perfected stack is executed.

Backend Choice

Feature-First Architecture

All the context for a feature lives in one place. You don't jump between 5 folders.

src/
├── app/
│   ├── (auth)/
│   ├── (main)/
│   └── layout.tsx
│
├── features/
│   ├── auth/
│   │   ├── components/
│   │   ├── hooks/
│   │   ├── services/
│   │   ├── types/
│   │   └── store/
│   └── [feature]/
│
└── shared/
    ├── components/
    ├── hooks/
    ├── lib/
    └── types/

MCPs — Your Senses and Hands

09Specialized Agents

Forge includes 12 agents that activate based on context during the build.

Included Design Systems

During UI Design (Skill #8), you can choose one of 5 pre-configured design systems:

20 Built-in Skills 20 skills

10Security & Auto-Shielding

Security is not an optional step at the end. It's the difference between a product and an attack vector.

Protection Layers

7 Fail-Open Hooks

Principle: if a hook fails unexpectedly, it approves the action. It never traps the user.

claude config set hookMode auto

Adversarial Review v2.6

The /adversarial-review command launches 4 attacking agents that try to break your app from different angles: injection, auth bypass, data exposure, and supply chain. Codex provides a second opinion. Critical findings block deployment.

Critical Security Rules

11Tips System

Forge reveals its capabilities progressively. Instead of showing you 30+ commands at once, it gives you relevant tips based on what you're doing.

Karpathy Principles v2.8

Token Auditor v2.7

The /audit-tokens command analyzes your Forge configuration for token efficiency. It runs 8 checks, generates a 0-100 score, and provides the top 5 fixes to reduce token usage.

3 Types of Tips

System Rules

• —Frequency: every 3-5 messages, not every response
• —Maximum 1 tip per response (of any type)
• —Priority: Security > Git > Tip
• —Don't repeat tips already shown in the session
• —Always actionable — includes the concrete command
• —Read the tone — if you're in a hurry, the tip is omitted

When They Appear

12Cheat Sheet

Your First Project (Quick Start)

# 1. Setup (once)
git clone https://github.com/getforja/forge-pro.git ~/forge
echo "alias forge='cp -r ~/forge/. .'" >> ~/.zshrc && source ~/.zshrc

# 2. New project
mkdir my-app && cd my-app
forge && npm install
cp example.mcp.json .mcp.json  # Add your keys

# 3. Start with Claude
claude .
/forge-check    # Verify environment
/plan           # Plan (or /onboarding if first time)
/crisol         # Strategic validation (optional)
/build          # Build from Blueprint

Commands by Phase

Claude Code Keyboard Shortcuts

Git Conventions

# Atomic commit format
feat(F1-T1): create auth service with signUp and signIn
fix(F1-T3): fix RLS policy for profiles table
refactor(F2-T1): extract validation utils
test(F3-T2): add permission middleware tests
style(F2-T4): align spacing in dashboard

# Valid types
feat | fix | refactor | test | style | docs | chore

Your next project.
Forged, not generated. Plan first. Forge always.