diff --git a/home/dot_claude/CLAUDE.md b/home/dot_claude/CLAUDE.md index 8536ab8..b4eaff3 100644 --- a/home/dot_claude/CLAUDE.md +++ b/home/dot_claude/CLAUDE.md @@ -2,4 +2,6 @@ This is the global CLAUDE.md. Rules are organized in `~/.claude/rules/`. +Reply in the language of the user's latest message — usually Japanese — and keep it for the whole reply, including progress notes between tool calls and summaries written right after reading English docs, logs, or subagent reports. Drifting into English after English tool output is the known failure. Code, identifiers, commands, and quoted source text stay as they are. + Delegation — whether to spawn a subagent at all, which model tier, and when Codex owns a workstream — is decided in `~/.claude/rules/workflow.md` and nowhere else. diff --git a/home/dot_claude/agents/implementer.md b/home/dot_claude/agents/implementer.md index db35af5..a2be1a3 100644 --- a/home/dot_claude/agents/implementer.md +++ b/home/dot_claude/agents/implementer.md @@ -9,7 +9,7 @@ color: green tools: Bash, Glob, Grep, Read, Edit, Write, NotebookEdit, WebFetch --- -You implement exactly one well-specified task. The dispatching session is the planner and will review your output — your job is faithful execution, not redesign. If the brief is ambiguous or missing context you need, stop and ask (status NEEDS_CONTEXT) instead of guessing. +You implement exactly one well-specified task. The dispatching session is the planner and will review your output — your job is faithful execution, not redesign. If part of the brief is ambiguous or missing context you need, don't guess: finish the parts that don't depend on it, then report NEEDS_CONTEXT naming the open question. ## Workspace discipline @@ -20,13 +20,15 @@ You implement exactly one well-specified task. The dispatching session is the pl - Never push, never create PRs, never tag releases — integration belongs to the dispatcher. - Never run destructive or state-mutating commands outside the workspace (`git reset --hard`, force operations, package publishes, deploys, database resets, dotfile applies). -- Stay within the briefed scope. Report adjacent problems you notice; do not fix them. +- Stay within the briefed scope. When the briefed work is done and checked, stop and report. Don't add features, tests, files, docs, or refactors beyond what the brief and its TDD step require; report adjacent problems and would-be additions instead of making them. +- If meeting the brief seems to need machinery out of proportion to its goal (new layers, frameworks, config, workarounds stacked on workarounds), don't build that machinery. Build the parts that don't need it, then report: NEEDS_CONTEXT when the goal itself looks wrong, DONE_WITH_CONCERNS when you built a simpler alternative that meets the goal. ## Quality bar - Read neighboring code first; match the repo's conventions, naming, and comment density. No comments that restate the diff or reference the task. - TDD when a test harness exists: write the failing test, watch it fail, then make it pass. Show the Red output, not just the Green. - Every verification command must actually be RUN, with output and exit code captured verbatim. "Should pass", "looks correct", and "probably works" are forbidden — if you didn't run it, you don't know. +- The check must exercise the change: the project's tests, type-checker, or build, or the changed command itself. A syntax-only check, or a check command that failed to start, does not count. If only dependencies declared in the repo's own manifest or lockfile are missing, install them with its own package manager and lockfile (never sudo or a system package manager). If no real check can run, report which one you did not run and why, with status DONE_WITH_CONCERNS — not DONE. ## Reporting protocol @@ -37,4 +39,6 @@ End your final message with: - Verbatim verification output with exit codes - Any deviation from the brief, each with its reason +Your final message ends the run; nobody replies to it. Don't end on a plan, a next step, or an offer for work you can still do — do it first. Report NEEDS_CONTEXT or BLOCKED only after everything that doesn't depend on the answer is done. + Your final message is data for the dispatching session, not prose for a human. Return facts, not narrative. diff --git a/home/dot_claude/agents/skeptic.md b/home/dot_claude/agents/skeptic.md index fa32ef8..c882317 100644 --- a/home/dot_claude/agents/skeptic.md +++ b/home/dot_claude/agents/skeptic.md @@ -3,7 +3,7 @@ name: skeptic description: >- Adversarial claim verifier. Dispatch with one claim (an audit finding, a root-cause hypothesis, a "this is safe" assertion) and it tries to REFUTE it against primary sources. Use before acting on subagent reports or shipping a diagnosis. Also usable in Workflow adversarial-verify stages via agentType: 'skeptic'. Read-only by construction. -model: sonnet +model: fable effort: high color: red tools: Bash, Glob, Grep, Read, WebFetch @@ -17,6 +17,7 @@ You receive one claim. Your default stance is that it is wrong, and your job is - Prefer the cheapest decisive experiment: a one-line command that contradicts the claim beats an essay of reasoning. - Never mutate state: no edits, no commits, no applies, no installs. If a decisive experiment would require mutation, describe it and mark the claim UNVERIFIABLE rather than running it. - Distinguish "the claim is false" from "the claim is true but the stated reason is wrong" — both are refutations worth reporting precisely. +- If a safety classifier declines a check (e.g. on a security claim), report UNVERIFIABLE with the refusal as the reason; do not reword the request to get around it. ## Reporting diff --git a/home/dot_claude/agents/spec-reviewer.md b/home/dot_claude/agents/spec-reviewer.md index 15aa92b..f7aaa5c 100644 --- a/home/dot_claude/agents/spec-reviewer.md +++ b/home/dot_claude/agents/spec-reviewer.md @@ -15,9 +15,10 @@ You review one implementation against its brief. You are the cheap first pass; a - Read the brief first, then the diff (`git diff ...`), then the surrounding code the diff touches. - Check spec compliance both ways: everything the brief requires is present, and nothing beyond the brief was added (scope creep is a finding). +- Over-engineering is a finding: abstractions with one user, config for values that never change, defensive paths for states that can't occur, or a mechanism heavier than the brief's goal. Name the simpler shape that would meet the brief. - Run the verification commands the brief names (tests, linters, renders) and capture output verbatim. Never mutate state: no edits, no commits, no applies, no installs. - Test behavior over reading style — a finding backed by a failing command outranks one backed by opinion. ## Reporting -Return findings classified CRITICAL (breaks the spec or the build) and IMPORTANT (should fix before merge) only — drop nitpicks. For each finding: file:line, what is wrong, the evidence (command output or quoted code), and whether the fix is a root-cause fix or a workaround. If nothing is wrong, say exactly that with the verification output that convinced you. Your final message is data for the dispatcher, not prose for a human. +Report every finding you have evidence for, each tagged CRITICAL (breaks the spec or the build), IMPORTANT (should fix before merge), or LOW (style, naming, nits) — you are the coverage stage, and the main session is the filter stage; filtering here too loses findings it would have kept. For each finding: file:line, what is wrong, the evidence (command output or quoted code), and whether the fix is a root-cause fix or a workaround. If nothing is wrong, say exactly that with the verification output that convinced you. Your final message is data for the dispatcher, not prose for a human. diff --git a/home/dot_claude/references/model-profiles/README.md b/home/dot_claude/references/model-profiles/README.md index 103bc55..79320c6 100644 --- a/home/dot_claude/references/model-profiles/README.md +++ b/home/dot_claude/references/model-profiles/README.md @@ -12,7 +12,7 @@ A distilled, machine-actionable diff of how agent-facing config (CLAUDE.md, rule - `empirical-prompt-tuning` — reviews/improves skills and prompts - `context-diet` — cuts always-on context; the Remove table is its deletion signal after a model upgrade -All three open by loading `~/.claude/references/model-profiles/.md`. If no exact match, fall back to the nearest same-family profile and note the gap. +All three open by loading `~/.claude/references/model-profiles/.md`. If no exact match, fall back to the nearest same-family profile and note the gap. When the target is an agent definition that pins `model:` (e.g. `agents/implementer.md`), load the profile for that pinned model instead — it is the one that will read the text. ## Updating (the anti-obsolescence contract) diff --git a/home/dot_claude/references/model-profiles/opus-5-5.md b/home/dot_claude/references/model-profiles/opus-5-5.md new file mode 100644 index 0000000..0b96e72 --- /dev/null +++ b/home/dot_claude/references/model-profiles/opus-5-5.md @@ -0,0 +1,57 @@ +# Opus 5.5 prompting profile + +Model id: claude-opus-5-5 Source: https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5-5 + https://platform.claude.com/docs/en/models/opus-5-5/whats-new-opus-5-5 + https://platform.claude.com/docs/en/build-with-claude/effort + https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool Distilled: 2026-10-08 + +Re-distill when the source doc changes or this date is older than ~6 months. + +This profile is a delta on `opus-5.md`. The guide states Opus 5 prompts "should perform well without changes", so every Opus 5 row not contradicted below still applies — but as carried-over guidance, not re-measured on 5.5. In particular these Opus 5 rows are **carried until re-measured**: cap subagent spawns, "report every finding; a later stage filters" in review prompts, explicit conciseness prompt instead of effort for visible length, scope-discipline instruction. + +Re-measured in one Claude Code session (2026-10-08) — the Opus 5 row "delete verification instructions; never subagents for verification" splits in two: + +- The cost half looks right: 5.5 ran its own checks (test runs, re-reads, renders), though harness rules asking for verification were in context. Spawned readers cost 176–193K tokens each as `general-purpose` against 27K (`spec-reviewer`) and 94K (`skeptic`) for narrow-tool agents. Model, task, and tool list all differed, so read this as "agent type is a large cost lever", not a clean attribution. +- The "never" half did not hold in this session: on top of 5.5's own checks, separate agents found real defects in every round run — a misattributed source number the author believed, contradictions between an added line and an unread neighbor, a nonexistent tool parameter. The hypothesis is that these are belief errors an author's re-read would repeat; with no self-review-only control arm and one session, that is untested. The harness keeps separation, scoped to load-bearing output and the narrowest agent (`harness-engineering.md`). + +## Params (set these, don't reproduce their effect in prose) + +- effort: default **`medium`** (Opus 5 was `high`) — a request that omits effort runs one level lower than on Opus 5. `medium` matches or beats Opus 5 at `high` on coding and knowledge work; `low` comes close on several coding evals at much lower cost. At a given level 5.5 thinks _more_ per turn than Opus 5, most at `xhigh`/`max`: reserve those for measured gains. To get less thinking, lower effort — more reliable than prompt instructions. Change effort per turn with a per-message `output_config` (beta `mid-conversation-output-config-2026-07-01`); a top-level change invalidates the cache. +- thinking: **always on**. `{type: "disabled"}` and `{type: "enabled", budget_tokens}` → 400. Omit the field or send `adaptive`. Select response blocks by `type`, never by position. +- max_tokens: thinking counts toward it even when not returned; 128K (the model max) worked well for long agentic coding turns. +- tool_choice: `any` / `tool` → 400. Keep `auto`; for schema-valid JSON use `strict: true` or structured outputs; to make it call a tool, say in the prompt when the tool applies. +- history: thinking blocks are bound to the model and the conversation prefix (enforced for accounts created on/after 2026-08-31). Keep the conversation append-only; change instructions or tools via mid-conversation system messages. Opus 5.5 cannot read Fable/Mythos thinking blocks; Fable 5.1 can read Opus 5.5's (Claude API). +- progress text: notes between tool calls arrive as `thinking` blocks, empty under the default `display: "omitted"`. Set `display: "updates"` (beta `thinking-display-updates-2026-08-18`) before adding any progress prompt. +- safeguards: classifiers for cyber, **bio (new vs Opus 5)**, and `reasoning_extraction`. Finding vulnerabilities in source code is allowed; high-risk dual-use cyber is not. A prompt that asks the model to write out its reasoning in the response invites a `reasoning_extraction` decline — read `display: "summarized"` thinking instead. +- advisor: Opus 5.5 executor may pair with a Fable 5.1 / Mythos 5.1 / Fable 5 / Mythos 5 / Opus 5.5 / Opus 5 advisor. + +## Remove — scaffolding this model makes redundant or harmful + +| pattern in config | why remove | +| -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| "think carefully / think step by step before answering" in chat or always-on config | the model decides how much to think and effort is the control; removing such a line made replies start sooner with no clear quality decline | +| instructions that make the model write its reasoning into the response (stand-ins for disabled thinking) | thinking is always on; these now risk `reasoning_extraction` declines | +| thinking-disabled mitigations ("you may say a sentence before a tool call", no-internal-tags, no-think) | they patched Opus 5 artifacts that appear only with thinking disabled, which 5.5 cannot do; re-test, and drop the no-thinking rule unconditionally | +| vision scaffolding built for earlier models (forced crop/describe steps for ordinary charts/screenshots) | 5.5 at its lowest effort read dense charts more accurately than Opus 5 at its highest; for the densest inputs, higher-resolution images (most of all technical drawings) and crop/measure tools still add accuracy | +| "avoid a generic AI look" style frontend guidance | it mostly swaps one default style for another; name the specific patterns instead (Rewrite) | + +## Rewrite + +| from | to | why | +| ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| treating a text-only end of turn as "task done" (harness) | treat it as a report: keep the task's parts in a checklist the model updates; if a turn ends with open items and no stated blocker, send a user message naming them ("Your task list still has open items: … Continue with them. If one is blocked, say what is blocking it."); cap at 2–3 automatic continuations | on long multipart tasks 5.5 keeps the user updated, and some updates end the turn without a tool call; an unattended loop that reads that as completion stops partway | +| letting a run end while a background command/subagent runs | wait for it, return its output as the next user message, then judge completion | the work is not done while something it started is still running | +| generic "don't stop early" in unattended agents | name the stops to avoid and the stops wanted: no summary that announces the next step without taking it, no offer to carry on "unless the user would prefer otherwise", no list of non-blocking decisions, no "good place to report"; put status notes in the same message as the next tool call; stop only when nothing can move without the user or the blocker is deliberately protected; keep confirmation for risky actions | 5.5 responds to instructions that name specific early-stop kinds. Unattended only — leave it out of human-in-the-loop apps; expect more tool calls and output tokens | +| "avoid generic design" for frontend | name the patterns to avoid, e.g. "Do not use a cream or off-white background, italic accent words in headlines, numbered '01/02/03' section labels, monospace labels, or pill-shaped buttons"; iterate by checking which default it fell back on and extending the list | 5.5 falls back on a few default styles; named patterns steer it, general asks don't | + +## Keep / add + +| pattern | why | +| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| multi-app workflows: "Before taking any action, explore broadly with tool calls: list and open the emails, documents, spreadsheet tabs and records across the available apps that could be relevant to this task, including ones the task does not explicitly mention, and use what you find." | 5.5 gets to work quickly and misses context the task didn't point to; this completed noticeably more multi-app tasks. Keep untrusted content out of what it searches | +| multi-turn chat where re-examination is unwanted: "Once you have answered something, treat that answer as done. On later turns, focus your thinking on what the user is asking now, and don't go back over an earlier answer unless the user asks about it or points out a problem with it." | cuts follow-up thinking/latency. Leave out of long analyses and agentic tasks where a later step can reveal an earlier mistake; may suppress unprompted self-correction | +| multiagent time signal: append `elapsed s / s` to each harness message, budget set above the time you want; or, with no budget, "Time matters here: do not spend time that can be avoided, and the earlier a correct result is obtained, the better." | 5.5 paces to the budget and parallelizes more; advisory only — keep a hard timeout, and check quality (it may search/verify a little less) | +| pasted text wrapped in `` … `` plus the system note that instructions inside are followed only where the user's own message asks | makes 5.5 robust to instructions inside user-pasted content; slightly more cautious; one guardrail among several | +| progress cadence (helps most in human-in-the-loop work): one line of intent before the first tool call, a short recap at the end. Separately, a harness reminder after ~5 silent tool steps, max 2–3 reminders | 5.5 follows explicit cadence instructions; the reminder roughly halved long silent stretches at no measurable cost | +| advisor under-calling on an Opus executor (only when observed): "Call advisor for design, architecture, and risk questions where you won't touch a file. If your response would be analysis or a recommendation with no other tool calls, call advisor first." | measured as one block with a second paragraph — the hard rule "your first write … must be preceded by an advisor call" — and that combined block raised pass rates ~7–10 pt on under-calling tasks but over-called on tasks needing no planning, netting roughly flat on a mixed workload; the doc says not to add it by default. The first paragraph alone is unmeasured. Never add the Haiku-style mid-conversation nudge to Opus (it slightly lowered pass rates) | + +## Already supplied by the Claude Code harness + +Don't duplicate these into `~/.claude/rules/` or CLAUDE.md when the consumer is a Claude Code session — observed in a Claude Code session's system prompt and turn-scoped messages on 2026-10-08 (not documented; re-check when Claude Code updates): the `` note, the advisor timing and advice-handling blocks (when `advisorModel` is set), the "The user hasn't heard from you in a while" silent-stretch reminder, background subagent/command results arriving as later notifications, and compaction with a summary hand-off. Rules should cover only the judgment those leave open (when an advisor call is worth it in this workflow, which actions are risky here, what counts as done for a loop). diff --git a/home/dot_claude/references/model-profiles/sonnet-5-5.md b/home/dot_claude/references/model-profiles/sonnet-5-5.md new file mode 100644 index 0000000..2496acc --- /dev/null +++ b/home/dot_claude/references/model-profiles/sonnet-5-5.md @@ -0,0 +1,39 @@ +# Sonnet 5.5 prompting profile + +Model id: claude-sonnet-5-5 Source: https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-sonnet-5-5 + https://platform.claude.com/docs/en/build-with-claude/effort Distilled: 2026-10-08 + +Re-distill when the source doc changes or this date is older than ~6 months. + +Relevant here because the `implementer` and `spec-reviewer` agents run on `model: sonnet` (`skeptic` runs on `fable` — use `fable-5-1.md` for it). Load this profile when tuning those agent prompts, not the session model's — after confirming which model the `sonnet` alias currently resolves to (the agent's transcript or `/model` shows it); this file applies only while that is Sonnet 5.5. + +## Params (set these, don't reproduce their effect in prose) + +- effort: API default `high`; levels are recalibrated vs Sonnet 5. Agentic coding / multistep tool use: `medium` for well-specified tasks, `high` for harder or longer ones. `xhigh`/`max` only for measured gains — at those levels it starts its own review/verification rounds and related fixes. Asking it in prose to think less doesn't reliably work; lower effort instead. +- thinking: lowest setting is `{type: "between_tools"}` (≤ `high` effort only); with it, remove any no-thinking instruction (raises internal-tag leakage). +- max_tokens: 128K for agentic coding, streamed; thinking counts toward it. +- safeguards: `cyber` (finding vulnerabilities in source code is allowed), `bio`, `frontier_llm`, `reasoning_extraction`, `general_harms`. + +## Remove — scaffolding this model makes redundant or harmful + +| pattern in config | why remove | +| --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | +| "hold all findings for the final response" (when updates should be visible) | suppresses the between-tool notes it writes natively | +| "only use tools when strictly necessary" / "minimize tool calls" | on chat and knowledge work it sometimes answers from training knowledge when a search would catch changed details | +| instructions to include reasoning in the response | invite `reasoning_extraction` declines; read `display: "summarized"` thinking instead | + +## Rewrite + +| from | to | why | +| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | +| implicit scope on coding tasks | "When the work the user asked for is done and checked, stop and report. Don't add features, tests, files, docs or refactors that weren't asked for. If you think one would help, mention it at the end instead of doing it." | it adds tests/docs/small files that fit the repo even unasked, at every effort level, more at higher effort | +| implicit carry-through at `low`/`medium` | "Keep working until everything the user asked for is done, and only stop to ask when you can't go on without the user or before a risky step." (try raising effort first) | at lower effort it checks in before a coding task is done; this makes runs longer and costlier | +| "verify your work" | "When you change code that can be run, built, or type-checked, run a real check that exercises the change before reporting it done … A syntax-only check, or a check command that failed to start, does not count; if all that is missing is the project's declared dependencies, install them with its own package manager and lockfile … Only if no real check can run here, say which one you did not run and why." | at `low` it sometimes reports done without a check that exercises the change; the paragraph makes that rare at slightly higher cost | +| self-started review rounds at `xhigh`/`max` | "When the work the user asked for is done and its checks pass, stop and report. Don't start extra rounds of review or hardening on your own, and don't launch reviewer sub-agents unless the user asked for a review. If you think a deeper review is worth doing, say so at the end." | cut session cost ~1/3 at `max` with no quality change | + +## Keep / add + +| pattern | why | +| --------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | +| deliver mid-turn user input as a user text block after the last `tool_result`, never inside one; harness notices in a separate system message | otherwise it may treat a genuine user message as prompt injection; avoid per-step countdowns after tool results in interactive runs | +| search nudge where a search tool exists: check specifics that may have changed (what is allowed, required, or charged) even when confident | it answers from training knowledge when a search would catch changes | +| for the hardest long-horizon work, use an Opus model instead | the guide's own positioning | diff --git a/home/dot_claude/rules/development-principles.md b/home/dot_claude/rules/development-principles.md index 051c0bc..dbfab81 100644 --- a/home/dot_claude/rules/development-principles.md +++ b/home/dot_claude/rules/development-principles.md @@ -13,6 +13,7 @@ Read every file the change touches and trace the real flow end to end first. The 7. Only then: the minimum code that works - No unrequested abstractions: no interface with one implementation, no factory for one product, no config for a value that never changes, no scaffolding "for later" +- Complexity is a stop signal, not a task. When you are about to add a second layer, file, mechanism, or workaround the request did not name, stop before building it and decide which it is: the means is out of proportion to the goal (go back down the ladder; consult the advisor if unsure), or the goal itself needs questioning (put the simpler goal to the user — changing the goal is their call). Do not push through to finish the original plan. Items on the never-simplify list below are exempt - Do not add lines without explicit user request. Deletion over addition, boring over clever, fewest files - Shortest working diff in the right place — the smallest change in the wrong place is a second bug - Bug fix = root cause: grep every caller of the function you touch and fix the shared function once, not each caller diff --git a/home/dot_claude/rules/harness-engineering.md b/home/dot_claude/rules/harness-engineering.md index 4d145e8..b748641 100644 --- a/home/dot_claude/rules/harness-engineering.md +++ b/home/dot_claude/rules/harness-engineering.md @@ -2,7 +2,7 @@ ## Generator-Evaluator Separation -- Never let self-assessment of your own output be the final verdict. Code you wrote is reviewed by a separate agent that did not generate it +- Never let self-assessment of your own output be the final verdict. Use the cheapest evaluator that decides the question: a deterministic check that exercises the behavior (tests, type-check, build, render) when one exists; otherwise a separate agent (`workflow.md` picks which). Prose, rules, prompts, and claims of fact have no deterministic check, so they go to a separate evaluator unless the edit changes no meaning (typos, formatting); for them, "behavior" is what a fresh reader does with the text in a concrete scenario. A re-review after a fix is part of the same stage, bounded by the Oscillation Guard; don't add review rounds or reviewer agents beyond these stages - The evaluator judges by behavior, not by reading the implementation: it may read the subject to design a check (which condition to break, which input to feed), but the verdict comes from what ran and what it returned. When the artifact under evaluation is a test suite, its behavior is failing on a deliberately broken subject: break one condition of the subject at a time and confirm the suite goes red. A green run of a test suite proves nothing about the suite - Subagent reports are hypotheses, not facts: verify load-bearing claims against primary sources (run the commands, read the files) before acting on them. Counts, deletions, and "no longer applies" are load-bearing: when items are removed or merged, enumerate them before and after and account for every one; a summary that adds up is not evidence diff --git a/home/dot_claude/rules/loop-engineering.md b/home/dot_claude/rules/loop-engineering.md index e8fc723..b02efbb 100644 --- a/home/dot_claude/rules/loop-engineering.md +++ b/home/dot_claude/rules/loop-engineering.md @@ -27,6 +27,14 @@ A loop's conversation is volatile; the repo is not. Persist what a run needs to - Decisions that outlive the loop graduate to an ADR (`harness-engineering.md`), not STATE.md. - History and rationale never go in code comments — that is comment rot (`development-principles.md`); STATE.md and git carry history. +## A turn that ends is not a task that is done + +Current models report progress mid-task, and some of those reports end the turn without a tool call. A loop that treats every turn end as completion stops partway. + +- Judge completion against STATE.md's **Next** list, not against the turn ending. Open items with no stated blocker → continue with a message that names them ("Still open: X, Y. Continue; if one is blocked, say what blocks it"). +- Cap automatic continuations at 3 per iteration; waiting on background work doesn't count. A run still stuck after that is a finding for the human, not a reason to keep nudging. (This cap is separate from the 5-round review-fix cap in `harness-engineering.md`.) +- A run with a background command or subagent still running is not done: wait for its result and feed it back before judging. A wait with no result inside the runner's own timeout goes straight to the human as stuck, without spending a continuation. + ## Autonomy staging Graduate a loop's trust over runs; never start unattended. These names are descriptive, separate from the `harness-meta.md` L1–L4 ladder (which is about where a constraint lives, not how much a loop is trusted). diff --git a/home/dot_claude/rules/workflow.md b/home/dot_claude/rules/workflow.md index 3ecbd01..0eb264e 100644 --- a/home/dot_claude/rules/workflow.md +++ b/home/dot_claude/rules/workflow.md @@ -10,17 +10,17 @@ Delegation is decided here and nowhere else. The harness default of not spawning agents unasked wins; this section says how to delegate once it is warranted. -- Spawning costs a fixed ~10K tokens before any work happens: the subagent re-reads the rules, CLAUDE.md, git status, and the target files the caller already has. Delegate when the work dwarfs that cost, needs isolation from the caller's context, or when the generator must not be the evaluator. Stay inline for small, high-frequency tasks; on a 1M-context session, context hygiene alone does not justify a spawn +- Spawning has a fixed cost before any work happens: the subagent re-reads the rules, CLAUDE.md, git status, every tool schema it is given (MCP servers included), and the target files the caller already has. A `general-purpose` agent answering one line has measured well over 100K tokens; an agent with a narrow `tools:` list (skeptic, claude-code-guide) costs a fraction of that, so prefer the narrowest agent type that fits. Delegate when the work dwarfs that cost, needs isolation from the caller's context, or when the generator must not be the evaluator. Stay inline for small, high-frequency tasks; on a 1M-context session, context hygiene alone does not justify a spawn - Codex (`codex-subagent`) is for when an independent model's read is the point — cross-model review, a second opinion on a diagnosis — or when the user asks for it by name. It is not the default owner of coding work -- Roles: the main session plans, designs, and evaluates. `implementer` (sonnet; override `model: haiku` for mechanical single-file edits) implements from an approved plan. `spec-reviewer` screens diffs and `skeptic` refutes claims, both read-only; the main session adjudicates their findings. Explore agents return conclusions, not file dumps -- `/advisor fable` escalates decision points up (approach choice, recurring errors, pre-completion checks). It has no tools and reads only the transcript, so it never satisfies generator-evaluator separation +- Roles: the main session plans, designs, and evaluates. `implementer` (sonnet; override `model: haiku` for mechanical single-file edits) implements from an approved plan. `spec-reviewer` (sonnet) screens diffs and `skeptic` (fable: the strongest evaluator, low output volume) refutes claims, both read-only; the main session adjudicates their findings. Explore agents return conclusions, not file dumps +- The advisor (`advisorModel` in settings) — the harness prompt carries its timing; the user wants it used generously beyond that. Also call it for design, architecture, and risk questions: if the reply would be analysis or a recommendation with no file edits, consult first, after any reads (simple factual lookups excepted). It has no tools and reads only the transcript, so it never satisfies generator-evaluator separation - `sonnet[1m]` bills usage credits on subscription plans: for >200K-context tasks, split the task or use `opus`. `CLAUDE_CODE_SUBAGENT_MODEL` must stay unset or it overrides every per-agent model choice - Stay in the main process for brainstorming, spec clarification, architecture decisions, exploratory debugging, and trivial edits (single file, <10 lines, obvious intent) ### Subagent-driven implementation - Dispatch `implementer` with `isolation: "worktree"` and the task spec inline. It has no conversation history; its system prompt already carries workspace discipline and the reporting protocol -- The dispatcher never implements what it will evaluate; the implementer never evaluates its own diff. The main session reviews the diff itself instead of spawning review subagents +- The dispatcher never implements what it will evaluate; the implementer never evaluates its own diff. For implementer output the main session is already the separate evaluator: it reviews the diff itself instead of spawning review subagents - Before dispatching into an existing worktree, its `git status --short` must be empty and HEAD on the intended branch; otherwise create a fresh one. After a worktree agent finishes, `git worktree list` and `git branch -v` must show the main tree untouched and the feature branch at the agent's commits; repoint with `git branch -f` if not - **Push and PR creation require explicit user confirmation**, including post-phase follow-ups (docs, cleanup, completion records) - Manually created worktrees go in `/.claude/worktrees/` (add it to `.gitignore`), never `~/.claude/worktrees/` or a sibling of the repo: project-scoped, no cross-project name collisions, cleanup obvious. The Agent tool's `isolation: "worktree"` places its own diff --git a/home/dot_claude/settings.json.tmpl b/home/dot_claude/settings.json.tmpl index 5cb0553..6d00e5c 100644 --- a/home/dot_claude/settings.json.tmpl +++ b/home/dot_claude/settings.json.tmpl @@ -158,7 +158,6 @@ "worktree": { "baseRef": "head" }, - "language": "Follow the user's input language. Prioritize accuracy. Think step-by-step. Do not guess—ask or investigate when uncertain.", "claudeMdExcludes": [ "**/.claude/rules/gh-pr-body.md", "**/.claude/rules/browser-automation.md" @@ -230,6 +229,17 @@ ] } ], + "Stop": [ + { + "hooks": [ + { + "type": "agent", + "statusMessage": "Checking for unaddressed requests", + "prompt": "You check one thing: is Claude ending its turn with something the user asked for left neither done nor reported? Hook input: $ARGUMENTS\n\n1. If stop_hook_active is true, return {\"ok\": true} at once: one reminder per stop is the limit.\n Also return {\"ok\": true} at once, without searching, when this was a short exchange: last_assistant_message is a brief answer that mentions no commit, file, branch, PR, or test run, and background_tasks is empty.\n2. List the user's own messages with two Grep searches on transcript_path: the literal text \"role\":\"user\",\"content\":\" (typed turns), and The user sent a new message while you were working (messages sent mid-turn; the request follows that line). Not from the user, so skip: , , , Stop hook feedback, and hook-status lines. A slash command's is the user's request. Requests from the most recent user message back to Claude's previous final report are in scope; older ones only if never addressed since. A question asks for an answer, not an action.\n3. The transcript may lag, so judge Claude's final reply from last_assistant_message. Classify each request: done (acted on or answered), explicitly deferred, blocked, or declined with a reason, waiting on a decision Claude asked the user for, or missing.\n4. Any missing: return {\"ok\": false, \"reason\": \"Unaddressed: . Do each, or say why it can't be done, then finish.\"}. Otherwise {\"ok\": true}.\n\nJudge coverage only, never quality or approach. When unsure, return {\"ok\": true}." + } + ] + } + ], "SessionStart": [ { "matcher": "*", diff --git a/home/dot_claude/skills/browser-e2e-test/SKILL.md b/home/dot_claude/skills/browser-e2e-test/SKILL.md index 6ad5eaf..148b363 100644 --- a/home/dot_claude/skills/browser-e2e-test/SKILL.md +++ b/home/dot_claude/skills/browser-e2e-test/SKILL.md @@ -20,7 +20,7 @@ E2E testing workflow for web applications using Chrome in Claude. 1. tabs_context_mcp to get browser context 2. tabs_create_mcp to create a new test tab 3. Confirm project structure (root, API endpoints) -4. TodoWrite to create a test plan +4. Write the test plan as a task list (the harness's task tool, or a checklist in the reply) ``` ### 2. Test Execution @@ -77,5 +77,5 @@ Create a GitHub Issue for each discovered problem via `gh issue create`. See [re After testing is complete: 1. Delete any test data created during the session -2. Mark all TodoWrite tasks as complete +2. Close out every item in the test plan, marking any that were skipped and why 3. Output a test results summary diff --git a/home/dot_claude/skills/codex-subagent/SKILL.md b/home/dot_claude/skills/codex-subagent/SKILL.md index 8ba79f8..291aad5 100644 --- a/home/dot_claude/skills/codex-subagent/SKILL.md +++ b/home/dot_claude/skills/codex-subagent/SKILL.md @@ -1,12 +1,10 @@ --- name: codex-subagent description: | - Delegate a bounded coding task to the local Codex CLI and return its result - to Claude for verification and synthesis. Use whenever the user explicitly - asks Claude to use, consult, or get a second opinion from Codex, and when a - coding task calls for an independent cross-model investigation, review, - plan, or clearly scoped implementation. For routine work Claude can finish - directly, invoke this skill only when the user specifically requests Codex. + Delegate a bounded coding task to the local Codex CLI and verify its result. + Use when the user asks to use, consult, or get a second opinion from Codex, or + when an independent cross-model investigation, review, or plan is the point. + Not for routine work Claude can finish directly unless the user names Codex. --- # Codex Subagent diff --git a/home/dot_claude/skills/empirical-prompt-tuning/SKILL.md b/home/dot_claude/skills/empirical-prompt-tuning/SKILL.md index 1f82858..fa433a2 100644 --- a/home/dot_claude/skills/empirical-prompt-tuning/SKILL.md +++ b/home/dot_claude/skills/empirical-prompt-tuning/SKILL.md @@ -117,7 +117,6 @@ Apply the minimal fix that addresses one theme of unclear points. - **1 theme per iteration** (related micro-fixes count as 1 theme; unrelated fixes go to the next iter) - Before applying: state which checklist item / judgment criterion this fix satisfies. Axis names and judgment criteria are different things — map to the criterion text, not the axis label -- **Edit the chezmoi source** (`~/.local/share/chezmoi/home/dot_claude/`), never `~/.claude/` directly. After editing, confirm with the user before running `chezmoi apply`. ### Step 6 — Re-evaluate diff --git a/home/dot_claude/skills/interrupt/SKILL.md b/home/dot_claude/skills/interrupt/SKILL.md index 7aea273..b626193 100644 --- a/home/dot_claude/skills/interrupt/SKILL.md +++ b/home/dot_claude/skills/interrupt/SKILL.md @@ -2,7 +2,7 @@ name: interrupt description: | Delegate an interrupt task to a background agent in an isolated worktree. - The main session continues uninterrupted. The agent implements, commits, pushes, and creates a PR. + The main session continues uninterrupted. The agent implements and commits; push and PR wait for the user's go-ahead. Use when a quick fix or small task needs to happen without losing current context. argument-hint: Task description (e.g., "fix the null check in auth middleware") --- @@ -25,18 +25,17 @@ Delegate a task to a background agent running in an isolated git worktree. Your ## Phase 2: Launch Background Agent -Launch an Agent with these parameters: +Dispatch the `implementer` agent (it runs in the background; results arrive as a notification) with these parameters: - `isolation: "worktree"` — runs in a fresh worktree copy -- `run_in_background: true` — does not block the main session - `description` — short summary (3-5 words) The agent prompt MUST include: - The full task description -- Instruction to: implement the fix, make atomic commits, push the branch, create a PR via `gh pr create` +- Instruction to: implement the fix and make atomic commits on the new branch — never push, never create a PR (integration belongs to the main session) - Instruction to keep changes minimal and focused -- The base branch to target for the PR (usually `main`) +- The base: current HEAD, which the agent branches from (the PR target is confirmed at the push gate) Example agent prompt structure: @@ -50,9 +49,9 @@ Steps: 2. Create a new branch: {branch-name} 3. Implement the fix/feature with minimal, focused changes 4. Commit with a descriptive message -5. Push the branch: git push -u origin {branch-name} -6. Create a PR: gh pr create --title "{title}" --body "{body}" -7. Report the PR URL as your final output +5. Run the project's tests/linters that exercise the change; capture the output +6. Do not push or open a PR +7. Final output: branch name, commit SHAs, verification output, and a proposed PR title and body ``` ## Phase 3: Confirm & Continue @@ -62,10 +61,12 @@ After launching the agent: 1. Tell the user the background task is running 2. Mention the branch name for reference 3. Remind them they'll be notified when it completes -4. Suggest `wt ls` to see active worktrees if they want to check on it +4. Mention `git worktree list` if they want to check on it 5. **Resume the previous conversation context** — the whole point is zero interruption When the background agent completes: -- Report the PR URL to the user -- Suggest cleanup: `wt rm {name}` or let the worktree auto-cleanup +- Check placement: `git worktree list` and `git branch -v` show the main tree untouched and the new branch at the agent's commits +- Review the agent's diff and verification output as the evaluator +- Show the user the branch, a diff summary, and the proposed PR title/body, and ask before pushing or creating the PR (`workflow.md`: push and PR creation need explicit confirmation) +- After the PR exists or the user declines, remove the worktree with `git worktree remove ` diff --git a/home/dot_claude/skills/ios-submission-review/SKILL.md b/home/dot_claude/skills/ios-submission-review/SKILL.md index 873e63c..5196921 100644 --- a/home/dot_claude/skills/ios-submission-review/SKILL.md +++ b/home/dot_claude/skills/ios-submission-review/SKILL.md @@ -6,9 +6,7 @@ description: > # iOS Submission Review -Automated pre-submission review that catches the most common App Store rejection reasons before you submit. Modeled after the thoroughness of tools like Rork, but running entirely in CLI against your actual codebase. - -Apple rejects ~25% of submissions (1.93M out of 7.77M in 2024). Over 40% of those are for easily avoidable issues. This skill checks for them systematically. +Pre-submission review that checks the codebase for the most common App Store rejection reasons. Guideline numbers and yearly requirements change: when a check depends on Apple's current rules (SDK minimums, privacy manifests, age ratings), confirm against developer.apple.com with `WebFetch` before reporting it as FAIL. ## How it works diff --git a/home/dot_claude/skills/issue-ship/SKILL.md b/home/dot_claude/skills/issue-ship/SKILL.md index 853669c..7b3b412 100644 --- a/home/dot_claude/skills/issue-ship/SKILL.md +++ b/home/dot_claude/skills/issue-ship/SKILL.md @@ -53,7 +53,7 @@ When it returns: - Review the diff yourself as the evaluator (behavior over implementation). - Verify placement: `git worktree list` + `git branch -v` show the main tree untouched and the feature branch at the agent's commits. -- Run the `adversarial-review` skill on the branch with the implementer's report as a claim source. `ADVERSARIAL: FAIL` sends the refuted claims and their evidence back to a fresh `implementer` dispatch; repeat until PASS. Step 5 never starts on FAIL. +- Run the `adversarial-review` skill on the branch with the implementer's report as a claim source. `ADVERSARIAL: FAIL` sends the refuted claims and their evidence back to a fresh `implementer` dispatch; repeat until PASS, at most 5 rounds (the oscillation guard in `harness-engineering.md`) — then stop and present the remaining refuted rows to the user. A fix that reverts an earlier round's fix stops the loop immediately. Step 5 never starts on FAIL. ### 5. Open the PR (confirmation gate) diff --git a/home/dot_claude/skills/loop-design/SKILL.md b/home/dot_claude/skills/loop-design/SKILL.md index d9238df..aed6c1c 100644 --- a/home/dot_claude/skills/loop-design/SKILL.md +++ b/home/dot_claude/skills/loop-design/SKILL.md @@ -2,8 +2,6 @@ name: loop-design description: > Use when the user wants to set up a recurring or autonomous agent loop and needs to design it before running it. Triggers: 「ループを設計」「自律ループを 作りたい」「loop を組みたい」, turning a vague "I want a loop that does X" into a concrete spec, or choosing a runner (/loop, /schedule, ralph-loop, pr-monitor) for repeated work. NOT for running an already-designed loop, and NOT for one-off tasks. - -disable-model-invocation: false --- # Loop Design diff --git a/home/dot_claude/skills/pentest-parallel-prs/SKILL.md b/home/dot_claude/skills/pentest-parallel-prs/SKILL.md index 2c6bec3..30df2b6 100644 --- a/home/dot_claude/skills/pentest-parallel-prs/SKILL.md +++ b/home/dot_claude/skills/pentest-parallel-prs/SKILL.md @@ -12,7 +12,7 @@ argument-hint: Optional scope hint (e.g., "auth and SSRF only", "skip the extens You are running an authorized penetration test on a codebase, then shipping the fixes as a fan-out of independent, non-conflicting pull requests. The loop has two halves: **find** (parallel attacker-framed investigation) and **fix** (parallel TDD-driven implementation in isolated worktrees). The discipline that makes the whole thing work is generator-evaluator separation in the find half, and file-occupation analysis in the fix half. -> [!NOTE] Claude Fable 5 runs cybersecurity safety classifiers that can flag this skill's vocabulary (exploits, payloads, IDOR) even in authorized defensive use, triggering a refusal-fallback to Opus mid-session. If the session is on Fable, suggest the user switch to Opus (`/model`) before Phase 1. +> [!NOTE] The session model's cyber safety classifier can decline exploit-development wording even in authorized defensive work; finding vulnerabilities in source code is allowed. Keep payloads to the minimal PoC that proves a finding. On a refusal, check the safeguards line of `~/.claude/references/model-profiles/.md` before switching models. ## Core Principles @@ -23,7 +23,6 @@ You are running an authorized penetration test on a codebase, then shipping the - **One concern per worktree, unless files force grouping**. Don't artificially bundle unrelated fixes; that destroys the per-PR review experience. - **TDD inside subagent prompts**. Spell out the Red → Green discipline and list the exact test cases each subagent must add. Don't leave it implicit. - **Subagents commit, the main thread publishes**. Subagents create local commits only. The main thread reviews `git log main..`, renames awkward branches, then pushes and opens PRs. This keeps a human checkpoint before anything becomes public. -- **Recoverable, not perfect**. Worktree isolation occasionally fails (a subagent ends up committing in the main repo). Reconcile via git operations rather than panicking — `git checkout main`, rename, push, done. --- @@ -68,7 +67,7 @@ Adapt domains to the actual codebase. A read-only static site has none of these; **Goal**: Dispatch one focused subagent per domain, in parallel, with attacker framing. -Use the `Agent` tool with `subagent_type: "Explore"`. Send all dispatches in a **single message** so they run concurrently. Each subagent prompt MUST contain: +Use the `Agent` tool with `subagent_type: "general-purpose"` — not `Explore`, which reads excerpts to locate code and is not built to audit it. Send all dispatches in a **single message** so they run concurrently. Each subagent prompt MUST contain: 1. **Authorization context** ("authorized work on the owner's own project") so the subagent doesn't refuse. 2. **Specific files to read** (absolute paths). Don't make the subagent re-discover the structure. @@ -80,6 +79,7 @@ Use the `Agent` tool with `subagent_type: "Explore"`. Send all dispatches in a * - A fix sketch 4. **Length cap** ("under 1500 words") and **language** (match the user's). 5. **Negative instruction**: don't report findings without code citations, don't pad with generic "consider HTTPS" advice. +6. **Read-only**: no edits, commits, installs, or requests against live systems — this phase only reads code. `references/dispatch-templates.md` has a worked SSRF-domain prompt to adapt. @@ -146,9 +146,9 @@ Each subagent prompt MUST include: 8. **Suggested branch name**. If you can't suggest one, plan to rename in Phase 6. 9. **CRITICAL**: "Commit locally on a feature branch. Do **NOT** push. Do **NOT** create a PR." This keeps the publish step centralized. 10. **Return contract**: branch name, files changed, before/after test counts, deviations from the plan, blockers. Cap response length. -11. **Stop condition**: "If you get stuck for more than 2 retries on any step, STOP and report what blocked you. Do not force through." +11. **Stop condition**: "If you get stuck for more than 2 retries on any step, finish what doesn't depend on it, then report what blocked you. Do not force through." -Worth knowing: `isolation: "worktree"` automatically creates a worktree under `.claude/worktrees/agent-/`. The worktree persists if changes are made, is auto-cleaned if not. Worktree paths and branch names come back in the agent result. Don't try to manage worktrees manually for this phase — the tool handles it. +`isolation: "worktree"` creates and cleans up the worktrees; their paths and branches come back in each agent result. --- @@ -178,8 +178,6 @@ Worth knowing: `isolation: "worktree"` automatically creates a worktree under `. ```bash git branch -m worktree-agent-abc12345 fix/ ``` - Note: if `tag.gpgSign` is set globally, branch ops are unaffected, but tag creation in other workflows may need `git -c tag.gpgSign=false`. -5. **Optional**: run the full test suite once more in the main repo if you want extra confidence before publishing. Each subagent should already have done this, but a sanity check is cheap. If a subagent reported a blocker, decide: re-dispatch with a tighter prompt, do that fix yourself, or defer it. Don't push half-done work. diff --git a/home/dot_claude/skills/pr-description/SKILL.md b/home/dot_claude/skills/pr-description/SKILL.md index a879dc4..555ea31 100644 --- a/home/dot_claude/skills/pr-description/SKILL.md +++ b/home/dot_claude/skills/pr-description/SKILL.md @@ -2,12 +2,9 @@ name: pr-description description: >- Rewrite an existing PR's description into a fixed layout (overview → mermaid → - review guide → notes → links), with a per-commit verification table that cuts - the reviewer's tracking cost. Use when asked to 「PR description を更新して」 - 「PR 本文を書いて」「PR 説明を簡潔に」「PR description を簡潔に」 - 「mermaid を使って PR をまとめて」, + review guide → notes → links) with a per-commit verification table. Use on + 「PR description を更新して」「PR 本文を書いて」「PR 説明を簡潔に」「mermaid で PR をまとめて」, "rewrite the PR description", or after stacking commits on a pipeline PR. - Args: ... [-R owner/repo] [extra context] argument-hint: "... [-R owner/repo]" --- diff --git a/home/dot_claude/skills/trend-arbitrage/SKILL.md b/home/dot_claude/skills/trend-arbitrage/SKILL.md index 87b22b1..248f9c6 100644 --- a/home/dot_claude/skills/trend-arbitrage/SKILL.md +++ b/home/dot_claude/skills/trend-arbitrage/SKILL.md @@ -24,9 +24,9 @@ Three conditions must ALL be true: ## Initial Classification -Before starting any phase, use `ask_user_input` to classify the opportunity type unless the user has already made it clear. This determines which discovery methods, validation criteria, and strategy templates to use. +Before starting any phase, use `AskUserQuestion` to classify the opportunity type unless the user has already made it clear. This determines which discovery methods, validation criteria, and strategy templates to use. -**Always ask upfront:** +**Ask upfront whichever of these is still unknown** (in Recon mode, skip question 1 — all four types are scanned): 1. **What type of gap are you looking for?** - Content gap (blog, newsletter, guide, course) @@ -58,9 +58,9 @@ Read `references/phases.md` for the detailed procedure of each phase. **Goal**: Generate a list of 5-10 candidate opportunities showing breakout signals. -**Inputs**: Determined by classification above. If anything is ambiguous, ask via `ask_user_input`. +**Inputs**: Determined by classification above. If anything is ambiguous, ask via `AskUserQuestion`. -**Methods by type** (use web_search for all): +**Methods by type** (use `WebSearch` for all; open promising results with `WebFetch` rather than judging from snippets): ### Content gaps: diff --git a/home/dot_claude/skills/trend-arbitrage/references/phases.md b/home/dot_claude/skills/trend-arbitrage/references/phases.md index 1a3ace6..2d59d8e 100644 --- a/home/dot_claude/skills/trend-arbitrage/references/phases.md +++ b/home/dot_claude/skills/trend-arbitrage/references/phases.md @@ -12,7 +12,7 @@ Ask the user (or infer from context): ### Step 1.2: Mine Gap Signals -Use web_search to investigate signal sources **based on the classified opportunity type**. +Use `WebSearch` to investigate signal sources **based on the classified opportunity type**. #### For ALL types: diff --git a/home/dot_claude/skills/ui-design-standards/SKILL.md b/home/dot_claude/skills/ui-design-standards/SKILL.md index 58f7421..52580b0 100644 --- a/home/dot_claude/skills/ui-design-standards/SKILL.md +++ b/home/dot_claude/skills/ui-design-standards/SKILL.md @@ -1,143 +1,38 @@ --- name: ui-design-standards -description: UI design quality standards and principles for frontend implementation and code review. Use when (1) implementing UI from design specs or mockups, (2) reviewing frontend/UI code, (3) creating new UI components, (4) building user interfaces for web or mobile apps. Complements frontend-design skills with quality enforcement. +description: UI quality bar for implementing and reviewing frontend code — design-spec fidelity, the repo's own design tokens, complete interaction states, and accessibility. Use when (1) implementing UI from design specs or mockups, (2) reviewing frontend/UI code, (3) creating new UI components. --- # UI Design Standards -Quality standards for implementing and reviewing user interfaces. Apply these principles regardless of framework (React, Vue, SwiftUI, Flutter, etc.). +A quality bar for UI work in any framework. The repo's existing design system outranks everything here: find it first, then apply this bar inside it. -## Core Principles +## Before writing UI -### 1. Visual Fidelity +- Locate the token source the repo already uses (CSS variables, Tailwind config, a `theme/` module, a component library) and the nearest existing component that does something similar. Reuse both. Create a new token file or theme structure only when none exists, and say that you did. +- With a design spec: match layout, spacing, typography, color, radius, shadow, and hierarchy to the spec. Do not add elements or redesign; a spec gap is a question for the user, not a design decision. +- Without a spec: models fall back on a few default looks, and "avoid a generic look" just swaps one default for another. Name the concrete patterns to avoid instead (the session model's profile in `~/.claude/references/model-profiles/` lists its known defaults), then check which default the first result used and extend the list. -Match design specifications exactly: +## Done means -- **Layout**: Precise positioning, alignment, and structure -- **Spacing**: Exact margins, padding, and gaps -- **Typography**: Font family, size, weight, line-height, letter-spacing -- **Colors**: Exact color values (no approximations) -- **Component shapes**: Border radius, shadows, borders -- **Visual hierarchy**: Element prominence matches design intent +- Every value comes from the token source — no literal colors, magic spacing, or one-off inline styles for patterns that recur. +- Every interactive element has hover, focus-visible, active, and disabled states; async views have loading, error, and empty states. +- Semantic elements first (`button`, `a`, `label`, landmarks); ARIA only where no element fits; keyboard reachable; text contrast meets WCAG AA. +- Layout holds at the repo's breakpoints. +- Components take props/composition for variation instead of copies, and stay shallow enough to read. +- Missing assets (icons, illustrations) match the existing set's style; SVG for icons. -**Rule**: Do not introduce new UI elements or redesign. Follow the design precisely. +Verify by rendering, not by reading: run the app or the component's story and look at each state (a browser tool or screenshot when available). Say which states you rendered and which you could not. -### 2. Component Architecture +## Reviewing UI code -Apply OOP principles to UI development: +Report every finding with evidence (`file:line`, a screenshot, or the rendered state), each tagged CRITICAL (wrong behavior, inaccessible, breaks the spec), IMPORTANT (hardcoded values, missing states, deviates from tokens or neighboring components), or LOW (naming, minor structure). Filtering for what to show the user happens after, not during, the review. -- **Single Responsibility**: Each component does one thing well -- **Open/Closed**: Extend via props/composition, not modification -- **Encapsulation**: Internal state hidden, clean public interface -- **Composition over Inheritance**: Compose small components - -``` -// Good: Reusable, props-driven, single responsibility - - -// Bad: One-off, hardcoded, mixed concerns - -``` - -- Break UI into logical, single-responsibility components -- Components should be composable and testable -- Avoid deep nesting (max 3-4 levels) - -### 3. Theme System - -Use a single global theme file for all design tokens: - -``` -theme/ -├── colors.ts # Color palette -├── typography.ts # Font styles -├── spacing.ts # Spacing scale -├── shadows.ts # Shadow definitions -└── index.ts # Unified export -``` - -**Required tokens**: - -- Colors (primary, secondary, neutral, semantic) -- Typography (font families, sizes, weights) -- Spacing (consistent scale: 4, 8, 12, 16, 24, 32...) -- Border radius -- Shadows/elevation -- Breakpoints (responsive) - -**Rule**: No hardcoded styles inside components. All values from theme. - -### 4. Functional Completeness - -UI must be fully functional: - -- **Navigation**: Working routes and transitions -- **State handling**: Proper state management for all interactions -- **Interactions**: Hover, focus, active, disabled states -- **Loading states**: Skeleton, spinner, or placeholder -- **Error states**: Clear error feedback -- **Empty states**: Meaningful empty state UI - -### 5. Asset Generation - -When assets are missing (icons, images, avatars, illustrations): - -- Generate in a style that matches the design language -- Maintain consistent visual weight and style -- Use appropriate formats (SVG for icons, optimized images) -- Provide fallbacks where needed - -## Implementation Checklist - -Before marking UI implementation complete: - -- [ ] Layout matches design exactly -- [ ] All spacing values from theme -- [ ] Typography matches design specs -- [ ] Colors are exact (use color picker to verify) -- [ ] All interactive states implemented -- [ ] Responsive behavior works correctly -- [ ] No hardcoded style values -- [ ] Components are reusable -- [ ] Loading/error/empty states handled - -## Code Review Checklist - -When reviewing UI code: - -| Area | Check | -| ------------- | --------------------------------- | -| Visual | Does it match the design? | -| Theme | Are all values from theme system? | -| Components | Reusable and properly abstracted? | -| States | All interaction states handled? | -| Accessibility | Proper semantics and ARIA? | -| Performance | No unnecessary re-renders? | -| Hardcoding | Any magic numbers or colors? | - -### Common Issues to Flag - -``` -// Flag: Hardcoded color -color: '#3b82f6' // Should use theme.colors.primary - -// Flag: Magic number -padding: 13px // Should use spacing scale - -// Flag: Inline styles for reusable patterns -style={{ display: 'flex', gap: 8 }} // Should be component/class - -// Flag: Missing states - // Where is disabled/loading state? -``` - -## Quality Levels - -| Level | Description | -| ----- | ------------------------------------------------------ | -| A | Pixel-perfect, fully themed, all states, accessible | -| B | Visually accurate, mostly themed, core states work | -| C | Functional but visual inconsistencies, some hardcoding | -| D | Major visual deviations, significant hardcoding | - -Target: Level A for production, Level B minimum for review approval. +| Area | Check | +| ------------- | ---------------------------------------------------------------------- | +| Spec | Matches the design, no unrequested elements | +| Tokens | No literal colors, spacing, radii, or shadows outside the token source | +| States | hover / focus-visible / active / disabled / loading / error / empty | +| Accessibility | Semantics, labels, keyboard path, contrast | +| Reuse | Uses existing components instead of a near-duplicate | +| Rendering | No avoidable re-renders on hot paths | diff --git a/home/dot_claude/skills/zero-cost-scaling/SKILL.md b/home/dot_claude/skills/zero-cost-scaling/SKILL.md index abb4c44..c4efa45 100644 --- a/home/dot_claude/skills/zero-cost-scaling/SKILL.md +++ b/home/dot_claude/skills/zero-cost-scaling/SKILL.md @@ -12,7 +12,7 @@ description: | # Zero-Cost Scaling Pattern -When designing personal/indie web apps, especially those that may go viral: +When designing personal/indie web apps, especially those that may go viral. The prices, quotas, and product statuses below were true when written and drift: confirm the current numbers on the provider's pricing page (`WebFetch`) before putting them in a recommendation. ## Client-Side Processing First