Vaiz

View saved version →

---
name: vaiz-agents
description: Work safely with Vaiz AI agents — recognise agent members (isAgent true), learn what each agent does with list_agents, confirm with the user before assigning or mentioning one, report whether the agent run started, and review past runs.
---

# Vaiz AI agents

A Vaiz space can have AI agents: configured automations that act on their own inside their project/board scope. Each agent is also a member of the space, so it shows up next to people and is assigned or mentioned by its member id. It is not a person: never treat an agent as a teammate who will "pick up" a task.

## Prerequisite

The Vaiz MCP server (`https://api.vaiz.com/mcp`) must be available through the installed Vaiz plugin and authorized with OAuth (open the Vaiz connection and complete OAuth sign-in). Reading agents and runs needs the `agents:read` permission of the connection; starting an agent by assigning or mentioning it needs `agents:write` ("Start AI agents" on the consent screen).

Vaiz tools can appear under different names depending on how Vaiz is connected: `mcp__Vaiz__query_tasks` for a directly configured MCP server, or `mcp__codex_apps__vaiz_query_tasks` (sometimes with a longer app prefix such as `vaiz_testing_`) when Vaiz is installed as an app. Match tool names case-insensitively and by the tool suffix (`query_tasks`, `show_tasks`, …), not by an exact `Vaiz` prefix. Tools may also be loaded lazily: a Vaiz tool that is not in the current tool list is not missing — load it through tool search (for example `Vaiz list_agents`) before concluding it is unavailable. Work with Vaiz only through these tools: do not open app.vaiz.com in a browser or drive the Vaiz desktop app with Computer Use, even if the user's `@Vaiz` mention also resolves to that app.

## Recognising an agent

- Member, task, follower, and comment tools mark agent members with `isAgent: true`. A comment whose author has `isAgent: true` is an agent's reply. History tools add "(AI agent)" to the name instead.
- `list_agents` (optional `projectId`) lists agents with `memberId`, `instructions`, `trigger`, `runsWhen`, `mode`, `writeCapabilities`, `scope`, and `status` / `paused`.
  - `agentsEnabled: false` — agents are off in the space; assigning one does nothing.
  - `status: disabled` — the agent cannot run; `statusReason` says why. Do not assign or mention it.
  - `canStartAgents: false` — the connection lacks `agents:write`; an assignment or mention will not start a run. Tell the user they can reconnect and allow it.
  - `aiCreditsExhausted: true` — no agent can start until credits refresh or are bought; only the space owner can buy them.

## What starts a run

| Action | Effect |
| --- | --- |
| Assign an agent to a task (`create_task` / `edit_task` assignees) | Starts a run on that task |
| Mention an agent in a task comment (`create_comment` / `edit_comment`) | Starts a run that answers in the thread |
| Mention in a milestone or document comment, or inside any body | Nothing runs |
| Add an agent as a follower | Nothing runs |

Only agents with `answersAssignmentsAndMentions: true` react to assignments and mentions. Agents with event triggers can also react to your edits: creating or changing a task, adding a comment, or creating or editing a milestone in their scope (`runsWhen` says when). Board automations never wake agents.

The agent's `mode` decides what happens to its changes: `suggest` only proposes, `ask` waits for a human approval on the run page (comments are posted right away), `auto` applies changes immediately. Every run spends the space's AI credits.

## Rules

1. **Confirm first.** Before assigning or mentioning an agent, tell the user it is an AI agent, what it will do (instructions, mode, write capabilities from `list_agents`), and that it will start a run. Proceed only after the user agrees, unless they explicitly asked for that agent.
2. **No agent as a fallback assignee.** When the user asks to assign "someone" or a role, choose among people. Offer an agent only when its instructions fit, and say it is an agent.
3. **Use the member id** from `list_agents` (the same id as in `query_members`), never `agentId`.
4. **Report the outcome.** `create_task`, `edit_task`, `create_comment`, and `edit_comment` return `agentInvocations` with `runStarted`, `runUrl`, `mode`, or `notStartedReason`. Say plainly whether the agent started and, if not, why. If an invocation carries `buyCreditsUrl`, give the user that link.
5. **Do not wait for the agent.** Point the user to the task, its comments, or `runUrl` instead of polling.
6. **Unassigning stops nothing.** A started run is cancelled only on the run page by a Manager or Owner of the agent's scope.

## Reading what agents did

- `list_agent_runs` — runs newest first, one page at a time (default 20, max 50), filtered by `agentId`, `projectId`, `taskId`, `statuses`, `triggers`, `modes`, or dates. Load the next page with `nextCursor` only when the user needs older runs.
- `get_agent_run` — one run by `runId` or `number`: the agent's report and every proposed or applied action with its decision (`pending` actions wait for approval on the run page).

Reading runs never starts an agent and spends no credits. `create_milestone` and `edit_milestone` do not report the runs they cause; check `list_agent_runs` if the user asks.

Further reading: https://vaiz.com/help/tutorials/how-to-connect-vaiz-to-mcp · https://vaiz.com

View saved version →

---
name: vaiz-automations
description: Build and change Vaiz board automations — turn a "when X, do Y" request into conditions and actions with real ids, edit and publish automation graphs, pause or delete automations, and avoid duplicates and app-only webhook or Slack actions.
---

# Vaiz board automations

An automation belongs to one board: when a task event on that board matches its conditions, its actions run on that task. Only board managers and owners can create, change, or delete automations.

## Prerequisite

The Vaiz MCP server (`https://api.vaiz.com/mcp`) must be available through the installed Vaiz plugin and authorized with OAuth (open the Vaiz connection and complete OAuth sign-in).

Vaiz tools can appear under different names depending on how Vaiz is connected: `mcp__Vaiz__query_tasks` for a directly configured MCP server, or `mcp__codex_apps__vaiz_query_tasks` (sometimes with a longer app prefix such as `vaiz_testing_`) when Vaiz is installed as an app. Match tool names case-insensitively and by the tool suffix (`query_tasks`, `show_tasks`, …), not by an exact `Vaiz` prefix. Tools may also be loaded lazily: a Vaiz tool that is not in the current tool list is not missing — load it through tool search (for example `Vaiz get_automations`) before concluding it is unavailable. Work with Vaiz only through these tools: do not open app.vaiz.com in a browser or drive the Vaiz desktop app with Computer Use, even if the user's `@Vaiz` mention also resolves to that app.

## Before creating

1. `get_automations(boardId)` — an automation for the same trigger may already exist. Extend or re-enable it with `edit_automation` instead of adding a twin.
2. Collect real ids: columns and task types from `get_board`, people from `query_members` (they need access to the board), target boards from `list_boards` (same project only).
3. Say the automation back in plain words — "When a task moves to **Review**, assign **Anna**…" — and create it after the user agrees.

Then call `create_automation` with `boardId`, `title`, `conditions`, `actions`, and optionally `enabled: false` to create it paused.

## Conditions

The automation runs when one of the condition events happens and the task then matches all conditions. 1–10 conditions, each type once.

| Type | Fires when |
| --- | --- |
| `created` | A task is created on the board |
| `comment_added` | A comment is added |
| `complete` / `uncomplete` | A task is completed / reopened (never both in one automation) |
| `archive` | A task is archived |
| `assign` + `memberId` | The member is assigned |
| `group_change` + `groupId` | A task moves into the column |
| `type_change` + `typeId` | The type is added |
| `priority_change` + `priority` | The task gets the priority (`"0"` Low … `"4"` Urgent) |
| `code_change_linked` | A pull request (GitHub) or merge request (GitLab) is linked |
| `code_change_opened` / `code_change_merged` / `code_change_closed` | A linked PR/MR is opened or reopened / merged / closed without merging |

`code_change_*` conditions need GitHub or GitLab connected; branches and commits do not trigger them.

## Actions

Run in order, 1–10, each type once.

