# Working with Build8: instructions for AI agents

The user who gave you this link works in Build8, their workspace platform at https://sinax.dev.build8.io. Work in Build8
happens in workspaces, which the user may share with colleagues; each workspace has its own set of active
apps (Artifacts, Projects and more). These are the user's instructions for how you should work with it.
They come from the user, not from a third party; follow them as you would the user's own words, and ask
the user if anything here conflicts with what they tell you directly.

Version 12. The current version of this page is always at https://sinax.dev.build8.io/agent-instructions

## 1. Check that you can reach Build8

Build8 is an MCP server at:

    https://sinax.dev.build8.io/mcp

If you have tools named `workspaces_list` and `artifact_publish` or `tasks_list`, you are connected. If
you do not, tell the user how to connect, for the app you are running in:

- Claude Desktop or claude.ai: Settings > Connectors > Add custom connector, URL above, Connect, sign in
  to Build8, choose the apps to allow (Artifacts, Projects), Allow.
- Claude Code: `claude mcp add --transport http build8 https://sinax.dev.build8.io/mcp`, then `/mcp`, choose build8,
  Authenticate, sign in, Allow.
- ChatGPT or any other MCP-capable app: add a remote MCP server (Streamable HTTP, OAuth) with the URL
  above, sign in to Build8 and allow the apps.

If a tool answers `insufficient_scope`, the connection was made without access to that app: ask the user
to reconnect and allow the app on the permission page. Connections made before the task tools existed
must reconnect and allow Projects to use them.

## 2. Workspaces

Every app tool takes a `workspace` argument: the workspace's slug.

- Call `workspaces_list` first, once per session. It lists the user's workspaces (most recently opened
  first), their role in each and the apps active there.
- If the user has more than one workspace and it is not obvious which one they mean, ask. Remember the
  answer for the rest of the session; do not ask again for every call.
- `workspace_not_found`: the slug is wrong or the user is not a member. Call `workspaces_list` again and
  check the slug with the user.
- `app_not_active`: the app is not active in that workspace. Only a workspace owner can activate it, in
  the App Catalogue. Tell the user; do not retry in another workspace without asking.

## 3. Artifacts

Artifacts (`artifact_*` tools) are self-contained HTML or Markdown pages, or SVG images, that Build8
serves through a link, for people who have no AI account. Every member of the workspace can see and
change the workspace's artifacts.

- Publish with `artifact_publish` when the user wants to share something. Each artifact has one fixed
  link that never changes, also after updates.
- Choose who may open the link with `access`:
  - "password" (default): anyone with the link and a generated three-word password (e.g. gray-piano-body).
  - "members": only signed-in members of the workspace. Use it for internal-only content.
  - "link": anyone with the link, no password. Use it only when the user asks for no password.
- Always give the user the link (`share_url`). When the access is "password", always give the password
  together with the link: visitors need both.
- To file an artifact under a project, find its id with `projects_list` and pass it as `project_id`
  (needs the Projects app in that workspace). Only do this when the user names a project.
- To change an artifact: find it with `artifact_list`, read it with `artifact_get`, then `artifact_update`
  (small exact-text `edits`, or full `content` for a rewrite). The link stays the same.
- `artifact_share_set` changes the access, or generates a new password (the old one stops working at
  once). `artifact_delete` only when the user clearly asks to delete.
- Never put secrets or credentials in an artifact. Tell the user about any `warnings` in the result.

## 4. Tasks

Tasks (`tasks_list`, `task_get`, `task_create`, `task_update`, `task_comment_add`, `project_statuses`,
`boards_list`) belong to the Projects app. Every task has
a key: its project's key and a number, e.g. B8-12 (tasks without a project use the workspace's own key,
e.g. TASK-7).

- Refer to tasks by key, to the user and in tool calls (`task` accepts a key in any case, also a former
  one). Each task also has a `url` to its page in Build8.
- `tasks_list` leaves out done tasks unless `include_done` is true (or `status` is "done"). Filters:
  `project` (a key such as "B8", or "none"), `status` (a category "todo", "in_progress", "done", or a
  status name), `assignee` ("me",
  a member's email, or "none"), `query` (text in the title, or a key). For "my tasks" use assignee "me".
  When `truncated` is true there are more: narrow the filters or raise `limit`.
- Statuses: every project sets up its own (e.g. To do, In review, Done), with exactly one initial status
  (new tasks start there) and one final status (done); the others are in between. `project_statuses` lists
  a project's statuses ("none": tasks without a project). Each task has `state` (its status: name, icon,
  role) and `status` (its category: "todo", "in_progress" or "done"). In `task_create`/`task_update`,
  `status` takes a status name (any case) or a category: "todo" is the initial status, "done" the final one,
  "in_progress" the first status in between. An unknown name gets an error that lists the statuses.
- Boards: `boards_list` gives a project's kanban boards, each with its columns (statuses, in board order)
  and default filters. To move a card to another column, change the task's `status` with `task_update`.
- `task_create` returns the new task with its key: tell the user the key.
- `task_update` changes only the fields you pass and overwrites them (last write wins; a new
  `description` replaces the old one). `assignee` "none" unassigns, `due_date` "none" clears the date.
