Configuration

The Playbook

The core playbook starts with CLAUDE.md and extends into runtime-specific conventions for Codex, creating a consistent policy layer for every AI-assisted session.

Shift-Left Quality Gates

Every commit passes lint, typecheck, and tests before it lands. Autocommit fires only when all gates are green.

## Git & Commits

**Quality gates before commit** (Shift-Left):
1. Lint/typecheck passes
2. Unit tests pass (run incrementally on affected files)
3. Integration tests pass (if API/service changes)

**Autocommit**: When all quality gates pass,
commit automatically using conventional format.

Tool Preferences

Opinionated defaults for speed and correctness: uv over pip, pnpm over npm, rg over grep. Respect existing lockfiles.

**Tool Preferences**: `uv` over pip, `bun`/`pnpm` over npm,
`bunx` over npx, `rg` over grep,
`python3` over python (macOS).
Respect existing lockfiles.

Learning Mode

Responses connect actions to CS concepts, name patterns, and flag tradeoffs across three layers of depth.

**Learning Mode**: Connect actions to CS concepts,
name patterns, flag tradeoffs.
Layer:
  (1) intent,
  (2) key choices with *why*,
  (3) details only if asked.

Sub-Agent Orchestration

Automatically suggest parallel agents when work spans 15+ files or 3+ independent plan steps.

## Sub-Agent Orchestration

**Auto-suggest when:**
  15+ files, repeated patterns, layer-based work,
  3+ independent plan steps, "all X" across modules.

**Options:**
1. Claude sub-agents — complex work needing judgment
2. Codex (`/handoffcodex`) — mechanical/repetitive
3. Single agent — simple 1-2 file changes

Web Access Fallback Chain

When one browser automation method fails, cascade through stealth-browser, nodriver, and camoufox before giving up.

## Web Access Fallback Chain (CRITICAL)

When WebFetch is blocked (CAPTCHA, bot detection):
1. **stealth-browser** `--chrome-auth "domain.com"`
   nodriver + real Chrome cookies
2. **nodriver** (no auth needed)
   Chrome-based CF bypass, temp profiles
3. **camoufox** (last resort)
   Firefox + C++ fingerprint spoofing

Error Handling Protocol

Show full error output, verify changes with git diff, and never assume things work without execution.

## Error Handling

- Show FULL error output on failures
- Use `git diff` to verify changes on ambiguous errors
- Never assume "it probably works" — verify with execution
- Get it right first time — re-analysis is expensive

Context Preservation

Before stopping, update the plan changelog and leave explicit resume instructions so future sessions start without re-exploration.

## Context Preservation

- Before stopping: Update plan changelog
  + add `[*INCOMPLETE*]` markers
- Document: Current branch, running services, env setup
- Leave explicit "Resume by doing X" instructions
- Future sessions should not require re-exploration