| Type | Does |
| --- | --- |
| `complete` | Completes the task |
| `archive` | Archives the task (it leaves the board for everyone — mention it) |
| `assign` + `memberId` | Assigns the member |
| `group_change` + `groupId` | Moves the task to a column of this board |
| `type_change` + `typeId` | Adds the type |
| `move_in_group` + `position` | Reorders it in its column: `top`, `middle`, or `bottom` |
| `duplicate_task` + `boardId` (+ `groupId`) | Copies the task to a board of the same project |

Moving a task to another board is not an automation action. An old `move_to_board` action shown by `get_automations` does nothing any more; offer to replace it with `duplicate_task` or with multihoming (`add_task_to_board`, see `vaiz-tasks`).

## Graph drafts and publication

`get_automations` also returns `draftGraph`, `publishedGraph`, `publishedVersion`, and validation issues. Only the published graph runs.

- Convert a legacy rule into a draft with `edit_automation` and `convertToGraph: true`; conversion does not publish.
- Replace the draft with `draftGraph` (version 1, nodes and edges; trigger, condition, and action nodes). Preserve existing node ids.
- Publish with `publishGraph: true` only when the user asks. Invalid or disconnected graphs cannot be published; saving a draft leaves the published graph running.
- Do not mix graph fields with legacy `conditions` / `actions` in one request. Once a graph is published, edit the graph.

## Changing and removing

- `edit_automation` — omitted fields keep their values; `conditions` and `actions` are replaced as a whole, so send the full list.
- Pause with `enabled: false` rather than deleting. `delete_automation` is permanent (tasks it already changed stay as they are); confirm first.
- Webhook and Slack actions are app-only: they cannot be created over MCP, and in an automation that has them the legacy actions cannot be replaced. Graph edits may keep those nodes only if you copy their returned items unchanged. Webhook values come back masked; never ask the user to paste secrets into the chat.

## Pitfalls

- Changes made by automation actions do not emit further automation events, so automations do not chain.
- Assigning an AI agent in an action does not start it: automations never wake agents. Agent reactions are configured in the agent's own trigger (see `vaiz-agents`).
- Changing a task over MCP runs automations the same way the app does: `edit_task` moving a column fires `group_change`, `set_task_archived` fires `archive`. Expect the extra changes and mention them to the user.

Further reading: https://vaiz.com/help/tutorials/how-to-connect-vaiz-to-mcp · https://vaiz.com

View saved version →

---
name: vaiz-code-links
description: Connect code to work in Vaiz — discover GitHub and GitLab repositories connected to the space, search branches, pull or merge requests, and commits, and link or unlink them on tasks and Space Memory entries so PR/MR state syncs into Vaiz.
---

# Vaiz code links (GitHub and GitLab)

Vaiz can attach branches, pull requests (GitHub), merge requests (GitLab), and commits to a task or to a Space Memory entry. Linked pull and merge requests show up in the Vaiz UI and their state is synced automatically. Linking changes nothing on GitHub or GitLab; it only records the relationship inside Vaiz.

## Prerequisite

The Vaiz MCP server (`https://api.vaiz.com/mcp`) must be available through the installed Vaiz plugin and authorized with OAuth (open the Vaiz connection and complete OAuth sign-in), and the space must have the GitHub or GitLab integration configured by a space admin. Reading needs the `github:read` / `gitlab:read` scope of the connection, linking and unlinking need `github:write` / `gitlab:write`. If `get_code_repositories` returns nothing, the integration is not set up or the scope was not granted — tell the user instead of retrying.

Vaiz tools can appear under different names depending on how Vaiz is connected: `mcp__Vaiz__query_tasks` for a directly configured MCP server, or `mcp__codex_apps__vaiz_query_tasks` (sometimes with a longer app prefix such as `vaiz_testing_`) when Vaiz is installed as an app. Match tool names case-insensitively and by the tool suffix (`query_tasks`, `show_tasks`, …), not by an exact `Vaiz` prefix. Tools may also be loaded lazily: a Vaiz tool that is not in the current tool list is not missing — load it through tool search (for example `Vaiz get_code_repositories`) before concluding it is unavailable. Work with Vaiz only through these tools: do not open app.vaiz.com in a browser or drive the Vaiz desktop app with Computer Use, even if the user's `@Vaiz` mention also resolves to that app.

## Flow

1. `get_code_repositories` — repositories connected to the current space. Use the returned repository key (for example `github.com/acme/api` or `gitlab.acme.com/team/api`) as `repository` in the next steps; a bare `acme/api` works only when exactly one connected repository has that path.
2. `search_code_entities` — search a connected repository for branches, pull/merge requests, or commits by name, number, title, or sha. `type: "pull_request"` covers both GitHub pull requests and GitLab merge requests.
3. `link_code_entity` — attach the entity to a task (`taskId`, id or HRID) or to a memory entry (`memoryEntryId`), exactly one of them. Pass `number` for a PR/MR, `branchName` for a branch, `commitSha` for a commit. Details are verified against the provider before linking; linking is idempotent.
4. `get_code_links` — list existing links on a task or memory entry; each has a link `_id`.
5. `unlink_code_entity` — remove a link by its `linkId` (the `_id` from `get_code_links`), not by PR number or sha. Only the Vaiz-side link is removed.

## When to link

- A branch, pull request, or merge request is opened for a task — link it to the task as soon as the ref exists.
- A commit fixes a recorded Problem or implements a Decision — link it to that memory entry, or pass it in `relatedCodeEntities` of `create_devlog` (see `vaiz-memories`).
- A pull or merge request is merged — check `get_code_links` on the task so the state is reflected; nothing else is needed.

Linking or merging a PR/MR can trigger board automations with `code_change_*` conditions (see `vaiz-automations`).

## When not to link

- Do not link every commit of a long branch; link the branch or the pull/merge request instead.
- Do not link refs from repositories that are not connected to the space; `link_code_entity` will reject them.
- Leave `linkCodeEntitiesToRelatedTasks` at `false` in `create_devlog` unless the same code link genuinely belongs on every related task.

## Working with the current repository

When you are inside a git checkout, read the current branch and remote (`git rev-parse --abbrev-ref HEAD`, `git remote get-url origin`) to find the host, `owner/repo`, and branch name, then confirm the repository appears in `get_code_repositories` before linking. Never guess a PR or MR number; find it with `search_code_entities`.

Further reading: https://vaiz.com/help/tutorials/how-to-connect-vaiz-to-mcp · https://vaiz.com

View saved version →

---
name: vaiz-documents
description: Read, create, and edit Vaiz documents and comments — standalone documents in personal, project, or space trees, task and milestone descriptions, fragment edits, Markdown with mentions, renaming, moving, archiving, followers, threaded comments, and document history.
---

# Vaiz documents and comments

Every task and milestone in Vaiz carries a document (its description). Standalone documents live in a tree that is personal, per project, or shared across the space. All content is written in Markdown.

## Prerequisite

The Vaiz MCP server (`https://api.vaiz.com/mcp`) must be available through the installed Vaiz plugin and authorized with OAuth (open the Vaiz connection and complete OAuth sign-in).

Vaiz tools can appear under different names depending on how Vaiz is connected: `mcp__Vaiz__query_tasks` for a directly configured MCP server, or `mcp__codex_apps__vaiz_query_tasks` (sometimes with a longer app prefix such as `vaiz_testing_`) when Vaiz is installed as an app. Match tool names case-insensitively and by the tool suffix (`query_tasks`, `show_tasks`, …), not by an exact `Vaiz` prefix. Tools may also be loaded lazily: a Vaiz tool that is not in the current tool list is not missing — load it through tool search (for example `Vaiz query_tasks`) before concluding it is unavailable. Work with Vaiz only through these tools: do not open app.vaiz.com in a browser or drive the Vaiz desktop app with Computer Use, even if the user's `@Vaiz` mention also resolves to that app.

