<div align="center">

<img src="assets/gabe-lens-hero.png" alt="gabe-suite" width="600">

Gabe Suite

Development suite for Claude Code and Codex

Skills, commands, and hooks for understanding, reviewing, deciding, and shipping — with a knowledge system (KDBP) that tracks values, decisions, and deferred work across sessions.

Not a prompt template. Built from empirical self-observation.

</div>

Name note. The project/suite is Gabe Suite. One of the skills inside it is called Gabe Lens (invoked via /gabe-lens) — the cognitive-translation layer. They're different things: the suite contains the skill. Previous name for the suite was "Gabe Lens" — this repo was renamed to avoid collision.

The Suite

Skills (11)

Command Wrappers (20)

The installed command surface includes direct skill commands plus the full KDBP lifecycle from project init through ship:

Both Claude Code and Codex install five thin lifecycle command-wrapper skills (gabe-next, gabe-plan, gabe-execute, gabe-commit, gabe-push). Claude Code also has native slash commands; the wrappers preserve skill-style handoff parity and load the same command specs mirrored under each local home.

KDBP System

The Knowledge, Decisions, Behavior, and Pending system tracks project state across sessions:

.kdbp/
├── BEHAVIOR.md      # Project name, domain, maturity, tech stack
├── VALUES.md        # 3-7 project-specific values (checked at commit)
├── DECISIONS.md     # Append-only architecture decision table
├── PENDING.md       # Deferred items with priority and escalation
├── LEDGER.md        # Session checkpoint history (auto-appended)
├── MAINTENANCE.md   # Quarterly human checklist
├── PLAN.md          # Active plan (written by /gabe-plan)
├── KNOWLEDGE.md     # Human knowledge map (managed by /gabe-teach)
└── archive/         # Archived plans (completed_, defer_, cancelled_)

User-level values at ~/.kdbp/VALUES.md apply across all projects.

For complex plans, /gabe-plan may also create a self-contained HTML review artifact under docs/gabe/plans/.... That HTML is the human-facing entrypoint for dense decisions, diagrams, phase maps, and bottleneck summaries; .kdbp/PLAN.md, .kdbp/DECISIONS.md, and .kdbp/LEDGER.md remain canonical for automation and lifecycle state.

Hooks (6, installed to ~/.claude/settings.json)

Workflows

Documentation

Install

git clone https://github.com/khujta/gabe-suite.git
cd gabe-suite
./install.sh              # Install skills, commands, templates, and docs
./install.sh --dry-run    # Show what would be done
./install.sh --uninstall  # Remove everything

After install, initialize a project:

/gabe-init [project-name]

This creates .kdbp/, installs hooks, and asks about project type and maturity.

Gabe Lens (skill)

Everything from here through "Cognitive Suits" describes the /gabe-lens cognitive-translation skill — the single component that shares its name with the old suite. Other skills (/gabe-review, /gabe-roast, /gabe-align, etc.) are documented further below or in their respective SKILL.md files.

See it in action

Ask /gabe-lens enforcement tiers and get this:

