Skip to content
Back to search

bulletproof

Turns AI agents from chaotic code generators into disciplined engineers. 12-stage workflow from research to production.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/artemiimillier--bulletproof/badge.svg)](/listings/artemiimillier--bulletproof)

HTML

<a href="/listings/artemiimillier--bulletproof"><img src="/api/listings/artemiimillier--bulletproof/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# Into your project
mkdir -p .claude/skills && git clone https://github.com/artemiimillier/bulletproof.git .claude/skills/bulletproof

# Global (all projects)
mkdir -p ~/.claude/skills && git clone https://github.com/artemiimillier/bulletproof.git ~/.claude/skills/bulletproof

# For teams
git submodule add https://github.com/artemiimillier/bulletproof.git .claude/skills/bulletproof

Open Claude Code → type `/bulletproof` → done.

Or just describe your task - Claude picks up Bulletproof automatically when it's relevant.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 440 lines · 1 finding marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: bulletproof
  3. 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.
  4. ---
  5. # Bulletproof — Adaptive Development Workflow
  6. > **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)
  7. > **Version:** 5.0 · March 2026
  8. > **License:** MIT
  9. > **Compatible:** Claude Code, Codex, Gemini CLI, Cursor, Windsurf, OpenCode
  10. ## Core Principle
  11. **Code to solve problems, not code for code's sake.**
  12. Before EVERY change ask: "Does this actually solve our problem? Is this the most efficient solution?"
  13. If the answer isn't clear — stop, research alternatives, pick the best one.
  14. ---
  15. ## Pick Your Mode
  16. Not every task needs the full pipeline.
  17. | Size | Examples | Mode | Stages |
  18. |------|----------|------|--------|
  19. | **S** | Bug fix, small edit, 1-2 files | Lightweight | 1 → 4 → 5 → 6 → 7 → Gates (skip spec/plan) |
  20. | **M** | New feature, module refactor, 3-10 files | Standard | Stages 1-10 |
  21. | **L** | Architecture change, new service, 10+ files | Full | Stages 1-12 (all) |
  22. **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.
  23. ---
  24. ## Context Management (ALWAYS applies)
  25. ### The 40% Rule
  26. Code quality degrades when context fills beyond 40% ("Dumb Zone"). Rules:
  27. - Stay within 40-60% of the context window
  28. - Manual `/compact` at 50% — don't wait for auto
  29. - If overloaded: save progress → `/clear` → fresh start
  30. ### Fresh Context Between Stages
  31. Every major stage = clean context window:
  32. 1. Save stage artifact (research / spec / plan / handoff)
  33. 2. `/clear`
  34. 3. Start new stage pointing the agent to the artifact path
  35. ### Handoff Protocol
  36. Before `/clear` always create `progress/<task>-handoff.md`.
  37. See `templates/handoff.md` for format.
  38. ### Progressive Disclosure
  39. Don't dump the entire codebase into context:
  40. - Research: sub-agents → compact summary
  41. - Planning: summary + key interfaces only
  42. - Implementation: only files for current phase
  43. - In CLAUDE.md: `"For details, see path/to/docs.md"` (not @file)
  44. ---
  45. ## Stage 1: Deep Research
  46. **Mode: Read-Only. No code. No changes.**
  47. - Launch parallel Explore agents (1 per area: structure, patterns, deps, tests)
  48. - **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.
  49. - **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.
  50. - Save to `thoughts/research/YYYY-MM-DD-<task>.md`
  51. (see `templates/research.md` for format)
  52. **→ `/clear`**
  53. ---
  54. ## Stage 2: Spec / PRD
  55. **Mode: Read + Write only in specs/. No code.**
  56. **Spec = WHAT and WHY. Not how. Spec = contract.**
  57. - Read Research Artifact from `thoughts/research/`
  58. - Create `specs/YYYY-MM-DD-<name>.md`
  59. (see `templates/spec.md` for format)
  60. - Key sections: Problem, Goal, Scope, Acceptance Criteria, Constraints, Non-Goals
  61. **Skip for size S tasks.**
  62. **→ `/clear`**
  63. ---
  64. ## Stage 3: Planning + Questions
  65. **Mode: Read + Write only in plans/. No code yet.**
  66. - Read **both** Spec (`specs/`) and Research (`thoughts/research/`)
  67. - Launch Plan agents to check the approach
  68. - Find gaps: what's unthought? What edge cases? What could break?
  69. - **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.
  70. - **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.
  71. - 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.
  72. ### Challenge Loop (mandatory before finalizing plan)
  73. ```
  74. Before finalizing the plan, answer 3 questions:
  75. 1. DOES THIS SOLVE THE PROBLEM?
  76. Compare every plan item against acceptance criteria from spec.
  77. If any criterion is uncovered — the plan is incomplete.
  78. 2. IS THIS THE MOST EFFICIENT SOLUTION?
  79. Search: who has already solved this problem? What approach did they use?
  80. Name 2-3 alternative approaches (including ones found via research).
  81. For each: pros, cons, effort.
  82. Justify why the chosen approach is better than all alternatives.
  83. 3. IS THERE "CODE FOR CODE'S SAKE"?
  84. Every change must directly serve acceptance criteria.
  85. If a change isn't tied to solving the problem — remove it.
  86. Drive-by refactoring = separate task, not part of this one.
  87. ```
  88. ### Annotation Cycle
  89. 1. Claude drafts the plan
  90. 2. `Ctrl+G` — plan opens in editor
  91. 3. User adds `> NOTE:` annotations
  92. 4. Claude: `"Address all notes, don't implement yet"`
  93. 5. Repeat until no notes remain
  94. ### Questions for User
  95. - Only for real forks where there's a genuine decision to make
  96. - Use AskUserQuestion with options
  97. - For each question: **recommend which option you think is best and why**
  98. - Don't ask the obvious
  99. ### Final Plan
  100. Create `plans/YYYY-MM-DD-<name>.md`
  101. (see `templates/plan.md` for full template with Challenge Log, phases, prompts)
  102. **→ `/clear`**
  103. ---
  104. ## Stage 4: Phased Implementation
  105. **Each phase = separate session, fresh context, feature branch.**
  106. 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.
  107. **Guard phrase to start coding:** Only begin implementation after the plan is finalized and all annotation notes are addressed. The trigger: `"Implement Phase N according to plan."`
  108. Order within each phase:
  109. 1. Create/switch to feature branch: `feature/<task>`
  110. 2. Update status → `in_progress`
  111. 3. **TDD**: tests FIRST (red)
  112. 4. **Implement**: code to make tests pass (green)
  113. 5. **Refactor** (if needed)
  114. 6. **Self-Audit** (Stage 5)
  115. 7. **Verification** (Stage 6)
  116. 8. **Impact Analysis** (Stage 7)
  117. 9. **Gates** (see Gates section)
  118. 10. **Commit** (checkpoint)
  119. 11. Status → `completed`, write to Changelog
  120. 12. **Handoff** → `/clear`
  121. ---
  122. ## Stage 5: Self-Audit (after each phase)
  123. **Mandatory BEFORE marking `completed`:**
  124. ```
  125. Check the phase implementation:
  126. 1. SPEC COMPLIANCE
  127. Open spec. Walk through every acceptance criterion.
  128. For each: implemented? Where exactly in code?
  129. If any not covered — finish it.
  130. 2. CHALLENGE THE SOLUTION
  131. Look at the written code with fresh eyes.
  132. Does this actually solve the problem from spec?
  133. Is there a simpler/more efficient way?
  134. Any "code for code's sake" — changes unrelated to the task?
  135. ```
  136. ---
  137. ## Stage 6: Verification — Deep Bug Hunt
  138. **Not just linting. Thoughtful review with false-positive filtering.**
  139. ### Step 1: Find errors
  140. ```
  141. Check ALL code from this phase for:
  142. - Logic errors (wrong conditions, off-by-one, race conditions)
  143. - Data handling (null/undefined, type mismatches)
  144. - Security (injection, auth bypass, exposed secrets)
  145. - Performance (N+1 queries, memory leaks, unnecessary re-renders)
  146. ```
  147. ### Step 2: Verify bugs are REAL
  148. ```
  149. For EACH found bug:
  150. 1. Is this a REAL bug or a false positive?
  151. 2. Can you prove this bug is reproducible?
  152. 3. If you can't prove it — it's NOT a bug. Don't touch it.
  153. RULE: Don't fix code "for beauty" or "just in case".
  154. Fix ONLY proven bugs that actually affect functionality.
  155. Every "fix" without proof = risk of introducing a new bug.
  156. ```
  157. ### Step 3: Logic and efficiency check
  158. ```
  159. Final code cleanliness check:
  160. - Logic: is the data flow correct from input to output?
  161. - Efficiency: any redundant operations?
  162. - Readability: is the code understandable without comments?
  163. BUT: don't refactor "for beauty". Only if it affects correctness.
  164. ```
  165. ---
  166. ## Stage 7: Impact Analysis — "Did we break anything?"
  167. **The most underestimated stage. 75% of AI agents break previously working code.**
  168. ```
  169. MANDATORY CHECK BEFORE MERGE:
  170. 1. REGRESSION
  171. What other modules/functions depend on changed files?
  172. Run ALL project tests (not just current phase).
  173. If anything broke — this is priority #1.
  174. 2. SIDE EFFECTS
  175. Did any contracts/interfaces change (API, props, types)?
  176. If yes — who uses them? Are all consumers updated?
  177. 3. THINK AHEAD
  178. What problems could these changes cause in a week/month?
  179. Edge cases we haven't tested?
  180. What happens with: zero data? Huge data? Concurrent requests?
  181. What if the user does something unexpected?
  182. 4. COMPATIBILITY
  183. Backward compatibility preserved?
  184. Data migrations needed?
  185. Feature flags needed for gradual rollout?
  186. ```
  187. ---
  188. ## Stage 8: Integration Check
  189. - All phases `completed` → run gates across entire project
  190. - Explore agents for audit: everything from spec implemented?
  191. - Every acceptance criterion → fulfilled?
  192. ---
  193. ## Stage 9: Code Review (fresh context)
  194. **New session. No implementation bias.**
  195. - Launch `@code-reviewer` agent (see `agents/code-reviewer.md`)
  196. - Checklist: edge cases, race conditions, backward compat, security, error handling, performance
  197. - If possible: cross-model review (different model checks Claude's work)
  198. - **Warning**: AI reviewing AI has shared blind spots. For critical code — human review is mandatory.
  199. ---
  200. ## Stage 10: Security Scan (for M and L)
  201. ```bash
  202. semgrep --config=auto .
  203. # or
  204. /security-review # built into Claude Code
  205. ```
  206. ---
  207. ## Stage 11: Fixes + Re-verification
  208. If review/scan found issues:
  209. 1. Fix (only proven bugs — rule from Stage 6)
  210. 2. Re-run gates
  211. 3. Repeat Impact Analysis (Stage 7) — fixes didn't break anything else?
  212. 4. Re-review if major changes were made
  213. ---
  214. ## Stage 12: Cleanup + Deploy
  215. - Archive plan: `mv plans/<file> plans/archive/`
  216. - Keep spec as documentation
  217. - Squash merge → main
  218. - **Deploy — ONLY on explicit user request**
  219. ---
  220. ## Deterministic Gates
  221. A phase CANNOT be `completed` without passing ALL required gates.
  222. ### Tier 1: Required (block the phase)
  223. ```bash
  224. # Frontend
  225. cd frontend && npx tsc --noEmit # 0 type errors
  226. cd frontend && npm run lint # 0 lint errors
  227. cd frontend && npm test # all tests green
  228. # Backend
  229. cd backend && python -m py_compile app/main.py
  230. cd backend && pytest --tb=short -q
  231. cd backend && ruff check .
  232. ```
  233. ### Tier 2: Recommended (for M and L)
  234. ```bash
  235. npx madge --circular src/ # circular dependencies
  236. npm audit --audit-level=high # dependency vulnerabilities
  237. pip-audit
  238. ```
  239. ### Tier 3: Deep Security (for Security Scan stage)
  240. ```bash
  241. semgrep --config=auto .
  242. # or /security-review
  243. ```
  244. If a gate fails — fix and re-run. Never skip.
  245. ---
  246. ## Hooks
  247. Add to `.claude/settings.json`:
  248. ```json
  249. {
  250. "hooks": {
  251. "PreToolUse": [
  252. {
  253. "matcher": "Bash",
  254. "hooks": [{
  255. "type": "command",
  256. "command": "bash -c \"CMD=$(echo $TOOL_INPUT | jq -r '.command // empty'); echo \\\"$CMD\\\" | grep -qE '(git push.*(main|master)|rm -rf /|DROP TABLE)' && echo 'BLOCKED: Use feature branch / safe alternative.' >&2 && exit 2 || exit 0\""
    • Dismissed after review: Runs `rm -rf` against a root or home-directory path
    • Line 351 on GitHub
  257. }]
  258. }
  259. ],
  260. "Stop": [
  261. {
  262. "hooks": [{
  263. "type": "prompt",
  264. "prompt": "You are a JSON-only evaluator. Respond ONLY with raw JSON, no markdown.\n\nReview the assistant's final response. Reject if:\n- Rationalizing incomplete work ('pre-existing', 'out of scope', 'follow-up')\n- Listing problems without fixing them\n- Skipping test/lint failures with excuses\n- Making changes unrelated to the stated problem ('code for code's sake')\n- Claiming completion without running verification gates\n\nRespond: {\"ok\": false, \"reason\": \"[issue]. Go back and finish.\"}\nor: {\"ok\": true}"
  265. }]
  266. }
  267. ]
  268. }
  269. }
  270. ```
  271. ---
  272. ## Git Discipline
  273. - Each task = `feature/<task>` branch
  274. - Commit after each passed gate (checkpoint for rollback)
  275. - NEVER push to main directly (hook blocks it)
  276. - Squash merge on completion
  277. ---
  278. ## Optional Enhancements
  279. ### PostToolUse: Auto-format after every file write
  280. ```json
  281. {
  282. "matcher": "Write|Edit",
  283. "hooks": [{
  284. "type": "command",
  285. "command": "npx prettier --write \"$FILE_PATH\" 2>/dev/null || true"
  286. }]
  287. }
  288. ```
  289. Claude generates well-formatted code; the hook handles the last 10% to avoid CI failures.
  290. ### PreToolUse: Block hardcoded secrets on file write
  291. ```json
  292. {
  293. "matcher": "Write|Edit",
  294. "hooks": [{
  295. "type": "command",
  296. "command": "bash -c \"CONTENT=$(echo $TOOL_INPUT | jq -r '.content // empty'); echo \\\"$CONTENT\\\" | grep -qiP '(api.?key|secret|password)\\s*=\\s*[\\x27\\\"][^\\x27\\\"]{10,}' && echo 'BLOCKED: Hardcoded secret. Use env vars.' >&2 && exit 2 || exit 0\""
  297. }]
  298. }
  299. ```
  300. Fragile (regex-based) but catches obvious mistakes. For production, use `semgrep` or `/security-review` instead.
  301. ---
  302. ## Model Recommendations
  303. | Stage | Model | Why |
  304. |-------|-------|-----|
  305. | Research, Planning | Opus | Cross-file reasoning |
  306. | Implementation | Sonnet | Speed, cost-efficiency |
  307. | Code Review, Security | Opus | Deep analysis |
  308. | Anti-rationalization hook | Haiku | Fast, cheap gate |
  309. ---
  310. ## Project Structure
  311. ```
  312. project/
  313. ├── .claude/
  314. │ ├── settings.json # hooks config
  315. │ ├── skills/
  316. │ │ └── bulletproof/
  317. │ │ ├── SKILL.md # ← this file
  318. │ │ ├── templates/
  319. │ │ │ ├── research.md
  320. │ │ │ ├── spec.md
  321. │ │ │ ├── plan.md
  322. │ │ │ └── handoff.md
  323. │ │ └── agents/
  324. │ │ └── code-reviewer.md
  325. │ └── agents/ # project-level agents
  326. ├── CLAUDE.md # project brain
  327. ├── specs/ # WHAT and WHY
  328. ├── plans/ # HOW
  329. │ └── archive/ # completed plans
  330. ├── thoughts/research/ # research artifacts
  331. └── progress/ # handoff files
  332. ```
README.md · README · 247 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # 🛡️ Bulletproof
  2. [![GitHub stars](https://img.shields.io/github/stars/artemiimillier/bulletproof?style=for-the-badge&logo=github)](https://github.com/artemiimillier/bulletproof/stargazers)
  3. [![License: MIT](https://img.shields.io/badge/License-MIT-green?style=for-the-badge)](LICENSE)
  4. [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen?style=for-the-badge)](CONTRIBUTING.md)
  5. [![Last Commit](https://img.shields.io/github/last-commit/artemiimillier/bulletproof?style=for-the-badge)](https://github.com/artemiimillier/bulletproof/commits/main)
  6. [![Claude Code](https://img.shields.io/badge/Claude_Code-compatible-blue?style=for-the-badge)](https://claude.com/claude-code)
  7. [![Cursor](https://img.shields.io/badge/Cursor-compatible-blue?style=for-the-badge)](https://cursor.com)
  8. **A complete development methodology for AI agents. From idea to production.**
  9. > AI agents without a system are chaotic code generators. They start coding before they understand the task, grab the first solution instead of the best one, "find bugs" that aren't bugs, and say "done" when half the work isn't finished. Bulletproof turns that chaos into discipline.
  10. **Author:** Artemiy Miller · [GitHub](https://github.com/artemiimillier) · [Telegram](https://t.me/artemiymiller) · [Channel](https://t.me/+0jZamDvGOeZjOWE1) · [Email](mailto:who.ismillerr@gmail.com)
  11. ---
  12. ## The Problem
  13. You describe a feature. The AI writes code. Looks great. Then:
  14. - It broke something that was working fine
  15. - It "fixed" bugs that didn't exist and created real ones
  16. - It refactored code nobody asked it to touch
  17. - It said "done" when half the acceptance criteria aren't met
  18. - It picked the first solution that came to mind, not the best one
  19. - Next morning you realize it ignored the entire architecture of your project
  20. **75% of AI agents introduce regressions into working code** (SWE-CI benchmark, Alibaba 2025). This isn't an AI problem. It's a process problem.
  21. ---
  22. ## How Bulletproof Fixes This
  23. Bulletproof is a 12-stage workflow. Every stage exists because without it, something specific breaks. Not every task goes through all 12 - a bug fix runs through 6, a feature through 10, an architecture change through all 12.
  24. Here's what happens at each one:
  25. ---
  26. ### 🔍 Stage 1: Deep Research
  27. **The pain:** AI jumps straight into coding. Doesn't study the codebase, doesn't look for existing solutions, doesn't understand context.
  28. **What Bulletproof does:** AI launches parallel research agents. Each one digs into a different area - project structure, patterns, dependencies, tests. At the same time, it searches the web: who's already solved this? What libraries exist? What's the proven best practice?
  29. **The key thing:** The output isn't a list of options. It's a **concrete recommendation**: "the best approach is X, because Y." The AI has to make a decision and defend it, not dump the choice on you.
  30. ---
  31. ### 📋 Stage 2: Spec
  32. **The pain:** AI starts writing code without defining what exactly needs to be done. No criteria for "done." It ends up building the wrong thing, or building too much.
  33. **What Bulletproof does:** Creates a specification: WHAT we're building and WHY. Not how - just what. With clear acceptance criteria - an objective measure of "done" that the AI can't argue with later.
  34. **The key thing:** The spec is a **contract**. When the AI checks its own work at Stage 5, it checks against this contract, not against its gut feeling of "seems about right."
  35. ---
  36. ### 🧠 Stage 3: Plan + Challenge Loop
  37. **The pain:** AI grabs the first solution that pops into its head. Doesn't consider alternatives, doesn't think about consequences.
  38. **What Bulletproof does:** AI creates a plan. But before it can start coding, it has to pass the Challenge Loop - answer 3 questions:
  39. 1. **Does this actually solve the problem?** Compare every item in the plan against acceptance criteria from the spec. If anything isn't covered - the plan is incomplete.
  40. 2. **Is this the best solution?** Find 2-3 alternative approaches, compare pros and cons, and justify why the chosen one is better than all of them.
  41. 3. **Is there any "code for code's sake"?** Every change must tie directly to solving the problem. Drive-by refactoring = separate task, not part of this one.
  42. **The key thing:** AI can't start coding until it has **proven** that its plan is the best option available. Not "I think so" - "here are 3 options, here's the comparison, here's why this one wins."
  43. ---
  44. ### ⚡ Stage 4: Implementation
  45. **The pain:** AI writes code in one big chunk, context fills up, quality drops. No tests, no iterations.
  46. **What Bulletproof does:** Implementation is split into phases. Each phase runs in a fresh context window (so the AI doesn't get dumber as it goes). Order: tests first (TDD), then code. Phases with no dependencies can run in parallel across separate terminals.
  47. **The key thing:** **The 40% rule.** AI output quality degrades when context fills beyond 40%. Bulletproof runs `/clear` between stages and passes context through handoff documents. The AI always works in its "smart zone."
  48. ---
  49. ### ✅ Stage 5: Self-Audit
  50. **The pain:** AI says "done" - but half the criteria aren't met. Or it did extra stuff nobody asked for.
  51. **What Bulletproof does:** AI opens the spec and walks through every acceptance criterion: implemented? Where exactly in the code? Anything in there that wasn't part of the task?
  52. **The key thing:** It doesn't check based on vibes. It checks against **the contract**. Every criterion - yes or no. If no - go back and finish.
  53. ---
  54. ### 🔬 Stage 6: Verification
  55. **The pain:** AI "finds bugs" that aren't bugs. Fixes things that aren't broken. Makes "improvements" that create real problems.
  56. **What Bulletproof does:** Three-step check. Step 1 - find errors (logic, security, performance). Step 2 - **prove every bug is real**. Can you reproduce it? No? Then it's not a bug, don't touch it. Step 3 - logic and efficiency review.
  57. **The key thing:** The rule is **"don't fix code for aesthetics or just in case."** Every fix without proof is a risk of introducing a new bug. Early AI code reviewers flagged 9 false positives for every 1 real bug (Anthropic). This stage cuts out 90% of wasted work.
  58. ---
  59. ### 💥 Stage 7: Impact Analysis
  60. **The pain:** The code works. But it broke something somewhere else. You find out a week later.
  61. **What Bulletproof does:** Mandatory check before merge: (1) What modules depend on the changed files? Run ALL project tests, not just the current phase. (2) Did any contracts change - APIs, types, interfaces? Are all consumers updated? (3) What could go wrong in a month? With zero data? With a million records? With concurrent requests? (4) Backward compatibility? Migrations needed?
  62. **The key thing:** **75% of AI agents break working code** - precisely because this stage doesn't exist. Dependency graph analysis cuts regressions by 70% (TDAD/arXiv).
  63. ---
  64. ### 🔗 Stage 8: Integration Check
  65. All phases done - full test suite across the entire project. Audit: is everything from the spec actually implemented?
  66. ---
  67. ### 👁️ Stage 9: Code Review
  68. **The pain:** AI reviews its own code and thinks it's great.
  69. **What Bulletproof does:** New session. Fresh context. A separate agent that has **never seen** the implementation. Checks edge cases, race conditions, security, performance.
  70. **The key thing:** AI reviewing AI, but without the implementer's bias. For critical code - you still need a human, and Bulletproof says so explicitly.
  71. ---
  72. ### 🔒 Stage 10: Security Scan
  73. Automated vulnerability scanning. AI-generated code has 2-3x more security issues than human-written code. This catches them.
  74. ---
  75. ### 🔧 Stage 11: Fixes + Re-verification
  76. Found issues? Fix only proven bugs (Stage 6 rule still applies). After fixes - run impact analysis again. Fixes break code more often than original development does.
  77. ---
  78. ### 🚀 Stage 12: Deploy
  79. Archive the plan. Squash merge. Deploy - only when you explicitly say so.
  80. ---
  81. ## Plus: Anti-Rationalization Hook
  82. This one lives outside the stages. It's a Stop hook that fires **every time** the AI tries to wrap up. It checks:
  83. - Is the AI rationalizing incomplete work? ("pre-existing issue", "out of scope", "I'll note this for a follow-up")
  84. - Listing problems without actually fixing them?
  85. - Skipping failed tests with excuses?
  86. - Making changes unrelated to the task?
  87. - Claiming "done" without running verification?
  88. If yes - **blocks completion** and sends the AI back to finish.
  89. ---
  90. ## Adaptive Sizing
  91. Not every task needs all 12 stages:
  92. | Size | What | Stages |
  93. |------|------|--------|
  94. | **S** - bug fix, 1-2 files | Lightweight | Research → Build → Self-Audit → Verify → Impact → Gates |
  95. | **M** - feature, 3-10 files | Standard | Stages 1-10 |
  96. | **L** - architecture, 10+ files | Full pipeline | All 12 stages |
  97. ---
  98. ## Why This Works
  99. Not theory. Every mechanism is backed by research:
  100. | Mechanism | Source |
  101. |-----------|--------|
  102. | 40% context rule | HumanLayer |
  103. | Challenge Loop (justify decisions) | Addy Osmani, spec-first workflow |
  104. | False-positive filter | Anthropic Code Review |
  105. | Impact Analysis (dependency graphs) | SWE-CI (Alibaba), TDAD/arXiv |
  106. | Anti-rationalization | Trail of Bits |
  107. | Phase separation | RIPER-5, Spotify Engineering |
  108. ---
  109. ## Who This Is For
  110. - You're building real products with AI, not throwaway prototypes
  111. - You're tired of code that works on demo but breaks in production
  112. - You need a system that scales - from a one-line fix to a new microservice
  113. ---
  114. ## Install (30 seconds)
  115. ```bash
  116. # Into your project
  117. mkdir -p .claude/skills && git clone https://github.com/artemiimillier/bulletproof.git .claude/skills/bulletproof
  118. # Global (all projects)
  119. mkdir -p ~/.claude/skills && git clone https://github.com/artemiimillier/bulletproof.git ~/.claude/skills/bulletproof
  120. # For teams
  121. git submodule add https://github.com/artemiimillier/bulletproof.git .claude/skills/bulletproof
  122. ```
  123. Open Claude Code → type `/bulletproof` → done.
  124. Or just describe your task - Claude picks up Bulletproof automatically when it's relevant.
  125. ---
  126. ## Compatibility
  127. Claude Code · Codex · Cursor · Gemini CLI · Windsurf · OpenCode - any tool that supports the Agent Skills standard.
  128. ---
  129. ## What's Inside
  130. ```
  131. bulletproof/
  132. ├── SKILL.md # The full 12-stage workflow
  133. ├── templates/ # Artifact templates (research, spec, plan, handoff)
  134. ├── agents/ # Code review sub-agent
  135. ├── examples/ # Use cases
  136. ├── CONTRIBUTING.md
  137. └── LICENSE # MIT
  138. ```
  139. ---
  140. ## Contributing
  141. Contributions welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).
  142. ---
  143. ## License
  144. MIT
  145. *[Artemiy Miller](https://github.com/artemiimillier) · [Telegram](https://t.me/artemiymiller) · [Channel](https://t.me/+0jZamDvGOeZjOWE1) · [Email](mailto:who.ismillerr@gmail.com)*

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.