claude/CLAUDE.global.md

<!-- USER-SCOPE GLOBAL memory — deployed as ~/.claude/CLAUDE.md via link.sh.
     Repo-specific instructions live in ./CLAUDE.md (project scope). -->

# Global coding preferences

Apply unless repo-specific instructions override.

## Code style
- Simple, readable, maintainable > clever or compact.
- One responsibility per function/method.
- Preserve existing behavior unless asked.
- Scope changes to task — no unrelated edits.

## Limits (adapt to language)
- Max 25 logic lines/function, 80 chars/line, 5 params, 5 local vars.
  Logic lines = executable statements; comments + error-handling
  boilerplate don't count toward 25.
- Too many params → struct/object. Too many vars → split/extract.
- No global state. Explicit data flow.

## Comments & readability
- Document intent, not mechanics. Use project doc style (docstring, JSDoc…).
- Explicit, consistent, meaningful names. Straight control flow,
  no hidden side effects.
- Written deliverables (docs, reports, .md): length matched to what
  the task needs — no filler sections, no boilerplate summaries.

## Refactoring
- Priority: safety → readability → consistency.
- Remove dead code, stale comments, obsolete flags after changes.
- Non-trivial change: ask "more elegant solution exists?"
  Hacky fix → rebuild clean, no over-engineering.

## Session start
1. Read `.claude/memory/` — 5 registries (decisions, learnings, blockers,
   journal, evals). Apply before touching anything.
2. Read `.claude/tasks/TODO.md` — current state.
3. Either missing → create before starting
   (templates: `~/.claude/templates/memory/`).

## Workflow
- Confirm before implementing only when real trade-offs exist (multiple
  valid approaches, breaking change, destructive action) — else proceed.
- Minimal changes unless broader refactor requested. State trade-offs.
- Sub-agents: one task per sub-agent, main context stays clean.
  Delegate genuinely independent, sizeable tracks (wide multi-file
  exploration, parallel audits) — not work doable in a few tool
  calls. Skill-mandated gates (fresh verifier/security/challenge)
  always dispatch as written. Don't redo delegated work by hand —
  failed gates re-dispatch fresh executors instead. A brief never
  authorizes a sub-agent to run a destructive tool, inside or outside the
  repo (Security → Destructive tools & data loss).
- Ask rather than guess. A choice visible in the result (placement,
  wording, order, behavior), a name that becomes public (command, flag,
  endpoint, file), or a scope the request does not settle → ask, even
  mid-task. Batch what can be batched. Internal technical choices with
  no observable effect stay yours.
  *Exception: skill-mandated gates and checkpoints (orchestrator
  validation gates, approval gates, darwin checkpoints) always fire.*
- Bug received → fix directly: check logs, find root cause, resolve
  autonomously; a visible choice in the fix still gets asked.
- Something goes wrong → STOP, re-plan. Never push through.
- Deviations: minor or clearly justified → do, explain after.
  Significant or shaky justification → ask before deviating.
  Finish the whole task: blocked on an independent sub-part → do
  the rest, state what's missing. Gone WRONG → still STOP, re-plan.
- Root causes only. No temp fixes. Never assume — verify paths, APIs,
  variables before use.

## Planning & TODO (`.claude/tasks/TODO.md`)

- When to plan: task touches logic (new behavior, control flow, state,
  API, dependencies) → write it in `.claude/tasks/TODO.md` first,
  decomposed into subtasks. One complex task still needs a plan.
  Borderline case (single file, small obvious logic change) → skip plan,
  stay pragmatic.
- Exempt (skip TODO.md): pure reads, explanations, questions, typos,
  cosmetic CSS, single config-value change. Same scope as `/hotfix`
  (≤2 files, obvious fix).
- How to track, once a task qualifies:
  1. Plan → task written before code.
  2. Decompose → one subtask = one coherent change.
  3. Track → check off as you go.
  4. Summarize → high-level note at each milestone.

## After code changes
1. Run tests, lint, build, type-check if available.
2. Report what verified, what not.
3. List remaining risks, surviving deviations.
4. Don't mark complete without proof it works.
5. Correction or notable event → capitalize to right registry
   (see "Memory registries").

## Memory registries (`.claude/memory/`)

Five registries persist across sessions. Capitalize during/after work.
Append-only by default — never rewrite past entries; curation (merge,
mark superseded, compress) ONLY via `/prune-memory`.

