Codebloom

Codebloom transforms Claude Code into a disciplined coding partner, ensuring structured workflows.

Codebloom

🇫🇷 Version française

Codebloom — workflow ritual for Claude Code

Claude Code, structured — plan, verify, ship. No rush, no slop, no drift.

A Claude Code plugin that turns your AI agent into a structured teammate: it explains before coding, verifies before shipping, and documents before pushing.

Who this is for

If you use Claude Code seriously — not just to autocomplete a line — you know the drill. It rushes in, refactors five files when you asked for one, invents function names that don't exist, forgets the convention you just set, and declares done before running the tests. Codebloom is the missing workflow layer that fixes this.

It's built for:

  • The solo dev who writes code with Claude every day, juggles three or four projects, and keeps hitting the same oversights.
  • The freelance / consultant who jumps between WordPress, Node, Python, Rails, Flutter — and wants one consistent guardrail across all of them.
  • The tech lead who needs to standardize how the team uses Claude Code, so reviews, tests, and conventional commits aren't optional anymore.

If none of that sounds like you, you probably don't need Codebloom. If it does, keep reading.

The problem

By default, Claude Code is a brilliant but undisciplined teammate. Ask it to fix one bug, it refactors five files. Ask it a question, it writes code. Ask it to review, it praises the diff and moves on. The result is a workflow that feels fast until the third time you undo something it "helpfully" changed.

Concretely:

  • It rushes in. You ask for a share button, it modifies 8 files and installs a library.
  • It over-engineers. Strategy patterns for a single function, any types, flags for features you never asked for.
  • It hallucinates references. Function names that don't exist, WordPress hooks invented on the spot, API signatures that look plausible but aren't real.
  • It forgets context. Your design system, your conventions, your CLAUDE.md — ignored the moment the session gets long.
  • It says "done" without verifying. No test run, no build check, no proof. Just ✓ finished.
  • It flatters. "Great question!", "You're absolutely right!", "I hope this helps!" — tokens you pay for, zero signal.

Codebloom fixes each of these with a layered system: 15 auto-invoked skills, 7 specialized agents working in isolated background contexts, 6 slash commands that structure your session, and 7 inviolable rules injected into every project's CLAUDE.md.

Before / After

A real request, a real difference.

Without Codebloom:

You:    "Add rate limiting to the /api/users endpoint"
Claude: [opens 6 files, installs express-rate-limit, refactors the auth
         middleware, changes the error handler signature, adds Redis as a
         dependency, "✓ done!" — no tests run, no security check]
You:    "... I just wanted rate limiting on one route."

With Codebloom:

You:    "Add rate limiting to the /api/users endpoint"
Claude: "Plan:
        - Add express-rate-limit middleware scoped to /api/users only
        - In-memory store, 100 req/min per IP
        - Files touched: routes/users.ts (1 line), middleware/rateLimit.ts (new)
        - Out of scope: auth middleware, error handler, global config
        Go?"
You:    "Go"
Claude: [implements, 2 files, minimal diff]

[you run /codebloom:push]

Claude: "Agents kicked off in parallel for the gate:
        ⏳ reviewer          — quality/security/footprint
        ⏳ tester            — test suite
        ⏳ security-auditor  — sensitive zones touched: /api/
        ⏳ researcher        — new dependency: [email protected]"

[pipeline runs in parallel, isolated contexts]

Claude: "✅ reviewer         9.1/10, clean
         ✅ tester           47/47 pass
         ✅ security-auditor 8.8/10, zero critical
         ✅ researcher       [email protected] — maintained, MIT, CVE-free
         📋 Aggregated report: 0 blockers, 2 suggestions → TODO.md [review]
         Ready to commit."

Same goal. Different outcome. The difference is not magic — it's a pipeline of skills and agents that enforce the discipline you'd apply yourself if you had infinite time.

The core loop

Every session with Codebloom goes through 4 moments. Skills and agents auto-invoke at each step.

