@lipter7/blueprint 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Lex Christopherson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,626 @@
+<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
+npx @lipter7/blueprint@latest
+```
+
+**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
+npx @lipter7/blueprint@latest
+```
+
+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
+npx @lipter7/blueprint@latest
+```
+
+<details>
+<summary><strong>Non-interactive Install (Docker, CI, Scripts)</strong></summary>
+
+```bash
+# Claude Code
+npx @lipter7/blueprint --claude --global   # Install to ~/.claude/
+npx @lipter7/blueprint --claude --local    # Install to ./.claude/
+
+# OpenCode (open source, free models)
+npx @lipter7/blueprint --opencode --global # Install to ~/.config/opencode/
+
+# Gemini CLI
+npx @lipter7/blueprint --gemini --global   # Install to ~/.gemini/
+
+# All runtimes
+npx @lipter7/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 `npx @lipter7/blueprint` to reinstall
+
+**Updating to the latest version?**
+```bash
+npx @lipter7/blueprint@latest
+```
+
+**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 npx @lipter7/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
+npx @lipter7/blueprint --claude --global --uninstall
+npx @lipter7/blueprint --opencode --global --uninstall
+
+# Local installs (current project)
+npx @lipter7/blueprint --claude --local --uninstall
+npx @lipter7/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 `npx @lipter7/blueprint`.
+
+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>