claude-forge

Execution trace capture and token baselining. Use when user says trace, extract trace, count tokens, token baseline, or /harness-trace. Not for harness optimization (use harness-mechanic).

Release prep and tagging with pre-flight verification. Use when user says release, tag, ship it, push to production, create release, or bump version. Not for editing a version string outside a release, a lockfile or a changelog entry by hand, and not for reading what changed in a past release: those are ordinary edits, just do them.

Mine LEARNING.md retrospectives across all repos for recurring failure-modes, then propose harness changes (hooks, rules, skills, checklist items) with falsifiable change-contracts. Also runs the doc-gardening pass over the governance docs (stale rules, dead cross-references, skill-table drift). Use when user says learning loop, mine learnings, recurring failures, what should I fix in my process, cross-repo retrospective, doc gardening, stale docs, or run learning-loop. Runs on human schedule, never autonomously. Not for single-project retrospectives (use learning-docs) or trace/token analysis (use harness-mechanic).

Full contractor-mode loop: sub-protocols (LOCALIZE, BENCH-BASELINE, REPRODUCE, DRIFT), review routing by file pattern, blast radius, UAT, parallelism and effort caps, escalation, just-do-it, goal-backed runs. Load it to RUN that loop, once you have an approved plan and are entering step 1, or when a step needs its detail. It is a protocol, not a way to do the work: it never replaces the language, review or planning skill the task itself calls for, and a task small enough to just edit (SKIP_SET) needs none of it. The always-on spine lives in rules/orchestrator-protocol.md. Not for trace capture (harness-trace) or harness optimization (harness-mechanic).

Ruby on Rails with service-oriented architecture, Dry-validation, Sidekiq/Solid Queue, Hotwire. Use for Rails API, Rails services, Rails forms, RSpec, ActiveRecord, Rails migrations. Not for standalone Ruby gems (use ruby skill), and not for judging whether a migration is safe to run in production (that is the database-reviewer agent).

Get three independent second opinions (isolated Claude + isolated Gemini + isolated DeepSeek) on a problem Claude is analyzing. Use when user says second opinion, another perspective, challenge this approach, or asks gemini/deepseek about a decision, approach, or diagnosis. Also invoke on your own initiative, without being asked: on a complex task before planning, after 2 failed root-cause attempts, on a 🔴 decision (rewrite, core logic, security), or when the review loop is stuck below 80 after 2 fix rounds. Gathers context, writes a focused prompt, calls all reviewers in isolated Docker containers, and synthesizes all viewpoints. Not for reviewing code or changes, even phrased as 'ask gemini to review' (use gemini-review).

Assess test suite quality using Farley's 8 Properties and Tautology Theatre detection. Use when user says review tests, test quality, are my tests good, test assessment, or test design review. Not for writing tests (use language skills) or code review (use gemini-review).

Create new skills or review and improve existing ones. Use when user says create skill, new skill, improve skill, review skill, audit skills, or skill quality.

Turn a GitHub issue or an in-session analysis into a locked ExecPlan on disk plus a ready-to-paste implementation prompt and /goal line for a fresh session using opus subagents in a separate worktree. Use when user says plan-forge, issue to plan, prepara il piano, piano di implementazione, fai il piano per la issue N, forge a plan. Runs deep code analysis, /second-opinion on the approach, writes quality_reports/plans/active/ with decisions table, tasklist, exhaustive E2E matrix, DoD. Not for implementing (the emitted prompt drives that), not for trivial SKIP_SET fixes, not for ADRs (use adr).

PR-level review that composes gemini-review, the orchestrator review fleet, and (when contested) second-opinion, reading each commit's intent before judging. Use when user says review PR, review pull request, analyze PR, pr review, or /pr-review. Not for pre-commit review (use gemini-review).

Write clear, direct emails in Max's voice. Use when user says write email, draft email, scrivi una mail, scrivi una email, rispondi a questa mail, reply to this email, mail-writer, clean up this email draft. Applies Castonguay's email rules, Max's distilled voice, and a humanizer pass. Outputs email text in chat, never sends. Not for blog posts (blog-writer), LinkedIn (linkedin-post), or inbox triage (inbox-triage).

Sync vault knowledge patterns to skills. Scans Second Brain for strong signals, proposes skill updates. Use when user says knowledge sync, sync skills, update skills from vault, or promote patterns.

Git conventions for commit messages and workflow. Use for git commit, conventional commits, branch strategy, rebasing, merge conflicts, git workflow. Not for general code changes that happen to need a commit afterward.

Verify UI changes end-to-end in a real browser before declaring them done: dev server, direct interaction, console check, before/after screenshots, Lighthouse when perf-relevant. Use after any frontend/UI change, when user says verify UI, check the page, or does it render. Supersedes generic verify flows for rendered UI. Not for backend-only changes (verification-protocol test/lint/build covers those).