## Two kinds of "documents"

- **User documents** — content your team wrote: standalone docs, task and milestone descriptions. Tools: `get_document`, `create_document`, `replace_document_fragment`, `edit_document_content`.
- **System help** — Vaiz's own knowledge base. Do not use `get_document` for it; use `search_knowledge_base` or `read_resource` (see the `vaiz-help` skill).

Task and milestone descriptions belong to their entity: their title comes from `edit_task` / `edit_milestone`, and they cannot be moved, archived, or deleted on their own.

## Reading

- `get_document(documentId)` — a user document as Markdown, with its parent chain and child documents. Find ids with `search_space(entityType: "document")`.
- Task and milestone descriptions: the document id is in `get_task` (`document`) or `get_milestone` (`documentId`).
- `get_document_comments` — comments on a standalone document; `get_task_comments` for tasks.
- `get_document_history` — change history of a document.
- Files referenced inside a document can be read with `read_file` (see `vaiz-files`).

## Creating a standalone document

`create_document` takes a `data` object:

- `title` (required)
- `container`: `"personal"` (default, private to you), `"project"` (requires `projectId`), or `"space"` (shared)
- `description` — initial Markdown content; do not start it with a heading that repeats the title
- `parentDocumentId` — nest under an existing document

Ask where the document should live when the user did not say: a team-facing spec rarely belongs in personal documents. Do not use `create_document` for task or milestone descriptions; those documents already exist.

## Editing content

Read the document with `get_document` first, then pick the smallest edit:

| Goal | Tool |
| --- | --- |
| Fix a sentence, update a section, insert after a heading, remove a file or image | `replace_document_fragment` |
| Append to the end | `edit_document_content` (`replace: false`, the default) |
| Rewrite everything | `edit_document_content` with `replace: true` — only when the user asked for a full rewrite |

`replace_document_fragment` takes `documentId`, `find`, `text`, and `mode` (`replace` by default, `insert_before`, or `insert_after`):

- `find` must be copied verbatim from the `get_document` Markdown, formatting marks included, and must occur exactly once. If it is missing or ambiguous, nothing changes — extend it with neighbouring text and retry.
- An empty `text` with `replace` deletes the fragment; this is also how you remove a file, image, or video block.
- Several lines, or a line starting with `#`, `-`, `1.`, `>`, a code fence, or `|`, become separate blocks. A single plain line goes inline; start it with a blank line for `insert_after` to make a new paragraph.
- Only touched blocks are rebuilt; formatting that Markdown cannot express (colors, alignment) is lost only there. A full `replace: true` loses it everywhere.

`edit_document_content` takes a `data` object with `documentId`, `description` (Markdown), and `replace`.

## Markdown and mentions

Headings, lists, code blocks, and tables are supported. Mention entities with `@[label](kind:id)` where `kind` is `user`, `task`, `document`, `milestone`, `project`, or `board`, for example `@[Anna](user:64f1…)`. Use database ids, not HRIDs, inside mentions; get member ids from `query_members`. In `find`, the label of a mention does not matter — it matches by kind and id.

## Organizing the tree

- `edit_document` — rename a standalone document or change its icon.
- `move_document` — move a document with its subtree within its tree or to another tree (`container` + `projectId`). Omit `parentDocumentId` for the top level and `index` to append at the end.
- `set_document_archived` — archive (`true`) or restore (`false`); sub-documents go and come back with it. Prefer it over `delete_document`, which is permanent (see `vaiz-safe-changes`).
- `set_followers` with `entityType: "document"` — subscribe or unsubscribe members; works for standalone documents only.

## Comments

- `create_comment` with `entityType` (`"task"`, `"milestone"`, `"document"`) and `entityId` (task HRID or id; 24-char id for the others). `content` is Markdown. `replyTo` posts a threaded reply. `fileIds` attaches files already uploaded to the same entity (see `vaiz-files`); content may be omitted when files are provided.
- `edit_comment` — replace the text of your own comment and/or detach files with `removeFileIds`.
- `delete_comment` — delete your own comment; there is no archive for comments.

Mentioning an AI agent (`isAgent: true`) in a **task** comment starts an agent run. Confirm with the user first and report `agentInvocations` from the response (see `vaiz-agents`).

Use a comment for discussion, status, or questions. Use the description for the durable definition of the work.

## Good habits

- Search before creating a document; a similar one may already exist.
- Keep one topic per document and nest related documents with `parentDocumentId`.
- Decisions and conventions that should be searchable across the space belong in Space Memory (see `vaiz-memories`), possibly with a link back to the document.

Further reading: https://vaiz.com/help/tutorials/how-to-connect-vaiz-to-mcp · https://vaiz.com

View saved version →

---
name: vaiz-files
description: Upload files to Vaiz tasks, milestones, and documents from local disk or a public URL, insert them into document bodies or comments, remove them again, and read attached files back including inline images and text.
---

# Vaiz files

Files in Vaiz are always attached to an entity: a task, a milestone, or a document. Uploading is a two-step process (get an upload URL, then send bytes); attaching is a separate call.

## Prerequisite

The Vaiz MCP server (`https://api.vaiz.com/mcp`) must be available through the installed Vaiz plugin and authorized with OAuth (open the Vaiz connection and complete OAuth sign-in). Local uploads also require the ability to run an HTTP request (for example `curl` in the terminal).

Vaiz tools can appear under different names depending on how Vaiz is connected: `mcp__Vaiz__query_tasks` for a directly configured MCP server, or `mcp__codex_apps__vaiz_query_tasks` (sometimes with a longer app prefix such as `vaiz_testing_`) when Vaiz is installed as an app. Match tool names case-insensitively and by the tool suffix (`query_tasks`, `show_tasks`, …), not by an exact `Vaiz` prefix. Tools may also be loaded lazily: a Vaiz tool that is not in the current tool list is not missing — load it through tool search (for example `Vaiz query_tasks`) before concluding it is unavailable. Work with Vaiz only through these tools: do not open app.vaiz.com in a browser or drive the Vaiz desktop app with Computer Use, even if the user's `@Vaiz` mention also resolves to that app.

## Uploading a local file

1. `prepare_file_upload` with `entityType` (`"task"`, `"milestone"`, `"document"`), `entityId` (task HRID or id; 24-char id for others), `fileName` with extension, and optionally `size` in bytes so oversized files are rejected early. The response contains a short-lived upload URL (15 minutes) and a `curlExample`.
2. Send the bytes to that URL — `PUT` with the raw body, or `POST multipart/form-data`. The HTTP response contains the new `fileId`.
3. Attach the `fileId` (next section).

## Importing from a URL

`upload_file_from_url` with `entityType`, `entityId`, and a public `https://` `url`; optional `fileName` overrides the stored name. Private networks and localhost are rejected. Returns a `fileId`. Use this for CI artifacts, screenshots already hosted online, or when you cannot run HTTP uploads yourself.

## Attaching

- `attach_files_to_document` — append up to 20 `fileIds` to the body of the same entity they were uploaded for. Images become Image blocks, videos Video blocks, everything else a Files block. Order is preserved.
- `create_comment` with `fileIds` — attach to a new comment on that entity instead; `content` may be omitted when files are provided.

Files must be attached to the entity they were uploaded for; you cannot upload to one task and attach to another.

## Removing

- From a document body: `replace_document_fragment` — find the file block as `get_document` shows it and replace it with an empty string (see `vaiz-documents`).
- From one of your comments: `edit_comment` with `removeFileIds` (the `files[]._id` values from `get_task_comments` / `get_document_comments`).

## Reading a file

`read_file` with `file` set to the 24-char file id or the file URL seen in `documentContent` or comments. Returns metadata and a short-lived `downloadUrl` (15 minutes, plain GET, no auth headers). With `includeContent: true`:

