Work items: Linear
Work items for this repository live in Linear (https://linear.app/calab) — issues, sub-issues, projects, milestones, project documents, initiatives, and customer requests.
Interact with Linear via the linear CLI (user-scope skill) or Linear MCP tools. Do not use gh issue to create or manage Calab work items.
This document is the source of truth for work-item conventions in calab-mocks. .github/instructions/linear-issues.instructions.md is a thin pointer to it. Engineering skills that need an issue-tracker description read docs/agents/issue-tracker.md.
Entity mapping
| Concept | Linear object |
|---|---|
| Value stream / strategic programme | Initiative |
| Plan | Project (a small single-outcome plan = a single Issue with sub-issues) |
| PRD / Spec | Project document (issue description for small plans) |
| Plan phase | Project milestone |
| Client ask | Customer Request |
| Task | Issue |
| Issue breakdown | Sub-issues (see below) |
Sub-issues are not a fixed "step" level. Use them when an issue is large enough that it should be broken down — as a rule of thumb, more than about 21 hours of effort — or to plan the separation of small stacked PRs under one parent issue. Sub-issues can nest multiple levels when the root parent issue requires it.
Category types map to the workspace Type label group: Bug, Feature, Improvement, Problem, Request, Task, and Incident. See triage-labels.md.
Team routing
Work items go to the Linear team that owns the work. Team names change, so verify live names with linear team list (or the Linear MCP equivalent) rather than trusting remembered names. Team keys are stabler references.
| Work type | Linear team (verify live) | Key |
|---|---|---|
| This repository's product and engineering work | intl-mocks | MOC |
| Platform, agent infrastructure, technology content | gl04-technology | GL04 |
| Governance / value streams / org model | gl01-executive | GL01 |
| Sales content and ops | gl02-sales | GL02 |
| Delivery content and products | gl03-delivery | GL03 |
| Administration and operations content | gl05-operations | GL05 |
| Client or product delivery work | The owning squad team | varies |
Default to intl-mocks (MOC) for work in this repository unless the change is clearly platform or agent-infrastructure (GL04) or belongs to another owner above.
This repository is the fakes estate. Do not file NeuralOps consumer-connection work here — that belongs on the owning NeuralOps team.
Relationships
Use Linear's native relations — they are the link of record:
- Sub-issue (parent/child) — set the parent when creating the child. A sub-issue has exactly one parent.
- Blocking / blocked-by — define each directed dependency once; Linear shows the reciprocal automatically.
- Project membership — add issues that belong to a plan to that plan's Project.
- Duplicates — mark duplicate so Linear moves the duplicate to the system-managed Duplicate status and links it to the canonical issue. Attachments and customer requests migrate; comment threads are not merged — copy unique details to the canonical issue first.
Body-text references are optional context for readers, not the link of record.
Workflow rules
- Every Project should have at least one issue; break an issue into sub-issues when it is large enough to warrant it (roughly more than 21 hours of effort) or to plan a set of small stacked PRs (nesting further levels as needed).
- Every item must include a clear title, a short description (what and why), and acceptance criteria.
- Not every issue must roll up to a Project: small, self-contained work may stand alone.
- Avoid duplicate issues: search by similar titles before creating; use Mark duplicate when applicable.
- Audit trails live in Linear's activity log — do not maintain CHANGELOG-file audit conventions for work tracking.
- Use existing labels only. Ask a maintainer to add a missing workspace label rather than creating one ad hoc.
- Confirm the target team's statuses with
linear team states <team-id>before relying on a specific status name. - When raising an issue, say whether the change is local-only (
docker compose), Azure (azd/ landing-zone RGs), or both.
Description best practices
- Keep descriptions concise and specific.
- For Projects, include a brief overview in the project description; attach the PRD as a project document.
- For Features, Improvements, and Bugs, state the problem or opportunity, desired outcome, and acceptance criteria. For Bugs, add steps to reproduce, expected versus actual behaviour, and relevant logs or screenshots.
- For sub-issues, state the action and relevant links or dependencies. Prefer imperative phrasing (for example, "Add Linear work-item instructions").
- Include
Acceptance Criteria:andOut of Scope:sections when helpful.
PR linking
Pull requests stay on GitHub. Linear links PRs to issues when:
- Branch names contain the issue identifier, for example
feat/MOC-12-container-apps. - Magic words appear in the PR title or description, for example
Fixes MOC-18orRefs MOC-18.
Use both where practical. Branch and PR titles still follow this repository's Conventional Commit conventions. Automation branches may use the copilot/ or cursor/ prefix.
Agent delegation
To hand an issue to an AFK coding agent, assign the Linear issue to the coding agent from Linear. The agent still raises a draft PR on GitHub; kickoff is from Linear. Prefer Cursor cloud or agent workflows where the team has standardized on Cursor.
Interim documents
Publish interim or collaborative research as a Linear Document attached to the relevant Project, and leave a link comment on related issues. Commit to the repository (for example under docs/) only when the content is durable and a maintainer has reviewed it.
Handoffs
Publish a session handoff as a Linear issue with the workspace handoff label, routed per the team table, unassigned by default.
linear CLI conventions
These commands refer to the user-scope linear-cli skill (invoked as linear <resource> <action>), not a public npm package with a similar name. Prefer the linear CLI or Linear MCP tools; both are valid.
- Create:
linear issue create "Title" --team <team-id> --body-file <file> [--parent MOC-N] [--project <project-id>] - Read:
linear issue view MOC-N - List:
linear issue list --team <team-id> [--status <name>] [--label <name>] - Comment:
linear issue comment MOC-N <text> - Update:
linear issue update MOC-N --status <name> --assignee <id> --add-label <name> - Triage actions:
linear issue snooze MOC-N [--days <n>],linear issue unsnooze MOC-N,linear issue duplicate MOC-N <canonical> - Relations:
linear issue relate MOC-A MOC-B --type blocks|related|similar(defaultblocks) - Projects / milestones / documents:
linear project create|update,linear milestone create|update,linear document create|update(team-scoped documents:document create --team) - Teams / states / labels:
linear team list,linear team states <team-id>,linear label list --team <team-id>
When paginating labels via the GraphQL API, page through all results — a single first: N query can miss workspace labels in a workspace with many teams.
When asked to publish to the issue tracker
Create a Linear issue following the entity mapping and team routing above. Set parent and project at creation time with --parent and --project. After create, record blocking or related links with linear issue relate … --type blocks|related|similar (see Relations above).
When asked to fetch the relevant ticket
Run linear issue view <identifier> or the Linear MCP equivalent.