Optimus Claude

A Claude Code plugin that sets up your project for effective AI-assisted engineering.

The problem: AI amplifies whatever it finds. Messy code leads to messier AI-generated code, which becomes the new context for even worse output — a vicious cycle that compounds faster than any human could create technical debt. Without maintained context, any AI coding tool's quality degrades with every file it reads.

The solution: Optimus Claude generates tailored and optimized CLAUDE.md files, coding guidelines, formatter hooks, TDD and test coverage, all based on your actual codebase. Built-in quality agents (code simplifier, test guardian) run alongside reviews and TDD cycles; refactor runs the code simplifier plus its own consistency and testability agents.

Use it regularly and your project stays clean, consistent, tested, and well-documented. Exactly the conditions where Claude Code performs at its prime.

The philosophy: This is all about perfecting context. The codebase, prompts, unit tests, docs, commit messages, PR descriptions, branch names — it's all context and it all adds up to shape how well Claude Code performs. Optimus Claude provides developers ways to create and maintain optimal context for AI-assisted engineering across the entire development workflow.

Quick Start

Install

Run these commands inside Claude Code:

/plugin marketplace add https://github.com/oprogramadorreal/optimus-claude.git
/plugin install optimus@optimus-claude

Having trouble? See Troubleshooting.

Run

Start a new Claude Code session and type /optimus:init in any project directory. See Skills for the full list.

How It Works

Every skill operates on the same shared foundation: your project's quality guidelines (coding guidelines for code, skill-writing guidelines for markdown instruction projects) and a verification protocol that demands evidence over confidence.

/optimus:init analyzes your codebase and generates constraint docs — coding guidelines, CLAUDE.md, formatter hooks, and test infrastructure (framework, coverage tooling, testing docs) — into your .claude/ directory. It detects your project's stacks (Python, Node, Rust, UI frameworks, etc.) and installs the matching quality doc for each. This includes skill authoring as a recognized stack: if your project is a Claude Code plugin, a Codex skill repo, a prompt library, or any other project whose "source code" includes markdown instructions authored for an AI agent, init installs skill-writing-guidelines.md alongside coding-guidelines.md, and review/refactor skills route markdown instruction files through the skill-writing lens while routing code files through the coding lens. The plugin bundles quality agents at two levels: plugin-level agents (code-simplifier, test-guardian) that define reusable quality concerns, and skill-level agents that adapt them for specific workflows within skills like code-review, refactor, and tdd. Skill-level agents often extend the plugin-level definitions with skill-specific scope and output format — see references/agent-architecture.md for the full architecture. From that point on, skills that analyze or modify code load the relevant guidelines, and skills that make completion claims apply the verification protocol as a gate before reporting.

/optimus:code-review doesn't run a generic review — its agents check your naming conventions, your architectural patterns, and your DRY principles alongside bugs and security. For projects with a skill-authoring stack, it also reviews markdown instruction files against your skill-writing conventions (progressive disclosure, writing style, reference-depth limits). /optimus:tdd applies coding-guidelines.md during the Refactor step. /optimus:refactor uses them as its quality lens. /optimus:unit-test follows them for test naming and structure.

Every skill is also conservative by default — /optimus:unit-test never refactors source code, and /optimus:commit warns about secret files before proceeding.

The result: consistent patterns, meaningful names, and lean context across every operation — exactly the signals that keep Claude Code accurate and productive.

Design Principles

Explicit invocation — Skills never auto-trigger. The plugin's only automatic component is a lightweight, read-only SessionStart hook that surfaces project state (e.g., init not yet run, unpushed commits); everything else runs only when you explicitly call a /optimus skill.

Project-scoped output — Formatter hooks and coding guidelines are installed into .claude/ and travel with the repo via git — self-contained and working for every teammate without the plugin. The plugin layers development skills on top: TDD, code-review, commit, refactor, and more.

Skills

Core

Utility

Recommended Workflow

1. Safety guardrails — /optimus:permissions for branch protection, precious file safety, and streamlined tool permissions
2. Initial setup — /optimus:init to generate project context and set up test infrastructure (audits and updates if already present)
3. Test coverage — /optimus:unit-test to write tests and improve coverage (or /optimus:unit-test-deep for an automated multi-cycle coverage + testability refactoring loop with fresh context per phase)
4. Code quality — /optimus:refactor for full codebase refactoring against your coding guidelines and testability (if unit-test flagged untestable code, use /optimus:refactor testability then re-run /optimus:unit-test after refactoring — or use /optimus:unit-test-deep which automates this cycle)