Create and update LEARNING.md project retrospectives. Use when user says retrospective, lessons learned, what did we learn, document decisions, or session analysis.

Write Architecture Decision Records following HikmaAI format. Use when user says write ADR, architecture decision, ADR, or decision record. Orchestrates refinement, research, writing, vault storage, and review. Not for implementation plans (use plan mode) or retrospectives (use learning-docs).

Android development with Kotlin, Jetpack Compose, Clean Architecture, and performance. Use when working with .kt files, build.gradle.kts, AndroidManifest.xml, or Compose UI.

Apple platform development with Swift, SwiftUI, async/await, and performance. Use when working with .swift files, Package.swift, Xcode projects, or building for iOS/macOS/watchOS/visionOS.

Write blog posts from Second Brain content, IDEAS.md, or free prompts. Use when user says write blog post, blog post, vault to blog, scrivi un post, blog ideas, what should I write about. Discovers topics from vault signals, drafts in Max's style, humanizes, generates cover. Not for processing content INTO the vault (use process-clippings, newsletter-digest).

AWS/GCP cloud infrastructure: Well-Architected, security, cost, observability. Use when working with Terraform outputs, IAM policies, VPC design, load balancers, or cloud architecture decisions. For HCL/module/state mechanics use the terraform skill; this one owns the architecture decisions.

Calculate a Cognitive Load Index (CLI) score (0-1000) for a codebase. Measures 8 dimensions of cognitive load using static analysis and LLM-based naming assessment.

Generate editorial cover images from article context. Use when user wants a cover image, hero image, or editorial illustration for an article or blog post. Not for table/diagram images (use table-image).

Local code review with Gemini CLI for pre-commit reviews. Use when user says review code, code review, check my changes, or review before commit.

Go development: conventions, architecture, concurrency, performance, and code review. Use when working with .go files, go.mod, or user asks about goroutines, channels, error handling, interfaces.

Build, run, and debug iOS apps via CLI without Xcode UI. Use when user wants to build iOS app, run on simulator, capture logs, take screenshots, or automate simulator interactions. Not for Swift code patterns (use apple-swift).

Safely modify legacy code lacking tests. Identifies seams, breaks dependencies, plans characterization tests. Invoke before verification-protocol when touching untested code with tangled dependencies.

Process web clippings into Second Brain. Use when user mentions clippings, asks to process articles, or wants to integrate saved content. Not for newsletters (use newsletter-digest) or email bookmarks (use process-email-bookmarks).

Python development with uv, type checking, linting, testing, and Docker deployment. Use when working with .py files, pyproject.toml, or user asks about pytest, mypy, ruff, FastAPI, Django.

React + Next.js App Router development. Use when working with .tsx/.jsx files, next.config, or user asks about Server Components, data fetching, state management, forms, or React testing.

Ruby gem development with modern tooling, testing, and publishing. Use when working with .gemspec, Rakefile, or user asks about gem structure, RSpec for gems, Bundler, or gem publishing. Not for Rails apps (use rails skill).

Render markdown tables as hand-drawn sketch images. Use when user wants a table rendered as an image, visual table, or diagram illustration.

Autonomous prompt optimization via eval-driven experiment loop (Karpathy autoresearch pattern). Use when user says autoresearch, prompt optimization, optimize prompt, or eval loop.

Harness optimization: analyze execution traces, propose rule/skill improvements. Use when user says optimize harness, harness review, improve rules, meta-harness, or /harness-mechanic. Not for trace capture (use harness-trace).

iOS 26+ Liquid Glass API for glassmorphism effects. Use when user wants glass effects, frosted backgrounds, translucent UI, or .glassEffect() modifier guidance.

Scaffold a Makefile with language-specific check targets (lint, vet, fmt, vuln, test). Auto-detects project languages from marker files. Use when user says project checks, scaffold checks, add make check, or /project-checks. Not for running checks (the advanced-review preflight does that).

Run the local quality gates (`make check` + `make test-e2e`) and report commit/PR/excellence readiness per `rules/quality-gates.md`. Use when user says /score, is this ready to commit, is this ready for a PR, or score my changes.

Bullet Journal management: daily/weekly/monthly logs, task migration, reviews. Use when user says daily log, bujo, weekly review, monthly log, journal, migrate tasks, what's on my plate. Not for task sync with external tools (use bujo-sync).

Bidirectional task sync between Bullet Journal and project tools (ClickUp, Linear). Use when user says sync tasks, bujo sync, pull from clickup, pull from linear, push tasks. Not for daily logs or reviews (use bujo).

Remove signs of AI-generated writing from text. Use when editing or reviewing text to make it sound more natural and human-written. Detects inflated symbolism, promotional language, superficial -ing analyses, vague attributions, rule of three, AI vocabulary, and more.

Obsidian vault operations via CLI. Use for note management, search, daily notes, knowledge graph analysis, tasks, properties. Not for Notion sync (use notion-sync).