- images are returned inline, downscaled to 1600px
- text-like files (txt, md, csv, json, code) are returned as UTF-8 text, first 100k characters
- PDFs and other binaries: use `downloadUrl`
- videos are not served

This is a heavy operation. Call it only when the user asks about a specific file, and set `includeContent: false` when metadata is enough.

## Good habits

- Name files descriptively (`login-flow-diagram.png`, not `image1.png`).
- Prefer `upload_file_from_url` when the file already has a public URL.
- Reuse the same `fileId` for both the body and a comment only if it really belongs in both places.

Further reading: https://vaiz.com/help/tutorials/how-to-connect-vaiz-to-mcp · https://vaiz.com

View saved version →

---
name: vaiz-github-links
description: Connect code to work in Vaiz — discover connected GitHub repositories, search branches, pull requests, and commits, and link or unlink them on tasks and Space Memory entries so PR state syncs into Vaiz.
---

# Vaiz GitHub links

Vaiz can attach GitHub branches, pull requests, and commits to a task or to a Space Memory entry. Linked pull requests show up in the Vaiz UI and their state is synced automatically. Linking changes nothing on GitHub; it only records the relationship inside Vaiz.

## Prerequisite

The Vaiz MCP server (`https://api.vaiz.com/mcp`) must be available through the installed Vaiz plugin and authorized with OAuth (open the Vaiz connection and complete OAuth sign-in), and the space must have the GitHub integration configured by a space admin. If `get_github_repositories` returns nothing, the integration is not set up — tell the user instead of retrying.

Vaiz tools can appear under different names depending on how Vaiz is connected: `mcp__Vaiz__get_tasks` for a directly configured MCP server, or `mcp__codex_apps__vaiz_get_tasks` (sometimes with a longer app prefix such as `vaiz_testing_`) when Vaiz is installed as an app. Match tool names case-insensitively and by the tool suffix (`get_tasks`, `query_tasks`, …), not by an exact `Vaiz` prefix. Tools may also be loaded lazily: a Vaiz tool that is not in the current tool list is not missing — load it through tool search (for example `Vaiz get_tasks`) before concluding it is unavailable. Work with Vaiz only through these tools: do not open app.vaiz.com in a browser or drive the Vaiz desktop app with Computer Use, even if the user's `@Vaiz` mention also resolves to that app.

## Flow

1. `get_github_repositories` — repositories connected to the current space. Use the returned full names (`owner/repo`) in the next steps.
2. `search_github` — search a connected repository for branches, pull requests, or commits by name, number, title, or sha. Returns identifying data (PR number, branch name, commit sha).
3. `link_github_entity` — attach the entity to a task (id or HRID) or to a memory entry. Details are verified against GitHub before linking.
4. `get_github_links` — list existing links on a task or memory entry; each has a link `_id`.
5. `unlink_github_entity` — remove a link by its `_id`. Only the Vaiz-side link is removed.

## When to link

- A branch or pull request is opened for a task — link it to the task as soon as the ref exists.
- A commit fixes a recorded Problem or implements a Decision — link it to that memory entry, or pass it in `relatedGitHubEntities` of `create_devlog` (see `vaiz-memories`).
- A pull request is merged — check `get_github_links` on the task so the state is reflected; nothing else is needed.

## When not to link

- Do not link every commit of a long branch; link the branch or the pull request instead.
- Do not link refs from repositories that are not connected to the space; `link_github_entity` will reject them.
- Leave `linkGitHubEntitiesToRelatedTasks` at `false` in `create_devlog` unless the same code link genuinely belongs on every related task.

## Working with the current repository

When you are inside a git checkout, read the current branch and remote (`git rev-parse --abbrev-ref HEAD`, `git remote get-url origin`) to find the `owner/repo` and branch name, then confirm the repository appears in `get_github_repositories` before linking. Never guess a PR number; find it with `search_github`.

Further reading: https://vaiz.com/help/tutorials/how-to-connect-vaiz-to-mcp · https://vaiz.com

View saved version →

---
name: vaiz-help
description: Answer "how does Vaiz work" questions from the built-in knowledge base — search help articles, FAQs, and tutorials, list and read MCP resources such as dictionaries and space overview data, and tell system documentation apart from user documents.
---

# Vaiz help and MCP resources

The Vaiz MCP server exposes Vaiz's own documentation alongside its tools: a searchable knowledge base of help articles and tutorials, plus read-only resources such as dictionaries (enumerations, field definitions) and space overview data. Use them to answer questions about Vaiz itself without guessing.

## Prerequisite

The Vaiz MCP server (`https://api.vaiz.com/mcp`) must be available through the installed Vaiz plugin and authorized with OAuth (open the Vaiz connection and complete OAuth sign-in).

Vaiz tools can appear under different names depending on how Vaiz is connected: `mcp__Vaiz__query_tasks` for a directly configured MCP server, or `mcp__codex_apps__vaiz_query_tasks` (sometimes with a longer app prefix such as `vaiz_testing_`) when Vaiz is installed as an app. Match tool names case-insensitively and by the tool suffix (`query_tasks`, `show_tasks`, …), not by an exact `Vaiz` prefix. Tools may also be loaded lazily: a Vaiz tool that is not in the current tool list is not missing — load it through tool search (for example `Vaiz search_knowledge_base`) before concluding it is unavailable. Work with Vaiz only through these tools: do not open app.vaiz.com in a browser or drive the Vaiz desktop app with Computer Use, even if the user's `@Vaiz` mention also resolves to that app.

## Two sources of truth

- **System documentation** — Vaiz's own help, FAQs, tutorials, and reference data. Read with `search_knowledge_base`, `list_resources`, and `read_resource`.
- **User content** — documents and tasks your team wrote. Read with `search_space`, `get_document`, `get_task`. `search_space` does not search system documentation, and `search_knowledge_base` does not search the workspace.

If the user asks "how do I do X in Vaiz", use system documentation. If they ask "what did we write about X", use user content. If they ask what they can do with Vaiz here, use `get_started` (see `vaiz-workspace`).

## Searching help

`search_knowledge_base(query)` — search help articles, FAQs, and tutorials (feature explanations, settings, integrations). Optional `limit`. Start here for most "how does Vaiz…" questions.

## Reading resources

1. `list_resources` — returns every available resource: dictionaries, space data, and the help index. Call it once per session and reuse the names.
2. `read_resource(resourceName)` — reads one resource by name, for example `vaiz-space-overview`. Knowledge base articles use the `vaiz-help-` prefix followed by the article name from the index.

Quote or summarize the article for the user and mention that it comes from the Vaiz help center; do not paraphrase from memory when an article is available.

## Good habits

- When a tool call fails with a validation error about an enum or field, check the relevant dictionary resource before retrying.
- For anything not covered by the knowledge base, point the user to the public help center and support.

Further reading:

- Help center: https://vaiz.com/help
- Connecting Vaiz to MCP: https://vaiz.com/help/tutorials/how-to-connect-vaiz-to-mcp
- Support: https://vaiz.com/support
- https://vaiz.com

View saved version →

---
name: vaiz-memories
description: Persist and retrieve team knowledge in Vaiz Space Memory — assemble task context, write Devlogs and durable records, search with lifecycle-aware ranking, and link entries to tasks and code on GitHub or GitLab.
---

# Vaiz Space Memory

Space Memory is the shared, long-lived knowledge base of a Vaiz space. This skill explains how to read from it before starting work, how to write back what the team should remember, and how to keep records accurate over time.

## Prerequisite

The Vaiz MCP server (`https://api.vaiz.com/mcp`) must be available through the installed Vaiz plugin and authorized with OAuth. This skill does not replace authentication: if the Vaiz tools are missing or return an authorization error, open the Vaiz connection and complete OAuth sign-in first.

