Coding Agent

Coding Agent Skill 💻

When to Use

Trigger this skill when the user wants:

• Code review, PR review, or standards review
• Implementation or refactoring
• GitHub workflows, commits, and PRs

Execution Modes

Plan Mode (new)

Use plan-first workflow before risky implementation:

# Generate read-only plan artifact
scripts/code-plan --engine codex --repo /path/to/repo "Add feature X"

# Execute approved plan
scripts/code-implement --plan /path/to/repo/.ai/plans/<plan>.md

Plan artifacts are written to .ai/plans/*.md with machine-checkable status metadata. code-implement --plan enforces approval status (or requires explicit --force bypass).

Primary: Direct CLI (Session Resume + Permission Bypass)

Agent CLIs now support non-interactive execution with full autonomy and session persistence:

Reasoning default policy for Codex implementation:

• Use -c model_reasoning_effort="high" for feature implementation and architectural refactors.
• Use medium/low for simple fixes, docs-only updates, or when the user explicitly asks for fast/cheap execution.

# Codex — full autonomy, no TTY needed
codex --yolo exec -c model_reasoning_effort="high" "Implement feature X. No questions."
codex exec resume --last    # restore context from last session

# Claude Code — full autonomy, no TTY needed
claude -p --dangerously-skip-permissions "Implement feature X"
claude -p --resume <id>     # restore specific session
claude -p -c "Follow up"    # continue most recent session

Secondary: tmux Wrappers (Optional)

For long-running implementation tasks where TTY logging and session durability are needed:

# Implementation (3 min timeout, tmux)
"${CODING_AGENT_DIR:-./}/scripts/code-implement" "Implement feature X in /path/to/repo"

Multi-Phase Workflow (Session Resume)

Full issue → implement → PR → review → fix cycle using session resume:

1. Implement: codex --yolo exec -c model_reasoning_effort="high" "Implement feature from issue #N" 2. Create PR: gh pr create --title "feat: ..." --body "..." 3. Review: timeout 600s codex review --base <base> --title "Review PR #N" 4. Fix issues: codex exec resume --last (context preserved) 5. Re-review: timeout 600s codex review --base <base> --title "Re-review PR #N" 6. Merge: gh pr merge

`<base>` = repo's default branch (main, master, or trunk). Detect with:

git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@'

Fallback if origin/HEAD is unset:

git remote show origin | sed -n '/HEAD branch/s/.*: //p'

Non-Negotiable Rules (Summary)

1. Use agent CLIs — Never write code directly. Use Codex CLI or Claude Code CLI (direct or via tmux wrappers). Do not switch to MCP orchestration unless explicitly required. 2. Feature branch — Always use a feature branch for changes. 3. PR before done — Always create a PR before completion. 4. GitHub hygiene — Precise titles, structured bodies, explicit test commands, AI disclosure. 5. No `--max-turns` — Let agent runs complete naturally. 6. Adequate timeouts — Minimum 600s for reviews. 7. Self-audit before completion — Run implementation and review audit checklists before marking done.

Self-Audit Policy (Option A)

Self-audit is required when any of these are true:

• Code or config changed.
• Tests changed or should have changed.
• Review is requested (PR review, standards review, architecture/code quality review).
• Docs changed with executable commands/examples.

Self-audit may be skipped only for:

• Pure informational answers with zero repo changes.
• User explicitly asks for raw output only.

If skipped, state why it was skipped.

Fallback Chain

Implementation: Codex CLI (direct) → Codex CLI (tmux) → Claude CLI → BLOCKED
Reviews:        Codex CLI (direct) → Claude CLI → BLOCKED

⛔ NEVER skip to direct edits — request user override instead

Implementation mode is configurable:

• CODING_AGENT_IMPL_MODE=direct|tmux|auto (default: direct)
• auto selects tmux first only when running in an interactive TTY with tmux available

Tooling + Workflow References

Read these before doing any work:

• references/WORKFLOW.md for branch, PR, review order, multi-phase workflows
• references/STANDARDS.md for coding standards and limits
• references/quick-reference.md for commands and guardrails
• references/tooling.md for CLI usage, session management, and timeouts
• references/codex-cli.md for canonical Codex CLI workflows (exec, review, resume, MCP distinctions)
• references/claude-code.md for Claude Code CLI reference and session resume
• references/reviews.md for review formats and GH review posting
• references/examples.md for violation examples and recovery
• references/templates/plan-system-prompt.txt for deterministic plan mode output contract
• references/templates/plan-template.md for plan artifact structure
• references/frontend-design.md for frontend-design-ultimate source refs

Humanizer Usage (User-Facing Copy)

For user-facing long-form text (status updates, outreach copy, explanatory prose), default to a humanization pass:

• Preferred command: /humanizer
• Keep exact technical artifacts unchanged (commands, code, IDs, links, payloads, legal text).
• If unavailable, fall back to original text and proceed.

Persona

You are Dev: pragmatic, experienced, and direct. Explain tradeoffs and risks. Prefer simple, working solutions.

Summary

Describe the problem and fix in 2-5 bullets:

• Problem:
• Why it matters:
• What changed:
• What did not change (scope boundary):

Change Type (select all)

• [ ] Bug fix
• [ ] Feature
• [ ] Refactor
• [ ] Docs
• [ ] Security hardening
• [ ] Chore/infra

Scope (select all touched areas)

• [ ] Scripts/wrappers
• [ ] Skill docs/references
• [ ] Issue/PR templates or community files
• [ ] CI/workflows
• [ ] Other

Linked Issue/PR

• Closes #
• Related #

User-visible / Behavior Changes

List user-visible changes (including defaults/config). If none, write None.

Security Impact (required)

• New permissions/capabilities? (Yes/No)
• Secrets/tokens handling changed? (Yes/No)
• New/changed network calls? (Yes/No)
• Tool execution surface changed? (Yes/No)
• If any Yes, explain risk + mitigation:

Repro + Verification

Environment

• OS:
• Shell/runtime:
• Relevant tool versions:

Steps

1. 2. 3.

Expected

-

Actual

-

Evidence

Attach at least one:

• [ ] Failing output before + passing output after
• [ ] Log snippets
• [ ] Screenshot/recording
• [ ] N/A (docs-only or template-only change)

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios:
• Edge cases checked:
• What you did not verify:

Compatibility / Migration

• Backward compatible? (Yes/No)
• Config/env changes? (Yes/No)
• Migration needed? (Yes/No)
• If yes, exact upgrade steps:

Failure Recovery

• How to disable/revert this change quickly:
• Files/config to restore:
• Known bad symptoms reviewers should watch for:

Risks and Mitigations

• Risk:
• Mitigation:

AI Assistance

• AI-assisted: yes/no
• Tools/agents/models used:
• Testing level: untested/lightly tested/fully tested
• Human understanding confirmation: yes/no

Current date: 2026-02-19

Purpose

High-signal instructions for coding agents in this repository. Keep this file concise; move long examples and deep procedures to README.md and references/.

Scope

• Applies to the repository root and descendants.
• Add nested AGENTS.md files only when a subdirectory needs different rules.
• CLAUDE.md should remain a symlink to this file.

Language

• English only for code, comments, docs, examples, commits, configs, errors, and tests.

Tooling

• Prefer rg over grep.
• Prefer fd/tree when available; fall back to find/ls -R when missing.
• Resolve Claude CLI in this order: ~/.claude/local/claude (if present), otherwise claude from PATH.
• Prefer non-interactive command execution.

Runtime Reality Check

• Before running major workflows, verify toolchain:
• command -v codex && codex --version
• command -v timeout
• command -v gh
• command -v claude || test -x ~/.claude/local/claude
• If a required binary is missing, stop and report exact install/unblock steps.

Codex Command Canon

• Prefer Codex for implementation and review:
• Implementation: codex exec "..." (or codex --yolo exec "..." only in trusted/sandboxed environments)
• Resume: codex exec resume --last
• Review: codex review --base <branch> "custom focus prompt"
• Use --full-auto for sandboxed low-friction automation.
• Use --yolo only when bypassing sandbox/approvals is explicitly intended.

Workflow

1. Gather context with read-only operations first. 2. For non-trivial work, propose a concise plan with assumptions, risks, and one alternative. 3. Get explicit APPROVE before file writes, package installs, or system changes. 4. After approval, execute end-to-end and report progress, results, and deviations.

Long-Running Commands

• Ensure tsx scripts close watchers/timers and call process.exit(0).
• Wrap long tasks with process-group timeout, e.g.:
• timeout -k5s 60s bash -lc 'exec npx --yes tsx scripts/tool-schema-lint.ts'
• Avoid timeout --foreground.
• After timeout, verify child processes are stopped; if not, run pkill -P <wrapper_pid>.

Code Standards

• Prefer KISS and YAGNI; avoid speculative abstractions.
• Apply DRY with a three-strikes rule before abstraction.
• Keep modules and classes focused (SRP).
• TypeScript: avoid any; prefer precise types or Record<string, unknown>.
• Use explicit error handling; never fail silently.
• Import order: node -> external -> internal.
• Use descriptive names and named constants instead of magic numbers.

Review Expectations (Plan/Review Mode)

• Review in this order: Architecture, Code Quality, Tests, Performance.
• For each issue:
• include file/line references,
• present 2-3 options (include do-nothing when reasonable),
• state effort, risk, impact, and maintenance burden per option,
• recommend one option and ask for user decision before implementation.
• Interactive flow:
• Big change: section-by-section with up to 4 top issues per section.
• Small change: one focused question per section.

Testing and Validation

• Reproduce first when debugging.
• Before finalizing, run relevant checks:
• formatting/lint
• typecheck
• unit/integration/e2e tests as applicable
• Report exact commands run and outcomes.
• Explicitly call out checks not run and residual risk.

Documentation Hygiene

• Update README.md or references/ when public behavior/workflow changes.
• Final report must summarize files changed, key diffs, and side effects.
• Prefer inclusive language: allowlist/blocklist, primary/replica, main branch.

Humanized Communication Policy

• For user-facing long-form writing (outreach copy, status updates, explanations, docs prose), run a humanization pass by default.
• Preferred invocation in OpenClaw contexts: /humanizer.
• Keep exact technical artifacts untouched: code blocks, CLI commands, JSON/YAML payloads, IDs/UUIDs, URLs, stack traces, legal/compliance text, and direct quotations.
• If humanizer is unavailable, continue safely with original text and note the fallback.

OpenClaw Skill Notes

• Keep SKILL.md AgentSkills-compatible: clear name + description, concise body, references for deep detail.
• For OpenClaw compatibility, keep frontmatter keys single-line and keep metadata as a single-line JSON object.

CLI Drift Check

• Periodically verify docs/scripts against real CLI help:
• codex --help
• codex review --help
• claude --help
• Update references when flags/behavior drift.

AGENTS.md

Contributing

How to contribute

• Bugs and focused fixes: open a PR.
• New features or architecture changes: open an issue/discussion first.
• Questions: open an issue or discussion.

Before you open a PR

• Search existing issues and PRs first.
• Keep PRs focused; do not mix unrelated concerns.
• Use the issue forms in .github/ISSUE_TEMPLATE/ for new reports and requests.

Branches and commits

• Branch names should be short and descriptive (example: codex/<topic>).
• Prefer commit format type(scope): subject.

Validation expectations

Include exact commands and outcomes in every PR.

For script changes, run:

while IFS= read -r script; do [[ -f "$script" ]] || continue; bash -n "$script"; done < <(git ls-files scripts)
while IFS= read -r script; do [[ -f "$script" ]] || continue; shellcheck "$script"; done < <(git ls-files scripts)
./scripts/doc-drift-check
./scripts/smoke-wrappers.sh

When wrapper behavior is involved, also run:

./scripts/doctor

AI-assisted contributions

AI-assisted PRs are welcome. Be explicit:

• Mark AI assistance in the PR.
• State testing level (untested/lightly tested/fully tested).
• Include prompt/session notes when feasible.
• Confirm you understand the final code and behavior.

PR requirements

Complete all sections in .github/pull_request_template.md, especially:

• Security impact
• Repro + verification
• Human verification
• Compatibility/migration
• Failure recovery

coding-agent OpenClaw Skill 💻

OpenClaw skill for coding assistant using agent CLIs (Codex, Claude Code). Primary mode: direct CLI with session resume and permission bypass. Secondary mode: tmux wrappers for durable TTY sessions.

Features

• Session Resume Workflows — Multi-phase issue → implement → PR → review → fix cycles with full context preservation
• Agent CLI Integration — Direct CLI execution with permission bypass (--yolo, --dangerously-skip-permissions)
• PR Review Workflow — Direct CLI reviews with proper timeouts
• Plan Mode Workflow — Read-only plan generation with machine-checkable approval gate before implementation
• Self-Auditing Workflow — Mandatory implementation + review checklists with VERIFIED/UNVERIFIED command labeling
• Dev Persona — Pragmatic code reviews with clear feedback
• Git Workflow Documentation — Branch, commit, PR conventions
• Code Quality Standards — KISS, YAGNI, DRY, SRP principles

Requirements

• GitHub CLI (gh)
• One of: Codex CLI (codex) or Claude Code CLI (claude)
• GNU timeout command (coreutils on macOS)
• Optional: tmux (for durable TTY sessions and wrapper scripts)

Installation

# Clone to OpenClaw skills directory
cd /home/art/clawd/skills
git clone https://github.com/kesslerio/coding-agent-openclaw-skill.git coding-agent

Preflight and Validation

# Verify local tooling before running wrappers
./scripts/doctor

# Run wrapper behavior smoke tests
./scripts/smoke-wrappers.sh

Usage

In OpenClaw, activate with:

/coding

Plan-first shortcut:

/plan <task>

Direct CLI (Primary)

# Implementation (Codex)
codex --yolo exec "Implement feature X. No questions."

# Implementation (Claude Code)
claude -p --dangerously-skip-permissions "Implement feature X"

# Resume last session (context preserved)
codex exec resume --last
claude -p -c "Fix the review findings"

Reviews (Direct CLI)

gh pr checkout <PR>
timeout 600s codex review --base <base> --title "Review PR #N"

Wrapper Scripts (Plan + Implementation)

# Plan mode (read-only planning artifact)
./scripts/code-plan --engine codex --repo /path/to/repo "Implement feature X"

# Execute plan (prompts for approval if status is still PENDING)
./scripts/code-implement --plan /path/to/repo/.ai/plans/<plan>.md

# Direct implementation (3 min timeout, tmux)
./scripts/code-implement "Implement feature X"

Implementation mode policy can be configured:

export CODING_AGENT_IMPL_MODE=direct  # direct|tmux|auto

Files

• SKILL.md — Full skill documentation (includes Dev persona)
• references/WORKFLOW.md — Coding workflow, Git integration, multi-phase workflows
• references/STANDARDS.md — Coding standards & rules
• references/quick-reference.md — Command quick reference
• references/tooling.md — CLI usage, session management, timeouts
• references/codex-cli.md — Canonical Codex CLI reference and policy matrix
• references/claude-code.md — Claude Code CLI reference and session resume
• scripts/code-plan — Plan mode wrapper (read-only execution + artifact validation)
• references/reviews.md — Review + PR/issue writing patterns
• references/templates/plan-system-prompt.txt — Deterministic plan-mode system prompt
• references/templates/plan-template.md — Canonical plan structure template

GitHub Hygiene

• PR titles: type(scope): imperative summary (or repo override).
• Issue titles:
• Feature: feat: <capability> (for <surface>)
• Bug: bug: <symptom> when <condition>
• Tracking: TODO: <cleanup> after <dependency>
• PR bodies must include: What, Why, Tests, AI Assistance.
• Tests should be exact commands; AI Assistance should include prompt/session link when available.

License

MIT

Claude Code CLI Reference

Detailed reference for Claude Code as a fallback when Codex is unavailable, or as primary CLI for Claude-based workflows.

Contents

• Non-interactive mode flags
• Session resume (non-interactive)
• Model selection
• Permission modes
• Budget controls
• Output formats
• Examples
• Codex → Claude mapping

---

Non-Interactive Mode (-p/--print)

The -p flag runs Claude in non-interactive mode: it processes the prompt and exits.

claude -p "Your prompt here"

Note: The -p flag skips workspace trust dialogs. Only use in trusted directories.

---

Flags Reference

---

Session Resume (Non-Interactive)

Session resume restores full conversation context from disk. Use this for multi-phase workflows where context must persist across separate CLI invocations.

Continue Most Recent Session

# Continue the last conversation with a new prompt
claude -p -c "Fix the review findings from the previous session"

# Continue without a new prompt (re-runs last context)
claude -p -c

Resume Specific Session

# Browse sessions interactively to find the ID
claude --resume

# Resume a specific session by ID
claude -p --resume abc123 "Address the security concern raised in review"

Session Storage

Sessions persist to ~/.claude/projects/<project>/sessions/. Each session contains the full conversation history, tool calls, and file context.

When to Use Resume

Multi-Phase Example

# Phase 1: Implement
claude -p --dangerously-skip-permissions "Implement JWT auth middleware"

# Phase 2: Fix review findings (context preserved)
claude -p -c --dangerously-skip-permissions "Fix the review findings: add token expiry check"

# Phase 3: Add tests (context preserved)
claude -p -c --dangerously-skip-permissions "Add unit tests for the JWT middleware"

---

Permission Modes

# Auto-accept edits (recommended for automation)
claude -p --permission-mode acceptEdits "Fix the bug"

# Full bypass (like Codex --yolo)
claude -p --dangerously-skip-permissions "Build the feature"

---

Model Selection

# Use Opus for complex tasks
claude -p --model opus "Design the database schema"

# Use Haiku for quick/cheap tasks
claude -p --model haiku "Add a docstring"

# Use Sonnet (default, balanced)
claude -p --model sonnet "Refactor this function"

# With fallback
claude -p --model opus --fallback-model sonnet "Complex task"

Models:

• opus - Most capable, highest cost
• sonnet - Balanced (default)
• haiku - Fastest, lowest cost

---

Budget Controls

# Cap spending at $5
claude -p --max-budget-usd 5 "Build a REST API"

# Combine with fallback for cost optimization
claude -p --model opus --fallback-model haiku --max-budget-usd 2 "Review this code"

---

Output Formats

# Plain text (default)
claude -p "Summarize this file"

# JSON (single result)
claude -p --output-format json "List the functions in this file"

# Streaming JSON (for real-time processing)
claude -p --output-format stream-json "Analyze this codebase"

---

Working Directory

# Add specific directories for file access
claude -p --add-dir ~/project --add-dir ~/shared "Refactor across both directories"

---

Session Management

# Continue last conversation
claude -p -c "Follow up on the previous task"

# Resume specific session
claude -p -r session-id "Continue from here"

# Browse/pick sessions interactively
claude --resume

---

Examples

Quick Code Fix

claude -p --permission-mode acceptEdits "Fix the null pointer exception in src/api.ts"

Full Auto Build

claude -p --dangerously-skip-permissions "Build a REST API with CRUD endpoints for users"

Code Review with Budget

claude -p --model opus --max-budget-usd 1 "Review this PR for security issues"

Multi-Phase Implementation

# Phase 1: Implement
claude -p --dangerously-skip-permissions "Implement the user registration endpoint"

# Phase 2: Fix issues (resume context)
claude -p -c --dangerously-skip-permissions "Fix the validation error in registration"

# Phase 3: Add tests
claude -p -c --dangerously-skip-permissions "Add integration tests for registration"

---

Codex → Claude Mapping

Codex CLI Reference

Canonical Codex guidance for this skill.

Default Strategy

Use single-agent Codex for most work: 1. codex --yolo exec -c model_reasoning_effort="high" "..." for one-off implementation/refactor prompts. 2. codex exec resume --last "..." for follow-up work on the same task. 3. Use tmux only when terminal persistence/reattach is required.

This keeps workflows interactive and stateful without forcing a persistent tmux session.

Reasoning default policy:

• Use high for feature implementation and architectural refactors.
• Use medium/low only for simple fixes/docs tasks or when the user explicitly asks for fast/cheap execution.

Core Commands

One-off implementation

codex --yolo exec -c model_reasoning_effort="high" "Implement feature X. No questions."

Resume previous context

codex exec resume --last "Fix findings from the previous run"

Review against base branch

timeout 600s codex review --base <base> --title "PR #N Review"

Structured non-interactive output

codex exec --json --output-last-message /tmp/last.txt "Summarize changes"

Useful automation flags:

• --json
• --output-schema <FILE>
• --output-last-message <FILE>
• --skip-git-repo-check

Safety Profiles

Choose one profile per run:

• Guardrailed sandbox: codex exec --full-auto "..."
• Full bypass (externally sandboxed environments only):

codex exec --dangerously-bypass-approvals-and-sandbox "..."

codex --yolo exec is equivalent to bypass mode.

Execution Policy Matrix

Implementation-mode env var:

• CODING_AGENT_IMPL_MODE=direct|tmux|auto
• direct: run Codex directly first
• tmux: run tmux transport first
• auto: tmux first only when attached to TTY and tmux is available

MCP Clarification

There are two distinct MCP paths:

1. codex mcp ...

• Configure external MCP tools for Codex.
• Use when Codex needs extra context/tools.

2. codex mcp-server

• Expose Codex itself as an MCP server for another orchestrator.
• Experimental; use behind feature flags/pilots.

Multi-Agent Guidance

Codex multi-agent workflows are experimental.

Use only when the task is truly decomposable into parallel tracks (for example: independent security/performance/test-review streams). Prefer single-agent exec + resume for normal implementation cycles.

Official Sources

• https://developers.openai.com/codex/cli/reference
• https://developers.openai.com/codex/noninteractive
• https://developers.openai.com/codex/mcp
• https://developers.openai.com/codex/multi-agent

Violation Examples and Recovery

Violation Consequences

If any rule is violated: 1. Stop immediately. 2. Acknowledge the violation. 3. Revert or fix. 4. Document the violation in PR/commit notes. 5. Resume correctly.

Common Pitfalls

❌ Writing code directly

Wrong:

Edit file.py: add function xyz...

Correct:

./scripts/code-implement "Add function xyz to file.py"

❌ Skipping review

Wrong:

git push && gh pr create && gh pr merge

Correct:

gh pr create
timeout 600s codex review --base <base> --title "PR Review"
./scripts/tmux-run timeout 1200s codex --yolo exec -c model_reasoning_effort="medium" \
  "Review against STANDARDS.md and report PASS/FAIL per category"

❌ Chaining without timeouts

Wrong:

codex exec "Part 1" && codex exec "Part 2"

Correct:

timeout 300s codex --yolo exec -c model_reasoning_effort="high" "Part 1"
timeout 300s codex --yolo exec -c model_reasoning_effort="high" "Part 2"

Real Violation Examples

Example 1: “Trivial Change” Rationalization

• What happened: Direct edit for a typo.
• Why wrong: Rule 1 has no exceptions.
• Fix:

./scripts/code-implement "Fix typo in config.py line 42"

Example 2: Skipped PR Creation

• What happened: Commit on main, pushed directly.
• Why wrong: Rule 2 and Rule 3.
• Fix:

git checkout -b fix/typo-config
git add -A && git commit -m "fix: correct typo"
git push -u origin fix/typo-config
gh pr create

Example 3: Missing Self-Check

• What happened: Implementation started without STOP-AND-VERIFY.
• Why wrong: Mandatory protocol.
• Fix: perform STOP-AND-VERIFY before any changes.

Frontend Design References

When reviewing frontend/UI work, check consistency with these sources:

1. Anthropic frontend-design

• https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md
• Anti-AI-slop philosophy, typography, color, motion, spatial composition
• BANNED: Inter, Roboto, Arial, purple gradients, centered layouts

2. Anthropic web-artifacts-builder

• https://github.com/anthropics/skills/blob/main/skills/web-artifacts-builder/SKILL.md
• React 18 + TypeScript + Vite + Tailwind + shadcn/ui
• Single-file HTML bundling with Parcel

3. Community frontend-design-v2

• https://github.com/nhatmobile1/claude-skills/blob/main/skills/frontend/frontend-design-v2/SKILL.md
• Mobile-first patterns, hero layouts, accordions, form consistency

Gemini CLI Reference

Optional reference for Gemini CLI. This skill does not use Gemini by default. To enable Gemini as a fallback in scripts/safe-fallback.sh, set:

export GEMINI_FALLBACK_ENABLE=1

Contents

• Basic usage
• Approval modes
• Model selection
• Sandbox mode
• Session management
• Output formats
• Examples

---

Basic Usage

Gemini CLI defaults to one-shot mode with positional prompts:

gemini "Your prompt here"

For interactive mode, use -i:

gemini -i "Start with this prompt"

---

Flags Reference

---

Approval Modes

# Auto-approve edits only
gemini --approval-mode auto_edit "Fix the bug in api.ts"

# Full auto (yolo)
gemini -y "Build the feature"
# or
gemini --approval-mode yolo "Build the feature"

---

Model Selection

# Specify model
gemini -m gemini-2.5-pro "Complex analysis task"

# Default model (usually gemini-2.5-flash)
gemini "Quick task"

---

Sandbox Mode

Run in a sandboxed environment for safety:

gemini -s "Experiment with this code"
gemini --sandbox "Run untrusted operations"

---

Working Directories

# Include additional directories
gemini --include-directories ~/project,~/shared "Work across directories"

# Multiple flags
gemini --include-directories ~/project --include-directories ~/lib "Cross-repo task"

---

Session Management

# List available sessions
gemini --list-sessions

# Resume latest session
gemini -r latest "Continue where we left off"

# Resume specific session by index
gemini -r 5 "Continue session 5"

# Delete a session
gemini --delete-session 3

---

Output Formats

# Plain text (default)
gemini "Summarize this"

# JSON output
gemini -o json "List functions in this file"

# Streaming JSON
gemini -o stream-json "Analyze codebase"

---

Examples

Quick Code Fix

gemini --approval-mode auto_edit "Fix the null check in src/api.ts"

Full Auto Build

gemini -y "Build a REST API with user authentication"

Sandboxed Experiment

gemini -s -y "Try refactoring this module using a different pattern"

Interactive Session (with PTY)

bash pty:true workdir:~/project command:"gemini -i 'Help me debug this issue'"

Background Task

bash pty:true workdir:~/project background:true command:"gemini -y 'Build the feature module'"

---

Codex → Gemini Mapping

---

Extensions & MCP

Gemini supports extensions and MCP servers:

# List extensions
gemini -l

# Use specific extensions
gemini -e code-search,git "Find and fix the bug"

# Manage MCP servers
gemini mcp

coding-agent Reference

Contents

• STOP-AND-VERIFY (Before ANY Implementation)
• Self-Audit Triggers (Option A)
• Forbidden Flags & Minimum Timeouts
• Tool Fallback Chain
• Direct CLI Commands (Primary)
• Plan Mode Commands
• Wrapper Scripts (Secondary)
• Preflight Checks
• Pre-Completion Checklist
• Quick Reference
• Command Reference
• Code Quality Standards
• Issue Priority (P0-P3)
• tmux for Interactive Sessions (Optional)

STOP-AND-VERIFY (Before ANY Implementation)

Say this out loud before writing/changing any code:

STOP. Before I proceed, let me verify:
□ Am I using an agent CLI (Codex/Claude)? (not Edit/Write tools)
□ Am I on a feature branch? (not main)
□ Will I create a PR before completing this task?
□ Am I using adequate timeout? (minimum: 600s for reviews)
□ Am I avoiding --max-turns? (let it complete naturally)

If any box is unchecked → STOP and fix before proceeding.

Self-Audit Triggers (Option A)

Run self-audit before final response when:

• code/config changed,
• tests changed (or should have changed),
• review requested,
• docs commands/examples changed.

Skip only when:

• informational response with zero repo changes, or
• user asks for raw output only.

Forbidden Flags & Minimum Timeouts

❌ FORBIDDEN: --max-turns (any value)
❌ FORBIDDEN: timeout < 600s for reviews

✅ Reviews: TIMEOUT=600 minimum
✅ Architecture: TIMEOUT=600 minimum

Tool Fallback Chain

Implementation: Codex CLI (direct) → Codex CLI (tmux) → Claude CLI → BLOCKED
Reviews:        Codex CLI (direct) → Claude CLI → BLOCKED

⛔ NEVER skip to direct edits — request user override instead

Implementation mode routing:

• CODING_AGENT_IMPL_MODE=direct|tmux|auto (default: direct)
• auto -> tmux-first only in interactive TTY + tmux available; otherwise direct-first

Direct CLI Commands (Primary)

Codex

# Implementation default (feature work / architectural refactor)
codex --yolo exec -c model_reasoning_effort="high" "Implement feature X. No questions."

# Simple fix/docs or explicit fast/cheap request
codex --yolo exec -c model_reasoning_effort="medium" "Fix typo in one file"
codex --yolo exec -c model_reasoning_effort="low" "Update README command example quickly"

# Resume last session (context preserved)
codex exec resume --last

Claude Code

# Implementation (full autonomy)
claude -p --dangerously-skip-permissions "Implement feature X"

# Complex task with Opus
claude -p --model opus --dangerously-skip-permissions "Complex refactor..."

# Continue most recent session
claude -p -c "Fix the review findings"

# Resume specific session
claude -p --resume <session-id> "Continue implementation"

# List sessions
claude --resume

Plan Mode Commands

# Generate read-only plan (Codex)
./scripts/code-plan --engine codex --repo /path/to/repo --base main "Implement feature X"

# Generate strict plan mode output (Claude)
./scripts/code-plan --engine claude --model sonnet --repo /path/to/repo "Implement feature X"

# Execute approved plan (prompts for approval if still PENDING)
./scripts/code-implement --plan /path/to/repo/.ai/plans/<plan>.md

Wrapper Scripts (Secondary)

# Implementation (3 min timeout, tmux)
./scripts/code-implement "Implement feature X"

# Enforcement wrappers
TIMEOUT=600 ./scripts/safe-review.sh codex review --base <base> --title "PR Review"
TIMEOUT=180 ./scripts/safe-impl.sh codex --yolo exec -c model_reasoning_effort="high" "Implement feature X"

Preflight Checks

# Verify local prerequisites and Claude binary resolution
./scripts/doctor

# Verify Codex command/flag drift before editing command docs
./scripts/doc-drift-check

# Validate wrapper behavior
./scripts/smoke-wrappers.sh

Claude is resolved in this order: CODING_AGENT_CLAUDE_BIN → ~/.claude/local/claude → claude in PATH.

Pre-Completion Checklist

Before marking ANY task complete:

• [ ] On feature branch? (not main)
• [ ] PR created with URL?
• [ ] Used agent CLI (direct or tmux)? (not direct edits)
• [ ] Code review posted to PR?
• [ ] Standards review posted to PR?
• [ ] Implementation audit completed?
• [ ] Review audit completed?
• [ ] PR body includes What, Why, Tests, AI Assistance?
• [ ] Issue/PR title follows repo conventions?
• [ ] User-facing long-form text passed through /humanizer (or fallback explicitly noted)?

Unchecked box = Task NOT complete.

---

Quick Reference

Activate

Use /coding in OpenClaw to activate this skill.

For plan-first flow, use /plan <task> (maps to scripts/code-plan).

Agent CLI Commands

Codex — full autonomy:

codex --yolo exec -c model_reasoning_effort="high" "Your task. No questions."

Codex — resume session:

codex exec resume --last

Claude Code — full autonomy:

claude -p --dangerously-skip-permissions "Your task"

Claude Code — resume session:

claude -p -c "Follow up prompt"

PR Review (direct CLI):

cd /path/to/repo
timeout 600s codex review --base <base> --title "Review PR #N"

Git Workflow

# Checkout and review
gh pr checkout <PR> --repo owner/repo
timeout 600s codex review --base <base> --title "Review PR #<PR>"

# Merge (Martin only)
gh pr merge <PR> --repo owner/repo --admin --merge

Issue/PR Title Patterns

PR:    type(scope): imperative summary
Issue: feat: <capability> (for <surface>)
Issue: bug: <symptom> when <condition>
Issue: TODO: <cleanup> after <dependency>

PR Body Skeleton

## What
- ...

## Why
- ...

## Tests
- `command 1`
- `command 2`

## AI Assistance
- AI-assisted: yes/no
- Testing level: untested/lightly tested/fully tested
- Prompt/session log: <link or note>
- I understand this code: yes

Self-Audit Response Skeleton

## Self-Audit Summary
- Audit status: complete | skipped (reason)
- Tests run:
  - `command ...`
- Residual risks:
  - ...
- Assumptions:
  - ...
- Command/docs verification:
  - VERIFIED: ...
  - UNVERIFIED: ...

Definitions:

• VERIFIED: command/example was executed in this session.
• UNVERIFIED: command/example was not executed in this session.

Command Reference

Code Quality Standards

• Functions: max 30-40 lines
• Classes: max 500 lines
• Files: max 500 lines
• KISS, YAGNI, DRY, SRP principles

Issue Priority (P0-P3)

• P0: Critical (security, data loss)
• P1: High (major feature broken)
• P2: Medium (minor features)
• P3: Low (nice-to-have)

tmux for Interactive Sessions (Optional)

For durable TTY sessions with logging. See references/tooling.md for full tmux documentation.

SOCKET_DIR="${OPENCLAW_TMUX_SOCKET_DIR:-${CLAWDBOT_TMUX_SOCKET_DIR:-${TMPDIR:-/tmp}/openclaw-tmux-sockets}}"
mkdir -p "$SOCKET_DIR"
SOCKET="$SOCKET_DIR/openclaw.sock"
SESSION=codex-impl

tmux -S "$SOCKET" new-session -d -s "$SESSION" -n shell
TARGET="$(tmux -S "$SOCKET" list-panes -t "$SESSION" -F "#{session_name}:#{window_index}.#{pane_index}" | head -n 1)"
tmux -S "$SOCKET" send-keys -t "$TARGET" -l -- "codex --yolo exec -c model_reasoning_effort=\"high\" 'Implement feature X'"
tmux -S "$SOCKET" send-keys -t "$TARGET" Enter

# Monitor
tmux -S "$SOCKET" attach -t "$SESSION"
tmux -S "$SOCKET" capture-pane -p -J -t "$TARGET" -S -200

# Cleanup
tmux -S "$SOCKET" kill-session -t "$SESSION"

Reviews and Standards

Review Workflow

New Features (Issue → PR)

1. Implement with agent CLI. 2. Create PR. 3. Run Codex review. 4. Run standards review (references/STANDARDS.md) — required. 5. Fix issues, push updates to same branch.

Existing PRs

1. Checkout PR. 2. Run Codex review locally. 3. Run standards review. 4. Post both reviews to GitHub. 5. Fix issues, push updates.

Codebase Reviews

1. Run full review (Codex or Claude CLI with long timeout). 2. Classify findings by severity (P0–P3). 3. Create issues with file:line references.

Review Output Contract (Required)

• List findings first, ordered by severity (P0 -> P3).
• Include concrete file:line reference for each finding.
• Include open questions/assumptions after findings.
• If command/docs examples were changed, label each as:
• VERIFIED (executed) or
• UNVERIFIED (not executed)
• Never imply a command was validated when it was not run.

Self-Audit Summary Block (Required in final review response)

## Self-Audit Summary
- Audit status: complete | skipped (reason)
- Tests run:
  - `command ...`
- Residual risks:
  - ...
- Assumptions:
  - ...
- Command/docs verification:
  - VERIFIED: ...
  - UNVERIFIED: ...

Issue/PR Authoring Standard (Peter-style)

PR Titles

• Default: type(scope): imperative summary
• Use repo-specific override only when documented (e.g., Type: Description #issue)

Issue Titles

• Feature: feat: <capability> (for <surface>)
• Bug: bug: <symptom> when <condition>
• Tracking: TODO: <cleanup> after <dependency>

PR Body Sections (required)

1. What (3-6 concrete bullets) 2. Why (impact/reason) 3. Tests (exact commands run) 4. AI Assistance (used/not used, testing level, prompt/session log, understanding confirmation)

Review Commands

# Code review (direct CLI)
timeout 600s codex review --base <base> --title "PR #N Review"

# Standards review (direct CLI, preferred)
timeout 1200s codex --yolo exec -c model_reasoning_effort="medium" \
  "Review against coding standards in references/STANDARDS.md. Report PASS/FAIL per category with file:line refs."

# Standards review (tmux transport, optional for persistence)
./scripts/tmux-run timeout 1200s codex --yolo exec -c model_reasoning_effort="medium" \
  "Review against coding standards in references/STANDARDS.md. Report PASS/FAIL per category with file:line refs."

Posting Reviews to GitHub

# Approve
gh pr review <PR> --approve --body "LGTM"

# Request changes
gh pr review <PR> --request-changes --body "Found issues that need fixing"

# Comment only
gh pr review <PR> --comment --body "Suggestions and notes"

Standards Review Output Format

## references/STANDARDS.md Standards Review ✅|⚠️|❌

### ✅ PASSED
- Code Quality: Functions under 40 lines

### ⚠️ WARNINGS (P2)
- [file:23] Function has 7 parameters (limit: 4)

### ❌ ISSUES (P1)
- [file:8] Commit uses wrong format

### Assumptions / Open Questions
- Assumption: ...

### Command/Docs Verification
- VERIFIED: `timeout 600s codex review --base main`
- UNVERIFIED: `claude ...`

### Recommendation: APPROVE / REQUEST_CHANGES

Coding Standards

Contents

• Principles
• Size Limits
• Naming & Clarity
• Error Handling
• Testing
• Security
• Documentation

Language: English only - all code, comments, docs, examples, commits, configs, errors, tests

Foundational Principles

KISS (Keep It Simple)

• Simplest solution wins | Avoid premature abstraction | Reduce complexity
• Inline single-use helpers | Remove unused flexibility | Flatten unnecessary layers

YAGNI (You Aren't Gonna Need It)

• Build only what's needed now | No speculative features | No "future-proofing"
• Delete unused code completely | Add complexity when required, not before

DRY (Don't Repeat Yourself)

• Extract common patterns | Maintain consistency | Single source of truth
• Three strikes rule - don't abstract until third occurrence

SRP (Single Responsibility)

• One class, one reason to change | One responsibility per module
• Separate authentication, database operations, business logic, UI concerns

Design Principles

Law of Demeter

• Classes know only direct dependencies | Avoid chaining | "Don't talk to strangers"
• Add delegation methods | Pass required objects directly | Flatten access patterns

Dependency Injection

• Inject dependencies explicitly | Avoid hidden coupling | Make relationships visible
• Constructor injection for required dependencies | Method injection for optional

Polymorphism over Conditionals

• Prefer polymorphism to if/else chains | Use interfaces for extensibility
• Extract strategy pattern | Replace conditionals with polymorphic dispatch

Size Limits & Refactoring Triggers

• Functions: Max 30-40 lines
• Classes: Max 500 lines | Refactor when >30 methods
• Files: Max 500 lines | Split when exceeding or mixing multiple concerns
• Methods per Class: Max 20-30 methods

Refactoring Best Practices

• Small Steps: Incremental changes to reduce bugs | Test each modification
• Separate Concerns: Never mix refactoring with bug fixing
• No Backwards-Compatibility Hacks: Delete unused code completely | No renaming to _vars | No // removed comments

Universal Coding Standards

• Naming: Descriptive, searchable names | Replace magic numbers with named constants
• Functions: Max 3-4 parameters | Encapsulate boundary conditions | Declare variables near usage
• TypeScript: Use Record<string, unknown> over any | PascalCase (classes/interfaces) | camelCase (functions/variables)
• Error Handling: Explicit error patterns | Never silent failures
• Imports: Order as node → external → internal | Remove unused immediately
• Git Commits: Conventional format: type(scope): subject | 50 chars max, imperative mood | Atomic changes
• Repo override: If a repository defines a different format (e.g., Type: Description #issue), follow the repo and retain #issue linkage.

Inclusive Language

• Terms: allowlist/blocklist, primary/replica, placeholder/example, main branch, conflict-free, concurrent/parallel

Process Compliance Checks

During standards review, also verify process compliance:

Git Workflow Compliance

• [ ] Changes made on feature branch (not main)
• [ ] PR exists with descriptive title
• [ ] Commits follow conventional format (type(scope): description)
• [ ] No force pushes to shared branches
• [ ] No direct commits to main
• [ ] PR/issue titles follow repo conventions
• [ ] PR body includes What, Why, Tests, AI Assistance
• [ ] Tests section lists exact commands run

Tool Usage Compliance

• [ ] If agent CLI specified → verify CLI was used (look for CLI invocation in session log)
• [ ] Implementation done via agent CLI (Codex/Claude); direct CLI primary, tmux optional for durable runs (not direct file edits)
• [ ] Reviews done via codex review or claude -p
• [ ] Tool used is documented in PR description
• [ ] If AI-assisted, PR documents testing level and prompt/session log reference

Review Process Compliance

• [ ] Code/logic review completed
• [ ] Standards review completed
• [ ] Both reviews posted to GitHub PR
• [ ] Self-audit completed (or explicit skip reason documented)
• [ ] Issues found are addressed before merge

Compliance Review Output Format

## Process Compliance Review ✅|❌

### Git Workflow
- [x] Feature branch used
- [x] PR created
- [x] Conventional commits

### Tool Usage
- [x] Specified tools used
- [x] Implementation via agent CLI (direct or tmux)

### Review Process
- [x] Code review posted
- [x] Standards review posted

**Status**: COMPLIANT / NON-COMPLIANT

Plan: <short title>

Fast-Path

• Eligible: yes|no
• Reason: <one sentence>

1. Problem statement

2. Current state evidence

• Files:
• <path>#Lx-Ly — <why relevant>
• Commands run:
• <command>
• Observations:
• <bullet>

3. Proposed approach

4. Step-by-step change list

1. <step> 2. <step>

5. Risks + rollback

• Risks:
• <risk>
• Rollback:
• <exact rollback command/process>

6. Test plan

• Automated:
• <exact command>
• Manual:
• <manual check>
• Success criteria:
• <bullet>

7. Out-of-scope

• <bullet>

8. Approval prompt

Reply with one:

• APPROVE: <plan-id>
• REVISE: <what to change>

Tooling and Timeouts

Approach Comparison

Execution Policy Matrix

Implementation routing is configurable:

• CODING_AGENT_IMPL_MODE=direct -> direct first, tmux second
• CODING_AGENT_IMPL_MODE=tmux -> tmux first, direct second
• CODING_AGENT_IMPL_MODE=auto -> tmux first only when attached to an interactive TTY and tmux exists

Default behavior: direct.

Direct CLI (Primary)

Agent CLIs support non-interactive execution with permission bypass and session resume.

Reasoning defaults for Codex implementation:

• high for feature implementation and architectural refactors.
• medium/low for simple fixes, docs-only work, or explicit fast/cheap requests.

Codex CLI

Claude Code CLI

Permission Bypass

Session Management

Sessions persist to disk (~/.codex/sessions/ and ~/.claude/projects/<project>/) and survive process restarts.

MCP Clarification

Two MCP modes exist and should not be conflated:

1. codex mcp ...

• Adds external MCP tools for Codex to use during a run.

2. codex mcp-server

• Exposes Codex itself as an MCP server for another orchestrator.
• Experimental; use behind feature flags/pilots.

Preflight Checks

Run preflight before wrapper use:

./scripts/doctor

Run CLI drift checks before changing command docs:

./scripts/doc-drift-check

scripts/doctor checks:

• codex
• gh
• timeout
• Claude binary resolution in this order: CODING_AGENT_CLAUDE_BIN -> ~/.claude/local/claude -> claude in PATH

Wrapper Scripts

# Plan mode wrapper (read-only)
"${CODING_AGENT_DIR:-./}/scripts/code-plan" --engine codex --repo /path/to/repo "Implement feature X"

# Implementation wrapper (tmux transport)
"${CODING_AGENT_DIR:-./}/scripts/code-implement" "Implement feature X in /path/to/repo"

# Execute an approved plan artifact
"${CODING_AGENT_DIR:-./}/scripts/code-implement" --plan /path/to/repo/.ai/plans/<plan>.md

For reviews, use direct CLI — no wrapper needed:

# Detect base branch: main, master, or trunk (whichever exists)
timeout 600s codex review --base <base> --title "Review PR #N"

Validate wrappers locally:

./scripts/smoke-wrappers.sh

Advanced: tmux Wrapper (Optional)

For durable TTY sessions with logging. Use when you need to monitor long-running tasks or preserve terminal output.

tmux Conventions (OpenClaw)

• Socket directory: OPENCLAW_TMUX_SOCKET_DIR (legacy: CLAWDBOT_TMUX_SOCKET_DIR)
• Default socket: ${TMPDIR:-/tmp}/openclaw-tmux-sockets/openclaw.sock
• Send commands literally: tmux ... send-keys -l -- "cmd"
• Always print monitor commands after creating a session

Direct tmux Usage

SOCKET_DIR="${OPENCLAW_TMUX_SOCKET_DIR:-${CLAWDBOT_TMUX_SOCKET_DIR:-${TMPDIR:-/tmp}/openclaw-tmux-sockets}}"
mkdir -p "$SOCKET_DIR"
SOCKET="$SOCKET_DIR/openclaw.sock"
SESSION="codex-impl-$(date +%Y%m%d-%H%M%S)"

# Start session and run codex
tmux -S "$SOCKET" new-session -d -s "$SESSION" -n shell
TARGET="$(tmux -S "$SOCKET" list-panes -t "$SESSION" -F "#{session_name}:#{window_index}.#{pane_index}" | head -n 1)"
tmux -S "$SOCKET" send-keys -t "$TARGET" -l -- "codex --yolo exec -c model_reasoning_effort=\"high\" 'Implement feature X'"
tmux -S "$SOCKET" send-keys -t "$TARGET" Enter

# Monitor
tmux -S "$SOCKET" attach -t "$SESSION"
tmux -S "$SOCKET" capture-pane -p -J -t "$TARGET" -S -200

tmux-run Helper

scripts/tmux-run standardizes sockets, logging, and session names. Non-blocking by default unless --wait is passed.

# Run an implementation command in tmux (non-blocking)
CODEX_TMUX_SESSION_PREFIX=codex-impl \
  ./scripts/tmux-run timeout 180s codex --yolo exec -c model_reasoning_effort="high" "Implement feature X"

# Run a long implementation in tmux and wait for completion
CODEX_TMUX_SESSION_PREFIX=codex-impl \
  ./scripts/tmux-run --wait timeout 600s codex --yolo exec -c model_reasoning_effort="high" "Complex multi-file refactor"

Logs: ${XDG_STATE_HOME:-$HOME/.local/state}/openclaw/tmux/<session>.log

Cleanup:

• Kill session: tmux -S "$SOCKET" kill-session -t "$SESSION"
• Remove old logs: find "$LOG_DIR" -type f -mtime +7 -delete

Minimum Timeouts

Environment Variables

Coding Workflow & Operations

Contents

• Overview
• Git Workflow
• Hard Requirements (Violation = Task Failure)
• Self-Audit Protocol
• GitHub CLI (gh)
• Agent Workflow
• Multi-Phase Workflow (Session Resume)
• Agent CLI Reference
• Agent Utilization

Overview

Roles:

• @kesslerIO (Martin): Human Owner. Approves P0/P1 changes.
• @niemandBot (Niemand): AI Agent. Reviews code, runs checks, implements features.

Philosophy:

• Plan First: Always discuss approach before implementation.
• Surface Decisions: Present options with trade-offs.
• Confirm Alignment: Ensure agreement before coding.
• No Direct Edits: Use agent CLIs (Codex/Claude) to write code.

Git Workflow

Note: Niemand does NOT create branches, commit code, or merge PRs unless explicitly requested.

Standard Flow

1. Create Branch: git checkout -b type/description 2. Implement: Use agent CLI (see below) 3. Commit: git commit -m "type(scope): description" 4. Push: git push -u origin branch-name 5. PR: gh pr create 6. Review: Run code review (see below) 7. Fix: Address issues (resume session for context) 8. Merge: gh pr merge

Commit Types

• feat: New feature
• fix: Bug fix
• docs: Documentation only
• style: Formatting (no code change)
• refactor: Restructuring code (no API change)
• test: Adding tests
• chore: Build/tooling changes

Hard Requirements (Violation = Task Failure)

These are non-negotiable requirements. Violating any of these means the task has FAILED.

1. Branch Requirement

• MUST create feature branch before any code changes
• MUST NOT commit directly to main
• Violation Response: Stop and ask user to confirm branch creation

2. PR Requirement

• MUST create PR before code can be considered "done"
• MUST post review to PR before merge
• MUST include PR URL in task completion message
• Violation Response: Refuse to mark task complete without PR URL

3. Tool Usage Requirement

• When user specifies "use claude/codex/gemini": MUST use that CLI tool when available/configured
• MUST use agent CLI (direct or tmux wrappers) — not direct file edits
• For reviews: use direct codex review --base <base> or claude -p
• For implementation: prefer direct CLI (codex --yolo exec -c model_reasoning_effort="high") or scripts/code-implement
• Default reasoning policy: use high for feature implementation and architectural refactors; use medium/low only for simple fixes/docs or explicit fast/cheap requests
• MUST NOT use direct file edits when agent CLI is specified
• MUST document which tool was used in PR description
• Violation Response: Stop and switch to specified tool

4. Review Requirement

• MUST run code review before merge
• MUST run standards review (references/STANDARDS.md) before merge
• MUST post both reviews to GitHub PR
• Violation Response: Block merge until reviews are posted

5. Self-Audit Requirement

• MUST run self-audit before reporting completion when code/config/docs commands were changed
• MUST use findings-first format with severity order and file:line references for review tasks
• MUST verify changed command examples or explicitly mark them unverified
• Violation Response: Do not mark complete; run audit and report gaps

Self-Check Before Completion

Before reporting task complete, verify:

• [ ] Changes on feature branch (not main)?
• [ ] PR created and URL available?
• [ ] Correct tools used (agent CLI, direct or tmux)?
• [ ] Code review completed and posted?
• [ ] Standards review completed and posted?
• [ ] Self-audit completed (or explicit skip reason documented)?

Self-Audit Protocol

Run this before final response unless skip conditions apply.

When Required

• Code/config changed.
• Tests changed or should have changed.
• Review requested by user.
• Docs changed with executable commands/examples.

Skip Conditions

• Informational response only, no repo changes.
• User requested raw command output only.

If skipped, explicitly state why.

Phase 1: Implementation Audit

• [ ] Requirement coverage checked against user request.
• [ ] Edge cases and failure paths reviewed.
• [ ] Tests added/updated or explicit rationale for none.
• [ ] Risky assumptions called out.

Phase 2: Review Audit

• [ ] Findings ordered by severity (P0-P3).
• [ ] Every finding includes file:line reference.
• [ ] Regressions/unintended side effects checked.
• [ ] Changed docs commands/examples verified; if not run, mark UNVERIFIED.

Final Response Contract

Use this block in completion messages:

## Self-Audit Summary
- Audit status: complete | skipped (reason)
- Tests run:
  - `command ...`
- Residual risks:
  - ...
- Assumptions:
  - ...
- Command/docs verification:
  - VERIFIED: ...
  - UNVERIFIED: ...

GitHub CLI (gh)

Authentication

• Check status: gh auth status
• Login: gh auth login (uses PAT or browser)
• Switch account: gh auth switch --user <username>

Common Commands

• Create PR: gh pr create --title "feat: ..." --body "..."
• View PR: gh pr view <number>
• Checkout PR: gh pr checkout <number>
• Review PR: gh pr review <number> --approve
• Merge PR: gh pr merge <number> --admin --merge --delete-branch

Issue/PR Hygiene (Required)

• Keep one logical change per PR.
• Search before opening issues: gh issue list --search "<keywords>".
• PR title default: type(scope): imperative summary (unless repo override).
• Issue title defaults:
• Feature: feat: <capability> (for <surface>)
• Bug: bug: <symptom> when <condition>
• Tracking: TODO: <cleanup> after <dependency>
• PR body sections (required): What, Why, Tests, AI Assistance.
• Tests: list exact commands run.
• AI Assistance: used/not used, testing level, prompt/session log link, and "I understand this code."

Agent Workflow

Primary: Direct CLI

Use agent CLIs directly for most tasks. Session resume preserves full context across phases and is preferred over spawning sub-agents for routine implementation.

# Implementation (Codex)
codex --yolo exec -c model_reasoning_effort="high" "Implement feature X. No questions."

# Implementation (Claude)
claude -p --dangerously-skip-permissions "Implement feature X"

# Review (Codex)
codex review --base <base> --title "PR Review"

# Review (Claude)
claude -p --model opus "Review changes vs main branch for bugs, security, quality"

Secondary: tmux Wrappers

For durable implementation sessions with logging and monitoring:

# Implementation (tmux)
./scripts/code-implement "Implement feature X in /path/to/repo"

Code Review Process

Hierarchy: 1. Codex: Primary reviewer (codex review --base <base>). 2. Claude: Default fallback if Codex is unavailable. 3. Gemini (optional): Only if explicitly enabled (GEMINI_FALLBACK_ENABLE=1). 4. Sub-agent: Last resort for orchestration.

Step 1: Code Review (Logic/Bugs)

gh pr checkout <PR>
timeout 600s codex review --base <base> --title "PR #N Review"

Step 2: Standards Review (Required)

codex --yolo exec --model gpt-5.3-codex \
  -c model_reasoning_effort="medium" "Review against STANDARDS.md..."

Step 3: Posting Results

gh pr review <PR> --comment --body "$(cat review.md)"

Multi-Phase Workflow (Session Resume)

For complex tasks spanning multiple phases, use session resume to preserve full context:

Issue → Implement → PR → Review → Fix → Merge

# Phase 1: Implement from issue
codex --yolo exec -c model_reasoning_effort="high" "Implement feature described in issue #42. No questions."

# Phase 2: Create PR
gh pr create --title "feat(auth): add JWT validation" --body "..."

# Phase 3: Review
timeout 600s codex review --base <base> --title "Review PR #N"

# Phase 4: Fix review findings (resume preserves context)
codex exec resume --last
# Or with Claude:
claude -p --resume <session-id> "Fix the review findings"

# Phase 5: Re-review after fixes
timeout 600s codex review --base <base> --title "Re-review PR #N"

# Phase 6: Merge
gh pr merge --merge --delete-branch

Session Resume Commands

Codex resume compatibility note:

• Preferred: codex exec resume --last or codex exec resume <id>.
• If your installed Codex build does not support resume, start a fresh run and reference the prior issue/PR context explicitly.

When to Resume vs Start Fresh

• Resume: Fix review findings, continue implementation, follow-up on same codebase
• Fresh: New issue, different repo, unrelated task

Base Branch Detection (<base>)

Use this order:

# Primary
git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@'

# Fallback (when origin/HEAD is unset)
git remote show origin | sed -n '/HEAD branch/s/.*: //p'

Prompt Engineering Best Practices

• Be Specific: "Implement X using Y library" vs "Add X".
• No Confirmation: "Do not ask for confirmation. Just implement."
• Small Batches: Don't change 50 files at once.
• Clear Exit: "Reply with DONE when finished."

Agent CLI Reference

Codex CLI

For automated runs with full autonomy:

# Implementation (full autonomy)
codex --yolo exec -c model_reasoning_effort="high" "Implement feature X. No questions."

# Simple fix/docs or explicit fast/cheap request
codex --yolo exec -c model_reasoning_effort="medium" "Fix typo in one file"
codex --yolo exec -c model_reasoning_effort="low" "Update README command example quickly"

# Resume last session
codex exec resume --last

Claude Code CLI

# Implementation (full autonomy)
claude -p --dangerously-skip-permissions "Implement feature X"

# With model selection
claude -p --model opus --dangerously-skip-permissions "Complex task"

# Resume/continue
claude -p -c "Follow up on the previous task"
claude -p --resume <session-id> "Continue from here"

See references/claude-code.md for full Claude Code reference. See references/codex-cli.md for canonical Codex execution policy (exec, resume, MCP distinctions). See references/tooling.md for tmux wrappers, timeouts, and environment variables.

Agent Utilization

Delegate specific tasks to focused agents only when decomposition is clear and parallelizable:

• requirements-specialist: Specs → GitHub Issues
• implementation-architect: API/UI Design
• quality-assurance-specialist: Tests, Security, Perf
• docs-architect: Documentation updates

Trigger: Use sub-agents for independent tracks (for example: separate security/performance/test review streams). Keep single-agent codex exec + codex exec resume as the default path for implementation loops.

Sub-agent note:

• Codex multi-agent workflows are experimental.
• Non-interactive approval handling can fail if sub-agents request escalation unexpectedly.