Forge

A CLI that scaffolds and manages an agent development harness for any project. Designed to be called by Claude Code, not by humans directly.

The harness is a complete build/bugfix/review automation system — scripts, skill prompts, doc structure — that lets a coding agent build features from specs and fix bugs autonomously.

Install

npm install -g @m6un/forge

Commands

forge init

Scaffolds the harness into the current project:

.claude/scripts/     — worktree, verify, publish, escalate scripts
.claude/skills/      — build, bugfix, fix-review skill prompts + shared reviewer/retro
docs/                — design docs, exec plans, product specs, retros
AGENTS.md            — repo map and invariants (you fill in)
ARCHITECTURE.md      — system overview and layer rules (you fill in)
forge.config.ts      — domain config (verify commands, layer rules)

After init, fill in the project knowledge — architecture, core beliefs, domains — then run forge check.

forge check

Verifies the project has the minimum foundation for /build and /bugfix to work:

• ARCHITECTURE.md has real content
• forge.config.ts has at least one domain with verify commands
• Core beliefs are defined
• All skill prompts are present

Returns JSON with pass/fail per check. Exit code 1 on any failure.

forge add-domain <name> [path] [verify-json] [layers]

Registers a domain in forge.config.ts.

forge add-domain backend backend/ '["npm ci", "npm run typecheck", "npm test"]'
forge add-domain ios ios/ '["swiftlint --path ios"]' .github/scripts/lint-ios-layers.sh

forge update

Syncs forge-managed files (scripts, skill prompts, spec template) from the installed forge version into the project. Never touches project-owned files. Writes a .forge-changeset.json manifest describing what changed.

How it works

The harness provides three skill-driven workflows:

/build <spec-file> — Build a feature from a spec. Runs up to 3 cycles of build → verify → publish → review. Escalates as a draft PR if all cycles fail.

/bugfix <bug-report> — Diagnose and fix a bug. Same loop structure as build, but starts with root cause analysis.

/fix-review <pr-number> — Read PR review comments, fix the code, verify, and push.

Each workflow uses isolated git worktrees, automated verification (type-check, lint, test), and a reviewer agent that checks the diff against the project's architecture rules and core beliefs.

File ownership

Forge-managed (synced by forge update):

• .claude/scripts/*, .claude/skills/**/*, docs/exec-plans/_template.md

Project-owned (never overwritten):

• AGENTS.md, ARCHITECTURE.md, CLAUDE.md, forge.config.ts
• docs/design-docs/core-beliefs.md, docs/product-specs/*

Config

forge.config.ts holds what varies per project — domains and their verify commands:

export default {
  domains: {
    backend: {
      path: "backend/",
      verify: ["npm ci", "npm run typecheck", "npm run lint", "npm test"],
      layers: ".github/scripts/lint-backend-layers.sh"  // optional
    }
  }
}

run-verify.sh reads this config and runs each domain's commands. That's it.

Output

All commands output JSON. This is an agent tool — output is machine-readable, not pretty.

License

MIT