Coding Router

Coding Router Skill 💻

This file exists for backward compatibility with single-entry skill setups (for example /coding). Canonical sibling skills live at:

• skills/plan-issue/SKILL.md
• skills/coding-agent/SKILL.md

Routing Rules

1. If user asks to plan/scope/estimate/design, follow plan-issue behavior. 2. For non-trivial implementation requests, produce a plan first and wait for exact APPROVE before any writes. 3. Only after APPROVE, follow coding-agent behavior with ACP-aware execution routing and CLI fallback.

Command Routing (Channel Aliases)

When invoked via channel aliases:

• /coding → use this compatibility skill as router.
• /plan → route directly to plan-issue behavior.
• /plan-review → route to plan review flow using scripts/plan-review.
• /plan-review-live → route to interactive plan review checkpoints using scripts/plan-review-live (Lobster in-repo workflow first, legacy fallback).
• /review_pr → route to review flow using references/reviews.md.

Runtime Status Contract

When wrappers are used for planning/review:

• Emit RUN_EVENT start at run start.
• If the run exceeds 30s, emit RUN_EVENT heartbeat every 20s.
• If interrupted or timed out, emit RUN_EVENT interrupted immediately with exit code.
• On non-interruption failure, emit RUN_EVENT failed.
• On success, emit RUN_EVENT done.

Known ACP Runtime Limitation

Issue #43 (upstream) may affect spawned ACP run observability and browser relay profile alias mapping. Use repo-side mitigations and bounded fallback guidance in:

• references/acp-troubleshooting.md

Non-Negotiable Gates

1. Never write files, install packages, commit, or open PRs before explicit APPROVE. 2. Never default to bypass flags (--yolo, --dangerously-skip-permissions). 3. Use bypass flags only when the user explicitly asks to bypass approvals.

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.

Canonical Local Clone (Anti-Divergence)

• Canonical local repo path: /home/art/projects/skills/shared/coding-agent.
• Do not maintain independent duplicate clones of this repository.
• Wrapper scripts enforce canonical-path execution and fail fast on non-canonical clones.
• Temporary override for controlled recovery only: CODING_AGENT_ALLOW_NONCANONICAL=1.
• CI runs are exempt from canonical-path enforcement (CI=true or GITHUB_ACTIONS=true).

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.

Review Routing Contract (Hard Rule)

• Plan artifact reviews must run through wrappers first:
• scripts/plan-review
• scripts/plan-review-live
• PR/code reviews must run via codex review --base ... directly or scripts/safe-review.sh.
• Never post a manual review summary before the corresponding wrapper/CLI run is attempted.

Verbosity Mode

• CODING_AGENT_VERBOSE controls execution progress verbosity and is opt-in.
• Default behavior is concise when the variable is unset or falsy.
• When enabled, use Now/Why/Next progress updates for active execution.
• Verbosity must never delay action once execution is approved and unblocked.
• Status updates are not a pause point: after any progress update, execute the next unblocked step immediately.
• Do not end on a progress-only response when a command can be run in the same turn.

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>.
• Hard-fail run status contract:
• Emit RUN_EVENT start when a wrapper run begins.
• For runs exceeding 30 seconds, emit RUN_EVENT heartbeat every 20 seconds.
• On interruption/timeouts/signals, emit RUN_EVENT interrupted immediately.
• On non-interruption failure, emit RUN_EVENT failed.
• Emit RUN_EVENT done on success.

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 each 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 when metadata is present.

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:

python3 -m unittest tests/python/test_wrapper_policy.py
while IFS= read -r script; do [[ -f "$script" ]] || continue; head -n 1 "$script" | grep -Eq '^#!/usr/bin/env (bash|sh)$|^#!/bin/(bash|sh)$' || continue; bash -n "$script"; done < <(git ls-files scripts)
while IFS= read -r script; do [[ -f "$script" ]] || continue; head -n 1 "$script" | grep -Eq '^#!/usr/bin/env (bash|sh)$|^#!/bin/(bash|sh)$' || 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 Skill Pack 💻

Plan-first OpenClaw skill pack.

Skill Layout

This repo now ships two sibling skills:

• skills/plan-issue/SKILL.md
• skills/coding-agent/SKILL.md

SKILL.md at repo root is a compatibility entry for single-skill setups.

Behavior Model

1. Use plan-issue for planning/scoping tasks. 2. Wait for explicit APPROVE. 3. Use coding-agent to execute the approved plan with ACP-first routing, then CLI fallback.

Guardrail: no bypass flags (--yolo, --dangerously-skip-permissions) unless explicitly requested.

Review Routing + Run Status Contract

• Plan artifact review: use ./scripts/plan-review or ./scripts/plan-review-live.
• PR/code review: use codex review --base ... directly or ./scripts/safe-review.sh.
• Never provide a manual review summary before running the matching wrapper/command.
• ./scripts/safe-review.sh now emits the full RUN_EVENT lifecycle for single-review runs and classifies timeout/signal exits as interrupted.

Long-run wrapper status events (hard-fail policy):

