Chapter 3

Installation

Zero to pforge smith green in 10 minutes.

Prerequisites

RequirementMinimum VersionCheck Command
VS Code (or Insiders)1.99+code --version
GitHub Copilot extensionCopilot subscription activeCopilot icon visible in status bar
Git2.30+git --version
Node.js (for MCP server)18+node --version
Node.js is optional unless you want the MCP server (dashboard, 19 tools, REST API). The core pipeline (prompts, instructions, agents) works without it.

Option A: Clone & Setup

The fastest path — clone the repo and run the setup wizard:

Terminal
git clone https://github.com/srnichols/plan-forge.git my-project-plans
cd my-project-plans
.\setup.ps1 -Preset <your-stack>

This installs all guardrails, agents, prompts, skills, and MCP tools into your project. See the preset list below.

Option B: Setup Wizard

Clone the template and run the setup wizard:

Step 1 — Clone
git clone https://github.com/srnichols/plan-forge.git my-project-plans
cd my-project-plans
Step 2 — Run setup (PowerShell)
# Interactive — the wizard asks which preset
.\setup.ps1

# Or specify directly
.\setup.ps1 -Preset dotnet
Step 2 — Run setup (Bash)
chmod +x setup.sh
./setup.sh --preset typescript

The wizard detects your tech stack (or uses the preset you specify), creates .github/ with instruction files, agents, prompts, skills, and hooks, generates .forge.json, and sets up .vscode/settings.json.

Adding to an Existing Project
Clone Plan Forge alongside your project, then point the setup wizard at your repo:
git clone https://github.com/srnichols/plan-forge.git ../plan-forge
cd ../plan-forge && ./setup.ps1 -ProjectPath ../my-existing-app -Preset typescript
This copies prompts, instructions, agents, and hooks into your existing repo without touching your source code.

Choosing Your Preset

Nine presets, each tailored to a tech stack. Each installs ~21 instruction files, 19 agents, 12 skills, and 7+ pipeline prompts.

🟣
dotnet
C# · ASP.NET · xUnit
🟡
typescript
Node.js · Express · Vitest
🐍
python
FastAPI · Pytest
☕
java
Spring Boot · Maven
🔵
go
Standard Library · Cobra
🍎
swift
SwiftUI · Vapor · XCTest
🦀
rust
Tokio · Axum · Cargo
🐘
php
Laravel · PHPUnit
☁️
azure-iac
Bicep · Terraform · azd
Polyglot projects? Use comma-separated presets: .\setup.ps1 -Preset dotnet,typescript

What Just Happened?

After setup completes, your project has:

Files created (dotnet preset example)
.github/
├── instructions/     21 files  (architecture, security, testing, database, ...)
├── agents/           19 files  (6 stack + 8 shared + 5 pipeline)
├── prompts/          12 files  (7 pipeline + 5 scaffolding)
├── skills/           12 dirs   (8 stack + 4 shared)
├── hooks/             4 files  (SessionStart, PreToolUse, PostToolUse, Stop)
└── copilot-instructions.md     (master config)

.forge.json                     (project configuration)
.vscode/settings.json           (Copilot settings)
docs/plans/
├── DEPLOYMENT-ROADMAP.md       (phase tracker)
└── AI-Plan-Hardening-Runbook.md (methodology reference)
pforge.ps1 / pforge.sh          (CLI scripts)

Verify with pforge smith

The Smith inspects your forge — environment, VS Code config, setup health, version currency. Run it to confirm everything is green:

PowerShell
.\pforge.ps1 smith
Expected output
╔══════════════════════════════════════════════════════════════╗
║       Plan Forge — The Smith                                 ║
╚══════════════════════════════════════════════════════════════╝

Environment:
  ✅ git 2.44.0
  ✅ code (VS Code CLI) 1.99.0
  ✅ PowerShell 7.5.0
  ✅ node 22.3.0

VS Code Configuration:
  ✅ chat.agent.enabled = true
  ✅ chat.promptFiles = true

Setup Health:
  ✅ .forge.json valid (preset: dotnet, v2.17.0)
  ✅ 21 instruction files (expected: ≥15 for dotnet)
  ✅ 19 agent definitions
  ✅ copilot-instructions.md exists

────────────────────────────────────────────────────
  Results:  10 passed  |  0 failed  |  0 warnings
Got failures? Each failed check includes a FIX: suggestion. Common fix: add "chat.agent.enabled": true to .vscode/settings.json. See Chapter 14: Troubleshooting for more.

Multi-Agent Setup

Plan Forge works primarily with VS Code + GitHub Copilot. But if you also use Claude Code, Cursor, Codex, Gemini, or Windsurf, add their adapters during setup:

PowerShell
# Add Claude Code support
.\setup.ps1 -Preset dotnet -Agent claude

# Add all agent adapters at once
.\setup.ps1 -Preset dotnet -Agent all
Agent FlagToolFiles Created
copilot (default)GitHub Copilot.github/ instructions, agents, skills, prompts, hooks
claudeClaude CodeCLAUDE.md with embedded guardrails + slash commands
cursorCursor.cursorrules + .cursor/rules/*.mdc
codexCodex CLIAGENTS.md + skill scripts
geminiGemini CLIGEMINI.md + .gemini/commands/*.toml
windsurfWindsurf.windsurfrules + .windsurf/rules/*.md
genericAny AI toolAI-ASSISTANT.md — copy-paste guardrails

See Chapter 12: Multi-Agent Setup for detailed configuration per agent, feature parity matrix, and quorum mode.

Updating

When a new Plan Forge version is available, pforge smith will tell you. Update without re-running the full setup:

PowerShell
# Preview what would change
.\pforge.ps1 update --dry-run

# Apply updates
.\pforge.ps1 update

Updates replace framework files (pipeline prompts, shared instructions, hooks) but never touch your customized files (copilot-instructions.md, project principles, plan files, .forge.json).

Next step: You're installed. Time to build something. Head to Chapter 4: Your First Plan.

📄 Full reference: AGENT-SETUP.md, README.md Quick Start