@programmingonmars/forge

A Node CLI that orchestrates a multi-agent, AI-assisted workflow — taking a raw product idea all the way to tested code through disciplined phases (plan → spec → implement) with quality gates and auditable runs.

Forge is the executable expression of a methodology: structuring collaboration between a human, a lead orchestrator, and specialized subagents inside a reproducible pipeline. The programmer stays in charge of the result; Forge is the tool belt.

Guiding principle: document first, generate second, validate always. AI is an amplifier of method, not a substitute for it.

Requirements

• Node.js ≥ 20
• Claude Code installed and authenticated. Forge uses the Claude Agent SDK and reuses your existing Claude Code OAuth login from ~/.claude — no API keys required.

Installation

npm install -g @programmingonmars/forge

Verify the install:

forge --help

Usage

Forge ships three commands, each one phase of the FORGE method:

forge plan <prompt>

Generate a user story and acceptance criteria from a free-form prompt.

forge plan "Add SSO login with Google for the admin dashboard"

Output: a story.md + tasks.md folder you can review and edit before the next phase.

forge spec <user-story-path>

Turn a user story folder into a Blueprint — a per-task implementation spec with context, validation steps, and quality gates.

forge spec docs/stories/sso-login/

forge implement <blueprint-path>

Implement a Blueprint task using TDD and the validation loops declared in the spec. Accepts either a Blueprint folder or a single task file.

forge implement docs/blueprints/sso-login/
forge implement docs/blueprints/sso-login/task-001.md

Render modes

Every command accepts -o, --output <mode>:

• dashboard (default) — interactive Ink-based UI with live agent events.
• text — linear log output, friendly to non-TTY environments and CI.
• json — structured event stream for programmatic consumption.

Auto-approve (use with care)

--auto-approve (or FORGE_AUTO_APPROVE=1) bypasses every permission prompt and runs the agent SDK in bypassPermissions mode. Every tool call (Bash, Edit, Write, network, …) is auto-allowed. Only use this on trusted code in disposable environments (containers, ephemeral VMs).

forge implement docs/blueprints/sso-login/ --auto-approve

How it works

Each invocation is a run identified by a ULID. Forge persists, for every run:

• a manifest describing inputs, agents, and gate outcomes
• a full transcript of agent messages
• the generated artifacts (story, blueprint, code edits)

Runs live under .forge/runs/ in your project, in plain text — auditable by humans, diffable in git.

Glossary

• Skill — a Markdown file with YAML frontmatter that declares a named workflow and its phases.
• Agent — a specialized role (lead orchestrator or subagent) with its own prompt and restricted tool set.
• Gate — a numeric quality criterion the lead emits at the end of a run; below the threshold, the run fails.
• Validation loop — a sequence of shell commands (L1–L4) that validates generated code in order.
• Blueprint — a folder of per-task implementation specs produced by forge spec.

Non-goals

• Not an IDE or a git replacement — Forge does not manage branches, PRs, or code review.
• Not a multi-user server — there is no shared state across machines.
• Does not abstract the model provider — Forge is deliberately coupled to the Claude Agent SDK.
• Does not replace human review of AI-generated output.

License

MIT