┌─── GABE BLOCK: Enforcement Tiers ──────────────────────┐
│                                                        │
│  THE PROBLEM                                           │
│  Rules written in docs get ignored under fatigue and   │
│  context loss. 19 files exceeded the 800-line limit    │
│  despite the limit being documented everywhere.        │
│                                                        │
│  THE ANALOGY                                           │
│  Think of it as gravity vs. posted speed limits.       │
│  Gravity (Tier 1 hooks) works whether you're paying    │
│  attention or not — drop a ball, it falls. Speed       │
│  limits (Tier 3 docs) only work if the driver reads    │
│  the sign AND chooses to comply. Tier 2 (workflows)    │
│  is like a speed bump — it slows you down IF you       │
│  drive over it, but you can take a different road.     │
│                                                        │
│  THE MAP                                               │
│                                                        │
│    Tier 1: GRAVITY ══════════════════► Always works    │
│    (hooks)    PreToolUse ─→ fires every edit           │
│               pre-commit ─→ fires every commit         │
│                                                        │
│    Tier 2: SPEED BUMPS ─ ─ ─ ─ ─ ─ ─► Works if used    │
│    (workflows) /review ─→ only if invoked              │
│                                                        │
│    Tier 3: POSTED SIGNS · · · · · · ·► Often ignored   │
│    (docs)     CLAUDE.md rules ─→ lost after compaction │
│                                                        │
│  CONSTRAINT BOX                                        │
│    IS:      A reliability classification for rules     │
│    IS NOT:  A quality judgment (Tier 3 rules aren't    │
│             bad rules — they're just badly placed)     │
│    DECIDES: Where to invest enforcement effort —       │
│             convert Tier 3 lessons into Tier 1 hooks   │
│                                                        │
│  ONE-LINE HANDLE                                       │
│  "Hooks are gravity — docs are speed limit signs"      │
│                                                        │
│  SIGNAL: Quick check ✓                                 │
│  (The concept is intuitive once you see the tiers.     │
│   Don't overthink — the tier system IS the insight.)   │
└────────────────────────────────────────────────────────┘

That one-line handle — "Hooks are gravity — docs are speed limit signs" — stuck for weeks. The original 3-paragraph explanation didn't last a day.

Usage

#### Full block (default)

/gabe-lens [concept or question]

All components: problem, analogy, map, constraint box, one-line handle. ~200-350 tokens.

#### Brief

/gabe-lens bf [concept]

Constraint box + one-line handle only. ~40-80 tokens. For previously introduced concepts.

#### Oneliner

/gabe-lens ol [concept]

Just the memorable phrase. ~5-15 tokens. For compaction handoffs or re-anchoring.

#### Annotate a document

/gabe-lens an [file-path]

Reads a file and produces a companion with Gabe Blocks for the 3-5 most critical concepts.

Compression modes

Analogy domains

Physical systems you can visualize in 3D, in preference order:

1. Mechanical — gears, valves, pulleys
2. Fluid dynamics — pressure, flow, reservoirs
3. Optics — lenses, mirrors, refraction
4. Chemistry — reactions, catalysts, equilibrium
5. Electromagnetism — fields, circuits, charges
6. Thermodynamics — heat, entropy, engines
7. Biology — cells, ecosystems, evolution

If no good physical analogy exists, the skill says so explicitly rather than forcing a weak metaphor.

Cognitive Suits

Not everyone thinks the same way. The Gabe Lens skill adapts its output to match how your brain works.

#### Calibrate

/gabe-lens-calibrate

Presents the same concept in all 4 suits. Pick the one that clicks. Your choice is saved globally and used for all future /gabe-lens output.

To reset to default: /gabe-lens-calibrate reset

Gabe Roast (skill)

Adversarial gap review. Adopts a perspective (architect, UX designer, security auditor, etc.) and attacks a target to find what's missing, broken, or risky.

See it in action

Ask /gabe-roast "UX Designer" MOCKUP-PLAN.md and get:

GABE ROAST: MOCKUP-PLAN.md
Perspective: UX Designer

═══ MVP ════════════════════════════════════════════════

CRITICAL

  M1
  **Gap:** The plan starts with 12 isolated screen mockups
  but defines no user flow diagrams. Each screen is designed
  in a vacuum.
  **One-liner:** "Building rooms before drawing the hallways"
  **Effort:** M (confident)
  **Lose:** Every screen gets reworked once flows reveal they
  don't connect.

HIGH

  M2
  **Gap:** Component library is extracted BEFORE screens exist.
  **One-liner:** "Packing a suitcase before knowing the destination"
  **Effort:** S (confident)
  **Lose:** Component library gets rebuilt from scratch once
  real screens reveal actual patterns.

────────────────────────────────────────────────────────
TOTAL: 2 gaps — 1 critical, 1 high

Usage

Both inputs are required — if either is missing, the skill asks before proceeding.

/gabe-roast [perspective] [target]

Brief mode (table format):

/gabe-roast bf [perspective] [target]

Classification

Gaps are grouped by maturity level (MVP / Enterprise / Scale), then by importance (Critical / High / Medium / Low). Each gap includes a Gabe Lens one-liner, effort estimate with confidence, and the cost of inaction.

Gabe Assess (skill)

Rapid change impact assessment. Pauses before an "obvious yes" to surface what a proposed change actually means before you commit.

See it in action

Someone proposes fixing CORS on a shared staging bucket. Before saying yes:

/gabe-assess Fix Storage CORS for staging scan testing

GABE ASSESS: Fix Storage CORS for staging scan testing
Context: blocker

D1 BLAST RADIUS: External
   Bucket is shared with Gustify. CORS changes affect all apps.

D2 MATURITY SCOPE: MVP
   Current: MVP. Proposed: MVP-appropriate config change.
   Match — but shared infra elevates risk.

D3 PREREQUISITES:
   - Verify Gustify doesn't have its own CORS config
   - Check who deploys staging rules (INC-001)

D4 ALTERNATIVES:
   [A] Do nothing — defer E2E, unit tests already prove it
   [B] Minimal    — gsutil cors set + allowedEmails entry (S)
   [C] Proper     — combined rules deploy from Gustify repo (M)
   [D] Workaround — test via admin script, bypass client (S)

RECOMMENDATION: [B] — neither change touches shared rules file
ONE-LINER: "Bucket knob and guest list — don't redecorate the shared house"

Usage

/gabe-assess [change description]           # Full assessment
/gabe-assess bf [change]                    # Brief (4 lines)
/gabe-assess il [change]                    # Inline (1 sentence)
/gabe-assess batch [change 1] + [change 2]  # Multiple changes

Assessment dimensions

Embedding in workflows

project_knowledge:
  optional:
    - "skills/gabe-lens/SKILL.md"
    - "skills/gabe-roast/SKILL.md"

One-line handles from both skills enhance compaction handoff notes by surviving context compression.

The origin story

<details> <summary>How the Gabe Lens skill — and later the whole suite — was built from a cognitive self-observation experiment</summary>

The suite started as a single skill called gabe-lens. That skill started as a personal experiment: what happens when you use AI to reverse-engineer how your own brain learns? Over time, workflow commands (/gabe-init, /gabe-commit, /gabe-plan, /gabe-execute, /gabe-push, /gabe-teach, /gabe-scope) and companion skills (/gabe-roast, /gabe-align, /gabe-assess, /gabe-review, /gabe-health, /gabe-help, plus the consulted-only gabe-docs and gabe-arch) accreted around it. The umbrella became the Gabe Suite. The origin skill kept its name.

I sat down with Claude and deliberately tried to learn a complex topic — attention mechanisms in neural networks. But the real goal wasn't understanding attention. It was watching how my mind processed the explanation, in real time, and having Claude observe and document the patterns.

What we discovered:

• I don't reach for equations — I reach for metaphors. When learning how Query/Key/Value works in transformers, I spontaneously generated analogies: spheres reflecting light onto each other, chemical reactions with temperature and state. These weren't decorations — they were my primary reasoning substrate.

• I reason top-down, not bottom-up. My mind asks "why does this exist?" before "how does it work?" Purpose first, constraints second, mechanism last.

• I learn in spirals. Constrained prototype → generalize → formalize → refine. I don't need complete understanding to start.

• I have an overthinking trap. When a correct answer comes fast, I spiral searching for hidden complexity that isn't there. The IS NOT field in constraint boxes was designed specifically to short-circuit this.

These were patterns observed during actual learning exercises, documented in real time. Once we had the cognitive profile, the next question was obvious: can we turn this into a reusable format?

The learning profile became the SKILL.md. The explanation sequence (Problem → Analogy → Code) became the Gabe Block. The overthinking trap mitigation became the constraint box. The one-liners I remembered days later became the one-line handles.

</details>

License

MIT