Imported from cicd-sensor/cicd-sensor (AGENTS.md). Install upstream with npx skills add cicd-sensor/cicd-sensor. Copyright stays with the author.

Repo Instructions

cicd-sensor is an eBPF-powered CI/CD runtime security sensor. The source of truth for design is docs/.

AI agent workflow

This repo is developed through collaborative engineering, not autonomous "vibe coding".

AI agents should first investigate the code, docs, runtime behavior, and tradeoffs; then help write down the design or plan; then implement the agreed change. Do not skip directly from a rough idea to a finished PR.

Before changing external state such as creating, closing, reopening, or merging GitHub Issues / PRs, pushing branches, or publishing releases, show the exact target and proposed content, then wait for explicit approval.

Use ignored work_docs/ for local temporary design drafts, progress notes, investigation logs, and result reports. Do not place local-only working notes at the repository root.

What to read first

• docs/index.md — project goal and supported platforms
• docs/user-guide/overview.md — runner environments and usage models
• docs/developer-guide/overview.md — repository layout and subsystem reading order
• docs/developer-guide/agent.md — Job / Scope / JobRegistry / KernelTracker model
• docs/developer-guide/agent-ownership-boundaries.md — Agent / JobRegistry / Job / JobScopeState ownership rules and per-Job evaluation rationale
• docs/developer-guide/ebpf-runtime.md — cgroup v2 tracking, BPF map boundary, eBPF code style and contribution contract
• docs/developer-guide/manager.md — config and log delivery boundary
• docs/developer-guide/rule-engine.md — RuleSet / RuleModifier / CEL flow

Detailed rules

The files below add detail that only applies when touching specific paths. They apply to any AI coding agent working in this repo — Claude Code, Codex, Gemini, or otherwise. The .claude/ directory is only there because Claude Code auto-loads from that path; the contents are not Claude-specific. Read the relevant one before changing code in that area.

Build and test

• make build — build agent + manager binaries (Linux).
• make test — run unit tests.
• go test -race ./... — race detector (required for concurrency changes).
• make check — generate + test + rules-validate + rules-bundle-validate + diff-check (the gate this repo uses before commit).
• make integration / make bpf-integration — integration suites (need privileges; may require Linux).
• make rules-validate — validate baseline rule YAML.
• make generate — regenerate protobuf and bpf2go output (run after touching proto/ or BPF C sources). BPF compilation runs through Docker, so macOS / Windows hosts work as long as Docker is available.

Repository layout

Agent components

The Agent is built from several components, each owning a different boundary. Before writing code, identify which component owns the state, lifecycle, or interface you are touching. Do not let responsibilities leak across components.

A single Job may carry one scope or both. Each scope owns its own rules, evaluation state, and outputs, and the two are isolated: neither operator can read or override the other's rules, and their outputs are emitted separately. This is the security boundary of the agent — see docs/developer-guide/agent.md for the conceptual model and docs/developer-guide/agent-ownership-boundaries.md for the implementation ownership rules. For the kernel-side model, see docs/developer-guide/ebpf-runtime.md.

Host scope and project scope are internal Agent implementation boundaries. User-facing docs should describe the user-visible deployment path and configuration owner instead: installed runner, GitHub Action, project-local config, or manager config. GitHub Action can run with manager-url, so do not imply that Action configuration and manager configuration are mutually exclusive. Do not expose host/project scope mechanics in user docs unless the page is specifically explaining Agent architecture or a log field that uses scope to distinguish emitted records.

Commits

• Conventional Commits. English. One-line title.
• No multi-paragraph body unless the change needs it.
• No Claude, Codex, Co-Authored-By, Generated by, or similar signatures.
• Before committing a rename or moved file — or a changed rule_id / predefined list name / other identifier referenced by name — grep the old name across docs/, AGENTS.md, .claude/rules/**, and the Go sources, and update every reference in the same commit. Markdown link targets and rule cross-references are not caught by make rules-validate / make test.

Large changes

For large feature additions or substantial behavior changes, write a Markdown Design Doc before implementation. Use .claude/rules/50-design-docs.md for the recommended format. Use it mainly as a local working document to keep the direction stable and track progress. If communication needs it, copy or summarize the relevant parts into GitHub Issues.