Review Workspace

Review Workspace is a VS Code extension for intent-grouped review of Azure DevOps pull requests. It keeps diffs and durable review actions in Azure DevOps while using native GitHub Copilot Chat for read-only investigation.

Preview: Review Workspace is under active development. Review generated analysis and proposals before acting on them.

Requirements

• VS Code 1.100 or later.
• GitHub Copilot Chat with access to Copilot agent and chat features.
• An Azure DevOps account with access to the pull requests and repositories you want to review.
• Git available on the local machine for exact pull-request checkouts and local-change snapshots.

Review Workspace uses VS Code's Microsoft authentication flow for Azure DevOps and does not require a Personal Access Token. It does not collect telemetry. Session diagnostics remain on the local machine and exclude source content, comments, prompts, responses, credentials, and access tokens.

Quick start

1. Install Review Workspace and reload VS Code if prompted.
2. Open the Review Workspace activity-bar container.
3. Sign in when VS Code requests Microsoft or GitHub authentication.
4. Open an Azure DevOps Git repository to discover its organization and project, select the Review Inbox settings gear to add sources manually, or paste a full Azure DevOps pull-request URL.
5. Select a pull request to review its summary, intent groups, files, walkthrough, and discussions.

Review Inbox and Review Outbox

Review Workspace separates published incoming work from local work that is still being prepared:

• Review Inbox contains published review requests, currently Azure DevOps pull requests.
• Review Outbox contains local technical designs and stable snapshots of local Git changes before a pull request exists.

Review Outbox is a persistent catalog rather than a repository registry. Each item records its own repository or source context, so one Outbox can contain designs and code-change sessions from multiple repositories.

Each design also owns an editable context collection. Its primary repository is retained with the design, and additional repositories, local files or folders, web links, and requirement/decision notes can be added or removed. @review-outbox includes those entities when answering questions; bounded local document content is included directly and attached repositories remain available through read-only repository tools.

Select New design in Review Outbox to open the dedicated design composer. The composer gathers the title, requirements and problem context, primary and supporting repositories, files or folders, reference links, and requirement/decision notes in one surface before generation starts. Copilot uses bounded, read-only repository tools to create the technical design. Use Add design file to start a workspace from an existing Markdown or HTML file, or Export to repository to move an extension draft into a repository. An open design workspace can contain multiple Markdown and HTML documents. Use Add document to attach more files and switch between them without leaving the design review. After creation, attached Design Context is available under More actions so the primary review surface remains focused on navigation and feedback.

The design-generation workflow is also available from Copilot Chat through @design-review. The chat prompt becomes the initial requirements and constraints. Use @review-outbox to investigate the currently open Outbox design or code-change session.

The generated design includes goals, non-goals, acceptance criteria, assumptions, current state, proposed architecture, component impact, call-graph changes, sequence flows, alternatives, risks, validation, rollout, and open decisions. Architecture and sequence views are Mermaid diagrams rendered from the packaged extension under a restrictive webview content security policy; no CDN content is loaded.

Open the shared rendered-document preview from either Review Inbox or Review Outbox. Selecting rendered text offers phrase-level feedback and maps the selection back to Markdown or HTML source lines and columns. Markdown hover feedback targets the exact source line under the pointer; blocks remain the fallback for diagrams, tables, or selections that cannot be mapped safely. HTML uses a browser-parity sandbox that preserves the complete document structure, safe CSS, inline styles, native controls, SVG, and local or HTTPS assets. Review mode keeps comments available while removing author scripts and event handlers. Interactive mode runs author JavaScript inside an isolated frame while blocking nested browsing contexts, form submission, VS Code APIs, and access to Review Workspace controls. Fragment-only History API updates that browsers reject for opaque sandbox origins are safely ignored so they cannot prevent the rest of an interactive document from initializing. Both modes project comment markers and feedback composition through a trusted overlay outside the page DOM, with a persistent Add feedback action as a fallback when hover or text selection is unavailable. In Review Inbox, preview comments are published as source-anchored Azure DevOps threads. In Review Outbox, comments remain local. Copilot answers clarifying questions in the discussion without editing the document, while explicit add, remove, rewrite, update, or modify requests become document proposals. Existing comments and answers remain projected in the preview; Outbox proposals can be reviewed from the page and Discussions. Accepted or revised proposals refresh the sandbox and restore its latest scroll position. Local design threads can be deleted from the preview card, Outbox Discussions, or the native VS Code comment thread. Newly submitted threads appear immediately at their document anchor with a Copilot is working status. CRUD-style instructions such as add, update, modify, replace, remove, or delete are deterministically routed to document proposals; an answer-only result is rejected and retried.