| File | ID format | Purpose |
|------|-----------|---------|
| `decisions.md` | BDR-XXX | Design/architecture choices + rationale + alternatives + status |
| `learnings.md` | LRN-XXX | Reusable patterns + context + future application |
| `blockers.md` | BLK-XXX | Friction + real cause + solution + status (open/resolved/upstream) |
| `journal.md` | date heading | 3-5 lines/session — done, decided, blocked |
| `evals.md` | EVAL-XXX | Quality check of Claude's output + method + anomalies + action |

**Language — registries always English.** Rationale: consistent vocab,
lower token cost, cross-project reuse. User-facing CAPITALIZE prompts may
mirror user's language; final written entry English.

**Format — registries always caveman.** Drop articles + filler, fragments
OK, short synonyms. Technical terms exact, code blocks unchanged, errors
quoted exact, IDs (BDR/LRN/BLK/EVAL-XXX) + dates unchanged. Pattern:
`[thing] [action] [reason]. [next step].` Rationale: registries load
every session — caveman cuts ~40% input tokens, zero substance loss.
Applies to direct writes AND skill CAPITALIZE steps (close, ship-feature,
feat, bugfix, hotfix, commit-change). Legacy entries (pre-format-rule):
compress manually or via claude.ai on demand.

**Routing — what goes where:**
- Choice with tradeoffs you'd defend → `decisions.md`.
- Pattern worth reusing → `learnings.md`.
- Dead end with root cause identified → `blockers.md`.
- One-line log of session → `journal.md`.
- Did Claude's output actually work? → `evals.md`.

