Coding Lead

---

name: coding-lead description: Coding execution skill for any implementation-focused agent. Current production path is claude-only with simple tasks direct, medium tasks preferring ACP run or direct acpx, and complex tasks handled via existing agent continuity plus context files instead of ACP session persistence. Integrates with qmd and smart-agent-memory when available.

---

Coding Lead

> This is a coding execution skill for any agent that owns implementation work. > It defines how coding work runs, not who should own the task. > In multi-agent teams, routing may be handled elsewhere; in single-agent use, this skill still works directly.

Route by complexity. Current production path is claude-only. Do not depend on ACP session persistence in IM threads; use direct execution, direct acpx, and existing implementation session continuity instead.

Task Classification

| Level | Criteria | Action | |-------|----------|--------| | Simple | Single file, <60 lines, clear local scope | Direct: read/write/edit/exec | | Medium | 2-5 files, clear scope, likely follow-up questions | Prefer Claude ACP mode:"run" or direct acpx → fallback direct | | Complex | Multi-module, architecture, needs continuity | Use existing implementation session continuity + context files + direct acpx/direct execution |

When in doubt, go one level up.

Practical default rule

Simple: stay in the current session; do not open ACP unless clearly beneficial

Medium: prefer Claude ACP one-shot (run) when available; otherwise direct acpx

Complex: preserve continuity through the existing implementation session, on-disk context files, and serial follow-ups; do not make IM-bound ACP session the default path

ACP unavailable: medium/complex fall back to direct acpx or direct execution; simple tasks were already direct by default

Never block on ACP availability: ACP is an accelerator, not a hard dependency

Multi-agent dispatch rule (when dispatching to other agents)

Dispatch to ACP-configured agents (agents with runtime.type: "acp" in openclaw.json): use sessions_spawn(runtime="acp"), may include streamTo="parent"

Dispatch to standard agents (all others): use sessions_spawn(runtime="subagent"), never include streamTo

Results from subagent spawns arrive via auto-announce, not polling

How to tell which is which: check the target agent's config in openclaw.json — if it has runtime.type: "acp", use ACP; otherwise use subagent

Tech Stack (New Projects)

| Layer | Preferred | Fallback | |-------|-----------|----------| | Backend | PHP (Laravel/ThinkPHP) | Python | | Frontend | Vue.js | React | | Mobile | Flutter | UniApp-X | | CSS | Tailwind | - | | DB | MySQL | PostgreSQL |

Existing projects: follow current stack. New: propose first, wait for confirmation.

Tool Detection & Fallback

All tools are optional. Detect once per session:

| Tool | Check | Fallback | |------|-------|----------| | smart-agent-memory | node ~/.openclaw/skills/smart-agent-memory/scripts/memory-cli.js stats ok? | memory_search + manual .md writes | | qmd | qmd --version ok? | grep (Linux/macOS) / Select-String (Windows) / find | | ACP | See ACP detection below | Direct read/write/edit/exec |

Notation: [memory] [qmd] [acp] = use if available, fallback if not.

ACP Detection & Routing

Run once per session, stop at first success:

Step 1: Try sessions_spawn (timeout: 30s)

sessions_spawn(runtime: "acp", agentId: "claude", task: "say hello", mode: "run", runTimeoutSeconds: 30)

Preferred in OpenClaw because it cleanly supports both:

mode: "run" for one-shot coding tasks

mode: "session" for persistent long-context coding threads

Got a reply → ACP_MODE = "spawn". Done.

Error or no reply within 30s → kill session, go to Step 2.

Step 2: Try acpx CLI (timeout: 30s)

# Detect acpx path (OS-dependent)
Windows: %APPDATA%\npm\node_modules\openclaw\extensions\acpx\node_modules\.bin\acpx.cmd
macOS/Linux: $(npm root -g)/openclaw/extensions/acpx/node_modules/.bin/acpx
Use exec with timeout
acpx claude exec "say hello"   # timeout 30s

Got a reply → ACP_MODE = "acpx". Done.

Error, empty output, or stuck beyond 30s → kill process, go to Step 3.

Step 3: No ACP available

ACP_MODE = "direct". Agent executes all coding tasks directly with read/write/edit/exec. Load team standards (see Coding Standards below).

Cache the result

Set a session variable (mental note): ACP_MODE = "spawn" | "acpx" | "direct"

