Open Source · MIT License · GitHub Template · v1.2.2
Plan Forge

Forge the Plan.
Harden the Scope.
Ship with Confidence.

AI coding guardrails that convert rough ideas into hardened execution contracts (locked-down plans the AI can't deviate from) — so your AI agent builds exactly what you asked for, without drift, scope creep, or skipped tests.

Spending thousands on AI tokens and hitting the 80% wall? Read why — and how to fix it →

🎬

See Plan Forge in action — from feature idea to shipped code in under 5 minutes.

(Video walkthrough coming soon — read the written walkthrough in the meantime)

Start Building Right View on GitHub
7
Pipeline Steps
6+
Tech Stacks
18+
Guardrail Files
MIT
Open Source

The Problem

AI Agents Drift Without Guardrails

Fast isn't the same as good. Without structure, AI-generated code tends to be untestable, insecure, and impossible to maintain at scale.

🔀

Silent Scope Creep

"I'll also add..." — features you never asked for, silently introduced. You find out at code review.

🎲

Undiscussed Decisions

Database pattern, framework choice, architecture — picked without asking. You discover the consequences too late.

🚫

Skipped Validation

Ships code that doesn't build or breaks tests. "It should work" is not a quality gate for production.

🧠

No Memory

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.

The Solution

The 7-Step Hardening Pipeline

A structured pipeline across 4 focused sessions that converts rough feature ideas into shipped, reviewed, production-grade code.

0

Specify

What & why

Session 1
1

Pre-flight

Verify setup

Session 1
2

Harden

Scope contract

Session 1
3

Execute

Slice by slice

Session 2
4

Sweep

No TODOs left

Session 2
5

Review

Drift detection

Session 3
6

Ship

Commit & close

Session 4

💡 Why 4 Separate Sessions Instead of One Long Chat?

Most people use AI as a single long conversation. Plan Forge breaks that pattern on purpose — because the builder shouldn't grade its own exam.

Single Session (chatbot way)

  • • Context exhausts halfway through
  • • Same AI reviews its own work
  • • Scope creep goes unnoticed
  • • Failure = restart the whole conversation

Plan Forge (4 sessions)

  • • Fresh context for each role
  • • Independent reviewer catches blind spots
  • • Scope drift detected immediately
  • • Failure = re-run only the failed session
🔒

Scope Locked in Session 1

The execution contract is created and locked. Nothing can be added mid-build without restarting the contract. Drift becomes structurally impossible.

🔍

Independent Audit Session

The reviewer runs in a completely separate session with fresh context. The executor can't self-audit — that's like grading your own exam.

✅

Validated at Every Slice

Build and test must pass at every slice boundary before moving to the next. No shipping code that doesn't compile or that breaks existing tests.

Three Ways to Run the Same Pipeline

🖱️

Pipeline Agents

Click-through flow with handoff buttons. Smoothest experience. Context carries automatically.

VS Code + GitHub Copilot

📎

Prompt Templates

Attach step files in Copilot Chat. See exactly what each step does. Best for learning the pipeline.

VS Code + GitHub Copilot

📋

Copy-Paste Prompts

Copy prompts from the runbook. Works in any AI tool — Claude, Cursor, ChatGPT, terminal agents.

Any AI Tool

Features

Enterprise-Grade by Default

Every project gets a full suite of guardrails, specialized reviewers, and automated validation — whether you ask for them or not.

🛡️

Two-Layer Guardrails

Automatic protection at two levels. The baseline ships with every preset. The project profile is generated per-project via an interview prompt.

Layer 1 — Universal Baseline

Architecture principles, OWASP security, TDD, error handling, type safety, async patterns. Ships automatically. No configuration needed.

Layer 2 — Project Profile

Coverage targets, latency SLAs, compliance requirements, domain-specific rules — generated from a one-time interview and stored in the repo.

🤖

Specialized Reviewer Agents

Dedicated AI reviewer personas — each focused on one concern, checking it deeply.

  • Security Reviewer — OWASP Top 10
  • Architecture Reviewer — layer separation
  • Performance Analyzer — hot paths, allocations
  • Database Reviewer — N+1, safe queries
  • Test Runner + Deploy Helper
  • + 8 cross-stack agents (API, accessibility, CI/CD, compliance, error handling...)
  • + 5 pipeline agents (Specifier → Shipper)
⚡

Auto-Loading Instructions

Instruction files load automatically based on the file being edited. Editing SQL? Database guardrails load. Editing auth? Security guardrails load. No action needed.

⚙️

Slash Command Skills

Multi-step executable procedures with validation gates between steps.

/database-migration /staging-deploy /test-sweep /code-review
📐

Scaffolding Prompts

15 prompt templates for generating consistent code patterns — entities, services, controllers, tests, DTOs, workers, and more — all following your project's architecture.

🔗

Lifecycle Hooks

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.

🔨

The Smith

Run 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.

✅ git 2.44.0
✅ 16 instruction files (expected: ≥14)
❌ chat.promptFiles not set
FIX: Add to .vscode/settings.json
🔄

CI Validation Action

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@v1
🌱

Spec Kit Compatible

Auto-imports Spec Kit specs, plans, and constitutions. Shared extension catalog. Write specs with Spec Kit, enforce them with Plan Forge.

See the combined workflow →
🔌

MCP Server

Expose forge commands as native MCP tools — any agent with MCP support can invoke forge_smith, forge_sweep, forge_diff, forge_analyze as function calls. Auto-configured during setup. Composable with OpenBrain.

8 tools · Node.js · stdio transport · zero config

Wait — What's the Difference Between All These File Types?

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).

