my-claude-setup

Use when designing component interaction specs with visual states, transitions, and accessibility requirements. Covers state matrices, responsive behavior, ARIA compliance, and content constraints. Do not use for multi-step user journey mapping (use journey-mapping).

Use when mapping complete user journeys through multi-step flows, onboarding sequences, or feature workflows. Covers entry points, happy paths, alternate paths, error states, friction analysis, and delight opportunities. Do not use for individual component interaction specs (use interaction-design).

Use when analyzing an existing codebase for architecture, tech stack, conventions, and infrastructure. Covers project structure mapping, data model discovery, integration point cataloging, and constraint identification. Do not use for schema changes (use schema-design) or API contract definition (use api-design).

Use when designing documentation architecture for a project or team. Covers audience mapping, Diataxis framework classification, onboarding path design, format and location decisions, documentation testing, and maintenance scheduling. Do not use for recording individual architecture decisions (use adr-template) or creating versioned changelogs (use changelog-design).

Use when auditing codebase patterns or evaluating proposed changes for convention consistency. Covers file naming, component patterns, data fetching, state management, and type conventions. Do not use for test plan design or coverage targets (use testing-strategy).

Use when classifying data elements by sensitivity tier and defining per-tier handling requirements. Covers data inventory, sensitivity classification, PII flow mapping, encryption and masking specifications, and cross-boundary transfer documentation. Do not use for regulatory gap analysis (use compliance-review) or audit logging design (use audit-trail-design).

Use when designing, evaluating, or versioning system prompts for LLM-powered features. Covers instruction structure, chain-of-thought patterns, output format constraints, few-shot example selection, and prompt versioning strategy. Do not use for RAG pipeline design (use rag-architecture) or AI evaluation frameworks (use ai-evaluation).

Use when designing features that exist in competing products or analyzing prior art in the market. Covers feature mapping, UX evaluation, technical trade-off assessment, and differentiation opportunity identification. Do not use for evaluating individual libraries (use library-evaluation) or assessing technology maturity (use technology-radar).

Use when defining minimum viable scope for a product or feature launch. Covers MoSCoW prioritization, value-effort matrix analysis, MVP cut-line definition, and phased roadmap planning. Do not use for quantified feature comparison (use impact-estimation) or measurement instrumentation (use analytics-design).

Use when you must prove a claim about this repo's token budgets, description trigger-reliability, hook-blocking behavior, multi-agent session cost, or a counter's trustworthiness before citing it in a review or merge decision, rather than eyeballing it or trusting a hook that merely looks wired. Covers hand-deriving token math, live-fire hook payloads, write-path-to-commit tracing, refute-first fix verification, each with a worked example. Not for routine tool invocation or exit-code reading (mcs-diagnostics-and-tooling), acceptance-evidence tiers (mcs-validation-and-qa), or the hunch-to-accepted-result idea lifecycle (mcs-research-methodology).

Use when you need to know WHY this repo is built the way it is, not just what a file contains: shared engine plus themed layer, symlink deployment, backend degradation (workflow to teams to sequential), fail-soft contracts, progressive skill loading, session-state layering, and which invariants are enforced-by-hook versus prose-only. Also use to check a known-weak-point first: routing truth on three surfaces, unsynced session state, private-repo coupling. Do NOT use for step- by-step procedures (mcs-run-and-operate) or generic Claude Code platform mechanics (mcs-claude-code- platform).

Use when setting up my-claude-setup on a bare macOS machine, running or scripting install.sh (presets, flags, --uninstall, --dry-run, --conflict-policy), bootstrapping the mcp/openrouter venv, diagnosing "command not found", missing-symlink, or manifest errors during install, or verifying a fresh clone is healthy before first use. Not for day-to-day running of /council, /ship, or /looper (see mcs-run-and-operate) or for settings.json axis semantics and hook wiring (see mcs-config-and-flags).

Use when about to commit or merge in this repo, edit settings.json or hooks.json, run git commit --no-verify, force-push or rewrite history, choose a commit type prefix, a TaskUpdate gets blocked, or another session touched main today. Symptoms include "acceptance gate blocked me", "which commit type", "can I --no-verify this", "is it safe to force-push". Not for live symptom triage (mcs-debugging-playbook), "has this happened before" digs (mcs-failure-archaeology), or the config/flag catalog (mcs-config-and-flags).