Cache lifetime = current session. Each new session re-detects once. Keep the detection note minimal and refresh it whenever the underlying mode stops working.

If a cached mode fails mid-session (e.g. acpx suddenly errors), re-run detection from Step 1.

ACP Agent Policy

Current supported ACP coding agent: claude only.

Do not route coding work to codex or other future agents in the production path yet.

If a request merely mentions ACP or coding-agent execution without naming a different approved agent, default detection and execution guidance to Claude.

If documentation mentions other coding agents, treat them as future possibilities only, not current operating policy.

Code review can still be done by the coordinating OpenClaw agent, but ACP execution guidance in this skill is claude-only.

Rule Priority

Apply rules in this order: 1. Matched skill instructions (this skill wins for coding execution when loaded) 2. Agent role fallback only when the coding skill is not loaded or does not cover the case 3. Team templates / README / generated docs provide boundaries and ownership, not competing execution logic

If the same topic appears in multiple places, follow the highest-priority source above and simplify the lower-priority wording instead of combining conflicting chains.

Context File Lifecycle

Context files exist to preserve continuity across the current code chain, but they must stay tidy.

Store active context files under /.openclaw/

Use a stable name per task chain: context-.md

Reuse the same file for the same chain; do not create a new file every turn

Active context file cap per project: 60

Context-file lifecycle window per project: 100 total files (active + archive). When approaching the limit, prune stale archived files first, then merge or remove low-value active chains only if truly superseded.

When a task is completed, either delete the temporary context file or move it under .openclaw/archive/ if it has durable follow-up value

If a file is stale, ownerless, or superseded by a newer chain, treat it as cleanup/archive candidate

Before creating a new active context file, check whether an existing file for that chain can be reused

Context Naming

Recommended pattern:

/.openclaw/context-.md

task slug should be short, stable, and human-readable

avoid timestamp-only names for active files unless the task truly has no durable identifier

Coding Standards — Two Layers, No Overlap

Layer 1: Project-level (Claude Code owns)

Projects may have their own CLAUDE.md, .cursorrules, docs/ — these are Claude Code's responsibility. It reads them automatically. Do NOT paste project-level rules into ACP prompts.

Layer 2: Team-level (OpenClaw owns)

shared/knowledge/tech-standards.md — cross-project standards (security, change control, tech stack preferences). Only relevant for direct execution (simple tasks without ACP).

When spawning ACP

Don't embed coding standards in the prompt — Claude Code has its own CLAUDE.md

Do include: task description, acceptance criteria, relevant context (file paths, decisions)

Do include task-specific constraints if any (e.g., "don't change the API contract")

When executing directly (no ACP)

Load standards once per session, first match wins: 1. shared/knowledge/tech-standards.md (team-level, if exists) 2. Built-in defaults (below, if nothing exists)

Built-in Defaults (fallback for direct execution)

KISS + SOLID + DRY, research before modifying

Methods <200 lines, follow existing architecture

No hardcoded secrets, minimal change scope, clear commits

DB changes via SQL scripts, new tech requires confirmation

Simple Tasks

1. Read target file(s) (standards already loaded per above) 2. [memory] Recall related decisions 3. Execute with read/write/edit/exec 4. [memory] Record what changed and why

Medium/Complex Tasks

Step 1: Build Context File

Write to /.openclaw/context-.md (ACP reads from disk, not from prompt):

# [qmd] or grep: find relevant code
[memory] recall + lessons: find past decisions
Standards already loaded (see "Coding Standards Loading" above)
Write context file with 3-5 key rules from loaded standards — do NOT paste full file

Minimal context file structure:

# Task Context: 
Project — path, stack, architecture style
Relevant Code — file paths + brief descriptions from qmd/grep
History — past decisions/lessons from memory (if any)
Long-term Knowledge Boundary — durable facts or decisions worth preserving outside this file; if none, say "none"
Constraints — task-specific rules only (NOT general coding standards — Claude Code has CLAUDE.md)

Full template with examples → see references/prompt-templates.md

Step 2: Lean Prompt

Use the smallest prompt that still preserves correctness. Start with the task and acceptance criteria. Add only the minimum extra header needed for the run to be unambiguous.

