Add Codex repository guidance and validation

2026-05-10 11:11:03 +00:00
parent 0d3905b8a1
commit a527022518
17 changed files with 935 additions and 23 deletions
@@ -0,0 +1,116 @@
+# 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-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.
+
+## 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.