• RUN_EVENT start
• RUN_EVENT heartbeat every 20s after 30s elapsed
• RUN_EVENT interrupted on signal/timeout/interruption
• RUN_EVENT failed on non-interruption errors
• RUN_EVENT done on success

Usage

In OpenClaw:

/coding
/plan <task>
/plan-review [--plan <path>]
/plan-review-live [--plan <path>]
/review_pr <number|url>

CLI wrappers:

# Generate a read-only plan artifact
./scripts/plan --engine codex --repo /path/to/repo "Implement feature X"

# Review latest generated plan (or pass --plan explicitly)
./scripts/plan-review --repo /path/to/repo

# Review with interactive section checkpoints (Architecture -> Code Quality -> Tests -> Performance)
# Default engine: Lobster workflow in this repo (falls back to legacy engine if lobster is unavailable)
./scripts/plan-review-live --repo /path/to/repo

# Non-TTY/chat-safe live review finalization (no interactive prompts)
./scripts/plan-review-live --repo /path/to/repo --decisions "1A,2B,3A,4A" --blocking none
# or
./scripts/plan-review-live --repo /path/to/repo --resolve-file /path/to/decisions.json

# Force legacy engine explicitly
./scripts/plan-review-live --engine legacy --repo /path/to/repo

# Resume a paused Lobster approval run
./scripts/plan-review-live --resume-token <token> --output /path/to/repo/.ai/plan-reviews/<same-file>.md
# Optional: fail instead of auto-restarting when session state is missing
./scripts/plan-review-live --resume-token <token> --resume-missing-state error --output /path/to/repo/.ai/plan-reviews/<same-file>.md

# Execute an approved plan artifact
# Requires latest plan-review metadata to be ready unless --force is used.
# In non-TTY orchestration, this fails fast if plan status is not APPROVED.
# If the next step is review-loop-supervisor --open-pr, commit the generated implementation changes first.
# When executing from Hermes, do the work in a dedicated git worktree, not in the primary checkout.
# Phase B stops after push + PR; do not merge or deploy from this flow.
# Wrapper output remains text by default; pass --output json explicitly for machine-readable automation.
./scripts/code-implement --plan /path/to/repo/.ai/plans/<plan>.md

# Supervise review/fix loop until P0/P1/P2 clear (optional PR open/update)
./scripts/review-loop-supervisor --repo /path/to/repo --base main
# For strict closure, require a GitHub-visible review attached to the current PR head SHA.
./scripts/review-loop-supervisor --repo /path/to/repo --base main \
  --closure-mode github \
  --github-review-author codex-bot
# --open-pr expects a committed, clean feature branch before the review loop starts.
./scripts/review-loop-supervisor --repo /path/to/repo --base main \
  --test-cmd "npm run lint" \
  --test-cmd "npm test" \
  --open-pr --issue 50

# Validate an approved plan without mutating or launching (machine-readable output stays opt-in)
# Dry-run now validates plan/review/approval state only; it no longer requires codex/tmux to be installed.
./scripts/code-implement --plan /path/to/repo/.ai/plans/<plan>.md --dry-run --output json

Wrapper Architecture

The wrapper surface is split intentionally:

Bash wrappers:
- argv/env parsing
- backend execution
- text streaming
- tmux lifecycle and trusted RUN_EVENT handling

Python policy core:
- review-base selection
- plan-path and review-gate validation
- approval decisioning
- structured result normalization

This keeps transport behavior in shell while moving duplicated policy into one tested core.

Command Map (Telegram/OpenClaw)

These aliases are routing hints at the channel layer. Behavior is enforced by skills.

• /coding → compatibility entry skill (SKILL.md), routes plan-first + execution flow
• /plan <task> → skills/plan-issue/SKILL.md (plan only, no writes)
• /plan-review [--plan <path>] → batch plan review (single-pass full report). In unattended flow it may still end in a blocked state when interactive decision resolution is required; treat that as a hard stop, not an implicit handoff to implementation.
• /plan-review-live [--plan <path>] → Lobster workflow checkpoints by default (in-repo workflows/plan-review-live.lobster), legacy fallback if Lobster is unavailable; in non-TTY/chat use --decisions/--blocking or --resolve-file to finalize readiness metadata
• /review_pr <number|url> → review workflow with standards checks via references/reviews.md

Supervisor wrapper (CLI-only, no slash alias):

• ./scripts/review-loop-supervisor → finite-state review/fix supervisor with machine-checkable milestone events and .ai/review-loops/latest.json state output.

Approval Semantics

• APPROVE applies only to the latest plan in the current conversation context.
• Approval is not global, does not carry across unrelated threads/chats, and does not auto-approve future plans.
• If no pending plan exists in context, return: No pending plan found. Run /plan first.
• Plan approval is text-gated via APPROVE; this workflow does not require a separate "ExitPlanMode" tool.

OpenClaw Setup: Add Coding Skill Slash Commands

To enable this skill’s aliases for your team, add these entries under telegram.customCommands in OpenClaw.

