linear-workflow

Linear Workflow

Claude Code plugin for planning and implementing software with Linear and GitHub. Intended to work equally well with vanilla claude code running locally or as a self hosted Linear Agent driving the claude code sdk command line tool.

What This Does

This plugin provides two skills that drive an adversarial plan-implement-review cycle. Linear is the source of truth for work; code ships through GitHub PRs. The cycle works like this:

1. A feature is described as a Linear ticket.
2. Plan — An agent explores the codebase, creates a new primary issue with a structured plan and phased sub-tickets, then marks the original ticket Done.
3. Implement — For each sub-ticket, an agent-team orchestrator dispatches teammates to:
   • Implement the sub-issue (branch, code, tests, PR).
   • Run adversarial code review (round 1).
   • Fix round 1 findings.
   • Run adversarial code review (round 2).
   • Fix round 2 findings.
   • Run a final review gate — if critical/important findings remain, the issue enters needs-human-review and the skill stops.
   • Wait for CI; fix failures
   • Merge to base branch.
4. Repeat for all remaining sub-tickets, then sweep for follow-ups.
5. Summary posted back to the primary issue with wall clock timing.

The skills are project-agnostic — they read conventions (build commands, test strategy, commit format) from the target repo's CLAUDE.md or AGENTS.md rather than encoding them in the plugin.

Installation

claude plugin marketplace add holos-run/skills

claude plugin install linear-workflow@holos-run

Skills

Skill	Purpose
/linear-workflow:plan-issue	Explore codebase, create a new primary issue with phased sub-tickets, relate back to original
/linear-workflow:implement-issue	Implement any Linear ticket: leaf issues directly, parent issues via agent-team orchestration

Typical Workflow

# 1. Plan — creates a new primary issue with sub-tickets
/linear-workflow:plan-issue APP-123

# 2. Implement — orchestrates all sub-tickets under the new primary
/linear-workflow:implement-issue APP-234

implement-issue self-detects whether the ticket has children:

• No children → implements directly (branch, code, PR, review, CI, merge)
• Has children → spawns an agent-team, dispatches a teammate per sub-ticket

Prerequisites

• Linear MCP server configured (see below)
• GitHub CLI (gh) authenticated with repo access
• Git with a clean working directory
• Agent teams enabled for parent-mode orchestration (see below)

Enable Agent Teams

Parent-mode orchestration requires Claude Code agent-teams (experimental):

claude config set -g env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 1

Linear MCP Configuration

Both Claude and any external review tools need persistent access to Linear. The key pattern is mcp-remote with a Linear API key managed through direnv and your system keychain.

Load the API key securely via direnv. Add to your project .envrc:

export LINEAR_API_KEY="$(ks show LINEAR_API_KEY)"

This uses ks (keychain-store) to retrieve the key at shell init rather than storing it in plaintext.

Copy this to ~/.local/bin/linear-server and make executable.

#! /bin/bash
# Avoid reauth interruptions with an API key. install with:
#   claude mcp remove linear-server
#   claude mcp add linear-server --scope user -- ~/.local/bin/linear-server
set -euo pipefail
if [[ -z "${LINEAR_API_KEY}" ]]; then
  echo "empty LINEAR_API_KEY" >&2
  exit 1
fi
exec npx mcp-remote https://mcp.linear.app/mcp --header "Authorization: Bearer ${LINEAR_API_KEY}"

Then configure the MCP:

claude mcp add linear-server --scope user -- ~/.local/bin/linear-server

Configuring Code Review

The implement-issue skill runs adversarial code review on every PR (up to 2 fix rounds + a final gate check). It looks for a review command in the target repo's CLAUDE.md or AGENTS.md. If none is found, it falls back to a Claude sub-agent review.

How the skill resolves the review command

1. Look in CLAUDE.md or AGENTS.md for a section headed ## Code Review
2. Find a fenced code block containing a shell command
3. Substitute $PR_NUMBER, $BRANCH, and $REPO into the command
4. Execute and parse stdout for: APPROVE, REQUEST_CHANGES, [CRITICAL], [IMPORTANT], [STYLE]

If no ## Code Review section is found, the skill spawns a Claude sub-agent to review the PR diff. This works everywhere but is less adversarial than using a separate model.

Example: Codex CLI for adversarial review (recommended)

Add this to your project's CLAUDE.md:

## Code Review