Whetstone

A Claude Code plugin that makes AI coding agents follow engineering discipline. Plan before coding. Verify before claiming done. Find root cause before patching. Review before merge. Skills activate based on file type and task signals, not manual toggling.

Bundles agents, skills, workflow commands, and a skill distillery for PHP, Python, TypeScript, React, and infrastructure workflows.

Who this is for

Teams using Claude Code for real work. You're building with PHP, Python, TypeScript, or React. You want the agent to plan before building, verify before shipping, and debug by reasoning instead of guessing. This plugin provides that structure.

Solo developers who want consistency. Bash tasks receive guidance on strict mode and ShellCheck; Laravel tasks receive strict-type and thin-controller patterns. Skills guide the agent; only checks actually run can establish compliance.

Anyone building with AI agents. Includes skills for multi-agent orchestration, agent-native architecture design, and a distillery that generates new skills from top-rated community sources.

The Problem

AI coding agents skip planning, claim "done" without verifying, patch symptoms over root causes, and forget what they learned when context resets. The output looks polished. The behavior underneath is undisciplined.

The long-form argument is at AI Agents Don't Lack Capability. They Lack Process.. This plugin supplies that process as instructions and supporting tools.

🚀 Install

Claude Code (recommended)

/plugin marketplace add https://github.com/iliaal/whetstone
/plugin install whetstone@iliaal-marketplace
/reload-plugins

Standalone skills (any AI coding agent)

Individual skills work with Claude Code, Cursor, Codex, Gemini CLI, Copilot CLI, OpenCode, and 35+ other agents via the ai-skills repo:

# All skills
npx skills add iliaal/ai-skills

# Single skill
npx skills add iliaal/ai-skills -s code-review

# Target a specific agent
npx skills add iliaal/ai-skills -a cursor

Codex

Install Whetstone's portable skills and Context7 integration through the repository's native Codex marketplace:

git clone https://github.com/iliaal/whetstone
cd whetstone
bash scripts/install-codex-plugin.sh

Start a new Codex thread after installation or update. The native package includes Whetstone's cross-harness skills and Context7 MCP server. Claude-specific agents, slash commands, and hooks remain available only through the Claude Code plugin.

Two shared skills retain Claude's explicit-only disable-model-invocation metadata. Codex enforces the equivalent restriction through each skill's agents/openai.yaml. The current Codex runtime installs and loads this dual-harness package, although the standalone plugin-creator validator rejects those two Claude fields. Whetstone's regression suite treats the mapped fields as an intentional compatibility exception; it does not claim validator-clean source metadata.

Normal Whetstone releases refresh the local Codex plugin before publication when codex is on PATH. For source edits between releases, use the wrapper that applies a temporary cachebuster, reinstalls, and restores the tracked release version:

bash scripts/refresh-codex-plugin.sh

The legacy converter remains available for OpenCode and other non-plugin targets.

In this checkout, Codex also discovers the 12 repository commands and skill-distiller through .agents/skills/. Invoke them as $release, $audit-plugin, $write-skill, or $skill-distiller, with arguments after the name. Command wrappers read the maintained .claude/commands/ sources. If an existing session has not refreshed its skill list, start a new Codex session. These repository workflows are separate from the distributed plugin skills.

OpenCode

Same converter, different target. OpenCode reads skills from its per-project config. The converter translates the plugin's SKILL.md format into OpenCode's expected shape and writes output into the current project (override with --output <dir>).

Command-based PreToolUse and PostToolUse hooks use a bundled adapter; unsupported hook events and types cause conversion to fail. Whetstone's injection hook requires Bash and jq on PATH. The installed bundle includes its scripts and skill files, so it does not depend on the source checkout.

bun run src/index.ts install ./plugins/whetstone --to opencode

Cleanup for OpenCode (and other targets) uses the same command:

bun run src/index.ts cleanup --target opencode
bun run src/index.ts cleanup --target kilocode
bun run src/index.ts cleanup --target agents

Use cleanup --target opencode --output <dir> for a custom installation. Default OpenCode cleanup checks the current project and legacy global locations. Cleanup backs up individually identified Whetstone artifacts and preserves unrelated or customized files; files whose ownership cannot be established require manual review.

Additional targets (symlink-based)