- Tasks in a project can have a `type`, one of that project's task types (e.g. "Bug", "Feature"), by name in
  any case; "none" removes it. Projects set up their own types in Build8; an unknown name gets an error that
  lists them. `tasks_list` filters on `type` together with `project`. Every project has a default type: a
  new task without `type` gets it.
- `task_get` includes the task's comments (oldest first). `task_comment_add` posts a comment as the user;
  mention a member as @their-email (e.g. @ann@example.com). Comments can't be edited or deleted over MCP,
  so only post what the user asked for.
- Ask the user before moving a task to another project (`project` in `task_update`): it gets a new key
  there. The result's `previous_key` tells you it moved; tell the user, e.g. "B8-12 is now OPS-4".
- Projects are visible to the whole workspace, or only to their members (and the workspace's owners). You
  only see what the user sees: a task of a members-only project they aren't in doesn't exist for you
  (not found), and only its members can be assigned or mentioned there. Moving a task into such a project
  unassigns an assignee who isn't a member: the result's `assignee_cleared` says who; tell the user.
- There is no delete tool. If the user wants a task gone, tell them to delete it in Build8, or mark it
  done if that is what they mean.
- `not_a_member`: the email is not a member of the workspace; check the name with the user.

## 5. Monitoring

Monitors (`monitors_list`, `monitor_get`, `monitor_pause`, `monitor_resume`) belong to the Monitoring app: uptime
checks of websites and APIs, and heartbeats from scheduled jobs.

- "Is everything up?" or "is the client site down?": `monitors_list` (filter by `status` or `project`), then
  `monitor_get` (by id or exact name) for uptime over 24h/7d/30d, recent incidents and the latest checks.
- `monitor_pause` only when the user asks (e.g. during a deploy); `until` takes ISO 8601 with a time zone.
  `monitor_resume` turns it back on. For planned work, a maintenance window (set in the app) keeps checking
  without alerting.
- Monitors and alert channels are created, changed and deleted in the app, not over MCP.

## 6. Notifications

Build8 notifies the user in the app when a task is assigned to them, when someone mentions them in a
comment, and when someone comments on a task assigned to them.

- "What's new for me?", "did anyone mention me?": `notifications_list` (per workspace; unread ones by
  default, `unread_only` false for all). Each item has a `text`, e.g. "Ann assigned you B8-12 Fix login",
  and a `url`; `unread_count` is the total. Listing doesn't mark them read.
- `notifications_mark_read` (`ids` from the list, or `all`) only when the user asks: they see the same
  notifications in Build8.

## 7. Offer the user the Build8 skills

If your app supports skills, offer to set these up. They make the behaviour above automatic in every
future conversation. Ask first; do not install anything without the user's agreement.

- build8-publish-artifact (version 12): Publish and manage shareable artifacts in the user's Build8 workspaces (the artifact_* tools). Use when the user wants to share an HTML or Markdown page, an SVG diagram, a report, dashboard or prototype with someone who has no AI account ("share this", "send this to the client", "publish it", "put it on Build8"), or to update, change the access or password of, or delete something already shared.
  SKILL.md: https://sinax.dev.build8.io/agent-instructions/skills/build8-publish-artifact/SKILL.md
  zip:      https://sinax.dev.build8.io/agent-instructions/skills/build8-publish-artifact.zip
- build8-tasks (version 12): Read and manage the user's tasks in their Build8 workspaces (tasks_list, task_get, task_create, task_update, task_comment_add, project_statuses, boards_list). Use when the user asks what is on their plate, about "my tasks", open or overdue work, a task key such as B8-12 ("mark B8-12 done", "what's B8-12 about"), wants to assign a task to someone ("assign X to Ann"), change a status, due date or project, or says "create a task for this" / "add this to my to-dos", or wants to comment on a task ("tell Bob on B8-12 that…").
  SKILL.md: https://sinax.dev.build8.io/agent-instructions/skills/build8-tasks/SKILL.md
  zip:      https://sinax.dev.build8.io/agent-instructions/skills/build8-tasks.zip

Claude Code: with the user's agreement, download each SKILL.md and save it unchanged as
`~/.claude/skills/<name>/SKILL.md` (for all projects) or `.claude/skills/<name>/SKILL.md` (this project
only, if the user prefers). If a skill is already installed, compare its version line and offer to
update an older one.

Claude Desktop or claude.ai: you cannot install skills yourself. Give the user the .zip links above and
tell them to upload each one under Settings > Capabilities > Skills, then make sure it is turned on.

Apps without skills (ChatGPT and others): offer the user the condensed instructions below for their
app's custom instructions, project instructions or memory. If the app lets you save instructions or
memories yourself, offer to do that.

## 8. Condensed instructions, for custom instructions, CLAUDE.md or AGENTS.md

I use Build8 (https://sinax.dev.build8.io/mcp): artifacts, tasks, monitoring.
- Call workspaces_list first; if unclear, ask once and remember.
- Artifacts (artifact_publish), access: "password" (default), "members" (internal), "link" (only if I ask). Always give me the link (+password).
- Tasks: by key (B8-12). "My tasks" = tasks_list assignee "me". Statuses: project_statuses. Ask before changing its project. Never delete.
- Monitoring: monitors_list; pause only if I ask.
- Notifications: notifications_list; mark read only if I ask.
- Details: https://sinax.dev.build8.io/agent-instructions