Skip to content
miospotdevteamPublic

About

Interactive planning

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Orbit Artifact Review

A VS Code extension and MCP server for block-level artifact review with agent feedback loops.

Orbit lets you review generated artifacts (implementation plans, specs, etc.) directly in VS Code with semantic, block-anchored comments — not fragile line-based annotations. Agents can participate in the review cycle via MCP tools.

How it works

  1. Source (plan.md) — a markdown document (written by you or generated by an agent)
  2. Resolved artifact (plan.md.resolved) — auto-generated review artifact with stable block IDs and frontmatter
  3. Comments (plan.md.comments.json) — block-anchored comment threads
  4. Review state (plan.md.review.json) — tracks approval status and staleness

Review state machine

draft → in_review → changes_requested → in_review → approved
                  → approved → stale (if source changes) → in_review

Thread lifecycle

open → resolved | agent_applied | outdated (if block disappears on regeneration)

Features

VS Code editor:

  • Custom editor for *.md.resolved files with React-based UI
  • Hover-to-comment on any block
  • Inline threads with open/resolved/agent_applied/outdated states
  • Approve, Request Changes, and Regenerate from the toolbar
  • Keyboard navigation (j/k for blocks, [/] for threads)
  • Staleness detection and regeneration

MCP server (for agents):

  • orbit_generate_resolved — generate a resolved artifact and open it in VS Code
  • orbit_load_artifact — load an artifact's content
  • orbit_list_blocks / orbit_list_threads — inspect structure and feedback
  • orbit_get_review_state — check approval status
  • orbit_add_comment / orbit_reply / orbit_resolve_thread — participate in review
  • orbit_approve / orbit_request_changes — update review state
  • orbit_await_review — block until the user approves or requests changes

Getting started

Prerequisites

  • Node.js 18+
  • VS Code 1.85+

Build

npm install
npm run build

This produces three bundles in out/:

  • extension.js — VS Code extension
  • webview.js — React webview UI
  • mcp-server.js — MCP server (stdio)

Install as VS Code extension

npm run package   # creates orbit-artifact-review-0.1.0.vsix

Then install the .vsix in VS Code (Extensions > ... > Install from VSIX).

Run the MCP server

node out/mcp-server.js
# or via the bin entrypoint:
orbit-mcp

Development

npm run watch    # rebuild on changes
npm run lint     # type-check
npm test         # run tests (vitest)

Project structure

src/
├── extension.ts                    # VS Code activation and command registration
├── editor-provider.ts              # Custom editor provider for .md.resolved files
├── webview/app.tsx                  # React webview app
├── mcp/server.ts                   # MCP server with tool definitions
├── browser/components/             # React UI components
├── node/                           # Core services
│   ├── artifact-file-service.ts    # Bundle I/O, hashing, path conventions
│   ├── artifact-comment-service.ts # Thread CRUD and reattachment
│   ├── artifact-review-service.ts  # Review state machine
│   ├── artifact-resolution-service.ts  # Resolved artifact generation
│   ├── artifact-agent-bridge.ts    # Agent integration interface
│   └── __tests__/                  # Tests
└── common/                         # Shared types, parsers, schemas

License

MIT

About

Interactive planning

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages