/bulletproof

name: bulletproof
description: Use when building a feature, refactoring, fixing a complex bug, changing architecture, or starting any non-trivial coding task. 12-stage verified dev workflow from research to deploy.

Bulletproof — Adaptive Development Workflow

> **Author:** Artemiy Miller ([@artemiimillier](https://github.com/artemiimillier)) · [Telegram](https://t.me/artemiymiller) · [who.ismillerr@gmail.com](mailto:who.ismillerr@gmail.com) · [TG Channel](https://t.me/+0jZamDvGOeZjOWE1) > **Version:** 5.0 · March 2026 > **License:** MIT > **Compatible:** Claude Code, Codex, Gemini CLI, Cursor, Windsurf, OpenCode

Core Principle

**Code to solve problems, not code for code's sake.**

Before EVERY change ask: "Does this actually solve our problem? Is this the most efficient solution?" If the answer isn't clear — stop, research alternatives, pick the best one.

---

Pick Your Mode

Not every task needs the full pipeline.

| Size | Examples | Mode | Stages | |------|----------|------|--------| | **S** | Bug fix, small edit, 1-2 files | Lightweight | 1 → 4 → 5 → 6 → 7 → Gates (skip spec/plan) | | **M** | New feature, module refactor, 3-10 files | Standard | Stages 1-10 | | **L** | Architecture change, new service, 10+ files | Full | Stages 1-12 (all) |

**How stages relate:** Stages 5-6-7 (Self-Audit, Verification, Impact) run **inside each implementation phase** as an inner loop. Stages 8-12 run **once after all phases complete** as an outer loop.

---

Context Management (ALWAYS applies)

The 40% Rule

Code quality degrades when context fills beyond 40% ("Dumb Zone"). Rules:

• Stay within 40-60% of the context window
• Manual `/compact` at 50% — don't wait for auto
• If overloaded: save progress → `/clear` → fresh start

Fresh Context Between Stages

Every major stage = clean context window: 1. Save stage artifact (research / spec / plan / handoff) 2. `/clear` 3. Start new stage pointing the agent to the artifact path

Handoff Protocol

Before `/clear` always create `progress/<task>-handoff.md`. See `templates/handoff.md` for format.

Progressive Disclosure

Don't dump the entire codebase into context:

• Research: sub-agents → compact summary
• Planning: summary + key interfaces only
• Implementation: only files for current phase
• In CLAUDE.md: `"For details, see path/to/docs.md"` (not @file)

---

Stage 1: Deep Research

**Mode: Read-Only. No code. No changes.**

• Launch parallel Explore agents (1 per area: structure, patterns, deps, tests)
• **WebSearch: Who has already solved this problem? How did they solve it? What is the most efficient known solution?** Don't reinvent — find the best existing approach first.
• **Analyze all findings and make a conclusion: which solution is the BEST and why.** The research artifact must end with a clear recommendation, not just a list of options.
• Save to `thoughts/research/YYYY-MM-DD-<task>.md`

(see `templates/research.md` for format)

**→ `/clear`**

---

Stage 2: Spec / PRD

**Mode: Read + Write only in specs/. No code.**

**Spec = WHAT and WHY. Not how. Spec = contract.**

• Read Research Artifact from `thoughts/research/`
• Create `specs/YYYY-MM-DD-<name>.md`

(see `templates/spec.md` for format)

• Key sections: Problem, Goal, Scope, Acceptance Criteria, Constraints, Non-Goals

**Skip for size S tasks.** **→ `/clear`**

---

Stage 3: Planning + Questions

**Mode: Read + Write only in plans/. No code yet.**

• Read **both** Spec (`specs/`) and Research (`thoughts/research/`)
• Launch Plan agents to check the approach
• Find gaps: what's unthought? What edge cases? What could break?
• **Be creative and proactive: anticipate ALL possible problems BEFORE writing code.** Think several steps ahead. What could go wrong in a week? A month? Under load? With unexpected user behavior? Solve problems before they exist.
• **WebSearch: How have others solved this exact problem? What libraries/patterns exist? What's the proven best practice?** Choose the most efficient solution, not the first one that comes to mind.
• After Plan agents verify the approach — **rewrite the plan into an improved version** incorporating all findings, edge cases, and research results. Not just patch it — rewrite it better.

Challenge Loop (mandatory before finalizing plan)

Before finalizing the plan, answer 3 questions:

1. DOES THIS SOLVE THE PROBLEM?
   Compare every plan item against acceptance criteria from spec.
   If any criterion is uncovered — the plan is incomplete.

2. IS THIS THE MOST EFFICIENT SOLUTION?
   Search: who has already solved this problem? What approach did they use?
   Name 2-3 alternative approaches (including ones found via research).
   For each: pros, cons, effort.
   Justify why the chosen approach is better than all alternatives.

3. IS THERE "CODE FOR CODE'S SAKE"?
   Every change must directly serve acceptance criteria.
   If a change isn't tied to solving the problem — remove it.
   Drive-by refactoring = separate task, not part of this one.

Annotation Cycle

1. Claude drafts the plan 2. `Ctrl+G` — plan opens in editor 3. User adds `> NOTE:` annotations 4. Claude: `"Address all notes, don't implement yet"` 5. Repeat until no notes remain

Questions for User

• Only for real forks where there's a genuine decision to make
• Use AskUserQuestion with options
• For each question: **recommend which option you think is best and why**
• Don't ask the obvious

Final Plan

Create `plans/YYYY-MM-DD-<name>.md` (see `templates/plan.md` for full template with Challenge Log, phases, prompts)

**→ `/clear`**

---

Stage 4: Phased Implementation

**Each phase = separate session, fresh context, feature branch.**

Phases can be run **in parallel** via separate Claude Code sessions/terminals when they don't depend on each other. Check the plan for dependencies before parallelizing.

**Guard phrase to start coding:** Only begin implementation after the plan is finalized and all annotation notes are a