# Cinc Omnibus Toolchain Agent Guide

This file defines how coding agents should work in this repository.
Nested `AGENTS.md` files override this file for their subdirectories.

## Goals

- Keep changes minimal, reviewable, and aligned with current CI behavior.
- Prefer Cinc naming in new/edited text and code unless touching upstream-synced
  content that intentionally keeps Chef naming.
- Favor documentation links over copied prose.

## Repository Map

- `build/`: Platform build entry points for Linux, macOS, Windows, plus the
  source-tarball builder and the deploy helper.
- `ci/`: GitLab CI templates (`lint.yml`, `package.yml`, `rules.yml`,
  `test.yml`).
- `config/projects/omnibus-toolchain.rb`: Omnibus project definition.
- `config/software/`: Cinc-specific software definitions on top of those
  inherited from the omnibus-software gem.
- `omnibus.rb`: Omnibus runtime config.
- Release flow: GitLab CI components from `cinc-project/ci-tools`
  (`changelog-release-mr` + `changelog-tag-release`) included in
  `.gitlab-ci.yml`. No local release script.
- `test/integration/cinc-sources/`: InSpec profile validating source tarball
  checksums.
- `test/integration/cinc-tests/`: InSpec profile validating an installed
  toolchain package.
- `docs/`: Per-platform install notes for builders.
- `package-scripts/omnibus-toolchain/`: postinst/postrm scripts shipped in the
  RPM/DEB.
- `resources/omnibus-toolchain/`: Per-package-format resources (msi, pkg, ips).

## Command Policy

- Default to lightweight validation unless the user explicitly asks for full
  builds or full matrix tests.
- Run targeted checks for touched areas first.
- Avoid long-running package builds by default; an omnibus-toolchain build is
  multi-hour wall-clock on the fastest runner.

### Local Ruby Environment (RVM)

- For local development, use RVM with project gemsets instead of system Ruby.
- Run Ruby/Bundler commands inside the active project gemset.
- Local `.ruby-version` and `.ruby-gemset` files may exist to indicate an
  already-created RVM environment; use them as environment hints when present.

### Preferred Lightweight Checks

- Ruby style: `bundle exec rake style`
- YAML lint of CI files: `ruby -ryaml -e 'YAML.load_file(".gitlab-ci.yml")'`
- InSpec profile syntax: `cinc-auditor check test/integration/cinc-tests`

### Heavyweight Commands (Run Only On Explicit Request)

- Linux package build (multi-hour): `./build/build.sh`
- macOS package build: `bash build/build-macos.sh`
- Windows package build: `bash build/build-windows.sh`
- Source tarball: `bash build/build-source.sh`
- Package install/verify flow from CI: see `ci/test.yml`

## Guardrails

- Do **not** use the `cincproject/omnibus-*` Docker images for building this
  project. Those images contain the toolchain itself; using them inside a
  toolchain build creates a circular dependency. Build in bare distro images
  (debian:13, almalinux:10, …) — that is the entire reason `build/build.sh`
  bootstraps Ruby via RVM.
- The macOS and Windows runners require a *previously installed* copy of
  omnibus-toolchain to bootstrap. Document any builder-side changes in
  `CINC_MAINTENANCE_PLAN.md`.
- Treat `data/`, `pkg/`, `cache/`, `vendor/`, and `local/` as build artifacts;
  never commit them.
- `build/build.sh` appends `cache_dir` / `git_cache_dir` lines to `omnibus.rb`
  when running in CI; do not commit those transient edits.
- `bundle exec omnibus clean ... --purge` is destructive (removes
  `/opt/omnibus-toolchain`); use only when explicitly requested.
- Do not regenerate the MSI `upgrade_code` GUID in
  `config/projects/omnibus-toolchain.rb` casually — changing it breaks
  in-place upgrades for every Windows builder.

## Versioning And Commits

- Follow Conventional Commits for user-facing changes.
- Release/version bump behavior is driven by the `cinc-project/ci-tools`
  `changelog-release-mr` + `changelog-tag-release` components and CI
  labels (`version::patch`, `version::minor`, `version::major`).
- DCO signoff is required for contributions (`git commit --signoff`).
- Prefer detailed multi-line commit messages for non-trivial changes.
- For multi-line commits, prefer stdin/heredoc (`git commit -F - <<'EOF' ... EOF`)
  over a single `-m` flag.
- In commit bodies, capitalize bullet points and summarize the main changes as
  short bullets when that improves scanability.
- Keep commit subjects and bodies wrapped to 80 characters per line.

## Documentation Sources Of Truth

- Contribution policy: `CONTRIBUTING.md`
- Release/version rules: `README.md` and the `cinc-project/ci-tools`
  changelog-flow components referenced in `.gitlab-ci.yml`
- Long-term maintenance plan and builder bootstrap: `CINC_MAINTENANCE_PLAN.md`
- CI behavior and install/test matrix: `ci/lint.yml`, `ci/package.yml`,
  `ci/test.yml`, `.gitlab-ci.yml`

## Change Style

- Keep edits focused; avoid unrelated refactors.
- Preserve existing formatting and structure.
- For Markdown documentation files (`*.md`), keep lines at 120 characters or
  fewer.
- Add comments only when logic is non-obvious.