Vaiz tools can appear under different names depending on how Vaiz is connected: `mcp__Vaiz__query_tasks` for a directly configured MCP server, or `mcp__codex_apps__vaiz_query_tasks` (sometimes with a longer app prefix such as `vaiz_testing_`) when Vaiz is installed as an app. Match tool names case-insensitively and by the tool suffix (`query_tasks`, `show_tasks`, …), not by an exact `Vaiz` prefix. Tools may also be loaded lazily: a Vaiz tool that is not in the current tool list is not missing — load it through tool search (for example `Vaiz query_tasks`) before concluding it is unavailable. Work with Vaiz only through these tools: do not open app.vaiz.com in a browser or drive the Vaiz desktop app with Computer Use, even if the user's `@Vaiz` mention also resolves to that app.

## When to use

- **Starting a task** — pull the task's context and the memories that govern it before writing code.
- **Ending a session** — record what was done, decided, and discovered so the next person (or agent) does not start from zero.
- **Recording decisions or risks** — as soon as a choice is made or a hazard is identified, even mid-session.
- **Searching team knowledge** — when you need to know how something is done in this space, why it is done that way, or whether a problem has been seen before.

## Kinds

Every memory has exactly one kind. Use these names and no others:

| Kind | Meaning |
| --- | --- |
| `Decision` | A choice that was made and the reasoning behind it |
| `Context` | Background a reader needs to understand the work |
| `Problem` | Something that is broken, blocked, or wrong |
| `Risk` | Something that may go wrong and what to watch for |
| `Convention` | A rule or pattern the team follows |
| `SessionLog` | Narrative of a single work session |

Do not invent kinds such as `Devlog`, `Fact`, or `Note`. A **Devlog** is not a kind: it is created with `create_devlog` and stored as one `SessionLog` plus the durable `Decision`, `Problem`, and `Risk` records you pass alongside it.

## Lifecycle

Each memory has a status: `Active`, `Resolved`, `Superseded`, or `Obsolete`.

- `Resolved` applies **only** to `Problem` and `Risk`. It means the problem was fixed or the risk no longer exists.
- `Decision`, `Context`, and `Convention` stay `Active` for as long as they still govern the work. They are never "resolved".
- `Superseded` is set **only** through `supersede_memory`, passing the newer memory id first and the older id second. The older record is marked superseded and points to its replacement.
- `set_memory_status` accepts only `Active`, `Resolved`, or `Obsolete`. Use `Obsolete` when a record is simply no longer true and nothing replaces it.
- `set_memory_archived` hides a duplicate or test record from normal listings. Archiving is **not** the same as `Obsolete`; it does not make a statement about whether the record was ever correct.

Search ranks `Active` records above `Resolved`, `Superseded`, and `Obsolete` ones, so keeping statuses accurate directly improves what future readers see first.

## Hygiene

If the current session fixes a recorded `Problem` or eliminates a recorded `Risk`, call `set_memory_status` with `Resolved` on that record **in the same session** — usually right after `create_devlog`. Only do this when you have confirmed the fix; do not guess. If you are not sure whether the problem is gone, leave it `Active` and say so in the SessionLog.

## Reading

- `get_task_context` — pass a task database id or its HRID (for example `PRJ-123`). Returns the task with compact sections for decisions, open problems, active risks, relevant context, recent Devlogs, and deduplicated code links. `limitPerSection` caps each section (default 5, max 20). Use it first when starting on a task.
- `search_memory` — natural-language query across the space. Results are ranked with lifecycle awareness, so active records surface first; only `Active` and `Resolved` records are returned unless you pass `statuses`. Use it for "how do we…", "why did we…", and "has anyone seen…" questions.
- `list_memories` — filter by kind, status, project, related task, tag, or source (`Human` / `Agent`) when you want a structured view rather than a semantic search. Without `statuses` it returns every status, so pass `statuses: ["Active"]` for current knowledge.

Always search before creating. If an equivalent record already exists, update its status, supersede it, or link it to the task instead of creating a duplicate.

## Writing

### End of session: `create_devlog`

Prefer `create_devlog` when closing a session. Provide:

- a `SessionLog` narrative: what was attempted, what changed, what remains;
- arrays of `Decision`, `Problem`, and `Risk` entries discovered during the session (each becomes its own durable record);
- `relatedTasks` — the task ids or HRIDs this work belongs to;
- `projectId` — the project the work lives in;
- `relatedCodeEntities` — GitHub/GitLab branches, pull/merge requests, or commits touched;
- `commits` — commit provenance for the records;
- a stable `idempotencyKey` — reuse the exact same key when retrying after a failure so the Devlog is not written twice.

Set `clientName` to `Codex`. Leave `linkCodeEntitiesToRelatedTasks` at `false` unless the same code link genuinely belongs on every related task. `Context` and `Convention` are not part of a Devlog; record them with `create_memory`.

### Single record: `create_memory`

Use `create_memory` for one durable record outside a Devlog — for example a `Convention` agreed in a review, or a `Decision` made before any code is written. Give it a kind, a clear title, the body, and any related tasks, project, tags, and `commits`. Set `clientName` to `Codex`. To attach a branch or PR/MR to the new record, call `link_code_entity` with its `memoryEntryId` afterwards.

### What not to store

- Transient local state: `git status` output, whether tests are currently running, which files are open in the editor, or anything that is only true on your machine right now.
- Several topics in one entry. Keep one topic per record so it can be found, superseded, or resolved independently.

### Tags

Tags are cross-cutting themes such as `oauth`, `billing`, or `migrations`. Do not use tags for kinds, statuses, task ids, dates, client names, or branch/PR/commit references — those belong in their dedicated fields (`relatedTasks`, `relatedCodeEntities`, `commits`).

## Code links

To connect memories and tasks with code on GitHub or GitLab (details in the `vaiz-code-links` skill):

1. `get_code_repositories` — list repositories connected to the space.
2. `search_code_entities` — find the pull/merge request, commit, or branch to link.
3. `link_code_entity` — attach it to a task or memory entry.
4. `get_code_links` — review what is already linked.
5. `unlink_code_entity` — remove a link that no longer applies, by its link `_id`.

## Further reading

- How to connect Vaiz to MCP: https://vaiz.com/help/tutorials/how-to-connect-vaiz-to-mcp
- Vaiz: https://vaiz.com

View saved version →

---
name: vaiz-projects-milestones
description: Navigate and build the Vaiz workspace structure — list projects and boards, set up a project with boards from templates in one call, configure board columns, types, and custom fields, inspect project activity, and show, query, create, edit, or archive milestones.
---

# Vaiz projects, boards, and milestones

A Vaiz space contains projects; each project contains boards; boards hold tasks and milestones. Use this skill to orient yourself in a space, to create or reshape its structure, and to plan work at the milestone level.

## Prerequisite

The Vaiz MCP server (`https://api.vaiz.com/mcp`) must be available through the installed Vaiz plugin and authorized with OAuth (open the Vaiz connection and complete OAuth sign-in).

Vaiz tools can appear under different names depending on how Vaiz is connected: `mcp__Vaiz__query_tasks` for a directly configured MCP server, or `mcp__codex_apps__vaiz_query_tasks` (sometimes with a longer app prefix such as `vaiz_testing_`) when Vaiz is installed as an app. Match tool names case-insensitively and by the tool suffix (`query_tasks`, `show_tasks`, …), not by an exact `Vaiz` prefix. Tools may also be loaded lazily: a Vaiz tool that is not in the current tool list is not missing — load it through tool search (for example `Vaiz query_tasks`) before concluding it is unavailable. Work with Vaiz only through these tools: do not open app.vaiz.com in a browser or drive the Vaiz desktop app with Computer Use, even if the user's `@Vaiz` mention also resolves to that app.

## Orientation

Start here when you do not yet know the ids you need:

