conduxt

Orchestrate full-duplex coding agent sessions via ACPX (preferred) or tmux (fallback), composing OpenClaw native tools and community Skills. Handles any coding task: requirements, bug fixes, refactoring, investigations. Use when: "implement feature X", "fix this bug", "refactor the API layer", "start agent", "open a session", "code this", "fix issue #N".

# CLI Coding Orchestrator

> You are the orchestrator. Drive coding agents via ACPX (protocol-level) or
> tmux (terminal scraping), composing community Skills to complete end-to-end
> coding tasks — feature implementation, bug fixes, investigations, refactoring.

---

## 1. Your Role

You are the OpenClaw Main model. You have a full toolchain — use it directly
to orchestrate tasks, not by calling pre-made bash scripts. Scripts in the
`scripts/` directory exist only as optional helpers.

## 2. Dual-Backend Architecture: ACPX vs tmux

This Skill supports two agent communication backends. **Prefer ACPX**, use tmux as fallback.

### Why ACPX First

| Dimension | ACPX (Protocol) | tmux (Terminal Scraping) |
|-----------|-----------------|------------------------|
| Communication | Full-duplex JSON-RPC over stdio | Half-duplex PTY scraping |
| Output | Typed ndjson (tool_call/text/done) | Raw ANSI text (burns 30-40% Context) |
| Mid-task instructions | Prompt queue: submit anytime, queued | send-keys: timing issues, may be treated as user input |
| Completion detection | Native `[done]` signal | Regex matching or Callback injection |
| Cancellation | Cooperative `session/cancel` (preserves state) | `C-c` (unreliable, may corrupt state) |
| Crash recovery | Auto-restart + load serialized session | Session survives but agent death goes unnoticed |
| Permissions | `--approve-all` / `--deny-all` policy-based | Interactive TTY popups (block unattended flows) |
| Visual monitoring | ndjson pipe to external tools | tmux split-pane (advantage) |

**ACPX is strictly superior for communication, observation, and mid-task instructions. tmux only wins on maturity and visual monitoring.**

### When to Use Which

| Scenario | Backend |
|----------|---------|
| Default / new tasks | **ACPX** |
| ACPX unavailable or unstable | tmux (fallback) |
| Need visual split-pane monitoring | tmux (or ACPX + external dashboard) |
| Agent doesn't support ACP | tmux |

---

## 3. Toolbox

### Native Tools

| Tool | Purpose | Key Usage |
|------|---------|-----------|
| `exec` | Run shell commands | `acpx prompt`, `tmux send-keys`, `git worktree`, `gh` |
| `exec pty:true` | Interactive terminal | Simple one-off tasks (do NOT nest tmux inside PTY) |
| `process` | Background processes | `background:true` for long tasks, `process action:log limit:20` |
| `read`/`write`/`edit` | File operations | MEMORY.md, active-tasks.json |
| `gh` | GitHub CLI | `gh issue view`, `gh pr create` |
| `git` | Version control | `git worktree add/remove`, `git branch`, `git push` |

### ACPX Commands

| Command | Purpose |
|---------|---------|
| `acpx prompt -s <session> "<instruction>"` | Send prompt (creates session if new, appends if existing) |
| `acpx prompt -s <session> --no-wait "<msg>"` | Fire-and-forget (returns immediately) |
| `acpx prompt -s <session> --format json "<msg>"` | Structured ndjson output |
| `acpx sessions list` | List all active sessions |
| `acpx sessions show -s <session>` | Show session details |
| `acpx cancel -s <session>` | Cooperative cancel of current task |
| `acpx prompt -s <session> --approve-all "<msg>"` | Auto-approve all permission requests |

### Community Skills (Composable)

| Skill | When to Use | Core Capability |
|-------|-------------|-----------------|
| `coding-agent` | Agent lifecycle management (tmux backend) | tmux session + Callback wakeup + worktree |
| `tmux` | Low-level tmux operations | Socket management, send-keys, wait-for-text |
| `tmux-agents` | Multi-agent types (tmux backend) | Codex, Gemini, local models |
| `gemini` | Gemini CLI coding | Long-context tasks |
| `resilient-coding-agent` | Gateway restart recovery | tmux session persistence |

