# GitHub Issues Walkthrough

A step-by-step tour of Squad's GitHub Issues workflow. This connects your team to a real repository's issue tracker so agents can pick up issues, create branches, open PRs, and handle review feedback.

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

---

## 1. Connect to a Repository

Tell Squad which repo to track:

```
> Connect to myorg/recipe-app
```

Squad stores the issue source in team state:

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

From now on, Squad can read issues from that repo and create branches and PRs against it.

---

## 2. View the Backlog

Ask to see open issues:

```
> Show the backlog
```

Squad pulls open issues via `gh` and displays them:

```
┌─────┬──────────────────────────────────────────┬───────────┬────────────┐
│  #  │ Title                                    │ Labels    │ Assignee   │
├─────┼──────────────────────────────────────────┼───────────┼────────────┤
│  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  │ —          │
│  23 │ Mobile responsive layout                 │ ui        │ —          │
└─────┴──────────────────────────────────────────┴───────────┴────────────┘
5 open issues
```

---

## 3. Work on an Issue

Pick an issue for an agent to work on:

```
> Work on #12
```

Squad reads the issue details, routes it to the right agent, and kicks off the workflow:

```
🔧 Dallas — picking up #12 (Add ingredient search)

Dallas is reading the issue and starting work.
```

Behind the scenes, the agent:

1. **Creates a branch** — named descriptively based on the issue (e.g., `12-add-ingredient-search`)
2. **Does the implementation work** — writes code, tests, whatever the issue requires
3. **Opens a PR** — linked back to issue #12, with a description of what was done

When the agent finishes:

```
🔧 Dallas — Completed #12 (Add ingredient search)
   Branch: 12-add-ingredient-search
   PR: #24 opened — "Add ingredient search (#12)"
   Files changed:
   - src/routes/recipes.ts (added search endpoint)
   - src/models/recipe.ts (added text index)
   - test/search.test.ts (6 test cases)
```

---

## 4. Multiple Issues in Parallel

You can assign multiple issues at once:

```
> Work on #15 and #23
```

```
🔧 Dallas  — picking up #15 (Fix pagination on recipe list)
⚛️ Ripley  — picking up #23 (Mobile responsive layout)
📋 Scribe  — logging session
```

Each agent creates its own branch and works independently. If your repo supports worktrees, Squad can work on multiple branches simultaneously.

---

## 5. Handle Review Feedback

After a PR is open, reviewers may leave comments. When you see feedback:

```
> There's review feedback on PR #24
```

Squad routes the review to the agent who opened the PR:

```
🔧 Dallas — reading review comments on PR #24

Dallas is addressing the feedback now.
```

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

```
🔧 Dallas — Addressed review feedback on PR #24
   - Added input sanitization for search query (reviewer concern)
   - Added test case for SQL injection attempt
   - Pushed 2 new commits to 12-add-ingredient-search
```

---

## 6. Merge Completed Work

When the PR is approved and ready:

```
> Merge PR #24
```

```
✅ PR #24 merged — "Add ingredient search (#12)"
   Issue #12 closed.
   Branch 12-add-ingredient-search deleted.
```

The issue is closed automatically when the PR merges (if the PR body includes `Closes #12`).

---

## 7. Check Remaining Work

After merging, see what's left:

```
> What's left?
```

Squad refreshes the backlog:

```
┌─────┬──────────────────────────────────────────┬───────────┬────────────┐
│  #  │ Title                                    │ Labels    │ Assignee   │
├─────┼──────────────────────────────────────────┼───────────┼────────────┤
│  15 │ Fix pagination on recipe list            │ bug       │ Dallas     │
│  18 │ Add user profile page                    │ feature   │ —          │
│  21 │ Rate limiting on API endpoints           │ security  │ —          │
│  23 │ Mobile responsive layout                 │ ui        │ Ripley     │
└─────┴──────────────────────────────────────────┴───────────┴────────────┘
4 open issues (2 in progress)
```

---

## Full Workflow at a Glance

```
Connect      →  "connect to myorg/recipe-app"
Browse       →  "show the backlog"
Assign       →  "work on #12"
  └─ Agent creates branch, implements, opens PR
Review       →  "there's review feedback on PR #24"
  └─ Agent reads comments, pushes fixes
Merge        →  "merge PR #24"
  └─ PR merged, issue closed
Status       →  "what's left?"
  └─ Updated backlog
```

---

## Tips

- **You don't pick the agent.** Squad routes the issue to the agent whose expertise matches the issue's domain. A bug in the API goes to the backend agent. A UI issue goes to the frontend agent.
- **Agents name branches sensibly.** Branch names include the issue number and a slugified title, so they're easy to find in `git branch`.
- **PRs link to issues.** The PR description includes a `Closes #N` reference so merging automatically closes the issue.
- **Review feedback is incremental.** When you tell Squad about review feedback, the agent pushes new commits to the existing branch — no force-pushes, no new PRs.
- **Check `decisions.md` after issue work.** Agents often record decisions while working on issues (e.g., "chose cursor pagination" or "added text index for search"). These decisions carry forward to future issues.
