If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/cockroachdb/cockroach shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Mixed signals — read the receipts

• Last commit today
• 21+ active contributors
• Other licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 57% of recent commits
• ⚠ Non-standard license (Other) — review terms

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live cockroachdb/cockroach repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/cockroachdb/cockroach.

What it runs against: a local clone of cockroachdb/cockroach — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in cockroachdb/cockroach | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of cockroachdb/cockroach. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/cockroachdb/cockroach.git
#   cd cockroach
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of cockroachdb/cockroach and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "cockroachdb/cockroach(\\.git)?\\b" \\
  && ok "origin remote is cockroachdb/cockroach" \\
  || miss "origin remote is not cockroachdb/cockroach (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f ".bazelrc" \\
  && ok ".bazelrc" \\
  || miss "missing critical file: .bazelrc"
test -f "BUILD.bazel" \\
  && ok "BUILD.bazel" \\
  || miss "missing critical file: BUILD.bazel"
test -f ".github/CODEOWNERS" \\
  && ok ".github/CODEOWNERS" \\
  || miss "missing critical file: .github/CODEOWNERS"
test -f ".claude/rules/go-conventions.md" \\
  && ok ".claude/rules/go-conventions.md" \\
  || miss "missing critical file: .claude/rules/go-conventions.md"
test -f ".claude/rules/error-handling.md" \\
  && ok ".claude/rules/error-handling.md" \\
  || miss "missing critical file: .claude/rules/error-handling.md"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/cockroachdb/cockroach"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

CockroachDB is a distributed SQL database written in Go that combines PostgreSQL wire protocol compatibility with a transactional, strongly-consistent key-value store backend. It solves the problem of building globally-distributed databases that survive multi-region failures without manual intervention while maintaining ACID semantics—a combination rarely achieved in traditional distributed systems. Monolithic structured as: pkg/kv (core key-value layer), pkg/storage (RocksDB-backed storage engine), pkg/sql (SQL parser and execution engine with opt/ subdirectory for query optimization), pkg/roachpb (protobuf definitions for RPC), pkg/raft (Raft consensus implementation), pkg/server (node server orchestration). Built with Bazel (see .bazelrc, .bazelversion) rather than Make. Includes separate TypeScript frontend code (likely cluster UI in ~3.7MB) under a different tree. Uses protobuf extensively for data serialization across the distributed system.

Database engineers and infrastructure teams building cloud-native applications that require geographic distribution, automatic failover, and horizontal scaling without sacrificing SQL compatibility or transaction guarantees. Contributors range from storage layer specialists (working in pkg/storage) to SQL optimizer engineers (pkg/sql/opt) to distributed systems engineers (pkg/kv).

Production-ready and actively developed. CockroachDB is a mature project with 101+ MB of Go code, comprehensive test coverage (indicated by extensive testing infrastructure in .claude/rules and .claude/agents), and documented standards (go-conventions.md, error-handling.md). The presence of Bazel build configuration, protobuf dependencies, and backward compatibility concerns (evidenced by .claude skills for backporting) indicates a stable, well-maintained codebase used in production by enterprises.

Low technical risk for deployment, but high complexity risk for contributors. The codebase is extremely large (100MB+ Go alone) with distributed systems complexity requiring deep understanding of consensus (Raft), transactions, and consistency models. The project manages this through strict code review agents (.claude/agents) and detailed contributing guidelines, but there is a steep learning curve. No single-maintainer risk (Cockroach Labs maintains this with multiple teams), though pull request turnaround depends on domain expertise availability.

Active development across multiple vectors: storage optimization (evidenced by RocksDB integration), SQL compatibility improvements (pkg/sql remains a focus), distributed systems hardening (Raft consensus refinements), and operational tooling. The presence of .claude/skills indicates recent investment in developer experience, with skills for issue triage (file-crdb-issue), test reduction (reduce-unoptimized-query-oracle), and artifact analysis (engflow-artifacts). Cluster UI bumping (bump-cluster-ui skill) suggests ongoing frontend updates.

Clone and build: git clone https://github.com/cockroachdb/cockroach.git && cd cockroach. Install dependencies: ensure Go is installed (primary language is Go), protoc for protobuf (>=4.21.0 in dependencies), and Bazel for the build system (brew install bazelisk or equivalent). Build: bazel build //cmd/cockroach or check Makefile for convenience targets. Run: ./cockroach start-single-node --insecure for a local single-node instance, then ./cockroach sql in another terminal to connect.

Daily commands: For development: bazel run //cmd/cockroach -- start-single-node --insecure or build then execute the binary directly. For local testing: make test or bazel test //pkg/... for specific packages. For cluster: cockroach start --join=localhost:26257 (standard multi-node bootstrap). SQL client: cockroach sql connects to local node or cockroach sql --url=postgresql://user@host/db. See Makefile for additional targets and .bazelrc for build configuration options.

