speedy-claude: Instructions file for Claude Code

Global Rules

Operating Style (applies to every response)

• Think before acting; read existing files before writing code. No redundant re-reads.
• Act autonomously on reversible steps; ask only before publishing, deleting, or other irreversible/outward-facing actions.
• One focused implementation pass — avoid write-delete-rewrite cycles.
• Verify with real command output before claiming anything works. Evidence before assertions.
• Concise output, thorough reasoning. No sycophancy, no filler. If unsure, say so; never invent file paths.
• Parked skills live in ~/.claude/skills-available/ (see its README to restore).
• Third-party skills/plugins/MCP servers are prompt+code injectors: ALWAYS run the skill-security-review skill on the exact source ref before installing — the install gate denies unmarked installs; append --security-reviewed only after a PASS verdict.

File Editing Rules (enforced by hooks)

• Never create or modify files via shell. No cat > f <<'EOF', cat >> f, echo/printf > f, sed -i, perl -i, or inline python3 - <<EOF rewriters. edit-enforce.sh denies these; they bypass context anchoring, diffing, and syntax checks.
• Use Edit for surgical changes (requires a unique context anchor — ambiguity fails loudly instead of corrupting) and Write for new/whole files. Both are prompt-free under acceptEdits and syntax-checked on save by syntax-check.sh (per-type gates: jq json · yq yaml · taplo toml · ruff py · bash -n sh · esbuild parse-gate ts/js 6.8ms + project-tsc tier-2).
• Bulk mechanical replaces: sd / ambr (fast, blessed). Identifier/structure-shaped changes: ast-grep. Semantic multi-file changes: Edit per file.
• Capturing command output to a file (xh ... > resp.json) is fine; generating file content through the shell is not.
• After any structural edit, fix syntax errors reported by the PostToolUse check before moving on.
• Verify every 3rd edit to the same file: run/build/test it then, not after the 5th (observed failure mode: five blind edits, then the first run crashes).
• >5 planned changes to one file = re-read once and do a single whole-file Write, not 3 Reads + 7 Edits of churn.
• Automation architecture (doctrine): glue logic in TypeScript run by Bun (bun hooks/x.ts) — typed, testable, real parsers (e.g. shell-quote AST for command analysis, NEVER regex against shell text). Heavy operations go to native CLI tools launched with ARGUMENT ARRAYS (no shell re-parsing, no quoting bugs), batched — one rg over 10k files, not 10k launches. Rust only when profiling proves a bottleneck. Plain bash remains for trivial one-liners only.
• Markdown is auto-formatted on every save (md-format.sh → prettier, GFM, prose preserved). Do not hand-align tables — write them loosely and let the formatter tidy; re-read after bulk writes.