From optimus
Discovers testing gaps and generates unit tests that follow project conventions. Conservative — only adds new test files, never refactors source code. Use when coverage is low or after adding new code lacking tests.
How this skill is triggered — by the user, by Claude, or both
Slash command
/optimus:unit-test [path][path]The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Improve unit test coverage for existing code. Requires `/optimus:init` to have set up test infrastructure (framework, coverage tooling, testing docs) first. Conservative by design — only adds new test files, never refactors or restructures existing source code. If code is untestable as-is, it flags it rather than changing it. Refactoring is the domain of `/optimus:refactor`.
Improve unit test coverage for existing code. Requires /optimus:init to have set up test infrastructure (framework, coverage tooling, testing docs) first. Conservative by design — only adds new test files, never refactors or restructures existing source code. If code is untestable as-is, it flags it rather than changing it. Refactoring is the domain of /optimus:refactor.
Extract from the user's arguments:
Examples:
/optimus:unit-test → full project/optimus:unit-test src/api → scopedIf your invocation prompt body contains HARNESS_MODE_INLINE, you are running inside the /optimus:unit-test-deep orchestrator as a single cycle (unit-test phase). Read $CLAUDE_PLUGIN_ROOT/references/coverage-harness-mode.md and follow its "Unit-Test Phase Execution" section: skip user confirmation, run Steps 2–4 exactly once, then output structured JSON via Step 6 and stop. Do not use AskUserQuestion. Do not loop.
Read $CLAUDE_PLUGIN_ROOT/skills/init/references/multi-repo-detection.md for workspace detection. If a multi-repo workspace is detected, process each repo independently: run Steps 1-5 inside each repo that has .claude/CLAUDE.md. Report results per repo. If no repos have been initialized, suggest running /optimus:init first from the workspace root.
Check that .claude/CLAUDE.md exists. If it doesn't, stop and recommend running /optimus:init first — the project needs baseline context before test generation can be effective.
Beyond the init check, identify which guideline documents are available — they directly affect the quality of everything this skill does:
| Document | Role | Effect on skill |
|---|---|---|
coding-guidelines.md | Primary quality reference | Tests follow naming conventions, code structure, quality standards |
testing.md | Testing conventions | Framework, runner commands, mocking patterns, file organization |
.claude/CLAUDE.md | Project overview | Tech stack signals, test runner commands |
Monorepo path note: Read the "Monorepo Scoping Rule" section of $CLAUDE_PLUGIN_ROOT/skills/init/references/constraint-doc-loading.md for doc layout and scoping rules. When generating tests for a subproject, load that subproject's testing.md, not another subproject's.
The skill operates differently depending on what exists:
Parse optional path argument (e.g., /optimus:unit-test src/api) to limit scope. If no path is specified, default to the full project.
For monorepos and multi-repo workspaces, detect project structure using the same approach as /optimus:init — read $CLAUDE_PLUGIN_ROOT/skills/init/references/project-detection.md for the full detection algorithm (workspace configs, manifest scanning, supporting signals; multi-repo workspace detection is already loaded from the pre-flight checks above). Process each project/repo independently.
Delegate test infrastructure scanning, test execution, and coverage analysis to a reconnaissance agent to keep the main context clean for test writing.
For each subproject (or the single project):
Read $CLAUDE_PLUGIN_ROOT/skills/unit-test/agents/shared-constraints.md for agent constraints.
Read $CLAUDE_PLUGIN_ROOT/skills/unit-test/agents/test-infrastructure-analyzer.md for the full prompt template, scanning patterns, execution rules, and return format for the Test Infrastructure Analyzer Agent.
When running under HARNESS_MODE_INLINE and the progress file's cycle.current is greater than 1, prepend a concise context block to the agent prompt before the main instructions. Source the data from the progress file's tests_created, untestable_code, and coverage.history. Include:
file → target entries from tests_created with status pass, so the agent skips re-discovering the same targets.tests_created with status fail-abandoned or similar, so the agent does not re-propose them.untestable_code, so the agent does not re-flag them; focus new discovery on genuinely new items.coverage.history.The goal is convergence: each cycle should propose new testable items, not duplicates. Keep the block under ~30 lines to limit context drift.
Launch 1 general-purpose Agent tool call using the prompt from test-infrastructure-analyzer.md, prepended with the shared constraints (and the cycle context block, if applicable).
| Agent | Role | Runs when |
|---|---|---|
| 1 — Test Infrastructure Analysis | Scan test files/frameworks/runners, run existing tests, measure coverage, classify code testability | Always |
Wait for the agent to complete.
If no test framework is detected in the agent's Discovery Results, stop and report: "No test framework found. Run /optimus:init (or re-run it) to install a test framework and set up test infrastructure before using this skill. For a project with no code or detectable stack yet, pick Scaffold new project when init asks — init builds a starter stack, then sets up the framework on it." Do not proceed to test generation without a working framework.
If the agent's Test Suite Execution reports failures, stop. This skill does not fix failing tests or build-level issues by design. Print the matching message below (Conversation / Mode / Next skill per $CLAUDE_PLUGIN_ROOT/references/skill-handoff.md).
Fail - assertion (tests compile and run, but some fail): print the quote below, then append a ### Bugs Discovered section listing each failing test as [test file] — [test name] — [one-line failure excerpt] (prefix entries with repo name/path in multi-repo workspaces; omit the excerpt if the test runner output did not expose it).
Pre-existing tests are failing. A green baseline is required before adding new tests, and this skill does not modify existing tests or source code.
Next: stay in this conversation (normal mode) and ask Claude to triage the failing tests listed in Bugs Discovered. Once the baseline is green, start a fresh conversation and re-run
/optimus:unit-test.Tip: for best results, start a fresh conversation for the next skill — each skill gathers its own context from scratch.
Fail - build (build/bootstrap failures): print the quote below and stop — no Bugs Discovered section (there are no per-test failures to list, only build errors the analyzer has already summarized).
The test runner cannot start or test files fail to compile. These are build-level issues, not test logic, and
/optimus:initowns that repair path.Next: start a fresh conversation in normal mode and run
/optimus:init— its health check will propose minimal fixes and re-run the suite. Once the build is healthy, start another fresh conversation and re-run/optimus:unit-test.Tip: for best results, start a fresh conversation for the next skill — each skill gathers its own context from scratch.
From the agent's results, present the Discovery Summary and Coverage Analysis to the user. This sets clear expectations and reinforces the conservative constraint.
Create a prioritized list, capped at 10 items per run:
Skip (flag in summary, don't attempt):
Harness mode: Skip the question — auto-select "Generate tests for all planned items" and proceed directly to Step 4. The orchestrator skill (/optimus:unit-test-deep) decides whether to iterate after Step 6 emits JSON.
Normal mode: Present the plan, then use AskUserQuestion — header "Plan", question "How would you like to proceed with the test generation plan?":
If the user selects Selective, ask which item numbers to proceed with (e.g., "1, 3, 5").
Tests must follow:
coding-guidelines.md for quality standards (naming, structure, clarity)testing.md for testing conventions (framework idioms, file naming, directory structure)$CLAUDE_PLUGIN_ROOT/skills/tdd/references/testing-anti-patterns.md for mocking discipline — prefer real code over mocks, never assert on mock behavior, mock only external services or non-deterministic dependenciesAnswer these gate questions — fix any "no" before proceeding:
testing.md (typically test_<module_name> or <module_name>.test).$CLAUDE_PLUGIN_ROOT/skills/tdd/references/testing-anti-patterns.md (already referenced in Quality standards above).coding-guidelines.md to test setup: repeated setup should be extracted to shared fixtures (setUp/beforeEach, conftest, factories).Only add new test files. Never refactor or modify existing source code — refactoring is the domain of /optimus:refactor. If a function can't be tested without changing its signature or extracting dependencies, flag it in the summary instead of changing it.
For each approved item:
After all tests are written, run the full test suite to ensure no regressions. Follow the verification protocol from $CLAUDE_PLUGIN_ROOT/skills/init/references/verification-protocol.md — run tests fresh, read complete output, and report actual results with evidence before claiming success.
If the full-suite run reveals that a newly-added test file causes regressions (either the new test itself failing under the full suite, or causing other tests to fail), revert that test file. In harness mode, record the affected item's status as fail-abandoned in the JSON output at Step 6.
Harness mode: Skip this step — Step 6 emits the structured JSON output instead.
Normal mode: Report to the user:
## Unit Test Summary
### Coverage
- Coverage tooling: [tool name / not configured]
- Before: [X]% → After: [Y]%
- Achievable target (without refactoring): ~[Z]%
### Tests Created
| # | File | Target | Status |
|---|------|--------|--------|
| 1 | src/__tests__/auth.test.ts | auth module exports | ✓ Pass |
| 2 | src/__tests__/validate.test.ts | validation utilities | ✓ Pass |
| ... | ... | ... | ... |
### Bugs Discovered
- [List of bugs found in existing code — reported, not fixed]
### Not Testable Without Refactoring
- [List of code flagged as untestable — with brief explanation of what structural change would be needed]
- To address these, run `/optimus:refactor testability` to prioritize testability improvements.
For multi-repo workspaces, present results per repo (one summary block per repo) and include the repo name/path in each section header.
Recommend running /optimus:refactor testability to prioritize testability improvements (or /optimus:refactor for balanced code quality review), or /optimus:tdd to continue development with test-driven workflow. If many untestable items were flagged or coverage gains are blocked behind untestable code, suggest /optimus:unit-test-deep which alternates test generation with testability refactoring in an automated loop.
Tell the user: Tip: for best results, start a fresh conversation for the next skill — each skill gathers its own context from scratch.
If running under HARNESS_MODE_INLINE, output structured JSON instead of the Step 5 markdown summary. The exact schema lives in $CLAUDE_PLUGIN_ROOT/references/coverage-harness-mode.md "Output structured JSON" — read it and emit the fenced block specified there. Then stop — do not loop, do not present recommendations, do not use AskUserQuestion.
npx claudepluginhub oprogramadorreal/optimus-claude --plugin optimusScouts test coverage gaps, creates test files, continues incomplete suites, tracks persistent coverage using project test config and git analysis.
Guides coverage-driven test writing for existing codebases: discovers untested user-facing behavior via coverage reports, writes one meaningful test per iteration, marks low-value code with ignore annotations.