Handbook
Adopting Blueprints
Choosing which adoption story matches you (ICP-style paths A / B / C) — not the command-by-command first hour.
What it is
Choosing which adoption story matches you (ICP-style paths A / B / C) — not the command-by-command first hour.
ForgeSDLC treats delivery as human-governed, agent-assisted work: Blueprints gives you the traceable documentation baseline; Forge and Versonas add governed review and execution patterns. This page is about which adoption slice to start with, not every command.
Blueprints is a reusable documentation framework: SDLC, PDLC, disciplines, and Forge / Versona patterns you consume as a Blueprints tree in your repository (often a submodule named blueprints/). Your project work lives in sdlc/, docs/, forge/ at the repository root — not in edits to the frozen baseline inside the Blueprints tree (see Blueprint policy).
Hands-on first hour: Quickstarts — First hour.
Terms (quick read)
| Term | Plain language |
|---|---|
| Blueprints | Software delivery documentation framework — SDLC/PDLC text, ceremonies, and templates you submodule into a repo. |
| Forge | Methodology tooling in your repo (config, logs, optional tasklets) that aligns editors and automation with that framework. |
| Forge Studio | Local workspace UI for delivery visibility — part of Lenses; runs on your machine, not inside blueprints/. |
| Wizard | Guided planning / assessment workflow in Studio — structured sessions and exports; does not auto-change your submodule. |
| Versona | Discipline-specific perspective (reviewer lens) used in Forge-aligned sessions — e.g. architecture, testing, security voice. |
When to use it
Use this page before you deep-read methodology folders or maintainer docs. Pick a path below, then run the first hour or the full Project setup checklist.
Prerequisites
- Add Blueprints to your repo (typically as a git submodule at
blueprints/; or copy the tree if you do not use submodules). The handbook home summarizes layout expectations. - Use the decision guide and path pages next.
Decision guide
Answer in order; the first row that matches your situation is usually the right starting path.
| Question | If yes → |
|---|---|
| You mainly need a solid text baseline and minimal ceremony | Start with path A |
| You must align several contributors or repos on vocabulary and ceremonies | Path B after A’s basics |
| You maintain a platform corpus and many products must pin the same upstream | Path C (often with governance for submodule bumps) |
Path choice (visual)
The decision guide above maps three situations to paths A, B, and C. Use it before deep-reading methodology folders.
What changes vs what stays frozen
| Area | What you add or own in your repo | What stays upstream (do not fork casually) |
|---|---|---|
| Interpretations, principles, “how we run it” | Project sdlc/, docs/, optional forge/ |
blueprints/sdlc/ baseline text — see Blueprint policy |
| Tooling and editor alignment | Cursor rules, optional Forge tasklets — see Project setup checklist | Templates in blueprints/ you copy or sync; not edited in place for product specifics |
| Submodule pointer | Your commit moves blueprints/ to a new SHA |
Upstream autowww/blueprints remains the canonical framework |
Risks and trade-offs (chooser)
| Path | Main trade-off | Mitigation |
|---|---|---|
| A | Too little shared process if the team grows | Move to B when you need shared ceremony language |
| B | Heavier alignment cost | Anchor one repo; use Team rollout patterns |
| C | Submodule drift across products | Published “golden” SHA + cadence; see Updating the submodule |
Choose your path (deep dives)
| Path | Page |
|---|---|
| A — Solo developer or small team | Adopting Blueprints — path A |
| B — Team lead / EM | Adopting Blueprints — path B |
| C — Organization / platform group | Adopting Blueprints — path C |
How to verify success
You have picked a path and can follow that path’s Steps page. Next, confirm repo checks in first hour or Project setup profile.
What to do next
- Quickstarts hub
- First hour (~60 minutes)
- Project setup profile
- Troubleshooting and FAQ
- Updating the submodule
- Team rollout patterns
Maintainer and GitHub-only detail
Release notes and framework-product context live on GitHub (for example ADOPTION.md, ROADMAP.md). Skip this block until you need upstream or release mechanics.