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:

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:

./scripts/validate-repo.sh

Focused checks:

./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:

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.