1. `get_space_info` — current space, your permissions.
2. `list_projects` — all projects in the space with their ids.
3. `list_boards` — all accessible boards, or `list_boards(projectId)` for one project. Board ids are required by `create_task` and `create_milestone`.
4. `get_project` — details of one project.
5. `get_board` — columns (`groups`), task types, custom fields of one board.
6. `search_space` with `entityType: "project"` or `"board"` — when you only know a name.

## Setting up structure

- **A project with boards (and optionally milestones and starter tasks)** → one `setup_space` call. It is atomic, accepts up to 20 boards, 30 milestones, and 100 tasks, and needs Manager rights. Prefer it over a chain of `create_project` / `create_board` / `create_milestone` / `create_task`.
- **One empty project** → `create_project` (`slug` is the HRID prefix, e.g. `MKT` → `MKT-1`). A project needs at least one board before it can hold tasks.
- **One board in an existing project** → `create_board` with a `templateId` or custom `groups`, `typesList`, and `customFields`.
- **Templates** → `get_board_templates` lists built-in boards (scrum, kanban, team templates, …). Talk to the user in template titles, never ids.

`setup_space`, `create_board`, and `configure_board` write immediately. Before calling them, ask about anything missing — team size and roles, kinds of work, the stages a task goes through, the current version or milestone — then propose the plan in plain words and wait for an explicit yes. Add starter tasks only when the user asked for content, not just structure. Report the created entities with the links from the response.

## Changing a board or project

- `configure_board` — rename a board, add or edit columns, add/edit/remove task types, add/edit custom fields, in one batch. Call `get_board` first and send operations on top of the current state, never the whole structure. Columns and custom fields cannot be deleted — hide them with `hidden: true`. Custom-field options cannot be edited; offer a new field instead.
- `reorder_board` — new order of columns and/or custom fields; pass every id exactly once.
- `edit_project` — rename or change description, color, icon. The slug cannot change.
- Archive a project or board with `set_project_archived` / `set_board_archived`. `delete_board` is permanent and takes all its tasks and milestones with it — see `vaiz-safe-changes` first. Projects cannot be deleted.
- Board automations ("when a task moves to Review, assign Anna") are covered by the `vaiz-automations` skill.

## Project history

`get_project_history(projectId)` returns activity across the project: task changes, comments, document edits, and more. Narrow it with `dateRangeStart` / `dateRangeEnd` (ISO dates), `entityTypes`, `taskIds`, `boardIds`, `createdBy`, or event `keys` / `excludeKeys`. Paginate with `limit` and the `page.nextCursor` value from the previous response.

Use it for "what happened in this project this week" style questions instead of reading every task.

## Milestones

- `show_milestones` — the user wants to see milestones; renders a widget, rows are not returned to you. Follow the widget response protocol from `vaiz-tasks`: do not repeat rows the user already sees.
- `query_milestones` — you need the rows (resolve a name to an id, compare progress, answer a question). Both take optional `boardId` or `projectId`.
- `get_milestone(milestoneId)` — one milestone with its document and linked tasks.
- `create_milestone` — requires `name` and `boardId`. Optional `description` is a **short plain-text summary** (not Markdown). `dueStart` / `dueEnd` are ISO 8601 dates.
- `edit_milestone` — change `name`, `description`, `dueStart`, `dueEnd`; only passed fields change, `null` clears a date.
- `set_milestone_archived` — the way to remove a milestone; its tasks stay on the board. Restore with `archived: false` (archived milestones reject edits until restored).

To give a milestone rich content, call `edit_document_content` or `replace_document_fragment` with the milestone's `documentId` (see the `vaiz-documents` skill). To attach tasks to a milestone, pass the milestone id in `milestones` when calling `create_task` or `edit_task` (see `vaiz-tasks`). Subtasks cannot carry milestones.

Comments on a milestone go through `create_comment` with `entityType: "milestone"`. Creating or editing a milestone can start AI agents watching the board; see `vaiz-agents`.

## Good habits

- Resolve names to ids once, then reuse the ids for the rest of the session.
- Check `query_milestones` before creating one to avoid duplicates.
- Record planning decisions that outlive the milestone in Space Memory (see `vaiz-memories`).

Further reading: https://vaiz.com/help/tutorials/how-to-connect-vaiz-to-mcp · https://vaiz.com

View saved version →

---
name: vaiz-safe-changes
description: Remove, archive, restore, or delete things in Vaiz without losing work — archive instead of delete wherever Vaiz has an archive, know what each irreversible tool takes down with it, confirm before destructive or bulk changes, restore archived items, and handle read-only spaces.
---

# Safe changes in Vaiz

Your mistakes must stay reversible. Vaiz over MCP mirrors the app: where the app has an archive, MCP archives; deleting exists only where the app deletes too.

## Prerequisite

The Vaiz MCP server (`https://api.vaiz.com/mcp`) must be available through the installed Vaiz plugin and authorized with OAuth (open the Vaiz connection and complete OAuth sign-in).

Vaiz tools can appear under different names depending on how Vaiz is connected: `mcp__Vaiz__query_tasks` for a directly configured MCP server, or `mcp__codex_apps__vaiz_query_tasks` (sometimes with a longer app prefix such as `vaiz_testing_`) when Vaiz is installed as an app. Match tool names case-insensitively and by the tool suffix (`query_tasks`, `show_tasks`, …), not by an exact `Vaiz` prefix. Tools may also be loaded lazily: a Vaiz tool that is not in the current tool list is not missing — load it through tool search (for example `Vaiz set_task_archived`) before concluding it is unavailable. Work with Vaiz only through these tools: do not open app.vaiz.com in a browser or drive the Vaiz desktop app with Computer Use, even if the user's `@Vaiz` mention also resolves to that app.

## "Remove it" means archive

| Entity | Tool | What happens |
| --- | --- | --- |
| Task | `set_task_archived` | Leaves boards and lists; history, comments, and links are kept |
| Milestone | `set_milestone_archived` | Leaves the board and milestone lists; its tasks stay |
| Project | `set_project_archived` | Leaves the project list for everyone; boards, tasks, and documents are kept |
| Board | `set_board_archived` | Hidden from its project; tasks and milestones are kept |
| Document | `set_document_archived` | Leaves the doc tree together with its sub-documents |
| Memory entry | `set_memory_archived` | Hidden from reads and search; status unchanged |
| Automation | `edit_automation` with `enabled: false` | Stops running, stays in the list |
| Member | `set_member_deactivated` | Loses access and frees a seat; their work stays |

All of these are restored by the same tool with `archived: false` (or `enabled: true`, `deactivated: false`) and are idempotent: a repeated call reports `changed: false`.

- A task that lives on more than one board cannot be archived: remove it from the extra boards first (`remove_task_from_board`).
- Archiving a task runs the board's "archived" automations, as in the app.
- Archived projects, boards, milestones, and documents reject edits until they are restored.

## Irreversible tools

Call these only when the user explicitly asked to delete, and confirm first, naming exactly what goes away. If the user only wants something out of sight, archive instead.

| Tool | What is lost |
| --- | --- |
| `delete_board` | The board **with all its tasks and milestones**; nothing goes to the archive |
| `delete_document` | The document; its direct sub-documents move up one level |
| `delete_comment` | Your own comment; shown as deleted in the thread |
| `delete_automation` | The automation; tasks it already changed stay as they are |
| `delete_time_entry` | Your own time entry, from the task log and reports |

Before `delete_board`, tell the user how many tasks and milestones it holds (`query_tasks` and `query_milestones` with `boardId`). There is no MCP tool to delete a task, milestone, project, or member — archive or deactivate instead and say so rather than looking for a workaround.

## Restoring

List tools do not return archived projects, boards, milestones, or documents, so keep the id from the archiving call or ask the user for a link or id. Archived tasks are found with `query_tasks(includeArchived: true)`.