Each Markdown thread keeps its own line marker even when several comments share a rendered block. Proposal-ready Discussion cards expose View changes, Keep, Undo, and Ask to revise in place; opening the native diff selects and centers the proposed hunk.

When Copilot finishes a clarifying design comment, the matching thread is automatically reopened in either the Markdown preview or the HTML trusted overlay. Local code-change comments use the same answer-versus-change intent rule, immediately project a persistent native comment on the snapshot range, show working/answer/proposal state in Discussions, and reopen the exact range when processing completes.

The design workspace lists every document with its open-feedback and proposal counts. Its Outline tab derives a Word-style hierarchy from Markdown headings or HTML h1-h6 elements and follows the currently selected document. The Discussions tab shows comments and proposals for the current file or summarizes open discussions across all workspace documents. Selecting a heading reveals the matching source and rendered-preview section, follow-cursor highlights the active section, heading badges show open feedback and pending proposals, and the heading search filters the visible navigation tree as text is entered.

Opening a design from Review Outbox opens the rendered preview by itself; Open source remains available under More actions. For explicit document changes, Copilot creates a focused document-only proposal hunk. Proposal decisions stay visible in Review Outbox and in the inline preview rather than using a modal prompt. Users can view the native diff, Keep or Undo each hunk, ask Copilot to revise it inline, or choose Keep all and Undo all. Review Workspace applies accepted proposal hunks only when:

• the comment still matches the current document hash,
• the replacement stays within the commented level-2 section,
• the complete document still satisfies the technical-design contract, and
• no other VS Code window is revising the same design.

Failed, rejected, or stale proposals remain visible. Implementation source files are never changed by design comments.

Review Outbox catalog, item, snapshot, feedback, proposal, and draft artifacts are stored under:

<VS Code extension global storage>/review-outbox/

Review Outbox reads only its current catalog format during startup. It does not scan or migrate legacy design-session state.

Select Track local changes to capture committed branch changes relative to a detected or selected base together with staged, unstaged, and untracked text changes. Review Workspace stores immutable base/head artifacts for source comments and diffs without changing the Git branch, index, worktree, or configuration. When the review is ready, Create Azure DevOps PR opens Copilot Agent with every file represented by the Outbox snapshot plus the generated review summary and metadata. The publish click authorizes the agent to prepare any required commit, push the named branch, and create the pull request without requiring files to be individually marked reviewed. Review Workspace discovers the active Azure DevOps pull request, stores its identity and latest published commit, replaces the creation action with an Open PR link, and offers Push updates for later local changes. If the repository changes, the session is marked stale until its snapshot is refreshed or its updates are published.

Local code sessions use the same review organization as pull requests: the review summary card followed by Intent Groups, Files, Walkthrough, and Discussions. The walkthrough initially follows the deterministic intent groups, while Discussions lists feedback anchored to the immutable snapshot.

Pull requests and local code sessions render through a shared code-review surface and provider-neutral content model. Provider adapters supply different capabilities: Azure DevOps sessions expose votes, auto-complete, and shared threads, while local sessions expose snapshot refresh, Copilot proposals, and local feedback.

Code comments create focused Copilot proposals against the captured snapshot. Applying a proposal requires the current working file to match the expected snapshot hash, preventing stale proposals from overwriting newer edits.

Capabilities

