Issue Lifecycle

When connecting Squad to an issue tracker, store the connection in .squad/team.md:

Detection triggers:

• User says “connect to {repo}”
• User says “monitor {repo} for issues”
• Ralph is activated without an issue source

Platform-Specific Issue States

Each platform tracks issue lifecycle differently. Squad normalizes these into a common board state.

GitHub

Issue labels used by Squad:

• squad — Issue is in Squad backlog
• squad:{member} — Assigned to specific agent
• squad:untriaged — Needs triage
• go:needs-research — Needs investigation before implementation
• priority:p{N} — Priority level (0=critical, 1=high, 2=medium, 3=low)
• next-up — Queued for next agent pickup

Branch naming convention:

Example: squad/42-fix-login-validation

Azure DevOps

Work item tags used by Squad:

• squad — Work item is in Squad backlog
• squad:{member} — Assigned to specific agent

Branch naming convention:

Example: squad/1234-add-auth-module

Microsoft Planner

Planner does not have native Git integration. Squad uses Planner for task tracking and GitHub/ADO for code management.

Planner→Git workflow:

1. Task created in Planner bucket
2. Agent reads task from Planner
3. Agent creates branch in GitHub/ADO repo
4. Agent opens PR referencing Planner task ID in description
5. Agent marks task as “Completed” when PR merges

Issue → Branch → PR → Merge Lifecycle

1. Issue Assignment (Triage)

Trigger: Ralph detects an untriaged issue or user manually assigns work.

Actions:

1. Read .squad/routing.md to determine which agent should handle the issue
2. Apply squad:{member} label (GitHub) or tag (ADO)
3. Transition issue to assigned state
4. Optionally spawn agent immediately if issue is high-priority

Issue read command:

2. Branch Creation (Start Work)

Trigger: Agent accepts issue assignment and begins work.

Actions:

1. Ensure working on latest base branch (usually main or dev)
2. Create feature branch using Squad naming convention
3. Transition issue to inProgress state

Branch creation commands:

Standard (single-agent, no parallelism):

Worktree (parallel multi-agent):

Note: Worktree support is in progress (#525). Current implementation uses standard checkout.

3. Implementation & Commit

Actions:

1. Agent makes code changes
2. Commits reference the issue number
3. Pushes branch to remote

Commit message format:

Commit types: feat, fix, docs, refactor, test, chore, perf, style, build, ci

Push command:

4. PR Creation

Trigger: Agent completes implementation and is ready for review.

Actions:

1. Open PR from feature branch to base branch
2. Reference issue in PR description
3. Apply labels if needed
4. Transition issue to needsReview state

PR creation commands:

GitHub:

Azure DevOps:

PR description template:

5. PR Review & Updates

Review states:

• Approved → readyToMerge
• Changes requested → changesRequested
• CI failure → ciFailure

When changes are requested:

1. Agent addresses feedback
2. Commits fixes to the same branch
3. Pushes updates
4. Requests re-review

Update workflow:

Re-request review (GitHub):

6. PR Merge

Trigger: PR is approved and CI passes.

Merge strategies:

GitHub (merge commit):

GitHub (squash):

Azure DevOps:

Post-merge actions:

1. Issue automatically closes (if “Closes #{number}” is in PR description)
2. Feature branch is deleted
3. Squad board state transitions to done
4. Worktree cleanup (if worktree was used — #525)

7. Cleanup

Standard workflow cleanup:

Worktree cleanup (future, #525):

Spawn Prompt Additions for Issue Work

When spawning an agent to work on an issue, include this context block:

gh pr create --title “{title}” --body “Closes #{number}\n\n{description}” --head squad/{issue-number}-{slug} --base {base-branch}

Ralph’s Role in Issue Lifecycle

Ralph (the work monitor) continuously checks issue and PR state:

1. Triage: Detects untriaged issues, assigns squad:{member} labels
2. Spawn: Launches agents for assigned issues
3. Monitor: Tracks PR state transitions (needsReview → changesRequested → readyToMerge)
4. Merge: Automatically merges approved PRs
5. Cleanup: Marks issues as done when PRs merge

Ralph’s work-check cycle:

See .squad/templates/ralph-reference.md for Ralph’s full lifecycle.

PR Review Handling

Automated Approval (CI-only projects)

If the project has no human reviewers configured:

1. PR opens
2. CI runs
3. If CI passes, Ralph auto-merges
4. Issue closes

Human Review Required

If the project requires human approval:

1. PR opens
2. Human reviewer is notified (GitHub/ADO notifications)
3. Reviewer approves or requests changes
4. If approved + CI passes, Ralph merges
5. If changes requested, agent addresses feedback

Squad Member Review

If the issue was assigned to a squad member and they authored the PR:

1. Another squad member reviews (conflict of interest avoidance)
2. Original author is locked out from re-working rejected code (rejection lockout)
3. Reviewer can approve edits or reject outright

Common Issue Lifecycle Patterns

Pattern 1: Quick Fix (Single Agent, No Review)

Pattern 2: Feature Development (Human Review)

Pattern 3: Research-Then-Implement

Pattern 4: Parallel Multi-Agent (Future, #525)

Anti-Patterns

• ❌ Creating branches without linking to an issue
• ❌ Committing without issue reference in message
• ❌ Opening PRs without “Closes #{number}” in description
• ❌ Merging PRs before CI passes
• ❌ Leaving feature branches undeleted after merge
• ❌ Using checkout -b when parallel agents are active (causes working directory conflicts)
• ❌ Manually transitioning issue states — let the platform and Squad automation handle it
• ❌ Skipping the branch naming convention — breaks Ralph’s tracking logic

Migration Notes

v0.8.x → v0.9.x (Worktree Support):

• checkout -b → git worktree add for parallel agents
• Worktree cleanup added to post-merge flow
• TEAM_ROOT passing to agents to support worktree-aware state resolution

This template will be updated as worktree lifecycle support lands in #525.