mcpField
L
linear-doctor

linear-doctor

github.com/lkshrkAgent workflows141 installsUpdated 4w ago
Repository

About linear-doctor

linear-doctor is a setup-check skill for agents using Linear workflows. It validates live teams, projects, and labels, reports missing setup, and guides the next workflow step.

Key features

  1. 01Read-only setup diagnosis
  2. 02Capture and validate Linear metadata
  3. 03Check workflow, phase, and claim labels
  4. 04Report evidence and missing setup
  5. 05Recommend the next workflow skill

Use cases

  1. 01Check Linear setup before running a workflow
  2. 02Find missing labels or target teams and projects
  3. 03Verify setup when its state is uncertain

MCP support

Uses available Linear MCP read tools to inspect teams, projects, and labels. It can report required mutations when write tools or label creation are unavailable.

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/lkshrk/linear-ai --skill linear-doctor

After installing, type/linear-doctorin Claude Code to confirm it loaded.

Bundled filesagents/openai.yamlscripts/linear_metadata.ts

Details

From the project README

Linear Doctor

Use this as the setup check before workflow execution or when setup state is uncertain.

Linear MCP Contract

Use these Linear MCP tools when available:

  • list_teams - read available teams.
  • list_projects - read available projects and their teams.
  • list_issue_labels - read type, component, LLM, and Superpowers labels.
  • save_issue is not required; setup diagnosis is read-only unless the agent is explicitly asked to fix an existing issue.

Capture and validate live metadata with:

scripts/linear_metadata.ts capture --teams linear-teams.json --projects linear-projects.json --labels linear-labels.json > linear-metadata.json
scripts/linear_metadata.ts validate --metadata linear-metadata.json

Use the local JavaScript package manager or runtime available to the agent: Bun can run the .ts scripts directly; Node/npm/pnpm/yarn environments should run them through a TypeScript runner such as tsx.

If Linear MCP read tools are unavailable, ask for exported teams, projects, and labels. If Linear MCP write tools are unavailable or label creation is not supported, emit REQUIRED_LINEAR_MUTATIONS with exact setup changes.

Required Setup

Report missing llm-* workflow labels:

  • llm-refine
  • llm-ready
  • llm-active
  • llm-blocked
  • llm-review

Report the missing claim lock label (outside the llm-* state machine):

  • in-use

Report missing sp-* Superpowers phase labels:

  • sp-clarify
  • sp-plan
  • sp-implement
  • sp-review
  • sp-verify

Report missing component labels, type labels, target teams, and target projects. Component/type/project names are workspace-specific, so propose likely values from live Linear metadata instead of hardcoding stale lists.

Step Completion Handoff

Report:

  • Current phase
  • What changed, if this doctor pass repaired or clarified setup
  • Evidence from live teams, projects, and labels
  • Missing evidence
  • Open blocker
  • Recommended next step
  • Recommended next skill

Ask if there is anything else to add for this setup step. If yes, continue the current step by checking that setup item. If no, recommend moving to the next workflow step, normally linear-create-issue for a new issue or linear-status for an existing issue.

After the add-more question is answered "no", ask whether the user wants to continue with the recommended next skill. Name the recommended next skill explicitly and wait for user confirmation; do not auto-run it.

Use this response shape:

  • Current phase
  • What changed
  • Evidence
  • Missing evidence
  • Open blocker
  • Recommended next step
  • Recommended next skill
  • Question: Is there anything else to add before moving on?
  • Question: Do you want to continue with the recommended next skill?

Stop when setup is either ready or the exact REQUIRED_LINEAR_MUTATIONS list identifies missing labels/projects/statuses.

Comments

Markdown supported