1. Open your OpenClaw JSON config. 2. Find the telegram block and replace or extend customCommands in place. 3. Save the file and restart/reload OpenClaw. 4. Verify in Telegram that commands appear in the bot command list.

[
  { "command": "coding", "description": "Run coding-agent workflow" },
  { "command": "plan", "description": "Plan implementation only (no writes)" },
  { "command": "plan-review", "description": "Review generated plan in read-only mode" },
  { "command": "plan-review-live", "description": "Interactive plan review with decision checkpoints" },
  { "command": "review_pr", "description": "Review PR + standards check" }
]

If some commands already exist in your config, keep existing entries and append only missing new ones to avoid overriding other aliases.

Example resolve file for non-TTY finalization:

{
  "resolved_decisions": ["1A", "2B", "3A", "4A"],
  "blocking_decisions": []
}

Requirements

• GitHub CLI (gh)
• jq
• python3
• One of: Codex CLI (codex) or Claude Code CLI (claude / ~/.claude/local/claude)
• GNU timeout command (coreutils on macOS)
• Optional: tmux (wrapper workflows)

Validation

./scripts/doctor
./scripts/smoke-wrappers.sh

Canonical Local Repo Path

• Canonical local clone path: /home/art/projects/skills/shared/coding-agent
• Do not maintain independent duplicate clones for this repository.
• Wrappers fail fast when run from a non-canonical clone.
• Temporary override (recovery-only): CODING_AGENT_ALLOW_NONCANONICAL=1
• CI bypass: canonical-path guard is bypassed automatically when CI=true/GITHUB_ACTIONS=true.

ACP-First Wrapper Routing

Execution routing in scripts/safe-fallback.sh is mode-specific:

• impl: ACP first (via acpx), then CLI fallback chain
• review: codex review --base first, then ACP fallback, then remaining CLI fallback chain
• direct ACPX path: scripts/acpx-direct only (raw acpx ... invocations are not allowed in coding-agent orchestration)

• CODING_AGENT_ACP_ENABLE: 1 (default) or 0 to skip ACP attempt
• CODING_AGENT_ACP_AGENT: ACP harness alias (default: codex)
• CODING_AGENT_ACPX_CMD: executable path override for ACPX binary

Direct ACPX examples (sanctioned wrapper):

./scripts/acpx-direct --cwd /path/to/repo --format quiet codex sessions ensure --name "ca-codex-$(basename /path/to/repo)"
./scripts/acpx-direct --cwd /path/to/repo --format quiet codex -s "ca-codex-$(basename /path/to/repo)" "Reply with READY only."

Known runtime limitation:

• Issue #43 tracks upstream ACP observability and relay profile alias behavior.
• Repo-side mitigations and bounded fallbacks are documented in references/acp-troubleshooting.md.

Verbosity Configuration

The coding-agent skill supports an opt-in execution progress verbosity mode via CODING_AGENT_VERBOSE.

• Default: off (concise updates)
• On: structured progress updates (Now, Why, Next) during execution
• Scope: progress updates only (not globally longer planning/review prose)

Truthy values (case-insensitive): 1, true, on, yes, verbose

Planning/review wrapper heartbeat settings:

• CODING_AGENT_STATUS_PING_SECONDS (default 20)
• CODING_AGENT_LONG_RUN_THRESHOLD_SECONDS (default 30)

Review-loop supervisor heartbeat setting:

• --status-interval-seconds (default 120)

One-shot example:

CODING_AGENT_VERBOSE=1 ./scripts/code-implement --plan /path/to/repo/.ai/plans/<plan>.md

Persistent OpenClaw gateway setup:

1. Add to ~/.config/systemd/user/secrets.conf: CODING_AGENT_VERBOSE="1" 2. Reload the user unit:

systemctl --user daemon-reload && systemctl --user restart openclaw-gateway.service

CI Workflows

• wrapper-smoke.yml: wrapper syntax, drift, and smoke validation.
• pr-policy.yml: PR policy caller for main/master pull requests.
• reusable-pr-checks.yml: reusable branch/title/linked-issue policy checks with concurrency cancellation.

References

• references/WORKFLOW.md
• references/STANDARDS.md
• references/tooling.md
• references/codex-cli.md
• references/claude-code.md
• references/reviews.md
• references/lobster-workflows.md
• references/acp-troubleshooting.md

License

MIT

