branch-and-task-management

Branch and Task Management

Contract

Iron law: no code before context — read the issue body and comments, load history, understand scope, then create the branch. Invoked by /flow:start (Phase 1 EXPLORE through Phase 2 PLAN) and by the implementation-planner agent for task decomposition. Returns: a feature branch named per conventions.branchPatterns checked out from the default branch, one TaskCreate task per acceptance criterion with dependencies set, and an initialized decision journal at {JOURNAL_DIR}/issue-{N}.md. Permitted skips: none — an issue without acceptance criteria is not decomposed; it goes back to the user (or Skill(issue-crafting)) first.

Pre-Conditions

Before creating a branch, confirm: the issue exists and is OPEN; it has acceptance criteria (otherwise ask the user or create them); no existing branch already addresses it; you have read the full body AND comments.

Branch Creation

DEFAULT_BRANCH=$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name' 2>/dev/null || echo "main")
git fetch origin "$DEFAULT_BRANCH"
git checkout -b "feature/issue-{N}-{desc}" "origin/$DEFAULT_BRANCH"

Patterns from settings.json → conventions.branchPatterns: feature/issue-{N}-{desc}, fix/issue-{N}-{desc}, docs/issue-{N}-{desc}. {desc} is 3-5 kebab-case words.

Issue Context Loading

Fetch in parallel: gh issue view $N --json title,body,labels,assignees,milestone and gh issue view $N --comments. Extract: title; acceptance criteria (each - [ ] item becomes a task); labels (inform approach); related issues.

Impact Analysis

Grep for issue keywords and check git log --oneline -10 -- <related path>. Map acceptance criteria to likely file changes. Flag when the issue touches multiple modules (coordination), shared utilities (side-effect risk), or test fixtures (cross-suite updates).

Task Decomposition

For each acceptance criterion:

TaskCreate(
  subject: "Implement: {criterion summary}",
  description: "Acceptance criterion: {full text}\nLikely files: {paths}\nVerification: {how to check}"
)