Paia Workboard

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:

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 ``

1. Check service health if the CLI cannot reach the API:

``bash curl -sS http://127.0.0.1:3560/api/status ``

1. 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:

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.

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:

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:

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:

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:

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

Create a task:

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:

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:

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:

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:

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:

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:

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
• Source: dbmcco/claude-agent-toolkit
• License: MIT

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