toolkit

Scaffolds a top-level Makefile for repository workflow orchestration — strict-shell header, safety `MAKEFLAGS`, `.PHONY` coverage, self-documenting `help` from `## description` comments, overridable `?=` config, and a flat target graph with scoped `clean`. Use when the user wants to "create a makefile", "scaffold a makefile", or "new makefile for [X]". Not for POSIX-`make`, compilation-driving Makefiles, or multi-module recursive builds.

Scaffolds a reproducible pre-commit configuration — a `.pre-commit-config.yaml` at the repo root (optionally with local shell scripts under `scripts/hooks/`) that runs formatters, linters, and validators against staged changes via the `pre-commit` framework. Pins every `rev:`, declares scope per hook, serializes file-mutators, and documents the bootstrap. Use when the user wants to "set up pre-commit", "scaffold pre-commit hooks", or "configure .pre-commit-config.yaml". Not for hand-rolled `.git/hooks/` scripts, not for `pre-push` / `commit-msg` / server-side hooks, not for CI pipelines — route to the appropriate primitive.

Audits a standalone Python 3 script against 25 deterministic checks (shebang, `__main__` guard, argparse shape, declared dependencies, ruff-backed AST lints, line count, secret patterns) plus nine judgment dimensions (output discipline, input validation, dependency posture, performance intent, naming, function design, module-scope discipline, literal intent, commenting intent) and a Tier-3 cross-script collision check. Use when the user wants to "audit a python script", "lint a python script", or "review this script". Not for general-purpose shell scripts — route to `/build:check-bash-script`.

Audits a project's top-level README.md against 28 deterministic checks across seven scripts (secret scanning, H1 uniqueness & position, heading-hierarchy skips, section presence & order, TOC threshold, line count & length, code-block language tags, shell-prompt prefixes, smart quotes in code, relative-link resolution, fragment-anchor resolution, image alt text, badge/image byte size, destructive-command flagging, pipe-to-shell patterns, TLS-disable instructions, non-reserved hostnames/IPs, emoji in headings, LICENSE file presence & link, CONTRIBUTING link, TODO/FIXME/XXX markers, README gitignore status) plus seven judgment dimensions and a Tier-3 cross-README collision check. Use when the user wants to "audit a README", "lint a README", or "run linters on README.md". Not for sub-package READMEs (different rubric) or docs-site pages (different toolchain).

Audits Claude Code custom subagent definitions against deterministic Tier-1 checks (location, frontmatter shape, naming, `tools` hygiene, prompt size, body structure, secret patterns) and seven judgment dimensions (scope discipline, routing-description quality, tool proportionality, output contract, voice & framing, failure behavior, injection surface). Use when the user wants to "audit a subagent", "review agent permissions", or "validate a subagent definition". Not for skills (route to `/build:check-skill`), hooks (route to `/build:check-hook`), or rules (route to `/build:check-rule`).

Ingest any source into wiki pages. Use when the user says "ingest this", "add to wiki", or "update wiki with", or provides a URL, file path, or pasted text for knowledge capture.

Conducts structured investigations using the SIFT framework and produces verified research documents. Use when the user wants to "research", "investigate", or "deep dive into" a topic — any request to conduct a structured investigation.

Initialize or update project context. Use when starting a new project, setting up context structure, configuring project documentation, or re-run to verify and repair an existing setup. Idempotent — safe to run multiple times.

Use when implementation is complete and validated, to decide how to integrate the work. Presents structured options for merge, PR, keep, or discard with safety verification. Use when the user wants to "finish", "create PR", or "ship it", or after completing all tasks and validation in a plan.

Use when the user has a spec or requirements for a multi-step task, before touching code. Creates structured implementation plans with explicit lifecycle management and verification criteria. Use when the user wants to "plan", "make an implementation plan", "break this down into tasks", or needs to turn a design into actionable work items.

Audits a Bash 4.0+ script against 34 deterministic rules emitted as JSON envelopes (shebang, `set -euo pipefail`, header comment, main + sourceable guard, readonly constants, mktemp+trap pairing, shellcheck rule set SC2086 / SC2046 / SC2068 / SC2154 / SC2155 / SC2006 / SC2010 / SC2012 / SC2045 / SC2013 / SC2162 / SC2038 / SC2164 / SC2002 / SC2294, shfmt format compliance, eval / GNU-flag / `/tmp/` literal flagging, secret patterns, line count, naming conventions, command preflight) plus six judgment dimensions (output discipline, input validation, performance intent, function design, commenting intent, cross-entity collision). Use when the user wants to "audit a bash script", "lint a bash script", or "run shellcheck on this". Not for POSIX `sh` portability — refused at scope. Not for Python scripts — route to `/build:check-python-script`.

Evaluate decisions by considering impact across three time horizons — use when short-term emotions and long-term consequences may point in different directions

Drill to root cause by asking why repeatedly until fundamentals emerge — use when a problem recurs or the quick fix keeps failing to hold

Scope decisions by distinguishing what you know well from what you don't — use when expertise boundaries are uncertain or a decision requires knowledge outside your direct experience

Apply structured mental models to think through problems. Use when the user wants to "analyze", "evaluate", "think through", "decide between", "weigh tradeoffs", or needs a framework for a decision.

Prioritize tasks and decisions by mapping urgency against importance — use when facing competing demands and unclear where to focus first

Break down assumptions and rebuild reasoning from fundamental truths — use when a standard approach feels wrong or produces diminishing returns but no one has questioned its underlying assumptions

Interpret behavior charitably — attribute to mistakes before malice; use when behavior seems hostile or frustrating and an adversarial interpretation is forming

