forge-cli

AI agent pipeline scaffolding for Claude Code. Turns any repository into an orchestrated, multi-agent workspace with decomposition, risk classification, parallel execution, and automated delivery.

Install

npm install -g @samahlstrom/forge-cli

This installs forge as a global command. Use it in any project from now on.

Quick start

New project from scratch

mkdir my-app && cd my-app && git init
forge init

The onboarding asks what language, framework, and project type you want, then generates everything.

Existing project

cd my-existing-project
forge init

Forge auto-detects your stack (language, framework, test runner, linter) and generates a harness that matches.

From a spec document

mkdir my-app && cd my-app && git init
forge init --spec ~/Downloads/project-spec.pdf

Forge analyzes the spec with Claude, extracts project metadata (language, modules, architecture, constraints), and pre-fills everything. No manual onboarding needed.

From multiple spec documents

mkdir my-app && cd my-app && git init
forge ingest \
  ~/Downloads/architecture.md \
  ~/Downloads/engineering-backlog.md \
  ~/Downloads/database-schema.md
forge init

Forge combines multiple documents into one spec, analyzes it, and sets up the harness.

What it does

forge init scans your project, asks a few questions about what you're building, and generates a complete .forge/ harness with:

• Pipeline scripts — a state machine that routes work through intake, classification, decomposition, execution, verification, and delivery
• Specialist agents — architect, backend, frontend, quality, and security agents (only the ones your project needs)
• Risk classification — T1/T2/T3 tiers that determine how much decomposition and verification a task gets
• Task tracking — work tracked via bd (Dolt-backed issue tracker for AI agents)
• Hooks — pre-edit and post-edit hooks that enforce tracked work
• Skills — /deliver, /ingest, and /skill-creator commands for Claude Code

Usage

After init, open Claude Code in your project:

/deliver — execute tracked work

/deliver "Add JWT authentication with role-based access"

The pipeline:

1. Intake — parses and scores the work description
2. Classify — assigns risk tier (T1 low, T2 moderate, T3 critical)
3. Decompose — breaks complex work into parallel-safe subtasks
4. Execute — dispatches subtasks to specialist agents
5. Verify — runs typecheck, lint, tests, anti-pattern checks
6. Deliver — creates branch, commits, pushes, opens PR

/ingest — decompose a spec into a project plan

# Add specs to your project
forge ingest ~/Downloads/platform-spec.pdf

# Or multiple documents at once
forge ingest architecture.md backlog.md schema.md

# Then in Claude Code:
/ingest spec-a1b2

Multi-pass analysis:

1. Extract — sections, requirements, constraints, data entities
2. Map domains — group into modules with dependency graph
3. Decompose — epics, features, atomic tasks
4. Identify skills — find repeated patterns worth automating

You review and refine the plan before any code is written. Then execute phase-by-phase through /deliver.

/skill-creator — generate custom skills

/skill-creator

Create new Claude Code skills for domain-specific workflows. The ingestion system can also auto-generate skills from patterns it finds in your spec.

Commands

| Command | Description | |---|---| | forge init | Initialize harness in current project | | forge init --spec <file> | Initialize from a spec document (PDF, markdown, text) | | forge ingest <files...> | Add one or more spec documents for analysis | | forge add <addon> | Install an addon (browser-testing, compliance-hipaa, compliance-soc2) | | forge remove <addon> | Remove an addon | | forge status | Show harness status, agents, addons | | forge doctor | Diagnose harness health | | forge upgrade | Upgrade harness files to latest version |

What gets generated

my-project/
├── forge.yaml                          # Main configuration
├── CLAUDE.md                           # Agent instructions
├── .claude/
│   ├── settings.json                   # Permissions and hooks
│   └── skills/
│       ├── deliver/SKILL.md            # /deliver command
│       ├── ingest/SKILL.md             # /ingest command
│       └── skill-creator/SKILL.md      # /skill-creator command
└── .forge/
    ├── pipeline/                       # State machine scripts
    │   ├── orchestrator.sh
    │   ├── intake.sh
    │   ├── classify.sh
    │   ├── decompose.md
    │   ├── execute.md
    │   ├── verify.sh
    │   └── deliver.sh
    ├── agents/                         # Specialist agent definitions
    │   ├── architect.md
    │   ├── backend.md                  # (if project needs it)
    │   ├── frontend.md                 # (if project needs it)
    │   ├── quality.md
    │   └── security.md
    ├── context/                        # Project knowledge
    │   ├── stack.md                    # Tech stack conventions
    │   └── project.md                  # Your project context
    ├── hooks/                          # Claude Code lifecycle hooks
    ├── specs/                          # Ingested spec documents
    └── addons/                         # Installed addon files
.beads/                                 # bd task tracking (Dolt database)

Supported stacks

Forge auto-detects and has presets for:

• TypeScript/JavaScript — Next.js, SvelteKit
• Python — FastAPI, Django, Flask
• Go — Gin, Chi, Fiber

Works with any project regardless of stack — presets just provide stack-specific conventions.

Addons

forge add browser-testing      # Playwright visual QA
forge add compliance-hipaa     # HIPAA security checks
forge add compliance-soc2      # SOC2 compliance verification

Requirements

• Node.js 18+
• Git
• bd (task tracking — brew install beads)
• jq (for JSON processing in pipeline scripts)
• gh CLI (for PR creation)
• Claude Code (to run the generated harness)

License

MIT