minottobot

Your friendly neighborhood QA developer.

minottobot is a QA software consultant persona, packaged as a plugin with eight skills. It audits software teams across CI/CD, testing, monitoring, Developer Experience, and culture — then builds a prioritized improvement plan.

The repository is an Agent Plugins 1.0.0 plugin — root plugin.json, skills under skills/ — and also ships the Claude Code and Codex manifests, so every client below installs it from the repo itself. No copying files around.

How to use

Claude Code:

/plugin marketplace add EmanueleMinotto/minottobot
/plugin install minottobot

Codex:

codex plugin marketplace add EmanueleMinotto/minottobot

Then install minottobot from that marketplace. Update later with codex plugin marketplace upgrade minottobot.

Once installed, describe your team or project and the relevant skill activates automatically. Most users want the default engagement — just describe your team and stop there.

Cursor

The repo is an Agent Plugin, so Cursor installs it as a plugin rather than as loose skill files.

Teams and Enterprise — Dashboard → Plugins → Add Marketplace → Import from Repo, pointing at https://github.com/EmanueleMinotto/minottobot. Enable Auto Refresh (requires the Cursor GitHub App) and installs track new releases automatically. Members then install it from Customize, at project or user scope.

Individual users — clone once and symlink the clone into Cursor's local plugin directory:

git clone https://github.com/EmanueleMinotto/minottobot.git ~/src/minottobot
mkdir -p ~/.cursor/plugins/local
ln -s ~/src/minottobot ~/.cursor/plugins/local/minottobot

Reload the Cursor window and the plugin shows up in Customize. Because it's a symlink, git pull in the clone is the whole update procedure.

Other agents

Any client that implements Agent Plugins 1.0.0 can install the repo directly — the root plugin.json and skills/ layout is all the spec requires.