Persistent Memory

Your AI Gets Smarter Over Time

Every decision you make, every pattern you establish, every lesson learned — captured once and searchable forever. Across sessions, across AI tools, across projects.

1

Capture During Execution

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.

2

Search by Meaning, Not Keywords

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.

3

Any Tool, Any Session, Any Project

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.

pgvector semantic search MCP protocol Self-hosted & private 9 AI clients Project-scoped Docker / Azure / K8s
memory — persistent across sessions
# Plan Forge Shipper auto-captures after Phase 2:
💾 captured: "Decision: Using PostgreSQL
  row-level security over app-level tenant
  filtering. RLS scales better at query time.
  project: saas-platform · phase-2-slice-4"
# 4 months later, starting a new project:
You: "How did we handle multi-tenancy last time?"
✅ Found (94% match):
"Decision: PostgreSQL row-level security
over app-level filtering. RLS scales better."
Source: plan-forge-phase-2-slice-4 · 4 months ago
# The AI already knows your standards.
Agent: "Applying RLS pattern from saas-platform
  decision — consistent with your architecture."

Unified System Architecture

Plan Forge Is One Piece of a Bigger Picture

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.

🔨

Plan Forge

The Blueprint

What to build, how to build it, and when to stop. Guardrails, pipeline, and execution contracts.

+ Great guardrails & methodology
+ 4-session isolation model
+ Works in VS Code and any AI tool
🧠

OpenBrain

The Memory

Why we decided, what we learned, what failed. Persistent semantic memory across every session and every tool.

+ Decisions survive across sessions
+ pgvector semantic search
+ 9 AI clients via MCP protocol
🦅

OpenClaw

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.

+ WhatsApp, Telegram, Slack, Discord
+ Voice wake + talk mode
+ Launches Copilot CLI for execution

What the unified system looks like end-to-end

  1. 1
    Describe a feature from any device — WhatsApp message, Slack DM, phone, terminal, or voice. OpenClaw routes the request.
  2. 2
    OpenBrain loads prior context — architecture decisions, postmortems, known patterns — before your agent writes a single line.
  3. 3
    Plan Forge hardens the plan — scope locked, slices defined, guardrails loaded. Then Copilot CLI builds it slice by slice with validation gates.
  4. 4
    You get notified on your phone — "Slice 3 of 5 complete. Build passed. Ready to proceed?" Approve from your couch.
  5. 5
    OpenBrain captures every lesson — The Shipper batch-captures postmortems, decisions, and patterns. Next feature, the AI already knows your standards.

Plan Forge ships with OpenBrain integration hooks across 106+ files — ready to connect the moment you deploy OpenBrain.

Read the Unified System Architecture →

Results

The Difference Is Measurable

Scenario
❌ Without Guardrails
✅ With Plan Forge
Code quality
Passes once, breaks in production
Follows your architecture from line 1
Rework rate
30–50% needs rework after review
Independent review catches drift before merge
Session context
Re-explain decisions in every session
Memory loads prior decisions in seconds
Token efficiency
Context window wasted on exploration
Hardened plan = fewer tokens, faster results
Deployment
"Works on my machine"
Validation gates must pass at every slice
Postmortems
Written once, never read again
Searched automatically at next phase start

Presets

Your Stack. Your Rules.

Pre-configured guardrail packs for the most common enterprise stacks. One setup command installs the right instruction files, agents, skills, and templates.

🔷

.NET / C#

ASP.NET Core, Blazor, Entity Framework, xUnit. 16 instruction files.

.\setup.ps1 -Preset dotnet
🟨

TypeScript

React, Node.js, Express, Vitest, pnpm. Includes frontend instructions.

.\setup.ps1 -Preset typescript
🐍

Python

FastAPI, Django, pytest, SQLAlchemy. 16 instruction files.

.\setup.ps1 -Preset python
☕

Java

Spring Boot, Gradle / Maven, JUnit 5. 16 instruction files.

.\setup.ps1 -Preset java
🐹

Go

Chi, Gin, standard library, Go test. 16 instruction files.

.\setup.ps1 -Preset go
☁️

Azure IaC

Bicep, Terraform, PowerShell, azd. Full CAF + WAF + Landing Zone guardrails.

.\setup.ps1 -Preset azure-iac

All presets also install 8 cross-stack agents: API contracts, accessibility, multi-tenancy, CI/CD, observability, dependency, compliance, and error handling.

Quick Start

Up and Running in Minutes

One setup script bootstraps your entire guardrails stack — instruction files, agents, skills, hooks, and Copilot config.

✅ VS Code ✅ GitHub Copilot ✅ Git That's it — no other dependencies
⚡ EASY BUTTON