• Keeps published requests in Review Inbox and local work in Review Outbox.
• Creates and reviews extension-managed or repository technical designs.
• Captures stable local Git snapshots for pre-PR code review.
• Renders local Mermaid architecture and sequence diagrams.
• Stores source-anchored local feedback and proposals outside the repository.
• Requires explicit Apply, Reject, or Revise approval for Copilot proposals.
• Opens an Azure DevOps pull request from its URL and loads the current iteration.
• Uses an authored semanticIntentGrouping block when one is present in the PR description. When authored groups do not cover every changed file, they are passed to local Copilot as trusted seeds while it inspects and groups the remaining files. For a fresh revision without usable authored metadata, Copilot inspects bounded base/head change summaries and must assign every changed file exactly once to semantic intent groups. Deterministic, explainable completion is shown only when semantic grouping fails.
• Shows the deterministic groups and opens their diffs immediately while Copilot semantic grouping runs in the background. When analysis finishes, the file nodes move into the semantic groups unless the reviewer edited the provisional map.
• Prepares compact changed-file summaries once and reuses them for independent Review Summary and semantic-grouping requests.
• Opens on a dedicated Summary tab with concise Why, Before, and After cards. Summary generation runs in parallel with intent grouping and can be retried independently.
• Shows live Copilot progress for Review Summary, intent groups, and Code Walkthrough, including completion, failure, cancellation, and results that were intentionally not applied.
• Opens base/head content in the native VS Code diff editor.
• Prefetches Azure DevOps discussions and projects current head-side threads into VS Code's native comment gutter and Comments panel.
• Uses the shared rendered-document preview for Markdown and HTML PR files, including browser-parity HTML modes, line-based Markdown feedback, source mapping, and projected Azure DevOps discussions.
• Creates, replies to, resolves, and reactivates Azure DevOps discussion threads only after reviewer confirmation.
• Publishes an iteration-scoped review status only after reviewer confirmation.
• Starts PR-, intent-group-, or selected-file conversations in native Copilot Chat through @review-workspace.
• Imports a debugger-like Code Walkthrough from a versioned code-walkthrough block in the PR description.
• Generates a local fallback walkthrough with Copilot when authored metadata is absent, stale, or invalid.
• Persists a privacy-safe JSONL diagnostic file for each loaded PR session, including the selected map source, fallback reason, classification counts, warnings, and operational Output-channel events.

Pull Request Review Metadata skill

The VSIX includes a pull-request-review-metadata agent skill for agents that create or update Azure DevOps pull requests. The skill defines:

• A human-readable PR description structure covering summary, motivation, changes, validation, risk and rollout, related work, and a compact Review guide.
• The version 1 review-summary contract consumed by the Summary tab.
• The version 1 semanticIntentGrouping contract consumed by the Intent Groups view, including authored risk, confidence, and direct intent dependencies.
• The version 1 code-walkthrough contract consumed by Code Walkthrough.
• Shared policies and JSON schemas under the skill's references/ directory; the extension embeds the same files in its local Copilot prompts.
• Installation synchronizes the complete bundled skill directory, removing obsolete files after replacement is confirmed.
• Freshness, changed-file coverage, source-anchor, safe-update, and PR read-back validation requirements.

Run Review Workspace: Install Pull Request Review Metadata Skill from the Command Palette to install it at:

~/.copilot/skills/pull-request-review-metadata/SKILL.md

This is a personal GitHub Copilot skill, so it applies across the user's projects without adding files to each repository. Running the command again updates the installed copy. If the personal copy was modified, Review Workspace asks before replacing it; an identical copy is left unchanged.

VS Code must have Chat: Use Agent Skills (chat.agent.skills) enabled for Copilot to discover installed skills. The packaged source is located under resources/skills/pull-request-review-metadata/ in the extension. Installation copies the complete skill directory, including its shared policies and versioned schemas.

Review Summary and Code Walkthrough

The Summary tab is the default review surface. It presents a concise executive briefing as separate Why this change, Before, and After cards. Review Workspace prefers exact-head review-summary metadata, can import the legacy summary from older walkthrough metadata, and otherwise restores or generates an exact-head local summary. Local generation starts alongside semantic intent grouping and has independent progress and retry handling.

