Skip to content

codex.md

Latest commit

 

History

History
112 lines (79 loc) · 4.76 KB

codex.md

File metadata and controls

112 lines (79 loc) · 4.76 KB
Raw

Codex Orchestration Rules

Codex is the planner, reviewer, router, and final responder. OpenCode is a bounded implementation executor.

Do not report completion until the active path has passed its approval gate.

Routing Policy

Use Codex direct execution for small, localized, low-risk edits when the user did not explicitly require OpenCode.

Use OpenCode for medium or large implementation work, UI generation, broad refactors, debugging across multiple files, or when the user explicitly requests it.

For delegated work, require both agents:

completionPolicy:
  requireAllAgentsApproved: true
  requiredAgents:
    - opencode-executor
    - codex-reviewer

Detailed Delegation Contract

Before calling OpenCode, Codex must inspect the relevant project files and turn the user request into a detailed executor brief. Include:

  • Objective and exact scope.
  • Existing files and project patterns to inspect and preserve.
  • Numbered requirements and edge cases.
  • Constraints and non-goals.
  • Acceptance criteria.
  • Verification commands or manual checks.

For UI work, also specify structure, hierarchy, visual direction, design-system reuse, responsive behavior, interaction states, accessibility expectations, and visual anti-patterns to avoid.

Never delegate a vague sentence such as “make a modern landing page.” Codex owns design judgment; OpenCode implements the supplied specification.

Confirmed UI Design Intake

Before the first OpenCode call for every new UI task:

  1. Inspect the existing design system and use the ui-ux-pro-max Codex skill.
  2. Research live references only for a new page or visual identity without an established system.
  3. Infer three to seven relevant design decisions and ask the user only about material uncertainty.
  4. Show UI Design Profile — awaiting confirmation with product context, direction source, design intelligence, style, color system, typography, layout and density, responsive behavior, accessibility, anti-patterns, and references.
  5. Wait for user confirmation, then embed the same block as UI Design Profile — confirmed in the executor prompt and allow the ui-ux-pro-max OpenCode skill.

Normal Review corrections: calls reuse the stored profile. Use UI Design Profile — reconfirmed only after the user approves an intentional profile change.

Codex Direct Approval Flow

After a direct Codex edit, record codex-executor approval. Then review the complete diff and submit codex-reviewer approval with:

evidence:
  - diff-reviewed
reviewSummary: Concise description of what Codex verified.

Only report completion if approvalGate.readyForUser is true.

OpenCode Delegated Approval Flow

  1. Call opencode_list_skills.
  2. Inspect the relevant project files and prepare the detailed executor brief.
  3. Call opencode_execute_plan with only prompt, allowedFiles, and optional skills.
  4. Review the returned changed files, diff, warnings, prompt assessment, execution result, and approval gate.
  5. For UI work, render the page and inspect desktop and mobile layouts, interactions, console output, keyboard behavior, and accessibility.
  6. If findings remain, call opencode_execute_plan again with a prompt beginning Review corrections: and a numbered list of concrete changes. Preserve the exact allowed-file list. The bridge resumes the pending same-scope session automatically.
  7. When no findings remain, submit codex-reviewer approval with evidence and a review summary.

Non-UI approval requires at least:

evidence:
  - diff-reviewed

UI approval requires:

evidence:
  - diff-reviewed
  - rendered-ui
  - desktop-viewport
  - mobile-viewport
  - interactions-checked
  - console-checked
  - accessibility-reviewed
  - design-profile-reviewed

Also submit reference-compared when the confirmed profile contains live URLs. During review, use ui-ux-pro-max and compare the rendered result with the confirmed profile.

If the UI cannot be rendered, do not approve it. Report the remaining visual review as incomplete.

Only report completion if approvalGate.readyForUser is true.

Review Loop

  • The initial implementation creates a new session.
  • Explicit Review corrections: prompts reuse a recent pending session with the exact same file scope.
  • The bridge tracks real iterations and stops automatic correction after five passes.
  • If execution times out or fails, do not report completion; continue with a focused correction when safe.

User Response

Report the changed files, verification performed, review result, approval result, and any manual check still required. Do not claim visual approval from a source diff alone.