Frequently Asked Questions

Plan Forge is a specification-driven framework that converts rough feature ideas into hardened execution contracts for AI coding agents. It adds guardrails, validation gates, and independent review to prevent the scope creep, skipped tests, and architecture drift that plague unstructured AI-assisted development. It's a GitHub template — clone it, run the setup wizard, and you're ready.

Those tools are great at generating code. Plan Forge makes them great at generating the right code. Without guardrails, agents silently expand scope, pick their own architecture, skip validation, and forget context across sessions. Plan Forge adds a 7-step pipeline, auto-loading instruction files (security, testing, architecture, etc.), and independent review — so the agent works within your standards, not its own improvisation.

Yes. MIT licensed — free for personal, commercial, and enterprise use. No sign-ups, no telemetry, no vendor lock-in. It's a GitHub template that installs files into your project's .github/ directory.

The pipeline works in three ways: Pipeline Agents (optimized for VS Code + Copilot), Prompt Templates (VS Code Copilot Chat), and Copy-Paste Prompts (works in any AI tool — Claude, Cursor, ChatGPT, Gemini, Windsurf, terminal agents).

First-class agent support: Setup generates rich native files for Claude Code, Cursor, and Codex CLI. This includes all 16 guardrail files embedded in the context file, all prompts and scaffolding recipes as native skills/commands, all 19 reviewer agents as invocable skills, and smart instructions that emulate Copilot's auto-loading and post-edit scanning. Use -Agent claude,cursor during setup.

Copilot files are always installed. Additional agents layer on top — use one, some, or all.

Yes. The setup wizard detects existing files and merges rather than overwrites. It only adds missing guardrail files — your project-specific content is preserved. AGENT-SETUP.md has full brownfield instructions.

Six presets out of the box: .NET/C#, TypeScript/React, Python/FastAPI, Java/Spring Boot, Go, and Azure IaC (Bicep/Terraform). There's also a custom preset for any other stack. Multi-preset combinations are supported — e.g., -Preset dotnet,azure-iac for an app with infrastructure code.

No. All 18+ guardrail files ship pre-written with best practices and auto-load based on the file type being edited — no action needed. To customize, run the Project Profile workshop (a one-time interview that generates project-specific guardrails) or edit any instruction file directly.

Set chat.useCustomizationsInParentRepositories in VS Code settings so child workspaces inherit parent guardrails. Run multi-preset setup with different stacks for different directories (e.g., -Preset typescript,azure-iac -ProjectPath ./packages/api).

A blacksmith inspects the forge, checks the tools, and makes sure everything is ready before the work begins. pforge smith does the same for your project — it diagnoses five areas in seconds:

• Environment — git, VS Code CLI, PowerShell/bash, GitHub CLI
• VS Code Config — agent mode, parent repo customizations, prompt file discovery
• Setup Health — .forge.json, file counts per preset, copilot-instructions.md
• Version Currency — is your Plan Forge install up to date?
• Common Problems — duplicate files, orphaned agents, missing applyTo, unresolved placeholders

Every issue includes a FIX: suggestion with the exact command or setting to resolve it. Run it after setup, after updates, or whenever something feels off.

The executor shouldn't self-audit — that's like grading your own exam. Session isolation forces fresh context so the reviewer catches drift and bugs the builder is blind to. Each session loads the same guardrails but brings independent judgment.

No. The pipeline has complexity routing — Step 0 classifies work as Micro, Small, Medium, or Large. Quick bug fixes can skip hardening. Small features get a lightweight plan. Only medium and large features run the full pipeline. You stay in control.

There's a structured Plan Amendment Protocol. You can modify the scope contract through a defined process — not by silently drifting. Changes are documented and the remaining slices are re-evaluated against the updated contract.

The agent must fix the failure before proceeding. Build and test gates are hard gates — not suggestions. There's also a rollback protocol for reverting a failed slice cleanly, and stop conditions that immediately halt execution for critical issues.

No. Plan Forge works fully without OpenBrain. Memory integration is an optional extension (plan-forge-memory) — 106 files have OpenBrain hooks, but they're all gated behind "if configured." You get the full pipeline, all guardrails, and all agents without it. OpenBrain just makes the experience compound over time.

Self-hosted with Ollama: $0/month. Local embeddings, local LLM, local PostgreSQL. Cloud option (Azure OpenAI): ~$15/month. OpenBrain is MIT-licensed and fully self-hosted.

