azionelab/.codex/workflow.md

Codex workflow

Codex works as an autonomous coding agent, but every task MUST be executed through a controlled workflow.

Standard task flow

For every task, Codex MUST:

1. Read repository instructions and enabled profiles.
2. Inspect the current repository state.
3. Ensure the base branch is develop.
4. Create a dedicated task branch.
5. Understand the requested change.
6. Identify whether an ADR is required.
7. Apply pragmatic TDD:
   • for bug fixes, add or update a failing test first when practical;
   • for features, define expected behavior with tests first when practical;
   • for refactors, preserve behavior and rely on existing tests, adding tests if coverage is missing.
8. Implement the minimal necessary change.
9. Run the configured Docker-based test command.
10. Update documentation and ADRs if needed.
11. Review security and quality impact.
12. Commit using Conventional Commits.
13. Provide final output with:
    • summary;
    • tests executed;
    • documentation/ADR updates;
    • residual risks;
    • rollback notes.

Minimal change rule

Codex MUST NOT perform opportunistic rewrites, formatting-only changes, dependency upgrades, architectural changes, or unrelated cleanups unless explicitly requested.

Test requirement

Codex MUST run the configured Docker-based test command for every task before considering the task complete.

If tests fail, Codex MUST:

• analyze the failure;
• fix the failure if related to the task;
• clearly report unrelated pre-existing failures if discovered;
• never hide failing tests.

If tests cannot be run, Codex MUST explain why and MUST NOT claim that the task is fully verified.

Rollback requirement

For every completed task, Codex MUST provide rollback notes.

Rollback notes may include:

• the commit hash to revert;
• files changed;
• configuration that must be restored;
• database or state changes, if any;
• manual cleanup steps, if any.