PerkOS AI

Create Task

Create a task on a project's job board and optionally assign it to a worker agent by name. PM/orchestrator use this to break a goal into assigned tasks. Returns the new taskId.

Update Task Status

Move a task to a new column and optionally record its result. Workers use this to mark their task In progress / Done with the deliverable.

List Project Tasks

List the tasks on a project's job board (id, name, status, assigned agent, prompt, result). Use to see the board before creating or picking up work.

Post Project Message

Post a message to the project chat / team (e.g. a PM summary or a worker status update). Visible to all project participants.

List Docs

List a project's docs (the docs workspace tree): each doc's id, type (note|plan|spec), title, status, draft flag, parentId. Use to find a doc to read or edit, or before creating a new one.

Create Doc

Create a new doc in the project's docs workspace (type: note | plan | spec). Your new doc lands in the 'PM Drafts' section until a human promotes it. Returns the new docId — use it with readDoc / upsertPlanGroup / upsertPlanTask / postDocMessage.

Read Doc

Read a project doc + its blocks in order (note blocks written by humans, plus planGroup/planTask blocks). Reads the active plan doc when docId is omitted. Read a doc before proposing or editing structure so you build on the human discussion.

Upsert Plan Group

Create or update a task group (sprint section) in a doc. Group related work before adding planTasks. Targets the active plan doc unless docId is given. Omit groupId to create a new group; pass it to rename/reorder. Returns the groupId for upsertPlanTask.

Upsert Plan Task

Create or update a DRAFT task in a doc — a proposal, not a board task (it only becomes real when a human approves the plan). Decompose the goal into draft tasks under a group, with a suggestedAgent and acceptance criteria. Targets the active plan doc unless docId is given. Omit taskId to create; pass it to update.

Propose Plan

Mark a plan doc as proposed (ready for human approval) and notify the team in that doc's discussion. Call once the task groups and draft tasks are laid out. The plan becomes real board tasks only after a human approves it in the app. Targets the active plan doc unless docId is given.

Post Doc Message

Post a message into a specific doc's discussion (NOT the project-wide chat). Use this to explain doc edits you made and answer questions about that doc. When you change structure (groups/tasks), post here so humans have a narrative trail.