|
|
@@ -2,7 +2,6 @@
|
|
|
|
Repo-specific instructions live in ./CLAUDE.md (project scope). -->
|
|
|
|
Repo-specific instructions live in ./CLAUDE.md (project scope). -->
|
|
|
|
|
|
|
|
|
|
|
|
# Global coding preferences
|
|
|
|
# Global coding preferences
|
|
|
|
|
|
|
|
|
|
|
|
Apply unless repo-specific instructions override.
|
|
|
|
Apply unless repo-specific instructions override.
|
|
|
|
|
|
|
|
|
|
|
|
## Code style
|
|
|
|
## Code style
|
|
|
@@ -12,18 +11,16 @@ Apply unless repo-specific instructions override.
|
|
|
|
- Scope changes to task — no unrelated edits.
|
|
|
|
- Scope changes to task — no unrelated edits.
|
|
|
|
|
|
|
|
|
|
|
|
## Limits (adapt to language)
|
|
|
|
## Limits (adapt to language)
|
|
|
|
- Max 25 logic lines/function, 80 chars/line, 5 params, 5 local vars.
|
|
|
|
- Max 25 logic lines/function (executable statements; comments and
|
|
|
|
Logic lines = executable statements; comments + error-handling
|
|
|
|
error-handling boilerplate don't count), 80 chars/line, 5 params, 5 locals.
|
|
|
|
boilerplate don't count toward 25.
|
|
|
|
|
|
|
|
- Too many params → struct/object. Too many vars → split/extract.
|
|
|
|
- Too many params → struct/object. Too many vars → split/extract.
|
|
|
|
- No global state. Explicit data flow.
|
|
|
|
- No global state. Explicit data flow.
|
|
|
|
|
|
|
|
|
|
|
|
## Comments & readability
|
|
|
|
## Comments & readability
|
|
|
|
- Document intent, not mechanics. Use project doc style (docstring, JSDoc…).
|
|
|
|
- Document intent, not mechanics. Use project doc style (docstring, JSDoc…).
|
|
|
|
- Explicit, consistent, meaningful names. Straight control flow,
|
|
|
|
- Explicit, consistent names. Straight control flow, no hidden side effects.
|
|
|
|
no hidden side effects.
|
|
|
|
- Written deliverables (docs, reports, .md): length matched to the task, no
|
|
|
|
- Written deliverables (docs, reports, .md): length matched to what
|
|
|
|
filler sections, no boilerplate summaries.
|
|
|
|
the task needs — no filler sections, no boilerplate summaries.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## Refactoring
|
|
|
|
## Refactoring
|
|
|
|
- Priority: safety → readability → consistency.
|
|
|
|
- Priority: safety → readability → consistency.
|
|
|
@@ -32,314 +29,235 @@ Apply unless repo-specific instructions override.
|
|
|
|
Hacky fix → rebuild clean, no over-engineering.
|
|
|
|
Hacky fix → rebuild clean, no over-engineering.
|
|
|
|
|
|
|
|
|
|
|
|
## Session start
|
|
|
|
## Session start
|
|
|
|
1. Read `.claude/memory/` — 5 registries (decisions, learnings, blockers,
|
|
|
|
1. Read `.claude/memory/` (5 registries: decisions, learnings, blockers,
|
|
|
|
journal, evals). Apply before touching anything.
|
|
|
|
journal, evals) and `.claude/tasks/TODO.md`. Apply before touching anything.
|
|
|
|
2. Read `.claude/tasks/TODO.md` — current state.
|
|
|
|
2. Either missing → create it first (templates: `~/.claude/templates/memory/`).
|
|
|
|
3. Either missing → create before starting
|
|
|
|
|
|
|
|
(templates: `~/.claude/templates/memory/`).
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## Workflow
|
|
|
|
## Workflow
|
|
|
|
- Confirm before implementing only when real trade-offs exist (multiple
|
|
|
|
- Confirm before implementing only when real trade-offs exist (several
|
|
|
|
valid approaches, breaking change, destructive action) — else proceed.
|
|
|
|
valid approaches, breaking change, destructive action); else proceed.
|
|
|
|
- Minimal changes unless broader refactor requested. State trade-offs.
|
|
|
|
Minimal changes unless a broader refactor is requested. State trade-offs.
|
|
|
|
- Sub-agents: one task per sub-agent, main context stays clean.
|
|
|
|
- Sub-agents: one task each, main context stays clean. Delegate
|
|
|
|
Delegate genuinely independent, sizeable tracks (wide multi-file
|
|
|
|
independent, sizeable tracks (wide multi-file exploration, parallel
|
|
|
|
exploration, parallel audits) — not work doable in a few tool
|
|
|
|
audits), not work doable in a few tool calls. Skill-mandated gates (fresh
|
|
|
|
calls. Skill-mandated gates (fresh verifier/security/challenge)
|
|
|
|
verifier/security/challenge) always dispatch as written; a failed gate
|
|
|
|
always dispatch as written. Don't redo delegated work by hand —
|
|
|
|
re-dispatches a fresh executor, never redo its work by hand. A brief never
|
|
|
|
failed gates re-dispatch fresh executors instead. A brief never
|
|
|
|
|
|
|
|
authorizes a sub-agent to run a destructive tool, inside or outside the
|
|
|
|
authorizes a sub-agent to run a destructive tool, inside or outside the
|
|
|
|
repo (Security → Destructive tools & data loss).
|
|
|
|
repo (Security → Destructive tools & data loss).
|
|
|
|
- Ask rather than guess. A choice visible in the result (placement,
|
|
|
|
- Ask rather than guess. A choice visible in the result (placement,
|
|
|
|
wording, order, behavior), a name that becomes public (command, flag,
|
|
|
|
wording, order, behavior), a name that becomes public (command, flag,
|
|
|
|
endpoint, file), or a scope the request does not settle → ask, even
|
|
|
|
endpoint, file), or a scope the request leaves open → ask, even mid-task;
|
|
|
|
mid-task. Batch what can be batched. Internal technical choices with
|
|
|
|
batch what can be batched. Internal choices with no observable effect
|
|
|
|
no observable effect stay yours.
|
|
|
|
stay yours. Exception: skill-mandated gates and checkpoints (validation,
|
|
|
|
*Exception: skill-mandated gates and checkpoints (orchestrator
|
|
|
|
approval, darwin) always fire.
|
|
|
|
validation gates, approval gates, darwin checkpoints) always fire.*
|
|
|
|
- Bug received → fix directly: logs, root cause, resolve autonomously; a
|
|
|
|
- Bug received → fix directly: check logs, find root cause, resolve
|
|
|
|
visible choice in the fix still gets asked.
|
|
|
|
autonomously; a visible choice in the fix still gets asked.
|
|
|
|
- Deviations: minor or clearly justified → do, explain after; significant
|
|
|
|
- Something goes wrong → STOP, re-plan. Never push through.
|
|
|
|
or shaky → ask first. Finish the whole task: a blocked independent
|
|
|
|
- Deviations: minor or clearly justified → do, explain after.
|
|
|
|
sub-part → do the rest, state what's missing. Something goes WRONG →
|
|
|
|
Significant or shaky justification → ask before deviating.
|
|
|
|
STOP, re-plan, never push through.
|
|
|
|
Finish the whole task: blocked on an independent sub-part → do
|
|
|
|
- Root causes only, no temp fixes. Never assume: verify paths, APIs,
|
|
|
|
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.
|
|
|
|
variables before use.
|
|
|
|
|
|
|
|
|
|
|
|
## Planning & TODO (`.claude/tasks/TODO.md`)
|
|
|
|
## Planning & TODO (`.claude/tasks/TODO.md`)
|
|
|
|
|
|
|
|
- Task touches logic (new behavior, control flow, state, API, dependencies)
|
|
|
|
- When to plan: task touches logic (new behavior, control flow, state,
|
|
|
|
→ write the plan in TODO.md first, decomposed into subtasks; one complex
|
|
|
|
API, dependencies) → write it in `.claude/tasks/TODO.md` first,
|
|
|
|
task still needs one. Borderline (single file, small obvious change) →
|
|
|
|
decomposed into subtasks. One complex task still needs a plan.
|
|
|
|
skip, stay pragmatic.
|
|
|
|
Borderline case (single file, small obvious logic change) → skip plan,
|
|
|
|
- Exempt: pure reads, explanations, questions, typos, cosmetic CSS, single
|
|
|
|
stay pragmatic.
|
|
|
|
config value — the `/hotfix` scope (≤2 files, obvious fix).
|
|
|
|
- Exempt (skip TODO.md): pure reads, explanations, questions, typos,
|
|
|
|
- Once it qualifies: plan before code → one subtask = one coherent change
|
|
|
|
cosmetic CSS, single config-value change. Same scope as `/hotfix`
|
|
|
|
→ check off as you go → high-level note at each milestone.
|
|
|
|
(≤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
|
|
|
|
## After code changes
|
|
|
|
1. Run tests, lint, build, type-check if available.
|
|
|
|
1. Run tests, lint, build, type-check if available. Report what was
|
|
|
|
2. Report what verified, what not.
|
|
|
|
verified and what was not; list remaining risks and surviving deviations.
|
|
|
|
3. List remaining risks, surviving deviations.
|
|
|
|
2. Don't mark complete without proof it works.
|
|
|
|
4. Don't mark complete without proof it works.
|
|
|
|
3. Correction or notable event → capitalize to the right registry.
|
|
|
|
5. Correction or notable event → capitalize to right registry
|
|
|
|
|
|
|
|
(see "Memory registries").
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## Memory registries (`.claude/memory/`)
|
|
|
|
## Memory registries (`.claude/memory/`)
|
|
|
|
|
|
|
|
Five registries persist across sessions; capitalize during and after work.
|
|
|
|
|
|
|
|
Append-only: never rewrite past entries; curation (merge, supersede,
|
|
|
|
|
|
|
|
compress) only via `/prune-memory`.
|
|
|
|
|
|
|
|
|
|
|
|
Five registries persist across sessions. Capitalize during/after work.
|
|
|
|
| File | ID | Purpose |
|
|
|
|
Append-only by default — never rewrite past entries; curation (merge,
|
|
|
|
|---|---|---|
|
|
|
|
mark superseded, compress) ONLY via `/prune-memory`.
|
|
|
|
| `decisions.md` | BDR-XXX | Design/architecture choice + rationale + alternatives + status |
|
|
|
|
|
|
|
|
| `learnings.md` | LRN-XXX | Reusable pattern + context + future application |
|
|
|
|
| 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) |
|
|
|
|
| `blockers.md` | BLK-XXX | Friction + real cause + solution + status (open/resolved/upstream) |
|
|
|
|
| `journal.md` | date heading | 3-5 lines/session — 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 |
|
|
|
|
| `evals.md` | EVAL-XXX | Quality check of Claude's output + method + anomalies + action |
|
|
|
|
|
|
|
|
|
|
|
|
**Language — registries always English.** Rationale: consistent vocab,
|
|
|
|
Routing: a choice with trade-offs you'd defend → decisions; a pattern worth
|
|
|
|
lower token cost, cross-project reuse. User-facing CAPITALIZE prompts may
|
|
|
|
reusing → learnings; a dead end with its root cause → blockers; the session
|
|
|
|
mirror user's language; final written entry English.
|
|
|
|
log → journal; whether the output actually worked → evals.
|
|
|
|
|
|
|
|
|
|
|
|
**Format — registries always caveman.** Drop articles + filler, fragments
|
|
|
|
**Always English, always caveman**: drop articles and filler, fragments OK,
|
|
|
|
OK, short synonyms. Technical terms exact, code blocks unchanged, errors
|
|
|
|
short synonyms; technical terms, code blocks, quoted errors, IDs and dates
|
|
|
|
quoted exact, IDs (BDR/LRN/BLK/EVAL-XXX) + dates unchanged. Pattern:
|
|
|
|
exact. Pattern `[thing] [action] [reason]. [next step].` Registries load
|
|
|
|
`[thing] [action] [reason]. [next step].` Rationale: registries load
|
|
|
|
every session; caveman cuts ~40% of the tokens with no substance lost.
|
|
|
|
every session — caveman cuts ~40% input tokens, zero substance loss.
|
|
|
|
Applies to direct writes and to the CAPITALIZE step of every completion
|
|
|
|
Applies to direct writes AND skill CAPITALIZE steps (close, ship-feature,
|
|
|
|
skill. Prompts to the user may mirror their language; the entry is English.
|
|
|
|
feat, bugfix, hotfix, commit-change). Legacy entries (pre-format-rule):
|
|
|
|
Legacy entries: compress on demand.
|
|
|
|
compress manually or via claude.ai on demand.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
**Routing — what goes where:**
|
|
|
|
**Proactive capitalization** is Claude's job: after a substantive milestone
|
|
|
|
- Choice with tradeoffs you'd defend → `decisions.md`.
|
|
|
|
(root-caused bug fix, shipped feature, non-trivial commit, design choice,
|
|
|
|
- Pattern worth reusing → `learnings.md`.
|
|
|
|
surprising discovery, dead end with a lesson) offer to capitalize inline,
|
|
|
|
- Dead end with root cause identified → `blockers.md`.
|
|
|
|
entry pre-filled, user approves before the write. Completion skills
|
|
|
|
- One-line log of session → `journal.md`.
|
|
|
|
(`/ship-feature` `/feat` `/bugfix` `/hotfix` `/commit-change`) do it via
|
|
|
|
- Did Claude's output actually work? → `evals.md`.
|
|
|
|
their CAPITALIZE step. Session close (`/close` = `/capitalize --ritual`):
|
|
|
|
|
|
|
|
what was decided → decisions, learned → learnings, blocked → blockers.
|
|
|
|
**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
|
|
|
|
# Architecture decisions
|
|
|
|
|
|
|
|
Override default framework/tooling choices at project creation, scaffolding,
|
|
|
|
Override default framework/tooling choices. Apply at project creation,
|
|
|
|
brainstorming.
|
|
|
|
scaffolding, brainstorming.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## Public websites — never SPA
|
|
|
|
## Public websites — never SPA
|
|
|
|
|
|
|
|
A public site meant to be indexed (landing, portfolio, blog, e-commerce,
|
|
|
|
When project is public-facing website meant to be indexed (landing page,
|
|
|
|
docs) is never a pure SPA (CRA, Vite React, Vue SPA): the empty HTML shell
|
|
|
|
portfolio, blog, e-commerce, docs):
|
|
|
|
hides content from search and AI engines, SEO and GEO destroyed.
|
|
|
|
- **FORBIDDEN**: pure SPA (CRA, Vite React SPA, Vue SPA) for public pages.
|
|
|
|
- **Astro** by default for informational sites: static HTML at build, zero
|
|
|
|
SPA sends empty HTML shell — search engines and AI engines (GEO) can't
|
|
|
|
JS by default, React/Vue/Svelte islands for interactive parts.
|
|
|
|
see content without executing JS. SEO and AI visibility destroyed.
|
|
|
|
- **Next.js** when dynamic SSR is needed (personalized content, server-side
|
|
|
|
- **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).
|
|
|
|
auth, API routes, hybrid app).
|
|
|
|
- **React SPA** = valid only for: admin panels, dashboards, auth-gated
|
|
|
|
- **React SPA** only for what needs no indexing: admin panels, dashboards,
|
|
|
|
apps, internal tools — anything that does not need indexing.
|
|
|
|
auth-gated apps, internal tools. Mixed project: Astro/Next for public,
|
|
|
|
- **Mixed project** (public + admin): Astro/Next for public, React island
|
|
|
|
React island (`client:only`) for admin.
|
|
|
|
(`client:only`) for admin.
|
|
|
|
- At brainstorming (`/init-project`, `/ship-feature` STEP 1), public site
|
|
|
|
- At brainstorming (`/init-project` STEP 1, `/ship-feature` STEP 1): if
|
|
|
|
and no framework named → propose Astro, explain why not SPA. Never
|
|
|
|
project is public website and user hasn't specified framework, propose
|
|
|
|
silently pick React CRA.
|
|
|
|
Astro and explain why not SPA. Never silently pick React CRA.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## Web APIs — always versioned
|
|
|
|
## Web APIs — always versioned
|
|
|
|
|
|
|
|
Every endpoint versioned from day one: `/api/v1/...`, no bare `/api/`; the
|
|
|
|
All web API endpoints must be versioned from day one: `/api/v1/...`.
|
|
|
|
router mirrors it (`api/v1/routes/`). Breaking change → `v2`, the old
|
|
|
|
- New project → start at `/api/v1/`, no bare `/api/` routes.
|
|
|
|
version keeps working and clients migrate at their pace; non-breaking
|
|
|
|
- Breaking changes → new version (`v2`). Old version stays functional —
|
|
|
|
additions → current version. Each version is a self-contained contract,
|
|
|
|
clients migrate at own pace.
|
|
|
|
never bent to match a newer one.
|
|
|
|
- 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)
|
|
|
|
## 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 = memory/doc maintenance such as a
|
|
|
|
|
|
|
|
standalone `/capitalize` `/close` `/prune-memory` `/reconcile`) ·
|
|
|
|
|
|
|
|
`release/*` (off develop → main + back-merge develop) · `hotfix/*` (off main
|
|
|
|
|
|
|
|
→ main + develop + any open release). `master` → `main` everywhere.
|
|
|
|
|
|
|
|
|
|
|
|
Every git action follows gitflow — in a skill, or an ad-hoc commit made outside
|
|
|
|
Never commit code on `main` or `develop`: branch first as `<type>/<name>`
|
|
|
|
one on request. `main` (prod) · `develop` (integration, off main) · `feature/*`
|
|
|
|
(`.claude/**` memory/config commits are hook-exempt, following the work).
|
|
|
|
`bugfix/*` + `chore/*` (off develop → develop; `chore/*` = memory/doc
|
|
|
|
Branch, merge and delete only via the lib: `bash ~/.claude/lib/gitflow.sh
|
|
|
|
maintenance, e.g. standalone `/capitalize` `/close` `/prune-memory`
|
|
|
|
start <type> <name>` · `finish` · `delete <br>`. `finish` runs only on an
|
|
|
|
`/reconcile`) · `release/*` (off develop → main + back-merge develop) ·
|
|
|
|
explicit human signal ("merge it", "feature OK"), never because tests pass,
|
|
|
|
`hotfix/*` (off main → main + develop [+ any open release/*]). `master`→`main`
|
|
|
|
a plan step says merge, or "ship" implied it. Assistance flows (`/feat`
|
|
|
|
everywhere.
|
|
|
|
`/bugfix` `/hotfix`) and the standalone memory/doc skills auto-branch on a
|
|
|
|
|
|
|
|
protected base but commit in place on a working branch, never finishing, so
|
|
|
|
Never commit code directly on `main` or `develop`: branch first from the
|
|
|
|
they branch to `chore/*` via the aiguillage, not the `.claude/**` exemption.
|
|
|
|
correct base as `<type>/<name>` (`.claude/**` memory/config commits are
|
|
|
|
Deterministic backstops behind the doctrine: the pre-commit hook (blocks
|
|
|
|
hook-exempt, following the work). Branch/merge only via the lib, never by hand:
|
|
|
|
code commits on main/develop; exempts `.claude/**`, `.githooks/**`, merges,
|
|
|
|
`bash ~/.claude/lib/gitflow.sh start <type> <name>` · `… finish`. Run `finish`
|
|
|
|
the root commit), Gitea branch protection on both, and never `--no-verify`.
|
|
|
|
(merge) only on an explicit human signal ("merge it", "feature OK"), never
|
|
|
|
Every branch is pushed at `start`, every commit and merge as it lands
|
|
|
|
because tests pass, a plan step says "merge", or "ship" implied it. Assistance
|
|
|
|
(post-commit and post-merge hooks; warn, never block). A branch is deleted
|
|
|
|
flows (`/feat` `/bugfix` `/hotfix`) and the standalone memory/doc `chore`
|
|
|
|
only by `finish` or `delete`, local and `origin/` copy alike: never
|
|
|
|
skills auto-branch on a protected base but commit in place on a working branch,
|
|
|
|
`main`/`develop`, never a tip not merged into develop or main (explicit
|
|
|
|
never finishing — so those skills branch to `chore/*` via the aiguillage, not
|
|
|
|
ancestor check; `git branch -d` proves nothing once the branch has an
|
|
|
|
the `.claude/**` exemption. New/onboarded projects get the model + the
|
|
|
|
auto-pushed upstream). The reference-transaction hook vetoes any deletion
|
|
|
|
versioned hooks via `gitflow init`. Advisory, so deterministic backstops
|
|
|
|
or rename of `main`/`develop`. The four hooks run in every repo: `make
|
|
|
|
apply: the pre-commit hook (blocks code commits on main/develop, exempts
|
|
|
|
link` generates `githooks/` and sets the global `core.hooksPath`; a repo
|
|
|
|
`.claude/**` + `.githooks/**` + merges + the root commit) and Gitea branch
|
|
|
|
that ran `gitflow init` (new/onboarded projects) keeps its own `.githooks/`,
|
|
|
|
protection on `main`/`develop`. Don't lean on `--no-verify` to bypass them.
|
|
|
|
refreshed at session start. Foreign clone: `git config gitflow.protect
|
|
|
|
Every branch is pushed at `start` and every commit as it lands by the
|
|
|
|
false` / `gitflow.autopush false`; `GITFLOW_NO_PUSH=1` only for throwaway
|
|
|
|
post-commit and post-merge hooks (warn, never block, on failure). A branch
|
|
|
|
test repos. A branch ahead of its upstream is a defect, not a state.
|
|
|
|
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
|
|
|
|
## Security — non-negotiable defaults
|
|
|
|
|
|
|
|
Apply at every step: design, scaffolding, implementation, review.
|
|
|
|
Apply at every dev step: design, scaffolding, implementation, review.
|
|
|
|
- **Input & data**: never trust user input; validate type, length, format,
|
|
|
|
|
|
|
|
range. Sanitize before rendering (XSS), SQL (injection), shell (command
|
|
|
|
### Input & data
|
|
|
|
injection). Parameterized queries only; string concatenation into SQL is
|
|
|
|
- Never trust user input. Validate type, length, format, range before use.
|
|
|
|
an immediate blocker.
|
|
|
|
- Sanitize before rendering (XSS), before SQL (injection), before shell
|
|
|
|
- **Secrets**: never hardcoded (credentials, tokens, keys, URLs with auth),
|
|
|
|
(command injection).
|
|
|
|
not even in comments; env vars only, `.env.example` with placeholders. A
|
|
|
|
- Use parameterized queries / prepared statements. String concatenation
|
|
|
|
secret found in review → flag and stop.
|
|
|
|
into SQL = immediate blocker.
|
|
|
|
- **AuthN / AuthZ**: separate; AuthN never implies AuthZ. Check
|
|
|
|
|
|
|
|
authorization on every sensitive endpoint or function, not only at the
|
|
|
|
### Secrets
|
|
|
|
entry point. Default deny; explicit allowlist over implicit denylist.
|
|
|
|
- Never hardcode credentials, tokens, keys, or URLs containing auth info —
|
|
|
|
- **Dependencies**: none without stating what it does and why; prefer
|
|
|
|
not even in comments.
|
|
|
|
well-maintained, widely used packages, flag abandoned or single-maintainer
|
|
|
|
- Always use env vars. Provide `.env.example` with placeholder values only.
|
|
|
|
ones; never install a package from a random snippet without naming it.
|
|
|
|
- If secret appears in code during review, flag and stop — do not proceed.
|
|
|
|
- **Errors & logging**: no stack traces, internal paths or DB errors to end
|
|
|
|
|
|
|
|
users (log internally, generic message out); never log secrets, tokens or
|
|
|
|
### Authentication & authorization
|
|
|
|
PII, even at DEBUG; fail closed, deny on unexpected error.
|
|
|
|
- AuthN (who you are) and AuthZ (what you can do) separate. Never assume
|
|
|
|
- **Minimal privilege**: request only what is needed; temporary elevation
|
|
|
|
AuthN implies AuthZ.
|
|
|
|
scoped and reverted explicitly.
|
|
|
|
- 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
|
|
|
|
### Destructive tools & data loss
|
|
|
|
Written after 2026-09-21: a reviewer sub-agent traced `lftp mirror --delete`
|
|
|
|
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
|
|
|
|
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
|
|
|
|
seconds later the home, the NAS mount and 15 repositories were gone, four
|
|
|
|
days of work had never been pushed.
|
|
|
|
days of work never pushed.
|
|
|
|
- Claude never deploys and never runs a transfer or mirror tool (`lftp`,
|
|
|
|
- Claude never deploys and never runs a transfer or mirror tool (`lftp`,
|
|
|
|
`sftp`, `ftp`, `rsync --delete`). It writes or explains the runbook; the
|
|
|
|
`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.
|
|
|
|
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
|
|
|
|
- A destructive tool is never run "to see what it would do", not even on a
|
|
|
|
against a scratch tree. Trace it by reading. If a run is unavoidable, the
|
|
|
|
scratch tree: trace it by reading. If a run is unavoidable, the target is
|
|
|
|
target is a fresh `mktemp -d` path written literally in the same command,
|
|
|
|
a fresh `mktemp -d` path written literally in the same command, after a
|
|
|
|
after a dry-run whose output is shown.
|
|
|
|
dry-run whose output is shown.
|
|
|
|
- Recursive delete stays inside the project or the temp dir, on a literal
|
|
|
|
- Recursive delete stays inside the project or the temp dir, on a literal
|
|
|
|
relative path: never through a variable, `~`, `..`, a wildcard, or an
|
|
|
|
relative path: never through a variable, `~`, `..`, a wildcard or an
|
|
|
|
absolute path elsewhere. `chmod -R`, `chown -R`, `sudo`, docker volume
|
|
|
|
absolute path elsewhere. `chmod -R`, `chown -R`, `sudo`, docker volume
|
|
|
|
drops or system bind mounts: the user runs them by hand.
|
|
|
|
drops, 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
|
|
|
|
- A brief, plan step or test recipe never authorizes a sub-agent to do any
|
|
|
|
any of the above. A reviewer reads the script it reviews; it does not run
|
|
|
|
of this; a reviewer reads the script it reviews, it does not run it.
|
|
|
|
it.
|
|
|
|
- Everything is pushed as it lands (gitflow hooks): unpushed work is a
|
|
|
|
- Every commit is pushed as it lands (gitflow post-commit and post-merge
|
|
|
|
defect to fix now, not a state to keep.
|
|
|
|
hooks) and every branch at creation. Unpushed work is a defect to fix now,
|
|
|
|
|
|
|
|
not a state to keep.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
# Communication mode: radical honesty
|
|
|
|
# Communication mode: radical honesty
|
|
|
|
|
|
|
|
- TRUTH OVER COMFORT: point out flaws immediately, no sugarcoating, no "not
|
|
|
|
- TRUTH OVER COMFORT — Point out flaws immediately. No sugarcoating,
|
|
|
|
bad but…". ZERO COMPLACENCY: never validate an idea because I proposed
|
|
|
|
no "not bad but…".
|
|
|
|
it; judge arguments on merit.
|
|
|
|
- ZERO COMPLACENCY — Never validate idea just because I proposed it.
|
|
|
|
- BLIND SPOT DETECTION: look for what I'm missing (confirmation bias, hidden
|
|
|
|
Evaluate arguments on merit.
|
|
|
|
assumptions, ignored alternatives) and flag it without waiting.
|
|
|
|
- BLIND SPOT DETECTION — Actively look for what I'm missing: confirmation
|
|
|
|
- ACTIVE RESISTANCE: when I make a weak point, push back until I correct it
|
|
|
|
bias, hidden assumptions, ignored alternatives. Flag without waiting
|
|
|
|
or solidly justify it. UNCERTAINTY TRANSPARENCY: don't know → say so; no
|
|
|
|
for permission.
|
|
|
|
invention, no vague answers to save face.
|
|
|
|
- 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
|
|
|
|
# Tooling & skills
|
|
|
|
## Skill routing
|
|
|
|
## Skill routing
|
|
|
|
|
|
|
|
Skills route by name: match the request to the skill whose description
|
|
|
|
Most skills route by name — match the request to the skill whose
|
|
|
|
fits. Below, only the non-obvious cases: gstack fallbacks, disambiguation,
|
|
|
|
description fits (full list is in context). Rules below cover only the
|
|
|
|
cryptic names.
|
|
|
|
non-obvious cases: gstack fallbacks, disambiguation, cryptic names.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
- Product idea, "worth building?" → office-hours
|
|
|
|
- Product idea, "worth building?" → office-hours
|
|
|
|
- Bug / error / 500 → bugfix (full framework: gitflow, contract, fresh
|
|
|
|
- Bug / error / 500 → bugfix (gitflow, contract, fresh verifier/security
|
|
|
|
verifier/security gates, registries). investigate ONLY on explicit ask
|
|
|
|
gates, registries). investigate only on explicit ask for the gstack
|
|
|
|
for the gstack ecosystem (cross-project learnings, /freeze scope lock,
|
|
|
|
ecosystem (cross-project learnings, /freeze, long open-ended investigation)
|
|
|
|
long investigation with no immediate commit intent)
|
|
|
|
|
|
|
|
- feat / hotfix / bugfix distinguished by file count → see descriptions
|
|
|
|
- feat / hotfix / bugfix distinguished by file count → see descriptions
|
|
|
|
- Ship / deploy / PR → ship (ship-feature if gstack off)
|
|
|
|
- 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
|
|
|
|
- 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 ("tir groupé", fix + loop until clean) → tour
|
|
|
|
- Grouped all-axes sweep (clean+security+reconcile+doc, "tir groupé",
|
|
|
|
- Open-work inventory / "queue empty?" / stale TODO vs git → reconcile
|
|
|
|
tour of one or more projects, fix + loop until clean) → tour
|
|
|
|
- Design / UI (build, system, audit, polish) → "Design work" below
|
|
|
|
- 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
|
|
|
|
- Architecture review → plan-eng-review
|
|
|
|
- Before /clear or /compact → capitalize; end-of-session ritual → close
|
|
|
|
- Before /clear or /compact → capitalize; end-of-session ritual → close
|
|
|
|
- SEO+GEO → seo (GEO only → geo)
|
|
|
|
- SEO+GEO → seo (GEO only → geo); W3C + WCAG a11y → web-validate;
|
|
|
|
- W3C + WCAG a11y (HTML/CSS validity, axe, pa11y) → web-validate
|
|
|
|
security audit (secrets, CVE, OWASP) → cso
|
|
|
|
- Security audit (secrets, CVE, OWASP) → cso
|
|
|
|
|
|
|
|
- New project → init-project; onboard existing repo → onboard
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
gstack OFF → its skills (investigate, ship, qa, review, health, retro,
|
|
|
|
gstack OFF → its skills (investigate, ship, qa, review, health, retro,
|
|
|
|
office-hours, context-save…) are gone: use the fallback above, else say so.
|
|
|
|
office-hours, context-save…) are gone: use the fallback above, else say so.
|
|
|
|
|
|
|
|
|
|
|
|
## Design work — full toolchain (tiered by scope)
|
|
|
|
## Design work — full toolchain (tiered by scope)
|
|
|
|
|
|
|
|
|
|
|
|
Trigger = UI work: editing a component/style file (.tsx/.vue/.svelte/.css…)
|
|
|
|
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
|
|
|
|
or a design/UI request, not the word "design" alone. Single source for
|
|
|
|
source for design routing; the design-toolchain hook reinforces it.
|
|
|
|
design routing; the design-toolchain hook reinforces it.
|
|
|
|
- Trivial (≤2 files, one cosmetic value) → /hotfix, no toolchain.
|
|
|
|
- Trivial (≤2 files, one cosmetic value) → /hotfix, no toolchain.
|
|
|
|
- Build UI (component, page, redesign) → ui-ux-pro-max + frontend-design
|
|
|
|
- Build UI (component, page, redesign) → ui-ux-pro-max + frontend-design
|
|
|
|
(anti-slop) + 21st-ui-build (catalog + generation) + emil-design-eng
|
|
|
|
(anti-slop) + 21st-ui-build (catalog + generation) + emil-design-eng
|
|
|
|
(polish) + design-motion-principles (if motion) + design-html (if static).
|
|
|
|
(polish) + design-motion-principles (motion) + design-html (static).
|
|
|
|
Post-build floor: `npx impeccable detect <files>` (45 deterministic
|
|
|
|
Post-build floor when impeccable is installed: `npx impeccable detect
|
|
|
|
anti-slop rules, exit 2 = findings) when impeccable installed.
|
|
|
|
<files>` (45 deterministic anti-slop rules, exit 2 = findings).
|
|
|
|
- Design system / brand → design-consultation first, then the build tools.
|
|
|
|
- Design system / brand → design-consultation first, then the build tools.
|
|
|
|
- Review / audit → design-review + emil-design-eng + design-motion-principles
|
|
|
|
- Review / audit → design-review + emil-design-eng + design-motion-principles
|
|
|
|
+ 21st-ui-review + /impeccable audit|critique + `impeccable detect` floor.
|
|
|
|
+ 21st-ui-review + /impeccable audit|critique + `impeccable detect` floor.
|
|
|
|
Scope doubt → don't silently skip: ask, or default to Build tier.
|
|
|
|
Scope doubt → ask or default to Build, never silently skip. Gate: light
|
|
|
|
Gate: lightweight skills run `~/.claude/lib/design-gate.md`; orchestrators via
|
|
|
|
skills run `~/.claude/lib/design-gate.md`, orchestrators plugin-check. 21st =
|
|
|
|
plugin-check. 21st = CLI (`npm i -g @21st-dev/cli`, `21st login`), no MCP,
|
|
|
|
CLI (`npm i -g @21st-dev/cli`, `21st login`), no MCP, no key; search free,
|
|
|
|
no API key. Search is free; `21st get` and `21st generate` are metered —
|
|
|
|
`21st get`/`generate` metered → generation, not micro-tweaks.
|
|
|
|
generation, not micro-tweaks.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## graphify
|
|
|
|
## graphify
|
|
|
|
|
|
|
|
|
|
|
|
bastien