npm package: @lipter7/blueprint
Description: Blueprint: a meta-prompting, context engineering and spec-driven development system for Claude Code, OpenCode and Gemini CLI.
Author: TÂCHES
Latest version: 2.0.1

<div align="center">

# Blueprint

**A light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code, OpenCode, and Gemini CLI.**

*Forked from [GET SHIT DONE (GSD)](https://github.com/gsd-build/get-shit-done) with a focus on improved user interaction during research, planning, and codebase mapping.*

**Solves context rot — the quality degradation that happens as Claude fills its context window.**

[![npm version](https://img.shields.io/npm/v/@lipter7/blueprint?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/@lipter7/blueprint)
[![npm downloads](https://img.shields.io/npm/dm/@lipter7/blueprint?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/@lipter7/blueprint)
[![GitHub stars](https://img.shields.io/github/stars/lipter7/blueprint?style=for-the-badge&logo=github&color=181717)](https://github.com/lipter7/blueprint)
[![License](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](LICENSE)

<br>

```bash
npm install -g @lipter7/blueprint
blueprint
```

**Works on Mac, Windows, and Linux.**

<br>

![Blueprint Install](assets/terminal.svg)

<br>

[How It Works](#how-it-works) · [Commands](#commands) · [Why It Works](#why-it-works)

</div>

---

## What Is Blueprint?

Blueprint is a context engineering layer that makes Claude Code reliable. It solves "vibecoding" problems -- the inconsistent, degrading output you get as Claude fills its context window. The complexity is in the system, not in your workflow: context engineering, XML prompt formatting, subagent orchestration, and state management happen behind the scenes. What you see is a few commands that just work.

Blueprint is a fork of [GET SHIT DONE (GSD)](https://github.com/gsd-build/get-shit-done) by TACHES. This fork adds more user interaction points during the research, planning, and codebase mapping steps -- areas where the upstream version was too heavily AI-driven with insufficient human oversight.

---

## Getting Started

```bash
npm install -g @lipter7/blueprint
blueprint
```

The installer prompts you to choose:
1. **Runtime** — Claude Code, OpenCode, Gemini, or all
2. **Location** — Global (all projects) or local (current project only)

Verify with `/bp:help` inside your chosen runtime.

### Staying Updated

Blueprint evolves fast. Update periodically:

```bash
npm install -g @lipter7/blueprint@latest
blueprint
```

<details>
<summary><strong>Non-interactive Install (Docker, CI, Scripts)</strong></summary>

```bash
# Claude Code
blueprint --claude --global   # Install to ~/.claude/
blueprint --claude --local    # Install to ./.claude/

# OpenCode (open source, free models)
blueprint --opencode --global # Install to ~/.config/opencode/

# Gemini CLI
blueprint --gemini --global   # Install to ~/.gemini/

# All runtimes
blueprint --all --global      # Install to all directories
```

Use `--global` (`-g`) or `--local` (`-l`) to skip the location prompt.
Use `--claude`, `--opencode`, `--gemini`, or `--all` to skip the runtime prompt.

</details>

<details>
<summary><strong>Development Installation</strong></summary>

Clone the repository and run the installer locally:

```bash
git clone https://github.com/lipter7/blueprint.git
cd blueprint
node bin/install.js --claude --local
```

Installs to `./.claude/` for testing modifications before contributing.

</details>

### Recommended: Skip Permissions Mode

Blueprint is designed for frictionless automation. Run Claude Code with:

```bash
claude --dangerously-skip-permissions
```

> [!TIP]
> This is how Blueprint is intended to be used — stopping to approve `date` and `git commit` 50 times defeats the purpose.

<details>
<summary><strong>Alternative: Granular Permissions</strong></summary>

If you prefer not to use that flag, add this to your project's `.claude/settings.json`:

```json
{
  "permissions": {
    "allow": [
      "Bash(date:*)",
      "Bash(echo:*)",
      "Bash(cat:*)",
      "Bash(ls:*)",
      "Bash(mkdir:*)",
      "Bash(wc:*)",
      "Bash(head:*)",
      "Bash(tail:*)",
      "Bash(sort:*)",
      "Bash(grep:*)",
      "Bash(tr:*)",
      "Bash(git add:*)",
      "Bash(git commit:*)",
      "Bash(git status:*)",
      "Bash(git log:*)",
      "Bash(git diff:*)",
      "Bash(git tag:*)"
    ]
  }
}
```

</details>

---

## How It Works

> **Already have code?** Run `/bp:map-codebase` first. It spawns parallel agents to analyze your stack, architecture, conventions, and concerns. Then `/bp:new-project` knows your codebase — questions focus on what you're adding, and planning automatically loads your patterns.

### 1. Initialize Project

```
/bp:new-project
```

One command, one flow. The system:

1. **Questions** — Asks until it understands your idea completely (goals, constraints, tech preferences, edge cases)
2. **Research** — Spawns parallel agents to investigate the domain (optional but recommended)
3. **Requirements** — Extracts what's v1, v2, and out of scope
4. **Roadmap** — Creates phases mapped to requirements

You approve the roadmap. Now you're ready to build.

**Creates:** `PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, `STATE.md`, `.blueprint/research/`

---

### 2. Discuss Phase

```
/bp:discuss-phase 1
```

**This is where you shape the implementation.**

Your roadmap has a sentence or two per phase. That's not enough context to build something the way *you* imagine it. This step captures your preferences before anything gets researched or planned.

The system analyzes the phase and identifies gray areas based on what's being built:

- **Visual features** → Layout, density, interactions, empty states
- **APIs/CLIs** → Response format, flags, error handling, verbosity
- **Content systems** → Structure, tone, depth, flow
- **Organization tasks** → Grouping criteria, naming, duplicates, exceptions

For each area you select, it asks until you're satisfied. The output — `CONTEXT.md` — feeds directly into the next two steps:

1. **Researcher reads it** — Knows what patterns to investigate ("user wants card layout" → research card component libraries)
2. **Planner reads it** — Knows what decisions are locked ("infinite scroll decided" → plan includes scroll handling)

The deeper you go here, the more the system builds what you actually want. Skip it and you get reasonable defaults. Use it and you get *your* vision.

**Creates:** `{phase}-CONTEXT.md`

---

### 3. Plan Phase

```
/bp:plan-phase 1
```

The system:

1. **Researches** — Investigates how to implement this phase, guided by your CONTEXT.md decisions
2. **Plans** — Creates 2-3 atomic task plans with XML structure
3. **Verifies** — Checks plans against requirements, loops until they pass

Each plan is small enough to execute in a fresh context window. No degradation, no "I'll be more concise now."

**Creates:** `{phase}-RESEARCH.md`, `{phase}-{N}-PLAN.md`

---

### 4. Execute Phase

```
/bp:execute-phase 1
```

The system:

1. **Runs plans in waves** — Parallel where possible, sequential when dependent
2. **Fresh context per plan** — 200k tokens purely for implementation, zero accumulated garbage
3. **Commits per task** — Every task gets its own atomic commit
4. **Verifies against goals** — Checks the codebase delivers what the phase promised

Walk away, come back to completed work with clean git history.

**Creates:** `{phase}-{N}-SUMMARY.md`, `{phase}-VERIFICATION.md`

---

### 5. Verify Work

```
/bp:verify-work 1
```

**This is where you confirm it actually works.**

Automated verification checks that code exists and tests pass. But does the feature *work* the way you expected? This is your chance to use it.

The system:

1. **Extracts testable deliverables** — What you should be able to do now
2. **Walks you through one at a time** — "Can you log in with email?" Yes/no, or describe what's wrong
3. **Diagnoses failures automatically** — Spawns debug agents to find root causes
4. **Creates verified fix plans** — Ready for immediate re-execution

If everything passes, you move on. If something's broken, you don't manually debug — you just run `/bp:execute-phase` again with the fix plans it created.

**Creates:** `{phase}-UAT.md`, fix plans if issues found

---

### 6. Repeat → Complete → Next Milestone

```
/bp:discuss-phase 2
/bp:plan-phase 2
/bp:execute-phase 2
/bp:verify-work 2
...
/bp:complete-milestone
/bp:new-milestone
```

Loop **discuss → plan → execute → verify** until milestone complete.

Each phase gets your input (discuss), proper research (plan), clean execution (execute), and human verification (verify). Context stays fresh. Quality stays high.

When all phases are done, `/bp:complete-milestone` archives the milestone and tags the release.

Then `/bp:new-milestone` starts the next version — same flow as `new-project` but for your existing codebase. You describe what you want to build next, the system researches the domain, you scope requirements, and it creates a fresh roadmap. Each milestone is a clean cycle: define → build → ship.

---

### Quick Mode

```
/bp:quick
```

**For ad-hoc tasks that don't need full planning.**

Quick mode gives you Blueprint guarantees (atomic commits, state tracking) with a faster path:

- **Same agents** — Planner + executor, same quality
- **Skips optional steps** — No research, no plan checker, no verifier
- **Separate tracking** — Lives in `.blueprint/quick/`, not phases

Use for: bug fixes, small features, config changes, one-off tasks.

```
/bp:quick
> What do you want to do? "Add dark mode toggle to settings"
```

**Creates:** `.blueprint/quick/001-add-dark-mode-toggle/PLAN.md`, `SUMMARY.md`

---

## Why It Works

### Context Engineering

Claude Code is incredibly powerful *if* you give it the context it needs. Most people don't.

Blueprint handles it for you:

| File | What it does |
|------|--------------|
| `PROJECT.md` | Project vision, always loaded |
| `research/` | Ecosystem knowledge (stack, features, architecture, pitfalls) |
| `REQUIREMENTS.md` | Scoped v1/v2 requirements with phase traceability |
| `ROADMAP.md` | Where you're going, what's done |
| `STATE.md` | Decisions, blockers, position — memory across sessions |
| `PLAN.md` | Atomic task with XML structure, verification steps |
| `SUMMARY.md` | What happened, what changed, committed to history |
| `todos/` | Captured ideas and tasks for later work |

Size limits based on where Claude's quality degrades. Stay under, get consistent excellence.

### XML Prompt Formatting

Every plan is structured XML optimized for Claude:

```xml
<task type="auto">
  <name>Create login endpoint</name>
  <files>src/app/api/auth/login/route.ts</files>
  <action>
    Use jose for JWT (not jsonwebtoken - CommonJS issues).
    Validate credentials against users table.
    Return httpOnly cookie on success.
  </action>
  <verify>curl -X POST localhost:3000/api/auth/login returns 200 + Set-Cookie</verify>
  <done>Valid credentials return cookie, invalid return 401</done>
</task>
```

Precise instructions. No guessing. Verification built in.

### Multi-Agent Orchestration

Every stage uses the same pattern: a thin orchestrator spawns specialized agents, collects results, and routes to the next step.

| Stage | Orchestrator does | Agents do |
|-------|------------------|-----------|
| Research | Coordinates, presents findings | 4 parallel researchers investigate stack, features, architecture, pitfalls |
| Planning | Validates, manages iteration | Planner creates plans, checker verifies, loop until pass |
| Execution | Groups into waves, tracks progress | Executors implement in parallel, each with fresh 200k context |
| Verification | Presents results, routes next | Verifier checks codebase against goals, debuggers diagnose failures |

The orchestrator never does heavy lifting. It spawns agents, waits, integrates results.

**The result:** You can run an entire phase — deep research, multiple plans created and verified, thousands of lines of code written across parallel executors, automated verification against goals — and your main context window stays at 30-40%. The work happens in fresh subagent contexts. Your session stays fast and responsive.

### Atomic Git Commits

Each task gets its own commit immediately after completion:

```bash
abc123f docs(08-02): complete user registration plan
def456g feat(08-02): add email confirmation flow
hij789k feat(08-02): implement password hashing
lmn012o feat(08-02): create registration endpoint
```

> [!NOTE]
> **Benefits:** Git bisect finds exact failing task. Each task independently revertable. Clear history for Claude in future sessions. Better observability in AI-automated workflow.

Every commit is surgical, traceable, and meaningful.

### Modular by Design

- Add phases to current milestone
- Insert urgent work between phases
- Complete milestones and start fresh
- Adjust plans without rebuilding everything

You're never locked in. The system adapts.

---

## Commands

### Core Workflow

| Command | What it does |
|---------|--------------|
| `/bp:new-project [--auto]` | Full initialization: questions → research → requirements → roadmap |
| `/bp:discuss-phase [N]` | Capture implementation decisions before planning |
| `/bp:plan-phase [N]` | Research + plan + verify for a phase |
| `/bp:execute-phase <N>` | Execute all plans in parallel waves, verify when complete |
| `/bp:verify-work [N]` | Manual user acceptance testing ¹ |
| `/bp:audit-milestone` | Verify milestone achieved its definition of done |
| `/bp:complete-milestone` | Archive milestone, tag release |
| `/bp:new-milestone [name]` | Start next version: questions → research → requirements → roadmap |

### Navigation

| Command | What it does |
|---------|--------------|
| `/bp:progress` | Where am I? What's next? |
| `/bp:help` | Show all commands and usage guide |
| `/bp:update` | Update Blueprint with changelog preview |
| `/bp:join-discord` | Join the community Discord |

### Brownfield

| Command | What it does |
|---------|--------------|
| `/bp:map-codebase` | Analyze existing codebase before new-project |

### Phase Management

| Command | What it does |
|---------|--------------|
| `/bp:add-phase` | Append phase to roadmap |
| `/bp:insert-phase [N]` | Insert urgent work between phases |
| `/bp:remove-phase [N]` | Remove future phase, renumber |
| `/bp:list-phase-assumptions [N]` | See Claude's intended approach before planning |
| `/bp:plan-milestone-gaps` | Create phases to close gaps from audit |

### Session

| Command | What it does |
|---------|--------------|
| `/bp:pause-work` | Create handoff when stopping mid-phase |
| `/bp:resume-work` | Restore from last session |

### Utilities

| Command | What it does |
|---------|--------------|
| `/bp:settings` | Configure model profile and workflow agents |
| `/bp:set-profile <profile>` | Switch model profile (quality/balanced/budget) |
| `/bp:add-todo [desc]` | Capture idea for later |
| `/bp:check-todos` | List pending todos |
| `/bp:debug [desc]` | Systematic debugging with persistent state |
| `/bp:quick` | Execute ad-hoc task with Blueprint guarantees |

<sup>¹ Contributed by reddit user OracleGreyBeard</sup>

---

## Configuration

Blueprint stores project settings in `.blueprint/config.json`. Configure during `/bp:new-project` or update later with `/bp:settings`.

### Core Settings

| Setting | Options | Default | What it controls |
|---------|---------|---------|------------------|
| `mode` | `yolo`, `interactive` | `interactive` | Auto-approve vs confirm at each step |
| `depth` | `quick`, `standard`, `comprehensive` | `standard` | Planning thoroughness (phases × plans) |

### Model Profiles

Control which Claude model each agent uses. Balance quality vs token spend.

| Profile | Planning | Execution | Verification |
|---------|----------|-----------|--------------|
| `quality` | Opus | Opus | Sonnet |
| `balanced` (default) | Opus | Sonnet | Sonnet |
| `budget` | Sonnet | Sonnet | Haiku |

Switch profiles:
```
/bp:set-profile budget
```

Or configure via `/bp:settings`.

### Workflow Agents

These spawn additional agents during planning/execution. They improve quality but add tokens and time.

| Setting | Default | What it does |
|---------|---------|--------------|
| `workflow.research` | `true` | Researches domain before planning each phase |
| `workflow.plan_check` | `true` | Verifies plans achieve phase goals before execution |
| `workflow.verifier` | `true` | Confirms must-haves were delivered after execution |

Use `/bp:settings` to toggle these, or override per-invocation:
- `/bp:plan-phase --skip-research`
- `/bp:plan-phase --skip-verify`

### Execution

| Setting | Default | What it controls |
|---------|---------|------------------|
| `parallelization.enabled` | `true` | Run independent plans simultaneously |
| `planning.commit_docs` | `true` | Track `.blueprint/` in git |

### Git Branching

Control how Blueprint handles branches during execution.

| Setting | Options | Default | What it does |
|---------|---------|---------|--------------|
| `git.branching_strategy` | `none`, `phase`, `milestone` | `none` | Branch creation strategy |
| `git.phase_branch_template` | string | `bp/phase-{phase}-{slug}` | Template for phase branches |
| `git.milestone_branch_template` | string | `bp/{milestone}-{slug}` | Template for milestone branches |

**Strategies:**
- **`none`** — Commits to current branch (default Blueprint behavior)
- **`phase`** — Creates a branch per phase, merges at phase completion
- **`milestone`** — Creates one branch for entire milestone, merges at completion

At milestone completion, Blueprint offers squash merge (recommended) or merge with history.

---

## Security

### Protecting Sensitive Files

Blueprint's codebase mapping and analysis commands read files to understand your project. **Protect files containing secrets** by adding them to Claude Code's deny list:

1. Open Claude Code settings (`.claude/settings.json` or global)
2. Add sensitive file patterns to the deny list:

```json
{
  "permissions": {
    "deny": [
      "Read(.env)",
      "Read(.env.*)",
      "Read(**/secrets/*)",
      "Read(**/*credential*)",
      "Read(**/*.pem)",
      "Read(**/*.key)"
    ]
  }
}
```

This prevents Claude from reading these files entirely, regardless of what commands you run.

> [!IMPORTANT]
> Blueprint includes built-in protections against committing secrets, but defense-in-depth is best practice. Deny read access to sensitive files as a first line of defense.

---

## Troubleshooting

**Commands not found after install?**
- Restart Claude Code to reload slash commands
- Verify files exist in `~/.claude/commands/bp/` (global) or `./.claude/commands/bp/` (local)

**Commands not working as expected?**
- Run `/bp:help` to verify installation
- Re-run `blueprint` to reinstall

**Updating to the latest version?**
```bash
npm install -g @lipter7/blueprint@latest
blueprint
```

**Using Docker or containerized environments?**

If file reads fail with tilde paths (`~/.claude/...`), set `CLAUDE_CONFIG_DIR` before installing:
```bash
CLAUDE_CONFIG_DIR=/home/youruser/.claude blueprint --global
```
This ensures absolute paths are used instead of `~` which may not expand correctly in containers.

### Uninstalling

To remove Blueprint completely:

```bash
# Global installs
blueprint --claude --global --uninstall
blueprint --opencode --global --uninstall

# Local installs (current project)
blueprint --claude --local --uninstall
blueprint --opencode --local --uninstall
```

This removes all Blueprint commands, agents, hooks, and settings while preserving your other configurations.

---

## Community Ports

OpenCode and Gemini CLI are now natively supported via the `blueprint` installer.

These upstream GSD community ports pioneered multi-runtime support:

| Project | Platform | Description |
|---------|----------|-------------|
| [gsd-opencode](https://github.com/rokicool/gsd-opencode) | OpenCode | Original OpenCode adaptation |
| gsd-gemini (archived) | Gemini CLI | Original Gemini adaptation by uberfuzzy |

---

## Star History

<a href="https://star-history.com/#lipter7/blueprint&Date">
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=lipter7/blueprint&type=Date&theme=dark" />
   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=lipter7/blueprint&type=Date" />
   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=lipter7/blueprint&type=Date" />
 </picture>
</a>

---

## License

MIT License. See [LICENSE](LICENSE) for details.

---

<div align="center">

**Claude Code is powerful. Blueprint makes it reliable.**

</div>