coding-agent

# Coding-Agent Skill

## Entry Gate

Only execute this skill after explicit approval in the current conversation context:
- `APPROVE`

Approval must correspond to the latest pending plan in-context.
If no matching approved plan exists, stop and request:
`Run /plan first, then reply APPROVE.`

## Execution Workflow

1. Verify toolchain before major workflows:
- `command -v codex && codex --version`
- `command -v timeout`
- `command -v gh`
- `command -v claude || test -x ~/.claude/local/claude`
2. Gather read-only context first (`rg`, `git status`, `git diff`, docs).
3. Execute the approved implementation plan.
4. Run relevant validation:
- formatting/lint
- typecheck
- unit/integration/e2e tests as applicable
5. Report exact commands run, outcomes, and residual risk.

### Review Routing Contract (Hard Rule)

- Plan artifact review must run via `scripts/plan-review` or `scripts/plan-review-live`.
- PR/code review must run via `codex review --base ...` (or `safe-review.sh` wrapper).
- Do not publish a manual review summary before running the review command/wrapper.

## ACP-First Routing

For harness-style implementation/review requests, ACP routing is mode-specific:

- Implementation uses ACP first (via `acpx`) with CLI fallback.
- Review keeps review-native `codex review --base` first, then ACP fallback.
- CLI fallback chain remains mandatory if ACP is unavailable.
- Direct ACPX calls in coding-agent orchestration must use `scripts/acpx-direct`.
- Do not emit raw `acpx ...` commands from prompts or wrappers.
- Disable ACP-first per run with `CODING_AGENT_ACP_ENABLE=0`.
- Override ACPX binary path with `CODING_AGENT_ACPX_CMD`.
- Override ACP agent alias with `CODING_AGENT_ACP_AGENT` (default: `codex`).

Known runtime limitation:
- Issue #43 tracks upstream ACP spawned-run observability and relay profile alias behavior.
- Use repo-side mitigation and fallback guidance in `references/acp-troubleshooting.md`.

## Verbosity Mode (Progress Updates)

`CODING_AGENT_VERBOSE` controls execution progress verbosity. Default is off.

- `off` (default): concise progress updates.
- `on`: include structured progress updates with `Now`, `Why`, and `Next`.

Accepted truthy values (case-insensitive): `1`, `true`, `on`, `yes`, `verbose`.
Accepted falsy values: unset, `0`, `false`, `off`, `no`.

When verbose mode is on:
- Send kickoff execution status in `Now/Why/Next` format.
- For long-running tasks, send periodic status updates.
- Send a completion update with outcome and blockers (if any).

Verbosity must not block execution. After explaining intent, proceed immediately
unless waiting on a required user decision or an explicit approval gate.
Status updates are not a wait state: if the next step is executable, run it in the same turn.

### Long-Run Hard-Fail Policy

For wrapper/CLI runs expected to exceed 30 seconds:
- Emit `RUN_EVENT start`.
- Emit `RUN_EVENT heartbeat` every 20 seconds while running.
- Emit `RUN_EVENT interrupted` immediately on signal/timeout/interruption.
- Emit `RUN_EVENT failed` on non-interruption errors.
- Emit `RUN_EVENT done` on success.
## Guardrails

- No bypass-by-default. Do not use approval-bypass flags unless the user explicitly requests bypass.
- Use feature branches for code changes.
- Keep changes scoped to the approved plan.

## Reference Loading

Open only the references needed for the current task:
- `references/WORKFLOW.md`
- `references/STANDARDS.md`
- `references/tooling.md`
- `references/codex-cli.md`
- `references/claude-code.md`
- `references/reviews.md`