• .bazelrc — Build configuration that controls compilation flags, test execution, and platform targeting across the entire CockroachDB codebase
• BUILD.bazel — Root Bazel build file defining the primary build targets and dependencies for the entire monorepo
• .github/CODEOWNERS — Defines code ownership and review requirements; essential to understand who reviews which subsystems and what governance rules apply
• .claude/rules/go-conventions.md — Documents CockroachDB-specific Go coding standards, error handling patterns, and naming conventions that all contributors must follow
• .claude/rules/error-handling.md — Specifies the error wrapping and redaction patterns used throughout CockroachDB for safe error propagation and customer privacy
• .claude/rules/table-driven-test.md — Establishes the testing methodology and structure expected in CockroachDB test files; critical for understanding test organization
• .github/workflows/github-actions-essential-ci.yml — Defines the core CI pipeline that validates all PRs; shows required test suites and quality gates every contributor must pass

• Bazel Build — undefined

Add a New Code Convention or Rule

1. Create a new markdown file in .claude/rules/ describing the convention with examples and rationale (.claude/rules/[convention-name].md)
2. Reference the new rule in .claude/settings.json to activate it for all AI-assisted reviews (.claude/settings.json)
3. Update CODEOWNERS to assign review responsibility for enforcement of this rule (.github/CODEOWNERS)

Add a New AI Review Agent

1. Create a new agent markdown file in .claude/agents/ describing the agent's purpose, validation logic, and error detection patterns (.claude/agents/crdb-[agent-name]-reviewer.md)
2. Wire the agent into the main review skill by updating the orchestration logic in the review skill file (.claude/skills/review-crdb/SKILL.md)
3. Document any new dependencies or external tools required by the agent in .claude/settings.json (.claude/settings.json)

Add a New Development Skill

1. Create a new directory under .claude/skills/[skill-name]/ with a SKILL.md file documenting the skill's purpose and usage (.claude/skills/[skill-name]/SKILL.md)
2. Implement the skill logic in companion files (Python, shell scripts, or reference documentation as needed) (.claude/skills/[skill-name]/[implementation])
3. If the skill involves code generation or automation, document the expected file paths and templates it will create (.claude/skills/[skill-name]/SKILL.md)

Configure a New CI/CD Workflow

1. Create a new GitHub Actions workflow YAML file in .github/workflows/ that defines job triggers, steps, and outputs (.github/workflows/[workflow-name].yml)
2. Reference any build targets via .bazelrc configuration or define new ones in relevant BUILD.bazel files (.bazelrc)
3. Update the essential or extended CI workflows if this is a required validation step (.github/workflows/github-actions-essential-ci.yml)

• Bazel Build System — Provides hermetic, reproducible builds across distributed development teams and CI/CD pipelines; critical for large-scale monorepo management
• Go Language — Enables efficient, statically-typed systems programming with excellent concurrency primitives (goroutines); essential for distributed database kernel implementation
• GitHub Actions — Tightly integrated with repository hosting; provides essential CI/CD automation for PR validation, testing, and release workflows
• Claude AI Agents — Automates code review, correctness validation, and error analysis; reduces review latency and enforces consistent coding standards at scale
• Protobuf 4.21.0+ — Language-neutral serialization for inter-process communication, RPC definitions, and persistent state management in distributed systems

• Bazel over Make/CMake

  • Why: Monorepo scale requires fine-grained dependency tracking and incremental builds; Bazel provides hermetic isolation and parallel test execution
  • Consequence: Steeper learning curve for contributors; slower initial builds due to sandboxing, but faster iteration and more reliable CI results

• AI-assisted code review agents as primary validation

  • Why: Enables consistent enforcement of CockroachDB-specific patterns (error redaction, concurrency safety) without human reviewer bottleneck
  • Consequence: Requires high-quality rule definitions and ongoing agent tuning; may miss domain-specific edge cases requiring human expertise

• Centralized CODEOWNERS governance

  • Why: Ensures subsystem experts review changes affecting critical infrastructure; prevents unauthorized modifications to sensitive components
  • Consequence: Can slow PR merging if code owners are unavailable; requires disciplined ownership assignment

• Does not handle HTTP routing or REST API implementation in this layer (that is in distributed database engine code, not shown here)
• Does not provide UI/frontend application code (that exists in separate cluster-ui repository)
• Does not implement SQL parsing or query optimization (kernel is in separate compiled modules)
• Does not provide Docker container definitions or Kubernetes orchestration (those are in separate deployment/operations repositories)

