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.