New Feature

Linear + Git Branch Workflow

Manages the complete feature development workflow, integrating Linear issue tracking with Git branch management.

Project Configuration

Read project configuration from .claude/project.json in the current repository root:

• projectName
• linear.teamId and linear.teamName
• linear.projectId
• github.owner, github.repo, github.defaultBranch
• vercel.*

If .claude/project.json doesn't exist, suggest running /setup-project first.

Instructions for Claude

Step 0: Load Configuration

PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)

Read $PROJECT_ROOT/.claude/project.json and use values throughout.

Mode 1: Starting Work on an Issue (DEFAULT)

When the user invokes this skill (with or without an issue ID):

1. List available issues to work on:

``` Use mcp__linear__list_issues with:

• team: [from config.linear.teamName]
• project: [from config.linear.projectId]
• state: "Todo"
• includeArchived: false

```

1. Present issues to the user:

``` ## Available Issues

### Features (Parent Issues)

• ABC-XX: [title] (X sub-issues)

Priority: [priority] | Size: [size]

### Standalone Tasks

• ABC-XX: [title]

Priority: [priority]

Which issue would you like to work on? (Enter issue ID) ```

1. After user selects an issue:

• Fetch full issue details with mcp__linear__get_issue
• If issue has sub-issues, show them
• If issue is a sub-issue (has parentId), STOP and explain:

``` ABC-XX is a sub-issue of ABC-YY ([Parent Title]).

Sub-issues don't get their own branches. Instead:

1. Work on the parent issue branch: feature/ABC-YY-parent-title
2. Move sub-issues individually in Linear as you work

Would you like to start the parent issue (ABC-YY) instead? ```

1. Create the feature branch:

``bash git checkout -b feature/[ISSUE-ID]-[slugified-title] ``

1. Update Linear issue status:

``` Use mcp__linear__update_issue:

• id: [issue-id]
• state: "In Progress"
• assignee: "me"

```

1. If parent issue, also update parent state to "In Progress".

1. Display the workflow:

``` Started work on [Issue Title]

Branch: feature/ABC-XX-issue-title Issue: [Linear URL] Status: In Progress

## Sub-issues (if applicable):

• [ ] ABC-XX: [sub-issue title] (Todo)
• [ ] ABC-XX: [sub-issue title] (Todo)

## Workflow:

1. Work on sub-issues in order (or pick any)
2. Move sub-issue to "In Progress" in Linear when you start
3. Commit your changes regularly
4. Move sub-issue to "Done" in Linear when complete
5. When all sub-issues done, run /create-pr

Which sub-issue would you like to start with? ```

Mode 2: Checking Current Workflow Status

If the user asks about status (e.g., "what am I working on", "show status"):

1. Get current git branch: git branch --show-current
2. Extract issue ID from branch (feature/ABC-XXX-... or bugfix/ABC-XXX-...)
3. If no issue ID or on default branch:

``` ## Current Status

Branch: [config.github.defaultBranch] (no active feature)

No active feature in progress. Run /new-feature to see available issues! ```

1. If issue ID found, fetch with mcp__linear__get_issue
2. Display current status:

``` ## Current Work: [Issue Title]

Branch: feature/ABC-XX-issue-title Issue: [Linear URL] Status: In Progress Assignee: You

## Progress:

• [x] ABC-XX: [sub-issue] (Done)
• [ ] ABC-XX: [sub-issue] (In Progress) ← Currently working
• [ ] ABC-XX: [sub-issue] (Todo)

Completion: X of Y sub-issues done (Z%)

## Recent commits: [Show last 5 commits on this branch] ```

Mode 3: Planning a New Feature (Not Yet in Linear)

1. Ask for feature details: title, description, large/small.
2. If large — use the Task tool with subagent_type="Explore" to understand existing patterns, then EnterPlanMode for the plan, create parent + sub-issues in Linear, branch, start work.
3. If small — create single Linear issue, branch, start work.

Key Principles

1. Parent issues = Feature branches — One branch per parent issue
2. Sub-issues = Task tracking — Moved individually in Linear; all commits go to parent branch
3. Standalone issues = Their own branch
4. Never create branches for sub-issues
5. Linear ↔ GitHub integration — PR will auto-link based on branch name
6. Update Linear in real-time — Move sub-issues as you work for visibility

Branch Naming Convention

• Features: feature/ABC-XXX-kebab-case-title
• Bugs: bugfix/ABC-XXX-kebab-case-title
• Chores: chore/ABC-XXX-kebab-case-title

The issue ID in the branch name is critical for GitHub ↔ Linear integration.

Working with Sub-issues

Example workflow:

1. Start parent: /new-feature ABC-XX
2. Pick sub-issue: "I'll start with ABC-YY"
3. Move to In Progress in Linear
4. Code and commit: "fix: description (ABC-YY)"
5. Move to Done in Linear
6. Pick next sub-issue
7. Repeat until all done
8. Create PR: /create-pr

Error Handling

If user tries to start a sub-issue directly: explain parent/child relationship, suggest starting the parent.

If issue is already "In Progress" by someone else: show who's assigned, ask if they want to take it over.

If no issues available: suggest /feature-from-backlog.

Integration with Other Skills

• After completion: /create-pr to create pull request
• For status: This skill doubles as status checker
• For backlog: /feature-from-backlog to refine and start backlog items

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ImTaegan
• Source: ImTaegan/claude-saas-flow
• License: MIT

Install and usage instructions live in the source repository linked above.