agents-collab

Files (3)

• SKILL.md
• SKILL.zh-CN.md
• troubleshooting.md · references/

SKILL.md (first lines)

# agents-collab — Sub-agent collaboration basics

This skill defines **how** Wopal should collaborate with sub-agents at the tool level. **When** to delegate, and which workflow-specific instructions must appear in the prompt (such as Plan paths or done checkboxes), are decided by higher-level workflow skills such as dev-flow.

---

## Tool priority

Always prefer `wopal_task` for delegation. Use the built-in `task` tool only when `wopal_task` is unavailable.
`wopal_task` provides bidirectional communication, progress monitoring, and non-blocking execution. Using `task` means downgrading execution and giving up those capabilities.

---

## Prompt format

Delegation prompts must be precise and complete so the sub-agent can succeed in one pass. Standard format:

```
Hello <agent>, I am wopal. Because <reason>, please do the following task:

Task: <task description>
Goal: <goal description>

<precise context: absolute paths, file:line anchors, current code, change locations, and boundaries of what must not be changed>
```

**Required location context**:
- If a Plan exists: provide the absolute path to the Plan file
- If a worktree is involved (such as `.wopal/`): explicitly state the worktree root and warn the sub-agent not to edit the wrong location

**Core principle**: give complete, precise context up front so rework is minimized.

### Code review delegation contract, especially for rook

When delegating code review to rook, you must first define the **change carrier**. Without it, rook cannot establish a correct review boundary:

| Scenario | Required prompt fields | How rook should review |
|------|----------------|------------------|
| **Uncommitted changes** | `review_type: implementation`, `project_path`, `change_scope: working_tree`, plus changed file list or an explicit instruction to review `git diff` / `git diff --cached` | Review against the working tree or staged diff using planless diff review |
| **Committed changes** | `review_type: implementation`, `project_path`, `commit: <hash>` or `commit_range: <A>..<B>`, and `background` | Review against the `git diff` for that commit or range; never rely on file paths alone |

Additional rules:

1. **For committed changes, never provide only file names.** Without a commit or range, rook tends to review whole files and loses precise diff context.
2. **Planless code review defaults to technical review.** Explicitly tell rook to focus on bugs, tests, repeated logic, convention violations, and technical debt rather than judging business logic.
3. **If business logic really must be reviewed**, say so explicitly in the prompt, for example: `business_logic_review: requested`. Otherwise rook should place severe logic concerns in a discussion-only section.

---

## Delegation tools

### wopal_task — launch a task

```typescript
wopal_task({
  description: "3-5 words",
  prompt: "<write the prompt using the format above>",
  agent: "fae"       // or "rook", "general", etc. Default: "general"
})
// Returns task_id for later monitoring and communication
```

- Asynchronous and non-blocking; the main session does not wait and can launch multiple tasks
- Concurrency limit: configurable via the wopal plugin; additional tasks queue automatically
- TTL: auto-cleanup after 30 minutes with no interaction

### wopal_task_output — inspect status and output

```typescript
wopal_task_output({ task_id })                              // summary status
wopal_task_output({ task_id, section: "text" })             // text output
wopal_task_output({ task_id, section: "tools" })            // tool calls
wopal_task_output({ task_id, section: "reasoning" })        // reasoning trace
wopal_task_output({ task_id, section: "text", last_n: 3 })  // last 3 text outputs only
```

### wopal_task_reply — communicate, resume, or redirect

Send a message to an idle, waiting, or stuck task to resume execution or correct direction. `error` tasks cannot be resumed; clean them up with `finish` and recreate them. The sub-agent **will wake up**.

```typescript
wopal_task_reply({ task_id, message: "Continue improving test coverage" })
wopal_task_reply({ task_id, message: "Change direction to...", interrupt: true })  // abort current execution + inject message
```

| Task state | Behavior |
|---------|------|
| `waiting` | Send a message and resume execution |
| `idle` | Clear the idle marker, send a message, and resume execution |
| `stuck` | Send a message and try again |
| `error` | Reply is invalid; finish and recreate with valid config |
| `running` | Must use `interrupt=true`, otherwise the message is queued |

**Forbidden**: `wopal_task_reply({ message: "Task complete" })` — this wakes the sub-agent and causes pointless extra work. `IDLE` is already the completion signal. If the output is accepted, end the task with `wopal_task_finish`.

### wopal_task_abort — stop an actively running task

Pure stop: no message, no wake-up. Afterward you can either `finish` the task or `reply` to resume it.

```typescript
wopal_task_abort({ task_id })
```

### wopal_task_finish — terminate a task

Terminate an idle, waiting, stuck, or error task and delete its sub-session. The sub-agent **will not wake up**. Running tasks must be `abort`ed first or redirected with `reply(interrupt=true)`.

```typescript
wopal_task_finish({ task_id })
```

---

## Task lifecycle

### State model

State model: `running | idle | waiting | stuck | error`

From wopal-cn/wopal-space-ontology, MIT.

More from wopal-cn/wopal-space-ontology