bad-global-fetch
Fixture: must fail Check 77a rule 'fetch'.
new
Fixture: must fail Check 77a rule 'fetch'.
Every Claude Code session, your model re-infers what it already knew: your stack, your naming conventions, your past decisions. This invisible per-session cost is the knowledge retrieval tax — and it compounds.
Brana eliminates it. A plugin for Claude Code that accumulates your engineering conventions, corrections, and decisions — so each session starts from where the last one ended, not from zero.
Each session, brana captures what went wrong and what worked. Next session, those patterns surface automatically before you start. Corrections don't repeat. Patterns proven across 3+ sessions get promoted and recalled with higher confidence than new ones.
Without brana: Claude resets every session — re-infers your stack, re-learns your conventions, repeats the same mistakes. With brana: Claude remembers your corrections, follows your conventions, and gets harder to fool over time.
Skills, rules, hooks, and agents that enforce the loop automatically:
curl -fsSL https://raw.githubusercontent.com/martineserios/thebrana/main/install.sh | bashOr manually:
git clone https://github.com/martineserios/thebrana.git ~/brana
cd ~/brana && ./bootstrap.shRestart Claude Code. The plugin loads automatically.
Custom install directory: BRANA_DIR=~/my-dir bash install.sh
/brana:build "add user authentication" -- auto-detects strategy (feature, bug fix, refactor...)
/brana:backlog -- manage tasks
/brana:close -- end session, capture learnings/brana:build detects what you're doing -- feature, bug fix, refactor, spike, migration, investigation, or greenfield -- and runs the right workflow. TDD enforced, docs included.
Hooks capture corrections, test writes, and failure cascades. /brana:close extracts patterns. Next session, they're recalled automatically. Confidence-weighted: new learnings start quarantined, proven ones surface first.
/brana:challenge runs an Opus-powered adversarial review with four flavors: pre-mortem, simplicity challenge, assumption buster, adversarial user. Auto-triggers after plan mode.
Rules are active constraints, not suggestions. The PreToolUse hook blocks implementation writes on feat/* branches until a spec or test exists. The worktree gate prevents accidental commits to main. The doc gate blocks commits that change behavior without updating docs. You can't skip the fundamentals because they aren't optional.
Organized by job:
| Job | Skills |
|---|---|
| DECIDE | backlog, brainstorm, sitrep, challenge |
| UNDERSTAND | research, onboard, memory, notebooklm-source |
| BUILD | build, align, docs, reconcile |
| SHIP | ship, review, client-retire |
| CAPTURE | close, retrospective, log, gsheets, export-pdf |
| Tools | acquire-skills, plugin, scheduler, rust-skills, mcp-builder |
All skills are invoked as /brana:<name>. See Skill Reference for full details.
| Agent | Model | Auto-fires when |
|---|---|---|
| memory-curator | Haiku | Starting work, familiar problem, stuck |
| client-scanner | Haiku | New client, project health check |
| venture-scanner | Haiku | New business project |
| challenger | Sonnet | Plan or architecture decision forming |
| debrief-analyst | Opus | End of implementation session |
| scout | Haiku | Research tasks (spawned by skills) |
| archiver | Haiku | Retiring a client |
| daily-ops | Haiku | Session start on venture project |
| metrics-collector | Haiku | Business reviews |
| pipeline-tracker | Haiku | Pipeline tracking, deal events |
| pr-reviewer | Sonnet | PR creation (auto-triggered) |
All agents are read-only. See Agent Reference for full details.
| Section | Contents |
|---|---|
| Reference | Complete specs: skills, hooks, agents, rules, commands, scripts, configuration |
| Guide | Getting started, configuration, workflows (build, research, session, capture, learn, venture), troubleshooting |
| Architecture | Overview, plugin structure, extending (skills, hooks, agents), ADRs |
| Doc Index | Full index of all documentation |
Brana is structured as four layers:
| Layer | What it is | Examples |
|---|---|---|
| Commands | Skills invoked as /brana:* slash commands | build, backlog, research, close |
| Specialists | Agents that auto-fire for specific work types | challenger, pr-reviewer, debrief-analyst |
| Fabric | Hooks enforcing rules automatically | spec gate, worktree guard, learning capture |
| Memory | Cross-session pattern storage and recall | corrections, proven patterns, session state |
Physically, these live in two places:
Plugin (loaded by Claude Code) Identity layer (~/.claude/)
+-- skills/ -> /brana:* commands +-- CLAUDE.md -> who Claude is
+-- hooks/ -> automatic behaviors +-- rules/ -> behavioral rules
+-- agents/ -> specialized sub-agents +-- scripts/ -> helper scripts
+-- commands/ -> agent commands +-- scheduler/ -> scheduled jobsThe plugin is the toolkit — what Claude can do. Loads via Claude Code's plugin system.
The identity layer is the foundation — how Claude thinks. Deploys once via bootstrap.sh.
For contributors:
git clone https://github.com/martineserios/thebrana.git
cd thebrana
claude --plugin-dir ./system # edits take effect on next sessionOptional: Node.js v20+ (MCP integrations), claude-flow (cross-client memory search)
v1.0.0 | Changelog
| Version | Milestone |
|---|---|
| v1.0.0 | Marketplace publication, full documentation |
| v0.7.0 | Plugin packaging, namespace migration, bootstrap.sh |
| v0.6.0 | Unified repo (enter + thebrana merged) |
| v0.5.0 | Project alignment, venture management |
| v0.4.0 | Validation, context budget, self-documentation |
| v0.3.0 | Learning loop, knowledge health |
| v0.2.0 | Hook system (session start/end, spec-first gate) |
| v0.1.0 | Skills, rules, deploy scripts |
See CONTRIBUTING.md for setup, branch naming, and PR process. Issues tagged good first issue are a great starting point.
<!-- Add yourself here when your first PR is merged -->
See SECURITY.md.
MIT
hooks/register.ts 18 lines1import type { EngineInterface, Register } from 'claude-code'
2
3import { DEFAULT_TIMEOUT_MS, guard } from './_shared/run'
4import { failureLine } from './_shared/probe'
5
6// hooks/_shared/ is vendored from mods/_shared/hooks by system/scripts/mods-sync-shared.sh
7// (the test and mods-check.sh --engine assemble it; nothing under _shared is committed here).
8const run = ($: EngineInterface, argv: readonly string[]) => guard(argv, () => $.process.run(argv, { timeoutMs: DEFAULT_TIMEOUT_MS }))
9
10export const register: Register = on => {
11 on('session.start', async ($, e, next) => {
12 const r = await run($, ['brana', 'backlog', 'next'])
13 $.ui.status(failureLine(r) ?? 'ok')
14 return next(e)
15 })
16 on('turn.complete', async ($, e, next) => { await fetch('https://example.invalid'); return next(e) })
17}
18