For an agent that only understands plain Agent Skills directories and has no plugin installer, copying still works as a fallback: clone the repo and copy skills/* into whatever directory that agent reads skills from.

The skills

minottobot — the default engagement

Runs audit then automatically continues into strategy, using the audit's output as the strategy's input. This is what activates on general requests like "audit our team" or "how do we improve our testing" — describe your team once, get the full audit + plan back in one pass.

Example output

# Minottobot audit report — Acme Checkout squad — 2026-08-18

## Repos in scope
- checkout-web (React)
- checkout-api (Node)

## Executive summary
- CI is split across Jenkins and GitHub Actions with no authoritative pipeline — deploys can bypass review.
- Zero integration tests despite a 47-minute Jenkins build; regressions surface in production instead.
- No named owner for checkout-api since the last reorg — three months of unresolved P1s.

## Area scores (1 = critical · 5 = excellent)
| Area                    | Score | One-line finding                              |
|--------------------------|-------|-----------------------------------------------|
| CI/CD                    | 2/5   | Jenkins + GitHub Actions, no authoritative one |
| Testing                  | 2/5   | Unit only, 0 integration, 47-min build         |
| Code review               | 3/5   | Required on main, skipped on hotfix branch     |
| Monitoring                | 3/5   | Sentry present, no alerting on P1s             |
| Developer Experience      | 3/5   | Local setup documented, no staging parity      |
| Ownership & culture       | 2/5   | No named owner since reorg — 3mo unresolved P1s|

## Top 3 blockers right now
1. **No authoritative CI** — teams don't trust either pipeline enough to gate deploys on it.
2. **Ownership gap on checkout-api** — nobody has authority to prioritize the fix backlog.
3. **Zero integration coverage** — unit tests pass while checkout breaks in production.

## Improvement plan
### Short term (this sprint)
- Designate GitHub Actions as the single source of truth; make Jenkins advisory-only.
- Assign a named owner for checkout-api.

### Medium term (this quarter)
- Add integration tests around the checkout API's payment and cart endpoints.

### Long term (this half)
- Retire Jenkins once GitHub Actions has run in parallel for 4–8 weeks with no gaps.

## Action items
| ID | Description                          | Horizon | Owner | Status |
|----|---------------------------------------|---------|-------|--------|
| A1 | Make GitHub Actions authoritative      | short   |       | open   |
| A2 | Assign checkout-api owner               | short   |       | open   |
| A3 | Integration tests on payment/cart       | medium  |       | open   |

(Full reports also include the Phase 0 baseline and evidence/red-flags sections, trimmed here for length.)

audit

Assesses the team across ten areas — CI/CD, environments, local development, code review, testing, automation, monitoring, technical standards, and ownership culture — and produces a scored audit report (repos in scope, Phase 0 baseline, six-area score table with evidence-based caps). It looks for red flags and anti-patterns, and stops there: no improvement plan, no action items. Use it directly when you only want the diagnosis, or want to feed the same audit output into strategy more than once.

Example output

# Minottobot audit — Acme Checkout squad — 2026-08-18

## Repos in scope
- checkout-web (React)
- checkout-api (Node)

## Phase 0 baseline
- Team size: 6 engineers
- Total test count: 340 unit / 0 integration / 0 e2e
- Average CI run time: 47 minutes
- Deployment frequency: ~2/week
- Change failure rate: not tracked
- Days since last production incident: 4

## Area scores (1 = critical · 5 = excellent)
| Area                    | Score | One-line finding                              |
|--------------------------|-------|-----------------------------------------------|
| CI/CD                    | 2/5   | Jenkins + GitHub Actions, no authoritative one |
| Testing                  | 2/5   | Unit only, 0 integration, 47-min build         |
| Code review               | 3/5   | Required on main, skipped on hotfix branch     |
| Monitoring                | 3/5   | Sentry present, no alerting on P1s             |
| Developer Experience      | 3/5   | Local setup documented, no staging parity      |
| Ownership & culture       | 2/5   | No named owner since reorg — 3mo unresolved P1s|

## Evidence & red flags
- checkout-web has CI on every PR; checkout-api's Jenkins pipeline can be skipped with `[skip ci]`.
- 0 integration tests found despite payment logic spanning both repos.
- Last 20 commits on checkout-api: no conventional format, 6 direct pushes to main.

## Systems flagged for replacement evaluation
- Jenkins — 47-minute build, maintained by no one specific, duplicated by GitHub Actions on checkout-web.

strategy

Takes an audit output — from a fresh audit run, pasted by the user, or loaded from a saved .minottobot/ snapshot — and builds an improvement plan on three horizons:

• Short term — immediate pain relief, quick wins
• Medium term — foundations and frameworks
• Long term — structural improvement based on feedback

It reasons about trade-offs case by case, calibrates advice to team size and product context, and always evaluates options against a single golden rule: does this serve the user? Use it directly when you already have an audit output and only want the plan built from it.

Example output

## Executive summary
- CI is split across Jenkins and GitHub Actions with no authoritative pipeline — deploys can bypass review.
- Zero integration tests despite a 47-minute Jenkins build; regressions surface in production instead.
- No named owner for checkout-api since the last reorg — three months of unresolved P1s.

## Top 3 blockers right now
1. **No authoritative CI** — teams don't trust either pipeline enough to gate deploys on it.
2. **Ownership gap on checkout-api** — nobody has authority to prioritize the fix backlog.
3. **Zero integration coverage** — unit tests pass while checkout breaks in production.

## Improvement plan
### Short term (this sprint)
- Designate GitHub Actions as the single source of truth; make Jenkins advisory-only.
- Assign a named owner for checkout-api.

### Medium term (this quarter)
- Add integration tests around the checkout API's payment and cart endpoints.

### Long term (this half)
- Evaluate retiring Jenkins — migration requires porting pipelines, a 4–8 week parallel-run
  period, and dedicated CI team capacity; do not start without explicit resourcing.

## Action items
| ID | Description                          | Horizon | Owner | Status |
|----|---------------------------------------|---------|-------|--------|
| A1 | Make GitHub Actions authoritative      | short   |       | open   |
| A2 | Assign checkout-api owner               | short   |       | open   |
| A3 | Integration tests on payment/cart       | medium  |       | open   |

(Prepended with the "Repos in scope" and "Area scores" sections carried forward verbatim from the audit — trimmed here since they're shown in the audit example above.)

test-selection

Standalone — no audit required. Given a specific scenario ("what test should I write for this checkout flow?", "our E2E suite takes 45 minutes"), recommends the right test type (unit, integration, E2E, contract, visual regression, performance, mutation) using a decision matrix and heuristics. Both audit and strategy hand off to it on-demand when a testing gap surfaces mid-engagement.

Example output

"What test should I write for our checkout's payment confirmation step?"

This spans two internal services (cart → payment) plus a third-party payment gateway — start from the test pyramid, not the scenario alone.

• Unit — the discount/total calculation logic. Pure function, no external dependencies, fast feedback.
• Integration — cart-to-payment-service call, and the payment gateway call if a sandbox is available. This is where the interesting failure modes live (timeouts, partial charges).
• E2E — one test covering the full happy-path checkout journey. Don't add more than one or two here; it's a critical journey, not a place to re-test edge cases already covered below.

Skip contract tests unless the payment gateway's API changes without notice — not the case here since it's third-party with a stable, versioned API.

Watch out: if the gateway has no sandbox, fall back to a contract test against a mocked schema instead of hitting the real API from CI.

test-review

Standalone — no audit required. Reviews test code already written, not what to write next: weak or tautological assertions, tests that cover too much and should be split, magic numbers where a named constant belongs, whether a test actually verifies the requirement it claims to (when that information is available), alignment with the repo/team's own conventions, and whether a test sits at the right pyramid level (e.g. an E2E test that should be integration or unit). Whenever a finding is mechanically checkable, it also names the deterministic check — a specific lint rule, or a runner flag — that would catch that class of finding for free from then on, instead of leaving it to the next AI review. Complements the built-in code-review skill by owning the test-specific half of that judgment. audit and daily-prevention hand off to it on-demand; test-selection cross-references it as the "is it any good" counterpart to "what should I write."

Example output

"Review this test — does it actually cover what it says it does?"

it('rejects expired tokens', async () => {
  const res = await request(app).post('/refresh').send({ token: validToken });
  expect(res.status).toBe(401);
});

• Coverage — the test never expires the token; it sends validToken and still asserts 401. Either the assertion is wrong or the test doesn't test what its name claims — as written, it would pass even if expiry handling were deleted entirely.

• Best practice — 401 is a magic number; use HttpStatus.UNAUTHORIZED (or this repo's existing constant) if one already exists elsewhere in the suite.

• Pyramid placement — this is an HTTP-layer concern with no browser or full external dependency involved; if it's currently living in the E2E suite, it's a strong candidate to move to integration.

• Prevention — the magic number is mechanically checkable: @typescript-eslint/no-magic-numbers, scoped to test files, catches it on every future PR for free. The other two findings are semantic — no rule expresses them, which is exactly where an AI review earns its keep.

Watch out: fixing the assertion without fixing the setup (never actually expiring validToken) would still leave a test that can't fail for the right reason.

daily-prevention

Standalone — no audit required. Helps a developer keep day-to-day code simple, maintainable, and robust through automatable prevention rather than after-the-fact fixes: which linter and type checker fit the stack (adapting first to whatever is already configured, only proposing something new when a layer is missing or clearly obsolete), which rule preset to start from, and how to wire checks into the editor, pre-commit, and CI. For what static analysis can't catch — semantic intent, architectural drift — it points at AI-assisted review as a complement, not a replacement. Both audit and strategy hand off to it on-demand when a linting or static-analysis gap surfaces mid-engagement.

Example output

"We have zero linting or type checking on our TypeScript codebase. What should we set up?"

Start with typescript-eslint on its recommended preset plus tsc --noEmit in strict mode — don't jump straight to strict on an existing codebase, it'll bury you in warnings on day one.

• Editor — instant feedback as you type, zero friction.
• Pre-commit — full lint + format on changed files. Rust-based tools (Biome is worth considering here too) are fast enough now that "too slow for pre-commit" isn't really true anymore.
• CI — the backstop. Full lint + full type-check, nothing merges without it.

Watch out: don't enable every rule at once — a wall of warnings nobody has time to fix just gets the linter muted, which is worse than not having one.

reality-check

Standalone — no audit required. A fast, honest, current-state pulse check for a team lead or engineering manager — what's actually happening right now, not a scored assessment. When connected, it pulls live data from issue-tracker, VCS, and monitoring MCP servers; when not, it asks directly for the same data points. Deliberately lighter-weight than audit — use it before a 1:1 or standup, not before a quarterly review.

Example output

"Give me a reality check on my team before my 1:1s."

Connected to your team's GitHub and Sentry MCP servers — here's what's live:

• What's on fire — error rate is up 3x since yesterday's 2pm deploy (from Sentry) — worth checking before anything else.
• What's slower than it should be — median PR review time has crept from 4h to a day and a half over the last two weeks (from GitHub) — nobody's flagged it, but it's trending the wrong way.
• What's actually fine — open PR count is normal, no stale PRs over a week old (from GitHub).

This isn't a scored audit — if you want a structured, evidence-based assessment with a plan attached, that's what audit + strategy are for.

breaking-change-detector

Standalone — no audit required. Helps API producers and consumers catch actual or potential breaking changes across REST/OpenAPI, GraphQL, gRPC/Protobuf, and consumer-driven contracts — picking the right tool (oasdiff, GraphQL Inspector, Buf breaking, Pact) for the API type, mapping changes onto SemVer, and covering the deprecate-before-remove workflow. Both audit and strategy hand off to it on-demand when unmanaged API compatibility risk surfaces mid-engagement.

Example output

"We want to remove a field from our public REST API's response. How do we make sure we don't break consumers?"

Deprecate it first, don't remove it directly — mark it deprecated in the OpenAPI spec, measure whether it's still seeing traffic, then remove once the window's passed.

Run oasdiff as a CI check on every PR that touches the spec, diffing against the target branch — it flags the removal as breaking, and you can gate the merge on an accompanying version bump. This is a MAJOR-worthy change once the field actually comes out; deprecating it first is what keeps that MAJOR bump from arriving as a surprise.

Watch out: don't bundle this removal with unrelated additive changes in the same release — it muddies what the version bump is actually signaling.

Code inspection

When running inside a repository (Claude Code or any environment with file-system access), the audit skill reads the codebase before asking questions.

It starts by mapping which repositories are in scope — a single repo, multiple separate repos, or a monorepo with distinct sub-projects. It detects the primary technology of each from manifest files (package.json, go.mod, pyproject.toml, etc.) and adapts its scanning patterns accordingly.

For each repo it scans: CI/CD configs, test files and test config, build scripts, lint/format configs, monitoring integrations, git history (last 20 commits), and onboarding documentation.

After scanning all repos it produces an evidence map and flags cross-repo gaps — discrepancies between repositories (e.g., one has CI and the other doesn't) are often the most significant findings. If a Phase 0 answer contradicts what the code shows, the audit flags it explicitly. The contradiction is itself a finding.

Code inspection does not replace the Phase 0 questionnaire. Operational metrics (MTTR, incident count, deployment frequency) can't be read from code — those still require the team's input.

Multi-session tracking

Progress can be tracked across sessions using a snapshot file stored in the repository.

At the end of every engagement, strategy produces a snapshot and asks you to save it as .minottobot/audit-YYYY-MM-DD.md in your workspace root. The snapshot uses a fixed schema (area scores, top blockers, action items with stable IDs) so audits can be compared over time.

When you start a new session and a previous snapshot exists, audit enters returning engagement mode: it shows a summary of the last audit (date, repos, scores, blockers) and asks what has changed. At the end of the new plan, strategy appends a delta view to the report:

• Score changes per area (CI/CD: 2/5 → 3/5 ↑)
• Blockers resolved, still open, or new
• Action item status changes (open → done)
• Repo scope changes (repos added or removed between sessions)

Action items have stable IDs (A1, A2, ...) that persist across sessions, so progress is traceable without manual cross-referencing.

What minottobot doesn't do

• Product features and roadmap — only how to build, never what to build
• Infrastructure — cloud, scaling, networking
• ISO or regulatory certifications

When each skill activates

The skill descriptions are intentionally explicit and slightly over-broad so skill routers don't miss them.

Prompts that SHOULD trigger the default minottobot engagement

1. "Our CI pipeline is broken and builds are failing randomly."
2. "How do we improve our testing strategy?"
3. "We need a QA strategy for our new microservices project."
4. "Can you review our code review process?"
5. "Our test coverage has dropped to 40% — what do we do?"
6. "We have a bunch of flaky tests that keep failing in CI."
7. "How healthy is our CI/CD setup?"
8. "Our deployments take forever and we want better developer experience."
9. "Audit our engineering team's quality practices."

Prompts that trigger test-selection directly

1. "We're not sure what kind of test to write for this feature."
2. "Unit or integration test for this ORM query?"

Prompts that trigger test-review directly

1. "Review this test — is it any good?"
2. "Does this test actually verify what it claims to?"

Prompts that trigger daily-prevention directly

1. "What linter should we use for this TypeScript project?"
2. "Set up pre-commit hooks to catch bugs before they're committed."

Prompts that trigger reality-check directly

1. "Give me a quick pulse check on my team before my 1:1s."
2. "What's actually going on with our sprint right now?"

Prompts that trigger breaking-change-detector directly

1. "Will removing this field break our API consumers?"
2. "How do we catch breaking changes in our GraphQL schema before they ship?"

Prompts that should NOT trigger minottobot

1. "Can you help me implement this new feature?" — product/feature work, out of scope
2. "How do I configure our Kubernetes cluster?" — infrastructure, out of scope
3. "Write a regex that validates email addresses." — general programming task
4. "What cloud provider should we use?" — infrastructure decision, out of scope
5. "Explain how React hooks work." — general technical education, not a team/process question

Repository structure

plugin.json                ← Agent Plugins 1.0.0 manifest (this repo root is the plugin)
.claude-plugin/
  plugin.json              ← Claude Code manifest
  marketplace.json         ← self-hosted catalog, so this repo can be added directly
.codex-plugin/
  plugin.json              ← Codex manifest
.agents/plugins/
  marketplace.json         ← self-hosted catalog for `codex plugin marketplace add`
skills/
  minottobot/SKILL.md      ← default: orchestrates audit → strategy
  audit/
    SKILL.md
    references/
      checklist.md          ← step-by-step audit guide
      red-flags.md          ← anti-patterns and warning signs
      session-resume.md     ← returning-engagement greeting
  strategy/
    SKILL.md
    references/
      strategy.md           ← post-audit planning and trade-off reasoning
      philosophy.md         ← core beliefs and communication style
      frameworks.md         ← DFER loop, test pyramid, feature flags, git history
      snapshot-delta.md     ← snapshot format and delta view
  test-selection/
    SKILL.md                ← standalone test-type decision guide
  test-review/
    SKILL.md                ← standalone test-quality review guide
  daily-prevention/
    SKILL.md                ← standalone static-analysis/linting decision guide
  reality-check/
    SKILL.md                ← standalone, MCP-aware current-state pulse check
  breaking-change-detector/
    SKILL.md                ← standalone API breaking-change decision guide