The unified Code Walkthrough view keeps progress, step selection, narration, and Start, Back, and Next controls together. The current step's source location, why it matters, reviewer question, intent, and transition stay visible while the native editor opens the exact code. Intent groups are collapsed by default to preserve space, and Discussions remains collapsed until needed while its badge shows the number of active threads. Before step 1, the walkthrough shows that its critical path is ready and keeps the executive briefing in the separate Summary tab.

Changed steps open the exact base/head PR diff and select the declared source range. Context steps open an exact-head, read-only virtual document and are clearly labeled CONTEXT · UNCHANGED IN THIS PR; they explain connections but do not inflate changed-file review coverage. Existing Azure DevOps comments remain projected on changed base/head documents.

PR-authored walkthroughs are preferred and must match the current head commit, intent groups, changed-file classification, graph references, and source anchors. When authored metadata is absent, stale, or invalid, Copilot automatically prepares compact summaries for every changed file and generates a local walkthrough after intent grouping settles. Repository reads and search remain available for exact ranges and verified relationships. Generate Code Walkthrough remains available to retry or regenerate. Generated walkthroughs remain local and are persisted only for that exact PR iteration/head.

The PR-authoring skill may enrich a walkthrough with grounded evidence, alternatives, rationale, and decisions. Local generation preserves such authored details when valid but does not invent them when they are absent; it generates the source-grounded critical path from the context available in VS Code.

Code Walkthrough uses a concise critical path rather than narrating every changed file. It starts with an intent and path orientation, then shows each major decision point with one explanation and one concrete reviewer question. There is no hard step limit; large pull requests can include the additional decision points required to cover their independent intents. Verified relationship narration stays out of the default view; inferred connections remain visible so uncertainty is not hidden.

The initial player follows the first transition automatically and asks the reviewer to choose when a step branches. Evidence and discussion steps can carry narration without opening source. The walkthrough does not publish comments, change the PR description, or write model output to Azure DevOps.

Native Copilot Chat

The extension contributes the @review-workspace chat participant and depends on the GitHub Copilot Chat extension. Use the chat icon on the Intent Groups view for the full PR, an intent group's context menu for that group, or the sparkle action that appears when hovering over a changed file. The same Ask About This Diff action remains visible in the editor title while a Review Workspace diff is open. Follow-up questions stay in the same native chat.

Use the adjacent check action on an intent group or changed file to toggle its reviewed state. Reviewed files and groups show a green check; groups with only some reviewed files show a partial state and reviewed-file count. Review progress is saved for the exact pull request iteration alongside reviewer grouping edits.

The PR Review view keeps the current Azure DevOps review decision above the intent groups. Its split menu supports Approve, Approve with suggestions, Wait for author, Reject, and Decline to review. Auto-complete can be set or cancelled without changing the pull request's existing completion options; actions that reject, decline, or enable automatic completion require explicit confirmation.

For source investigation, the participant exposes two private read-only tools:

• Read a bounded line range from a repository file.
• Search tracked text files for literal text.

The tools operate on a detached checkout verified against the PR head commit, not whichever repository or revision happens to be open in VS Code. Tool calls are bounded by result size, call count, and round count. They cannot edit files, run arbitrary commands, or write to Azure DevOps. On Windows, the extension enables Git long-path handling on its managed repository cache before creating the checkout, so deeply nested repository paths do not require a global Git configuration change. Managed PR worktrees that have not been used for seven days are removed by a background cleanup. The shared partial Git object cache remains available, and an exact worktree is recreated automatically when that PR revision is needed again.

Unlike the experimental ACP variant, the native extension does not fetch base and head content for every changed file before the first question. Copilot requests source lazily through the exact-head tools, so selected-file and selected-group questions prepare only the context they need.

Open a pull request

