/implement command

codex

---
name: codex
description: Use when the user asks to run Codex CLI (codex exec, codex resume) or references OpenAI Codex for code analysis, refactoring, or automated editing.
---

# Codex Skill Guide

Use this skill to run Codex CLI for consultation, reviews, or automated tasks.

## Running a Task

1. Choose an appropriate model and reasoning effort based on task complexity without asking the user.
2. Select the sandbox mode required for the task; default to `--sandbox read-only` unless edits or network access are necessary.
3. Assemble the command with the appropriate options:
   - `-m, --model <MODEL>`
   - `--config model_reasoning_effort="<high|medium|low>"`
   - `--sandbox <read-only|workspace-write|danger-full-access>`
   - `--full-auto`
   - `-C, --cd <DIR>`
   - `--skip-git-repo-check`
4. Always use `--skip-git-repo-check`.
5. By default, append `2>/dev/null` to all `codex exec` commands to suppress thinking tokens (stderr). Only show stderr if the user explicitly requests to see thinking tokens or if debugging is needed.
6. Run the command, capture stdout/stderr (filtered as appropriate), and summarize the outcome for the user.
7. After Codex completes, inform the user: "You can resume this Codex session at any time by saying 'codex resume' or asking me to continue with additional analysis or changes."

## Review Mode (Mandatory After Changes)

Run a code review via Codex:

```bash
codex exec review --uncommitted 2>/dev/null
```

If needed:
- Review against a base branch: `codex exec review --base main 2>/dev/null`
- Review a specific commit: `codex exec review --commit <sha> 2>/dev/null`

## Consult Mode (Second Opinion)

Use this when stuck or after one failed fix attempt:

```bash
codex exec "I'm debugging a test failure in Melange (OpenFGA-compatible auth library for PostgreSQL).

**Test output:**
<paste test output>

**Relevant code:**
<paste relevant code or file paths>

**What I've observed:**
<your analysis>

Help me understand: What is causing this failure and what's the correct fix?" 2>/dev/null
```

Set a generous timeout (5 minutes). Empty output means Codex had no findings.

## Resume a Session

When continuing a previous session, use:

```bash
echo "your prompt here" | codex exec --skip-git-repo-check resume --last 2>/dev/null
```

When resuming, do not pass configuration flags unless the user explicitly requests them.

## Quick Reference

| Use case | Sandbox mode | Key flags |
| --- | --- | --- |
| Read-only review or analysis | `read-only` | `--sandbox read-only 2>/dev/null` |
| Apply local edits | `workspace-write` | `--sandbox workspace-write --full-auto 2>/dev/null` |
| Permit network or broad access | `danger-full-access` | `--sandbox danger-full-access --full-auto 2>/dev/null` |
| Resume recent session | Inherited from original | `echo "prompt" | codex exec --skip-git-repo-check resume --last 2>/dev/null` |
| Run from another directory | Match task needs | `-C <DIR>` plus other flags `2>/dev/null` |

## Error Handling

- Stop and report failures whenever `codex --version` or a `codex exec` command exits non-zero; request direction before retrying.
- For dangerous actions (mutations, network access, or broad filesystem access), ask for user permission before running. For routine read-only analysis, run without confirmation.
- When output includes warnings or partial results, summarize them and ask how to adjust.

implement.md

/implement command

Implement

Implement the spec at: $ARGUMENTS

You are the orchestrator for this implementation. Your role is to:

• Hold global context across the entire implementation
• Break down the spec into logical, sequential steps
• Delegate each step to a builder subagent
• Track progress and ensure quality gates pass

Phase 1: Planning

1. Read the spec file completely
2. Identify all implementation phases/tasks from the spec
3. Create a TodoWrite checklist with each logical step
4. Order tasks by dependencies (what must be built first)

Phase 2: Orchestrated Implementation

For each todo item, execute this delegation cycle:

Step A: Spawn Builder Subagent

Spawn a builder agent (opus model) with this structured prompt:

## Task

Implement: [SPECIFIC TASK DESCRIPTION]

## Context

Spec: [FULL PATH TO SPEC FILE]
Related files: [list 3-5 key files the builder should read first]
Patterns to follow: [reference to similar existing code, e.g., "see services/controls_service.go"]

## Phase 1: Clarification (REQUIRED)

Before writing ANY code, formulate clarifying questions about this task.

