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
   

2. 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)
   

3. 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?
     

4. Create the feature branch:

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

5. Update Linear issue status:

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

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

7. 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!
   

4. If issue ID found, fetch with mcp__linear__get_issue
5. 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