Forge is an AI-driven software delivery orchestrator that coordinates seven specialized AI agents through a lean delivery pipeline — from inception to production. It uses Linear as the single source of truth and runs as a pi.dev extension with a deterministic workflow engine.
Forge is an attempt to create the perfect product team — a team of agents with enforced roles, gated handoffs, and a feedback loop where every piece of work is verifiable, gated, and recoverable. Seven agents — PO, UX, Architect, Developer, QA, DevOps, SecOps — each own a defined slice of the delivery pipeline and are blocked from operating outside it.
The outer acceptance test goes RED before any implementation code is written; TDD inner loops drive each sub-slice green (FE then BE); a QA desk check inspects every acceptance criterion through the UI exactly as a customer would; a scoped regression suite guards adjacent flows; and PO acceptance verifies shipped behavior against the original story intent. State lives in Linear — visible and human-readable — never in plan files or conversation summaries, which "lie." Loop pre-flights, failsafe auto-advance, crash recovery, and commit-per-AC guarantee nothing is silently lost.
Forge is a pi.dev extension that registers custom tools callable by the LLM. A generic, DOT-driven Graph Engine (.forge workflows) executes node pipelines, runs deterministic verifiers on node completion, serializes execution state, and projects status to Linear — ensuring agents can never skip steps or operate out of order.
- Install —
forge initdrops the pi.dev extension, 7 agent profiles, 24 skills, and configures Linear auth - Start — Run
piin your project — the extension auto-loads, registers forge tools, and starts polling Linear - Deliver — The engine polls Linear for stories, claims them, creates agent sessions, and coordinates the delivery pipeline
There is no separate process or daemon. The extension loads when you start pi
and stops when you exit.
┌─────────────────────────────────────────────────────┐
│ pi.dev runtime │
│ │
│ ┌──────────────┐ ┌───────────────────────────┐ │
│ │ LLM Agent │───▶│ Forge Extension (TS) │ │
│ │ (glm-5.2) │ │ │ │
│ │ │◀───│ ┌──────────────────────┐ │ │
│ │ Calls forge │ │ │ Graph Engine (.forge)│ │ │
│ │ tools │ │ │ • DOT executor │ │ │
│ └──────────────┘ │ │ • Verifiers │ │ │
│ │ │ • Checkpoint store │ │ │
│ │ │ • Linear projection │ │ │
│ │ └──────────┬───────────┘ │ │
│ └─────────────┼─────────────┘ │
│ │ │
│ ┌─────────────▼─────────────┐ │
│ │ Linear (GraphQL API) │ │
│ │ Stories, states, docs │ │
│ └───────────────────────────┘ │
└─────────────────────────────────────────────────────┘
| Agent | Owns |
|---|---|
| po-agent | Inception, story writing, backlog, story acceptance |
| ux-agent | Empathy mapping, UX specs, design system |
| architect-agent | Architecture Decision Records, service boundaries, tech debt |
| developer-agent | ATDD loops, TDD inner loops, contract tests, feature flags |
| qa-agent | Acceptance test authoring, desk checks, regression suite |
| devops-agent | CI/CD, environments, feature flags, deployments |
| secops-agent | Threat modeling, security ACs, SAST/DAST pipeline gates |
Each agent loads its assigned skills at session start. Roles are enforced by the workflow engine — the developer agent doesn't make architecture decisions, and the architect agent doesn't write production code.
The extension registers scoped tool families callable by the LLM (deny-by-default allowlisting per node):
| Tool Family | Purpose | Example Tools |
|---|---|---|
| node-tools | Signal node completion, query node status, request human approval | forge_node_complete, forge_node_status, forge_request_approval |
| command-tools | Run test, lint, or build commands in a sandbox | forge_run_tests, forge_run_lint, forge_run_build |
| linear-tools | Pull stories and create/read artifacts | forge_create_artifact, forge_read_artifact, forge_claim_story |
| git-tools | Inspect git log and status (read-only) | forge_git_log, forge_git_status |
| context-tools | Read context from declared namespaces | forge_read_context |
- pi.dev v0.80+ installed (
curl -fsSL https://pi.dev/install | sh) - Bun runtime
- A Linear account with API access
# Install globally
bun add -g @loopworx/forge
# or: npm install -g @loopworx/forge
# Initialize in your project
cd my-project
forge init
# Start pi.dev — the forge extension auto-loads
pi| Path | Contents |
|---|---|
.pi/extensions/forge.ts |
Forge extension entry point (imports from dist/) |
.forge/ |
Persistence directory (executions, sessions, auth.json) |
templates/agents/ |
7 agent profile definitions with skill assignments |
templates/skills/ |
24 skills (SKILL.md each; lean domain expertise) |
templates/workflows/ |
4 .forge workflows (pipeline.forge, atdd.forge, tdd-slice.forge, inception.forge) |
templates/forge.yaml |
Config template — poll interval, concurrency, graph file |
forge.yaml |
Project config (created from template) |
forge.yaml supports both camelCase and snake_case:
# Workflow Graph
workflow:
graphFile: "templates/workflows/pipeline.forge" # custom .forge DOT workflow
# Polling
pollInterval: 30 # seconds between Linear polls
pullStates: # states to pull stories from
- ready-for-dev
- ready-for-qa
# Concurrency
maxConcurrentStories: 3
# Linear
linear:
teamId: "team-abc123"
teamName: "Engineering"Stories flow through Linear workflow states:
in-analysis → ready-for-dev → in-dev → ready-for-qa → in-qa
→ ready-for-acceptance → in-acceptance → ready-to-deploy → done
- Stories are pulled, not assigned — the engine polls for stories in pull states, claims them (pull → active), and creates agent sessions
- Handoff comments — agents post compact summaries to Linear; the next agent reads them as context
- Failsafe — if an agent forgets to update Linear state but posted a handoff comment, the engine auto-advances; if no comment, it halts as
halted-ambiguous - Crash recovery — on startup, the engine checks
.forge/sessions.jsonfor orphaned sessions and re-claims active ones - Commit per AC — after each acceptance criterion goes green, the developer agent commits with
feat({STORY-ID}): AC{n} — {summary}before desk check
- Inception (8 phases) — PO, UX, and Architect agents facilitate structured discovery
- Story Refinement — Four-gate review: PO drafts → UX value gate → developer feasibility → QA testability
- Iteration Zero — CI/CD, environments, test harness scaffold, feature flags
- ATDD Loops — Outer Acceptance Test RED → sub-slice TDD (FE + BE) → GREEN → desk check
- Kanban Flow — Stories move through the Linear state machine independently
- Feature Flags + Trunk-Based CD — Everything on trunk; unfinished stories behind flags
Meta
using-forge— precedence rules, agent roles, session start protocolresuming-sessions— query Linear + read CONTEXT.md before anything else
Discovery (8-phase inception)
facilitating-inception,facilitating-event-storming,establishing-ubiquitous-language,designing-ux,writing-stories,building-iteration-map
Architecture
selecting-tech-stack,establishing-architecture,deciding-architecture
Iteration Zero
bootstrapping-project,validating-test-harness
Development (L1 Rigid)
running-atdd-sessions,running-tdd-loops,managing-feature-flags
Quality & Acceptance
running-desk-checks,writing-acceptance-tests,running-regression-suiteapproving-stories,finishing-stories
Security
modeling-threats,securing-pipeline,guarding-loops
Each skill has a SKILL.md (pure domain expertise). All 24 are validated by template tests.
# Clone
git clone https://github.com/loopworx/forge
cd forge
bun install
# Checks
bun run lint # oxlint — 0 warnings, 0 errors
bun run typecheck # tsc --noEmit
bun test # 682 tests across 60 files
bun run build # bundle → dist/forge.js
# Test forge init locally
mkdir /tmp/forge-test && cd /tmp/forge-test
bun run /path/to/forge/bin/forge.ts initsrc/
├── agent/ # pi.dev runtime session manager, tools, event adapters
│ └── tools/ # Scoped tool families (node, command, linear, git, context)
├── engine/ # Generic DOT-driven Graph Engine
│ ├── graph/ # DOT parser, validator, executor, template expansion, linear projection
│ ├── verifiers/ # Deterministic verifiers (git-commit, test-red, test-green, lint-clean, etc.)
│ ├── types.ts # All types (WorkflowState, AgentRole, Story, etc.)
│ ├── interfaces.ts # Core seam interfaces
│ ├── events.ts # EngineEventBus
│ ├── claim-queue.ts # FIFO serialization
│ ├── workflow-engine.ts # Engine dispatch onto GraphExecutor
│ ├── file-persistence.ts # .forge/ state persistence
│ └── session-manager.ts
├── config/ # YAML config loader (supports workflow.graphFile)
├── prompts/ # Lean node prompt builder
└── cli/ # CLI commands (init, setup, graph render)
Every push to main runs a single sequential pipeline:
build → (typecheck ‖ lint) → test → release
The release job auto-increments the npm version, publishes, creates a git tag, and generates a GitHub Release with commit history as release notes.
- Fork the repository
- Create a feature branch
- Ensure
bun run lint && bun run typecheck && bun test && bun run buildpass - Submit a PR
MIT — see LICENSE.