Skip to content

spec.md

Latest commit

 

History

History
208 lines (156 loc) · 6.69 KB

spec.md

File metadata and controls

208 lines (156 loc) · 6.69 KB

AI Desktop Document Surface POC Spec

Summary

This repository simulates a first delivery sprint for an AI desktop application built on a VS Code / VSCodium-compatible shell. The POC focuses on a standalone extension package named markdown-workbench.

The extension demonstrates how Markdown files can be rendered as styled interactive surfaces inside a custom editor while sidecar YAML files provide workflow metadata, cards, and mock AI actions. The goal is to prove extension architecture, typed message passing, local file integration, and command routing without depending on real LLM infrastructure.

Product Framing

Working name: AI Desktop Document Surface

Primary demo story: A user opens a project brief in Markdown, sees a styled document surface instead of raw text, reviews metadata sourced from a YAML state file, and triggers local actions such as copying a prompt template, opening a related document, or revealing the source file.

Scope

Included

  • CustomTextEditorProvider for Markdown documents through Reopen With...
  • Markdown frontmatter parsing for title, summary, tags, status, related
  • Sidecar YAML loading from <basename>.meta.yaml
  • Styled HTML webview using VS Code theme variables
  • Action routing through webview.postMessage -> command handling -> VS Code notification/output
  • Lightweight WebviewViewProvider side panel showing active document summary and status
  • Live refresh when the Markdown file changes
  • Live refresh when the sidecar YAML file changes
  • Graceful fallback when sidecar YAML is missing

Not Included

  • Real LLM calls
  • Electron or VSCodium fork shell customization
  • Hidden IDE chrome behavior
  • Packaging or distribution changes to a forked desktop runtime
  • Multi-extension orchestration beyond a local command-routing demo

Data Model

Frontmatter

title: Project Brief
summary: Short overview for the rendered hero section.
tags:
  - onboarding
  - customer-facing
status: Ready for Review
related:
  - related-note.md

Sidecar YAML

File name pattern:

project-brief.md
project-brief.meta.yaml

Schema used in the POC:

owner: Product Ops
stage: Internal Review
lastUpdated: 2026-04-07
cards:
  - title: Priority
    value: High
    tone: warning
  - title: Audience
    value: Executive Team
    tone: info
actions:
  - id: copy-prompt
    label: Copy Prompt
    kind: copyPrompt
    prompt: Summarize this document for leadership.
  - id: notify-review
    label: Trigger Review
    kind: notify
    description: Mock routed command for review workflow.
  - id: open-related
    label: Open Related Note
    kind: openRelated
    target: related-note.md

Public Interfaces

View IDs

  • aiDesktopSurface.documentSurface
  • aiDesktopSurface.metadataView

Commands

  • aiDesktopSurface.runAction
  • aiDesktopSurface.openRelated
  • aiDesktopSurface.revealSource
  • aiDesktopSurface.refresh

TypeScript Types

  • DocumentFrontmatter
  • DocumentStateFile
  • DocumentCard
  • DocumentAction
  • SurfacePayload

Webview Messages

  • surfaceReady
  • runAction
  • openRelated
  • revealSource

Behavior

Document Surface

  • When a Markdown file is reopened with the custom editor, the extension parses frontmatter, renders Markdown body HTML, loads sidecar YAML, and builds a unified SurfacePayload.
  • The webview presents hero content, tags, rendered document body, metadata cards, action buttons, and related docs.
  • When the document changes, the payload refreshes automatically.
  • When the sidecar YAML changes, the payload refreshes automatically.
  • When sidecar YAML is missing, the document still renders with frontmatter and body content only.

Metadata Side View

  • Shows the currently active surface title, owner, stage, tags, and whether a sidecar file was found.
  • Provides quick actions for refresh and reveal source.
  • Updates whenever the active custom editor payload changes.

Command Routing

  • copyPrompt copies action prompt text to the clipboard and writes to the output channel.
  • notify shows a VS Code information message and writes to the output channel.
  • openRelated resolves a relative path from the current document and opens it in the editor.
  • revealSource opens the original Markdown text document.

Acceptance Criteria

  1. npm install, npm run compile, npm run lint, and npm run test all succeed.
  2. The extension runs in a VS Code Extension Development Host.
  3. A demo Markdown document can be reopened with AI Desktop Surface.
  4. The rendered page shows hero content, tags, cards, actions, and related docs.
  5. Action buttons trigger routed behavior without any backend dependency.
  6. The metadata side view reflects the active document surface.
  7. Removing the sidecar YAML still leaves a functional surface with reduced metadata.

Runbook

Local Setup

npm install

Build and Validation

npm run compile
npm run lint
npm run test

Run the Demo in VS Code

  1. Open the repository root in VS Code.
  2. Press F5 and launch the Run Markdown Workbench configuration.
  3. In the Extension Development Host window, open the demo-workspace folder if it is not already opened.
  4. Open project-brief.md.
  5. Run Reopen Editor With....
  6. Select AI Desktop Surface.
  7. Verify the Explorer view shows AI Surface Metadata.

Optional Packaging Check

npm run package:vsix

Expected artifact:

extensions/markdown-workbench/markdown-workbench-0.1.0.vsix

Acceptance Test Procedure

  1. Run npm install, npm run compile, npm run lint, and npm run test from the repository root.
  2. Start the Extension Development Host with F5.
  3. Reopen demo-workspace/project-brief.md with AI Desktop Surface.
  4. Confirm the rendered surface shows title, summary, tags, Markdown body, sidecar cards, and action buttons.
  5. Click Copy Prompt and confirm a VS Code notification appears and clipboard content is updated.
  6. Click Trigger Review and confirm a mock routed notification appears.
  7. Click Open Related Note and confirm related-note.md opens.
  8. Confirm the AI Surface Metadata side panel shows title, owner, stage, tags, and sidecar status.
  9. Edit project-brief.md and confirm the surface refreshes.
  10. Edit project-brief.meta.yaml and confirm metadata cards/actions refresh.
  11. Open fallback-only.md with AI Desktop Surface and confirm the document still renders without sidecar metadata.

Future Extensions

  • Replace mock actions with command delegation to other local extensions
  • Introduce shared protocol packages for multi-extension orchestration
  • Add document state persistence and bidirectional edits
  • Add VSCodium fork shell customizations and bundled extension strategy