Yes. Create extensions with your organization's standards — code as versioned packages with extension.json manifests. Distribute via GitHub repos, git submodules, or ZIP files. Teams install with pforge ext install. Add an org-rules.instructions.md for company-wide naming conventions, approved libraries, and compliance gates.

Yes. Run pforge ext search to browse the community catalog, pforge ext info <name> for details, and pforge ext add <name> to download and install in one step. The catalog uses a Spec Kit-compatible format — extensions marked speckit_compatible work in both tools.

Yes. The setup wizard generates .vscode/mcp.json (and .claude/mcp.json for Claude), which exposes 8 forge tools as native MCP functions: forge_smith, forge_validate, forge_sweep, forge_status, forge_diff, forge_ext_search, forge_ext_info, and forge_new_phase. Your AI agent can call these directly — no terminal commands needed. The MCP server is composable with OpenBrain for persistent memory.

The compliance-reviewer agent audits for GDPR, CCPA, SOC2, and PII handling. The Project Profile workshop captures your specific compliance requirements. The security guardrails auto-load when editing auth, API, or data access code. For regulated industries, the extension ecosystem lets you package domain-specific compliance guardrails (e.g., HIPAA, PCI-DSS).

Add the Plan Forge Validate GitHub Action to your workflow:

- uses: srnichols/plan-forge-validate@v1
  with:
    sweep: true              # Run TODO/FIXME sweep
    fail-on-warnings: false  # Warnings don't block merge

It checks six areas: setup health, file counts per preset, unresolved placeholders, orphaned agents, plan artifacts (scope contracts + slices), and a completeness sweep. Every failure shows exactly what's wrong.

The action has zero dependencies beyond bash and git, runs in ~5 seconds, and outputs passed, failed, warnings, and result for use in downstream steps.

Run pforge analyze <plan-file>. It scores your implementation against the plan across 4 dimensions: requirement traceability, scope compliance, test coverage, and validation gates. Returns a consistency score out of 100. Also available as the forge_analyze MCP tool and via analyze: true in the GitHub Action.

Both are open-source, MIT-licensed frameworks for disciplined AI-assisted development — and both are excellent. They solve different parts of the problem:

Spec Kit (by GitHub) focuses on Spec-Driven Development — turning ideas into executable specifications via slash commands (/speckit.specify, /speckit.plan, /speckit.implement). It has a massive community (85K+ stars, 144 contributors), supports 25+ AI agents natively, and offers a rich extension and preset ecosystem with 40+ community extensions. It shines at defining what to build and generating implementation from specs.

Plan Forge focuses on hardened execution — locking specs into scope contracts the AI cannot deviate from, enforcing standards with 16–17 auto-loading guardrail files per stack, providing 18 specialized reviewer agents (security, architecture, performance, compliance, etc.), and validating at every slice boundary. It shines at ensuring the AI builds exactly what was specified with enterprise-grade quality.

They're genuinely complementary: use Spec Kit to write the spec, Plan Forge to enforce it. Or pick the one that matches your team's priorities (see the next question).

Pick Spec Kit if your team uses multiple AI tools (not just VS Code), you want the largest community and extension ecosystem, and you prefer a lightweight spec-first methodology you can adopt incrementally. GitHub's backing means strong long-term viability and rapid iteration.

Pick Plan Forge if you want deep guardrails that auto-enforce during coding, you need specialized reviewer agents, and you care about enterprise patterns like deployment templates, lifecycle hooks, and scope-contract enforcement. First-class support for VS Code + Copilot, Claude Code, and Cursor — with MCP tools for native integration.

Honest take: Spec Kit has the bigger ecosystem and broader agent support today. Plan Forge goes deeper on runtime enforcement and enterprise quality gates. Both are free. You really can't go wrong.

Yes — Plan Forge auto-detects Spec Kit artifacts. When you start Step 0 (Specifier), it scans for specs/*/spec.md, plan.md, and memory/constitution.md. If found, it offers to import them directly — no re-specifying needed.

The extension catalogs also use the same format, so Spec Kit-compatible extensions work in both tools. See the full integration guide for the combined workflow.

No. Plan Forge operates at the development layer, before code reaches your CI/CD pipeline. Its validation gates (build/test) run locally during slice execution. Your existing CI/CD pipeline handles deployment, environments, and production gates. Plan Forge catches problems before they reach your pipeline.