During development:

Each skill recommends the next step based on task complexity — you don't need to memorize these paths. Any /optimus:tdd step above can be swapped for /optimus:workflow to build the spec as a self-orchestrated parallel dynamic workflow (test-first as a quality bar) instead of supervised TDD cycles — /optimus:workflow launches directly in normal mode: where a flow above has a plan mode → /optimus:tdd sequence, it replaces both together; where it has a bare /optimus:tdd step, it simply takes that step's place (there is no plan-mode iteration before a workflow). Also available: /optimus:branch to move work to a properly named branch, /optimus:worktree for parallel isolated workspaces, /optimus:prompt to craft optimized prompts for any AI tool, /optimus:commit for conventional commits (or /optimus:commit-message to preview).

Stakeholder-facing features? Acceptance criteria are a first-class part of the design artifact (see /optimus:brainstorm in the Skills table above) — no new skill, no Cucumber/Gherkin tooling.

Before merging — keep intent flowing from implementation to review:

The canonical chain is implement (e.g., /optimus:tdd) → /optimus:commit → /optimus:pr → /optimus:code-review. /optimus:commit and /optimus:pr are continuation skills — they capture the implementation conversation's context into durable artifacts (commit messages, PR description). When /optimus:tdd is the implement step, its per-cycle auto-commits replace the /optimus:commit step and its Step 9 pushes the branch automatically, so the flow collapses to /optimus:tdd → /optimus:pr → /optimus:code-review with the first two in the same conversation. /optimus:code-review gathers its own context from a fresh conversation.

/optimus:commit-message is the read-only sibling of /optimus:commit and is also a continuation skill; see references/skill-handoff.md for the full list.

1. Implement your changes in a conversation (TDD, brainstorm-driven, or freeform).
2. Stay in the implementation conversation and run /optimus:commit — it can capture the "why" from the conversation into the commit message body, not just summarize the diff.
3. Still in the same conversation, run /optimus:pr — it captures decisions, scope, non-goals, and trade-offs into the PR description for downstream review.
4. Switch to a fresh conversation and run /optimus:code-review. It reads the PR description as author intent context and checks whether the implementation delivers what was supposed to be built, not just whether it follows style guidelines.

See references/skill-handoff.md under "Continuation skills" for the full list. Each upstream skill's closing tip differentiates continuation skills (stay in conversation) from non-continuation skills (start fresh) so you don't have to remember the rule.

After major changes — re-run /optimus:init to audit and refresh guidelines.

New to a codebase? — /optimus:how-to-run generates a HOW-TO-RUN.md that teaches a new developer how to set up their environment and run the project locally.

Removing optimus — /optimus:reset to remove optimus-generated files from the project (for clean reinstall or to stop using optimus).

Why It Works

What makes a good developer productive also makes Claude Code productive: clean code, good tests, and clear docs.

Research backs this up: AI tools introduce 30%+ more defects on poorly maintained code, and LLM performance degrades up to 85% as context length grows. Clean, DRY code with meaningful names keeps context lean and gives the LLM better semantic signals. The 2025 DORA report puts it simply: AI amplifies existing practices, good or bad.

Another key point: providing LLMs with tests alongside tasks consistently improves code generation. Tests enable self-correction. Anthropic's #1 best practice for Claude Code reflects this: "make the AI self-verifying". Unit tests and TDD are the purest way to achieve it.

AI assistants also tend toward sycophancy — validating ideas without critical pushback. A 2025 METR trial found developers using AI were 19% slower yet believed they were faster. This plugin counters that: every skill enforces project-defined standards as the source of truth, a shared verification protocol requires evidence before any completion claim and challenges assumptions before committing to an approach, code review runs independent duplicate guideline agents and verifies each finding against the actual code, and TDD ensures tests define what is correct instead of relying on the AI's confidence.

Complementary Tools

