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,55 @@
+# Codex Workflow
+
+This directory keeps future Codex sessions consistent when working in this infrastructure portfolio.
+
+## How To Start
+
+1. Read [AGENTS.md](../../AGENTS.md).
+2. Inspect the affected tree and nearby README files.
+3. Check `git status --short` so existing user work is preserved.
+4. Decide whether a plan is needed before editing.
+5. Make small, reviewable changes.
+6. Run focused validation plus `./scripts/validate-repo.sh` when practical.
+
+## When To Plan First
+
+Plan before editing when a task touches more than one subsystem, changes operational behavior, adds or modifies destructive actions, changes Ansible targeting, or updates repository conventions.
+
+For small typo fixes, narrow README updates, or obvious syntax fixes, inspect first and then make the change directly.
+
+Use [plans-template.md](./plans-template.md) for larger changes.
+
+## Scoped Tasks
+
+Good tasks name the operational goal, affected directories, constraints, validation commands, and what "done" means. Use [task-template.md](./task-template.md) for reusable prompts.
+
+Keep scope tied to real operations:
+
+- Bash tool: discovery, pre-check, dry-run, execute, post-check, report.
+- Ansible change: inventory target, role/playbook scope, check mode, idempotency, validation.
+- Runbook: incident signal, triage, decision points, rollback, evidence.
+- Lab/platform project: status, prerequisites, validation, limitations.
+
+## Validation
+
+Prefer the repository helpers:
+
+```bash
+./scripts/check-bash.sh
+./scripts/check-ansible.sh
+./scripts/check-docs.sh
+./scripts/validate-repo.sh
+```
+
+If optional tools are missing, report that clearly and continue with available checks. Do not claim skipped checks passed.
+
+## Final Response Format
+
+End with:
+
+1. Summary of what changed.
+2. Files created or modified.
+3. Validation commands run and results.
+4. Skipped checks and why.
+5. Risks or follow-ups.
+6. Whether the repo is ready for future Codex-driven work.