vb-linear
Shared reference other VibeRig skills point to for Linear access. This skill is not a workflow entry point on its own — it centralizes tool selection and rules that would otherwise be duplicated (and drift) across every Linear-touching skill. Target ids (team/project) and output language for every Linear operation come from .vibeRig/project.yaml.
MCP Server
VibeRig ships its own Linear MCP server declaration at the plugin root: .mcp.json (Claude Code), .codex.mcp.json (Codex), mcp.json (Cursor). The server key is vb-linear, pointing at Linear's official hosted MCP server (https://mcp.linear.app/mcp). No separate Linear account setup is required ahead of time — vb-init verifies login with a read-only probe before it registers a Project, and triggers the OAuth flow on the spot if the probe shows the host isn't logged in yet.
Hosts frequently also expose a Linear-capable tool from somewhere else — a platform-native connector, a user-level global MCP entry, another installed plugin. These can look identical (same tool names, same capability) but are not this server: they may be logged into a different Linear account/workspace, and they sit outside this plugin's config so future changes here won't reach them.
- Only use tools that resolve to the
vb-linear server declared in this plugin's own mcp config. Fully-qualified tool names carry the server identity (e.g. mcp__vb-linear__get_issue); when a host doesn't qualify names and more than one Linear-capable source is present, do not guess — tell the user there are multiple Linear sources available and ask which to use.
- If Linear tools are unavailable entirely, summarize the intended record in chat and stop — never claim Linear was updated when it wasn't.
Capability Map
Callers ask for a capability; this is what it resolves to.
| Capability |
Resolves to |
Notes |
| Read an issue |
get_issue |
Title, description, status, labels, assignee, comments. |
| Find an issue/project by free text |
search |
Use when no exact id/key is known. |
| Enumerate issues |
list_issues |
Filter by parent (sub-issues of a requirement), team, project, or status. |
| Resolve a team's workflow states |
list_issue_statuses |
Required before any status change — see Status Mapping Rule. |
| Reuse or create a label |
list_issue_labels / create_issue_label |
Check existing labels before creating new ones. |
| Read prior comments |
list_comments |
Prior analysis, proof packets, acceptance records. |
| Create or update an issue |
save_issue |
Title, description, status, labels, parentId, project, team, blockedBy/blocks. |
| Write a comment |
save_comment |
Analysis, proof packet, acceptance record, plan-sync summary. |
| Write lifecycle content |
Issue comment or Project Update, selected by host type |
Execution brief, phase summary, repair note, proof packet, or plan-sync summary. Issue-scoped records use comments; Milestone/requirement aggregate records use the registered Project's Project Updates because Milestones have no comments. |
| Resolve a team |
list_teams / get_team |
Typically during vb-init. |
| Find or create the registered project |
list_projects / save_project |
Search before creating. |
| Find or create the Project Document |
list_documents / save_document |
Typically during vb-init. |
| Read or create a milestone |
list_milestones / get_milestone / save_milestone |
split-milestones creates (check for duplicates first); task-runner / accept-milestone read. Milestone description holds only a Document link + local contract path + AC-ids — never the full document text. |
| Read or write a status update (Project Update) |
get_status_updates / save_status_update |
accept-milestone writes health/progress after milestone acceptance. |
VibeRig Event Record Hosts
VibeRig event records must use one real, searchable host for their entire lifecycle:
- Issue / sub-issue acceptance → that Issue's comments (
list_comments / save_comment).
- Issue execution brief, progress, repair, and proof → that Issue's comments (
list_comments / save_comment).
- Milestone execution aggregate, plan publication summary, and proof → the registered Linear Project's Project Updates (
get_status_updates / save_status_update).
- Milestone acceptance, Milestone delivery, requirement aggregation, and PRD/requirement finalization → the registered Linear Project's Project Updates (
get_status_updates / save_status_update). Milestones do not have a comment capability.
Put <!-- VibeRig-Event: <event-id> --> in every event record, plus a typed marker <!-- VibeRig-Record: <kind>:<event-id> -->. Use kind: acceptance for the single acceptance record, retrospective for the single insights record, delivery-intent for the pre-merge write-ahead record, delivery for the canonical pending delivery record, and phase for append-only state overlays. For acceptance, retrospective, delivery-intent, or delivery, zero exact typed-marker matches permits one write, one structurally valid match is adopted, and multiple/malformed/conflicting matches fail closed; never append a second canonical record. Retrospective adoption ignores other legitimate kinds; phase recovery selects the newest structurally valid typed phase record while preserving earlier references. Search/write only within the mapped host and registered project. Never write acceptance or delivery intent to one host and later search another. Callers refer to the result generically as a linear_record; an Issue result may additionally expose comment_id, while a Project Update exposes status_update_id.
Lifecycle status and lifecycle content are separate projections. A successful status change never proves that the execution brief, plan summary, or Proof Packet was recorded. Callers that require both must persist two intents, write/read back both projections, and ack them independently. Content read-back matches the exact typed marker and payload fingerprint, not merely the target's current status.
Lifecycle Projection
Resolve the team's actual workflow states before any status change.
- Never invent a status name that doesn't exist in the team's workflow.
- If no matching status exists for the intended lifecycle state, leave the current status unchanged and record the intended state in a comment instead.
- Callers request a semantic transition; all callers use the canonical table in lifecycle-projection.md. Do not redefine lifecycle mapping independently in
execute、task-runner、accept-deliver or split skills.
Before an external write, the caller persists an intent/outbox item with stable event id, host identity and payload fingerprint. After the tool call, read back the target and ack only when the observed state or typed marker matches. Tool timeout or lost response is recovered by search/adopt, not blind retry.
Language Policy
Read .vibeRig/project.yaml output.language and use it for all human-facing Linear content: issue titles, descriptions, comments, and plan-sync summaries.
- If
output.language is missing, infer the language from the user's current working language, state the fallback, and recommend reconciling project.yaml through vb-init.
- Do not translate stable IDs, file paths, commands, branch names, PR URLs, commit hashes, Linear keys, AC IDs, schema field names, code symbols, log excerpts, or existing external labels/status names.
- If source material (requirement docs, error output, user-provided acceptance text) is in a different language, write new human-facing Linear text in
output.language and preserve exact technical identifiers.
Ownership Invariant
Only the main agent reads and writes Linear. Subagents must not update Linear status, write Linear comments, or make final acceptance calls — they return phase evidence and a verdict only. The main agent is responsible for all Linear writes after a subagent's work completes.
Red Flags
- A caller names a specific Linear tool instead of describing the capability it needs → route it through this skill's Capability Map instead.
- A skill requests a status change without resolving workflow states first → resolve states first, every time.
- A caller maps
technically_ready to a completed/Done state → reject; technical completion is always non-terminal.
- A caller requests
done without a current human acceptance event and required delivery proof → reject.
- A skill creates an issue without checking for an existing match first → duplicate issues corrupt the plan; check before creating.
- A subagent's output implies a Linear write happened → subagents return evidence only; the calling skill's main agent performs the write.
- A skill claims a Linear update succeeded when tools were unavailable → summarize in chat and say so explicitly instead.
- More than one Linear-capable tool source is present and the caller can't tell which is the
vb-linear server → stop and ask the user, don't guess.
1---2name: vb-linear3description: Shared Linear access reference for VibeRig skills. Consult whenever a VibeRig skill needs to read or write Linear (issues, comments, statuses, labels, projects, teams, documents, milestones, status updates). Not a standalone user-facing workflow.4---56# vb-linear78Shared reference other VibeRig skills point to for Linear access. This skill is not a workflow entry point on its own — it centralizes tool selection and rules that would otherwise be duplicated (and drift) across every Linear-touching skill. Target ids (team/project) and output language for every Linear operation come from `.vibeRig/project.yaml`.910## MCP Server1112VibeRig ships its own Linear MCP server declaration at the plugin root: `.mcp.json` (Claude Code), `.codex.mcp.json` (Codex), `mcp.json` (Cursor). The server key is **`vb-linear`**, pointing at Linear's official hosted MCP server (`https://mcp.linear.app/mcp`). No separate Linear account setup is required ahead of time — `vb-init` verifies login with a read-only probe before it registers a Project, and triggers the OAuth flow on the spot if the probe shows the host isn't logged in yet.1314Hosts frequently also expose a Linear-capable tool from somewhere else — a platform-native connector, a user-level global MCP entry, another installed plugin. These can look identical (same tool names, same capability) but are **not** this server: they may be logged into a different Linear account/workspace, and they sit outside this plugin's config so future changes here won't reach them.1516- Only use tools that resolve to the `vb-linear` server declared in this plugin's own mcp config. Fully-qualified tool names carry the server identity (e.g. `mcp__vb-linear__get_issue`); when a host doesn't qualify names and more than one Linear-capable source is present, do not guess — tell the user there are multiple Linear sources available and ask which to use.17- If Linear tools are unavailable entirely, summarize the intended record in chat and stop — never claim Linear was updated when it wasn't.1819## Capability Map2021Callers ask for a capability; this is what it resolves to.2223| Capability | Resolves to | Notes |24|---|---|---|25| Read an issue | `get_issue` | Title, description, status, labels, assignee, comments. |26| Find an issue/project by free text | `search` | Use when no exact id/key is known. |27| Enumerate issues | `list_issues` | Filter by `parent` (sub-issues of a requirement), team, project, or status. |28| Resolve a team's workflow states | `list_issue_statuses` | Required before any status change — see Status Mapping Rule. |29| Reuse or create a label | `list_issue_labels` / `create_issue_label` | Check existing labels before creating new ones. |30| Read prior comments | `list_comments` | Prior analysis, proof packets, acceptance records. |31| Create or update an issue | `save_issue` | Title, description, status, labels, `parentId`, `project`, `team`, `blockedBy`/`blocks`. |32| Write a comment | `save_comment` | Analysis, proof packet, acceptance record, plan-sync summary. |33| Write lifecycle content | Issue comment or Project Update, selected by host type | Execution brief, phase summary, repair note, proof packet, or plan-sync summary. Issue-scoped records use comments; Milestone/requirement aggregate records use the registered Project's Project Updates because Milestones have no comments. |34| Resolve a team | `list_teams` / `get_team` | Typically during `vb-init`. |35| Find or create the registered project | `list_projects` / `save_project` | Search before creating. |36| Find or create the Project Document | `list_documents` / `save_document` | Typically during `vb-init`. |37| Read or create a milestone | `list_milestones` / `get_milestone` / `save_milestone` | `split-milestones` creates (check for duplicates first); `task-runner` / `accept-milestone` read. Milestone description holds only a Document link + local contract path + AC-ids — never the full document text. |38| Read or write a status update (Project Update) | `get_status_updates` / `save_status_update` | `accept-milestone` writes health/progress after milestone acceptance. |3940## VibeRig Event Record Hosts4142VibeRig event records must use one real, searchable host for their entire lifecycle:4344- Issue / sub-issue acceptance → that Issue's comments (`list_comments` / `save_comment`).45- Issue execution brief, progress, repair, and proof → that Issue's comments (`list_comments` / `save_comment`).46- Milestone execution aggregate, plan publication summary, and proof → the registered Linear Project's Project Updates (`get_status_updates` / `save_status_update`).47- Milestone acceptance, Milestone delivery, requirement aggregation, and PRD/requirement finalization → the registered Linear Project's Project Updates (`get_status_updates` / `save_status_update`). Milestones do not have a comment capability.4849Put `<!-- VibeRig-Event: <event-id> -->` in every event record, plus a typed marker `<!-- VibeRig-Record: <kind>:<event-id> -->`. Use `kind: acceptance` for the single acceptance record, `retrospective` for the single insights record, `delivery-intent` for the pre-merge write-ahead record, `delivery` for the canonical pending delivery record, and `phase` for append-only state overlays. For acceptance, retrospective, delivery-intent, or delivery, zero exact typed-marker matches permits one write, one structurally valid match is adopted, and multiple/malformed/conflicting matches fail closed; never append a second canonical record. Retrospective adoption ignores other legitimate kinds; phase recovery selects the newest structurally valid typed phase record while preserving earlier references. Search/write only within the mapped host and registered project. Never write acceptance or delivery intent to one host and later search another. Callers refer to the result generically as a `linear_record`; an Issue result may additionally expose `comment_id`, while a Project Update exposes `status_update_id`.5051Lifecycle status and lifecycle content are separate projections. A successful status change never proves that the execution brief, plan summary, or Proof Packet was recorded. Callers that require both must persist two intents, write/read back both projections, and ack them independently. Content read-back matches the exact typed marker and payload fingerprint, not merely the target's current status.5253## Lifecycle Projection5455Resolve the team's actual workflow states before any status change.5657- Never invent a status name that doesn't exist in the team's workflow.58- If no matching status exists for the intended lifecycle state, leave the current status unchanged and record the intended state in a comment instead.59- Callers request a semantic transition; all callers use the canonical table in [lifecycle-projection.md](./references/lifecycle-projection.md). Do not redefine lifecycle mapping independently in `execute`、`task-runner`、`accept-deliver` or split skills.6061Before an external write, the caller persists an intent/outbox item with stable event id, host identity and payload fingerprint. After the tool call, read back the target and ack only when the observed state or typed marker matches. Tool timeout or lost response is recovered by search/adopt, not blind retry.6263## Language Policy6465Read `.vibeRig/project.yaml` `output.language` and use it for all human-facing Linear content: issue titles, descriptions, comments, and plan-sync summaries.6667- If `output.language` is missing, infer the language from the user's current working language, state the fallback, and recommend reconciling `project.yaml` through `vb-init`.68- Do not translate stable IDs, file paths, commands, branch names, PR URLs, commit hashes, Linear keys, AC IDs, schema field names, code symbols, log excerpts, or existing external labels/status names.69- If source material (requirement docs, error output, user-provided acceptance text) is in a different language, write new human-facing Linear text in `output.language` and preserve exact technical identifiers.7071## Ownership Invariant7273Only the main agent reads and writes Linear. Subagents must not update Linear status, write Linear comments, or make final acceptance calls — they return phase evidence and a verdict only. The main agent is responsible for all Linear writes after a subagent's work completes.7475## Red Flags7677- A caller names a specific Linear tool instead of describing the capability it needs → route it through this skill's Capability Map instead.78- A skill requests a status change without resolving workflow states first → resolve states first, every time.79- A caller maps `technically_ready` to a completed/Done state → reject; technical completion is always non-terminal.80- A caller requests `done` without a current human acceptance event and required delivery proof → reject.81- A skill creates an issue without checking for an existing match first → duplicate issues corrupt the plan; check before creating.82- A subagent's output implies a Linear write happened → subagents return evidence only; the calling skill's main agent performs the write.83- A skill claims a Linear update succeeded when tools were unavailable → summarize in chat and say so explicitly instead.84- More than one Linear-capable tool source is present and the caller can't tell which is the `vb-linear` server → stop and ask the user, don't guess.
jsonlee12138