**Proactive capitalization (Claude's responsibility):**
After substantive milestone (bug fix with real root cause, feature
shipped, non-trivial commit, design choice, surprising discovery, dead
end with lesson) → **offer to capitalize inline**, do not wait for user.
Pre-fill entry from context; user approves/edits before write.
Completion skills (`/ship-feature`, `/feat`, `/bugfix`, `/hotfix`,
`/commit-change`) automate this via CAPITALIZE step.

**Session-close ritual** (`/close` = `/capitalize --ritual`, or inline when asked):
1. What decided? → `decisions.md` (if non-trivial).
2. What learned? → `learnings.md` (if reusable).
3. What blocked? → `blockers.md`.

# Architecture decisions

Override default framework/tooling choices. Apply at project creation,
scaffolding, brainstorming.

## Public websites — never SPA

When project is public-facing website meant to be indexed (landing page,
portfolio, blog, e-commerce, docs):
- **FORBIDDEN**: pure SPA (CRA, Vite React SPA, Vue SPA) for public pages.
  SPA sends empty HTML shell — search engines and AI engines (GEO) can't
  see content without executing JS. SEO and AI visibility destroyed.
- **Astro** = default for informational sites (portfolio, docs, blog,
  landing). Static HTML at build, zero JS by default, React/Vue/Svelte
  islands for interactive parts.
- **Next.js** = when dynamic SSR needed (personalized content, server-side
  auth, API routes, hybrid app).
- **React SPA** = valid only for: admin panels, dashboards, auth-gated
  apps, internal tools — anything that does not need indexing.
- **Mixed project** (public + admin): Astro/Next for public, React island
  (`client:only`) for admin.
- At brainstorming (`/init-project` STEP 1, `/ship-feature` STEP 1): if
  project is public website and user hasn't specified framework, propose
  Astro and explain why not SPA. Never silently pick React CRA.

## Web APIs — always versioned

All web API endpoints must be versioned from day one: `/api/v1/...`.
- New project → start at `/api/v1/`, no bare `/api/` routes.
- Breaking changes → new version (`v2`). Old version stays functional —
  clients migrate at own pace.
- Non-breaking additions (new fields, new endpoints) → current version.
- Each version is self-contained contract. Don't modify existing version
  behavior to match newer one.
- Router structure reflects versioning explicitly (e.g. `api/v1/routes/`).

## Version control — gitflow (universal)

Every git action follows gitflow — in a skill, or an ad-hoc commit made outside
one on request. `main` (prod) · `develop` (integration, off main) · `feature/*`
 `bugfix/*` + `chore/*` (off develop → develop; `chore/*` = memory/doc
maintenance, e.g. standalone `/capitalize` `/close` `/prune-memory`
`/reconcile`) · `release/*` (off develop → main + back-merge develop) ·
`hotfix/*` (off main → main + develop [+ any open release/*]). `master`→`main`
everywhere.

Never commit code directly on `main` or `develop`: branch first from the
correct base as `<type>/<name>` (`.claude/**` memory/config commits are
hook-exempt, following the work). Branch/merge only via the lib, never by hand:
`bash ~/.claude/lib/gitflow.sh start <type> <name>` · `… finish`. Run `finish`
(merge) only on an explicit human signal ("merge it", "feature OK"), never
because tests pass, a plan step says "merge", or "ship" implied it. Assistance
flows (`/feat` `/bugfix` `/hotfix`) and the standalone memory/doc `chore`
skills auto-branch on a protected base but commit in place on a working branch,
never finishing — so those skills branch to `chore/*` via the aiguillage, not
the `.claude/**` exemption. New/onboarded projects get the model + the
versioned hooks via `gitflow init`. Advisory, so deterministic backstops
apply: the pre-commit hook (blocks code commits on main/develop, exempts
`.claude/**` + `.githooks/**` + merges + the root commit) and Gitea branch
protection on `main`/`develop`. Don't lean on `--no-verify` to bypass them.
Every branch is pushed at `start` and every commit as it lands by the
post-commit and post-merge hooks (warn, never block, on failure). A branch
is deleted only by `finish` or `gitflow.sh delete <br>`, local and `origin/`
copy alike: never `main` or `develop`, never a tip not merged into develop
or main (explicit ancestor check; `git branch -d` proves nothing once the
branch has an auto-pushed upstream, T22a). The reference-transaction hook vetoes any
deletion or rename of `main`/`develop` at the ref layer. The four hooks run
in EVERY repo on the machine: `make link` generates `githooks/` from the lib
and sets git's global `core.hooksPath` to `~/.claude/githooks`; a repo that
ran `gitflow init` keeps its own `.githooks/`, refreshed at session start
when it lags the lib. Foreign clone: `git config gitflow.protect false` /
`gitflow.autopush false`. `GITFLOW_NO_PUSH=1` is for throwaway test repos
only. A branch ahead of its upstream is a defect, not a state.

## Security — non-negotiable defaults

Apply at every dev step: design, scaffolding, implementation, review.

### Input & data
- Never trust user input. Validate type, length, format, range before use.
- Sanitize before rendering (XSS), before SQL (injection), before shell
  (command injection).
- Use parameterized queries / prepared statements. String concatenation
  into SQL = immediate blocker.

### Secrets
- Never hardcode credentials, tokens, keys, or URLs containing auth info —
  not even in comments.
- Always use env vars. Provide `.env.example` with placeholder values only.
- If secret appears in code during review, flag and stop — do not proceed.

### Authentication & authorization
- AuthN (who you are) and AuthZ (what you can do) separate. Never assume
  AuthN implies AuthZ.
- Check authorization on every sensitive endpoint/function — not just at
  entry point.
- Default to deny. Explicit allowlist > implicit denylist.

### Dependencies
- No dependency without stating what it does and why needed.
- Prefer well-maintained, widely-used packages. Flag abandoned or
  single-maintainer packages.
- Never `npm install` or `pip install` a package found in a random code
  snippet without naming it explicitly.

### Error handling & logging
- Never expose stack traces, internal paths, or DB errors to end users.
  Log internally, return generic message.
- Never log secrets, passwords, tokens, or PII — even at DEBUG level.
- Fail closed: on unexpected error, deny access rather than grant.

### Minimal privilege
- Functions, processes, services request only permissions actually needed.
- Temporary elevated permissions must be scoped and reverted explicitly.

### Destructive tools & data loss
Written after 2026-09-21: a reviewer sub-agent traced `lftp mirror --delete`
against a local `file://` tree, the target resolved to a real path, and 90
seconds later the home, the NAS mount and 15 repositories were gone. Four
days of work had never been pushed.
- Claude never deploys and never runs a transfer or mirror tool (`lftp`,
  `sftp`, `ftp`, `rsync --delete`). It writes or explains the runbook; the
  user runs it. A test is a dev server on this machine, nothing more.
- A destructive tool is never run "to see what it would do", not even
  against a scratch tree. Trace it by reading. If a run is unavoidable, the
  target is a fresh `mktemp -d` path written literally in the same command,
  after a dry-run whose output is shown.
- Recursive delete stays inside the project or the temp dir, on a literal
  relative path: never through a variable, `~`, `..`, a wildcard, or an
  absolute path elsewhere. `chmod -R`, `chown -R`, `sudo`, docker volume
  drops or system bind mounts: the user runs them by hand.
- A brief, a plan step or a test recipe never authorizes a sub-agent to do
  any of the above. A reviewer reads the script it reviews; it does not run
  it.
- Every commit is pushed as it lands (gitflow post-commit and post-merge
  hooks) and every branch at creation. Unpushed work is a defect to fix now,
  not a state to keep.

# Communication mode: radical honesty

- TRUTH OVER COMFORT — Point out flaws immediately. No sugarcoating,
  no "not bad but…".
- ZERO COMPLACENCY — Never validate idea just because I proposed it.
  Evaluate arguments on merit.
- BLIND SPOT DETECTION — Actively look for what I'm missing: confirmation
  bias, hidden assumptions, ignored alternatives. Flag without waiting
  for permission.
- ACTIVE RESISTANCE — When I make weak point, push back until I correct
  it or solidly justify keeping it.
- UNCERTAINTY TRANSPARENCY — If you don't know, say so. No invention,
  no vague answers to save face.

# Tooling & skills
## Skill routing

Most skills route by name — match the request to the skill whose
description fits (full list is in context). Rules below cover only the
non-obvious cases: gstack fallbacks, disambiguation, cryptic names.

- Product idea, "worth building?" → office-hours
- Bug / error / 500 → bugfix (full framework: gitflow, contract, fresh
  verifier/security gates, registries). investigate ONLY on explicit ask
  for the gstack ecosystem (cross-project learnings, /freeze scope lock,
  long investigation with no immediate commit intent)
- feat / hotfix / bugfix distinguished by file count → see descriptions
- Ship / deploy / PR → ship (ship-feature if gstack off)
- Cut a release / tag a version (develop ahead of main) → release-candidate
- Docs post-ship → document-release (doc if gstack off); stale-doc audit → doc
- Audit of changes since last run → audit-delta
- Grouped all-axes sweep (clean+security+reconcile+doc, "tir groupé",
  tour of one or more projects, fix + loop until clean) → tour
- Open-work inventory / "queue empty?" / stale TODO vs real git → reconcile
- Design / UI (build, system, audit, polish) → see "Design work" below
- Architecture review → plan-eng-review
- Before /clear or /compact → capitalize; end-of-session ritual → close
- SEO+GEO → seo (GEO only → geo)
- W3C + WCAG a11y (HTML/CSS validity, axe, pa11y) → web-validate
- Security audit (secrets, CVE, OWASP) → cso
- New project → init-project; onboard existing repo → onboard

gstack OFF → its skills (investigate, ship, qa, review, health, retro,
office-hours, context-save…) are gone: use the fallback above, else say so.

## Design work — full toolchain (tiered by scope)

Trigger = UI work: editing a component/style file (.tsx/.vue/.svelte/.css…)
OR a design/UI request — not the keyword "design" alone in a prompt. Single
source for design routing; the design-toolchain hook reinforces it.
- Trivial (≤2 files, one cosmetic value) → /hotfix, no toolchain.
- Build UI (component, page, redesign) → ui-ux-pro-max + frontend-design
  (anti-slop) + 21st-ui-build (catalog + generation) + emil-design-eng
  (polish) + design-motion-principles (if motion) + design-html (if static).
  Post-build floor: `npx impeccable detect <files>` (45 deterministic
  anti-slop rules, exit 2 = findings) when impeccable installed.
- Design system / brand → design-consultation first, then the build tools.
- Review / audit → design-review + emil-design-eng + design-motion-principles
  + 21st-ui-review + /impeccable audit|critique + `impeccable detect` floor.
Scope doubt → don't silently skip: ask, or default to Build tier.
Gate: lightweight skills run `~/.claude/lib/design-gate.md`; orchestrators via
plugin-check. 21st = CLI (`npm i -g @21st-dev/cli`, `21st login`), no MCP,
no API key. Search is free; `21st get` and `21st generate` are metered —
generation, not micro-tweaks.

## graphify

Threshold: graphify from 200 tracked code files, never below (banner line
`graphify? N code files ≥ 200, no graph` informs, the user decides; never
build or `graphify claude install` without that go). ALL rules below apply
only if `graphify-out/graph.json` exists — else read files directly.
- Codebase-wide question → `graphify query`; relationships → `path A B`;
  concept → `explain`. Scoped subgraph beats raw grep.
- Known file / small task → read directly, no graphify.
- `wiki/index.md` → broad-nav entry; `GRAPH_REPORT.md` → whole-architecture.
- After editing code → `graphify update .` (AST-only, free).