pickup-task

/pickup-task

Status queries always hit the tracker. plans/phases.yaml is a stale cache. See your project CLAUDE.md §Source of truth.

Args

• [phase] — default: current active phase
• [type-filter] — optional, filter by owner_type

Steps

1. Query the tracker — never plans/phases.yaml — for status or dependencies. Use the Tracker interface (mcp__linear-server__list_issues for Linear, gh issue list for GitHub, ntn for Notion) to find active issues in the current cycle that are:

   • Status: Todo (or Backlog with no blockers)
   • All blocked_by issues are Done — verify via relations.blockedBy (issue prose like Depends on: forge#N is unreliable)

   phases.yaml is a local execution snapshot derived from the tracker — every status, dependency, or blocker field in it can be stale. The tracker is authoritative for all execution metadata; see your project CLAUDE.md §Source of truth.

2. If multiple match, list and ask user to pick. If one, auto-pick.

3. Set Linear issue status → "In Progress"

4. Compute branch name: feat/{LINEAR-ID}-{kebab-case-title}

5. Create the worktree + hydrate gitignored project meta via the CLI verb:

   forge orchestrate ensure-worktree --task "${LINEAR_ID}" --json
   

   The verb (src/cli/orchestrate/ensure-worktree.ts) owns:

   • Task-ID sanitization (same rules as src/core/workspace.ts#sanitizeIssueId)
   • Repo-root resolution via git rev-parse --git-common-dir so the worktree lands under the main checkout (not a sibling worktree, which would nest)
   • git worktree add at .forge/worktrees/<sanitized-id>/
   • .forge/worktree-task.json marker (binds worktree to task ID for worktree-guard preflight in /implement, /ship, /qa)
   • Hydration of spec/*.md, plans/, docs/learnings/, CLAUDE.md, CRITICAL.md, and .forge/settings.yaml from the main checkout — these are gitignored as a dogfooding rule but workers need them at runtime
   • Idempotence: if the worktree already exists with a matching marker, no-op exit 0; conflicting marker exits 1 with WORKTREE_CONFLICT