---
name: yak-tasks
description: Orchestrate sub-agents using yx task tracking. Use when delegating work to sub-agents, tracking task progress, or marking tasks complete. For breaking down problems into tasks, use /skill:problem-breakdown first.
---

# Yak Task Orchestration

Coordinate sub-agent work using the `yx` CLI. The main agent creates tasks and delegates to sub-agents; sub-agents execute domain work without yx CLI access.

## Workflow

1. **Break down** → `/skill:problem-breakdown` (creates yaks with context)
2. **Delegate** → sub-agents run on yaks via `pi -p` (blocked from yx CLI)
3. **Track** → `yx list` / `yx show <task-id>`
4. **Verify** → run `npm run checks` after sub-agent work
5. **Complete** → `yx done <task-id>`

## Running Sub-Agents

Sub-agents execute in print mode and are **hard-blocked from using `yx` commands** (see `.pi/extensions/yak-mode-gate.ts`). They receive:

- The yak's `.context.md` (task description)
- `AGENTS.md` (project conventions)
- Domain files to work on
- No yx CLI access

```bash
# Run a sub-agent on a specific yak
# The sub-agent reads the yak context and executes the work
pi -p "Work on yak: <task-name>. Read .yaks/<task-id>/.context.md for details."
```

## Tracking Progress

```bash
# List all yaks with hierarchy
yx list

# Show yak details
yx show <task-id>

# Check state directly
cat .yaks/<task-id>/.state
```

States:

- `pending` — not yet started
- `in-progress` — being worked on
- `done` — completed

## Marking Tasks Complete

```bash
yx done <task-id>
```

Always verify before marking done:

```bash
# 1. Check state
cat .yaks/<task-id>/.state

# 2. Review what was done
cat .yaks/<task-id>/.context.md

# 3. Run project checks
npm run checks
```

## Sub-Agent Communication

Sub-agents can read yak state files directly (no yx CLI needed):

```bash
cat .yaks/<task-id>/.name    # task name
cat .yaks/<task-id>/.state   # current state
cat .yaks/<task-id>/.context.md  # task description
cat .yaks/<task-id>/.created.json  # creation metadata
```

## Best Practices

- **Delegate after breakdown** — run `/skill:problem-breakdown` first to create structured yaks
- **Verify before marking done** — always run `npm run checks` to catch sub-agent errors
- **Review context** — read `.context.md` to understand what the sub-agent was supposed to do
- **Keep yaks focused** — each yak should be a single file operation or one method implementation
- **Use hierarchy** — parent yaks block children; fix leaves first