portfolio/docs/codex

Codex Workflow

This directory keeps future Codex sessions consistent when working in this infrastructure portfolio.

How To Start

1. Read 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 for larger changes.

Scoped Tasks

Good tasks name the operational goal, affected directories, constraints, validation commands, and what "done" means. Use 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:

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