1. Plan

Before touching a file, Claude stops and presents a plan: files it will change, what it will add, what's out of scope. You approve, it codes. You push back, it adjusts. No drive-by refactors. No tant qu'on y est.

intent-check enforces this on every message — a question gets a text answer, never code. Vague goals are reformulated into verifiable ones: "add validation" becomes "write tests for invalid inputs, make them pass".

2. Code

Minimal diff. No drive-by refactors. Every modified line must trace back to your request. code-quality enforces Karpathy principles (don't guess, code minimum, surgical, verify), zero invention of references, and the 3-strike rule (don't loop on the same error without changing approach).

context-guard saves tokens by delegating heavy explorations to subagents past 5 files and killing sycophantic openers/closers.

3. Verify

Before any commit, /codebloom:push runs a parallel pipeline of specialized agents in isolated background contexts:

  • Always: reviewer (quality/security/footprint) + tester (run tests, check regressions)
  • If the diff touches auth|jwt|token|password|crypto|upload|.env|admin: + security-auditor
  • If a new dependency was added: + researcher
  • If it's a structural change (new command, new dossier, new API): + doc-writer
  • If you touched a file modified ≥5 times in the last 7 days: + git-historian

Claude waits for all of them. An aggregated report is shown, classified by severity. 🔴 blockers stop the commit — fix, rerun the impacted agents, loop until green. 🟠 important findings ask for your decision. 🟡 suggestions are auto-capitalized into TODO.md with source tags ([review], [sec], [test], [audit], [research], [hotspot]) so nothing gets lost.

4. Ship

Once the gate passes, Codebloom handles the rest:

  • Updates CHANGELOG.md (Keep a Changelog format)
  • Runs a health-check on CLAUDE.md (size, obsolete commands, broken imports)
  • Syncs structural changes via doc-writer
  • Bumps the WordPress plugin zip if applicable (cross-platform, no rm prompts)
  • Writes a conventional commit message (feat:, fix:, refactor:, chore:…)
  • Pushes

Quick start

/plugin marketplace add vendeesign/codebloom
/plugin install codebloom@codebloom

That's it. Then in any project:

/codebloom:setup     ← configure once per project
/codebloom:hello     ← start of every session
(you work)           ← guardrails auto-load
/codebloom:push      ← end of session: verify, document, commit, push

What's inside

15 auto-invoked skills

Skills are contextual guardrails. Claude loads them automatically based on what you're doing — no command needed.

Permanent (active every session):

SkillRole
intent-checkClassifies every message before acting. Question → text answer, never code. Instruction → plan → approval → code.
code-qualitySTOP → plan → approval → code. Karpathy principles, zero invention, trace-test, debugging 5 phases, 3-strike rule, verification before completion.
context-guardSaves tokens, anti-cascade, delegates to subagents past 5 files. Anti-sycophancy, parseable output (no em-dashes in code), tool-first.

