Tickets, OKRs, sprints, releases — first-class.

Quick reference

One tool, eleven kinds.

All structured entities use the unified entity(...) tool. Pass kind to pick the entity and action to pick the operation.

entity(
  action: "list" | "get" | "create" | "update" | "delete",
  kind:   "ticket" | "handoff" | "backlog_view" | "incident" |
          "release" | "experiment" | "goal" | "key_result" |
          "sprint" | "review" | "risk",
  id?:    "<uuid>",          // for get / update / delete
  body?:  { ... },           // for create / update — free-form JSON
  query?: { ... },           // for list — flattened to URL params
  workspace_id?: "<uuid>",   // defaults to active workspace
  project_id?:   "<uuid>",   // defaults to active project
)

The eleven kinds

Pick the right shape for the work.

entity(action="create", kind="ticket", body={
  "title": "Fix replication lag on Oregon read replica",
  "kind": "bug",
  "priority": "high",
  "labels": ["postgres", "infra"],
  "external_ref": "JIRA-1234"
})

entity(action="create", kind="handoff", body={
  "title": "Auth middleware refactor — finish the rotation tests",
  "scope": "tests/auth/*, src/middleware/auth.rs",
  "to_agent": "claude",
  "summary": "Refactor done; 3 of 5 rotation tests pass; the failing 2 hit a clock-skew edge case.",
  "open_questions": ["Should we mock Utc::now() or use tokio::time::pause?"],
  "next_steps": ["Replace Utc::now() in rotate_token with the SystemClock trait"],
  "capsule_id": "<paired ContextCapsule uuid>"
})

entity(action="create", kind="backlog_view", body={
  "name": "Now / Next / Later",
  "bucket": "now",
  "filters": { "status": "open", "kind": "bug" },
  "ticket_order": ["<uuid-a>", "<uuid-b>", "<uuid-c>"]
})

entity(action="create", kind="incident", body={
  "title": "API 500s on /v1/search across all regions",
  "severity": "sev1",
  "status": "investigating",
  "services_affected": ["api", "search"],
  "summary": "Search returning 500 since 14:02 UTC; smoke tests failing."
})

entity(action="create", kind="release", body={
  "version": "1.4.0",
  "status": "released",
  "environments": ["prod", "eu-west"],
  "git_ref": "abc1234",
  "changelog_doc_id": "<release_notes doc uuid>"
})

entity(action="create", kind="experiment", body={
  "name": "Onboarding checklist redesign",
  "hypothesis": "Adding inline progress reduces drop-off in step 3",
  "control": "Current sequential checklist",
  "treatment": "Inline progress bar + collapsed steps",
  "primary_metric": "step_3_completion_rate",
  "secondary_metrics": ["d1_retention", "session_length"]
})

entity(action="create", kind="goal", body={
  "objective": "Ship the platform to 100 paying customers",
  "period": "2026-Q2",
  "owner_user_id": "<uuid>",
  "starts_at": "2026-04-01T00:00:00Z",
  "ends_at": "2026-06-30T23:59:59Z"
})

entity(action="create", kind="key_result", body={
  "goal_id": "<parent goal uuid>",
  "title": "MAU > 10,000",
  "unit": "number",
  "start_value": 6500,
  "current_value": 7200,
  "target_value": 10000
})

entity(action="create", kind="sprint", body={
  "name": "Sprint 42",
  "goal": "Ship taxonomy v1 to GA",
  "starts_at": "2026-04-28T00:00:00Z",
  "ends_at": "2026-05-12T23:59:59Z"
})

entity(action="create", kind="review", body={
  "title": "Security review — new entity tool surface",
  "kind": "security",
  "subject_ref": "github:contextstream/contextstream#1234",
  "reviewer_ids": ["<security-eng uuid>"]
})

entity(action="create", kind="risk", body={
  "title": "Third-party billing API may rate-limit during launch peak",
  "likelihood": "likely",
  "impact": "major",
  "category": "external-dependency",
  "mitigation": "Pre-warm 2x normal capacity; backoff queue with 60s retry"
})

Best practices

A few things that pay off later.

• Use external_ref for jira/linear sync

  Tickets accept external_ref so you can correlate to your system of record. Format is free-form (e.g. 'JIRA-1234' or 'linear:TKT-99').

• Pair handoffs with a ContextCapsule

  Handoffs hold the workflow shell; capsules hold the artifact bundle (export, search results, notes). Set capsule_id when creating a handoff so the recipient gets the bundle.

• Link incidents to tickets and postmortems

  ticket_id and postmortem_doc_id let you walk the chain — from the page event to the bug, to the postmortem doc. Future context() calls surface the chain together.

• Status transitions auto-set timestamps

  Marking a release 'released' fills in deployed_at, marking it 'rolled_back' fills in rolled_back_at. Same for incidents (mitigated_at / resolved_at) and tickets (resolved_at / closed_at).

• Backlogs are saved views, not entities

  A backlog_view is a named ordering + filter spec on tickets. Multiple backlogs (team / personal / now-next-later) coexist freely — tickets are the source of truth.