portfolio/AGENTS.md

# AGENTS.md

Guidance for Codex and other automated agents working in this repository.

## Purpose

This repository is a Linux/Unix infrastructure engineering portfolio. It shows practical operational work: incident response, troubleshooting, safe Bash tooling, Ansible hardening examples, storage workflows, runbooks, and platform/lab notes.

Treat it like internal operations tooling maintained by an infrastructure engineer. Preserve operational realism and avoid generic tutorial or template filler.

## Layout

- `infra-run/` - core operational tooling, Ansible, Bash scripts, runbooks, examples, and operations docs.
- `platform-projects/` - larger platform topics such as monitoring, storage, clustering, virtualization, and observability.
- `labs/` - experimental/lab environments for Kubernetes, Terraform, networking, CI/CD, Docker, and related work.
- `docs/codex/` - Codex workflow guidance, task templates, review checklist, and planning template.
- `scripts/` - repository validation helpers.

## Inspect First

Before editing, inspect the affected tree and nearby README files. Prefer:

```bash
rg --files
git status --short
sed -n '1,220p' <file>
```

Check existing style before introducing new structure. Keep changes small and reviewable.

## Validation

Run the broad repo check when practical:

```bash
./scripts/validate-repo.sh
```

Focused checks:

```bash
./scripts/check-bash.sh
./scripts/check-ansible.sh
./scripts/check-python.sh
./scripts/check-docs.sh
```

Optional strict mode fails when optional tools are missing:

```bash
STRICT=1 ./scripts/validate-repo.sh
```

Also run targeted checks for changed files, such as `bash -n`, `ansible-playbook --syntax-check`, or link checks when relevant.

## Bash Standards

- Use `#!/usr/bin/env bash`.
- Use `set -o errexit`, `set -o nounset`, and `set -o pipefail`.
- Validate input before using it.
- Handle missing commands clearly.
- Default to read-only or dry-run behavior.
- Require explicit `--execute` plus confirmation for destructive operations.
- Use clear `OK`, `WARNING`, and `CRITICAL` output.
- Exit codes: `0` OK, `1` operational issue, `2` invalid input or missing dependency.
- Keep scripts readable; separate discovery, pre-check, change, post-check, and reporting when it helps.

## Python Standards

- Use Python for parsing, reporting, and structured operational tooling where it adds value over Bash.
- Keep Python tools read-only by default.
- Prefer the Python standard library.
- Avoid frameworks and unnecessary abstractions.
- Use clear operational output and meaningful exit codes.
- Keep tools small, focused, and easy to validate.

## Ansible Standards

- Keep playbooks short and roles simple.
- Prefer modules over `shell` or `command`.
- Use `shell` or `command` only when the module set cannot express the operation, and document why if risk is not obvious.
- Preserve check-mode and diff-mode friendliness where possible.
- Use handlers, tags, defaults, and validation tasks when they clarify operations.
- Keep inventory under `inventory/hosts.yml`, `group_vars/`, and `host_vars/`.
- Do not present selected hardening examples as complete compliance certification.

## Documentation Standards

- Explain what exists, what is planned, and what is intentionally not supported.
- Prefer runbook style: scope, pre-checks, execution guardrails, rollback thinking, post-checks, and evidence.
- Avoid marketing language, fake enterprise wording, and tutorial bloat.
- Update README files and `CHANGELOG.md` when adding meaningful behavior or structure.

## Safety Rules

- Do not run destructive commands.
- Do not rename large directories unless the benefit is clear and low-risk.
- Do not hide validation failures.
- Do not claim live production validation for sanitized examples.
- Do not add secrets, real hostnames, customer identifiers, or private infrastructure details.
- Do not turn placeholders into fake completed projects.

## PR and Review Expectations

- State the operational risk of the change.
- Include commands run and whether tools were missing.
- Review scripts for dry-run behavior, input validation, dependency handling, and rollback path.
- Review Ansible for idempotency, check-mode behavior, inventory targeting, tags, handlers, and module choice.
- Keep diffs focused.

## Definition of Done

- The change preserves the repository intent.
- Relevant docs are updated.
- Changed Bash scripts pass `bash -n`.
- Available validation helpers were run.
- Missing optional tools are reported.
- Any remaining risk or follow-up is documented.

## Do Not

- Do not add an "ultimate DevOps template" structure.
- Do not replace working simple Bash with unnecessary abstractions.
- Do not make examples appear production-certified.
- Do not add destructive behavior without `--execute`, confirmation, and clear rollback notes.
- Do not delete useful content unless it is clearly duplicate, broken, or misleading.