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:

Implement: codex --yolo exec -c model_reasoning_effort="high" "Implement feature from issue #N"
Create PR: gh pr create --title "feat: ..." --body "..."
Review: timeout 600s codex review --base <base> --title "Review PR #N"
Fix issues: codex exec resume --last (context preserved)
Re-review: timeout 600s codex review --base <base> --title "Re-review PR #N"
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)

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.
Feature branch — Always use a feature branch for changes.
PR before done — Always create a PR before completion.
GitHub hygiene — Precise titles, structured bodies, explicit test commands, AI disclosure.
No --max-turns — Let agent runs complete naturally.
Adequate timeouts — Minimum 600s for reviews.
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.

coding-agent