claude-config

Project-specific layer for /plan-review, loaded only when reviewing plans in the claude-config repo itself.

Write a cross-session handoff file at ~/.claude/handoffs/<descriptive-slug>-handoff.md capturing goal, status, task list, next step, files modified, active markers, open questions, and resume command.

Confirm claims at the primary source — fetch the official docs, spec, or source directly. TRIGGER when: researching a library, API, framework, or architecture/design decision; or acting on a documentation claim from a subagent, blog post, or other secondary source. DO NOT TRIGGER when: you want a multi-source research synthesis (that is a research-harness job, not source verification); quick syntax lookups; error decoding; or when the cited URL is already the primary source.

Produce a cold-start task briefing at ~/.claude/briefs/<slug>-task.md for a fresh session to pick up known, well-scoped work (abandoned PR, surfaced follow-up, ticket whose scope is settled). Distinct from /handoff, which captures mid-flight session state.

Review implementation plans before presenting to the user. TRIGGER when: an implementation plan has been written or updated in .claude/plans/ or is about to be presented to the user for review. DO NOT TRIGGER when: the plan is a trivial one-liner (single migration, config change), or the user has explicitly said to skip review.

Produce a signal-bucketed error-mode report from a delivered body of multi-session AI-assisted work — bucket every failure by which pipeline layer caught it, correlate transcript signals with PR review comments, and split output into a private, project-identifying report and a de-identified public lessons doc. Builds on transcript-narrative and transcript-analysis. Supports a multi-window trend pass to distinguish recurring patterns from one-off noise.

Principal-engineer review before presenting code. TRIGGER when: code is about to be presented, or the user asks for a code review. DO NOT TRIGGER when: cosmetic-only changes (typo, formatting, CSS with no behavioral delta); only one specialized file type staged (SKILL.md→skill-review, agent→agent-review, plan→plan-review, CLAUDE.md/AGENTS.md/memory→ai-instruction-and-memory-files); fresh review-markers/ entry covers the diff.