Use when you need Claude Code platform mechanics as this repo actually wires them: writing or debugging a hook (stdin JSON payloads, which event plus exit code plus stream combination actually blocks), reading settings.json versus settings.local.json versus hooks.json, understanding why a skill or command loads twice, registering or calling an MCP server, or checking Workflow tool and agent-teams preflight. Not for this repo's commit rules and acceptance-gate incident history (mcs- change-control), the full config/flag value catalog (mcs-config-and-flags), or symptom-to-cause triage (mcs-debugging-playbook).

Use when you need the current value, default, production/experimental/parked status, or enforcement guard for any Claude Code configuration axis in this repo, such as settings.json fields, env flags, permissions allow/deny lanes, hooks wiring, settings.local.json, council cost profiles, model-routing.json/yaml, budgets.json overrides, or security-suppressions.json, and when adding a brand-new configuration axis. Not for what a setting means at the Claude Code platform level (mcs-claude-code-platform) or for how a config change gets reviewed and merged (mcs-change-control).

Use when a hook, gate, or check in this repo (my-claude-setup) seems armed but does nothing, or blocks when it shouldn't - a hook that should stop a tool call doesn't, TaskUpdate-to-completed is unexpectedly denied, /council's Workflow throws "requires args", /careful or /freeze does nothing, pre-commit fails on an untouched file, the openrouter MCP tool errors, or scripts/ recurses forever. Do NOT use for "has this been tried before" (mcs-failure-archaeology) or for measuring/profiling cost and reliability (mcs-diagnostics-and-tooling).

