start-task

0. Validate Environment

• Inside a git repo
• Working tree is clean (

  git status --porcelain

  should be empty)
  • IF dirty: show the status and ask "Commit, stash, or abort?"

• linear

  CLI available
• On main/default branch (warn if starting from a feature branch)

• IF

  .linear-project

  exists →

  PROJECT=$(cat .linear-project)

  , store

  PROJECT_FLAG

• IF missing → continue unscoped (don't interrupt task flow with setup prompts)

1. Select Issue

• Fetch issue details with

  linear issue view $ISSUE_ID

• Verify it's assigned to me and not already Done
• If it's already In Progress, ask: "This is already started. Resume it or pick a different one?"

• linear issue list -s unstarted --limit 10 $PROJECT_FLAG

  — fetch backlog
• IF zero unstarted issues:
  • Check for in-progress issues (

    linear issue list -s started --limit 10 $PROJECT_FLAG

    ): "No unstarted issues. You have N in-progress. Resume one?"
  • If also zero and scoped: "Backlog is empty for {project-name}. Create a new issue in Linear or check another project."
  • If also zero and unscoped: "Backlog is empty. Create a new issue in Linear or check another team."
  • Stop here.
• Sort by priority (Urgent > High > Medium > Low > None)
• IF single top-priority issue → auto-select it
• IF multiple issues share the same top priority → ask user to pick: "Multiple issues at the same priority. Which one?" Show issue IDs, titles, and due dates if available.

2. Check Readiness

• linear issue view $ISSUE_ID

  — look for blocking relations
• IF blocked by another issue: "This is blocked by ENG-XXX (title). Want to start that one instead, or start this anyway?"

• Does the issue have a description? If empty or very short (< 50 chars): Ask: "This issue has no description. Can you give me a one-liner on what needs to happen?" Capture the answer and update the Linear issue description.

• IF .planning/ROADMAP.md exists, check if this issue maps to a planned phase
• IF it does: note the phase number and load its CONTEXT.md or PLAN.md
• IF it doesn't: note it as ad-hoc work (still fine to proceed)

3. Create Branch

• Extract a slug from the issue title (lowercase, hyphens, max 50 chars)
• Branch name format:

  {team-prefix}-{number}-{slug}

  (e.g.,

  eng-123-add-auth-flow

  )

• git checkout -b $BRANCH_NAME

• Confirm: "Created branch:

  $BRANCH_NAME

  "

4. Move to In Progress

• linear issue update $ISSUE_ID -s "In Progress"

• Confirm: "Linear issue moved to In Progress"

5. Load Context & Plan

• Full issue description and comments from Linear
• Related GSD planning files (CONTEXT.md, RESEARCH.md, PLAN.md) if they exist
• CLAUDE.md for project conventions
• Quick scan of the codebase areas most likely affected (use issue description keywords)

Plan for ENG-123: Add user authentication flow
─────────────────────────────────────────────
1. Create auth middleware in src/middleware.ts
2. Add login page at app/(auth)/login/page.tsx
3. Implement session management with Convex Auth
4. Add protected route wrapper component
5. Write tests for auth flow

6. Confirm Approach

• Proceed → begin implementation
• Adjust → ask what to change, update plan, re-confirm
• Wrong task → go back to step 1

• Issue selected with clear rationale
• All blockers and missing context surfaced before starting
• Clean branch created from main/default branch
• Linear issue moved to In Progress
• Implementation plan presented and confirmed by user
• User explicitly approved before any code changes </success_criteria>