Issue-Driven Development with Squad

⚠️ Experimental — Squad is alpha software. APIs, commands, and behavior may change between releases.

Try this:

Connect to myorg/recipe-app

End-to-end workflow: connect to a repo, pick issues from backlog, let agents create branches, implement, open PRs, handle review feedback, and close issues. See also GitHub Issues Mode for detailed guidance.

Prerequisite: The gh CLI must be installed and authenticated (gh auth login).

1. Connect to the Repository

Tell Squad which repo to track:

> Connect to myorg/recipe-app

✅ Issue source stored: myorg/recipe-app
   Using gh CLI for issue tracking.

Squad stores the issue source in team state. From now on, it can read issues, create branches, and open PRs against this repo.

2. View the Backlog

> Show the backlog

┌─────┬──────────────────────────────────────────┬───────────┬────────────┐
│  #  │ Title                                    │ Labels    │ Assignee   │
├─────┼──────────────────────────────────────────┼───────────┼────────────┤
│   7 │ Add dark mode support                    │ feature   │ —          │
│  12 │ Add ingredient search                    │ feature   │ —          │
│  15 │ Fix pagination on recipe list            │ bug       │ —          │
│  18 │ Add user profile page                    │ feature   │ —          │
│  21 │ Rate limiting on API endpoints           │ security  │ —          │
└─────┴──────────────────────────────────────────┴───────────┴────────────┘
5 open issues

3. Assign an Issue

Pick an issue for an agent to work on:

> Work on #15

Squad reads the issue, routes it to the right agent based on domain, and kicks off the full workflow:

🔧 Dallas — picking up #15 (Fix pagination on recipe list)

Dallas is reading the issue and starting work.

Behind the scenes, the agent:

Creates a branch — 15-fix-pagination-on-recipe-list
Implements the fix — reads existing code, writes the change, adds tests
Opens a PR — linked to issue #15 with a description of the fix

When the agent finishes:

🔧 Dallas — Completed #15 (Fix pagination on recipe list)
   Branch: 15-fix-pagination-on-recipe-list
   PR: #22 opened — "Fix pagination on recipe list (#15)"
   Files changed:
   - src/routes/recipes.ts (fixed cursor calculation)
   - test/pagination.test.ts (3 new test cases)

4. Handle Review Feedback

A reviewer leaves comments on the PR. Tell Squad:

> There's review feedback on PR #22

Squad routes the feedback to the agent who opened it:

🔧 Dallas — reading review comments on PR #22

Dallas is addressing the feedback now.

The agent reads the comments, makes changes, and pushes new commits to the same branch:

🔧 Dallas — Addressed review feedback on PR #22
   - Added boundary check for empty result set (reviewer concern)
   - Added test case for zero-results pagination
   - Pushed 2 new commits to 15-fix-pagination-on-recipe-list

No force-pushes, no new branches. Just additional commits on the existing PR.

5. Merge

When the PR is approved:

> Merge PR #22

✅ PR #22 merged — "Fix pagination on recipe list (#15)"
   Issue #15 closed.
   Branch 15-fix-pagination-on-recipe-list deleted.

The issue closes automatically — the PR body includes a Closes #15 reference.

6. Check Remaining Work

> What's left?

┌─────┬──────────────────────────────────────────┬───────────┬────────────┐
│  #  │ Title                                    │ Labels    │ Assignee   │
├─────┼──────────────────────────────────────────┼───────────┼────────────┤
│   7 │ Add dark mode support                    │ feature   │ —          │
│  12 │ Add ingredient search                    │ feature   │ —          │
│  18 │ Add user profile page                    │ feature   │ —          │
│  21 │ Rate limiting on API endpoints           │ security  │ —          │
└─────┴──────────────────────────────────────────┴───────────┴────────────┘
4 open issues

7. Work Multiple Issues in Parallel

Assign several issues at once:

> Work on #12 and #18

🔧 Dallas  — picking up #12 (Add ingredient search)
⚛️ Ripley  — picking up #18 (Add user profile page)
📋 Scribe  — logging session

Each agent creates its own branch and works independently. Both PRs open when agents finish.

Full Lifecycle at a Glance

graph LR
    A["Connect<br/>connect to repo"] --> B["Browse<br/>show backlog"]
    B --> C["Assign<br/>work on issue"]
    C --> D["Branch/Implement<br/>Agent creates & codes"]
    D --> E["Review<br/>Handle feedback"]
    E --> F["Merge<br/>PR merged"]
    F --> G["Status<br/>Updated backlog"]
    G --> H["Parallel<br/>Work on multiple"]
    
    style D fill:#e1f5ff
    style E fill:#f3e5f5

Tips

You don’t pick the agent. Squad routes each issue to the agent whose expertise matches.
Agents name branches with the issue number. Pattern: {number}-{slugified-title}.
PRs auto-link to issues. The PR body includes Closes #N, so merging closes the issue.
Review feedback is incremental. Agents push new commits — no force-pushes, no new PRs.
Decisions accumulate during issue work. Agents record choices that carry forward across the backlog.
Work multiple issues in parallel. Say "Work on #12 and #18" and each agent gets its own branch.