Solve problems backwards by identifying what would guarantee failure — use when direct optimization feels stuck or failure modes are unclear

Recognize where your mental model diverges from reality — use when a plan or model is driving decisions and its assumptions haven't been stress-tested

Find the simplest explanation or solution that accounts for all known facts — use when there are multiple competing explanations and the simplest hasn't been tried first

Identify the single highest-leverage action that makes everything else easier — use when there are too many competing priorities and focus needs to be established before work begins

Evaluate what you give up by choosing one option over alternatives — use when a decision is being made without explicitly naming the best alternative foregone

Apply the 80/20 rule to find the highest-leverage inputs — use when effort and results feel misaligned or there are too many things competing for attention

Assess decision risk by classifying as one-way or two-way door — use when calibrating how much analysis a decision deserves before committing

Think through the consequences of consequences before acting — use when an action has obvious immediate effects but the downstream consequences haven't been traced

Map strengths, weaknesses, opportunities, and threats systematically — use when evaluating a strategic position or deciding how to proceed with both internal and external factors at play

Improve by removing problems rather than adding solutions — use when a system or process has accumulated complexity and improvement by addition has hit diminishing returns

Use when you have an approved implementation plan to execute. Handles sequential execution, progress tracking, and recovery. Enforces the approval gate. Use when the user wants to "execute the plan", "implement this plan", or "start work".

Scaffolds a standalone Bash 4.0+ script — a single-file CLI tool, glue automation, or ops utility — with explicit shebang, `set -euo pipefail`, header comment, `readonly` constants, `die` helper, `local` variables, `main` function, and a sourceable guard. Use when the user wants to "scaffold a bash script", "create a bash script", or "scaffold a shell script". Not for POSIX `sh` portability targets, Claude Code hooks, or scripts that would be cleaner in Python — route to the appropriate primitive.

Scaffolds a GitHub Actions workflow — a YAML file under `.github/workflows/` — with top-level least-priv `permissions:`, SHA-pinned `uses:`, per-job `timeout-minutes`, workflow-level `defaults.run.shell: bash`, scoped triggers, `harden-runner` as first step, `set -euo pipefail` in every multi-line `run:`, and deliberate concurrency posture (cancel-in-progress for PR/push, no-cancel for deploy). Use when the user wants to "scaffold a ci workflow", "create a github workflow", or "build a github actions workflow for X". Not for composite actions (`action.yml` — separate primitive), org rulesets, Dependabot configs, or GitHub Apps.

Scaffolds a standalone Python 3 script — a single-file CLI tool, automation helper, or data-wrangling utility — with shebang, module docstring, `main(argv) -> int`, `__main__` guard via `sys.exit(main())`, argparse parser, KeyboardInterrupt handling, and declared dependencies. Use when the user wants to "scaffold a python script", "create a python script", or "build an automation script in python". Not for long-running services, packages with multiple modules, or Claude Code hooks — route to the appropriate primitive instead.

Scaffolds a project's top-level README.md — the `README.md` at a repository root that orients a first-time reader in the top 30 seconds. Produces a conditionalized template with a single H1, one-sentence description, problem statement, badges block, H2 section sequence (Prerequisites → Installation → Usage → Configuration → Troubleshooting → Contributing → License), fenced code blocks with language tags, and placeholder discipline. Use when the user wants to "scaffold a README", "create a README", or "bootstrap README.md". Not for sub-package READMEs inside a monorepo, docs-site landing pages, or GitHub org-profile READMEs — those have different audiences and out of scope.

Create a Claude Code rule under `.claude/rules/` — a markdown instruction file with optional `paths:` frontmatter for path-scoping. Use when the user wants to "create a rule", "capture this convention", or "enforce this pattern".

Use when the user wants to "create a skill", "scaffold a skill", or "new skill for [X]", or wants to capture a recurring workflow as a reusable Claude Code skill. Also use to improve an existing SKILL.md.

Use when the user wants to "audit a skill", "review a skill", or "improve a skill". Audits a Claude Code SKILL.md for format compliance, content quality, and cross-skill description collisions across three tiers (deterministic scripts → LLM rubric → cross-skill conflict).

Use before creating implementation plans. Explores user intent, requirements, and design through structured divergent-then-convergent thinking. Produces a design document, not code. Use when the user wants to "brainstorm", "design", or "figure out what to build", or needs to think through a problem before planning.

Verifies completed work against validation criteria. Works in two modes: with a plan (runs the plan's Validation section) or ad-hoc (builds checks from git diff, project config, and project docs). Use when the user wants to "verify the work", "validate the work", or "run checks", or after completing all tasks in a plan.

Scaffolds a primitive-pair — a matched `build-<primitive>` and `check-<primitive>` skill sharing a single distilled principles doc under `_shared/references/`, plus one `references/check-<dim>.md` per judgment dimension on the check half. Distills best-practice material (files, URLs, pasted text, or the model's own domain knowledge) into one rubric that both halves reference. Use when the user wants to "create a skill pair", "scaffold build and check skills for X", or "codify best practices for a new primitive". Not for creating a single skill — route to `/build:build-skill`. Not for auditing an existing pair — route to `/build:check-skill` on each half.

Scaffolds a Claude Code custom subagent definition — a `.md` file under `.claude/agents/` with a routing-oriented description, an explicit `tools` allowlist sized to the workflow, a bounded system prompt in the markdown body, and explicit failure behavior. Use when the user wants to "create a subagent", "scaffold an agent", or "make a custom agent". Not for skills (route to `/build:build-skill`), hooks (route to `/build:build-hook`), or rules (route to `/build:build-rule`).