Project:  | Stack: 
Context file: .openclaw/context-.md (read it first if it exists)
Task
Acceptance Criteria
[ ] 
[ ] Tests pass, no unrelated changes, clean code
Before finishing: run linter + tests, include results.
When done: openclaw system event --text "Done: 
" --mode now

Step 3: Spawn (use detected ACP_MODE)

# ACP_MODE = "spawn", medium task:
sessions_spawn(runtime: "acp", agentId: "claude", task: , cwd: , mode: "run")
Complex task primary path:
Use the existing implementation session + context file + serial follow-ups.
If ACP is helpful, prefer bounded Claude run invocations or direct acpx commands inside the project directory.
ACP_MODE = "acpx":
exec: cd  && acpx claude exec ""
ACP_MODE = "direct":
Skip spawn, execute directly with read/write/edit/exec

run vs sustained execution

run: one-shot, bounded Claude ACP coding task

sustained execution: for repeated follow-up on the same code chain, keep working in the existing implementation conversation/session and persist context on disk; do not rely on IM-bound ACP thread/session support

direct fallback: when ACP is unavailable or unstable, execute directly with read/write/edit/exec instead of stalling

Step 4: Fallback Detection

| Condition | Action | |-----------|--------| | Spawn failed / timeout | → Direct execution | | Empty output / no file changes | → Direct execution | | Partial completion | → Agent fixes remaining |

Fallback: [memory] log failure → agent executes directly → report to user.

Never silently fail. Always complete or report why not.

Step 5: Verify & Record

1. Check acceptance criteria + run tests 2. Verify the final result against the task, acceptance criteria, and any explicit no-go constraints before declaring done 3. [memory] Record: what changed, decisions, lessons; only promote durable facts to long-term memory 4. Clean up context file

Complex Tasks

Read references/complex-tasks.md only for Complex-level tasks — roles, QA isolation, parallel strategies, RESEARCH→PLAN→EXECUTE→REVIEW flow.

Context Reuse (Token Savings)

Context file on disk instead of prompt embedding → major token savings per spawn

Simple tasks stay direct: don't pay ACP/session overhead for tiny edits

Medium tasks use run: cheaper than opening a persistent session

Complex tasks use sustained session continuity: preserve continuity through the existing implementation session plus context files

Serial follow-ups: continue in the same implementation conversation and refresh the on-disk context file as the task evolves

[qmd]: precision search → only relevant snippets in context file

No standards in ACP prompts: Claude Code reads its own CLAUDE.md/.cursorrules — don't duplicate

ACP prompt stays lean: task + acceptance criteria + context file path. No generic rules

Direct execution: load team standards once per session, not per task

Memory Integration

[memory] Before: recall related work + lessons for context file. [memory] After: record what changed, decisions made, lessons learned. Cross-session: agent remembers across sessions; Claude Code doesn't. This is the core advantage.

Parallel Execution Boundaries

Parallelism is allowed in the current production path, but only with explicit boundaries.

Hard cap: 5 concurrent work units total

Active context files per project must stay <= 60

Total context files per project should stay <= 100 across active + archive

Define boundaries first: by project, by module, by task stage, or by owner

Never let two work units modify the same code chain, same file cluster, or same acceptance scope

Parallel work must have a merge owner and an acceptance owner before execution starts

If boundaries are fuzzy, collapse back to sequential execution

Recommended shape:

1 coordinating implementation session

up to 4 additional bounded work units (Claude ACP run, direct acpx, or direct execution)

Good parallel cases:

independent products

different modules with separate files and acceptance criteria

one bounded Claude ACP run while direct tasks proceed elsewhere

Bad parallel cases:

same bug chain

same module with shared intermediate state

duplicate research on the same problem

implementation and delivery work both editing the same area

See references/prompt-templates.md for multi-project examples.

Smart Retry (max 3)

1. Analyze failure → 2. Adjust prompt → 3. Retry improved → 4. Max 3 then fallback/report. Each retry must be meaningfully different.

Progress Updates

Start → 1 short message. Error → immediate report. Completion → summary. Fallback → explain.

Safety

Never spawn in ~/.openclaw/ — coding agents may damage config

Always inspect and confirm the intended working directory before spawning or writing; then set cwd explicitly to the project directory

Review before commit — especially complex tasks

Kill runaway sessions — timeout or nonsensical output

See Also

references/complex-tasks.md — roles, QA, parallel (Complex only)

references/prompt-templates.md — context file template, prompt examples