optimus-claude is designed to work alongside official tools, not replace them. Use Anthropic's official code-review plugin for post-push PR review, claude-md-management for CLAUDE.md scoring and revision, the builtin /simplify for per-change cleanup (complemented by /optimus:refactor for project-wide restructuring), and Claude Code's built-in sandboxing or Docker containers for fully autonomous agent execution with OS-level isolation.

Claude Code's dynamic workflows are complementary rather than competing. The /optimus:*-deep skills are slash-invoked auto-fix orchestrators that persist progress to disk and resume across sessions, with no dependency on a research-preview feature — while /optimus:prompt can emit prompts that trigger a native dynamic workflow for one-off background fan-outs (its Template N). Reach for a *-deep skill for the iterative fix loop; reach for a dynamic workflow for a one-off, background, multi-agent sweep.

Claude Code's /goal command is similarly complementary, not a replacement for the *-deep skills. /goal sets a session-scoped completion condition and auto-iterates until a read-only evaluator judges it met — it never runs the test suite itself, isn't checked into the repo, and accumulates context within one session. The *-deep skills provide what that can't: deterministic test bisection (reverting the exact fix that broke the build), a fresh subagent per iteration so context never decays, resumable on-disk progress, and a checked-in, CI-gated contract. Reach for /goal for lightweight, autonomous "work until a verifiable end-state" in a single session; reach for a *-deep skill for the deterministic, resumable, team-shareable fix loop (/optimus:workflow remains the option for an autonomous parallel build, /optimus:tdd for supervised test-first). One caveat when pointing /goal at optimus: the skills set disable-model-invocation: true, so a goal condition that depends on a /optimus:* skill the model can't auto-invoke may never be satisfied and can loop — invoke the skill yourself and let the goal judge the result.

Troubleshooting

Windows: SSL certificate error during install

If you see SSL certificate OpenSSL verify result: unable to get local issuer certificate when running /plugin marketplace add, Git for Windows is using an outdated OpenSSL CA bundle. Fix it by switching to the native Windows certificate store:

git config --global http.sslBackend schannel

Then retry the install command.

Upgrading from 1.x: deep harness mode and the Python harness scripts are gone

2.0 replaced the two terminal-run Python harnesses with three in-conversation orchestrator skills. If you scripted the old entry points, migrate:

The *-deep skills run inside your Claude Code conversation, persist state to .claude/*-deep-progress.json, support --resume, and accept --yes for non-interactive/CI use (e.g. claude -p "/optimus:code-review-deep --yes 'src/auth'").

Contributing

See CONTRIBUTING.md for project structure, skill anatomy, feature branch testing, and local development setup.

Acknowledgements

The /optimus:prompt skill's prompt engineering techniques (intent extraction, tool routing, diagnostic patterns, templates, safe/excluded technique classification) are adapted from prompt-master by @nidhinjs.

Research & References

• Claude Code Best Practices — Anthropic: testing as #1 practice, compact CLAUDE.md, deterministic hooks, custom subagents
• How TDD Amplifies AI Success — DORA Report 2025: AI adoption increases delivery instability; TDD provides the control system
• Code for Machines, Not Just Humans — Borg et al. 2026: AI defect risk increases 30%+ on unhealthy code
• AI-Friendly Code Design — Thoughtworks Tech Radar Vol. 32: "good software design for humans also benefits AI"
• Context Length Alone Hurts LLM Performance — Du et al. 2025: 13.9%–85% degradation as input length increases
• Writing a Good CLAUDE.md — HumanLayer: WHAT/WHY/HOW structure, progressive disclosure, <60 lines
• Test-Driven Development for Code Generation — Mathews et al. 2024: providing LLMs with tests alongside problem statements consistently improves code generation outcomes
• AI Makes Engineering Discipline More Important — Codemanship 2026: 71% of developers say disciplined practices like TDD become more important with AI, not less
• AI Developer Productivity: Perception vs. Reality — METR 2025: experienced developers were 19% slower with AI but believed they were 24% faster — a striking confirmation bias gap
• Sycophancy in AI: The Risk of Complacency — SciELO 2026: AI sycophancy increases short-term productivity but reduces quality of collaborative work
• LLM-Powered Devil's Advocate for Decision-Making — IUI 2024: multi-agent debate reduces social influence bias and fosters balanced evaluation