Use the codex-cli skill to get answers:

/codex-cli

I am implementing [SPECIFIC TASK] from the spec at: [PATH]

I have the following clarifying questions:
1. [Question about requirements]
2. [Question about edge cases]
3. [Question about integration points]

Do not make any modification to the codebase.

Incorporate the answers into your implementation approach.

## Phase 2: Implementation

After clarification:
1. Read the relevant files to understand existing patterns
2. Implement the feature following Cable patterns
3. Write tests for new functionality
4. Run validation: `just codegen && go build ./server/...`

## Phase 3: Self-Review with Codex

Before declaring completion, validate your work:

/codex-cli

I have implemented [SPECIFIC TASK] from the spec at: [PATH]

Please review my implementation for:
1. Alignment with the spec requirements
2. Organization hierarchy rules (if touching data access)
3. Missing edge cases
4. Test coverage gaps

Files changed: [list files you modified]

Do not make any modification to the codebase.

If codex identifies issues, fix them and re-validate.

## Requirements

- Follow existing code patterns in the codebase
- Write tests for new functionality
- Do NOT refactor unrelated code
- Organization isolation rules must be followed
- Use PrepareConnectError for error handling

## Completion

When done, report:
1. What was implemented
2. Files changed
3. Tests added
4. Any concerns or follow-up items

Step B: Validate Build

After builder completes:

# Always run
just codegen && go build ./server/...

# If backend changes
go test -race ./server/...

# If frontend changes
just lint-frontend && just typecheck-frontend && just test-frontend

If validation fails, return task to builder with error context.

Step C: Review Gate (for significant changes)

For tasks that touch security, data access, or core business logic, spawn a reviewer agent:

## Review Task

Review the implementation of [SPECIFIC TASK] against spec at [PATH].

## Pre-Review Clarification

Use codex-cli to clarify any spec ambiguities before reviewing:

/codex-cli

I am reviewing the implementation of [SPECIFIC TASK] from spec at: [PATH]

Questions about requirements:
1. [Any unclear acceptance criteria]
2. [Boundary conditions]

Do not make any modification to the codebase.

## Review Checklist

- [ ] Implementation matches spec requirements
- [ ] Organization isolation rules followed (parent→child only)
- [ ] Tests cover new functionality and edge cases
- [ ] Error handling uses PrepareConnectError
- [ ] No unrelated changes included
- [ ] RBAC permissions checked where needed

## Validation

Use codex-cli to validate architectural decisions:

/codex-cli

Reviewing [TASK] implementation. Validating:
1. [Specific architectural choice made]
2. [Data access pattern used]

Is this aligned with the spec and Cable patterns?

Do not make any modification to the codebase.

## Output

Report: APPROVED, CHANGES_REQUESTED, or BLOCKED
If changes needed, specify exactly what must be fixed.

Step D: Iteration

If reviewer requests changes:

1. Update todo with findings
2. Re-spawn builder with reviewer feedback as additional context
3. Maximum 3 iterations before escalating to user with summary of blockers

Step E: Advance

Once step passes all gates:

1. Mark todo as completed
2. Note what was built and any context needed for subsequent steps
3. Move to next todo item
4. Spawn fresh builder subagent with cumulative context

Phase 3: Completion

After all todos are complete:

1. Run full validation suite:

just codegen && go build ./server/...
go test -race ./server/...
just lint-frontend && just typecheck-frontend && just test-frontend

2. Summarize implementation:

   • What was built (per spec section)
   • Files created/modified
   • Tests added
   • Any deferred items or known limitations

3. List any follow-up work identified during implementation

Orchestrator Guidelines

Your responsibilities as orchestrator:

• Hold global context: Remember what was built in previous steps
• Provide cumulative context: Each new builder should know what exists
• Track dependencies: If step 3 depends on step 2's output, ensure proper sequencing
• Escalate blockers: If a step fails 3 iterations, stop and ask the user
• Maintain quality: Every step must pass validation before advancing

Do NOT:

• Implement features yourself (delegate to builder)
• Skip the codex consultation phase
• Proceed if validation fails
• Allow scope creep beyond the spec

Success Criteria

• All spec requirements implemented
• Each step passed builder + reviewer validation
• Tests pass: go test -race ./server/...
• Lint passes: just lint-frontend
• Types pass: just typecheck-frontend
• No unrelated changes introduced