1. Protobuf version pinning: dependencies specify protobuf>=4.21.0; older versions may have compatibility issues with complex nested messages used in roachpb. 2. Raft implementation subtleties: pkg/raft has strict ordering requirements for log application and snapshot handling; casual changes break replication invariants. 3. MVCC versioning assumptions: pkg/storage MVCC tracking (multiple versions of keys) has unintuitive GC semantics; transaction history depends on clock correctness. 4. Bazel build complexity: incremental builds sometimes fail due to protoc code generation; bazel clean may be required. 5. SQL optimizer rules: pkg/sql/opt has recursive transformation rules that must preserve semantic equivalence; incorrect rules silently produce wrong results. 6. RedactableString requirement: error messages must follow redactability.md (use redact package) or fail code review; this is enforced but non-obvious to new contributors.

• Raft Consensus — CockroachDB's replicated state machine foundation; understanding Raft leader election, log replication, and snapshotting is essential for understanding how data survives failures
• MVCC (Multi-Version Concurrency Control) — Enables transaction isolation without locking; CockroachDB stores multiple versions of each key with timestamps, requiring careful GC and version visibility logic
• Cost-Based Query Optimization — pkg/sql/opt uses statistical cost models to choose optimal query execution plans; understanding cardinality estimation and join ordering is crucial for SQL performance
• Write-Ahead Logging (WAL) — RocksDB-backed storage uses WAL to ensure durability; CockroachDB's consistency model depends on log entries being persisted before application
• Distributed Transactions (Serializable Isolation) — CockroachDB implements true SERIALIZABLE transactions across multiple nodes using timestamp ordering and conflict detection; violations are non-obvious without understanding timestamp allocation
• Protobuf Code Generation — RPC contracts and persistent data formats are defined in .proto files and code-generated; changes to roachpb require understanding protoc versioning and backward compatibility
• Redactability & Information Hiding — CockroachDB enforces that logs never leak user data; the redact package marks safe vs. sensitive values, and .claude/rules/redactability.md is a hard requirement for merged code

• postgres/postgres — CockroachDB implements PostgreSQL wire protocol compatibility; the Postgres source is the authoritative reference for SQL semantics and behavior
• etcd-io/etcd — Shares Raft consensus foundation (though CockroachDB has a custom Raft implementation); etcd demonstrates distributed key-value store patterns and watch mechanisms
• cncf/tikv — Alternative distributed transactional key-value store with similar architecture (Raft + MVCC); helpful for comparing design decisions around consistency and replication
• cockroachdb/cockroach-cloud — Cockroach Cloud orchestration and control plane; uses CockroachDB as the system database and demonstrates operational deployment patterns
• cockroachdb/docs — Official documentation repository; tracks API changes and user-facing behavior documentation that mirrors codebase development

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for engflow-artifacts skill

The engflow-artifacts skill in .claude/skills/engflow-artifacts/ has a Python module (engflow_artifacts.py) with a test file (engflow_artifacts_test.py) and testdata, but appears to be missing comprehensive coverage for the protobuf parsing logic. Given that this skill handles ResultStore artifact analysis (critical for build debugging), adding robust unit tests for edge cases, error handling, and proto deserialization would improve reliability. This is high-value because build artifact analysis is a common failure point.

• [ ] Review engflow_artifacts.py implementation and current test coverage in engflow_artifacts_test.py
• [ ] Identify untested code paths, especially around resultstore_pb2.py proto message handling
• [ ] Add unit tests for: malformed proto inputs, missing fields, label parsing edge cases, and target filtering logic
• [ ] Add integration tests using the existing testdata (labels_response.bin, target_kvserver.bin, target_oidcccl.bin)
• [ ] Update engflow_artifacts_test.py with new test cases and verify requirements.txt has all dependencies

Implement validation tests for .claude/rules/ standards enforcement

The repository has well-defined standards in .claude/rules/ (go-conventions.md, error-handling.md, commenting-standards.md, etc.) and corresponding agents in .claude/agents/ (crdb-conventions-reviewer.md, crdb-error-reviewer.md), but there's no automated test suite to validate that codebase samples actually follow these rules. Adding a test suite that parses Go files and checks conformance to defined standards would help maintain code quality at scale and provide contributors with clear feedback.

• [ ] Review all rules in .claude/rules/ and extract testable patterns (e.g., error wrapping patterns from error-handling.md)
• [ ] Create a Go test file (e.g., pkg/util/rules_test.go or similar) that validates sample code snippets against these rules
• [ ] Implement linting checks for: redactability markers, comment standards, error handling patterns, and table-driven test structure
• [ ] Add negative test cases (code that violates rules) to ensure detection works
• [ ] Document results in .claude/rules/README.md with examples of automated enforcement

Add Bazel build rules validation and migration guide for new Bazel users

