# Paia Workboard

> Use when working with the user's PAIA workboard, paia-work tasks, Workgraph-backed personal task boards, agent task handoff, task status, task creation, claiming, completion, comments, or planning work from the PAIA board.

- **Type:** Skill
- **Install:** `agentstack add skill-dbmcco-claude-agent-toolkit-paia-workboard`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [dbmcco](https://agentstack.voostack.com/s/dbmcco)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [dbmcco](https://github.com/dbmcco)
- **Source:** https://github.com/dbmcco/claude-agent-toolkit/tree/main/skills/paia-workboard

## Install

```sh
agentstack add skill-dbmcco-claude-agent-toolkit-paia-workboard
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# PAIA Workboard

## Overview

Use `paia-work` as the canonical PAIA workboard service. It is a FastAPI HTTP/WS facade over Workgraph, backed by `paia-work/.workgraph/graph.jsonl` and the `wg` CLI.

Default paths can be configured with environment variables:

- Repo: `${PAIA_WORK_ROOT:-/paia-work}`
- API: `${PAIA_WORKBOARD_URL:-http://127.0.0.1:3560}`
- Workgraph: `${PAIA_WORK_ROOT:-/paia-work}/.workgraph`
- CLI: `cd "$PAIA_WORK_ROOT" && uv run workboard ...`

## New Session Startup

When the user starts a fresh agent session and asks to work with the PAIA Workboard,
the agent should treat this skill as the operating manual and start from the
Workboard control plane.

Good trigger phrases include:

- "work with me on my PAIA Workboard"
- "review my Workboard"
- "triage the board"
- "take over something from the board"
- "what can an agent run from my Workboard?"

Default startup flow:

```bash
cd /paia-work
uv run workboard list --agent-runnable --limit 20
uv run workboard waiting --limit 20
uv run workboard sessions
```

Then summarize:

- active focus items
- waiting/watch items that should not consume user attention
- agent-runnable tasks
- active agent/tmux sessions
- any task that is blocked, stale, or needs human input

Ask what to start only when the board does not make the next step obvious.

## First Checks

Before changing board state:

1. Check the Workboard CLI:
   ```bash
   cd /paia-work
   uv run workboard list --limit 5
   ```
2. Check service health if the CLI cannot reach the API:
   ```bash
   curl -sS http://127.0.0.1:3560/api/status
   ```
3. Check Workgraph orientation only when falling back below the Workboard API:
   ```bash
   cd /paia-work && wg quickstart
   ```

If the API is down but the repo exists, use:

```bash
wg --dir /paia-work/.workgraph list
wg --dir /paia-work/.workgraph ready
wg --dir /paia-work/.workgraph show 
```

## Working With the User

When the user asks to work from the board:

- Start by listing relevant open/ready tasks and summarize the smallest useful set.
- Ask which task to start only when the board does not make the next task obvious.
- Prefer explicit task IDs in conversation and logs.
- Before marking work done, record what changed and any verification result.
- Create follow-up tasks for real remaining work rather than burying TODOs in chat.

## Workboard CLI Operations

Use the `workboard` CLI first for normal task and agent-session operations.
This applies to Codex, Claude/OpenCode, PAIA agents, Sam-style agents, and any
other local agent that needs to read or mutate Workboard state. Agents should
call `workboard` before writing custom curl/JQ glue.

```bash
cd /paia-work

uv run workboard list --agent-runnable
uv run workboard list --board focus --activity active-collab
uv run workboard show 
uv run workboard waiting
uv run workboard deps 
uv run workboard watch 
uv run workboard claim  --agent codex
uv run workboard tag  --add activity:active-agent --remove activity:ready-delegate
uv run workboard log  "Progress note"
uv run workboard artifact  /path/to/report.md --summary "What changed"
uv run workboard done  --agent codex
uv run workboard fail  "Reason"
uv run workboard sessions
```

Use list filters instead of ad hoc `curl | jq` for common board questions:

```bash
uv run workboard list --board focus
uv run workboard list --activity waiting
uv run workboard list --mode agent-solo
uv run workboard list --cluster paia-control-plane
uv run workboard list --tag triage:codex-ready
```

To hand a task to a new tmux-backed Codex agent:

```bash
uv run workboard run  \
  --agent codex \
  --tmux per \
  --window  \
  --cwd 
```

This should claim the task, log the handoff, create a tmux window, start the
agent command, send the Workboard task prompt, and log the tmux target back to
the task.

If `workboard` lacks a needed operation, fall back to the HTTP API. If the API
is unavailable, fall back to `wg` for direct Workgraph inspection only.

## HTTP Operations

Use HTTP for board CRUD when the Workboard CLI does not expose the operation yet.

List tasks:

```bash
curl -sS 'http://127.0.0.1:3560/api/tasks'
curl -sS 'http://127.0.0.1:3560/api/tasks?status=open'
curl -sS 'http://127.0.0.1:3560/api/tasks?assigned_agent_id=codex'
curl -sS 'http://127.0.0.1:3560/api/tasks/ready'
```

Show one task:

```bash
curl -sS 'http://127.0.0.1:3560/api/tasks/'
```

Create a task:

```bash
curl -sS -X POST 'http://127.0.0.1:3560/api/tasks' \
  -H 'Content-Type: application/json' \
  -d '{"title":"Task title","description":"Context and acceptance criteria","tags":["board:paia"],"assigned_agent_id":"codex"}'
```

Update a task:

```bash
curl -sS -X PATCH 'http://127.0.0.1:3560/api/tasks/' \
  -H 'Content-Type: application/json' \
  -d '{"description":"Updated context","add_tag":["needs-review"]}'
```

Claim, log, comment, complete, fail, or unclaim:

```bash
curl -sS -X POST 'http://127.0.0.1:3560/api/tasks//claim' \
  -H 'Content-Type: application/json' -d '{"actor":"codex"}'

curl -sS -X POST 'http://127.0.0.1:3560/api/tasks//log' \
  -H 'Content-Type: application/json' -d '{"message":"Progress note"}'

curl -sS -X POST 'http://127.0.0.1:3560/api/tasks//comments' \
  -H 'Content-Type: application/json' -d '{"author":"codex","body":"Comment body","actor_type":"agent"}'

curl -sS -X POST 'http://127.0.0.1:3560/api/tasks//done' \
  -H 'Content-Type: application/json' -d '{"actor":"codex"}'

curl -sS -X POST 'http://127.0.0.1:3560/api/tasks//fail' \
  -H 'Content-Type: application/json' -d '{"reason":"Why it failed"}'

curl -sS -X POST 'http://127.0.0.1:3560/api/tasks//unclaim'
```

## CLI Operations

Use `wg` directly for dependency graph inspection, coordinator status, and fallback state management:

```bash
cd /paia-work
wg service status
wg list
wg ready
wg show 
wg viz
wg agents
```

When the coordinator service is running, define work and monitor it; avoid manual `wg claim` or `wg spawn` unless the user explicitly wants manual execution.

For manual mode:

```bash
wg claim 
wg log  "Progress note"
wg done 
wg fail  --reason "Reason"
wg unclaim 
```

## Task Creation Guidance

Good workboard tasks include:

- Clear title with the expected outcome.
- Description with context, constraints, and links/files.
- Validation section for code work.
- Dependencies via `blocked_by` in HTTP or `--after` in CLI.
- Tags such as `board:paia`, product area, urgency, or review state.

HTTP dependency example:

```bash
curl -sS -X POST 'http://127.0.0.1:3560/api/tasks' \
  -H 'Content-Type: application/json' \
  -d '{"title":"Follow-up task","description":"Do this after prerequisite completes","blocked_by":["prereq-task-id"],"tags":["board:paia"]}'
```

CLI dependency example:

```bash
cd /paia-work
wg add "Follow-up task" -d "Context and validation" --after prereq-task-id
```

## Safety

- Treat the workboard as shared state; inspect before mutating.
- Do not delete or abandon tasks unless the user asks or the task is clearly a duplicate/error.
- Do not use unrelated task systems for PAIA workboard state.
- If code changes are made while working a board task, follow the target repo's local `AGENTS.md` and validation instructions.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [dbmcco](https://github.com/dbmcco)
- **Source:** [dbmcco/claude-agent-toolkit](https://github.com/dbmcco/claude-agent-toolkit)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-dbmcco-claude-agent-toolkit-paia-workboard
- Seller: https://agentstack.voostack.com/s/dbmcco
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.