Coding Lead

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)

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

Tool Detection & Fallback

All tools are optional. Detect once per session:

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":