Use when you need a hard number instead of an impression in my-claude-setup - skill/agent/command inventory counts, description-token cost, per-file or context-load token budgets, prose/checklist pattern scans, eval-tier runs, manual pre-commit validator exit codes, whether a hook actually blocks, or README-vs-reality drift. Covers pipeline/scripts/*, scripts/*, `python3 pipeline/hooks/check_*.py`, gh-based issue/PR/branch-protection queries, and this skill's own hook-contract-check.sh / doc-drift-check.sh. Not for deciding what counts as acceptance evidence (mcs-validation-and-qa) or for fixing what a tool finds (mcs-debugging-playbook).

Use when editing or auditing README.md, ARCHITECTURE.md, CONTRIBUTING.md, CHANGELOG.md, SECURITY.md, THIRD_PARTY_NOTICES.md, docs/, pipeline/specs/, or memory/HANDOVER-*.md in my-claude-setup, when two docs disagree on a number (agent/skill/command counts, token budgets, spec versions), when writing a handover or design doc, or when asked "which doc is right" or "is this stale". Not for skill-authoring mechanics (use mcs-claude-code-platform or the governance spec directly), release/novelty claims (use mcs-external-positioning), or live incident triage (use mcs-debugging-playbook).

Use when deciding what this project (my-claude-setup) may claim publicly (README pitch, launch post, "why is this different" answers, OSS release announcements), when someone asks for a v1.0/launch readiness verdict against GitHub issue 3 (the v1.0 tracking issue), when evaluating third-party attribution or license compliance before a release, or when history/privacy exposure (real personal data reachable in pushed git refs) needs a decision framed for the owner. Not for fixing drifted docs (mcs-docs-of-record) or for open-research novelty claims (mcs-research-frontier).

Use when you need the history behind a file or decision before touching it, e.g. "has this been tried", "why was this deleted", "why is this branch stale", "is this issue real", or before reviving a branch, re-adding a deleted skill/hook/model-pin, or reopening an old issue. Covers the acceptance-gate saga, Fable-5 sweep, academy removal, OpenRouter Phase 1, branch graveyard, registry.json, privacy exposure. Not for live debugging (mcs-debugging-playbook) or why a design is load-bearing today (mcs-architecture-contract).

Use when consulting or extending the model-routing unification and OpenRouter multi-model council campaign in this repo (US-001..US-008, GitHub issues 59 to 66, council session claude-config-model-optimization-20260702-0003; track 1 completed 2026-07-06), checking phase state before touching .claude/ship-state.md or .claude/looper-state.md, mapping an issue to its acceptance criterion and test command, extending skills/council/model-routing.json, or judging whether OpenRouter Phase 2 lens-relay prerequisites (38-case harness, egress gates, fresh IDs, API key) are met. Not for generic ship/looper mechanics with no campaign context (mcs-run-and-operate), the full settings.json config-axis catalog (mcs-config-and-flags), or commit/PR review rules (mcs-change-control).

Use when scoping a genuinely open, publishable-flavor problem this repo could advance rather than a bug to fix or a feature to ship, e.g. "could this become a paper", "what's the interesting unsolved part here", "is anyone else doing this", or "what would make this evidence-worthy" for closed-loop skill evolution, heterogeneous multi-model council, contract-gated autonomous execution, config-as-production, or cross-session memory. Not for executing the OpenRouter/model-routing campaign itself (mcs-model-routing-campaign) or for how an idea graduates from hunch to accepted result (mcs-research-methodology).

Use when turning a hunch into a shipped change here, deciding if a claim survives adversarial refutation before trusting it, writing a predicted number/exit-code/pass-rate before running an experiment or eval, tracing an idea through council deliberation, PRD non-goals, a numbered acceptance contract, gated /ship or /looper execution, to verified or retired, or picking settings.local.json as the experiment lane instead of settings.json. Not for measurement techniques (mcs-analysis-toolkit) or formal evidence tiers and AC mechanics (mcs-validation-and-qa).

Use when running /council, /ship, /looper, or /handover day to day in this repo: choosing a council mode or --profile, resuming/listing/archiving a session, picking a Phase 5 execution path (team, ralf, launch, deep audit, issues export, Ship), reading or resuming .claude/ship-state.md or .claude/looper-state.md, writing a handover, or checking for an in-flight ship/council run before touching .claude/ state so you do not clobber it. Not for diagnosing why a hook or gate is silently failing (mcs-debugging-playbook) or for commit/PR/change-classification rules (mcs-change-control).

Use when deciding what counts as evidence in this repo, adding a pytest to mcp/openrouter, writing eval-cases/trigger-evals.json for a council department, flipping an acceptance-contract AC row to verified, running run-evals.sh or judge-skill-quality.sh, or someone claims a change "looks right" without a number or exit code. Covers hard vs warn pre-commit tiers, CI's actual (narrow) scope, and the acceptance-gate block mechanics. Not for running diagnostic tools themselves (mcs-diagnostics-and-tooling) or the history of why an enforcement gap exists (mcs-failure-archaeology).

Use when modeling infrastructure costs, projecting scaling expenses, or identifying optimization opportunities across cloud providers and third-party services. Covers per-unit cost estimation, growth milestone projections, and budget alerting setup. Do not use for deployment strategy design (use deployment-plan) or monitoring architecture (use observability-design).

Use when designing an evaluation framework for AI/LLM features. Covers golden dataset creation, automated scoring rubrics, hallucination detection, regression testing infrastructure, and production monitoring. Do not use for prompt design (use prompt-engineering) or RAG pipeline architecture (use rag-architecture).

Use when evaluating frameworks, tools, or platforms for adoption, migration, or stack decisions. Covers maturity assessment, ecosystem health, team readiness, migration cost, and long-term viability with radar quadrant placement. Do not use for comparing individual libraries (use library-evaluation) or analyzing competing products (use competitive-analysis).

Use when systematically identifying failure scenarios for proposed features and infrastructure changes. Covers component enumeration, failure mode discovery, cascade analysis, mitigation design, monitoring signals, and rollback planning. Do not use for security threat modeling (use threat-model) or input boundary testing (use edge-case-enumeration).

Use when applying STRIDE threat modeling to identify security risks in proposed features. Covers trust boundary mapping, data flow analysis, threat rating, mitigation proposals, and residual risk documentation. Do not use for failure scenario discovery (use failure-mode-analysis) or boundary value testing (use edge-case-enumeration).

Use when comparing multiple features or initiatives to determine prioritization order. Covers RICE scoring with quantified reach, impact, confidence, and effort dimensions, tier ranking, and success metric definition. Do not use for MVP scope definition (use mvp-scoping) or analytics instrumentation planning (use analytics-design).

Use when the council needs to surface organizational knowledge buried across multiple internal sources (wikis, design docs, ADRs, past tickets, postmortems, chat archives, code repos). Plans where to look, what to cross-reference, and how to synthesize findings into evidence the council can act on. Do not use for external market research (use competitive-analysis), library evaluation (use library-evaluation), or technology trend assessment (use technology-radar).

Local git operations for syncing, branching, merging, and conflict resolution

Use when a merge, rebase, or cherry-pick has gone wrong and needs to be safely aborted.

Use when creating a new git branch following the project's branch naming conventions.

Use when listing local and remote branches or visualizing branch status and divergence.

Use when resolving merge or rebase conflicts with step-by-step guided resolution.

Use when deleting local or remote branches with safety checks for unmerged work.

Use when merging the main branch into the current feature branch to pick up upstream changes.

Use when pulling remote changes with an explicit merge or rebase strategy choice.