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 <project>/.openclaw/
• Use a stable name per task chain: context-<task-slug>.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:

• <project>/.openclaw/context-<task-slug>.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 <project>/.openclaw/context-<task-id>.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: <id>
## 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: <path> | Stack: <e.g. Laravel 10 + React 18 + TS>
Context file: .openclaw/context-<task-id>.md (read it first if it exists)

## Task
<description>

## Acceptance Criteria
- [ ] <criteria>
- [ ] Tests pass, no unrelated changes, clean code

Before finishing: run linter + tests, include results.
When done: openclaw system event --text "Done: <summary>" --mode now

Step 3: Spawn (use detected ACP_MODE)

# ACP_MODE = "spawn", medium task:
sessions_spawn(runtime: "acp", agentId: "claude", task: <prompt>, cwd: <project-dir>, 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 <project-dir> && acpx claude exec "<prompt>"

# 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