mastermind

Turn a design handoff into a task contract that can actually be checked — named source, resolved components, token names instead of raw values, and an explicit list of what stays unverifiable. Use when a Figma frame, mockup, or design spec is handed over for implementation.

Convert a PRD, ticket, or feature request into a task contract that can fail — behaviour split from outcome, product nouns resolved to symbols that exist, unspecified cases surfaced as questions, and success metrics parked where a merge gate cannot wave them through. Use when product writing is handed over for implementation.

Enumerate what a change can reach and what enforces it — privileged operations and their callers, guards and the sites that apply them, and every module that reads a secret — before designing an auth, permission, or secrets change. Feeds the security review; produces a population and a gap list, never a verdict.

Read-only review of whether the tests in a finished change actually prove its behaviour — changed code no test reaches, a test exercising a different path than the one that changed, an assertion edited to match the new output, and a suite that ran nothing. Use after implementation, and whenever a change claims to be covered.

Gather who already depends on a service, handler, or state owner before changing it, and name the runtime gaps the codegraph cannot span. Use before designing a change to an API, queue consumer, background job, migration, or shared state; it feeds the architecture review rather than replacing it.

Read-only review of a finished UI change against the codegraph — a component nothing renders, a props contract changed without its callers, a reinvented component, or a raw value where the design system has a token. Use after implementing React or Vue work; triggers "review this UI change", "check the component", or a finished frontend diff.

Turn "I opened it and it looks fine" into recorded evidence — accessibility tree over screenshot, console and network errors as mechanical failures, viewport and colour-scheme checks as a checklist, and anything unchecked marked unchecked. Use after implementing a UI change in a client that can drive a browser.

Ground a UI change in the codegraph before writing it — find whether the component already exists, who renders it, and what its props contract is. Use before creating or changing any React or Vue component; triggers "add a component", "change these props", "build this screen", or a Figma frame handed over for implementation.

Read-only post-implementation review of the comments a change added, modified, or deleted. Flags narration with evidence, names what it deliberately kept, and reports removed rationale. Use after implementation is complete — triggers "check the comments", "audit the slop", "review comment discipline", or a finished diff awaiting review.

Write a grounded portrait of how the author actually develops — design approach, code shape, comments, tests, optimization habits, what they pay attention to, and commit voice — into the "Design patterns & tendencies" section of ~/.mastermind/style.md. The structural signature the deterministic miner can't measure. Use when the user wants a real "write like me" profile, says "deep style", "design patterns", "qualitative profile", or notices `mastermind miner profile` only produced formatter-level rules.

Execute an approved Mastermind task contract within Scope, prove its Acceptance Criteria, and write the canonical file-backed executor report. Use when the user hands off a `.mastermind/tasks/<NNN>-<name>/spec.md` or explicitly asks to execute an approved Mastermind task.

Choose the lightest Mastermind workflow that fits the risk, then create an evidence-grounded verified or strict task contract for delegated implementation. Direct work deliberately uses no task spec.

Retrieve and reason from durable project decisions, failed approaches, audits, reports, and lessons without treating provenance, search rank, or user approval as technical proof. Use when asking why a design exists, whether an approach was tried, what supersedes an older decision, or what prior evidence should constrain a new plan.

Review a proposed or existing architecture against the real runtime path, source-of-truth ownership, retry and idempotency behavior, and backward-compatibility constraints. Use for service boundaries, async workflows, persistence changes, external integrations, migrations, public APIs, events, schemas, or designs whose component diagram looks plausible but runtime safety is not yet proven.

Use mmcg to ground structural code claims before planning, auditing, criticizing, or researching code. Triggers when an agent needs symbol existence, callers, callees, imports, blast radius, file existence, or stale-index handling.

Stress-test a proposed design, task spec, implementation plan, or executor report for false assumptions, broken contracts, scope creep, missing evidence, and high-risk failure modes. Use before drafting sensitive specs, before approving a plan, or when a critic/auditor needs a compact review rubric.

Strip AI-slop comments from code — keep only comments that explain a *why* the code can't say itself, delete anything that just restates it. Use when writing or editing code (especially as an executor applying a spec) or reviewing a diff for comment noise. Triggers — "stop adding comments", "no slop comments", "too many comments", code that narrates itself.

Rewrite a request for a different agent or reusable prompt while preserving the original intent verbatim. Use when the user explicitly asks to improve/rewrite a prompt, or immediately before handing a genuinely rough request to a cold agent that will not see the original conversation. Do not activate merely because the current request is informal or multi-sentence.

Investigate unknown bugs with an explicit hypothesis ledger and evidence-driven probes before drafting a task spec. Triggers on unexplained failures, ambiguous test failures, regressions, or bug reports without a supported root cause.

Perform a portable, evidence-based security review of agent workflows, MCP tools, permissions, untrusted-input paths, audit controls, and supply-chain boundaries. Use for explicit security review or security-sensitive scope; add OWASP mapping only when requested.

Produce or consume the canonical file-backed Mastermind executor report parsed by `run-task --post-only`. Use for executor evidence, schema-v1 report validation, controller audit inputs, or strict auditor advisory output.

Install portable Mastermind workflow adapters and configure, inspect, update, or remove MCP registration for Claude Code, Cursor, Codex, Continue, or an explicit generic config. Use when a user asks to install Mastermind in an AI coding client, choose project/user scope, preview a safe config change, troubleshoot setup, or verify workflow/MCP parity with doctor.

Build an evidence-backed architecture briefing with `mastermind map` or `mmcg_map`. Use when exploring an unfamiliar repository, identifying components and entry points, choosing a reading order, inspecting dependency cycles or hotspots, or explaining codegraph precision and truncation limits.

Generate, verify, sign, or explain Mastermind audit envelopes and GitHub attestations. Use when checking audit-bundle tampering, validating exact repository/baseline/head policy, working with detached Ed25519 signatures, reviewing CI provenance, or distinguishing content integrity from signer authenticity and policy acceptance.

Produce an evidence-backed change-impact brief with `mastermind impact` or `mmcg_change_impact`. Use before editing, during implementation planning, or in PR review to trace changed symbols, callers, component/API crossings, collision risk, and likely affected consumers since a git ref.

Build a focused, evidence-backed test plan from `mastermind impact` or `mmcg_test_impact`. Use when deciding which tests to run for a change, explaining direct/transitive/heuristic candidates, or sequencing fast feedback before the repository's required full test gate.