ACP Troubleshooting (Issue #43)

This repo tracks a known upstream ACP/OpenClaw runtime limitation:

• Issue: https://github.com/kesslerio/coding-agent-openclaw-skill/issues/43
• Scope: spawned ACP run observability and browser relay profile alias mismatch.

What This Means

This skill repo can provide mitigations and fallbacks, but it does not own the runtime fix for:

• cross-session ACP run completion visibility, and
• browser relay alias mapping for profile=chrome.

Validated Wrapper Path (Issue #58)

The wrapper-hardened path was validated in Telegram topic 4112 on 2026-03-03 to 2026-03-04 and did not reproduce the historical parent-side observability failure from issue #43.

Validated parent-visible pattern:

• RUN_EVENT start
• repeated RUN_EVENT heartbeat
• RUN_EVENT interrupted
• RUN_EVENT failed
• restarted RUN_EVENT start
• terminal RUN_EVENT done

Negative findings in the validated sample:

• no Session history visibility is restricted
• no Profile "chrome" not found
• no No session found

Interpretation:

• for the wrapper-hardened path, parent-topic RUN_EVENT telemetry now provides

sufficient observability without parent reads of hidden ACP child-session history

• no gateway-level change is needed for this validated wrapper path
• this does not claim a global ACP runtime fix; keep issue #43 cautions for

legacy or direct ACP visibility paths

Evidence source:

• Issue #58 validation note: https://github.com/kesslerio/coding-agent-openclaw-skill/issues/58#issuecomment-4033980599

Symptom Signatures

1) Spawn accepted, but run output not observable

You may see successful spawn output with a child session key, followed by forbidden history reads (for example visibility restrictions).

Typical pattern:

• status: accepted with childSessionKey/runId
• later: status: forbidden for session history from parent context

2) Browser relay profile mismatch

Relay attempts using profile="chrome" fail even when browser relay is working. Available profile names may differ (for example niemand, mac, openclaw).

3) ACPX runtime timeouts

acpx can be installed and still fail with initialization timeout in some runtime states.

Fast Triage

1. Run local preflight:

./scripts/doctor

2. Verify ACPX install:

command -v acpx
acpx --version

3. Optional ACPX sanity probe (bounded):

ACPX_RUN_TIMEOUT=120 ./scripts/acpx-direct --cwd "$PWD" --format text codex exec "Reply with READY only."

Stable unattended pattern (preferred for automation):

ACPX_RUN_TIMEOUT=120 ./scripts/acpx-direct --cwd "$PWD" --format quiet codex sessions ensure --name "ca-codex-$(basename "$PWD")"
ACPX_RUN_TIMEOUT=120 ./scripts/acpx-direct --cwd "$PWD" --format quiet codex -s "ca-codex-$(basename "$PWD")" "Reply with READY only."

Wrapper note:

• scripts/lib/acpx-wrapper.sh treats ACPX globals as wrapper-owned. Do not

forward --cwd, --format, --timeout (or other ACPX globals) through agent subcommand args.

• Use ACPX_RUN_TIMEOUT=<seconds> to bound wrapper calls instead.
• scripts/acpx-direct is the sanctioned direct-path entrypoint in this repo.

4. Repeatable local smoke check from this repo:

./scripts/acp-smoke-local.sh

Recommended Fallbacks

When ACP observability is degraded, use direct wrapper/CLI review and implementation flows in this repo:

# Plan review wrappers
./scripts/plan-review --repo /path/to/repo
./scripts/plan-review-live --repo /path/to/repo

# PR/code review (primary)
timeout 600s codex review --base <base> --title "PR #N Review"

# Wrapper fallback chain
./scripts/safe-fallback.sh review "Review PR #N"
./scripts/safe-fallback.sh impl "Implement approved plan"

Important Boundary

• This mitigation doc is a repo-side operational workaround.
• Root runtime fixes are tracked upstream and will be specified separately.

Claude Code CLI Reference

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

Plan-First Gate

For non-trivial tasks: 1. Plan first. 2. Wait for explicit APPROVE. 3. Execute with Claude commands after approval.

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 --permission-mode acceptEdits "Implement JWT auth middleware"

# Phase 2: Fix review findings (context preserved)
claude -p -c --permission-mode acceptEdits "Fix the review findings: add token expiry check"

# Phase 3: Add tests (context preserved)
claude -p -c --permission-mode acceptEdits "Add unit tests for the JWT middleware"

---

Permission Modes

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

# Explicit bypass (only when user asks to bypass approvals)
claude -p --permission-mode bypassPermissions "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 --permission-mode acceptEdits "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 --permission-mode acceptEdits "Implement the user registration endpoint"

# Phase 2: Fix issues (resume context)
claude -p -c --permission-mode acceptEdits "Fix the validation error in registration"

# Phase 3: Add tests
claude -p -c --permission-mode acceptEdits "Add integration tests for registration"

---

Codex → Claude Mapping

Codex CLI Reference

Canonical Codex guidance for plan-issue + coding-agent.

Plan-First Gate

For non-trivial tasks: 1. Plan first (plan-issue behavior). 2. Wait for explicit APPROVE. 3. Execute with Codex (coding-agent behavior).

Do not perform writes before APPROVE.

Preferred plan artifact flow:

./scripts/plan --engine codex --repo /path/to/repo "Implement feature X"
./scripts/plan-review --repo /path/to/repo
./scripts/plan-review-live --repo /path/to/repo

Default Strategy

Use single-agent Codex for most work: 1. codex -c 'model_reasoning_effort="high"' exec --full-auto "..." for feature implementation/refactors after approval. 2. codex exec resume --last "..." for follow-up work. 3. Use tmux only when persistence/reattach is required.

Reasoning default policy:

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

Core Commands

Implementation (post-approval)