Paste one prompt — your AI installs everything automatically

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.

Paste into any AI chat — Copilot, Claude, Cursor 
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 mcp/server.mjs was installed, run: cd mcp && npm install (activates 8 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. 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.

or do it manually
1

Use as a GitHub Template

Terminal 
# 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
2

Run the Setup Wizard

PowerShell / Bash 
# 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 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

Installs instruction files, agents, skills, lifecycle hooks, and copilot-instructions.md into your project. Add -Agent to generate native files for Claude, Cursor, or Codex.

3

Describe Your Feature — Your AI Does the Rest

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.

Copilot Chat → Agent Mode → Specifier
That's literally it. 
I want to add user authentication with JWT tokens and
role-based access control to the admin panel.
What happens next — automatically, via handoff buttons:
S
Specifier — interviews you, surfaces ambiguities, produces the feature spec
H
Plan Hardener — converts the spec into a locked execution contract, runs pre-flight checks
E
Executor — builds slice by slice, runs build + tests at every boundary, no TODOs left behind
R
Reviewer Gate — independent fresh session audits for drift, security gaps, and missed requirements
✓
Shipper — commits, updates the roadmap, captures lessons to memory for next time

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.

Use This Template on GitHub → Full Walkthrough Guide

Who it's for

Your Entry Point

Different roles, same framework. Click your path.

⚡ MAGIC MODE

You're an AI agent setting up a project

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.

Paste this into any AI chat (Copilot, Claude, Cursor, etc.) 
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 mcp/server.mjs exists, run: cd mcp && npm install (activates MCP tools)
7. Note any Spec Kit artifacts found (specs/, memory/constitution.md)

Repo: https://github.com/srnichols/plan-forge
Target project: (current directory)
What it detects *.csproj → dotnet  ·  go.mod → go  ·  pom.xml → java  ·  tsconfig.json → typescript  ·  pyproject.toml → python  ·  *.bicep → azure-iac
What it installs 16–17 instruction files, 19 agents, 8 skills, lifecycle hooks, pipeline prompts, copilot-instructions.md
What it customizes Fills in your project name, tech stack, build commands, and architecture details automatically
🆕

Brand new to AI guardrails
1

Read the README — specifically What Is This? (Plain English) — to understand the 4-layer system.

2

Clone the template and run .\setup.ps1 — the interactive wizard asks your stack and bootstraps everything.

3

Follow docs/QUICKSTART-WALKTHROUGH.md — a step-by-step walkthrough of your first feature build.

🧑‍💻

A developer using VS Code + Copilot
1

Run .\setup.ps1 -Preset <your-stack> — installs instruction files, agents, and skills directly into your project's .github/ folder.

2

Read CUSTOMIZATION.md to fill in your project profile, generate domain-specific guardrails, and set up the project principles workshop.

3

Read docs/COPILOT-VSCODE-GUIDE.md — how Agent Mode works, how instruction files auto-load, managing context budget, and memory bridging.

4

Open Copilot Chat → Agent Mode → pick Specifier → describe your first feature. The pipeline runs from there.

📟

A CLI-first developer
1

Run .\setup.ps1 -Preset <your-stack> or ./setup.sh --preset <your-stack>. Works on Windows (PowerShell), macOS, and Linux.

2

Read docs/CLI-GUIDE.md — how to run the pipeline from the terminal using pforge.ps1 / pforge.sh helper scripts.

3

Copy prompts from the runbook into any terminal-based AI agent (Claude Code, Copilot CLI, Aider, etc.). Same pipeline, no IDE required.

🏢

An enterprise or SaaS team
1

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.

2

Run the Project Profile workshop (/project-profile) — generates coverage targets, latency SLAs, and compliance requirements from a short interview, stored per-repo.

3

Run the Project Principles workshop — captures non-negotiables, forbidden patterns, and architectural commitments that every AI session loads automatically.

4

Add an org-rules.instructions.md with your internal standards (naming conventions, approved libraries, compliance gates). It auto-loads on every session.

Compatibility

Works With Your AI Tools

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.

🐙 GitHub Copilot 🤖 Claude Code ⚡ Cursor 📟 Codex CLI 💎 Gemini 🌊 Windsurf 💬 ChatGPT 🔧 Any AI tool

Feature Parity by Agent

Feature 🐙 Copilot 🤖 Claude ⚡ Cursor 📟 Codex Others
Project context ✅ ✅ ✅ ✅ 📋
16 guardrail files ✅ auto ✅ embedded ✅ embedded — 📋
Pipeline prompts (7) ✅ ✅ ✅ ✅ 📋
Scaffolding prompts (15+) ✅ ✅ ✅ ✅ 📋
Reviewer agents (18) ✅ picker ✅ skills ✅ cmds ✅ skills 📋
MCP tools (9 forge operations) ✅ native ✅ native ✅ native — —
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 mcp/server.mjs running

Stop Vibe Coding.
Start Forging.

Plan Forge is free, open source, and ready to use in minutes. Your AI assistant is about to get a lot more disciplined.

Use This Template ⭐ Star on GitHub

MIT Licensed · GitHub Template · No vendor lock-in · Works with any AI tool