One workshop. Four Stations. Every phase of your software lifecycle — Smelt, Forge, Guard, Learn — under one roof, AI-run, product-owner-supervised.
Plan Forge is the orchestration harness that sits on top of GitHub Copilot (and other AI coding tools). It does not replace your model or your IDE — it adds the SDLC layer GitHub deliberately leaves to the ecosystem: planning, validation gates, memory, cost control, and reviewer separation.
It is also licensed MIT because your SDLC is yours, and your institutional memory lives in OpenBrain , a user-owned service, because your accumulated decisions should not be trapped inside any one AI vendor.
Three closed loops, not one. The Forge builds, Forge-Master supervises, and the Learn station feeds every finding back into the next plan — agents supervising agents, loops that run unattended for weeks and learn from every pass. Every discipline of a 20-person engineering team (architecture, security, QA, SRE, engineering management, continuous improvement) is encoded as agents and guardrails governed by 40 years of software engineering practice. You own the spec, the direction, and the final acceptance test. The shop owns everything in between.
Harness on substrate, not a Copilot replacement. See the GitHub stack alignment and surface-by-surface map.
"A blacksmith without a shop is just a hammer in a hand." — Plan Forge gives your AI agent the whole shop.
Spending thousands on AI tokens and hitting the 80% wall? Read why — and how to fix it →
Smelt → Forge → Guard → Learn — every SDLC phase, one shop.
Zero to hardened plan execution in 4 steps
pforge init -Preset dotnet
Detailed setup guide below ↓ · Step-by-step manual quickstart · Quick reference card
Five short walkthroughs — same product, framed for who you are.
One setup, all your AI tools — Claude, Cursor, Codex, Copilot. 10–15 min
Write specs with Spec Kit. Enforce them with Plan Forge. 10 min
Measurable AI quality, CI enforcement, budget tracking. 15 min
Same VS Code + Copilot — with guardrails and quality scores. 15–20 min
Most automated AI pipeline available — Full Auto + MCP tools. 12–15 min
The Four Stations
Every station is a phase of the software lifecycle. Every station is run by AI, watched by you, and wired into the next.
Every plan starts as ore. The Smelt station interviews you, extracts the real requirements, flags hidden assumptions, and pours out a Scope Contract the AI can't argue with.
The anvil. Plans are broken into slices and struck one at a time — each a commit, each with its own gate. The hammer doesn't swing twice on the same slice unless tests pass.
The watchtower. LiveGuard scans secrets, env drift, CVE surface, and regression risk — before deploy, after every slice, every hour. Incidents become triaged fix plans, not pager calls at 3 AM.
The brain above the bench. Plan Forge remembers every incident, every fix, every review — and feeds it back into the next session as OpenBrain memories, bug-registry entries, and testbed findings. The shop gets sharper the longer you run it.
Want the full walkthrough?
Take the Shop TourAbove the Four Stations
Four stations don't run themselves. Forge-Master and the Inner Loop walk the floor — rerouting work when a slice fails, retrying with what they learned, and feeding every outcome back into Smelt as the next ore.
This is what turns a 7-step pipeline into a closed loop: every failed test becomes a Crucible idea, every regression becomes a slice, every postmortem becomes a memory. The shop sharpens itself.
The foreman walks the floor — Forge-Master orchestrates, the Inner Loop closes the cycle.
The Problem
Fast isn't the same as good. Without structure, AI-generated code tends to be untestable, insecure, and impossible to maintain at scale.
"I'll also add..." — features you never asked for, silently introduced. You find out at code review.
Database pattern, framework choice, architecture — picked without asking. You discover the consequences too late.
Ships code that doesn't build or breaks tests. "It should work" is not a quality gate for production.
Every session starts from zero. You re-explain the same architecture decisions to a blank-slate AI every single time.
"A blacksmith doesn't hand raw iron to a customer.
They heat it, hammer it, and temper it until it holds its edge."
Plan Forge does the same for your AI-generated software.
Features
Guardrails, specialized reviewers, autonomous execution, cost tracking, and a live dashboard — every project gets the full suite.
Automatic protection at two levels. The baseline ships with every preset. The project profile is generated per-project via an interview prompt.
Architecture principles, OWASP security, TDD, error handling, type safety, async patterns. Ships automatically. No configuration needed.
Coverage targets, latency SLAs, compliance requirements, domain-specific rules — generated from a one-time interview and stored in the repo.
Dedicated AI reviewer personas — each focused on one concern, checking it deeply.
One command runs an entire hardened plan — spawning AI workers, validating at every slice boundary, tracking cost, and reporting results. Monitor everything in a live dashboard.
pforge run-plan <plan> — automatic execution with DAG scheduling, validation gates, token tracking. Full Auto or Assisted modes.
localhost:3100/dashboard — real-time slice progress, cost charts, run history, session replay, quick actions.
[P] tags for concurrent slices. 23-model pricing table. Per-slice token tracking. Monthly cost reports.
Instruction files load automatically based on the file being edited. Editing SQL? Database guardrails load. Editing auth? Security guardrails load. No action needed.
Multi-model consensus. Dispatch each slice to 3 AI models in parallel for independent dry-run analysis, synthesize the best approach, then execute with higher confidence.
--quorum=auto triggers only on complex slices (score ≥ 6)Closed-loop bug discovery. The audit drain probes live routes, triages findings into bug/spec/classifier lanes, and iterates until convergence. Runs post-plan or on demand.
pforge audit-loop — manual one-shot drainaudit.mode: "auto" — threshold-gated, default off
A read-only reasoning orchestrator with its own dashboard. Classifies intent, pulls OpenBrain memory, and chains read-only forge tools on your behalf — so you can ask open-ended questions instead of wiring tool calls by hand.
forge_master_ask MCP tool for agents that want one-shot reasoningpforge forge-master status|logs CLI for scripts + health checksMulti-step executable procedures with validation gates between steps.
/database-migration
/staging-deploy
/test-sweep
/code-review
/health-check
/forge-execute
15 prompt templates for generating consistent code patterns — entities, services, controllers, tests, DTOs, workers, and more — all following your project's architecture.
Hooks run automatically at agent lifecycle points — blocking edits to forbidden paths, warning on TODO markers, auto-formatting, and alerting when code ships without tests.
Works with the Copilot cloud agent out of the box. Add copilot-setup-steps.yml to provision guardrails, MCP tools, and validation gates before the agent writes a single line.
.vscode/mcp.jsonRun pforge smith to inspect your forge before you build. Diagnoses your environment, VS Code configuration, setup health, version currency, and common problems — with actionable fix suggestions for every issue.
Drop one line into your GitHub workflow to validate plans on every PR — setup health, file counts, placeholders, orphans, plan artifacts, and code sweep.
- uses: srnichols/plan-forge-validate@v1Auto-imports Spec Kit specs, plans, and constitutions. Shared extension catalog. Write specs with Spec Kit, enforce them with Plan Forge.
See the combined workflow →106 MCP tools (Core + LiveGuard + Watcher + Crucible + Tempering + Bug Registry + Testbed + Forge-Master + Lattice + Sync + Memory + Notify + Doctor) — run plans autonomously with forge_run_plan, multi-model analysis with forge_analyze --quorum and forge_diagnose, full health check with forge_liveguard_run, query the code graph with forge_lattice_query, sync agent memory with forge_sync_memories, generate images with forge_generate_image, track costs with forge_cost_report, monitor in real-time via WebSocket hub + dashboard at localhost:3100/dashboard. Full Auto, Assisted, and Quorum execution modes. xAI Grok + OpenAI support via API provider registry.
When a slice fails, the orchestrator automatically walks the escalationChain and retries on the next model — no manual intervention. Historical performance data in model-performance.json drives automatic model selection for best quality/cost ratio.
Slice fails → walks escalationChain → retries on next model. Emits slice-escalated event.
model-performance.json tracks success rate, cost, duration. Auto-selects cheapest model with >80% pass rate.
--estimate shows recommended model per slice with historical success rate before you run.
pforge smith checks GitHub for newer releases (24 h cache, silent offline). pforge ext publish outputs both a Plan Forge and a Spec Kit-compatible catalog entry in one command.
pforge update| Type | What It Is | When It Runs | Example |
|---|---|---|---|
| 📋 Instruction | Coding rules the AI must follow | Auto-loads when you edit a matching file | security.instructions.md |
| 📐 Prompt | Scaffolding recipe you attach in chat | When you reference it in Copilot Chat | new-entity.prompt.md |
| 🤖 Agent | Specialized reviewer persona | When you pick it from the agent dropdown | security-reviewer.agent.md |
| ⚙️ Skill | Multi-step procedure with validation | When you type /skill-name |
/database-migration |
Instructions = passive rules (auto-loaded). Prompts = recipes (you trigger). Agents = reviewers (you pick). Skills = workflows (you invoke).
LiveGuard
Plan Forge sessions end when the code ships. LiveGuard watches everything after — drift, secrets, dependencies, regressions, incidents. 14 post-coding tools that detect, respond, and learn automatically.
Continuously score your codebase against architecture guardrail rules. Catches empty-catch blocks, unsafe types, sync-over-async, SQL injection, and deferred work markers.
Violations don't just get reported — they trigger automatic incident capture, fix proposal generation, and regression verification. One call does it all.
▸▸▸ violation markersEvery finding is captured. The system tunes itself — escalation chains reorder by success rate, cost estimates calibrate from actuals, quorum thresholds adapt. The forge gets smarter every run.
forge_liveguard_run
One call replaces 8
Full health check in a single MCP tool call. Runs drift scan, sweep, secret scan, regression guard, dep watch, alert triage, and health trend — returns a unified status.
{
"drift": { "score": 100, "appViolations": 0 },
"sweep": { "appMarkers": 0 },
"secrets": { "findings": 0 },
"regression": { "gates": 2, "passed": 2, "failed": 0 },
"deps": { "vulnerabilities": 0 },
"alerts": { "critical": 0, "high": 0, "openIncidents": 0 },
"health": { "avgScore": 100, "trend": "stable" },
"overallStatus": "green"
}Persistent Memory
Every decision you make, every pattern you establish, every lesson learned — captured once and searchable forever. Across sessions, across AI tools, across projects.
Plan Forge agents automatically capture architecture decisions, patterns, and postmortems as they work — tagged by project, phase, and slice. The Shipper (Step 6) batch-captures lessons learned after every feature.
Semantic vector search understands intent. Ask "what did we decide about caching?" and find it — even if you never used exactly those words in the original thought.
Works with GitHub Copilot, Claude, Cursor, ChatGPT, Gemini, Windsurf, and 9+ more via the MCP protocol. Captured in one session, retrieved in the next — no re-explaining.
Unified System Architecture
Combine Plan Forge with OpenBrain and OpenClaw to build a closed-loop development system — where AI agents plan, build, remember, and communicate across every surface you use.
✅ Plan Forge works fully standalone — these are optional power-ups, not requirements.
The Blueprint
What to build, how to build it, and when to stop. Guardrails, pipeline, and execution contracts.
The Memory
Why we decided, what we learned, what failed. Persistent semantic memory across every session and every tool.
The Nervous System
Always-on AI gateway across 20+ channels. Start a build from your phone at 3am, get a Slack notification when the review passes.
Plan Forge ships with OpenBrain integration hooks across 106+ files — ready to connect the moment you deploy OpenBrain.
Read the Unified System Architecture →Results
Presets
9 pre-configured guardrail packs (8 app + 1 IaC) for the most common enterprise stacks. One setup command installs the right instruction files, agents, skills, and templates.
ASP.NET Core, Blazor, Entity Framework, xUnit. 22 instruction files.
.\setup.ps1 -Preset dotnet
React, Node.js, Express, Vitest, pnpm. Includes frontend instructions.
.\setup.ps1 -Preset typescript
FastAPI, Django, pytest, SQLAlchemy. 22 instruction files.
.\setup.ps1 -Preset python
Spring Boot, Gradle / Maven, JUnit 5. 22 instruction files.
.\setup.ps1 -Preset java
Chi, Gin, standard library, Go test. 22 instruction files.
.\setup.ps1 -Preset go
SwiftUI, iOS / macOS, Vapor. 16 instruction files.
.\setup.ps1 -Preset swift
Axum, Tokio, CLI tools, cargo test. 16 instruction files.
.\setup.ps1 -Preset rust
Laravel, Symfony, Slim, PHPUnit. 16 instruction files.
.\setup.ps1 -Preset php
Bicep, Terraform, PowerShell, azd. Full CAF + WAF + Landing Zone guardrails.
.\setup.ps1 -Preset azure-iac
9 presets (8 app + 1 IaC). All presets also install 8 cross-stack agents: API contracts, accessibility, multi-tenancy, CI/CD, observability, dependency, compliance, and error handling.
Quick Start
One setup script bootstraps your entire guardrails stack — instruction files, agents, skills, hooks, and Copilot config.
Open Copilot Chat (Agent Mode), Claude Code, or Cursor in your project — paste this prompt. The AI reads the setup guide, detects your stack, installs everything, customizes the files, and validates. Zero manual steps.
Clone https://github.com/srnichols/plan-forge into a temporary directory. Read its AGENT-SETUP.md file completely and follow the instructions exactly:
1. Scan THIS project's root directory and auto-detect the tech stack from marker files (*.csproj = dotnet, go.mod = go, package.json + tsconfig.json = typescript, pom.xml = java, pyproject.toml = python, *.bicep = azure-iac). If multiple stacks exist, combine them.
2. Detect which AI tool is running this prompt and set the -Agent flag:
- GitHub Copilot → -Agent copilot (default, can omit)
- Claude Code → -Agent claude
- Cursor → -Agent cursor
- Codex CLI → -Agent codex
- Not sure → -Agent all (installs all agent formats)
3. Run the Plan Forge setup script non-interactively:
.\setup.ps1 -Preset <detected> -Agent <detected-agent> -ProjectPath "." -ProjectName "<this folder name>" -Force
4. After setup completes, customize the generated files:
- Edit .github/copilot-instructions.md with this project's actual name, tech stack, build/test/lint commands, and architecture
- If CLAUDE.md was generated, verify it looks correct
- Edit docs/plans/DEPLOYMENT-ROADMAP.md with a first phase placeholder
5. Run .\pforge.ps1 smith to inspect the forge and confirm all checks pass.
6. If pforge-mcp/server.mjs was installed, run: cd pforge-mcp && npm install (activates 69 forge MCP tools).
7. If specs/ or memory/constitution.md exist (Spec Kit project), note that Step 0 will auto-detect and offer to import them.
8. Call forge_capabilities to verify all tools are available and discover workflows, config options, and OpenBrain memory integration.
9. Show me a summary of what was installed and any issues found.Works with GitHub Copilot (Agent Mode), Claude Code, Cursor, or any AI tool with terminal access.
# Click "Use this Template" on GitHub, or clone directly:
git clone https://github.com/srnichols/plan-forge.git my-project-plans
cd my-project-plans# Interactive wizard picks your stack (setup.sh for macOS/Linux):
.\setup.ps1
# Or specify directly (PowerShell / Bash):
.\setup.ps1 -Preset dotnet # .NET / C#
.\setup.ps1 -Preset typescript # TypeScript / React
.\setup.ps1 -Preset python # Python / FastAPI
.\setup.ps1 -Preset java # Java / Spring Boot
.\setup.ps1 -Preset go # Go / Chi / Gin
.\setup.ps1 -Preset swift # Swift / SwiftUI
.\setup.ps1 -Preset rust # Rust / Axum
.\setup.ps1 -Preset php # PHP / Laravel
.\setup.ps1 -Preset azure-iac # Azure Bicep / Terraform / azd
# Add support for other AI agents (optional):
.\setup.ps1 -Preset dotnet -Agent claude # + Claude Code
.\setup.ps1 -Preset dotnet -Agent all # + Claude + Cursor + Codex + Gemini + Windsurf + GenericInstalls instruction files, agents, skills, lifecycle hooks, and copilot-instructions.md into your project. Add -Agent to generate native files for Claude, Cursor, Codex, Gemini, Windsurf, or Generic.
VS Code + Copilot: Agent Mode → select Specifier from the agent picker. Claude Code: invoke /planforge-step0-specify-feature. Cursor: run the planforge.step0-specify-feature command. Type one sentence — the pipeline runs from there.
I want to add user authentication with JWT tokens and
role-based access control to the admin panel.
Using Claude, Cursor, or Codex? The -Agent flag generated native skills and commands — invoke them directly in your tool. Or use the copy-paste prompts from the runbook in any AI tool.
Who it's for
Different roles, same framework. Click your path.
Give your AI this single prompt. It reads AGENT-SETUP.md, auto-detects the tech stack, runs the setup script non-interactively, and customizes the generated files. No manual steps.
Read the file AGENT-SETUP.md in the plan-forge repo root.
Follow the instructions exactly:
1. Scan this project and detect the tech stack
2. Detect which AI agent you are (Copilot/Claude/Cursor/Codex) for the -Agent flag
3. Run setup.ps1 (or setup.sh) non-interactively with the correct -Preset and -Agent flags plus -Force
4. Customize copilot-instructions.md with this project's actual details
5. Run pforge smith to validate the setup
6. If pforge-mcp/server.mjs exists, run: cd pforge-mcp && npm install (activates MCP tools)
7. Call forge_capabilities to verify all tools are available
8. Note any Spec Kit artifacts found (specs/, memory/constitution.md)
Repo: https://github.com/srnichols/plan-forge
Target project: (current directory)*.csproj → dotnet · go.mod → go · pom.xml → java · tsconfig.json → typescript · pyproject.toml → python · *.bicep → azure-iac
Read the README — specifically What Is This? (Plain English) — to understand the 4-layer system.
Clone the template and run .\setup.ps1 — the interactive wizard asks your stack and bootstraps everything.
Follow docs/QUICKSTART-WALKTHROUGH.md — a step-by-step walkthrough of your first feature build.
Run .\setup.ps1 -Preset <your-stack> — installs instruction files, agents, and skills directly into your project's .github/ folder.
Read CUSTOMIZATION.md to fill in your project profile, generate domain-specific guardrails, and set up the project principles workshop.
Read docs/COPILOT-VSCODE-GUIDE.md — how Agent Mode works, how instruction files auto-load, managing context budget, and memory bridging.
Open Copilot Chat → Agent Mode → pick Specifier → describe your first feature. The pipeline runs from there.
Run .\setup.ps1 -Preset <your-stack> or ./setup.sh --preset <your-stack>. Works on Windows (PowerShell), macOS, and Linux.
Read docs/CLI-GUIDE.md — how to run the pipeline from the terminal using pforge.ps1 / pforge.sh helper scripts.
Copy prompts from the runbook into any terminal-based AI agent (Claude Code, Copilot CLI, Aider, etc.). Same pipeline, no IDE required.
Run setup with your primary stack. For microservices with infra: .\setup.ps1 -Preset dotnet,azure-iac installs both app guardrails and IaC guardrails in one pass.
Run the Project Profile workshop (/project-profile) — generates coverage targets, latency SLAs, and compliance requirements from a short interview, stored per-repo.
Run the Project Principles workshop — captures non-negotiables, forbidden patterns, and architectural commitments that every AI session loads automatically.
Add an org-rules.instructions.md with your internal standards (naming conventions, approved libraries, compliance gates). It auto-loads on every session.
Compatibility
Advanced integration with VS Code + GitHub Copilot. First-class support for Claude Code, Cursor, and Codex CLI. Copy-paste prompts work with any AI tool.
| Feature | 🐙 Copilot | 🤖 Claude | ⚡ Cursor | 📟 Codex | Others |
|---|---|---|---|---|---|
| Project context | ✅ | ✅ | ✅ | ✅ | 📋 |
| 16 guardrail instruction files | ✅ auto-load | ✅ embedded | ✅ embedded | — | 📋 |
| Pipeline prompts (8) | ✅ | ✅ | ✅ | ✅ | 📋 |
| Scaffolding prompts (70+) | ✅ | ✅ | ✅ | ✅ | 📋 |
| Reviewer agents (66) | ✅ picker | ✅ skills | ✅ cmds | ✅ skills | 📋 |
| MCP tools (18 forge operations) | ✅ native | ✅ native | ✅ native | — | — |
| Skills (3 multi-step workflows) | ✅ slash cmd | ✅ MCP | ✅ MCP | — | 📋 |
| Lifecycle hooks (5 types) | ✅ native | ⚡ guided | ⚡ guided | — | — |
| Live dashboard (25 tabs) | ✅ MCP | ✅ MCP | ✅ MCP | — | — |
| Autonomous plan execution | ✅ MCP | ✅ MCP | ✅ MCP | — | — |
| Cost tracking & telemetry | ✅ MCP | ✅ MCP | ✅ MCP | — | — |
| Quorum mode (multi-model consensus) | ✅ MCP | ✅ MCP | ✅ MCP | — | — |
| Extension ecosystem (3 packages) | ✅ MCP | ✅ MCP | ✅ MCP | — | — |
| Presets (10 — 8 stacks + IaC + shared) | ✅ | ✅ | ✅ | ✅ | 📋 |
| File-type awareness | ✅ native | ✅ guided | ✅ guided | — | — |
| Post-edit scanning | ✅ hook | ✅ MCP | ✅ MCP | — | — |
| Scope drift detection | ✅ hook + MCP | ✅ MCP | ✅ MCP | — | — |
| Forbidden path blocking | ✅ enforced | ⚡ advisory | ⚡ advisory | — | — |
| Pipeline handoff buttons | ✅ click | ⚡ guided | ⚡ guided | — | — |
✅ = native/MCP tool · ⚡ = instruction-guided · 📋 = copy-paste prompts · MCP = with pforge-mcp/server.mjs running · — = not supported
Plan Forge is free, open source, and ready to use in minutes. Your AI assistant is about to get a lot more disciplined.
MIT Licensed · GitHub Template · No vendor lock-in · Works with any AI tool
Dogfooding
Every feature in this repo — the MCP server, the dashboard, the orchestrator, the quorum system — was developed using the same hardened plan pipeline that ships to users. If the pipeline can build itself without drift, it can build your project too.
The dashboard screenshots in our docs were captured by a Playwright script — itself built slice-by-slice using Plan Forge.
From the Forge
Lessons, patterns, and A/B test results from building with AI coding agents.
Why AI agents break what they build — and the methodology that fixes it.
LessonsHard-won lessons from building 18 guardrail files and 19 reviewer agents.
Multi-AgentSame guardrails for Copilot, Claude, Cursor, Gemini, Windsurf, Codex, and any AI tool.