# GitHub Issues Mode

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


**Try this to connect to your backlog:**
```
Show me the open issues for this repo
```

**Try this to start work on a specific issue:**
```
Work on issue #42
```

**Try this to handle PR review feedback:**
```
There's review feedback on PR #24
```

Squad connects to your GitHub repository, fetches issues from the backlog, routes work to the right agents, creates branches, implements changes, and opens PRs — all from natural language requests.

---

## Requirements

- **`gh` CLI** installed and authenticated (`gh auth status` to check)
- A GitHub repository with issues

---

## Connect to a Repository

```
> Connect to myorg/myrepo
```

Squad stores the issue source in `team.md`. You only need to do this once per project.

---

## View the Backlog

```
> Show the backlog
```

Squad fetches open issues and displays them in a table:

```
#   Title                        Labels        Assignee
12  Add user authentication      backend       —
15  Fix responsive nav           frontend      —
18  Write API integration tests  testing       —
```

---

## Work on Issues

### Single issue

```
> Work on #12
```

The coordinator routes the issue to the best-fit agent. That agent:

1. Creates a branch (e.g., `feature/12-add-user-authentication`)
2. Implements the work
3. Opens a PR linked to the issue

### Multiple issues

```
> Work on #12 and #15
```

Agents work in parallel — each issue gets its own branch and PR.

---

## Handle PR Review Feedback

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

The agent who opened the PR reads the review comments and addresses them. Commits are pushed to the existing branch.

---

## Merge Completed Work

```
> Merge PR #24
```

Squad squash-merges the PR, deletes the branch, and closes the linked issue.

---

## Check Remaining Work

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

Squad refreshes the backlog and shows remaining open issues.

---

## Workflow Summary

| You say | What happens |
|---------|-------------|
| `"Connect to myorg/myrepo"` | Stores issue source |
| `"Show the backlog"` | Lists open issues |
| `"Work on #12"` | Agent branches, implements, opens PR |
| `"Work on #12 and #15"` | Parallel agent work on both issues |
| `"There's review feedback on PR #24"` | Agent addresses review comments |
| `"Merge PR #24"` | Squash merge, delete branch, close issue |
| `"What's left?"` | Refreshes and shows remaining issues |

---

## Tips

- You don't need to assign issues to specific agents — Squad routes based on domain expertise.
- If `gh` isn't authenticated, Squad will tell you. Run `gh auth login` first.
- For detailed GitHub workflow, see [GitHub Workflow](../concepts/github-workflow.md).

## Sample Prompts

```
connect to bradygaster/squad
```

Links Squad to a GitHub repository for issue-driven development.

```
show the backlog
```

Fetches and displays all open issues from the connected repository.

```
work on issue #23
```

Routes the issue to the appropriate agent who creates a branch, implements, and opens a PR.

```
work on all issues labeled "bug"
```

Processes multiple issues in parallel based on label filtering.

```
what's left in the backlog?
```

Refreshes the issue list and shows remaining open work items.
