What is the Parent -> Subs pattern?

Parent contains WHAT + WHY + acceptance criteria (no implementation details); Sub-Issues contain the HOW with implementation steps and specifics.

When is HotFix allowed?

Only for single-line fixes with no subs; otherwise create a parent issue with 3+ subs.

Which commands manage issues and milestones?

Create: mcp__linear-server__create_issue; List: mcp__linear-server__list_issues; Get: mcp__linear-server__get_issue; Update: mcp__linear-server__update_issue; Manage milestones via mcp__linear-server__create_milestone / mcp__linear-server__list_milestones.

linear-workflow

Scanned

npx machina-cli add skill srobinson/helioy-plugins/linear-workflow --openclaw

Files (1)

SKILL.md

3.2 KB

Linear Workflow — Ways of Working

Core Pattern: Parent -> Subs

Every non-trivial feature uses the parent/sub-issue pattern:

Parent Issue = the WHAT + WHY + acceptance criteria
- Optimized for agent consumption, not human reading
- Lean is mean. Anti-verbosity.
- This content gets fed into every worker agent
Sub-Issues = the HOW — implementation steps with detail
- Each sub is a discrete, completable unit of work
- ~1-4 hours of focused implementation
- Can be completed independently when possible

Issue Sizing

Size	Sub-issues	Example
Small	3-10	Add user profile export
Medium	10-30	Implement auth system (group by component)
Large	30-100+	Build analytics dashboard (group by phase)

Rules

Always assign a project. If basename $(pwd) matches a project, use it. If not, ask.
Set state to Todo when the issue is ready for work.
No parent issues with only 1 sub-issue — that's unnecessary overhead.
3+ subs minimum for parent issues, or use HotFix label instead.
HotFix label only — the sole case where a parent works without subs: typos, dependency bumps, single-line fixes.

Creating Issues

Use the Linear MCP tools to manage issues. All issues go to team Alphabio unless specified otherwise.

Parent Issue

Create with mcp__linear-server__create_issue:

title: Feature/outcome in imperative form
team: "Alphabio"
description: WHAT (1-2 sentences) + WHY (business/technical value) + acceptance criteria (bullet list, testable). NO implementation details.
project: Required — match basename $(pwd) if applicable, otherwise ask
priority: Match urgency (1=Urgent, 2=High, 3=Normal, 4=Low)
state: "Todo" when ready for work
labels: Add "HotFix" for single-line fixes (no subs needed)

Sub-Issues

Create with mcp__linear-server__create_issue with parentId:

title: Specific implementation step
parentId: Parent issue ID
description: HOW to implement + dependencies on other subs + specific files/modules affected
priority: Inherit from parent unless different

Querying and Updating

mcp__linear-server__list_issues — find existing issues (filter by project, assignee, state, label)
mcp__linear-server__get_issue — get full issue detail including attachments and branch name
mcp__linear-server__update_issue — change state, assignee, priority, description, or link issues
mcp__linear-server__list_projects / mcp__linear-server__get_project — find/verify project
mcp__linear-server__list_issue_statuses — discover available states for a team
mcp__linear-server__list_issue_labels — discover available labels
mcp__linear-server__create_milestone / mcp__linear-server__list_milestones — manage milestones
mcp__linear-server__list_comments / mcp__linear-server__create_comment — read/add comments

Source

git clone https://github.com/srobinson/helioy-plugins/blob/main/plugins/helioy-tools/skills/linear-workflow/SKILL.mdView on GitHub

Overview

Implements Helioy’s Linear workflow by creating a parent issue (WHAT + WHY + acceptance criteria) and multiple subtasks (HOW). It enforces sizing, parent/sub patterns, and metadata conventions to keep work organized, scannable, and actionable.

How This Skill Works

Create a parent issue with mcp__linear-server__create_issue containing title, team Alphabio, description (WHAT + WHY + acceptance criteria), and project. Then add 3+ sub-issues using the same tool with a parentId, detailing HOW to implement, dependencies, and affected files/modules. Sub tasks inherit priority unless overridden; use Todo state when ready for work and apply HotFix only for single-line fixes without subs.

When to Use It

When starting a new feature, create a parent issue that captures WHAT/WHY/acceptance criteria.
When planning features, decompose work into 3+ subtasks to cover HOW.
When organizing tasks across the project, map work using the parent/sub structure and sizing (Small/Medium/Large).
When you need to label a fix as urgent or isolated, use the HotFix label and avoid subs if applicable.
When updating or querying issues, use the Linear MCP tools to list, get, or update issues, projects, and statuses.

Quick Start

Step 1: Create parent issue with mcp__linear-server__create_issue including title (imperative form), team 'Alphabio', description (WHAT + WHY + acceptance criteria), project (match basename if possible), priority, and state 'Todo'.
Step 2: Create 3+ sub-issues with parentId pointing to the parent, detailing HOW to implement, dependencies, and affected modules/files.
Step 3: Use mcp__linear-server__list_issues / get_issue to verify structure; update statuses and link related issues as work progresses.

Best Practices

Always assign a project; match basename $(pwd) to the project or ask to verify.
Set state to Todo when the parent/issue is ready for work.
Do not create a parent issue with only 1 sub-issue; otherwise use a HotFix label.
Require 3+ subs for a parent issue, or use a HotFix label for single-line fixes only.
Use mcp__linear-server__create_issue for both parents and subs; keep parent description WHAT+WHY+testable acceptance criteria and no implementation details.

Example Use Cases

Add user profile export (Small).
Implement auth system (group by component) (Medium).
Build analytics dashboard (group by phase) (Large).
HotFix: Typo in UI label (HotFix, no subs).
User onboarding flow with step-by-step subtasks (Feature decomposition).

Frequently Asked Questions

Add this skill to your agents