coding-lead

# 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) ```bash # 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): ```bash # [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: ```markdown # 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](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](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](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](references/complex-tasks.md) — roles, QA, parallel (Complex only) - [references/prompt-templates.md](references/prompt-templates.md) — context file template, prompt examples