Skip to content

CLAUDE.md

Latest commit

 

History

History
305 lines (220 loc) · 11.6 KB

CLAUDE.md

File metadata and controls

305 lines (220 loc) · 11.6 KB
Raw

cub-scout

GitOps explorer for agents: a read-only Kubernetes observer. Detects ownership (Flux, ArgoCD, Sveltos, Modelplane, Helm, Crossplane, kro, ConfigHub, Native).

Read First

For a fresh coding session in this repo, read these in order:

  1. AI-README-FIRST.md
  2. HANDOVER.md
  3. docs/reference/commands.md
  4. docs/reference/cli-contract.md
  5. docs/reference/json-contracts.md

Related Abilities

  • cub-scout: read-only cluster/GitOps observation, connected comparison, import preview, MCP serving
  • cub: ConfigHub CLI for intended-state workflows, spaces/units/targets, cub variant upload
  • confighub/sdk: renderer/bridge implementation detail used by cub

Important boundary:

  • cub-scout import --git-path is a local structure/import-preview flow
  • cub variant upload ingests already rendered resources (a directory, -, or an oci:// bundle) and makes a space's units match them; the rendering is done by your own tooling (helm template, kustomize build, an installer)
  • cub gitops discover and cub gitops import no longer exist: cub removed the whole gitops group in July 2026, and nothing replaced the render-target model (#573)
  • do not claim that cub-scout can do SDK renderer work unless current code/help exposes it

Build & Run

go build ./cmd/cub-scout
./cub-scout map              # Interactive TUI
./cub-scout map list         # Plain text
./cub-scout trace deploy/x -n y
./cub-scout scan
./cub-scout gitops status    # GitOps pipeline health (v0.14)
./cub-scout graph export     # Resource graph (v0.6)
./cub-scout patterns detect  # Pattern detection (v0.7)

Always use ./cub-scout (local binary), not cub-scout.

Output formats (v0.14): Most commands support --format ascii|json|md.

Claude Capability-Assistant Mode

For demo flow "Can I do X with cub-scout or ConfigHub?":

Documentation

File Purpose
README.md Project overview, install, quick start
CLI-GUIDE.md Workflow-first CLI guide
docs/reference/cli-reference.md Complete command catalog (A-Z)
docs/reference/commands.md Detailed command usage and examples
CONTRIBUTING.md How to contribute
docs/semantic-contract.md ASCII vs JSON meaning contract (R1-R6)
evals/README.md Agent evals: running, recording, and growing the suite

Key Principles

  1. Single cluster — standalone mode inspects one kubectl context; multi-cluster only via connected mode
  2. Read-only by default — never modifies cluster state
  3. Deterministic — same input = same output, no AI/ML
  4. Parse, don't guess — ownership from actual labels, not heuristics
  5. Complement GitOps — works alongside Flux, Argo, Sveltos, Modelplane, Helm
  6. Graceful degradation — works without cluster, ConfigHub, or internet
  7. Test everything — go test ./... must pass
  8. CLI/TUI parity — CLI and TUI are two renderings of one model. Every feature must have both a CLI command (with --format ascii|json|md) and a TUI equivalent. CLI is not a second-class citizen.
  9. Measured for agents — agents are the primary users of cub-scout's evidence. Claims that cub-scout helps an agent cite the agent evals (evals/README.md), with and without cub-scout on the same evidence; where it adds nothing, say so.

Current Milestone Reality

Use HANDOVER.md as the latest execution snapshot.

As of the current handover:

  • the Argo truth-and-guidance track is closed (#365, #366, #367)
  • the Git import parser track is complete through ApplicationSet generator support (#363)
  • #369 is shipped: doctor is now the first standalone MCP troubleshooting tool
  • #364 is investigated, not a mandate to merge cub-scout with cub's import path
  • the highest-leverage open queue is now #370, then #368

Directory Structure

Path Purpose
cmd/cub-scout/ CLI commands, TUI
pkg/agent/ K8s watcher, ownership detection
test/ Tests

Ownership Detection

Owner Detection
Flux kustomize.toolkit.fluxcd.io/* or helm.toolkit.fluxcd.io/* labels
ArgoCD argocd.argoproj.io/instance label or tracking-id annotation
Sveltos projectsveltos.io/owner-kind + projectsveltos.io/owner-name annotations, Sveltos ownerRef, or Sveltos API group
Modelplane modelplane.ai / infrastructure.modelplane.ai API groups, Modelplane identity labels, or Modelplane ownerRef
Helm app.kubernetes.io/managed-by: Helm
Terraform app.terraform.io/run-id annotation or managed label
Crossplane crossplane.io/claim-name label (experimental)
kro kro.run/* labels/annotations, kro ownerRef, or kro API group
ConfigHub confighub.com/UnitSlug label
Native None of the above

Testing

go build ./cmd/cub-scout
go test ./...

Backlog Tracking

Future ideas live in supplemental planning docs (docs/roadmap-*.md, docs/reference/*-product-guide.md). These are non-authoritative and easy to forget during sprint planning.

Rules:

  • docs/roadmap.md contains an Untracked Backlog Checklist at the top
  • When a new idea appears in any planning doc, add it to the checklist
  • When an item graduates to real work, file a GitHub issue and remove the checklist entry
  • The master tracking issue is #154 — keep it current

This prevents ideas from being trapped in prose nobody re-reads.

Pre-Coding Test & Success Proof Requirements

All feature and bugfix issues must define success before implementation.

1. Deterministic Unit Tests (Required)

  • Define exact inputs (fixtures, manifests, objects)
  • Define expected outputs (ownership classification, lineage graph, buckets)
  • Tests must be: order-independent, K8s-version tolerant, runnable without live cluster

2. Example / Full Test Coverage (Required for user-visible behavior)

  • Add or extend an example under examples/
  • Or explicitly reference an existing example it validates against
  • Examples serve as: regression protection, documentation, demo artifacts

3. E2E / Integration Proof (Required unless explicitly waived)

For features affecting real cluster behavior, define validation in:

  • Standalone mode (single cluster, kubectl context)
  • Connected mode (mocked or recorded if CI cannot auth)
  • Fleet mode (if behavior aggregates across clusters)

If E2E cannot run in CI: provide reproducible local script or contract test with recorded inputs/outputs.

4. Graceful Degradation Rules (Required)

Each issue must state:

  • What happens when metadata is missing
  • How partial results are surfaced
  • How false "unmanaged/orphan" states are avoided

5. Agent Eval Case (Required for agent-facing behavior)

A change to MCP tool output, a skill, or a new kind of evidence an agent should use:

  • Adds or updates an eval case under evals/ that asks the question it answers
  • Re-records the fixtures in the same PR when tool output changes
  • An agent-facing bug fix adds a case that fails without the fix

See evals/README.md. Eval scoring runs on recordings, never a live cluster.

6. Definition of Done

An issue is complete only when:

  • Tests exist and pass
  • Examples demonstrate expected behavior
  • User-facing output is correct and explainable
  • Agent-facing changes have an eval case, and its result is known

cub-scout v0.5 Delivery Addendum

Historical note: the remainder of this file preserves older delivery-phase rules. Current execution priority and milestone state live in AI-README-FIRST.md and HANDOVER.md.

This addendum defines how the principles in this document are applied during the v0.5 delivery phase.

v0.5 is a trust and utility milestone, not a completeness milestone.

The goal is to ship a version that users can rely on daily, with clearly bounded capabilities and explicitly documented limitations.

v0.5 Priorities (In Order)

During v0.5 delivery, decisions MUST be evaluated against these priorities, in descending order:

  1. Correctness of ownership and provenance

    • cub-scout must not make false claims about where resources came from.
    • Unknown or ambiguous states are always preferable to incorrect certainty.

  2. Honest, explainable output

    • Partial results are acceptable if clearly explained.
    • Errors must explain what failed and why, not just that something failed.

  3. Stability of the TUI and CLI

    • No panics, crashes, or undefined navigation behavior.
    • Predictable keybindings and command behavior.

  4. Scope discipline

    • Features that dilute trust or stability are out of scope.
    • v0.5 is intentionally narrow.

Completeness, performance optimizations, and breadth of controller support are explicitly secondary during this phase.

Core Principles (Never Waived)

The following principles are non-negotiable for v0.5:

  • Deterministic behavior
  • Parse, don't guess
  • Read-only by default
  • No AI/ML inference
  • Avoid false ownership or orphan claims
  • Graceful degradation in the presence of missing or partial data

Any change that violates these principles MUST NOT ship.

Strong Defaults (May Be Deferred with Explicit Waiver)

The following expectations remain strong defaults but may be deferred for v0.5 only if a waiver is explicitly recorded:

  • Full end-to-end (E2E) test coverage
  • Exhaustive controller support
  • Complete example coverage for all edge cases
  • Fleet-scale or connected-mode parity

Deferral is acceptable only when the failure mode is safe and documented.

Waivers (v0.5 Only)

A requirement may be waived during v0.5 delivery only if all conditions below are met:

  1. The limitation is clearly documented (code comment, issue, or docs).
  2. The failure mode is safe:
    • No false positives
    • No misleading ownership or health claims
  3. A follow-up issue is filed and labeled appropriately.

Waivers MUST be visible and intentional. Silent corner-cutting is not acceptable.

Testing Expectations for v0.5

For v0.5:

  • Logic affecting ownership, provenance, or reconciliation reasoning MUST have deterministic tests.
  • UI and CLI changes MUST be exercised against at least one real cluster.
  • E2E tests are strongly encouraged but may be deferred via waiver.

The absence of a test is acceptable only if:

  • The behavior is explicitly documented as provisional, AND
  • The risk surface is understood and bounded.

Release Bar for v0.5

v0.5 is considered shippable only if:

  • Ownership claims are reproducible and conservative.
  • The TUI does not panic on malformed or minimal clusters.
  • Known limitations are explicitly documented.
  • The tool can be recommended to another operator with clear caveats.

Post–v0.5 Expectation

This addendum is temporary.

Future releases may:

  • Remove waiver allowances
  • Tighten testing requirements
  • Raise the completeness bar

All work done under v0.5 constraints should assume later hardening.