Handbook
First hour in your repository
A single sitting (~60 minutes) to get blueprints/, a project sdlc/ workspace, a minimal Forge layout, and Cursor rules aligned with the recommended preset. Each numbered step below ends with something you can verify…
What it is
A single sitting (~60 minutes) to get blueprints/, a project sdlc/ workspace, a minimal Forge layout, and Cursor rules aligned with the recommended preset. Each numbered step below ends with something you can verify before moving on.
Handbook-first: run every command from your repository root (the directory that will contain blueprints/ and sdlc/). The table below is a quick map; the numbered sections that follow are the same steps with full context.
When to use it
Use this guide after you intend to use Blueprints at the repository root (next to sdlc/, docs/, forge/). For which adoption story matches you first, see Adopting Blueprints.
Not covered here: choosing an ICP adopter path (solo vs team vs org) — see Adopting Blueprints. Maintainer plans and milestones — on GitHub: Roadmap.
First-hour sequence (visual)
Prerequisites
- Git and bash available.
- A repository checkout where you can run commands from the repository root (the folder that will contain
blueprints/). - Python 3 available (used by Forge init and Cursor rule sync scripts).
Steps
Before you start
Decide that blueprints/ will live at the repository root next to sdlc/, docs/, and (after this guide) forge/. The stock scripts assume that layout.
Why this layout: scripts such as init-sdlc-workspace.sh and forge-init.sh resolve paths from the repository root. Nesting blueprints/ elsewhere would require custom wrappers not covered here.
What each step does (one line each)
| # | You run (from repo root) | What it does |
|---|---|---|
| 1 | git submodule update --init --recursive |
Ensures the blueprints/ tree (including blueprints/sdlc/) is present |
| 2 | ./blueprints/sdlc/scripts/init-sdlc-workspace.sh "…" |
Creates your project sdlc/ workspace next to the baseline |
| 3 | ./blueprints/sdlc/methodologies/forge/setup/forge-init.sh |
Scaffolds Forge (forge/, logs paths, starter config) |
| 4 | bash blueprints/sdlc/methodologies/forge/setup/sync-forge-cursor-rules.sh sync --preset recommended |
Installs recommended Cursor rules from Blueprints |
| 5 | (See Forge Studio quickstart) | Optional local Studio — separate from this repo |
1. Get the blueprint on disk
If you have not already, add Blueprints as a git submodule at blueprints/ (or ensure a copy of the tree exists there). Initialize submodules so blueprints/sdlc/ is present:
git submodule update --init --recursive
2. Create the project sdlc/ workspace
From the repository root, run (replace the quoted name with your project label):
./blueprints/sdlc/scripts/init-sdlc-workspace.sh "Your project name"
3. Initialize Forge
Still from the repo root:
./blueprints/sdlc/methodologies/forge/setup/forge-init.sh
Edit forge/forge.config.yaml later when you are ready; the full setup checklist lists questionnaire and alignment steps.
4. Install Cursor rules (recommended preset)
From the repo root:
bash blueprints/sdlc/methodologies/forge/setup/sync-forge-cursor-rules.sh sync --preset recommended
For preset options and YAML-only installs, use the handbook page for Cursor rules — quickstart.
Optional audit:
bash blueprints/sdlc/methodologies/forge/setup/sync-forge-cursor-rules.sh check
5. Optional: Forge Studio (local workspace UI)
Forge Studio is the product name for Lenses Studio — the React UI at /studio/ on the forge-lenses server. It is a separate public repository (autowww/forge-lenses); it does not ship inside blueprints/. The same project’s user guides (Lenses, Forge Studio, Blueprints Wizard) are published read-only at blueprints.forgesdlc.com/lenses; the runnable app stays on your machine.
Next: Follow Forge Studio quickstart — clone or submodule, Python venv, run the server, open /studio/.
Example repo (generic)
| Starting situation | New monorepo root acme-api/; no blueprints/ yet; you want Forge + Cursor aligned in one sitting. |
| Action taken | Submodule add blueprints/, run init-sdlc-workspace.sh, forge-init.sh, sync-forge-cursor-rules.sh sync --preset recommended. |
| Expected result | blueprints/sdlc/README.md, sdlc/README.md, forge/forge.config.yaml, and .cursor/rules (or synced rules path) exist from the stock scripts. |
| What to check | From repo root: test -f blueprints/sdlc/README.md && test -f sdlc/README.md && test -f forge/forge.config.yaml; optional Studio only after this passes. |
How to verify success
| After step | Check |
|---|---|
| 1. Get the blueprint | From the repo root, test -f blueprints/sdlc/README.md exits 0. |
2. Project sdlc/ |
sdlc/README.md exists and describes your project — not edits under blueprints/sdlc/ (frozen baseline). |
| 3. Forge | forge/forge.config.yaml exists and ember-logs/ (or paths created by the script) are present. |
| 4. Cursor rules | The sync script completes without error; optional: … check passes. |
| 5. Optional Forge Studio | With the server running on the default port, http://127.0.0.1:8080/studio/ should load (see the Forge Studio quickstart and Lenses troubleshooting if it does not). |
If you are comfortable checking locally (optional)
| Check | When it helps |
|---|---|
| Server terminal output | Surfaces import, port, or scan errors if Studio or Classic misbehaves |
| Open the workspace-state URL your runbook names | Confirms the server is healthy when the UI is unclear — only if whoever runs Lenses agrees |
Common mistakes
| Mistake | What to do |
|---|---|
| Running scripts from a subfolder of the repo | cd to the repository root (the directory that will list blueprints/, sdlc/, …) and re-run |
Editing files under blueprints/ for product-specific wording |
Move that text to project sdlc/ or docs/; see Policy |
Skipping git submodule update after clone |
Run git submodule update --init --recursive so blueprints/sdlc/ exists |
Expecting Forge Studio inside blueprints/ |
Forge Studio is the forge-lenses app — see Forge Studio quickstart |
Worked example (generic)
| Stage | Situation | Action | What to check |
|---|---|---|---|
| Start | Fresh clone; blueprints/ empty |
git submodule update --init --recursive |
test -f blueprints/sdlc/README.md |
| Middle | Forge init done | Open forge/forge.config.yaml; fill questionnaire when ready |
YAML parses; paths exist |
| Done | Team wants Cursor help | sync-forge-cursor-rules.sh sync --preset recommended |
… check passes if you gate on it |
What to do next
- Full ordered checklist (submodule through optional product flows): Project setup profile.
- ICP paths (which adoption story matches you): Adopting Blueprints.
- Documentation layout in the consuming repo — Documentation structure in this handbook.