For tools that read skills directly from ~/.agents/skills or ~/.kilocode/skills, scripts/sync-to-tools.sh symlinks the plugin's skill directory into each path so edits land immediately without re-conversion. It removes legacy Whetstone-owned links from ~/.codex/skills and adds managed Codex exclusions for the same skills discovered through ~/.agents/skills; the native plugin remains Codex's single source.

bash scripts/sync-to-tools.sh              # symlink into shared non-Codex tool dirs
bash scripts/sync-to-tools.sh --dry-run    # preview changes

🔗 Works well with

• codesage adds structural code intelligence (find symbols, references, dependencies, blast-radius analysis) as an MCP server. Whetstone supplies process guidance; CodeSage supplies codebase structure for applying it.
• ai-skills is the read-only mirror of this plugin's skills for agents without native Whetstone plugin support.

🛠️ The workflow

Five commands form a loop: explore the problem, plan the solution, build it, review it, document what you learned. Each pass makes the next one faster because solutions accumulate as searchable docs.

Command	What it does
/ia-brainstorm	Interviews you one question at a time to surface hidden requirements. Produces 2-3 named approaches with trade-offs. No code until a design doc is approved.
/ia-plan	Turns a brainstorm or feature idea into a file-based plan with atomic tasks, specific file paths, and phased delivery in vertical slices.
/ia-work	Executes a plan with task tracking, worktree isolation, and verification gates. Each task runs through build/test before marking complete.
/ia-review	Multi-agent code review: scope-drift detection, spec compliance, code quality, security, performance. Auto-escalates to deep mode on complex diffs.
/ia-compound	Captures what you just solved as searchable documentation in docs/solutions/ so the next person (or the agent) doesn't re-debug it.

You don't have to use all five. /ia-review on its own is a solid pre-merge check. /ia-plan works standalone for scoping. Mix and match.

✨ Skills

Skills are instructions selected for the task. They guide procedures and identify anti-patterns; they are not runtime enforcement of the agent's decisions.

Architecture & design

Skill	Description
ia-agent-native-architecture	15-area architecture checklist for systems where AI agents are primary actors: tool design, execution patterns, context injection, approval gates, audit trails. For designing agent systems or MCP tools.
ia-frontend-design	Requires a design philosophy statement before code, detects existing design systems to match, and bans AI design cliches (purple-to-blue gradients, Space Grotesk, three-card hero layouts). Calibrates output via variance, motion, and density parameters. For work where visual identity matters.
ia-simplifying-code	Declutters code without changing behavior. Targets AI slop: redundant comments, unnecessary defensive checks, over-abstraction, verbose stdlib reimplementations. Applies changes in priority order and stops before touching public APIs. For cleanup after AI generation or accumulated complexity.

Language & framework

Skill	Description
ia-react-frontend	Decision tree routing most "should I use an effect?" questions to non-effect solutions. Separates state tools by purpose (Zustand for client, React Query for server, nuqs for URL). Enforces React 19 patterns, App Router server/client boundaries, and flags that Server Actions are public endpoints. For React, Next.js, and Vitest/RTL testing.
ia-nodejs-backend	Strict layered architecture (routes > services > repos) with no cross-layer HTTP imports. Contract-first API design using Zod schemas as the single source of truth. Production patterns like circuit breaker and load shedding as requirements, not suggestions. For Express, Fastify, Hono, or NestJS backends.
ia-python-services	Mandates modern tooling (uv, ruff, ty) over legacy equivalents. Structured concurrency via asyncio.TaskGroup, idempotent background jobs, and structured JSON logging with correlation IDs via contextvars. For Python CLI tools, FastAPI services, async workers, or new project setup.
ia-php-laravel	declare(strict_types=1) everywhere, PHPStan level 8+, fat models / thin controllers, Form Requests with toDto(), event-driven side effects. Prevents N+1 by disabling lazy loading in dev. Defaults to feature tests through the full HTTP stack. For Laravel codebases.
ia-rust-systems	Edition 2024, workspace layout with inward-only deps, thiserror in libraries / anyhow in binaries, no unwrap/expect outside main and tests, every unsafe block needs a // SAFETY: comment. Tokio patterns (JoinSet, CancellationToken, bounded mpsc) and axum service layout. For Rust CLIs, axum services, or cargo workspaces.
ia-c-systems	Repo conventions outrank the skill, so it defers on tabs, goto cleanup, and macros that return rather than fighting established C. Function altitudes (orchestrator / leaf / adapter) gated behind a name test that stops over-decomposition, status enums with one producer per error value, public-validates / internal-asserts boundaries. Separate references for memory safety (sanitizers, overflow-checked allocation, recursion to bounded worklists) and PHP extension C. For C11 and later, native extensions, and systems code.
ia-cpp-systems	Rule of zero by default and rule of five once a destructor appears, since a user-declared destructor silently suppresses moves. unique_ptr first and shared_ptr third. API rules that break callers when ignored: decide explicit at introduction, keep the narrow overload, delete rather than silently ignore. Separate references for ABI boundaries (exceptions must not cross extern "C", PIMPL, visibility) and CMake tooling. For C++17 and later libraries and services.
ia-pinescript	Guides Pine Script v6 syntax, platform limits, signal stability checks, and walk-forward validation. Distinguishes historical indexing from future outcomes and chart-bar confirmation from requested-timeframe confirmation.
ia-tailwind-css	Enforces v4's CSS-first config model (@theme, @utility, @custom-variant directives). Provides a v3-to-v4 breaking changes table. Prohibits dynamic class construction, mandates gap over space-x, size-* over paired w-*/h-*. For Tailwind v4 or v3 migrations.

