From a8ba619c690567e551cedb765b9faa1f3cbcf72c Mon Sep 17 00:00:00 2001 From: Angel M Miguel Date: Thu, 5 Feb 2026 11:08:00 +0100 Subject: [PATCH] feat: update context system and add a new guide --- rover.json | 2 +- .../docs/rover/guides/assign-tasks.mdx | 27 +++- .../docs/rover/guides/github-issues.mdx | 39 ++++- .../docs/rover/guides/iterate-tasks.mdx | 27 +++- .../docs/rover/guides/provide-context.mdx | 135 ++++++++++++++++++ .../docs/rover/reference/cli-reference.mdx | 9 +- 6 files changed, 232 insertions(+), 7 deletions(-) create mode 100644 src/content/docs/rover/guides/provide-context.mdx diff --git a/rover.json b/rover.json index bd2f9f3..37c638e 100644 --- a/rover.json +++ b/rover.json @@ -1,5 +1,5 @@ { - "version": "1.2", + "version": "1.3", "languages": [ "typescript", "javascript" diff --git a/src/content/docs/rover/guides/assign-tasks.mdx b/src/content/docs/rover/guides/assign-tasks.mdx index 83e811f..a5ef8b9 100644 --- a/src/content/docs/rover/guides/assign-tasks.mdx +++ b/src/content/docs/rover/guides/assign-tasks.mdx @@ -51,6 +51,31 @@ Create a simple task from scratch in your initialized repository. +## Provide context + +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. + + + + Combine a task description with context from a GitHub issue and a local file + + ```sh + rover task -y -c github:issue/15 -c file:./docs/design.md "Implement the new authentication flow" + ``` + + Rover fetches the issue content and reads the local file, then provides both to the agent alongside the task description. + + + Follow the task progress + + ```sh + rover logs -f 1 + ``` + + + +See the [Provide context to tasks](/rover/guides/provide-context) guide for full details on supported context sources and comment trust settings. + ## Inspect the task 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 ## Related Guides + - diff --git a/src/content/docs/rover/guides/github-issues.mdx b/src/content/docs/rover/guides/github-issues.mdx index 534172e..cc53c8e 100644 --- a/src/content/docs/rover/guides/github-issues.mdx +++ b/src/content/docs/rover/guides/github-issues.mdx @@ -9,14 +9,17 @@ import StepList from '../../../../components/StepList.svelte'; import StepItem from '../../../../components/StepItem.svelte'; import { CardGrid, LinkCard } from '@astrojs/starlight/components'; +:::caution +The `--from-github` flag is deprecated. Use the new [context system](/rover/guides/provide-context) instead: `--context github:issue/`. The `--from-github` flag will continue to work but may be removed in a future release. +::: + 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. ## Prerequisites -To create Rover [tasks](/rover/concepts/task) from GitHub issues, you need either: +To create Rover [tasks](/rover/concepts/task) from GitHub issues, you need: -- **GitHub CLI (`gh`)**: Recommended for private repositories and GitHub Enterprise. Install from [cli.github.com](https://cli.github.com/). -- **Public repository access**: For public repositories, Rover can fetch issues directly from the GitHub API without authentication. +- **GitHub CLI (`gh`)**: Install from [cli.github.com](https://cli.github.com/) and authenticate with `gh auth login`. ## Create a task from an issue @@ -160,6 +163,35 @@ Add a login form with email and password fields. Rover parses the issue and populates the workflow inputs accordingly. +## Migration to the context system + +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: + +| Old syntax | New syntax | +|---|---| +| `--from-github 15` | `--context github:issue/15` | +| `--from-github 15 --include-comments` | `--context github:issue/15 --context-trust-all-authors` | + +The context system also supports features not available with `--from-github`: + +### GitHub PR context + +Use `github:pr/` 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. + +```sh +rover task -c github:pr/42 "Address the review comments on this PR" +``` + +### Cross-repo references + +Reference issues and PRs from other repositories using the `github://issue/` or `github://pr/` format. + +```sh +rover task -c github:acme/design-docs/issue/8 "Implement the feature described in the design doc" +``` + +See the [Provide context to tasks](/rover/guides/provide-context) guide for full details on all supported context sources. + ## Best practices 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: ## Related Guides + diff --git a/src/content/docs/rover/guides/iterate-tasks.mdx b/src/content/docs/rover/guides/iterate-tasks.mdx index 015d1e8..2b85e87 100644 --- a/src/content/docs/rover/guides/iterate-tasks.mdx +++ b/src/content/docs/rover/guides/iterate-tasks.mdx @@ -36,6 +36,31 @@ Following the fizzbuzz example from the task creation guide, you can ask for an +## Provide context to iterations + +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. + + + + Add a GitHub PR as context to guide the iteration + + ```sh + rover iterate 1 "Align the implementation with the reviewed approach" -c github:pr/50 + ``` + + + Combine multiple context sources + + ```sh + rover iterate 1 "Update the API to match the spec" -c github:issue/20 -c file:./docs/api-spec.md + ``` + + + +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. + +See the [Provide context to tasks](/rover/guides/provide-context) guide for full details on supported sources and comment trust settings. + ## Review iteration changes 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: ## Related Guides + - diff --git a/src/content/docs/rover/guides/provide-context.mdx b/src/content/docs/rover/guides/provide-context.mdx new file mode 100644 index 0000000..1734e18 --- /dev/null +++ b/src/content/docs/rover/guides/provide-context.mdx @@ -0,0 +1,135 @@ +--- +title: Provide context to tasks +description: Supply external context from GitHub issues, pull requests, local files, and web resources to give AI agents the information they need +sidebar: + order: 5 +--- + +import StepList from '../../../../components/StepList.svelte'; +import StepItem from '../../../../components/StepItem.svelte'; +import { CardGrid, LinkCard } from '@astrojs/starlight/components'; + +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. + +## Supported context sources + +Rover resolves context URIs through built-in providers. You can combine multiple sources in a single command. + +| URI format | Description | Example | +|---|---|---| +| `github:issue/` | GitHub issue from the current repo | `github:issue/15` | +| `github:pr/` | GitHub PR with diff from the current repo | `github:pr/42` | +| `github://issue/` | Cross-repo GitHub issue | `github:acme/api/issue/8` | +| `github://pr/` | Cross-repo GitHub PR with diff | `github:acme/api/pr/31` | +| `file:./` | Local file (relative path) | `file:./docs/spec.md` | +| `file:///` | Local file (absolute path) | `file:///home/user/notes.md` | +| `https://` | Remote web resource | `https://example.com/api-spec.yaml` | + +:::tip +GitHub context requires the [GitHub CLI (`gh`)](https://cli.github.com/) to be installed and authenticated. +::: + +## Add context to a task + +Pass one or more `--context` flags when creating a task. Each flag accepts a context URI. + + + + Create a task with context from a GitHub issue and a local spec file + + ```sh + rover task -c github:issue/15 -c file:./docs/api-spec.md "Implement the new endpoint" + ``` + + Rover fetches the issue content and reads the local file, then provides both to the agent alongside the task description. + + + You can also provide context from a remote URL + + ```sh + rover task -c https://example.com/openapi.yaml "Generate client SDK from the API spec" + ``` + + + Follow the task progress + + ```sh + rover logs -f 1 + ``` + + + +:::tip +The `-c` short flag is equivalent to `--context`. You can repeat it as many times as needed to attach multiple sources. +::: + +## Add context to an iteration + +Context works the same way on iterations. Pass `--context` flags to `rover iterate` to provide additional information for a follow-up iteration. + + + + Add a PR as context to guide a refinement iteration + + ```sh + rover iterate 1 "Align the implementation with the reviewed approach" -c github:pr/50 + ``` + + + Follow the iteration progress + + ```sh + rover logs -f 1 2 + ``` + + + +### Context inheritance + +Context from previous iterations carries forward automatically. When you add new context to an iteration, it is merged with context from earlier iterations. + +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**. + +## Control comment visibility + +When using GitHub issues or PRs as context, comments and reviews are **excluded by default** to prevent prompt-injection from untrusted contributors. + +You can selectively include comments from trusted authors: + +```sh +# Trust specific authors +rover task -c github:issue/15 --context-trust-authors alice,bob "Fix the bug" + +# Trust all authors (use with caution) +rover task -c github:pr/42 --context-trust-all-authors "Review and address PR feedback" +``` + +The same flags work with `rover iterate`: + +```sh +rover iterate 1 "Address remaining review comments" -c github:pr/42 --context-trust-all-authors +``` + +## Best practices + +- **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. +- **Combine context with clear instructions**: Context provides information; the task description should explain what to do with it. +- **Scope context narrowly**: Provide only the sources relevant to the task. Too much unrelated context can dilute the agent's focus. +- **Use GitHub PRs for alignment**: When iterating on a task, referencing a related PR helps the agent understand the desired approach and coding patterns. +- **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. + +## Relevant Concepts + + + + + + +## Related Guides + + + + + + + diff --git a/src/content/docs/rover/reference/cli-reference.mdx b/src/content/docs/rover/reference/cli-reference.mdx index f8d9c33..29ebf73 100644 --- a/src/content/docs/rover/reference/cli-reference.mdx +++ b/src/content/docs/rover/reference/cli-reference.mdx @@ -77,7 +77,11 @@ rover task [options] [description] **Options:** -- `--from-github `: Fetch task description from a GitHub issue number +- `-c, --context `: Add context from a URI. Can be repeated. Supported schemes: `github:issue/`, `github:pr/`, `github://issue/`, `github://pr/`, `file:`, `https://` +- `--context-trust-authors `: Comma-separated list of trusted authors for comment inclusion +- `--context-trust-all-authors`: Trust all authors for comment inclusion (disables filtering) +- `--from-github `: *(Deprecated. Use `--context github:issue/`)* Fetch task description from a GitHub issue number +- `--include-comments`: *(Deprecated. Use `--context-trust-all-authors`)* Include issue comments in the task description (requires `--from-github`) - `--workflow, -w `: Use a specific workflow to complete this task - `-y, --yes`: Skip all confirmations and run non-interactively - `-s, --source-branch `: Base branch for git worktree creation @@ -174,6 +178,9 @@ rover iterate [options] [instructions] **Options:** +- `-c, --context `: Add context from a URI. Can be repeated. Supported schemes: `github:issue/`, `github:pr/`, `github://issue/`, `github://pr/`, `file:`, `https://` +- `--context-trust-authors `: Comma-separated list of trusted authors for comment inclusion +- `--context-trust-all-authors`: Trust all authors for comment inclusion (disables filtering) - `-i, --interactive`: Open an interactive command session to iterate on the task - `--json`: Output JSON and skip confirmation prompts