Audit of agent files: frontmatter, triggers, voice, length, duplication. TRIGGER when: authoring/reviewing a .claude/agents/*.md or plugins/*/agents/*.md change, or auditing trigger accuracy across the roster. DO NOT TRIGGER when: editing SKILL.md (use skill-review), editing CLAUDE.md/AGENTS.md/memory files (use ai-instruction-and-memory-files), or reviewing non-agent files.

Behavioral-equivalence audit of SKILL.md files (frontmatter, voice, length, duplication). Dispatched by name from /code-review and the require-skill-review hook — not auto-triggered by description.

Pre-handoff gate: runs verification, code review, syncs or opens a PR. TRIGGER when: handing off to a human reviewer — wrapping up a branch with an open PR, "ship it" intent, or before spawning a multi-persona review (CISO + staff-* engineers) or /ultrareview. DO NOT TRIGGER when: during active iteration, on diff-only requests, or on the default branch.

Verify and sync the current branch's open PR description against branch state — flag per-commit narratives, stale content claims, TBD markers, and files missing from the body; preserve coordination steps; apply the fix with gh pr edit. Dispatched from /ready-for-review step 4 and the /handoff pre-write checklist; also run standalone.

Testing conventions for writing tests in any codebase. TRIGGER when: planning tests for new code, writing test infrastructure (mocks, helpers, fixtures), or discussing test strategy for new features. DO NOT TRIGGER when: the task is purely mechanical (running tests, fixing a single assertion, updating a snapshot), or evaluating/debugging an existing test suite (use test-evaluation).

Dispatch to a subagent vs inline. TRIGGER when: full check suite or full-project verification; broad codebase search; first exploratory read; 2nd/3rd Bash toward same question; delegating implementation. DO NOT TRIGGER when: single-artifact targeted lookup (one file or value, not a multi-site sweep); comprehension read feeding your own writing/review/design; Edit/Write sequences where scope or content is still forming; the specific failure output or diff you reason over line by line.

Analyze Claude Code transcripts — model comparison by branch, test-failure convergence sequences, correction-signal frequency, active-vs-idle duration, subagent-vs-main turn split, PR-to-branch mapping, or per-session review-activity timelines (skill invocations, hook denials, reviewer spawns). For token-cost or cache-efficiency analysis use token-analyzer.py directly.

Post-apply cleanup for Lovable-duplicated migrations: diff originals, db reset, delete, open PR. TRIGGER when: the user signals Lovable's migration apply step completed, regardless of exact wording. DO NOT TRIGGER when: all originals already deleted, or user asks about mechanics without signaling completion.

Produces an implementation plan and hands off to /plan-review. TRIGGER when: asked for a plan or implementation strategy for work spanning multiple files or domains. DO NOT TRIGGER when: single-file tweaks, "just implement it" requests, or when a plan already exists (use /plan-review instead).

A playbook for debugging and root-cause investigation: establish the full symptom, verify tool ingestion, reproduce and capture the asymmetry, pull data for the specifically affected entities, then confirm the fix addresses the reported incident before shipping.

Produce a narrative case study / annotated timeline from Claude Code session transcripts — verbatim prompts, phase buckets, quantitative metrics, extracted lessons. For raw quantitative metrics use transcript-analysis.

Evaluate and debug existing test suites. TRIGGER when: reviewing or evaluating an existing test suite, debugging slow or flaky tests, assessing test coverage quality, or reviewing test code. DO NOT TRIGGER when: writing new tests (use test-conventions), or the task is purely mechanical (running tests, fixing a single assertion, updating a snapshot).

Error-handling: envelope, propagation, and capture rules for server-side APIs. TRIGGER when: reviewing server-side catch blocks, response formatters, telemetry capture, or serverless error boundaries; defining or auditing application error codes or the code registry; reviewing API error response shapes. DO NOT TRIGGER when: reviewing client-side error display only with no server path in diff; reviewing test assertions on error shapes without touching production code.

Audit of CLAUDE.md, AGENTS.md, and Claude Code auto-memory files. TRIGGER when: authoring/reviewing a CLAUDE.md, AGENTS.md, or ~/.claude/projects/*/memory/ change, or deciding which surface a rule belongs in. DO NOT TRIGGER when: editing .lovable/*.md, .agents/skills/*.md, .cursorrules, .github/copilot-instructions.md, README.md, or writing code.

Lovable's UI knowledge fields and workspace skill files — `.lovable/*.md` repo-mirror workflow, `.agents/skills/` propagation model, Project/Workspace scope split, precedence, review criteria. TRIGGER when: authoring or reviewing changes to `.lovable/*.md` or `.agents/skills/*.md`; drafting Project/Workspace Knowledge or workspace-skill changes. DO NOT TRIGGER when: not a Lovable project; editing CLAUDE.md or AGENTS.md; editing agent rules files; writing code.

Extract all comments from a .docx file (Google Docs / Word feedback) and present them grouped by document location with author and anchored text.

Review and audit of Claude Code hooks (.claude/hooks/*.sh and settings.json hook entries). TRIGGER when: reviewing a .claude/hooks/*.sh script or settings.json hook entry, or designing a new hook. DO NOT TRIGGER when: editing permissions.allow rules (use review-permissions) or non-Claude hook systems.

Rebase vs merge a feature branch; force-push safely. TRIGGER when: syncing a feature branch with the default branch or deciding whether and how to force-push. DO NOT TRIGGER when: routine work on a clean branch, operating on shared/default branches (never force-push them), or mid-merge/rebase/cherry-pick state (use git-state-safety instead).

Semver and version-field discipline for Claude Code plugin changes. TRIGGER when: modifying any file inside a plugin directory (tree contains .claude-plugin/plugin.json), or editing a .claude-plugin/marketplace.json. DO NOT TRIGGER when: editing skills/agents outside any plugin — e.g. user-scope stowed skills.

Respond to PR review comments on the current branch's PR. TRIGGER when: replying to PR review comments, or posting any reply to a GitHub PR. Enforces required attribution prefix. DO NOT TRIGGER when: default branch with no PR open; no unread review comments; or the conversation is about a different PR.

Supabase edge function authentication, config.toml, and Lovable Cloud deployment. TRIGGER when: adding, modifying, or reviewing an edge function in a Lovable Cloud project, or modifying a file that configures one (e.g. supabase/config.toml) or invokes one (e.g. pg_cron). DO NOT TRIGGER when: no edge function configured, invoked, or modified.

Security review of permissions.allow rules in settings.json. TRIGGER when: permissions.allow rules added/modified in any .claude/settings.json, or user asks to review permission/allow rules. DO NOT TRIGGER when: reviewing hook entries (use claude-hook-review); other settings.json fields (env, model, theme); Bash behavior unrelated to permissions scoping.

How to name new feature branches and start them from a clean base. TRIGGER when: creating a new feature branch, picking a branch name, deciding whether to use a tracker-provided default branch name. DO NOT TRIGGER when: on an existing branch, syncing a branch with the default (use `git-feature-branch-sync` instead), or force-pushing.

Multi-environment config design, credential isolation, and secrets provisioning. TRIGGER when: designing or reviewing env-var schemes, branching-on-environment credential selection, or secret-isolation strategies. DO NOT TRIGGER when: a process legitimately holds both env values simultaneously (migrations, test harnesses) or single-environment apps.

Ref inspection while mid-merge/rebase/cherry-pick without corrupting the index. TRIGGER when: examining another ref while the tree has merge/rebase/cherry-pick state or unresolved conflicts, or recovering from a bad merge already committed. DO NOT TRIGGER when: working on a clean tree or for force-push safety questions (use git-feature-branch-sync instead).

Read-path SQL conventions for raw SQL, PostgREST, and SQL-shaped ORMs. TRIGGER when: writing or modifying a SELECT query, PostgREST .from()/.select() chain, list-returning ORM call, or query-shape / pagination design. DO NOT TRIGGER when: writing write-path (INSERT/UPDATE/DELETE), DDL-only migrations, test fixtures, or document/KV stores.