Tasks

Create a Task

curl -s -X POST http://127.0.0.1:18789/api/tasks \
  -H "Authorization: Bearer 341c3e8015df9c77f6ed4cba1359403135994364caf7c668" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Task title here",
    "agent": "programmer",
    "notes": "## Problem\n...\n\n## Acceptance Criteria\n- [ ] ...",
    "workState": "queued"
  }'

Minimum required: title only. Add agent, notes, and workState for complete tasks.

List Tasks

# All active tasks
curl -s http://127.0.0.1:18789/api/tasks \
  -H "Authorization: Bearer 341c3e8015df9c77f6ed4cba1359403135994364caf7c668"

# Filter by status or workState
curl -s "http://127.0.0.1:18789/api/tasks?status=active&workState=queued" \
  -H "Authorization: Bearer 341c3e8015df9c77f6ed4cba1359403135994364caf7c668"

# Filter by agent
curl -s "http://127.0.0.1:18789/api/tasks?agent=programmer" \
  -H "Authorization: Bearer 341c3e8015df9c77f6ed4cba1359403135994364caf7c668"

Filter query params: status, workState, agent, projectId

Update a Task

curl -s -X PATCH http://127.0.0.1:18789/api/tasks/<task-id> \
  -H "Authorization: Bearer 341c3e8015df9c77f6ed4cba1359403135994364caf7c668" \
  -H "Content-Type: application/json" \
  -d '{"workState": "done", "notes": "Updated notes here"}'

Only send fields you want to change. All other fields are preserved.

Close / Cancel a Task

To mark done:

curl -s -X PATCH http://127.0.0.1:18789/api/tasks/<task-id> \
  -H "Authorization: Bearer 341c3e8015df9c77f6ed4cba1359403135994364caf7c668" \
  -H "Content-Type: application/json" \
  -d '{"workState": "done"}'

To cancel:

curl -s -X PATCH http://127.0.0.1:18789/api/tasks/<task-id> \
  -H "Authorization: Bearer 341c3e8015df9c77f6ed4cba1359403135994364caf7c668" \
  -H "Content-Type: application/json" \
  -d '{"status": "cancelled"}'

To hard-delete:

curl -s -X DELETE http://127.0.0.1:18789/api/tasks/<task-id> \
  -H "Authorization: Bearer 341c3e8015df9c77f6ed4cba1359403135994364caf7c668"

Prefer status: cancelled or workState: done over hard-delete. Delete only for test/junk tasks.

Get a Single Task

curl -s http://127.0.0.1:18789/api/tasks/<task-id> \
  -H "Authorization: Bearer 341c3e8015df9c77f6ed4cba1359403135994364caf7c668"

Block a Task on Another

curl -s -X PATCH http://127.0.0.1:18789/api/tasks/<task-id> \
  -H "Authorization: Bearer 341c3e8015df9c77f6ed4cba1359403135994364caf7c668" \
  -H "Content-Type: application/json" \
  -d '{"blockedBy": "<blocking-task-id>", "workState": "blocked"}'

Task Notes Format

Use structured markdown in notes for well-formed tasks:

## Problem
Brief description of what needs to be solved.

## Acceptance Criteria
- [ ] Criterion one
- [ ] Criterion two

## Context
Any relevant background, constraints, or links.

Workflow

1. Read before write — always GET task before PATCHing if you're not sure of current state.
2. Verify after mutation — re-fetch to confirm the change landed.
3. Don't duplicate — search existing tasks before creating new ones.
4. Close what's done — set workState: done when acceptance criteria are met.
5. Use notes for context — never put important detail only in chat; write it to notes.

Error Handling

User Commands This Skill Handles

• "create a task to..." → POST /api/tasks with structured notes
• "list my tasks" / "what tasks are active" → GET /api/tasks
• "mark task X as done" → PATCH workState: done
• "update task notes" → PATCH notes
• "cancel task X" → PATCH status: cancelled
• "show task X" → GET /api/tasks/:id
• "block task X on task Y" → PATCH blockedBy + workState: blocked