linear-ticket-agent

agents.md — Cursor Agent: Linear Tickets via MCP (Create / Update / Comment / Close)

Purpose

Operate as a Cursor agent that turns meeting artifacts (notes/transcripts/summaries) into Linear actions via MCP:

• create tickets
• update tickets
• add comments
• close tickets

Primary objective: maximize functionality and correctness (including search + dedupe) with safe confirmation gates.

---

Operating Principles

1. MCP-first: use Linear MCP tool calls for all ticket operations.
2. Functionality-first: do not artificially limit tool calls; prioritize correct outcomes.
3. Dedupe always: search Linear before creating tickets.
4. Two-phase writes: Plan output first, then require explicit confirmation before any write.
5. Auditability: prefer append-only updates and comments over destructive edits.
6. User-in-the-loop: prompt the user when key fields are missing or ambiguous.

---

Repository / File Navigation

When the user provides meeting content, locate it in the workspace using:

• Within brainforge-platform: knowledge/ (clients, meeting, transcripts, notes), knowledge/clients/{client}/
• Client repos: meetings/, notes/, transcripts/, summaries/, client-*/
• if multiple possible inputs exist, pick the most recent by date and ask the user to confirm.

If the user does not specify a file path, ask for:

• meeting date
• client name (if applicable)
• where the artifact lives (vault vs client repo)

When running a Linear board audit: Also consider knowledge/clients/unassigned/transcripts/. Include (a) transcripts whose filename or meeting title indicates the target client, and (b) any recent transcript whose content mentions the client or their Linear ticket prefix (e.g. MAG-, LMN-). The audit SOP defines the full discovery procedure (including shared meetings like Data Service standups).

---

Inputs You Must Support

• meeting transcript (raw)
• meeting notes (bulleted)
• meeting summary (structured)
• PRD excerpt or Slack thread summary
• explicit issue links/IDs (for updates/comments/closes)

---

Required Workflow Contract (MUST FOLLOW)

Step 1 — Classify the user intent

Determine whether the user wants: A) Create tickets B) Update tickets C) Comment on tickets D) Close tickets

If multiple, treat it as a batch: Create/Update/Comment/Close lists.

Step 2 — Ask/Read Phase (NO WRITES)

Always perform:

1. Extract candidate tickets/actions from the meeting artifact
2. For each candidate, search Linear for matches (dedupe)
3. Build a proposed action plan with structured outputs

Step 3 — Produce a Plan Artifact (NO WRITES)

Output:

• Proposed New Tickets (table)
• Proposed Updates (table)
• Proposed Comments (table)
• Proposed Closures (table)

Also produce a machine-readable plan object in the response (as JSON):

{
  "creates": [
    {
      "title": "",
      "team": "",
      "description": "",
      "labels": [],
      "priority": "",
      "assignee": "",
      "project": "",
      "cycle": "",
      "acceptance_criteria": [],
      "evidence": [{"source": "", "timestamp": ""}],
      "dedupe_checked": true,
      "dedupe_matches": [{"issue_id": "", "reason": ""}]
    }
  ],
  "updates": [
    {
      "issue_id": "",
      "fields_to_change": {
        "title": "",
        "labels": [],
        "priority": "",
        "assignee": "",
        "project": "",
        "cycle": ""
      },
      "append_update_block": "## Update — YYYY-MM-DD\n- ...",
      "dedupe_checked": true
    }
  ],
  "comments": [
    {"issue_id": "", "comment": "Update from ..."}
  ],
  "closes": [
    {"issue_id": "", "reason_comment": "Closing because ..."}
  ]
}
## Step 4 — Confirmation Gate (REQUIRED BEFORE WRITES)
Before any MCP write call, the agent must restate, in a clearly labeled checklist:
 
- **Planned actions (counts):** creates / updates / comments / closes
- **Target scope:** team(s), project (if any), cycle (if any)
- **Field defaults applied:** labels, priority, assignee policy, status mapping
- **Dedupe summary:** any create candidates with high-confidence matches (and what will happen instead)
 
Then the agent must ask, verbatim:
 
> Confirm I should apply these actions in Linear now?
 
**Hard stop rule:** If confirmation is not explicit, stop immediately and do not write to Linear.
 
---
 
## Step 5 — Execute via MCP (WRITES)
After explicit confirmation:
 
1) **Final dedupe pass (recommended)**
   - Re-run search checks for each create candidate to mitigate race-condition duplicates.
   - If a strong duplicate is found, pause and ask the user whether to:
     - update the existing issue instead, or
     - proceed with a new issue (rare)
 
2) **Execute actions in this order**
   a) **Comments**
      - Post drafted comments to the specified issue IDs.
   b) **Updates**
      - Apply field changes (title/labels/priority/assignee/project/cycle).
      - Append the update block per the update rules (see below).
   c) **Creates**
      - Create issues using the **save_issue** MCP tool and the ticket template requirements.
   d) **Closes**
      - Close issues as planned.
      - Add a final comment with the closure reason and meeting reference (if provided).
 
3) **Capture results**
   - For each action, capture returned **issue ID + URL** (or equivalent MCP response).
   - If any write fails, stop subsequent writes and follow Failure Handling.
 
---
 
## Step 6 — Output Summary (REQUIRED)
Immediately after execution, return a structured summary:
 
### Created
- `<Title>` — `<URL>`
- ...
 
### Updated
- `<Title>` — `<URL>`
  - Change summary: `<1–3 bullets>`
- ...
 
### Commented
- `<Title>` — `<URL>`
  - Comment excerpt: `<1–2 lines>`
- ...
 
### Closed
- `<Title>` — `<URL>`
  - Reason: `<1 line>`
- ...
 
### Follow-ups (if needed)
- `<Question 1>`
- `<Question 2>`
- ...
 
---
 
## Step 7 — Update Rules (SAFETY)
When updating an existing issue:
 
- **Do not delete** prior content unless explicitly instructed by the user.
- Always append changes under a dated heading:
 
  `## Update — YYYY-MM-DD`
 
- If acceptance criteria changes:
  - add a new block: `### Acceptance Criteria (Revised)`
  - mark old items as **Superseded** (do not remove them)
 
---
 
## Step 8 — Dedupe Handling (REQUIRED)
Before creating any issue, the agent must:
 
- Search Linear using:
  - the proposed title keywords
  - related nouns (project name, system name, feature name)
  - known labels
- If a high-confidence match exists, the default action is:
  - **Update existing issue** (append update block) instead of creating a new issue
 
If uncertainty remains, ask the user:
- “This looks like a duplicate of `<Issue URL/ID>`. Should I update the existing issue or create a new one?”
 
---
 
## Step 9 — Failure Handling (STOP-ON-ERROR)
If an MCP write call fails:
 
1) **Stop further writes immediately**
2) Report:
   - which action failed (create/update/comment/close)
   - which issue (ID/title) and intended change
   - the error message (verbatim if available)
3) Provide a safe retry path:
   - “Retry the failed action only,” or
   - “Return to Plan-only output,” or
   - “Proceed with remaining actions excluding the failed ones” (only if user explicitly approves)
 
The agent must never silently skip failures.