◉doc.ts
traceops.dev

Model

Work Items

Work items are the tenant-scoped records TraceOps.Dev uses to track repository work.

What a work item is

A work item is the durable record for one repository issue, feature, or audit finding. Every work item belongs to one tenant and one repository, and that tenant boundary controls access. For API usage, see API docs.

  • Types: Issue, Feature, AuditFinding.
  • Categories: Security, Bug, Infra, Refactor, Documentation, Performance, TechnicalDebt, Idea.
  • Severities: Critical, High, Medium, Low, Info.
  • Statuses: New, Accepted, Claimed, InProgress, InReview, Fixed, Closed, WontFix.

Fields that matter to users

The core fields are `tenantId`, `repoId`, `workItemId`, `title`, `description`, `severity`, `status`, `source`, `files`, `tags`, `createdBy`, and update timestamps. Assignment and claim metadata help coordination but do not change authorization.

  • assignedTo and assignedToUserKey are optional display and workflow fields.
  • createdByUserKey and assignedToUserKey do not grant tenant access.
  • Claims store claimedBy, claimedAt, and claimExpiresAt.
  • externalBranchName, externalCommitUrl, and externalPrUrl are metadata only.

Lifecycle

The supported lifecycle is create, search, get the next actionable item, claim the work, update status, and optionally attach external links. There is no separate review API beyond moving status to `InReview`, `Fixed`, `Closed`, or `WontFix`.

  • Create: `POST /api/workitems` or `create_workitem`.
  • Search: `GET /api/workitems` or `search_workitems`.
  • Pick next: `GET /api/workitems/next` or `get_next_workitem`.
  • Claim: `PATCH /api/workitems/{workItemId}/claim` or `claim_workitem`.
  • Update status: `PATCH /api/workitems/{workItemId}/status` or `update_workitem_status`.
  • Closeout: move the item to `Fixed`, `Closed`, or `WontFix` as appropriate and attach external links when useful.

How work items relate to tenants, repositories, and users

`tenantId` is the access boundary. `repoId` narrows the work down to one repository within that tenant. A user can only read or update work items when the API considers that user a tenant member.

  • The first hosted website login can create a personal tenant for that user.
  • Shared tenant access requires membership in that tenant.
  • The app-facing work item list can span multiple accessible repositories and return repository options for filtering.

How work items appear in the website

The website currently focuses on browsing work items, not editing them directly. Signed-in users reach the app after using https://traceops.dev/login, and the app then loads tenant-scoped items through the hosted API.

  • Users can filter by repository from the repositoryOptions returned by the API.
  • The cards show status, source, title, description, type, severity, category, created time, and updated time.
  • Personal API key management lives separately under /app/settings/api-keys.
  • Hosted admin pages are operational dashboards for site admins, not a normal user work item editor.

Using MCP with work items

MCP is one of the main ways to create and update work items from coding agents, but it is only another client for the same hosted API workflow. For MCP configuration, see MCP docs.

  • Use create_workitem to add a new issue, feature, or audit finding.
  • Use search_workitems and get_next_workitem to find work in one tenant and repository scope.
  • Use claim_workitem, update_workitem_status, and update_workitem_links as work progresses.