How It Works

The mental model. Understand the pipeline, sessions, and file structure without touching a terminal.

The 7-Step Pipeline

Every feature in Plan Forge flows through these steps:

You describe what you want (Step 0). The AI creates a spec. A pre-flight check verifies your setup (Step 1). The plan gets hardened into a binding scope contract with slices, gates, and forbidden actions (Step 2). The AI builds it slice by slice, validated at every boundary (Step 3). A completeness sweep eliminates stubs and TODOs (Step 4). A fresh session audits everything (Step 5). The shipper commits, updates the roadmap, and captures lessons (Step 6).

Sessions and Why They Matter

The executor shouldn't self-audit — that's like grading your own exam. Each session starts fresh, loads the same guardrails, but brings independent judgment. Session 3 (Review) has never seen the code being written — it reads the plan, reads the code, and checks for drift.

The File System

After setup, Plan Forge installs four types of files into your .github/ directory:

.github/
├── instructions/          ← Rules (auto-load by file type)
│   ├── architecture-principles.instructions.md
│   ├── security.instructions.md
│   ├── testing.instructions.md
│   ├── database.instructions.md
│   └── ... (14–18 files per preset)
├── agents/                ← Reviewer personas (read-only audit)
│   ├── architecture-reviewer.agent.md
│   ├── security-reviewer.agent.md
│   └── ... (19 agents)
├── prompts/               ← Pipeline templates (attach in chat)
│   ├── step0-specify-feature.prompt.md
│   ├── step2-harden-plan.prompt.md
│   └── ... (7 pipeline + scaffolding)
├── skills/                ← Multi-step procedures (slash commands)
│   ├── security-audit/SKILL.md
│   ├── forge-execute/SKILL.md
│   └── ... (12 skills)
├── hooks/                 ← Lifecycle automation
│   ├── sessionStart.sh
│   └── postToolUse.sh
└── copilot-instructions.md  ← Master config file

How Guardrails Auto-Load

Each instruction file has an applyTo pattern in its YAML frontmatter. When you edit a file that matches the pattern, the instruction file loads automatically into the AI's context:

---
description: Security best practices
applyTo: "**/auth/**,**/security/**,**/middleware/**"
---

When you open src/auth/token-validator.ts, the security instruction file loads. When you open src/models/User.ts, the database instruction file loads. No manual action needed — the AI reads the right rules for the right code.

The .forge.json Config

This file stores your project's Plan Forge configuration:

{
  "preset": "dotnet",
  "templateVersion": "2.17.0",
  "modelRouting": {
    "default": "claude-sonnet-4.6",
    "execute": "grok-4",
    "review": "claude-opus-4.6"
  },
  "escalationChain": ["grok-4", "claude-opus-4.6", "gpt-5.2-codex"],
  "quorumThreshold": 6
}

Key settings: which preset was used, which models to use for each role (execution vs review), the escalation chain when a model fails, and the complexity threshold for quorum mode.

Plans Are Markdown

A plan is just a .md file with structure. It lives in docs/plans/ and follows a template. Here's the minimal skeleton:

# Phase 1 — User Authentication

## Scope Contract
**In Scope**: src/auth/**, src/middleware/auth*, tests/auth/**
**Out of Scope**: frontend, deployment, CI
**Forbidden Actions**: Do NOT modify src/database/migrations/

## MUST Criteria
- [ ] JWT token generation and validation
- [ ] Role-based access control (admin, user)
- [ ] Password hashing with bcrypt

## Execution Slices

### Slice 1 — Auth Models + Migration [30 min]
**Tasks**: Create User model, JWT service
**Gate**: `dotnet build` passes, `dotnet test` passes
**Stop if**: Build fails or migration errors

### Slice 2 — Auth Middleware [30 min]
**Tasks**: JWT validation middleware, role decorator
**Gate**: `dotnet test` — 6+ tests pass
**Stop if**: Any existing test regresses

The AI reads this contract and follows it literally. Slices are checkpointed — the gate at the end of each slice must pass before proceeding to the next.

Slices, Gates, and Scope

These are the three building blocks of every plan:

Three Ways to Run the Pipeline

The same pipeline can run three different ways. Pick the one that matches your tools:

All three produce identical results. The guardrails, validation gates, and pipeline steps are the same — only the delivery mechanism differs.

📄 Full reference: COPILOT-VSCODE-GUIDE.md, capabilities.md