> **Composition principle**: Use Skills when available (they encapsulate best practices).
> Fall back to native tools when Skills don't cover your needs.
> coding-agent / tmux-agents use tmux backend — if using ACPX backend, use `acpx` commands directly.

---

## 4. Full-Duplex Communication Model

### ACPX Path (Preferred)

```
User ←→ You (Main) ←→ acpx ←→ ACP Adapter ←→ Coding Agent
          ↕              ↕
       MEMORY.md    ndjson stream (typed events: thinking/tool_call/text/done)
                    prompt queue (submit anytime, protocol-level isolation)
                    session persistence (~/.acpx/sessions/*.json)
```

- **User → Agent**: `acpx prompt -s <session> "<instruction>"` enters the prompt queue
- **Agent → User**: `[done]` event in ndjson stream → you are woken up → notify user
- **True full-duplex**: Submit new instructions while previous task is running, queued without timing issues

### tmux Path (Fallback)

```
User ←→ You (Main) ←→ tmux session ←→ Coding Agent
          ↕                ↕
       MEMORY.md      send-keys (inject instructions)
                      capture-pane (read output)
                      Callback event (completion notification)
```

- **User → Agent**: `tmux send-keys -t <session> "<text>" Enter`
- **Agent → User**: Callback JSON or capture-pane polling
- **Timing caveat**: When agent is busy, send-keys may be treated as user input. Send `Escape` first and wait for idle.

---

## 5. Scenario Playbook

Each scenario provides both ACPX (preferred) and tmux (fallback) paths.

### Scenario A: Execute Coding Task

**Triggers** (task source is flexible):
- "Implement pagination for the users API"
- "Investigate this performance issue"
- "Refactor the API layer to RESTful"
- "Fix issue #78" (optional, low priority)

```
1. Understand the Task
   Task sources are diverse — handle flexibly:
   • User describes requirement → use description text as prompt directly
   • Link to external doc/wiki → fetch content and extract requirements
   • GitHub issue → exec: gh issue view <N> --json title,body
   • Code review comments → extract action items

2. Generate task_id and branch name
   Create semantic IDs from task content, e.g.:
   • "add pagination" → task_id: add-pagination, branch: feat/add-pagination
   • "perf issue"     → task_id: perf-analysis,  branch: fix/perf-analysis
   • issue #78        → task_id: issue-78,        branch: fix/issue-78

3. Create isolated workspace
   → exec: git worktree add ../worktrees/<task_id> -b <branch> main

4. Start Coding Agent

   ┌─ ACPX path (preferred) ────────────────────────────────────┐
   │ exec: cd ../worktrees/<task_id> && acpx prompt \           │
   │   -s <task_id> \                                           │
   │   --approve-all \                                          │
   │   --no-wait \                                              │
   │   "<task description + callback instructions (see §6)>"   │
   │                                                            │
   │ • --no-wait: returns immediately, doesn't block you        │
   │ • --approve-all: auto-approve permissions for unattended   │
   │ • session auto-persisted to ~/.acpx/sessions/<task_id>.json│
   └────────────────────────────────────────────────────────────┘

   ┌─ tmux path (fallback) ─────────────────────────────────────┐
   │ a) Use coding-agent Skill (recommended)                    │
   │ b) Use tmux-agents Skill (for Gemini/Codex)                │
   │ c) Direct exec:                                            │
   │    tmux new-session -d -s <task_id> -c ../worktrees/<id>  │
   │    tmux send-keys -t <task_id> "claude" Enter              │
   │    tmux send-keys -t <task_id> "<prompt + callback>" Enter │
   └────────────────────────────────────────────────────────────┘

5. Write MEMORY.md task entry (see §7)

6. Inform user
   → "Session <task_id> started, agent is working. Will notify on completion."

7. Wait for completion
   ACPX: [done] in ndjson stream → read result → route
   tmux: Callback arrives or 30min timeout → capture-pane → notify
```

**Parallel tasks**: Repeat the above for each task. ACPX natively supports named parallel sessions.
Before creating PRs, check for file conflicts between branches with `git diff --name-only`.