Opening the Review Workspace activity-bar container loads a lightweight Review Inbox across the configured Azure DevOps organization/project sources. Active, non-draft pull requests are shown without automatic priority scoring. The default view groups them into Assigned to me and Tracked repositories. The Group control can instead organize the same in-memory results by Repository or Review state. Review-state sections are Awaiting review, Waiting for author, Changes requested, Reviewed, and Not assigned. Pull request cards call out Waiting for author, Changes requested, and Reviewed as tags; Awaiting review and Not assigned remain implicit.

The Sort control orders PRs by Age, Repository, Author, or Review state without another Azure DevOps request. Review-state sorting uses the same order as the review-state groups. Age defaults to oldest first. Grouping, sort field, and direction are stored locally per user and restored when VS Code is reopened.

Use Review Workspace: Reset Local Data from the Command Palette to return the extension to a blank local state. It removes configured sources, tracked repositories, inbox and Copilot-context caches, dismissed-repository state, view preferences, and persisted review/walkthrough progress.

After the initial list appears, Review Workspace checks blocking Azure DevOps policies and asks Copilot to classify business-impact evidence from the full PR description and linked work items. These pipelines run in parallel and show progress in the inbox for both assigned and tracked PRs. Their results are informational labels only—such as required checks pending, bug fix, customer impact, or release blocker—and never reorder or regroup cards. Copilot context results are cached locally by PR head commit. Requests use context-size-aware batches and split failed batches into smaller requests. Active pull requests older than 14 days are excluded by default so abandoned work does not dominate the inbox. The threshold can be changed with reviewWorkspace.maxInboxPullRequestAgeDays.

Review Inbox sources are stored per user in reviewWorkspace.azureDevOpsScopes. The extension seeds this list from the Azure DevOps Git remotes in open workspaces, assigned pull requests discovered for the signed-in identity, and manually opened pull request URLs. Sources can also be added or removed from the Review Inbox settings. They are queried in parallel; a source-specific failure is shown as a warning without hiding results from other organizations. When none of those sources are available, the extension discovers Azure DevOps organizations from the authenticated profile, finds projects containing active pull requests assigned to that identity, and persists those organization/project pairs as inbox scopes. Use the gear button in the Review Inbox title bar to add or remove sources.

Repositories followed by the user are stored separately in reviewWorkspace.inboxRepositories. When a pull request is opened manually from an untracked repository, Review Workspace offers to include that repository. Repositories containing a direct required-reviewer assignment are also learned automatically. Their active PRs appear in a separate Tracked repositories section and are not presented as personal assignments. The source-management gear can remove a tracked repository; an explicitly removed repository is not automatically re-added by later required-review discovery.

The activity-bar container keeps Review Inbox and Review Outbox as independent top-level destinations in one adaptive shared view. Before a PR is selected, PR-specific review surfaces are hidden. After selection, Review Inbox is replaced by a compact current-PR header and decision card. Summary, Intent Groups, Files, Walkthrough, and Discussions act as section tabs so only one review surface uses the remaining vertical space. Review Inbox returns to the inbox list without discarding the loaded PR session.

Inbox startup intentionally performs identity resolution, one assigned-PR query per configured source, and bounded active-PR queries for tracked repositories. Results are cached for five minutes. Policy evaluation, full PR descriptions, linked work items, and Copilot context analysis start only after the initial list is rendered. Changed files, repository checkout, semantic grouping, and walkthrough generation still start only after a reviewer selects a PR.

1. Open the Review Workspace activity-bar container.
2. Select a pull request, or select Open Pull Request to paste a full Azure DevOps pull-request URL.
3. Select a file to open its diff, or use a chat action to investigate the PR.

In a head-side diff, select a range and use the comment gutter to draft a new thread. Existing current-iteration threads appear inline and accept replies, resolution, and reactivation. Every write shows a confirmation before it is sent to Azure DevOps. PR-wide, outdated, and otherwise unmappable threads remain available in the Discussions view.

The extension obtains Azure DevOps access through the signed-in VS Code authentication flow. It does not require a PAT.

Session diagnostics

Each PR load creates a local diagnostic file under the extension's persistent global storage. Use Review Workspace: Open Current Session Diagnostics or the diagnostics action in the Intent Groups title bar to open the current JSONL file.

