Skip to content

CODEX_PLATFORM_GUIDE.md

Latest commit

 

History

History
97 lines (63 loc) · 4.44 KB

CODEX_PLATFORM_GUIDE.md

File metadata and controls

97 lines (63 loc) · 4.44 KB
Raw

Codex Platform Guide (Web / App)

Scope

This template applies to both:

  • Codex Web
  • Codex App (Desktop)

File Placement Standards (Codex Web / App / Google Antigravity)

To avoid procedural complexity, all three platforms share the same canonical Skill body and compact metadata stub:

  1. Canonical Skill body: .agents/skills/<skill>/SKILL.md (shared standards-compatible path for supported hosts).
  2. Compact Agentic OS metadata stub: .agent/skills/<skill> (flat file; points to the canonical body and carries phase/trigger metadata).
  3. Platform Workflow Files: .agent/workflows/*.md and .agent/rules/*.md (No duplication).

Minimum Check Recommendations:

  • Run ./.agentcortex/bin/validate.sh.
  • Confirm AGENTS.md still declares both .agent/skills and .agents/skills.

Unified State Machine

Use the canonical state machine: Ref: .agent/rules/state_machine.md

  • /help, /commands, /test-skeleton, and /handoff are Read-Only commands.
  • /ship is allowed only after TESTED state.

Shared Recommendations

  1. Provide target, target files, constraints, and acceptance criteria (AC) at the start of a task.
  2. Run /bootstrap first, then /plan; only run /implement once the quality gate has passed.
  3. Run /review and /test after every implementation.
  4. Run ./.agentcortex/bin/validate.sh before submission.

GitHub Contributor Attribution

GitHub repository Contributors are derived from commit attribution on the default branch, not from repository collaborator invitations. If a project wants Codex-authored work to appear as codex in the Contributors panel, keep at least one merged commit authored or co-authored with the GitHub-linked no-reply address for the codex account.

Recommended author identity for Codex App/Web-authored commits:

Codex <267193182+codex@users.noreply.github.com>

When merging a Codex-authored PR, prefer a merge or rebase merge that preserves individual commit authors. If using squash merge, preserve a Co-authored-by: Codex <267193182+codex@users.noreply.github.com> trailer in the final squash commit.

Handoff Hard Gate (Non-tiny-fix)

Before /ship, you must have a /handoff. Minimum reference requirements:

  1. At least 1 docs/ artifact.
  2. At least 1 code file path.
  3. Corresponding work log: .agentcortex/context/work/<worklog-key>.md. Resolve <worklog-key> from the branch using a filesystem-safe name; if the active log is missing but recoverable, recreate it before rejecting /ship.

If unsatisfied, you must reject /ship and list the missing items.

Gate Receipt Persistence — Codex Web

On Codex Web there is no file-write capability. Gate receipts MUST still be recorded for validator compliance. Protocol:

  1. At each phase completion, output the gate receipt as a fenced block in chat: 
    ## Gate Evidence
- Gate: <phase> | Verdict: PASS | Classification: <tier> | Timestamp: <ISO>
  2. Instruct the user: "Paste the block above into .agentcortex/context/work/<worklog-key>.md under ## Gate Evidence."
  3. Do NOT proceed to the next phase until the user confirms the paste is done (or acknowledges they will do it before /ship).
  4. At /ship, the Gate Receipt Audit checks the Work Log — if receipts are missing because the user did not paste them, /ship MUST fail with missing: [<phase> receipt].

This ensures Codex Web-authored Work Logs remain validator-compliant even without direct file access.

Handoff Timing

Handoff timing follows the cross-platform SSoT — AGENTS.md §Context Pruning (context occupancy + phase boundary, not turn-count). Codex nuance (.agentcortex/docs/guides/token-governance.md §6.1): automatic prompt caching is active (0.1×, prefix ≥1024 tok; 24 h extended on GPT-5.1), and auto-compaction fires late (~95% capacity) and can derail mid-task — so prefer handing off at a clean phase boundary before that.

Web Edition Recommendations

  • Use one thread per requirement to avoid context pollution.
  • Before pausing a long task, output /handoff and remind the human to save it.

App Edition Recommendations

  • Run deploy_brain.sh and validation scripts locally.
  • Update the work log after every submodule completion to reduce context reconstruction costs.

Quick Checklist

  • /bootstrap completed
  • /plan passed quality gate
  • /implement executed in IMPLEMENTABLE state
  • /review and /test completed
  • /handoff completed for non-tiny-fix tasks
  • validate.sh passed