Infrastructure

Skill	Description
ia-postgresql	BIGINT GENERATED ALWAYS AS IDENTITY over SERIAL, TIMESTAMPTZ over TIMESTAMP, indexes on every FK (Postgres doesn't auto-create them). Includes an unindexed FK detection query and mandates EXPLAIN (ANALYZE, BUFFERS) before any optimization claim. For schema design, query tuning, RLS, or partitioning.
ia-terraform	Specific file organization, for_each over count to prevent recreation on reordering, remote state with locking, moved blocks for renames, and four-tier testing (validate > tflint > plan tests > integration). For Terraform or OpenTofu.
ia-linux-bash-scripting	set -Eeuo pipefail as foundation, EXIT traps for cleanup, printf over echo, arrays over eval, local separated from assignment. Production templates for atomic writes, retry with backoff, and script locking. For any Bash script meant for production.

Testing & quality

Skill	Description
ia-writing-tests	DAMP over DRY, test cases from user journeys not implementation details, real objects over mocks (mocks only at system boundaries). Requires red-green cycles for bug fix tests. Includes a 13-excuse Rationalization Table for when you're tempted to skip tests. Works with any language.
ia-code-review	Checks specification compliance before code quality, tracks selected-file coverage, and ranks findings by severity and evidence. Selects deep review when 3+ risk signals apply. Reports suggested action routes without editing during review-only work. For PR reviews and code audits.
ia-receiving-code-review	Verify-before-implement for every comment. Different skepticism levels by source: maximum for automated agents, trusted-but-verified for project owners. Requires evidence when pushing back. Prohibits performative agreement. For processing review feedback on your code.
ia-debugging	Reproduces the reported symptom, tests evidence-backed hypotheses, and verifies permanent repairs with regressions. Distinguishes authorized incident mitigation from root-cause repair and preserves diagnosis-only scope. Reassesses after 3 failed cycles without imposing a fixed tracing depth.
ia-verification-before-completion	Requires fresh evidence through Identify, Run, Read, Verify, Claim. Checks the actual revision and entry point, reports missing coverage, and distinguishes fixtures from live proof. Accepts a clean review when its coverage supports the conclusion.
ia-planning	Chooses a durable plan, inline list, or direct implementation from dependencies, recovery needs, and unresolved decisions. File counts are signals rather than automatic triggers. Plans name concrete tasks, ownership, verification, and runnable phase outcomes.

Content & workflow

Skill	Description
ia-brainstorming	Hard gate: no code until a design doc is approved. Reads the codebase first, interviews one question at a time, proposes 2-3 named approaches with trade-offs, saves a structured doc to docs/brainstorms/. For vague requirements or multiple valid interpretations.
ia-compound-docs	Explicitly invoked workflow for documenting solved problems. Captures lessons not already recoverable from code and existing documentation, validates YAML frontmatter, checks for duplicates, and detects recurring patterns when 3+ similar issues appear.
ia-document-review	Activates specialized lenses (Product, Design, Security, Scope Guardian, Adversarial) based on document signals. Scores on four criteria, identifies one critical improvement, and can dispatch a fresh-eyes sub-agent. For polishing specs or brainstorms before handing them to planning.
ia-writing	Edits prose while preserving meaning, facts, and voice. Treats vocabulary and structural tells as contextual signals, with separate edit and detect-only modes and guidance for publication surfaces. For blog posts, PR descriptions, docs, and changelogs.
ia-git-worktree	Routes all operations through a manager script handling .env copying, .gitignore updates, and dependency installation. Detects execution context and adapts. For parallel feature development or isolated reviews.
ia-md-docs	Treats AGENTS.md as the canonical context file. Verifies every factual claim against the actual codebase before writing. For project documentation that's stale, missing, or needs initialization.
ia-file-todos	File-based task tracking with structured YAML frontmatter and naming conventions. Distinct from in-session memory and application-level models. For persistent, human-and-agent-readable todo files with dependency tracking.

AI & prompting

Skill	Description
ia-meta-prompting	Decision modifiers through natural language or prompt markers: /verify-think challenges an answer, /adversarial ranks counterarguments, /edge explores failure scenarios, and /confidence scores claims. Distinct from the /ia-verify command's pre-PR checks.
ia-refine-prompt	Assesses against a six-element checklist (task, constraints, format, context, examples, edge cases), rewrites in specification language, validates all gaps addressed. Enforces 0.75x-1.5x length ratio and won't invent missing info. For prompts that produce inconsistent results.
ia-reflect	Scans the full conversation for mistakes, friction, and wins, citing specific exchanges. Proposes ranked improvements and audits skills used in the session for token efficiency. For end-of-session lessons learned.

Multi-agent orchestration

Skill	Description
ia-orchestrating-swarms	Coordinates independent agents with explicit scope, file ownership, and verification assignments. Uses worktrees or a shared-tree workflow with exclusive writes and parent-owned integration. Defines worker recovery, independent review, and four status signals.

🤖 Agents

Specialized subagents dispatched by the main agent or by workflow commands. Each runs in isolation with its own tools and context.

Review

Agent	Description
ia-accessibility-tester	WCAG 2.1 audit across keyboard navigation, screen reader compatibility, contrast ratios, ARIA attributes, and form accessibility. For compliance checks before launch.
ia-architecture-strategist	Evaluates architectural soundness, design pattern compliance, and structural consistency. For service additions, refactors, or codebase pattern audits.
ia-cloud-architect	Analyzes infrastructure against Well-Architected Framework principles: cost optimization, scalability, disaster recovery across AWS, Azure, and GCP.
ia-code-simplicity-reviewer	Produces a simplification report (no code changes) identifying YAGNI violations and over-engineering. For post-implementation analysis.
ia-database-guardian	Validates migration safety, referential constraints, and data integrity. For PRs touching migrations, backfills, or data transformations.
ia-kieran-reviewer	Opinionated Python and TypeScript review with a high bar for type safety, naming clarity, and modern patterns.
ia-performance-oracle	Identifies bottlenecks in algorithmic complexity, database queries, memory usage, and scalability limits.
ia-security-sentinel	Threat modeling and vulnerability scanning across authentication, input validation, secrets management, and OWASP categories.
ia-spec-flow-analyzer	Maps user flows through specifications to surface edge cases, missing clarifications, and completeness gaps before implementation.

Research

Agent	Description
ia-best-practices-researcher	Gathers official framework docs, version-specific best practices, and industry standards for any technology.
ia-git-history-analyzer	Excavates git history to explain code evolution: traces commits, authors, and context around decisions.
ia-learnings-researcher	Mines docs/solutions/ for documented solutions and patterns relevant to the current task. Prevents repeating past mistakes.
ia-repo-research-analyst	Analyzes repository architecture, naming conventions, and implementation patterns. For onboarding or understanding project conventions.

Design

Agent	Description
ia-design-iterator	Iterative UI refinement through screenshot-analyze-improve cycles. For when initial design changes produce mediocre results.
ia-figma-design-sync	Compares implemented UI against Figma designs, reports discrepancies, and optionally applies fixes.

Workflow

Agent	Description
ia-bug-reproduction-validator	Reproduces bug reports and identifies root causes without applying fixes. Validates whether reports are genuine bugs before engineers invest.
[ia-deployment-verificatio