Package Exports

@luizfosc/forge
@luizfosc/forge/core/agent-dispatcher
@luizfosc/forge/core/analysis-guard
@luizfosc/forge/core/artifact-gate
@luizfosc/forge/core/audit
@luizfosc/forge/core/auto-runner
@luizfosc/forge/core/best-practices
@luizfosc/forge/core/brownfield-audit
@luizfosc/forge/core/cache-stability
@luizfosc/forge/core/catalog-loader
@luizfosc/forge/core/checkpoint
@luizfosc/forge/core/claude-md-generator
@luizfosc/forge/core/complexity-scoring
@luizfosc/forge/core/compress
@luizfosc/forge/core/context-manager
@luizfosc/forge/core/context-state
@luizfosc/forge/core/cost-tracker
@luizfosc/forge/core/crash-recovery
@luizfosc/forge/core/cro-scoring
@luizfosc/forge/core/dispatch-mode
@luizfosc/forge/core/doctor
@luizfosc/forge/core/dreaming
@luizfosc/forge/core/engine
@luizfosc/forge/core/epic-executor
@luizfosc/forge/core/executor-assignment
@luizfosc/forge/core/file-utils
@luizfosc/forge/core/gate
@luizfosc/forge/core/gotchas
@luizfosc/forge/core/gray-area-detector
@luizfosc/forge/core/gray-area-resolver
@luizfosc/forge/core/guards
@luizfosc/forge/core/guards/_helpers
@luizfosc/forge/core/guards/database-guard
@luizfosc/forge/core/guards/design-spec-guard
@luizfosc/forge/core/guards/security-guard
@luizfosc/forge/core/guards/spec-quality-guard
@luizfosc/forge/core/guards/wiring-guard
@luizfosc/forge/core/hook-logic
@luizfosc/forge/core/ids
@luizfosc/forge/core/init
@luizfosc/forge/core/integration-checks
@luizfosc/forge/core/intent-classifier
@luizfosc/forge/core/logger
@luizfosc/forge/core/mailbox
@luizfosc/forge/core/memory
@luizfosc/forge/core/memory-extractor
@luizfosc/forge/core/needs-analyzer
@luizfosc/forge/core/parallel
@luizfosc/forge/core/party-mode
@luizfosc/forge/core/phase-intelligence
@luizfosc/forge/core/plugin-loader
@luizfosc/forge/core/plugin-manifest
@luizfosc/forge/core/plugin-sandbox
@luizfosc/forge/core/prd-injector
@luizfosc/forge/core/prd-parser
@luizfosc/forge/core/prd-scanner
@luizfosc/forge/core/project-registry
@luizfosc/forge/core/provider-adapter
@luizfosc/forge/core/qa-loop
@luizfosc/forge/core/ralph-loop
@luizfosc/forge/core/sherlock
@luizfosc/forge/core/stuck-detector
@luizfosc/forge/core/tech-preset
@luizfosc/forge/core/trust
@luizfosc/forge/core/veto-conditions

Readme

Forge

AI agent orchestration — from idea to deploy.

Forge is a state-driven framework that orchestrates 9 specialized AI agents through a deterministic pipeline with 17 workflows. The JS engine decides, the LLM executes, the human supervises.

Quick Start

npx @luizfosc/forge@alpha init
forge run "Build a recipe app with Next.js and Supabase"
forge status

Workflows (17)

Workflow	Use case	Type
`full-app`	New app from scratch	Full pipeline
`single-feature`	Add feature to existing project	Full pipeline
`landing-page`	Landing page with design tokens	Full pipeline
`brownfield`	Audit and improve existing codebase	Full pipeline
`design-system`	Extract DNA → tokens → components → pages	Full pipeline
`clone-site`	Premium redesign from reference	Full pipeline
`bug-fix`	Fix a specific bug	Shortcut
`quick`	Small, fast changes	Shortcut
`specs-ready`	Skip discovery, validate existing spec	Shortcut
`template`	Scaffold from template, mini-discovery	Shortcut
`replay`	Re-execute a previous run from phase N	Shortcut
`dry-run`	Simulate run (read-only), convert to real	Shortcut
`post-mortem`	Analyse completed run, extract learnings	Utility
`domino-audit`	Map process chains, detect gaps	Utility
`squad-upgrade`	Audit and enrich squads to production-grade	Utility
`stamp`	Clone shallow, extract patterns, report	Utility
`stress-test`	5-tier resilience audit	Utility

CLI Commands

Command	Description
`forge init`	Scaffold a new project (creates `.forgerc.json`, state files)
`forge run "prompt"`	Start or resume a pipeline run
`forge status`	Show current phase, stories, and progress
`forge doctor`	Diagnose state file, dependencies, and config

Agents

Agent	Persona	Role
dev	Dex	Writes code, tests, and implementation
qa	Quinn	Validates quality, runs test suites
architect	Aria	Designs system structure and tech decisions
pm	Morgan	Manages timeline, scope, and priorities
po	Pax	Owns product vision and acceptance criteria
sm	River	Facilitates flow, removes blockers
devops	Gage	Handles CI/CD, infrastructure, deploys
data-engineer	Dara	Manages data pipelines and schemas
analyst	Atlas	Researches, audits, and extracts patterns

Architecture

Forge is a state machine that manages two files:

state.json — run state (engine reads/writes atomically)
next-step.md — instruction for the LLM (engine writes, LLM reads)

idle → discovery → spec → stories → build → integration → deploy → learn → done

Human checkpoints pause the pipeline at critical gates. The human decides, then resumes with forge run --decision N.

Constitution

Art.	Rule
1	CLI First — all interaction through the terminal
2	Agent Authority — each agent owns an exclusive scope
3	Story-Driven — work is tracked as stories (except quick/bug-fix)
4	No Invention — build only what was specified
5	Quality First — lint + tests must pass before advancing
6	MVP First — smallest viable scope, then iterate
7	State File is Source of Truth — only the engine writes state
8	Scope Reduction Prohibited — never cut agreed scope

Config

Forge reads .forgerc.json from your project root. Generate the default with forge init.

{
  "workflow": "auto",
  "budget": { "ceiling": 10.00, "currency": "USD" },
  "checkpoints": { "discovery_confirm": true, "mvp_gate": true, "pre_deploy": true },
  "plugins": { "enabled": [], "disabled": [] }
}

Stack

JavaScript (ESM), Node >= 20, Vitest (2595 tests, 87% coverage).

License

MIT