From e7e9dacddc080b2186aefb1b8489f759536546e8 Mon Sep 17 00:00:00 2001 From: Bastien Chanot Date: Fri, 12 Jun 2026 13:56:59 +0200 Subject: [PATCH] refactor(claude-md): resolve contradictions, fix dead refs, restructure sections MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fable 5 audit of the global CLAUDE.md (symlinked from this repo): Contradictions resolved: - two conflicting graphify sections merged into one (query-first when graphify-out/graph.json exists, direct read otherwise; single command form; dropped the false 'this project has a knowledge graph' claim) - plan rule: 'when in doubt skip plan' no longer cancels the mandate — borderline = single-file small obvious change - deviation rule disambiguated: minor/justified -> explain after, significant/shaky -> ask before - 'append-only' registries reconciled with /prune-memory curation Dead refs fixed: /caveman:compress -> /caveman-compress; design-gate path now ~/.claude/lib/ (was repo-relative); '(replaces LESSONS)' note dropped. Structure: Health Stack / Skill routing / graphify no longer nested under '# Communication mode'; new '# Tooling & skills' and '# This repo only' sections; repo-specific Health Stack labeled as such. Routing updated: + audit-delta, close, capitalize, prune-memory, profile, context-restore, geo; explicit gstack-OFF fallback rule. Mid-task question exception generalized to all skill-mandated gates. Non-critical sections caveman-compressed; Architecture decisions and Security kept verbatim (must stay unambiguous). Net -1471 chars while adding 8 routing entries. Co-Authored-By: Claude Fable 5 --- CLAUDE.md | 338 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 208 insertions(+), 130 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index f8892f3..09537bb 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -5,73 +5,104 @@ Apply unless repo-specific instructions override. ## Code style - Simple, readable, maintainable > clever or compact. - One responsibility per function/method. -- Preserve existing behavior unless asked otherwise. +- 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 (excl. comments, error handling). +- 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, etc.). -- Explicit, consistent, meaningful names. Straight control flow. No hidden side effects. +- Document intent, not mechanics. Use project doc style (docstring, JSDoc…). +- Explicit, consistent, meaningful names. Straight control flow. + No hidden side effects. ## 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 cleanly. No over-engineer. +- 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` — understand current state. -3. If `.claude/memory/` or `.claude/tasks/TODO.md` missing, create before starting (templates at `~/.claude/templates/memory/`). +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 -- Write/modify task touching logic (new behavior, control flow, state, API, dependencies): plan in `.claude/tasks/TODO.md` first, decomposed into subtasks. Task count irrelevant — one complex task still needs plan. When in doubt about complexity, skip plan (be pragmatic). -- Confirm before implementing only when real trade-offs exist (multiple valid approaches, breaking change, destructive action) — else proceed. -- Exempt from `.claude/tasks/TODO.md`: pure reads, explanations, questions, typos, cosmetic CSS tweaks, single config-value changes. Aligns with `/hotfix` scope (≤2 files, obvious fix). +- Task touches logic (new behavior, control flow, state, API, + dependencies) → plan in `.claude/tasks/TODO.md` first, decomposed into + subtasks. One complex task still needs plan. Borderline case (single + file, small obvious logic change) → skip plan, stay pragmatic. +- Confirm before implementing ONLY when real trade-offs exist (multiple + valid approaches, breaking change, destructive action) — else proceed. +- Exempt from TODO.md: pure reads, explanations, questions, typos, + cosmetic CSS, single config-value change. Same scope as `/hotfix` + (≤2 files, obvious fix). - Minimal changes unless broader refactor requested. State trade-offs. -- Use sub-agents to keep main context clean — one task per sub-agent. Invest more compute on hard problems. -- One question upfront if needed — never interrupt mid-task. *(Exception: orchestrators' mandatory validation gates — example, /init-project STEP 4/7, /ship-feature STEP 3 — exempt.)* -- Bug received → fix directly: check logs, find root cause, resolve autonomously. -- Something goes wrong: STOP and re-plan — never push through. -- Report deviations: minor/justified → explain. Significant/unjustified → ask. -- Root causes only. No temp fixes. Never assume — verify paths, APIs, variables before use. +- Sub-agents keep main context clean — one task per sub-agent. + More compute on hard problems. +- One question upfront if needed — never interrupt mid-task. + *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. +- Something goes wrong → STOP, re-plan. Never push through. +- Deviations: minor or clearly justified → do, explain after. + Significant or shaky justification → ask BEFORE deviating. +- Root causes only. No temp fixes. Never assume — verify paths, APIs, + variables before use. ## After code changes 1. Run tests, lint, build, type-check if available. 2. Report what verified, what not. -3. List remaining risks and surviving deviations. -4. Never mark complete without proof it works. Bar: "would staff engineer approve this?" -5. After any correction or notable event, capitalize to right registry in `.claude/memory/` (see "Memory registries" below). +3. List remaining risks, surviving deviations. +4. Never mark complete without proof it works. + Bar: "would staff engineer approve?" +5. Correction or notable event → capitalize to right registry + (see "Memory registries"). ## Task tracking (`.claude/tasks/TODO.md`) -Applies to any write/modify task touching logic, regardless of count. Skip for reads and trivial edits (see Workflow). +Any write/modify task touching logic. Skip reads + trivial edits +(see Workflow). -1. Plan → write task in `.claude/tasks/TODO.md` before touching code. -2. Decompose → split each complex task into subtasks (one subtask = one coherent change). -3. Track → check off subtasks as you go. -4. Summarize → high-level summary at each milestone. +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. ## Memory registries (`.claude/memory/`) -Five append-only registries persist across sessions. Read all at session start. Capitalize during/after work. +Five registries persist across sessions. Read all at session start. +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 with rationale + alternatives + status | -| `learnings.md` | LRN-XXX | Reusable patterns observed + context + future application (replaces LESSONS) | +| `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 — what done, decided, blocked | +| `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:** -All persisted entries (decisions, learnings, blockers, journal, evals) must be English. Rationale: consistent vocab for re-read efficiency, lower token cost, easier cross-project reuse. User-facing CAPITALIZE prompts may mirror user's language; only final written entry is English. +**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:** -All writes to `.claude/memory/*.md` (decisions, learnings, blockers, journal, evals) MUST use caveman style — drop articles (a/an/the), drop filler (just/really/basically/actually/simply), fragments OK, short synonyms (big not extensive, fix not "implement a solution for"). Keep technical terms exact, code blocks unchanged, error messages quoted exact, IDs (BDR-XXX, LRN-XXX, BLK-XXX, EVAL-XXX) and dates unchanged. Pattern: `[thing] [action] [reason]. [next step].` Rationale: registries loaded every session start — caveman cuts ~40% input tokens with zero loss of technical substance. Applies to direct writes AND skill-driven CAPITALIZE steps (close, ship-feature, feat, bugfix, hotfix, commit-change). Existing entries: compress on demand via `/caveman:compress `. +**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). Existing entries: compress via +`/caveman-compress `. **Routing — what goes where:** - Choice with tradeoffs you'd defend → `decisions.md`. @@ -81,47 +112,57 @@ All writes to `.claude/memory/*.md` (decisions, learnings, blockers, journal, ev - Did Claude's output actually work? → `evals.md`. **Proactive capitalization (Claude's responsibility):** -After any 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. Use right registry; pre-fill entry from conversation context; let user approve/edit before writing. +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. -Completion skills (`/ship-feature`, `/feat`, `/bugfix`, `/hotfix`, `/commit-change`) include CAPITALIZE step that automates this. - -**Session-close ritual** (invoke manually via `/close`, or answer inline when asked): -1. What did I decide? → `decisions.md` (if non-trivial). -2. What did I learn? → `learnings.md` (if reusable). -3. What am I blocked on? → `blockers.md`. - -## Context Navigation (graphify) -- Use `/graphify query` ONLY for large-scope tasks: multi-file features, complex bug investigations, architectural changes, major refactors. -- Small tasks (hotfix, typo, single-file change, quick lookup): read files directly — do NOT invoke graphify. -- Before answering architecture/codebase questions, read `graphify-out/GRAPH_REPORT.md` for god nodes and community structure. If `graphify-out/wiki/index.md` exists, use as navigation entrypoint. -- After modifying code files, run `/graphify --update` to keep graph current (AST-only, no API cost for code-only changes). +**Session-close ritual** (`/close`, 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. +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): +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. +- **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/...`, `/api/v2/...`. +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) → keep in current version. -- Each version is self-contained contract. Never modify existing version behavior to match newer one. -- Router structure must reflect versioning explicitly (e.g. `api/v1/routes/`, `api/v2/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. Never modify existing version + behavior to match newer one. +- Router structure reflects versioning explicitly (e.g. `api/v1/routes/`). ## Security — non-negotiable defaults @@ -129,26 +170,34 @@ 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. +- 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. +- 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. +- 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` package found in random code snippet without naming it explicitly. +- 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 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. @@ -160,80 +209,109 @@ Apply at every dev step: design, scaffolding, implementation, review. # 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. +- 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. -## Health Stack +--- -- shell: shellcheck *.sh hooks/*.sh lib/*.sh +# Tooling & skills ## Skill routing -When user's request matches available skill, ALWAYS invoke via Skill -tool as FIRST action. Do NOT answer directly, do NOT use other tools first. -Skill has specialized workflows that produce better results than ad-hoc answers. +Request matches available skill → invoke via Skill tool FIRST. No direct +answer, no other tools before. Skill workflows beat ad-hoc answers. Key routing rules: -- Product ideas, "is this worth building", brainstorming → invoke office-hours -- Bugs, errors, "why is this broken", 500 errors → invoke investigate, or bugfix if no gstack -- Small feature (1-5 files, lightweight) → invoke feat -- Quick fix (typo, CSS, config, max 2 files) → invoke hotfix -- Ship, deploy, push, create PR → invoke ship, or ship-feature if no gstack -- QA, test site, find bugs → invoke qa -- Code review, check my diff → invoke review -- Update docs after shipping → invoke document-release, or doc if no gstack -- Stale docs audit, doc sync → invoke doc -- Weekly retro → invoke retro -- Design system, brand → invoke design-consultation, then full design toolchain (see "Design work" below) -- Build UI / component / page / screen → full design toolchain (see "Design work" below) -- Visual audit, design polish → invoke design-review + emil-design-eng lens + design-motion-principles (audit mode) -- Architecture review → invoke plan-eng-review -- Save progress, checkpoint, resume → invoke context-save -- Code quality, health check → invoke health -- Refactor without behavior change → invoke refactor -- Dead code, style cleanup → invoke code-clean -- SEO/GEO audit → invoke seo -- Web hardening (SSL/TLS, HSTS, CSP, HTTP→HTTPS, canonical, 404, .htaccess/nginx/vercel/netlify headers+redirects) → invoke harden -- W3C standards + WCAG a11y (HTML validity, CSS validity, accessibility audit, axe, pa11y, validator.w3.org, normes W3C) → invoke validate -- Deep analysis before any modification → invoke analyze -- Smart commit grouping → invoke commit-change -- Security audit (secrets, deps CVE, OWASP code-level) → invoke cso -- Initialize new project from scratch → invoke init-project -- Onboard existing project (config + archetype detection + full audit pipeline + backlog) → invoke onboard +- Product ideas, "worth building?", brainstorming → office-hours +- Bugs, errors, "why broken", 500s → investigate, or bugfix if no gstack +- Small feature (1-5 files) → feat +- Quick fix (typo, CSS, config, ≤2 files) → hotfix +- Ship, deploy, push, PR → ship, or ship-feature if no gstack +- QA, test site, find bugs → qa +- Code review, check diff → review +- Docs update post-ship → document-release, or doc if no gstack +- Stale docs audit, doc sync → doc +- Recurring audit of changes since last run → audit-delta +- Weekly retro → retro +- Design system, brand → design-consultation, then design toolchain below +- Build UI / component / page / screen → design toolchain below +- Visual audit, polish → design-review + emil-design-eng + + design-motion-principles (audit mode) +- Architecture review → plan-eng-review +- Save/restore working context → context-save / context-restore +- End-of-session ritual → close +- Flush memory before /clear or /compact → capitalize +- Registries too big/noisy → prune-memory +- Skill profiles (design/dev/qa/minimal) → profile +- Code quality dashboard → health +- Refactor without behavior change → refactor +- Dead code, style cleanup → code-clean +- SEO/GEO audit → seo (GEO only → geo) +- Web hardening (SSL/TLS, HSTS, CSP, redirects, headers) → harden +- W3C + WCAG a11y (HTML/CSS validity, axe, pa11y) → validate +- Deep analysis before modification → analyze +- Smart commit grouping → commit-change +- Security audit (secrets, deps CVE, OWASP) → cso +- New project from scratch → init-project +- Onboard existing repo (config + archetype + audits + backlog) → onboard -Design gate (automatic): -All lightweight skills (feat, hotfix, bugfix) include design gate that auto-detects -UI/style signals in task. If design signals found and ui-ux-pro-max inactive, -agent asks user whether to activate before proceeding. -Gate spec: lib/design-gate.md. Orchestrators (ship-feature, init-project) already -handle via STEP 0 plugin-check. +gstack OFF → gstack skills (investigate, ship, qa, review, health, retro, +office-hours, context-save…) unavailable: use the non-gstack fallback +where listed, else say so instead of improvising. -Design work — full toolchain (tiered by scope): -When a task touches design/UI, mobilize the available tools by scope. Reinforced by -the design-toolchain-reminder UserPromptSubmit hook (injects this on UI signals). -- Trivial (≤2 files, single cosmetic value, CSS tweak) → /hotfix, NO toolchain. -- Build UI (new component, page, screen, redesign) → invoke ui-ux-pro-max (plan/build) - + frontend-design (anti AI-slop) + Magic MCP `/ui` (21st.dev component scaffold) - + emil-design-eng (polish pass, invisible details) + design-motion-principles - (when motion/transitions) + design-html (when static HTML / Pretext-native). -- Design system / brand → design-consultation FIRST (aesthetic, type, color, spacing, - motion), THEN the build tools above. +Design gate (automatic): lightweight skills (feat, hotfix, bugfix) detect +UI/style signals; signals found + ui-ux-pro-max inactive → ask user +before proceeding. Gate spec: `~/.claude/lib/design-gate.md`. +Orchestrators (ship-feature, init-project) handle via STEP 0 plugin-check. + +## Design work — full toolchain (tiered by scope) + +Task touches design/UI → mobilize tools by scope. Reinforced by +design-toolchain-reminder hook (injects on UI signals). +- Trivial (≤2 files, single cosmetic value) → /hotfix, NO toolchain. +- Build UI (new component, page, screen, redesign) → ui-ux-pro-max + (plan/build) + frontend-design (anti AI-slop) + Magic MCP `/ui` + (21st.dev scaffold) + emil-design-eng (polish pass) + + design-motion-principles (when motion) + design-html (static HTML). +- Design system / brand → design-consultation FIRST (aesthetic, type, + color, spacing, motion), THEN build tools above. - Review / audit → design-review (visual QA + fix) + emil-design-eng lens - + design-motion-principles (audit mode, catch slop motion). -In doubt about scope (is this a trivial tweak or a real UI change?) → do NOT silently -skip the toolchain. Ask the user, or default to the Build tier rather than /hotfix. -Magic MCP (@21st-dev/magic) is configured globally and costs API calls — use it for -component generation, not micro-tweaks. + + design-motion-principles (audit mode). +Scope doubt (trivial tweak vs real UI change?) → do NOT silently skip +toolchain: ask user, or default to Build tier. +Magic MCP (@21st-dev/magic) costs API calls — component generation only, +not micro-tweaks. ## graphify -This project has a knowledge graph at graphify-out/ with god nodes, community structure, and cross-file relationships. +Knowledge-graph navigation via graphify CLI. ALL rules conditional: +`graphify-out/graph.json` exists in the project — else skip graphify +entirely, read files directly. -Rules: -- For codebase questions, first run `graphify query ""` when graphify-out/graph.json exists. Use `graphify path "" ""` for relationships and `graphify explain ""` for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output. -- If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing. -- Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context. -- After modifying code, run `graphify update .` to keep the graph current (AST-only, no API cost). +- Codebase-wide question → `graphify query ""` first. + Relationships → `graphify path "" ""`. Focused concept → + `graphify explain ""`. Scoped subgraph beats raw grep. +- Known file/symbol lookup, small task (hotfix, typo, single file) → + read directly, no graphify. +- `graphify-out/wiki/index.md` exists → broad-navigation entrypoint. + `GRAPH_REPORT.md` only for whole-architecture review or when + query/path/explain insufficient. +- After modifying code → `graphify update .` (AST-only, no API cost). + +--- + +# This repo only (claude-config) + +Apply when working directory = the claude-config repo itself. + +## Health Stack +- shell: `shellcheck *.sh hooks/*.sh lib/*.sh`