dev-workflow

name	dev-workflow
description	Full development workflow: pick Linear task, branch, implement, PR with Copilot review, merge, close. Use when starting a new task, creating PRs, or managing the dev cycle.
user-invocable	true
argument-hint	[TASK-ID]
allowed-tools	["Bash(gh *)","Bash(git *)","Bash(curl * linear *)"]

Development Workflow

Setup

Load env vars from .env at the start of every workflow run:

export $(grep -v '^#' .env | grep -v '^$' | xargs)

Required env vars: PROJECT_DIR, GITHUB_REPO, GITHUB_USER, LINEAR_API_KEY, LINEAR_TEAM_PREFIX, LINEAR_TEAM_ID, LINEAR_PROJECT_ID, STATE_IN_PROGRESS, STATE_DONE.

Argument Handling

• /dev-workflow BAT-42 → look up BAT-42 in Linear, set In Progress, start at step 2
• /dev-workflow 42 → look up issue #42 in team $LINEAR_TEAM_PREFIX, same as above
• /dev-workflow (no arg) → ask user what to work on, or list backlog tasks

Workflow

1. Pick or Create Task

Find the task and move it to "In Progress":

# Find by number
linear_query "{ issues(filter: { number: { eq: 42 }, team: { key: { eq: \\\"$LINEAR_TEAM_PREFIX\\\" } } }) { nodes { id identifier title description state { name } } } }"

# Move to In Progress
linear_query "mutation { issueUpdate(id: \\\"ISSUE_UUID\\\", input: { stateId: \\\"$STATE_IN_PROGRESS\\\" }) { success } }"

If no task exists, create one:

linear_query "mutation { issueCreate(input: { teamId: \\\"$LINEAR_TEAM_ID\\\", projectId: \\\"$LINEAR_PROJECT_ID\\\", title: \\\"TITLE\\\", description: \\\"DESC\\\" }) { success issue { id identifier url } } }"

2. Create Worktree & Implement

cd "$PROJECT_DIR" && git fetch origin
git worktree add "${PROJECT_DIR}-worktrees/${LINEAR_TEAM_PREFIX}-XX" \
  -b "feature/${LINEAR_TEAM_PREFIX}-XX" origin/main
cd "${PROJECT_DIR}-worktrees/${LINEAR_TEAM_PREFIX}-XX"

Work inside the worktree. Never touch $PROJECT_DIR directly for feature work.

Commit with conventional prefixes (feat:, fix:, refactor:, docs:, chore:, perf:):

git add <specific-files>
git commit -m "$(cat <<'EOF'
feat: description (TASK-ID)

Co-Authored-By: Claude Opus 4.6 <[e-mail]>
EOF
)"

3. Push & Create PR

git push -u origin "feature/${LINEAR_TEAM_PREFIX}-XX"

gh pr create --title "feat: short description (TASK-ID)" --body "$(cat <<'EOF'
## Summary
- What changed and why

## Test plan
- [ ] Verification steps

Generated with [Claude Code](https://claude.com/claude-code)
EOF
)"

4. Copilot Review Cycle

Copilot auto-reviews on PR creation. Never merge without review.

# Check reviews
gh api repos/$GITHUB_REPO/pulls/PR_NUMBER/reviews \
  --jq '.[] | {author: .user.login, state: .state, body: .body[0:200]}'

# Check inline comments
gh api repos/$GITHUB_REPO/pulls/PR_NUMBER/comments \
  --jq '.[] | {body: .body, path: .path}'

If there's feedback: fix, commit, push, then always re-request review:

gh api repos/$GITHUB_REPO/pulls/PR_NUMBER/requested_reviewers \
  -X POST -f 'reviewers[]=copilot-pull-request-reviewer[bot]'

Repeat until clean. Use a background sub-agent (run_in_background: true) to poll for review completion instead of blocking — continue other work while waiting.

5. Merge & Close

gh pr merge PR_NUMBER --squash --delete-branch

cd "$PROJECT_DIR"
git worktree remove "${PROJECT_DIR}-worktrees/${LINEAR_TEAM_PREFIX}-XX"
git fetch --prune

# Close Linear task
linear_query "mutation { issueUpdate(id: \\\"ISSUE_UUID\\\", input: { stateId: \\\"$STATE_DONE\\\" }) { success } }"

---

Linear API

All Linear calls use this pattern — linear_query is shorthand, always expand to:

curl -s -X POST https://api.linear.app/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: $LINEAR_API_KEY" \
  -d "{\"query\":\"QUERY\"}"

Task dependencies — use when tasks have ordering constraints:

# A blocks B
linear_query "mutation { issueRelationCreate(input: { issueId: \\\"A_UUID\\\", relatedIssueId: \\\"B_UUID\\\", type: blocks }) { success } }"

# Types: blocks | related | duplicate

Rules

1. Never merge without Copilot review — wait for it, always
2. Re-request review after every push during review cycle
3. Worktrees only — never switch branches on main, never stash
4. One task at a time — finish current before starting next
5. Squash merge — delete remote branch after
6. Clean up — remove worktree + local branch after merge
7. .env stays in main — symlink or copy to worktree if needed