The first record identifies the PR iteration and head commit, whether the map came from authored metadata, Copilot semantic grouping, deterministic fallback, or restored workspace state, and why fallback was selected. It also records semantic-grouping success or failure, correction and tool-call counts, group counts, and the path plus rule explanation for files under Needs classification. Subsequent records mirror Review Workspace Output-channel events.

Semantic grouping accepts up to 500 changed paths in one read request, fetches at most 8 files concurrently, and compacts large responses while retaining an entry for every inspected path. A generation may use up to 40 tool calls and 30 model rounds, with up to 3 correction attempts for invalid final output.

Diagnostics never contain file contents, diff bodies, comments, Copilot prompts or responses, credentials, or access tokens. The extension retains the newest 50 session files locally.

Security boundary

• Azure DevOps credentials are passed only to Azure DevOps requests and Git child processes used to prepare the exact PR checkout.
• Credentials are never included in Copilot prompts or tool results.
• The Copilot participant has no Azure DevOps write tool.
• Preview comment submission is the reviewer confirmation to publish the source-anchored Azure DevOps thread. Other thread status and review-status changes retain their explicit confirmation flows.
• Repository paths are normalized and checked against the detached checkout; .git, absolute paths, traversal, and symlink escapes are rejected.
• Markdown rendering is sanitized and blocks arbitrary script execution.

Rendered-document preview architecture

Review Workspace uses a shared Markdown/HTML preview architecture with a trusted comment overlay, sanitized review mode, and an isolated interactive sandbox.

Build and package

npm install
npm test
npm run typecheck
npm run package

The package is written to packaged\review-workspace.vsix.

Install it with:

code --install-extension packaged\review-workspace.vsix --force

Distributing private builds via OneDrive

For private testing outside the Marketplace, use scripts\publish-to-onedrive.ps1 to share a built VSIX with other reviewers:

npm run package
npm run publish:onedrive

This uploads the current packaged\review-workspace.vsix to a OneDrive folder (default Apps/ReviewWorkspace) as two files:

• A timestamped, versioned copy (e.g. review-workspace-0.1.0-20260904-155200.vsix) kept for history/rollback.
• review-workspace-latest.vsix, overwritten on every run so it always contains the newest build.

It then creates (or reuses) an organization-scoped sharing link on review-workspace-latest.vsix — accessible to anyone signed in inside the Microsoft tenant, not the public internet — and prints it along with the upload history for the folder.

Requirements:

• PowerShell 7+ (pwsh) and the Microsoft.Graph.Files / Microsoft.Graph.Authentication modules (installed automatically on first run via Install-Module -Scope CurrentUser).
• Interactive sign-in the first time (Connect-MgGraph); no app registration, client secret, or admin consent is required because it uses delegated Files.ReadWrite scope against your own OneDrive.

Share the printed stable link (pointing at review-workspace-latest.vsix) in Teams/wiki/email. It always resolves to whatever you most recently published, so recipients only need one link, ever.

Installing from the shared link (for recipients)

1. Open the link in a browser while signed in with your work account, then Download the .vsix file.
2. In VS Code, open the Extensions view (Ctrl+Shift+X) → click the ... menu → Install from VSIX... → select the downloaded file.
3. Reload VS Code when prompted. If GitHub Copilot Chat isn't already installed, accept the prompt to install it too (it's a required dependency).

Or from the command line after downloading:

code --install-extension "$env:USERPROFILE\Downloads\review-workspace-latest.vsix"

To pick up a newer build later, re-download from the same link and run Install from VSIX... again — it overwrites the existing installation. There is no in-editor auto-update with this distribution method; that requires a private extension gallery (see the improvement backlog).

To see who downloaded a build, open the file in OneDrive/SharePoint and use Details → Activity, or query the Microsoft 365 unified audit log:

Search-UnifiedAuditLog -Operations FileDownloaded -StartDate (Get-Date).AddDays(-7) -EndDate (Get-Date) `
  | Where-Object { $_.AuditData -like "*review-workspace*" }