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 every review and refactor.

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 coding guidelines 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. 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, every optimus skill loads those 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. /optimus:tdd applies them 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, /optimus:verify runs in an isolated sandbox and never pushes to remote, 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. Claude Code's default behavior is never altered unless 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
4. Code quality — /optimus:refactor for full codebase refactoring against your coding guidelines and testability

During development — /optimus:branch to move work to a properly named branch, /optimus:tdd to build features test-first, /optimus:worktree for parallel isolated workspaces, /optimus:prompt to craft optimized prompts for any AI tool in your workflow, /optimus:commit for conventional commits (or /optimus:commit-message to preview the message without committing).

Before merging — /optimus:pr to create or update pull requests, /optimus:verify to prove the feature branch works in an isolated sandbox, /optimus:code-review for pre-merge code quality review.

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

New to a codebase? — /optimus:dev-setup ensures the README has accurate development setup instructions for onboarding.

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.

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.

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