The repo uses Bazel extensively (.bazelrc, .bazelversion, BUILD.bazel files throughout) as evidenced by the file structure, but there's no dedicated skill or documentation for new contributors unfamiliar with Bazel. Creating a skill in .claude/skills/ that validates Bazel configurations, suggests fixes for common issues, and provides a migration guide would reduce contributor friction. This is concrete because .bazel* files are present but lack associated documentation.

• [ ] Create .claude/skills/bazel-build-helper/ directory with SKILL.md
• [ ] Document common Bazel issues in CockroachDB context (proto generation, cgo builds, dependency management)
• [ ] Add a Python script to validate BUILD.bazel files in the repo (check for missing dependencies, deprecated rules)
• [ ] Create a migration guide for developers converting Go standard build to Bazel targets
• [ ] Add validation tests that check a sample of BUILD.bazel files against Bazel best practices

• Add missing test coverage in pkg/storage for edge cases in MVCC garbage collection under concurrent deletes—the GC logic is complex but has limited table-driven tests for race conditions
• Improve error messages in pkg/sql/parser by adding ParseError details for common mistakes (e.g., missing FROM clause, syntax in wrong order)—errors are often vague and would benefit from context-aware hints following error-handling.md
• Extend pkg/raft test suite with scenarios for asymmetric network partitions—current tests cover basic splits but not partial connectivity loss, which is common in cloud environments and could improve correctness coverage

The CockroachDB codebase shows generally good security practices with infrastructure-as-code and automation. However, there are moderate concerns: (1) The protobuf dependency uses a loose version constraint that could allow vulnerable versions; (2) Python and CI/CD infrastructure scripts need security review for input validation; (3) GitHub Actions workflows should be audited for proper secret handling and permission minimization; (4) Build configuration (Bazel) requires validation of sandbox enforcement. The distributed SQL database nature suggests strong internal security practices, but the dependency management and infrastructure automation warrant hardening.

• Medium · Outdated Protobuf Dependency — requirements.txt / Package dependencies. The codebase specifies protobuf>=4.21.0, which allows for versions with known vulnerabilities. Protobuf versions before 4.24.x have had security advisories. The loose version constraint (>=4.21.0) does not enforce a safe minimum version and could allow vulnerable versions to be installed during dependency resolution. Fix: Update the protobuf dependency constraint to protobuf>=4.24.0 or higher to ensure only patched versions are used. Consider using more specific pinning (e.g., protobuf>=4.24.0,<5.0.0) to prevent unexpected major version upgrades.
• Low · Python Scripts in Build/Test Infrastructure — .claude/skills/drt-analyze/scripts/parse_events.py, .claude/skills/engflow-artifacts/engflow_artifacts.py. Python scripts are present in the .claude/skills directory (parse_events.py, engflow_artifacts.py, engflow_artifacts_test.py) without visible input validation patterns. These scripts handle protobuf serialization and API interactions. If these scripts process untrusted input, they could be vulnerable to deserialization attacks or injection. Fix: Review Python scripts for proper input validation and sanitization. Ensure protobuf deserialization uses safe parsing methods. Implement strict type checking and avoid eval() or exec() on user input. Consider using static analysis tools like bandit on Python code.
• Low · Workflow Configuration Files Require Review — .github/workflows/. Multiple GitHub Actions workflow files are present (.github/workflows/*.yml). These workflows could potentially expose secrets or execute untrusted code if not properly configured with appropriate permissions and secret management practices. Fix: Audit all GitHub Actions workflows for: (1) Principle of least privilege permissions, (2) Proper secret management using GitHub Secrets, (3) Restricted triggers on fork pull requests, (4) Use of pinned action versions instead of @main. Enable GitHub's security features like OIDC for trust relationships.
• Low · Bazel Build Configuration Security — .bazelrc, .bazelversion, .bazelignore. The presence of .bazelrc and .bazelversion files indicates Bazel-based builds. Bazel configuration files could potentially include or execute arbitrary code if not properly validated. The .bazelignore file should be reviewed to ensure sensitive files are properly excluded. Fix: Review .bazelrc for any exec-root or sandbox-related configurations that could bypass security controls. Ensure .bazelignore properly excludes all sensitive directories (.env, config files, credentials). Use Bazel's build sandbox features and validate all build rules.
• Low · Proto File Exposure — .claude/skills/engflow-artifacts/resultstore.proto, resultstore_pb2.py. The resultstore.proto file in .claude/skills/engflow-artifacts/ and its compiled resultstore_pb2.py may expose internal API structures. While not directly a vulnerability, exposure of internal protocol definitions could aid attackers in understanding system internals. Fix: Review what information is exposed in proto definitions. Consider whether this file should be in the public repository. Ensure API documentation doesn't reveal sensitive implementation details. Use proto versioning and deprecation markers for sensitive APIs.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.