Contextual (load based on what you're touching):

SkillLoads when
ui-designWriting HTML/CSS/JSX/Vue/Svelte/Astro/Tailwind. Distinctive typography, WCAG AA, zero cyan/indigo/violet/glassmorphism.
backendWriting routes/controllers/services/models in Express, FastAPI, Laravel, Django, Rails, Spring, Gin, ASP.NET, and more.
mobileWriting Kotlin/Android, SwiftUI/iOS, Flutter, React Native/Expo.
securityTouching auth, JWT, bcrypt, SQL, crypto, CORS, CSP, upload. OWASP Top 10 + STRIDE.
wp-packWordPress project detected (Plugin Name: or Theme Name: header). Auto detect → bump → zip → verify.
dependency-checkRunning npm install, composer require, pip install, cargo add, go get, gem install. Native possible? Size? Maintenance? CVE?
git-conventionsRunning git commit, git push, git branch, git rebase, creating PRs. Conventional commits, destructive guards.
discoveryRequirements are vague, multi-interpretable, or complex. Guided interview process.
doc-syncReminder after significant changes that docs should follow.
demo-pageUser asks for a mockup, preview, prototype. Pixel-perfect HTML validation before code.
create-skill / create-agentGuided creation of a new skill or agent through structured prompts.

7 specialized agents

Agents work in isolated background contexts. Their output is compact — it doesn't pollute your conversation. Every agent has:

  • Zero-invention rule — nothing cited without being confirmed by a tool.
  • Capitalization into TODO.md — non-critical findings end up as - [ ] [tag] description so you can triage later.
  • Isolated context — each agent runs in its own window, returns a compact summary, never pollutes the main conversation.
AgentRoleAuto-trigger
reviewer2-pass review: spec compliance (does the code do what was asked?) then code quality. 3-angle analysis (project conformity, 2-pass quality, git context). False-positive filtering. Confidence per finding./push step 2
testerDetects framework (vitest/jest/pytest/phpunit/cargo test…), generates AAA tests with mandatory edge cases (null/empty/boundary/concurrency/dates), runs suite, reports regressions./push step 2
security-auditor4 parallel scans (deps, secrets, configs, vulnerable code). Weighted 0-100 score on 6 categories. Grade A-F. Remediation per finding./push when diff matches sensitive patterns
researcherInvestigates lib/API/pattern: official doc first, patterns in the project, alternatives comparison, CVE, deprecations. Sources required./push when a new dep appears in the manifest
doc-writerSyncs CHANGELOG, CLAUDE.md, README, API_DOC, DESIGN_SYSTEM to the real code state. Never touches source code./push on structural changes
auditorFull health audit on 9 axes: deps, architecture, dead code, security, quality, tests, docs, config, perf. Scored report with prioritized actions./codebloom:audit or on demand
git-historianArchaeology: timeline, hotspots, bus factor, bug-introduction tracking, velocity. Read-only strict.Velocity + top 3 hotspots shown in every /hello. Full analysis on demand.

6 slash commands

CommandWhat it does
/codebloom:setupConfigure a new or existing project. Generates a lean CLAUDE.md (best practices, ~80 lines), .claude/settings.json with safe permissions, TODO.md, CHANGELOG.md, DEV_TIME.md. On existing projects: analyzes package.json/composer.json/Makefile/.env.example to pre-fill the template.
/codebloom:updateUpdate Codebloom in the project. Syncs the inviolable rules block (versioned via <!-- codebloom:rules:start vN -->), migrates the CLAUDE.md format on first run (with CLAUDE.md.backup + user validation), refreshes .claude/settings.json permissions.
/codebloom:helloStart-of-session briefing: branch, last commit, backlog, 7-day velocity, top 3 hotspots, CLAUDE.md health. Detects upstream Codebloom updates. Starts the screenshot watcher.
/codebloom:pushEnd-of-session pipeline. Parallel gate agents (conditional), aggregated report, blocking on 🔴, user decision on 🟠, capitalization on 🟡, CLAUDE.md health-check, CHANGELOG sync, version bump, conventional commit, push.
/codebloom:todoQuick backlog: add (classified automatically), list, or execute entries. Integrates with the tagged capitalization from agents.
/codebloom:auditOn-demand full audit — 4 parallel agents (quality, security, tests, health) with interactive fix proposals.

The inviolable rules

Codebloom injects a versioned block of 7 inviolable rules into every project's CLAUDE.md. This block is a safety net that works even when auto-invoked skills fail to load. Synchronized automatically by /codebloom:update, editable by you outside the markers.

1. STOP before writing code        — plan → approval → code, always
2. Question → text answer          — never Write/Edit on a question
3. Zero invention                  — cite only what a tool confirmed
4. Trace-test on every diff        — each line must trace to the request
5. Orphans vs pre-existing         — clean your own mess, leave the rest
6. Verification before completion  — no "done" without fresh proof
7. User override                   — your explicit instructions always win

These are the minimum contract. Everything else is guidance — these seven are enforced.

Tooling & goodies

Codebloom ships with a handful of cross-platform tools that sit quietly in the background and make the daily workflow more bearable. Zero config — all of them are enabled the moment you install the plugin.

Statusline

A permanent status bar at the bottom of Claude Code, with everything you actually want to see during a session:

Model: Opus 4.6 | /home/user/project | Session: 1h23 | Cost: $1.45
Context: 35% | 70k/200k tokens | 42k consumed
5h: $1.45/$5.00 ▓▓▓▓▓▓▓▓▓▓░░░░░░░░░░ 48% | Reset 2h13 | Weekly: ▓▓▓░░░░░░░ 28%

Model, CWD, session duration, cumulative cost, context usage, 5-hour rate limit window with progress bar and reset countdown, weekly quota. Cached every 5 minutes to avoid rate-limit hits, with a 24-hour stale window and 429 backoff.

Cross-platform notifications

Claude notifies you when it finishes a turn or is waiting for your input — so you can tab away without missing the moment it needs you.

PlatformAudioVisual
WindowsSystemSoundsOrange taskbar flash (FlashWindowEx)
macOSafplayNative notification (display notification)
Linuxpaplaynotify-send desktop notification

Powered by hooks/notify.js, a single Node.js script that Claude Code runs natively. Zero setup.

Screenshot → Claude Code

/codebloom:hello starts a watcher on your screenshots folder. Take a screenshot → the path is automatically copied to your clipboard → paste it into Claude Code to send the image. No save dialog, no drag-and-drop, no friction.

WordPress zip builder

A Node.js cross-platform packaging script (hooks/wp-pack.js) that handles PowerShell Compress-Archive on Windows and zip on Unix. It auto-detects plugin/theme headers, bumps version, cleans old zips via fs.unlinkSync (zero rm permission prompts during packaging), and verifies the final zip before handing it back.

Philosophy

  • Karpathy minimalism — three similar lines beat a premature abstraction. If 200 lines could be 50, rewrite. No abstractions for single-use code. No features beyond what was asked.
  • Zero invention — if a path, function, or API wasn't confirmed by a tool (Read, Grep, Glob, Bash, WebFetch), it doesn't get cited. Hallucinations are the fastest way to lose trust — especially in agent pipelines where downstream systems break on fake values.
  • Trace-test — every modified line must be justifiable by the user's request. Drive-by refactors are reverted on sight.
  • Anti-slop — UI output is distinctive: Fraunces or Instrument Serif, not Inter everywhere. Earth tones, not indigo-violet gradients. No glassmorphism. No bg-indigo-500 buttons by default.
  • User override — every rule bends to explicit user instructions. The plugin guides the default behavior, never fights you.
  • Skills over CLAUDE.md bloat — your CLAUDE.md stays under ~120 lines (warns past 150, alerts past 200). Contextual knowledge lives in skills that auto-load, not in a bloated instruction file the model eventually ignores. This follows Anthropic's official best practices.

Requirements

  • Claude Code installed
  • Git configured
  • Node.js (bundled with Claude Code — powers the cross-platform hooks)

Install

/plugin marketplace add vendeesign/codebloom
/plugin install codebloom@codebloom

Then in any project:

/codebloom:setup

Update

/plugin marketplace update codebloom
/plugin update codebloom@codebloom

Then in each project (once):

/codebloom:update

/codebloom:hello tells you when a new version is available on the marketplace.

Contributing

Commands, skills, and agents are Markdown files with YAML frontmatter. Easy to read, easy to edit, easy to fork. See CONTRIBUTING.md.

License

MIT — free to use, modify, distribute, fork.

Support

If Codebloom saves you hours of work every week and you want to keep it growing:

Solana (SOL): CNJ81Uz9mjeudEcV2xcqPzwT9WPDLB3sifjfpLcbSWzw