user-management

User Management

Manage the swarm's user registry — creating, updating, resolving, and listing users. Users link human identities across platforms (Slack, GitHub, GitLab, Linear, email) so the swarm can track who requested work.

Migration note (2026-05): the old top-level identity fields (slackUserId, linearUserId, githubUsername, gitlabUsername) and the fuzzy name lookup were removed in lockstep with the user-identity refactor. Use the new {kind, externalId} shape instead. Old payloads now fail Zod validation at runtime — there is no compatibility shim.

When to Create Users

Create a new user when:

• An unknown Slack user sends a message to the swarm (resolve-user with {kind: "slack", externalId: "<U_X>"} returns no match)
• An unknown GitHub user opens an issue or PR that triggers a task
• An unknown GitLab user creates an issue or MR
• An unknown Linear user is assigned to or creates a synced issue
• A human explicitly asks to be registered

Do NOT create duplicate users. Always call resolve-user first — by {kind, externalId} AND, when you have it, by email — to check if the person already exists under a different platform identity.

Tools

Two MCP tools handle user management:

resolve-user — Find an existing user

Looks up a user by an (kind, externalId) pair OR by email (primary or alias). Use this BEFORE creating a new user. Caller MUST supply either (kind + externalId) OR email — empty input is rejected.

# Lookup by platform identity
resolve-user with:
  kind: "slack"
  externalId: "U12345"

# OR
resolve-user with:
  kind: "github"
  externalId: "octocat"

# OR
resolve-user with:
  kind: "gitlab"
  externalId: "octocat"

# OR
resolve-user with:
  kind: "linear"
  externalId: "uuid-from-linear"

# OR lookup by email (primary or alias)
resolve-user with:
  email: "[email protected]"

Email lookup is case-insensitive and checks the primary email column AND every entry in emailAliases.