Chapter 3

Installation

Zero to pforge smith green in 10 minutes.

Prerequisites

Requirement	Minimum Version	Check Command	Required for
Git	2.30+	`git --version`	Everyone
VS Code (or Insiders)	1.99+	`code --version`	UI path
GitHub Copilot extension	Copilot subscription active	Copilot icon visible in status bar	UI path
Node.js	18+	`node --version`	CLI / server path

Node.js is optional. Required only for the dashboard, MCP server, pforge.ps1 / pforge.sh, and the 105 tools (REST API + WebSocket hub). Skip Node.js if you'll only use the core pipeline, prompts, instruction files, agents, and skills all live inside .github/ and run entirely inside Copilot Chat.

⚡ EASY BUTTON Skip the manual steps, paste one prompt and your AI installs everything

Open Copilot Chat (Agent Mode), Claude Code, or Cursor inside your project, paste this prompt. The AI reads AGENT-SETUP.md, detects your stack, runs setup, customizes the files, and validates. Zero manual steps.

Paste into any AI chat, Copilot, Claude, Cursor, Codex

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 the forge MCP tools).
   - As of v3.19.0, setup.ps1 / setup.sh also ship pforge-sdk/ (zero-dependency programmatic clients) and pforge-master/ (Forge-Master Studio reasoning loop) into the target repo.
   - Both directories are added to a managed block in .gitignore (Plan Forge marker, v3.15.1+) so they don't bloat the consumer's commits but remain available to pforge update.

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, Codex CLI, or any AI tool with terminal access. Prefer the manual steps? Continue with Option A or B below ↓

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 ~18 instruction files, 12 agents, 11 skills, and 8 pipeline prompts.

🟣

dotnet

C# · ASP.NET · xUnit

🟡

typescript

Node.js · Express · Vitest

🐍

python

FastAPI · Pytest

☕

java

Spring Boot · Maven

🔵

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/     ~26 files  (architecture, security, testing, database, ..., 18 preset + 8 shared)
├── agents/           19 files  (6 stack-specific + 7 cross-stack + 5 pipeline + 1 audit-classifier)
├── prompts/         ~23 files  (15 preset + 8 shared pipeline: project-profile + step0–step6)
├── skills/           11 dirs   (varies by preset: dotnet 11, typescript 10)
├── hooks/             5 items  (PreDeploy.md, PreCommit.mjs, PreAgentHandoff.md, PostSlice.md, plan-forge.json)
└── 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)

Note on hook names. Plan Forge ships lifecycle hooks named PreDeploy, PreCommit, PreAgentHandoff, and PostSlice (plus the plan-forge.json hook config). These are not the same as Claude Code's hook names (SessionStart, PreToolUse, etc.), if you're coming from Claude Code, the trigger semantics differ. See .github/hooks/plan-forge.json for the live configuration.

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: ≥17 for dotnet)
  ✓ 21 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 15: 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 Flag	Tool	Files Created
`copilot` (default)	GitHub Copilot	`.github/` instructions, agents, skills, prompts, hooks
`claude`	Claude Code	`CLAUDE.md` with embedded guardrails + slash commands
`cursor`	Cursor	`.cursorrules` + `.cursor/rules/*.mdc`
`codex`	Codex CLI	`AGENTS.md` + skill scripts
`gemini`	Gemini CLI	`GEMINI.md` + `.gemini/commands/*.toml`
`windsurf`	Windsurf	`.windsurfrules` + `.windsurf/rules/*.md`
`generic`	Any AI tool	`AI-ASSISTANT.md`, copy-paste guardrails

See Chapter 13: 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).

Where does pforge update pull from? By default (auto), it picks the newer of a local sibling clone at ../plan-forge and the latest GitHub tag, so a stale master checkout won't drag you onto unreleased -dev bytes. See Appendix G: Update Source Modes for the github-tags and local-sibling options and when to use them.

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

📄 Full reference: Multi-Agent Setup, Quick Start on GitHub

Installation

Prerequisites

Option A: Clone & Setup

Option B: Setup Wizard

Choosing Your Preset

What Just Happened?

Verify with pforge smith

Multi-Agent Setup

Updating

Verify with `pforge smith`