How OpsKit works

The three-agent investigation loop

Every Kubernetes investigation runs through three agents with different jobs and a handoff protocol between them. None of the three overlaps.

1. k8s-investigator — gathers evidence, forms a hypothesis

Uses only the 15 read-only MCP tools. Every conclusion must cite the specific tool call, field name, and exact value that supports it. When evidence is insufficient, it says so explicitly rather than filling the gap with reasoning. It finishes by writing a sealed hypothesis — a structured block with the root cause statement, the full evidence chain, confidence level, and a list of what was not checked and why.

Critically: the investigator never proposes fixes. That is a separate agent's job.

2. k8s-reviewer — reaches an independent conclusion from the same evidence

The reviewer receives the same raw evidence bundle as the investigator, but not the sealed hypothesis. It forms its own independent conclusion first, then compares. If the two agree, confidence rises. If they disagree, that disagreement surfaces to you as the human — it is never silently resolved or averaged away.

This is the core design decision that makes OpsKit different from a single-agent system: the investigation cannot validate itself.

3. k8s-fixer — generates a GitOps PR, never a direct change

Only runs after both investigator and reviewer have agreed on a hypothesis. Resolves the owning Git repository from ArgoCD or Flux annotations, generates a minimal patch against the manifest, runs a client-side diff, and opens a PR with the evidence summary, rollback plan, and verification checklist attached. Auto-merge is never enabled.

What a full investigation looks like

/k8s-triage payment-service is CrashLoopBackOff

  k8s-investigator → reads pod, events, logs, resource spec
  k8s-investigator → sealed hypothesis (exit 137, OOM, limit 256Mi)
  k8s-reviewer    → independent conclusion: agrees, OOM confirmed
  k8s-fixer       → PR #47 opened: resources.limits.memory 256Mi → 512Mi
                    evidence bundle attached, rollback plan included

Evidence contracts — what is required before a conclusion

Each of the 33 investigation skills defines an evidence contract: the exact tool calls and field paths that must be present before any conclusion, the conditions that trigger an abstention instead of a guess, and the confidence level that results from each evidence pattern.

If an abstention condition is triggered — logs rotated out, metrics unavailable, conflicting signals — the investigation says so explicitly. It does not produce a low-confidence conclusion dressed up as a finding. See all 33 skills for the full evidence contract on each one.

The safety layer runs underneath all of this

A pre-tool hook intercepts every bash command before it executes and checks it against the opskit-guard allowlist. kubectl apply, helm upgrade, terraform apply, and 120+ bypass patterns are blocked at the OS level before reaching your cluster — independent of what any agent says or intends. The MCP server itself has no write tools, so there is nothing to accidentally call.

Beyond Kubernetes

The same investigation discipline applies to AWS, GCP, Azure, and Terraform via their own specialist agents. Each has a specific job scope, read-only constraints, and output formats designed to feed into the same evidence bundle. See all 42 agents for the full roster.