# Cinc Workstation 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.
- `ci/`: GitLab CI templates and platform matrix.
- `components/gems/`: Ruby gem bundle definitions and lockfile.
- `components/main-cinc-wrapper/`: Go CLI wrapper and tests.
- `omnibus/`: Packaging definitions, software configs, package scripts.
- `scripts/`: Install/uninstall and automation helpers.
- `test/integration/cinc-tests/`: InSpec integration profile used in CI.
- `docs-chef-io/` and `dev-docs/`: Documentation and architecture context.

## 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.

### 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.
- If Ruby commands fail due to missing gems, verify the selected RVM Ruby + gemset before changing project files.
- 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`
- Go lint (wrapper): `cd components/main-cinc-wrapper && go vet ./...`
- Go unit tests (wrapper): `cd components/main-cinc-wrapper && go test -tags=unit ./cmd -v -count=1`
- Go integration tests (wrapper, only when relevant): `cd components/main-cinc-wrapper && go test -tags=integration \
  ./integration -v -count=1`
- For Linux testing when local tooling is unavailable or mismatched, default to `cincproject/omnibus-debian:13`.
- In that container, always source `/home/omnibus/load-omnibus-toolchain.sh` before running build/test commands.
- Agent-friendly example (Ruby style): `docker run --rm -v "$PWD":/w -w /w cincproject/omnibus-debian:13 \ bash -lc
  'source /home/omnibus/load-omnibus-toolchain.sh && \ bundle exec rake style'`
- Agent-friendly example (Go lint): `docker run --rm -v "$PWD":/w -w /w cincproject/omnibus-debian:13 \ bash -lc
  'source /home/omnibus/load-omnibus-toolchain.sh && cd \ components/main-cinc-wrapper && go vet ./...'`
- Agent-friendly example (Go unit tests): `docker run --rm -v "$PWD":/w -w /w cincproject/omnibus-debian:13 \ bash -lc
  'source /home/omnibus/load-omnibus-toolchain.sh && cd \ components/main-cinc-wrapper && go test -tags=unit ./cmd -v \
  -count=1'`

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

- Linux package build: `./build/build.sh`
- macOS package build: `bash build/build-macos.sh`
- Windows package build: `bash build/build-windows.sh`
- Package install/verify flow from CI: see `ci/test.yml`

## Guardrails

- Do not manually edit generated file `components/main-cinc-wrapper/dist/global.go`.
- Do not hand-edit `components/gems/Gemfile.lock`; use `rake update`.
- Treat `data/` and `omnibus/pkg/` as build artifacts.
- Build scripts may append local cache settings to `omnibus/omnibus.rb`; do not commit transient cache-path edits.
- `bin/omnibus clean ... --purge` is destructive; use only when
	explicitly requested.

## Versioning And Commits

- Follow Conventional Commits for user-facing changes.
- Release/version bump behavior is driven by `scripts/version-bump.sh` and CI labels.
- DCO signoff is required for contributions (`--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 `scripts/version-bump.sh`
- Packaging workflows: `omnibus/README.md`
- CI behavior and install/test matrix: `ci/lint.yml`, `ci/test.yml`, `ci/package.yml`, `ci/platforms.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.
