Coding Lead

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