gitflow-test aborts on a failed mktemp or newrepo before its reset --hard; helper sources exit on failure; no lint suppression left; T19c reads a real registry; doctrine rewrapped.
17 KiB
Global coding preferences
Strict in our code (project started by the user or Claude). Foreign
code (bash ~/.claude/lib/code-origin.sh → foreign) → "Foreign
code" wins. Repo-specific instructions override both.
Foreign code: keep its style
- Existing code's style is the norm unless the user says otherwise: function granularity, file layout, naming, comment density, error handling, idioms. Write like the neighbouring code.
- Neighbours work inline → work inline: no function, helper or abstraction the file would not have written. Reuse what is in scope (variables, macros, sizeof).
- Limits become guidelines: exceed them where the file's style needs it.
- No refactor toward our norms unless asked.
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. Literal ask: button color → change the color, no theme or token system. Idea beyond scope → ask first.
- Before writing code, stop at the first rung that applies: not needed (YAGNI) → reuse what the codebase has → stdlib → platform/runtime feature → dependency already installed → one line → the minimum that works. Runs after understanding the problem, never instead of it.
- Assumed shortcut →
shortcut:comment at the site (limit + upgrade path), harvested into TODO.md so "later" stays findable.
Limits (our code: strict; foreign code: see above)
- Max 25 logic lines/function (executable statements; comments and error-handling boilerplate don't count), 80 chars/line, 5 params, 5 locals.
- Too many params → struct/object. Too many vars → split/extract.
- No global state. Explicit data flow.
Comments & readability
- Self-explanatory code: names and structure carry the meaning. Comment only what the code can't say (why, intent). Project doc style (docstring…).
- Explicit, consistent names. Straight control flow, no hidden side effects.
- Written deliverables (docs, reports, .md): length matched to the task, 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
- Read
.claude/memory/(5 registries: decisions, learnings, blockers, journal, evals) and.claude/tasks/TODO.md. Apply before touching anything. - Either missing → create it first (templates:
~/.claude/templates/memory/).
Workflow
- Confirm the approach only when real trade-offs exist (several valid approaches, breaking change, destructive action); ask on the visible, public-name and open-scope choices below; otherwise proceed. Minimal changes unless a broader refactor is requested. State trade-offs.
- Sub-agents: one task each. Delegate independent, sizeable tracks (wide
exploration, parallel audits), not work doable in a few tool calls. Ceiling:
the main loop writes no code outside a skill run, whatever the model (the
model-router guard redirects it: enter the skill it names). Skill-mandated
executors and gates (pinned executors, fresh
verifier/security/challenge) always dispatch as written, even small; a failed
gate re-dispatches a fresh executor, never redo its work by hand. A brief
never authorizes a sub-agent to run a destructive tool (Security →
Destructive tools & data loss) or to route around a guardrail: a refused
command is reported with its rule (a guard redirect naming a skill is
followed instead), never rerun through a wrapper, alias, env
file or other shell. Hermetic tests run through
make test [suite=…]only. - 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 leaves open → ask, even mid-task; batch what can be batched. Internal choices with no observable effect stay yours. Exception: skill-mandated gates and checkpoints (validation, approval, darwin) always fire.
- Bug received → fix directly: logs, root cause, resolve autonomously; a visible choice in the fix still gets asked.
- Deviations: minor or clearly justified → do, explain after; significant or shaky → ask first. Finish the whole task: a blocked independent sub-part → do the rest, state what's missing. Something goes WRONG → STOP, re-plan, never push through.
- Root causes only, no temp fixes. Never assume: verify paths, APIs, variables before use.
Planning & TODO (.claude/tasks/TODO.md)
- Task touches logic (new behavior, control flow, state, API, dependencies) → write the plan in TODO.md first, decomposed into subtasks; one complex task still needs one. Borderline (single file, small obvious change) → skip, stay pragmatic.
- Exempt: pure reads, explanations, questions, typos, cosmetic CSS, single
config value — the
/hotfixscope (≤2 files, obvious fix). - Once it qualifies: plan before code → one subtask = one coherent change
→ check off as you go → high-level note at each milestone. A plan a skill
persists (
.claude/tasks/plans/, contract) satisfies the rule; TODO.md then carries one line per run.
After code changes
- Run tests, lint, build, type-check if available. Report what was verified and what was not; list remaining risks and surviving deviations.
- Don't mark complete without proof it works.
- Correction or notable event → capitalize to the right registry.
- Rule, heading, label or threshold changed → grep every citer across
skills/agents/lib and patch them in the same commit (
make testruns the doctrine-citers census; a threshold lives in one lib file, skills call it).
Memory registries (.claude/memory/)
Five registries persist across sessions; capitalize during and after work.
Append-only, written only through bash ~/.claude/lib/memory.sh (add,
status, journal), never by Edit; curation only via /prune-memory.
| File | ID | Purpose |
|---|---|---|
decisions.md |
BDR-XXX | Design/architecture choice + rationale + alternatives + status |
learnings.md |
LRN-XXX | Reusable pattern + 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 |
Routing: a choice with trade-offs you'd defend → decisions; a pattern worth reusing → learnings; a dead end with its root cause → blockers; the session log → journal; whether the output actually worked → evals.
Always English, always caveman: drop articles and filler, fragments OK,
short synonyms; technical terms, code blocks, quoted errors, IDs and dates
exact. Pattern [thing] [action] [reason]. [next step]. Planning flows
read the registries; caveman cuts ~40% of every read, no substance lost.
Applies to direct writes and to the CAPITALIZE step of every completion
skill. Prompts to the user may mirror their language; the entry is English.
Legacy entries: compress on demand via /prune-memory.
Proactive capitalization is Claude's job: after a substantive milestone
(root-caused bug fix, shipped feature, non-trivial commit, design choice,
surprising discovery, dead end with a lesson) offer to capitalize inline,
entry pre-filled, user approves before the write; the one-line journal
entry is exempt, it logs and decides nothing. Completion skills
(/ship-feature /feat /bugfix /hotfix /commit-change) do it via
their CAPITALIZE step. Session close (/close = /capitalize --ritual):
what was decided → decisions, learned → learnings, blocked → blockers.
Architecture decisions
New project, scaffolding, stack brainstorm or whole-project rewrite: Rust
by default, a public site is never a SPA (Astro; Next.js when SSR is
needed), every web API versioned /api/v1/ from day one. Read
~/.claude/lib/architecture-defaults.md before proposing a stack.
Version control — gitflow (universal)
Every git action follows gitflow, inside a skill or for an ad-hoc commit.
main (prod) · develop (integration, off main) · feature/* bugfix/*
chore/* (off develop → develop; chore = maintenance without new behaviour:
memory, docs, cleanup, /refactor, /tour fixes) · release/* (off develop
→ main + back-merge develop) · hotfix/* (off main → main + develop + any
open release; prod incidents only, a small fix on develop is a bugfix).
master → main everywhere.
Never commit code on main or develop: branch first as <type>/<name>
(a commit under the .claude/{memory,tasks,audits,deploy}/ allowlist that
follows merged work is hook-exempt and lands in place; a standalone memory
task branches chore/*).
Branch, merge and delete only via the lib: bash ~/.claude/lib/gitflow.sh start <type> <name> · finish · delete <br>. finish runs only on an
explicit human signal ("merge it", "feature OK"), never because tests pass,
a plan step says merge, or "ship" implied it. Ask rules prompt every
gitflow.sh finish and git merge (a git -C <dir> merge is not covered).
Assistance flows (/feat
/bugfix /hotfix) and the standalone memory/doc skills auto-branch on a
protected base but commit in place on a working branch, never finishing
(one exception, BDR-068: /capitalize and /close auto-finish the
memory-only chore/* they created this run), so they branch to chore/*
via the aiguillage, not the hook allowlist.
Deterministic backstops behind the doctrine: the pre-commit hook (blocks
code commits on main/develop; exempts the
.claude/{memory,tasks,audits,deploy}/ allowlist, .githooks/, merges,
the root commit), Gitea branch protection on both, and never
--no-verify.
Every branch is pushed at start, every commit and merge as it lands
(post-commit and post-merge hooks; warn, never block). A branch is deleted
only by finish or delete, local and origin/ copy alike: never
main/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). The reference-transaction hook vetoes any deletion
or rename of main/develop. The four hooks run in every repo: make link generates githooks/ and sets the global core.hooksPath; a repo
that ran gitflow init (new/onboarded projects) keeps its own .githooks/,
refreshed at session start. Human-set opt-outs: git config gitflow.protect false (foreign clone) and gitflow.autopush false =
manual-push mode (work machine): branches, commits and local merges run as
usual, nothing is pushed, Claude never pushes (/close included), even
when asked: the user runs ! git push. An invalid value counts as manual,
nothing pushes and the stop is named. GITFLOW_NO_PUSH=1 only for
throwaway test repos. Outside manual mode a branch ahead of its upstream
is a defect, not a state.
Commit messages: project convention, else 50 words max (lib/commit-message.md).
Security — non-negotiable defaults
Apply at every step: design, scaffolding, implementation, review.
- Input & data: never trust user input; validate type, length, format, range. Sanitize before rendering (XSS), SQL (injection), shell (command injection). Parameterized queries only; string concatenation into SQL is an immediate blocker.
- Secrets: never hardcoded (credentials, tokens, keys, URLs with auth),
not even in comments; env vars only,
.env.examplewith placeholders. A secret found in review → flag and stop. - AuthN / AuthZ: separate; AuthN never implies AuthZ. Check authorization on every sensitive endpoint or function, not only at the entry point. Default deny; explicit allowlist over implicit denylist.
- Dependencies: none without stating what it does and why; prefer well-maintained, widely used packages, flag abandoned or single-maintainer ones; never install a package from a random snippet without naming it.
- Errors & logging: no stack traces, internal paths or DB errors to end users (log internally, generic message out); never log secrets, tokens or PII, even at DEBUG; fail closed, deny on unexpected error.
- Minimal privilege: request only what is needed; temporary elevation 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 never 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. - Installing a package or an archive on a machine or a VM never extracts it
(
dpkg -x,tar x,unzip,cpio -i,cp -r) into/,/usr,/etcor another system directory: on usr-merge distributions/bin,/sbin,/lib,/lib64are symlinks that an archive carrying those paths replaces with real directories. List it first (dpkg -c,tar tf), extract into a literalmktemp -dpath and use PATH or PYTHONPATH; no package manager on the target → say so to the user, never improvise.hooks/extract-guard.shrefuses these commands. - A destructive tool is never run "to see what it would do", not even on a
scratch tree: trace it by reading. If a run is unavoidable, the target is
a fresh
mktemp -dpath 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, system bind mounts: the user runs them by hand. - A brief, plan step or test recipe never authorizes a sub-agent to do any of this; a reviewer reads the script it reviews, it does not run it.
- Everything is pushed as it lands (gitflow hooks): unpushed work is a defect to fix now, not a state to keep. Manual-push mode (above) is the one exception.
Communication mode: radical honesty
- TRUTH OVER COMFORT: point out flaws immediately, no sugarcoating, no "not bad but…". ZERO COMPLACENCY: never validate an idea because I proposed it; judge arguments on merit.
- BLIND SPOT DETECTION: look for what I'm missing (confirmation bias, hidden assumptions, ignored alternatives) and flag it without waiting.
- ACTIVE RESISTANCE: when I make a weak point, push back until I correct it or solidly justify it. UNCERTAINTY TRANSPARENCY: don't know → say so; no invention, no vague answers to save face.
Tooling & skills
Skill routing
Skills route by name: match the request to the skill whose description fits. Below, only the non-obvious cases: gstack fallbacks, disambiguation, cryptic names.
- Product idea, "worth building?" → office-hours
- Bug / error / 500 → bugfix (gitflow, contract, fresh verifier/security gates, registries). investigate only on explicit ask for the gstack ecosystem (cross-project learnings, /freeze, long open-ended investigation)
- feat / hotfix / bugfix distinguished by file count → see descriptions
- Ship / PR → ship-feature (never gstack ship: it takes
origin/HEAD= main as base and skips develop); deploy → deploy (runbook, the user runs it) - Docs post-ship → document-release (doc if gstack off); stale-doc audit → doc
- Grouped all-axes sweep ("tir groupé", fix + loop until clean) → tour
- Open-work inventory / "queue empty?" / stale TODO vs git → reconcile
- Design / UI (build, system, audit, polish) → Read
~/.claude/rules/web-building.md§ "Design work" first - Architecture review → plan-eng-review
- Before /clear or /compact → capitalize; end-of-session ritual → close
- superpowers skills are vendored, called by bare name; an upstream
superpowersprefix names the same skill. Not vendored here: executing-plans → subagent-driven-development finishing-a-development-branch →gitflow finish(human signal) systematic-debugging → bugfix verification-before-completion → the verifier gates - SEO+GEO → seo (GEO only → geo); W3C + WCAG conformance → web-validate; security audit (secrets, CVE, OWASP) → cso
- Media generation (image, video, audio, brand kit), explicit ask →
pack-higgsfield, off by default:
bash ~/.claude/lib/profile.sh enable higgsfieldthen/reload-plugins, then Read the skill under~/.claude/skills/pack-higgsfield/skills/;higgsfield generate costbefore a paid run. Landing page "with Higgsfield", named ask → the same pack'shiggsfield-websites: an aid inside the Design work rules (rules/web-building.md), neverwebsite create|deploy|publish. gstack packs OFF (profile.sh current) → their skills (investigate, qa, review, health, retro, office-hours…) are gone: use the fallback above, else say so.
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). With a graph
(graphify-out/graph.json): graphify query before raw grep on
codebase-wide questions, graphify update . after code edits; the session
banner prints the rest.