codex -c 'model_reasoning_effort="high"' exec --full-auto "Implement feature X according to the approved plan."

Resume previous context

codex exec resume --last "Address review findings from the previous run"

Review against base branch

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

Review latest generated plan (read-only)

./scripts/plan-review --repo /path/to/repo

Review latest generated plan (interactive checkpoints)

./scripts/plan-review-live --repo /path/to/repo
# Optional: force legacy engine
./scripts/plan-review-live --engine legacy --repo /path/to/repo

code-implement --plan enforces latest per-plan review metadata readiness. If blocking decisions remain unresolved, run plan-review-live first or use --force to bypass explicitly.

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

• Guardrailed default: codex exec --full-auto "..."
• Explicit bypass (only when user asks to bypass approvals):

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

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

1. codex mcp ...: configure external MCP tools for Codex runs. 2. codex mcp-server: expose Codex itself as an MCP server.

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

Lobster Workflows (In-Repo)

This repository contains the plan-review-live Lobster workflow used by ./scripts/plan-review-live.

Files

• workflows/plan-review-live.lobster: workflow definition.
• scripts/plan-review-lobster/section-step.sh: per-section review runner.
• scripts/plan-review-live-lobster: wrapper integration for metadata contract and decision collection.

Execution Contract

• Default live engine is Lobster (PLAN_REVIEW_LIVE_ENGINE=lobster).
• If lobster binary is missing, wrapper falls back to legacy engine automatically.
• Output + metadata contract remains unchanged:
• markdown output in .ai/plan-reviews/*.md
• metadata history file + latest-<plan-id>.json
• fields: schema_version, plan_id, plan_path, mode,

ready_for_implementation, blocking_decisions, resolved_decisions, created_at, review_markdown_path

Commands

# Default (Lobster first)
./scripts/plan-review-live --repo /path/to/repo

# Legacy path
./scripts/plan-review-live --engine legacy --repo /path/to/repo

# Resume a paused Lobster run
./scripts/plan-review-live --resume-token <token> --output /path/to/repo/.ai/plan-reviews/<same-file>.md

# Optional strict mode when resume state is missing
./scripts/plan-review-live --resume-token <token> --resume-missing-state error --output /path/to/repo/.ai/plan-reviews/<same-file>.md

Resume behavior persists decision state in:

• <review-markdown-path>.lobster-session.json

By default, if --resume-token is provided but session state is missing, the wrapper auto-recovers by restarting live mode without the resume token. Use --resume-missing-state error (or env override below) to keep strict fail behavior.

That file is removed automatically when the live review completes successfully.

Environment

• PLAN_REVIEW_LIVE_ENGINE: lobster (default) or legacy.
• PLAN_REVIEW_LOBSTER_FILE: override workflow file path.
• PLAN_REVIEW_LIVE_SECTION_TIMEOUT: per-section timeout seconds.
• PLAN_REVIEW_LIVE_TOTAL_TIMEOUT: total timeout budget seconds.
• PLAN_REVIEW_LIVE_DECISION_TIMEOUT: timeout for each interactive decision prompt (default 600).
• PLAN_REVIEW_LIVE_RESUME_MISSING_STATE: auto (default) or error.
• PLAN_REVIEW_LIVE_ALLOW_NON_TTY: allow live mode in non-TTY for scripted runs.

coding-agent Reference

Contents

• Plan-First Execution Gate
• 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)

Plan-First Execution Gate

For non-trivial requests: 1. Run planning flow first. 2. Wait for explicit APPROVE. 3. Execute implementation only after approval.

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

Review Routing + Run Events (Hard Rules)

• Plan artifact review: ./scripts/plan-review or ./scripts/plan-review-live
• PR/code review: timeout 600s codex review --base <base> --title "PR #N Review" or safe-review.sh
• Never produce manual review output before running the matching command.
• Required wrapper events:
• RUN_EVENT start
• RUN_EVENT heartbeat every 20s after 30s elapsed
• RUN_EVENT interrupted or RUN_EVENT failed
• RUN_EVENT done

Tool Fallback Chain

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

⛔ NEVER skip to direct edits — request user override instead

Known limitation:

• Upstream issue #43 can affect ACP spawned-run observability and profile=chrome relay expectations.
• See references/acp-troubleshooting.md for bounded checks and fallback commands.

Validated wrapper note:

• Issue #58 confirmed that the wrapper-hardened path in Telegram topic 4112

on 2026-03-03 to 2026-03-04 was observable from the parent topic via RUN_EVENT telemetry alone.

• Success criterion for this path: the parent topic shows the RUN_EVENT

lifecycle (start, heartbeat, terminal interrupted/failed/done as applicable) plus the emitted artifact or log path when provided.

• Keep issue #43 warnings scoped to upstream ACP/runtime behavior and

legacy/direct visibility paths; do not treat this as a global runtime fix.

Canonical local repo policy:

• Use /home/art/projects/skills/shared/coding-agent as the only local clone for this repo.
• Wrappers fail fast on non-canonical clones unless CODING_AGENT_ALLOW_NONCANONICAL=1 is explicitly set.
• CI bypass is automatic when CI=true or GITHUB_ACTIONS=true.

Implementation mode routing:

• CODING_AGENT_IMPL_MODE=direct|tmux|auto (default: direct)
• auto -> tmux-first only in interactive TTY + tmux available; otherwise direct-first
• ACP-first toggle: CODING_AGENT_ACP_ENABLE=1|0 (default: 1)
• ACPX binary override: CODING_AGENT_ACPX_CMD=/path/to/acpx
• direct ACPX wrapper: ./scripts/acpx-direct ... (raw acpx ... commands are out of policy for coding-agent orchestration)

Direct CLI Commands (Primary)

Codex

# Implementation default (feature work / architectural refactor)
codex -c 'model_reasoning_effort="high"' exec --full-auto "Implement feature X based on approved plan."

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

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

Claude Code

# Implementation (post-approval)
claude -p --permission-mode acceptEdits "Implement feature X"

# Complex task with Opus
claude -p --model opus --permission-mode acceptEdits "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/plan --engine codex --repo /path/to/repo --base main "Implement feature X"

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

# Review latest plan with Codex read-only mode (or pass --plan)
./scripts/plan-review --repo /path/to/repo

# Interactive section-by-section review with decision checkpoints
./scripts/plan-review-live --repo /path/to/repo

# Force legacy live-review engine
./scripts/plan-review-live --engine legacy --repo /path/to/repo

# Non-TTY/chat-safe finalization (no interactive prompts)
./scripts/plan-review-live --repo /path/to/repo --decisions "1A,2B,3A,4A" --blocking none

# Resolve from machine-readable file
./scripts/plan-review-live --repo /path/to/repo --resolve-file /path/to/decisions.json

# Resume a paused Lobster run
./scripts/plan-review-live --resume-token <token> --output /path/to/repo/.ai/plan-reviews/<same-file>.md

# Keep strict resume behavior when state is missing (default is auto-restart)
./scripts/plan-review-live --resume-token <token> --resume-missing-state error --output /path/to/repo/.ai/plan-reviews/<same-file>.md

# Execute approved plan (non-TTY runs fail fast if still PENDING)
# Requires latest plan-review metadata to be ready unless --force is used.
# If the next step is review-loop-supervisor --open-pr, commit the generated implementation changes first.
./scripts/code-implement --plan /path/to/repo/.ai/plans/<plan>.md

# Supervise review/fix loop until P0-P2 blockers clear
./scripts/review-loop-supervisor --repo /path/to/repo --base main
# --open-pr expects a committed, clean feature branch before the review loop starts.
./scripts/review-loop-supervisor --repo /path/to/repo --base main \
  --test-cmd "npm run lint" --test-cmd "npm test" --open-pr --issue 50

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 -c 'model_reasoning_effort="high"' exec --full-auto "Implement feature X"
ACPX_RUN_TIMEOUT=120 ./scripts/acpx-direct --cwd /path/to/repo --format quiet codex -s session-name "Implement approved plan"

# Review-loop supervisor (machine-checkable milestones + state artifacts)
./scripts/review-loop-supervisor --repo /path/to/repo --base main --status-interval-seconds 120

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?
• [ ] User-facing long-form text passed through /humanizer (or fallback explicitly noted)?
• [ ] PR body includes What, Why, Tests, AI Assistance?
• [ ] Issue/PR title follows repo conventions?

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/plan), /plan-review (batch), and /plan-review-live (Lobster workflow by default with legacy fallback; pass --decisions/--blocking or --resolve-file in non-TTY chat flows). If batch review reports that interactive resolution is still required, stop there; do not treat batch review alone as implementation-ready. review-loop-supervisor is CLI-only and writes run state to .ai/review-loops/latest.json.

Agent CLI Commands

Codex — guarded implementation:

codex -c 'model_reasoning_effort="high"' exec --full-auto "Your approved task."

Codex — resume session:

codex exec resume --last

Claude Code — guarded implementation:

claude -p --permission-mode acceptEdits "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"

PR Review config-safety trigger check:

gh pr view <PR> --json files --jq '.files[].path'

Git Workflow

# If no PR arg was provided, list and select one PR first
gh pr list --repo owner/repo

# Checkout and review
gh pr checkout <PR> --repo owner/repo
gh pr view <PR> --repo owner/repo
gh pr diff <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.

Configuration Safety Checklist (/review_pr)

Trigger when changed files include:

• .env, .env.*
• *.yml, *.yaml, *.json, *.toml, *.ini, *.conf, *.properties
• Dockerfile, docker-compose*
• .github/workflows/*
• config/, infra/, deploy/, k8s/, helm/

For each flagged config change, include:

• Load-test evidence (or explicit "not tested")
• Rollback method + expected rollback time
• Monitoring signals/alerts
• Dependency/limit interactions
• Historical context (incidents or none known)

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 exec --full-auto '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.

PR Intake (/review_pr)

1. If no PR number/URL is provided, run gh pr list and ask user to choose one PR. 2. If a PR number is provided, run gh pr view <number> to gather PR metadata. 3. Run gh pr diff <number> and review the actual patch before issuing findings.

Review Focus Checklist (Required)

• Code correctness
• Architecture and dependency boundaries
• Project conventions and style
• Performance implications
• Test coverage quality and gaps
• Security considerations

Configuration Safety Review (Required When Triggered)

Run a configuration safety section in the review output when the PR touches any of:

• .env, .env.*
• *.yml, *.yaml, *.json, *.toml, *.ini, *.conf, *.properties
• Dockerfile, docker-compose*
• .github/workflows/*
• config/, infra/, deploy/, k8s/, helm/

Treat numeric/config value changes as risky until justified. For each flagged config change, require:

• Load-test evidence (or explicit "not tested")
• Rollback method and expected rollback time
• Monitoring signals/alerts to detect regressions
• Dependency/limit interaction analysis (upstream/downstream/system caps)
• Historical context (similar prior incidents or "none known")

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.
• Include a short PR overview after findings (what changed and why).
• Include specific improvement suggestions and key risks.
• When configuration safety is triggered, include a dedicated Configuration Safety subsection with evidence.
• 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

# If PR number is missing, list open PRs first
gh pr list

# Load PR metadata
gh pr view <PR>

# Inspect patch before review output
gh pr diff <PR>

# Optional: list changed file paths to detect config-safety trigger
gh pr view <PR> --json files --jq '.files[].path'

# 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

Plan-First Gate

For non-trivial changes: 1. Produce a plan first. 2. Wait for explicit APPROVE. 3. Execute implementation commands only after approval.

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 session resume and approval-aware modes.

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

Approval Modes

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
• jq
• timeout
• Claude binary resolution in this order: CODING_AGENT_CLAUDE_BIN -> ~/.claude/local/claude -> claude in PATH
• ACPX discovery in this order: CODING_AGENT_ACPX_CMD -> acpx in PATH (warning-only; CLI fallback remains available)
• canonical local clone enforcement (default canonical path: /home/art/projects/skills/shared/coding-agent)

Wrapper Scripts (Plan + Implementation)

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

# Implementation (tmux transport wrapper)
"${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

code-implement execution contract

• New flags:
• --output text|json
• --dry-run
• --approve
• --require-approved
• --non-interactive
• Flag precedence:
• --dry-run validates only. It never mutates plan state and never launches Codex/tmux.
• --approve and --require-approved are mutually exclusive.
• --force bypasses review readiness only. It does not imply approval.
• --non-interactive forbids prompt paths. Pending plans must already be approved or use --approve.
• Output behavior:
• Default output remains text. Use --output json explicitly when machine-readable output is required.
• JSON responses include ok, command, run_id, and data or error.
• Error payloads include error.code, error.message, and error.remediation.
• Non-blocking launches return state: "launched_not_verified" with session, socket, and log metadata.
• JSON output never includes raw prompt bodies, raw plan markdown, or secrets.

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

Canonical direct ACPX wrapper (for explicit direct-path runs):

./scripts/acpx-direct --cwd /path/to/repo --format quiet codex sessions ensure --name "ca-codex-$(basename /path/to/repo)"
./scripts/acpx-direct --cwd /path/to/repo --format quiet codex -s "ca-codex-$(basename /path/to/repo)" "Reply with READY only."

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 -c 'model_reasoning_effort=\"high\"' exec --full-auto '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 -c 'model_reasoning_effort="high"' exec --full-auto "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 -c 'model_reasoning_effort="high"' exec --full-auto "Complex multi-file refactor"

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

Structured lifecycle events (stderr):

• TMUX_RUN_EVENT start ts=<iso> token=<id> session=<name> log_path=<path> socket=<path> mode=<wait|nowait>
• TMUX_RUN_EVENT heartbeat ts=<iso> token=<id> session=<name> elapsed_s=<seconds> (wait mode only)
• TMUX_RUN_EVENT done ts=<iso> token=<id> session=<name> exit_code=0 elapsed_s=<seconds>
• TMUX_RUN_EVENT failed ts=<iso> token=<id> session=<name> exit_code=<nonzero> elapsed_s=<seconds>
• TMUX_RUN_EVENT interrupted ts=<iso> token=<id> session=<name> exit_code=<124|130|137|143> elapsed_s=<seconds>

When running in wait mode, tmux-run prints only the most recent pane lines to stdout for relay safety. Full output remains in the log file path above.

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.
• Approval Gate: For non-trivial changes, wait for explicit APPROVE before writing files.
• Surface Decisions: Present options with trade-offs.
• Confirm Alignment: Ensure agreement before coding.
• No Direct Edits: Use agent CLIs (Codex/Claude) to write code.

Channel Alias Notes

Some channels expose aliases (/coding, /plan, /plan-review, /plan-review-live, /review_pr). These aliases do not change core policy:

• Plan-first for non-trivial work
• Explicit approval gate before writes
• No bypass-by-default flags unless the user explicitly requests bypass.
• Plan completion is approved through explicit APPROVE reply (there is no separate ExitPlanMode tool call in this repo flow).

Review Routing + Run Status (Hard Rules)

• Plan artifact reviews must use wrappers first: scripts/plan-review or scripts/plan-review-live.
• PR/code reviews must use codex review --base ... (or safe-review.sh wrapper).
• For long review/fix gate cycles, use scripts/review-loop-supervisor for milestone + blocker-delta state events.
• Do not send manual review findings before the matching review command executes.
• For runs >30 seconds, emit wrapper status updates every 20 seconds.
• On interruption/timeout/signal, emit immediate interruption status with exit code and remediation command.

Known ACP Runtime Limitation

• Upstream issue #43 can affect spawned ACP run observability and browser relay profile alias mapping (profile=chrome).
• This repo provides bounded mitigations and fallback commands only.
• See references/acp-troubleshooting.md for triage and fallback guidance.

Canonical Local Repo Policy (Anti-Divergence)

• Canonical local path for this repository is /home/art/projects/skills/shared/coding-agent.
• Do not maintain independent duplicate clones for this repo.
• Wrappers enforce canonical-path execution by default and fail fast on non-canonical clones.
• Temporary override exists for controlled recovery only: CODING_AGENT_ALLOW_NONCANONICAL=1.
• CI runs bypass canonical-path enforcement automatically (CI=true or GITHUB_ACTIONS=true).

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 -c 'model_reasoning_effort="high"' exec --full-auto) or scripts/code-implement
• When using scripts/safe-fallback.sh, wrappers attempt ACP first (acpx) and then use CLI fallback chain.
• 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?
• [ ] User-facing long-form text passed through /humanizer (or explicit fallback noted)?
• [ ] 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 -c 'model_reasoning_effort="high"' exec --full-auto "Implement feature X according to approved plan."

# Implementation (Claude)
claude -p --permission-mode acceptEdits "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"

Plan Mode Wrapper

For non-trivial work, generate a plan artifact before implementation:

./scripts/plan --engine codex --repo /path/to/repo "Implement feature X"
./scripts/plan-review --repo /path/to/repo
./scripts/plan-review-live --repo /path/to/repo
# Force legacy engine (bypass Lobster workflow path)
./scripts/plan-review-live --engine legacy --repo /path/to/repo
# Non-TTY/chat-safe finalization:
./scripts/plan-review-live --repo /path/to/repo --decisions "1A,2B,3A,4A" --blocking none
# Or:
./scripts/plan-review-live --repo /path/to/repo --resolve-file /path/to/decisions.json
# Optional strict resume behavior:
./scripts/plan-review-live --resume-token <token> --resume-missing-state error --output /path/to/repo/.ai/plan-reviews/<same-file>.md
./scripts/code-implement --plan /path/to/repo/.ai/plans/<plan>.md
# If the next step is review-loop-supervisor --open-pr, commit the generated implementation changes first.
# Supervise review/fix loop until P0-P2 clear; optional PR open/update.
./scripts/review-loop-supervisor --repo /path/to/repo --base main
# --open-pr expects a committed, clean feature branch before the review loop starts.
./scripts/review-loop-supervisor --repo /path/to/repo --base main --test-cmd "npm test" --open-pr --issue 50

code-implement --plan now enforces the latest per-plan review metadata gate. plan-review-live uses the in-repo Lobster workflow by default and falls back to the legacy live-review engine when Lobster is unavailable. In non-TTY orchestration, code-implement --plan fails fast when plan status is not APPROVED instead of blocking on interactive confirmation. Use plan-review-live to resolve blocking decisions before execution, or --force to bypass explicitly. If the next step is review-loop-supervisor --open-pr, commit the generated implementation changes before handing off so the review loop starts from a clean, deterministic branch state. review-loop-supervisor uses a strict parse contract (SUPERVISOR_COUNTS/SUPERVISOR_TOP) and persists machine-readable state to .ai/review-loops/latest.json plus per-run history JSON files.

Code Review Process

Hierarchy: 1. Codex: Primary reviewer (codex review --base <base>). 2. ACPX: Review fallback path through harness routing. 3. Claude: Secondary CLI fallback if Codex is unavailable. 4. Gemini (optional): Only if explicitly enabled (GEMINI_FALLBACK_ENABLE=1). 5. 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 exec --full-auto --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 -c 'model_reasoning_effort="high"' exec --full-auto "Implement feature described in issue #42 according to approved plan."

# 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".
• Use Explicit Gate: "Plan first; execute only after I reply APPROVE."
• Small Batches: Don't change 50 files at once.
• Clear Exit: "Reply with DONE when finished."

Agent CLI Reference

Codex CLI

For automated runs after approval:

# Implementation (post-approval)
codex -c 'model_reasoning_effort="high"' exec --full-auto "Implement feature X based on approved plan."

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

# Resume last session
codex exec resume --last

Claude Code CLI

# Implementation (post-approval)
claude -p --permission-mode acceptEdits "Implement feature X"

# With model selection
claude -p --model opus --permission-mode acceptEdits "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.

TODOs

All current follow-ups are tracked as GitHub issues.