pi-config/skills/project-ops/SKILL.md

name, description, compatibility

name	description	compatibility
project-ops	Access project tasks, stages and progress via Vikunja, and project documentation via Outline. Use for reading/creating/updating tasks, moving tasks between buckets (kanban stages), tracking percent done, and reading/writing docs on the home lab.	all pi-agents (sam-4screen-desktop .27, nixos-desktop .13, ubuntu1 .35, machine .51)

Project Ops — Vikunja (tasks/stages/progress) + Outline (documentation)

The home-lab's project layer for any pi agent. Vikunja = tasks, kanban stages/buckets, percent-done progress. Outline = project documentation. These are shared across all four machines; keys are in the environment secrets.

1. Secrets (bearer tokens)

Keys are stored in the machine's secrets file. Read them at runtime, never print them:

• Vikunja token: VIKUNJA_TOKEN in ~/.config/environment.d/10-secrets.conf
• Outline key: OL_API_KEY in ~/.config/environment.d/10-secrets.conf

VIKUNJA_TOKEN=$(grep "^VIKUNJA_TOKEN=" ~/.config/environment.d/10-secrets.conf | head -1 | cut -d= -f2- | tr -d '"' | tr -d ' ')
OL_API_KEY=$(grep "^OL_API_KEY=" ~/.config/environment.d/10-secrets.conf | head -1 | cut -d= -f2- | tr -d '"' | tr -d ' ')

If token 401s: Vikunja sometimes intermittently rejects a valid token (transient; observed on LAN). First retry once — the same call returning 401 then 200 with an identical token is a known flake, not a wrong value. Only if a retry still 401s: re-source the secrets (new shell/login) so the fresh value is read; if still failing, ask the user to confirm the token was regenerated in Vikunja and re-placed. Outline keys are stable (401 there = genuinely wrong key). Never commit or echo the token values.

2. Vikunja API (tasks, stages, progress)

Base: https://vikunja.lab.audasmedia.com.au/api/v1 Auth header: Authorization: Bearer $VIKUNJA_TOKEN (plus Content-Type: application/json on writes).

Read

# all projects
curl -s "$BASE/projects?page=1&per_page=100" -H "Authorization: Bearer $VIKUNJA_TOKEN"

# tasks in a project (project_id from above)
curl -s "$BASE/projects/<project_id>/tasks?page=1&per_page=100" -H "Authorization: Bearer $VIKUNJA_TOKEN"

# a single task (shows bucket_id, percent_done, due_date)
curl -s "$BASE/tasks/<task_id>" -H "Authorization: Bearer $VIKUNJA_TOKEN"

Create a task

curl -s -X PUT "$BASE/projects/<project_id>/tasks" -H "Authorization: Bearer $VIKUNJA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"new task","project_id":<project_id>}'

Update task — stage / progress / done

# move task to a kanban bucket ("stage"). Find bucket ids first:
curl -s "$BASE/projects/<project_id>/buckets" -H "Authorization: Bearer $VIKUNJA_TOKEN"
# then update the task; POST /tasks/<id> with any of: bucket_id, percent_done, done, due_date, priority
curl -s -X POST "$BASE/tasks/<task_id>" -H "Authorization: Bearer $VIKUNJA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"bucket_id":<bucket_id>,"percent_done":50}'
# mark done
curl -s -X POST "$BASE/tasks/<task_id>" -H "Authorization: Bearer $VIKUNJA_TOKEN" \
  -H "Content-Type: application/json" -d '{"done":true}'

3. Outline API (documentation)

Base: https://outline.lab.audasmedia.com.au/api Same bearer pattern (Authorization: Bearer $OL_API_KEY, Content-Type: application/json). Endpoints are POST.

# collections (top-level doc groups)
curl -s -X POST "$OL_BASE/collections.list" -H "Authorization: Bearer $OL_API_KEY" \
  -H "Content-Type: application/json" -d '{"limit":50}'

# documents in a collection
curl -s -X POST "$OL_BASE/documents.list" -H "Authorization: Bearer $OL_API_KEY" \
  -H "Content-Type: application/json" -d '{"collectionId":"<id>","limit":50}'

# search docs
curl -s -X POST "$OL_BASE/documents.search" -H "Authorization: Bearer $OL_API_KEY" \
  -H "Content-Type: application/json" -d '{"query":"<search terms>","limit":10}'

4. Guidance

• When a user asks about a project's tasks/progress: use Vikunja. When they want the "what/why/how" documentation: use Outline.
• Keep payloads minimal; fetch then update (don't guess ids). Always confirm the write succeeded and report the outcome concisely (task moved to stage X / created id Y / doc found Z).
• This skill has full scope (create/update/move/delete + docs read/write unless stated otherwise).
• Works on all lab machines; records are shared, so changes appear everywhere.