Issue tracker

Work items for calab-mocks live in the calab-ai Linear workspace (https://linear.app/calab). Skills that create, triage, or fetch tickets (to-tickets, triage, to-spec, and Calab equivalents such as to-issues / to-prd) must read and write Linear — not GitHub Issues, and not local markdown under .scratch/.

Where issues live

  • Workspace: calab-ai (https://linear.app/calab)
  • Default team: intl-mocks (key MOC)
  • Fallback team: gl04-technology (key GL04) for platform or agent-infrastructure work that is not mocks-specific
  • Conventions: docs/linear-work-items.md
  • Triage and Type labels: docs/triage-labels.md

Verify live team names with linear team list. Names can change; keys are stabler.

How to interact

Use the linear CLI (user-scope skill) or Linear MCP tools. Do not use gh issue to create or manage Calab work items.

Typical CLI shape:

linear issue create "Title" --team <team-id> --body-file <file>
linear issue view MOC-18
linear issue list --team <team-id>
linear team list
linear team states <team-id>

When publishing a ticket, follow the entity mapping and team routing in linear-work-items.md: set parent and project at creation time, then record blocking or related links with Linear relations. When fetching a ticket, use linear issue view <identifier> or the Linear MCP equivalent.

Where to do the work

When the work is on a local machine, isolate it in a git worktree (git worktree add) instead of switching the primary checkout between branches. A cloud agent that already has its own checkout can stay there.

Pull requests

PRs stay on GitHub. Link them to Linear with a branch name that contains the issue id and a magic word such as Fixes MOC-18 or Refs MOC-18. Automation branches may use the copilot/ or cursor/ prefix.

GitHub Issues remain enabled as a fallback and as Linear sync targets. They are not the primary tracker. Do not disable them from this repository until GL04-76 lands.

PRs as a request surface

Off. External pull requests are not added to the triage queue automatically.

Wayfinding operations

/wayfinder maps and tickets live in Linear on intl-mocks (MOC) unless routing says otherwise.

  • Map: one Linear issue (Type Task). Put wayfinder: map in the title or first line of the description. Do not create a new workspace label unless a maintainer adds one.

    This repo has no pull-request title check yet. calab-ai/neuralops-accelerator does (.github/workflows/pr-title-checker.yml, Conventional Commits). A title that is only wayfinder: map … fails that check, because wayfinder is not an allowed type. Keep the marker and still pass by putting a real type first:

    docs: wayfinder: map how project fakes are laid out

    The subject still contains wayfinder: map. If the title is already a normal docs: or feat: line, put wayfinder: map on the first line of the description instead.

  • Tickets: Linear sub-issues of the map. Record the ticket type (research, prototype, grilling, task) in the description.

  • Blocking: native Linear blocking relations (linear issue relate <blocker> <blocked> --type blocks), defined once per direction.

  • Frontier: open sub-issues of the map with no open blockers and no assignee.

  • Claim: assign the Linear issue to the person or coding agent driving the session before any work.

  • Research findings: Linear Document on the relevant Project, with a link comment on the ticket. Commit to git only when durable and reviewed.