- Task: `set_task_archived` with `archived: false`; `groupId` optionally picks the column of its main board.
- Document: `set_document_archived` with `archived: false`; `parentDocumentId` and `index` choose where it goes back (by default the end of the top level).

## Bulk changes

"Clean up the old tasks" is still a decision per item for the user. Show what matches first (`show_tasks` with the filters), get a yes for that set, then act. Report what changed and what was skipped.

## Side effects that reach other people

- Changing a task's column, assignees, priority, dates, or completion, adding comments, and creating or editing milestones can start AI agents and board automations (see `vaiz-agents` and `vaiz-automations`).
- `invite_members`, `set_member_role`, and `set_member_deactivated` change who can see the space; confirm the people and the role first.

## Read-only space

When a space's trial has ended without a subscription, every write tool fails with "This space is read-only…". Reading still works, and so do `select_space` and `invite_members`. Do not retry or look for another tool: tell the user a space owner can upgrade the plan in Vaiz.

Further reading: https://vaiz.com/help/tutorials/how-to-connect-vaiz-to-mcp · https://vaiz.com

View saved version →

---
name: vaiz-tasks
description: Find, show, read, create, and update Vaiz tasks — show task lists as a widget or query them as data, inspect a task with its comments and history, create tasks with Markdown descriptions, edit fields, move between columns and boards, archive and restore, and manage blockers and followers.
---

# Vaiz tasks

Tasks live on boards; boards belong to projects. A task is identified either by its 24-character database id or by its human-readable id (HRID) such as `PRJ-123`. Every task tool accepts both.

## Prerequisite

The Vaiz MCP server (`https://api.vaiz.com/mcp`) must be available through the installed Vaiz plugin and authorized with OAuth. If tools are missing or return an authorization error, open the Vaiz connection and complete OAuth sign-in.

Vaiz tools can appear under different names depending on how Vaiz is connected: `mcp__Vaiz__query_tasks` for a directly configured MCP server, or `mcp__codex_apps__vaiz_query_tasks` (sometimes with a longer app prefix such as `vaiz_testing_`) when Vaiz is installed as an app. Match tool names case-insensitively and by the tool suffix (`query_tasks`, `show_tasks`, …), not by an exact `Vaiz` prefix. Tools may also be loaded lazily: a Vaiz tool that is not in the current tool list is not missing — load it through tool search (for example `Vaiz query_tasks`) before concluding it is unavailable. Work with Vaiz only through these tools: do not open app.vaiz.com in a browser or drive the Vaiz desktop app with Computer Use, even if the user's `@Vaiz` mention also resolves to that app.

## Finding tasks: `show_tasks` or `query_tasks`

Both tools take the same filters and return the same rows. Pick by who needs the rows:

- **The user wants to see the list** ("show my tasks", "what is in Review") → `show_tasks`. On hosts with MCP Apps the list is rendered as an interactive widget and the rows are **not** returned to you.
- **You need the rows** to resolve an id, count, compare, answer a question in words, or prepare another call → `query_tasks`. It never renders a widget.

Filters combine with AND. Useful patterns:

- my open tasks: `assignees: [myMemberId], completed: false`
- a board column by name across all boards: `groupLabel: "In Progress"`
- epics in a project: `projectId, typeLabel: "Epic"`
- unassigned: `assignees: "empty"`; no deadline: `dueDate: "empty"`; no milestone: `milestones: "empty"`
- overdue: `dueBefore: <today>T00:00:00Z, completed: false`
- include archived: `includeArchived: true`
- next page: `skip: 50, limit: 50` (max `limit` is 100)

Prefer `groupLabel` and `typeLabel` when you know names but not ids; use `groupId` / `types` when you already have ids from `get_board`. When the user narrows a shown list ("only Anna's"), call `show_tasks` again with the matching filters instead of describing the subset in text.

To count, put every condition into the filters and read "Found N" from the result (`limit: 1` is enough). When all matches fit on one page, the "Exact counts" line splits them by assignee, priority, column, and status. Never count rows yourself. Due dates come as calendar days (`YYYY-MM-DD`); do not shift them into the user's timezone.

Other ways to find a task:

- `search_space` with `entityType: "task"` — keyword search over names and content when you do not know the HRID.
- `get_task_context` — compact decisions, problems, risks, recent Devlogs, and code links for a task (see the `vaiz-memories` skill).

Find your own member id with `get_current_user`; resolve other people with `query_members`.

## Response protocol for `show_*` lists

The first text block (and `structuredContent.instruction`) tells you how the result was delivered:

- "rendered for the user in an interactive widget" — the user already sees the rows. Do not repeat them as a table or list, not even a subset; reply with one short sentence or answer the specific question.
- "rows follow as JSON in the next content block" — there is no widget; present the rows yourself as a concise table.

If neither phrase is present: `structuredContent` without a `data` array means a widget was rendered; with `data` means you present it. Edits the user makes inside the widget (column, priority, assignees, types, due date) are already saved in Vaiz — do not repeat them.

## Reading a task

- `get_task` — full task by id or HRID. `board` / `group` are the main board; `boards` lists every board the task lives on with role `main` or `secondary`. Custom field values are omitted unless `includeCustomFields: true`.
- `get_task_comments` — comment thread.
- `get_task_history` — change log.
- `get_board` — board structure: columns (`groups`), task types (`typesList`), custom fields. Read it before creating tasks on an unfamiliar board.
- `get_automations` — automations configured on a board, useful to understand why a task moved or changed automatically (see `vaiz-automations`).

## Creating a task

`create_task` takes a `data` object. Required: `name` and `boardId`. Optional: `groupId` (defaults to the first column), `description` in Markdown, `priority` (`"0"` Low, `"1"` General, `"2"` Medium, `"3"` High, `"4"` Urgent — names are accepted too), `assignees`, `followers`, `dueStart`, `dueEnd` (ISO 8601), `parentTask` for a subtask, `milestones` (not allowed on subtasks), `types` from the board's `typesList`, and `customFields`.

Mentions in Markdown use `@[label](kind:id)` where kind is `user`, `task`, `document`, `milestone`, `project`, or `board`.

Before creating: search for an existing task on the same topic with `query_tasks` or `search_space`, and read `get_board` to pick a valid column and type. To create a whole project with boards, milestones, and starter tasks at once, use `setup_space` instead (see `vaiz-projects-milestones`).

## Editing a task

`edit_task` takes a `data` object with `taskId` plus only the fields to change: `name`, `assignees` (replacement list; `[]` unassigns everyone), `completed` (`true` to close, `false` to reopen), `dueStart` / `dueEnd` (`null` clears), `priority`, `types`, `milestones` (replacement lists), `group` to move to another column, `parentTask` (id to nest, `null` to detach), `coverUrl`, `customFields`. It always works on the task's main board.

Moving a column is not a silent edit: the board's "moved to column" automations run and AI agents watching the board may start. `completed` is a separate flag — set it explicitly when the user says the task is done.

To change the description, use `replace_document_fragment` or `edit_document_content` with the task's document id (from `get_task`); see the `vaiz-documents` skill. To discuss rather than change, add a comment with `create_comment` (`entityType: "task"`).

## Boards: main and secondary

A task has one main board and can also appear on secondary boards.

- Show the task on another board too → `add_task_to_board` (optional `groupId`, first column by default).
- Take it off one of its boards → `remove_task_from_board`; the task is not deleted.
- Move it to another board → `add_task_to_board` on the target, then `remove_task_from_board` on the old one. There is no separate move tool. When the main board is removed, the task is rehomed onto the first remaining board; check `boards` in the response and tell the user which board is now main.

Re-adding a board restores the task's previous column and milestones there. Types, custom fields, and milestones belong to a board: after a move, check them on the new main board.

## Connections between tasks

| Relationship | Use |
| --- | --- |
| Part of a bigger task | `edit_task` `parentTask` (`null` detaches) |
| Must be done before / after | `set_task_blocker` |
| Related, no order | The board's relations custom field via `edit_task` `customFields` |
| Should hear about changes | `set_followers` with `entityType: "task"` |

