Skip to content

Commit 08b041c

Browse files
AngelmmiguelAngelmmiguel
authored
feat: update context system and add a new guide (#37)
1 parent c023239 commit 08b041c

6 files changed

Lines changed: 232 additions & 7 deletions

File tree

‎rover.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{
2-
"version": "1.2",
2+
"version": "1.3",
33
"languages": [
44
"typescript",
55
"javascript"

‎src/content/docs/rover/guides/assign-tasks.mdx‎

Lines changed: 26 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,31 @@ Create a simple task from scratch in your initialized repository.
5151
</StepItem>
5252
</StepList>
5353

54+
## Provide context
55+
56+
You can attach external context to a task using the `--context` (or `-c`) flag. This gives the agent reference material from GitHub issues, pull requests, local files, or web URLs alongside the task description.
57+
58+
<StepList title="Creating a task with context">
59+
<StepItem step={1}>
60+
Combine a task description with context from a GitHub issue and a local file
61+
62+
```sh
63+
rover task -y -c github:issue/15 -c file:./docs/design.md "Implement the new authentication flow"
64+
```
65+
66+
Rover fetches the issue content and reads the local file, then provides both to the agent alongside the task description.
67+
</StepItem>
68+
<StepItem step={2}>
69+
Follow the task progress
70+
71+
```sh
72+
rover logs -f 1
73+
```
74+
</StepItem>
75+
</StepList>
76+
77+
See the [Provide context to tasks](/rover/guides/provide-context) guide for full details on supported context sources and comment trust settings.
78+
5479
## Inspect the task
5580

5681
Besides listing current tasks or watching the listing, you can inspect tasks and their iterations to understand what the agent planned and executed.
@@ -160,8 +185,8 @@ If the agent has produced a result that needs small changes to be ready, you can
160185
## Related Guides
161186

162187
<CardGrid>
188+
<LinkCard title="Provide context to tasks" href="/rover/guides/provide-context" description="Supply external context from GitHub, local files, and URLs" />
163189
<LinkCard title="Project Initialization" href="/rover/guides/project-initialization" description="Initialize Rover in your repository" />
164190
<LinkCard title="Iterate on tasks" href="/rover/guides/iterate-tasks" description="Refine and improve task implementations" />
165191
<LinkCard title="Merge changes from tasks" href="/rover/guides/merge-tasks" description="Integrate completed tasks into your codebase" />
166-
<LinkCard title="Write technical documentation" href="/rover/guides/write-docs" description="Use Rover to create and maintain documentation" />
167192
</CardGrid>

‎src/content/docs/rover/guides/github-issues.mdx‎

Lines changed: 36 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -9,14 +9,17 @@ import StepList from '../../../../components/StepList.svelte';
99
import StepItem from '../../../../components/StepItem.svelte';
1010
import { CardGrid, LinkCard } from '@astrojs/starlight/components';
1111

12+
:::caution
13+
The `--from-github` flag is deprecated. Use the new [context system](/rover/guides/provide-context) instead: `--context github:issue/<number>`. The `--from-github` flag will continue to work but may be removed in a future release.
14+
:::
15+
1216
Rover integrates with GitHub to create [tasks](/rover/concepts/task) directly from issues. This allows you to assign GitHub issues to local AI coding agents and maintain a clear link between the issue and the task result.
1317

1418
## Prerequisites
1519

16-
To create Rover [tasks](/rover/concepts/task) from GitHub issues, you need either:
20+
To create Rover [tasks](/rover/concepts/task) from GitHub issues, you need:
1721

18-
- **GitHub CLI (`gh`)**: Recommended for private repositories and GitHub Enterprise. Install from [cli.github.com](https://cli.github.com/).
19-
- **Public repository access**: For public repositories, Rover can fetch issues directly from the GitHub API without authentication.
22+
- **GitHub CLI (`gh`)**: Install from [cli.github.com](https://cli.github.com/) and authenticate with `gh auth login`.
2023

2124
## Create a task from an issue
2225

@@ -160,6 +163,35 @@ Add a login form with email and password fields.
160163

161164
Rover parses the issue and populates the workflow inputs accordingly.
162165

166+
## Migration to the context system
167+
168+
The `--from-github` and `--include-comments` flags are deprecated in favor of the more flexible [context system](/rover/guides/provide-context). The table below maps old flags to new equivalents:
169+
170+
| Old syntax | New syntax |
171+
|---|---|
172+
| `--from-github 15` | `--context github:issue/15` |
173+
| `--from-github 15 --include-comments` | `--context github:issue/15 --context-trust-all-authors` |
174+
175+
The context system also supports features not available with `--from-github`:
176+
177+
### GitHub PR context
178+
179+
Use `github:pr/<number>` to provide a pull request and its diff as context. This is useful when you want the agent to align its implementation with an existing PR or address review feedback.
180+
181+
```sh
182+
rover task -c github:pr/42 "Address the review comments on this PR"
183+
```
184+
185+
### Cross-repo references
186+
187+
Reference issues and PRs from other repositories using the `github:<owner>/<repo>/issue/<number>` or `github:<owner>/<repo>/pr/<number>` format.
188+
189+
```sh
190+
rover task -c github:acme/design-docs/issue/8 "Implement the feature described in the design doc"
191+
```
192+
193+
See the [Provide context to tasks](/rover/guides/provide-context) guide for full details on all supported context sources.
194+
163195
## Best practices
164196

165197
To get the best results when creating tasks from GitHub issues:
@@ -180,6 +212,7 @@ To get the best results when creating tasks from GitHub issues:
180212
## Related Guides
181213

182214
<CardGrid>
215+
<LinkCard title="Provide context to tasks" href="/rover/guides/provide-context" description="Supply external context from GitHub, local files, and URLs" />
183216
<LinkCard title="Implement a new feature" href="/rover/guides/assign-tasks" description="Create and assign tasks to AI coding agents" />
184217
<LinkCard title="Iterate on tasks" href="/rover/guides/iterate-tasks" description="Refine and improve task implementations" />
185218
<LinkCard title="Merge changes from tasks" href="/rover/guides/merge-tasks" description="Integrate completed tasks into your codebase" />

‎src/content/docs/rover/guides/iterate-tasks.mdx‎

Lines changed: 26 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,31 @@ Following the fizzbuzz example from the task creation guide, you can ask for an
3636
</StepItem>
3737
</StepList>
3838

39+
## Provide context to iterations
40+
41+
You can attach external context to an iteration using the `--context` flag. This lets you supply reference material such as GitHub issues, PRs, local files, or URLs that the agent can use alongside your instructions.
42+
43+
<StepList title="Iterating with context">
44+
<StepItem step={1}>
45+
Add a GitHub PR as context to guide the iteration
46+
47+
```sh
48+
rover iterate 1 "Align the implementation with the reviewed approach" -c github:pr/50
49+
```
50+
</StepItem>
51+
<StepItem step={2}>
52+
Combine multiple context sources
53+
54+
```sh
55+
rover iterate 1 "Update the API to match the spec" -c github:issue/20 -c file:./docs/api-spec.md
56+
```
57+
</StepItem>
58+
</StepList>
59+
60+
Context from previous iterations carries forward automatically. You don't need to repeat URIs already provided. New context is merged with inherited context. If you pass a URI that was used in a previous iteration, Rover re-fetches it to get the latest content.
61+
62+
See the [Provide context to tasks](/rover/guides/provide-context) guide for full details on supported sources and comment trust settings.
63+
3964
## Review iteration changes
4065

4166
After an iteration completes, you can inspect what changed compared to the previous iteration.
@@ -87,8 +112,8 @@ To get the best results from iterations:
87112
## Related Guides
88113

89114
<CardGrid>
115+
<LinkCard title="Provide context to tasks" href="/rover/guides/provide-context" description="Supply external context from GitHub, local files, and URLs" />
90116
<LinkCard title="Implement a new feature" href="/rover/guides/assign-tasks" description="Create and assign tasks to AI coding agents" />
91117
<LinkCard title="Merge changes from tasks" href="/rover/guides/merge-tasks" description="Integrate completed tasks into your codebase" />
92118
<LinkCard title="Project Initialization" href="/rover/guides/project-initialization" description="Initialize Rover in your repository" />
93-
<LinkCard title="Write technical documentation" href="/rover/guides/write-docs" description="Use Rover to create and maintain documentation" />
94119
</CardGrid>

‎src/content/docs/rover/guides/provide-context.mdx‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
---
2+
title: Provide context to tasks
3+
description: Supply external context from GitHub issues, pull requests, local files, and web resources to give AI agents the information they need
4+
sidebar:
5+
order: 5
6+
---
7+
8+
import StepList from '../../../../components/StepList.svelte';
9+
import StepItem from '../../../../components/StepItem.svelte';
10+
import { CardGrid, LinkCard } from '@astrojs/starlight/components';
11+
12+
Context lets you attach external information to a [task](/rover/concepts/task) or [iteration](/rover/guides/iterate-tasks) so the AI agent can reference it while working. Instead of pasting content into the task description, use context to provide requirements from GitHub issues, design specs from pull requests, reference documentation from local files, or API specifications from URLs.
13+
14+
## Supported context sources
15+
16+
Rover resolves context URIs through built-in providers. You can combine multiple sources in a single command.
17+
18+
| URI format | Description | Example |
19+
|---|---|---|
20+
| `github:issue/<number>` | GitHub issue from the current repo | `github:issue/15` |
21+
| `github:pr/<number>` | GitHub PR with diff from the current repo | `github:pr/42` |
22+
| `github:<owner>/<repo>/issue/<number>` | Cross-repo GitHub issue | `github:acme/api/issue/8` |
23+
| `github:<owner>/<repo>/pr/<number>` | Cross-repo GitHub PR with diff | `github:acme/api/pr/31` |
24+
| `file:./<path>` | Local file (relative path) | `file:./docs/spec.md` |
25+
| `file:///<path>` | Local file (absolute path) | `file:///home/user/notes.md` |
26+
| `https://<url>` | Remote web resource | `https://example.com/api-spec.yaml` |
27+
28+
:::tip
29+
GitHub context requires the [GitHub CLI (`gh`)](https://cli.github.com/) to be installed and authenticated.
30+
:::
31+
32+
## Add context to a task
33+
34+
Pass one or more `--context` flags when creating a task. Each flag accepts a context URI.
35+
36+
<StepList title="Creating a task with context">
37+
<StepItem step={1}>
38+
Create a task with context from a GitHub issue and a local spec file
39+
40+
```sh
41+
rover task -c github:issue/15 -c file:./docs/api-spec.md "Implement the new endpoint"
42+
```
43+
44+
Rover fetches the issue content and reads the local file, then provides both to the agent alongside the task description.
45+
</StepItem>
46+
<StepItem step={2}>
47+
You can also provide context from a remote URL
48+
49+
```sh
50+
rover task -c https://example.com/openapi.yaml "Generate client SDK from the API spec"
51+
```
52+
</StepItem>
53+
<StepItem step={3}>
54+
Follow the task progress
55+
56+
```sh
57+
rover logs -f 1
58+
```
59+
</StepItem>
60+
</StepList>
61+
62+
:::tip
63+
The `-c` short flag is equivalent to `--context`. You can repeat it as many times as needed to attach multiple sources.
64+
:::
65+
66+
## Add context to an iteration
67+
68+
Context works the same way on iterations. Pass `--context` flags to `rover iterate` to provide additional information for a follow-up iteration.
69+
70+
<StepList title="Iterating with context">
71+
<StepItem step={1}>
72+
Add a PR as context to guide a refinement iteration
73+
74+
```sh
75+
rover iterate 1 "Align the implementation with the reviewed approach" -c github:pr/50
76+
```
77+
</StepItem>
78+
<StepItem step={2}>
79+
Follow the iteration progress
80+
81+
```sh
82+
rover logs -f 1 2
83+
```
84+
</StepItem>
85+
</StepList>
86+
87+
### Context inheritance
88+
89+
Context from previous iterations carries forward automatically. When you add new context to an iteration, it is merged with context from earlier iterations.
90+
91+
You don't need to repeat URIs you've already provided. If you pass a URI that was used in a previous iteration, **Rover re-fetches it to get the latest content**.
92+
93+
## Control comment visibility
94+
95+
When using GitHub issues or PRs as context, comments and reviews are **excluded by default** to prevent prompt-injection from untrusted contributors.
96+
97+
You can selectively include comments from trusted authors:
98+
99+
```sh
100+
# Trust specific authors
101+
rover task -c github:issue/15 --context-trust-authors alice,bob "Fix the bug"
102+
103+
# Trust all authors (use with caution)
104+
rover task -c github:pr/42 --context-trust-all-authors "Review and address PR feedback"
105+
```
106+
107+
The same flags work with `rover iterate`:
108+
109+
```sh
110+
rover iterate 1 "Address remaining review comments" -c github:pr/42 --context-trust-all-authors
111+
```
112+
113+
## Best practices
114+
115+
- **Prefer context over copy-paste**: Use context URIs instead of pasting content into the task description. This keeps descriptions focused and lets Rover handle formatting and attribution.
116+
- **Combine context with clear instructions**: Context provides information; the task description should explain what to do with it.
117+
- **Scope context narrowly**: Provide only the sources relevant to the task. Too much unrelated context can dilute the agent's focus.
118+
- **Use GitHub PRs for alignment**: When iterating on a task, referencing a related PR helps the agent understand the desired approach and coding patterns.
119+
- **Be deliberate with comment trust**: Only enable `--context-trust-all-authors` on repositories where you trust all contributors. For open-source projects with external contributors, prefer `--context-trust-authors` with specific usernames.
120+
121+
## Relevant Concepts
122+
123+
<CardGrid>
124+
<LinkCard title="Task" href="/rover/concepts/task" description="Learn about Rover tasks and how they work" />
125+
<LinkCard title="Workflow" href="/rover/concepts/workflow" description="Discover how workflows guide coding agents" />
126+
</CardGrid>
127+
128+
## Related Guides
129+
130+
<CardGrid>
131+
<LinkCard title="Implement a new feature" href="/rover/guides/assign-tasks" description="Create and assign tasks to AI coding agents" />
132+
<LinkCard title="Work on GitHub issues" href="/rover/guides/github-issues" description="Create tasks from GitHub issues and track their relationship" />
133+
<LinkCard title="Iterate on tasks" href="/rover/guides/iterate-tasks" description="Refine and improve task implementations" />
134+
<LinkCard title="Merge changes from tasks" href="/rover/guides/merge-tasks" description="Integrate completed tasks into your codebase" />
135+
</CardGrid>

‎src/content/docs/rover/reference/cli-reference.mdx‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -77,7 +77,11 @@ rover task [options] [description]
7777

7878
**Options:**
7979

80-
- `--from-github <issue>`: Fetch task description from a GitHub issue number
80+
- `-c, --context <uri>`: Add context from a URI. Can be repeated. Supported schemes: `github:issue/<n>`, `github:pr/<n>`, `github:<owner>/<repo>/issue/<n>`, `github:<owner>/<repo>/pr/<n>`, `file:<path>`, `https://<url>`
81+
- `--context-trust-authors <users>`: Comma-separated list of trusted authors for comment inclusion
82+
- `--context-trust-all-authors`: Trust all authors for comment inclusion (disables filtering)
83+
- `--from-github <issue>`: *(Deprecated. Use `--context github:issue/<number>`)* Fetch task description from a GitHub issue number
84+
- `--include-comments`: *(Deprecated. Use `--context-trust-all-authors`)* Include issue comments in the task description (requires `--from-github`)
8185
- `--workflow, -w <name>`: Use a specific workflow to complete this task
8286
- `-y, --yes`: Skip all confirmations and run non-interactively
8387
- `-s, --source-branch <branch>`: Base branch for git worktree creation
@@ -174,6 +178,9 @@ rover iterate [options] <taskId> [instructions]
174178

175179
**Options:**
176180

181+
- `-c, --context <uri>`: Add context from a URI. Can be repeated. Supported schemes: `github:issue/<n>`, `github:pr/<n>`, `github:<owner>/<repo>/issue/<n>`, `github:<owner>/<repo>/pr/<n>`, `file:<path>`, `https://<url>`
182+
- `--context-trust-authors <users>`: Comma-separated list of trusted authors for comment inclusion
183+
- `--context-trust-all-authors`: Trust all authors for comment inclusion (disables filtering)
177184
- `-i, --interactive`: Open an interactive command session to iterate on the task
178185
- `--json`: Output JSON and skip confirmation prompts
179186

0 commit comments

Comments
 (0)