linear-implement

Workflow

Step 1: Fetch & Review Ticket

The user provides a Linear ticket URL or ticket ID (e.g. ABC-123).

1. Fetch the ticket details from Linear. Collect:
   • Title
   • Description
   • Acceptance criteria
   • Priority
   • Labels
   • Current status
   • Ticket type (feature, bug, chore, etc.)
2. Update the ticket status to In Progress.
3. Present a summary of the ticket to the user.
4. If any part of the ticket is ambiguous or lacks sufficient detail, ask the user for clarification before proceeding.

Step 2: Plan & Prepare

Create an implementation plan

• Break the work into concrete, ordered tasks.
• Use the TodoWrite tool to track each task.
• Present the plan to the user and wait for confirmation before proceeding.

Save the plan to docs

Write the plan to docs/TICKET-ID/PLAN.md (e.g. docs/ABC-123/PLAN.md). This file serves as a persistent reference for the implementation. Use the following structure:

# TICKET-ID: Ticket Title

## Ticket Summary
Brief summary of the ticket including context and goals.

## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2

## Implementation Plan
1. Step 1
2. Step 2
3. Step 3

## Technical Decisions
Document any significant decisions made during planning, such as:
- Libraries or approaches chosen and why
- Trade-offs considered
- Alternatives rejected

## Notes
Any additional context, links, or references useful for future work.

Update this file throughout implementation:

• Check off acceptance criteria as they are completed.
• Add entries to Technical Decisions when making non-obvious choices.
• Add anything to Notes that would be useful for reviewers or future developers.

Commit the docs/TICKET-ID/ directory as part of the implementation.

Determine the base branch

• Default base branch is main or master. Ask the user if they want to branch from a different base.

Map ticket type to conventional commit type

Use the same mapping as the linear-drafter skill:

Ticket type	Conventional commit type
Feature / capability	feat
Bug fix	fix
Maintenance / config / dependencies	chore
Documentation	docs
Code restructuring	refactor
Adding or updating tests	test
CI/CD changes	ci
Performance improvement	perf
Code style / formatting	style

If the ticket type is unclear, default to feat for new functionality or fix for bug reports.

Create worktree and branch

Branch naming convention: type/TICKET-ID (e.g. feat/ABC-123).

git fetch origin
git worktree add -b feat/ABC-123 ../ABC-123 origin/main

Then continue all work inside the new worktree directory.

Step 3: Implement & Test

1. Implement the ticket according to the plan, checking off tasks as they are completed.
2. Ensure all acceptance criteria from the ticket are met.
3. Run the project's test suite, type checks, and linter.
4. Write additional tests if the changes introduce new functionality that is not yet covered.
5. If any checks fail, fix the issues and re-run until everything passes.

Do not proceed to the next step until all checks pass.

Step 4: Commit, Push & Create PR

Commit

Use a conventional commit message that references the ticket ID:

type(scope): description (TICKET-ID)

Examples:

• feat(settings): add dark mode toggle (ABC-123)
• fix(auth): resolve 500 error on Safari iOS (XYZ-456)

If the change spans multiple scopes, omit the scope:

• feat: add dark mode toggle (ABC-123)

Push and create PR

Push the branch and create a pull request using the GitHub CLI:

git push -u origin feat/ABC-123
gh pr create --title "feat(settings): add dark mode toggle (ABC-123)" --body "$(cat <<'EOF'
## Summary
Brief description of what was implemented and why.

## Changes
- Change 1
- Change 2
- Change 3

## Linear Ticket
[ABC-123](https://linear.app/team/issue/ABC-123)

## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3

## Testing
Describe what was tested and how.
EOF
)"

Fill in the template with the actual ticket details, changes made, and acceptance criteria from the ticket.

Update ticket status

After the PR is created, update the Linear ticket status to In Review.

Best Practices

Branch Naming

• Always use type/TICKET-ID format: feat/ABC-123, fix/XYZ-456
• Derive the type from the ticket type using the mapping table above
• Keep it short — no additional description in the branch name

Commit Messages

• Use imperative mood: "add" not "adding" or "added"
• Keep the first line under 80 characters
• Reference the ticket ID in parentheses at the end
• Use conventional commit format: type(scope): description (TICKET-ID)

Implementation Quality

• Follow existing code conventions and patterns in the project
• Do not introduce new dependencies without confirming with the user
• Keep changes focused on the ticket scope — avoid unrelated changes

Example

Given a ticket ABC-123 of type "Feature" with title "Add dark mode toggle":

Branch:

feat/ABC-123

Worktree creation:

git fetch origin
git worktree add -b feat/ABC-123 ../ABC-123 origin/main

Commit message:

feat(settings): add dark mode toggle (ABC-123)

PR title:

feat(settings): add dark mode toggle (ABC-123)

PR body:

## Summary
Add a dark mode toggle to the settings page, allowing users to switch
between light and dark themes.

## Changes
- Add ThemeToggle component to Settings > Appearance
- Persist theme preference to user account
- Apply theme immediately without page reload
- Respect system preference as default

## Linear Ticket
[ABC-123](https://linear.app/team/issue/ABC-123)

## Acceptance Criteria
- [ ] Theme toggle in Settings > Appearance
- [ ] Preference persisted to user account
- [ ] Theme applied without page reload
- [ ] System preference used as default
- [ ] Cross-browser tested

## Testing
- Unit tests for ThemeToggle component
- Integration test for preference persistence
- Manual testing on Chrome, Firefox, Safari

Notes

• Always confirm the implementation plan with the user before writing any code.
• Do not push or create PRs without user confirmation.
• If tests fail, fix them before proceeding — never skip failing tests.
• If the ticket description is unclear or incomplete, ask the user rather than making assumptions.
• Always update the Linear ticket status: to "In Progress" when starting, to "In Review" after opening the PR.
• Do not introduce unrelated changes — keep the diff focused on the ticket.