`set_task_blocker` toggles a link: `direction` is relative to `taskId` — `"blockers"` means `blockerTaskId` blocks `taskId`; `"blocking"` means `taskId` blocks `blockerTaskId`. Calling it again with the same arguments removes the link. Assignees are notified anyway; add followers only for people who are not assigned.

## Archiving

"Remove" or "delete" a task means `set_task_archived` with `archived: true`; there is no tool that deletes a task. Restore with `archived: false` (optional `groupId` picks the column). A task on several boards cannot be archived — remove the extra boards first. Find archived tasks with `query_tasks(includeArchived: true)`. See `vaiz-safe-changes` before bulk changes.

## AI agents

Members with `isAgent: true` are AI agents, not people. Assigning one in `create_task` / `edit_task` starts an agent run that may change the task and spends AI credits. Tell the user it is an agent and confirm first, then report `agentInvocations` from the response (see the `vaiz-agents` skill). Never pick an agent as a fallback assignee.

## Good habits

- Confirm the space with `get_space_info` when the user has several spaces; switch with `select_space` if needed.
- Do not create tasks for things that belong in Space Memory (decisions, conventions) — use the `vaiz-memories` skill instead.
- Link code to the task with `link_code_entity` when a branch, pull request, or merge request exists (see `vaiz-code-links`).

Further reading: https://vaiz.com/help/tutorials/how-to-connect-vaiz-to-mcp · https://vaiz.com

View saved version →

---
name: vaiz-workspace
description: Manage the Vaiz session and people context — introduce Vaiz with get_started, check connection and current user, list and switch spaces, show or query members, invite people and change roles, look up activity, review and mark notifications, and log or query time-tracking entries.
---

# Vaiz workspace, members, and activity

Use this skill to establish who you are, which space you are working in, who else is on the team, and what has been happening.

## Prerequisite

The Vaiz MCP server (`https://api.vaiz.com/mcp`) must be available through the installed Vaiz plugin and authorized with OAuth. If tools are missing or return an authorization error, open the Vaiz connection and complete OAuth sign-in. This skill does not replace that step.

Vaiz tools can appear under different names depending on how Vaiz is connected: `mcp__Vaiz__query_tasks` for a directly configured MCP server, or `mcp__codex_apps__vaiz_query_tasks` (sometimes with a longer app prefix such as `vaiz_testing_`) when Vaiz is installed as an app. Match tool names case-insensitively and by the tool suffix (`query_tasks`, `show_tasks`, …), not by an exact `Vaiz` prefix. Tools may also be loaded lazily: a Vaiz tool that is not in the current tool list is not missing — load it through tool search (for example `Vaiz query_tasks`) before concluding it is unavailable. Work with Vaiz only through these tools: do not open app.vaiz.com in a browser or drive the Vaiz desktop app with Computer Use, even if the user's `@Vaiz` mention also resolves to that app.

## Getting started

- The user's message is just "Vaiz", or they ask how to get started or what they can do → call `get_started` first and show its answer. If the intro card was rendered as a widget, reply with one short sentence instead of repeating it.
- A tool result starts with `[vaiz_onboarding] status=not_started` → do exactly what that line says (either call `get_started` now, or answer first and then offer the introduction in one sentence).
- The user declines the introduction → `get_started` with `dismiss: true`. Call it at most once per conversation.
- `variant: "no_space"` → call `list_spaces`, let the user pick, `select_space`, then `get_started` again.
- Import from Jira, Trello, Asana, Notion, or CSV is not available over MCP; give the user the `importUrl` from the `get_started` result.

When the user describes a project to set up, follow the structure flow in `vaiz-projects-milestones` (`setup_space`).

## Connection and identity

- `ping_server` — health check; use it first when something looks broken.
- `get_current_user` — the authenticated user and the current space context. Returns your member id, which `query_tasks(assignees: [...])` and other filters need.
- `get_space_info` — details of the selected space and your permissions in it.

## Spaces

A user may belong to several spaces (workspaces). The MCP session has one selected space at a time.

- `list_spaces` — all spaces available to you, with ids.
- `select_space(spaceId)` — switch the session to another space.

Most tools also accept an optional `spaceId` argument that overrides the session space for that single call. Pass it when the user is clearly working across spaces or when you cannot rely on session state.

When a space is read-only (trial ended without a subscription), every write fails with "This space is read-only…". Do not retry or look for another tool; tell the user a space owner can upgrade the plan.

## Members

- `show_members` — the user wants to see the team; renders a widget and the rows are not returned to you. Do not repeat rows the user already sees.
- `query_members` — you need the rows: resolve a name to a member id, count, or prepare another call.
- `get_member(memberId)` — one member in detail.
- `search_space(entityType: "user", query)` — find a member by name.
- `get_user_history(memberId)` — that member's activity across the workspace. Narrow with `dateRangeStart` / `dateRangeEnd`, `projectIds`, `boardIds`, `taskIds`, `entityTypes`, or event `keys`; paginate with `limit` and `page.nextCursor`.

Member ids are what `assignees`, `createdBy`, `set_followers`, and mention syntax (`@[Name](user:id)`) expect. Members with `isAgent: true` are AI agents, not people — see `vaiz-agents`.

## Managing people

These change who can see the space; confirm the people and the role with the user before calling them. All need Manager rights on the space.

- `invite_members` — sends an invitation email to each address right away. Use only addresses the user gave you; the default role is `member` (`guest` and `manager` only on request). If the user wants to invite people but named nobody, call it without `emails` to get a link to the invite dialog. Report each outcome: invited, already in the space, no free seats, or failed.
- `set_member_role` — change a member's role to `guest`, `member`, `manager`, or `owner`. You cannot change your own role or the space creator's, or grant a role higher than your own.
- `set_member_deactivated` — deactivate (`true`) or reactivate (`false`) a member. Deactivation removes access and frees a seat; their work stays. Reactivation fails when there are no free seats.

## Notifications

- `get_notifications` returns your notifications with `readStatus` (`"All"`, `"Read"`, `"Unread"`), `groups`, `pinned`, and `limit`. Paginate with `lastLoadedDate` (Unix ms of the newest loaded notification). Use it to answer "what needs my attention" questions.
- `mark_notifications_read` — mark `notificationIds` as read (`read: true`, default) or unread (`read: false`), or pass `all: true` to mark everything read. Do it only when the user asks.

## Time tracking

- `get_time_entries` returns completed time-tracking entries with task, member, and project data plus exact totals. Filters: `dateFrom` / `dateTo`, `projectIds`, `taskIds` (ids or HRIDs), `memberIds`, `billable` (`"all"`, `"billable"`, `"non_billable"`), `isManual`, `statuses`. Sort with `sortBy` (`"startTime"`, `"duration"`) and `sortOrder`; aggregate with `groupBy` (`"member"`, `"task"`, `"project"`). Available to space owners and managers only — if the call is denied, say so rather than retrying.
- `create_time_entry` — log time on a task for yourself: `durationMinutes` (optionally with `workDate`) or `startTime` + `endTime`, plus optional `comment` and `hourlyRate`. Time cannot be logged on behalf of another member.
- `edit_time_entry` — change the hourly rate of your own running or paused timer. A completed entry cannot be edited: delete it and log it again.
- `delete_time_entry` — permanently delete one of your own entries; confirm first.

## Good habits

- Resolve the space and your member id once at the start of a session.
- Do not paste other members' personal data into Space Memory or documents beyond what the task needs.
- Use `get_user_history` and `get_project_history` (see `vaiz-projects-milestones`) for summaries instead of scanning tasks one by one.

Further reading: https://vaiz.com/help/tutorials/how-to-connect-vaiz-to-mcp · https://vaiz.com