faro-mvp-spec.md

Faro MVP Spec

Proposal status directory: proposals/in-progress/

Purpose

This document is the working spec and status tracker for Faro's first usable MVP.

Use it to answer three questions:

1. What is in scope for the MVP?
2. What is already implemented?
3. What is the next slice to build?

This file should be updated whenever a milestone or acceptance criterion changes state.

Status Legend

• done: implemented and verified
• in_progress: currently being built
• planned: accepted scope, not started
• blocked: cannot proceed without resolving a dependency or decision
• out_of_scope: explicitly excluded from this MVP

Product Definition

Faro is a VS Code extension that lets an agent turn codebase understanding into a persistent, navigable sequence of annotated code landmarks.

MVP Outcome

The first usable MVP is done when all of the following are true:

• a user can load the extension in VS Code
• the extension exposes a real Faro sidebar experience
• an outline of paths and beacons is visible in the sidebar
• a navigator view shows the current beacon and supports Prev / Next
• selecting or navigating a beacon reveals the target code range in the editor
• Faro state is stored per workspace
• the canonical schema, navigation logic, and adapters pass npm run check and npm test

Scope

In Scope

• one workspace-local store
• one active path at a time
• one active beacon at a time
• linear mainPath navigation only
• VS Code extension host integration
• Outline TreeView
• Navigator WebviewView
• editor reveal for the active beacon
• active beacon highlight
• workspace-scoped persistence
• a minimal agent-facing contract
• a Faro skill aligned with the contract

Out Of Scope

• graph or branch UI
• collaborative editing
• extension-side code analysis
• complex stale-range healing
• inline MCP App UI

Architecture Constraints

• src/core/** is the canonical model and state layer
• src/app/** is pure projection/use-case logic
• src/infra/** is the only VS Code or transport adapter layer
• all UI and future MCP writes must go through one canonical store
• views must render derived state, not own business rules
• npm run check and npm test are required verification gates for each slice
• commit after every completed slice

Current Repository Status

Foundation

Status: done

• TypeScript project using ESM
• node:test test suite
• npm run check
• canonical document model
• validation logic
• path navigation logic
• in-memory store
• workspace-state persistence adapter
• app-layer outline projection
• app-layer navigator projection
• real extension composition root
• runtime command surface
• outline adapter
• navigator adapter
• editor navigation adapter
• concrete VS Code outline registration
• concrete VS Code navigator registration
• concrete VS Code command registration
• editor reveal/highlight wiring through activation
• Faro skill scaffold

Verification:

• npm run check
• npm test

Current Limitation

Status: in_progress

The protocol-backed Faro authoring loop is now verified through the registered local stdio MCP server, but Faro still lacks higher-level authoring ergonomics:

• no manual VS Code chat-session validation yet
• no richer authoring operations beyond whole-path replace/update
• no dedicated empty-state flow for the first agent-authored path

Implementation Status

Slice 0: Foundation

Status: done

Acceptance criteria:

• canonical Faro document types exist
• validation exists for document, URI, and range integrity
• path movement exists for next/previous/current selection
• store supports load, replace, subscribe, upsert, selection, and delete
• tests cover core, app projections, and infra adapters

Slice 1: Extension Composition Root

Status: done

Acceptance criteria:

• activate() constructs one canonical store instance
• runtime owns subscriptions and refresh lifecycle
• command/controller wiring exists in one place
• no business logic moves into extension entrypoint
• runtime exposes setCurrentBeacon

Slice 2: Outline TreeView

Status: done

Acceptance criteria:

• outline adapter exists and renders paths and beacons from store state
• emitted command payloads route through the runtime command surface
• Faro container shows a concrete VS Code outline view
• active path/beacon state is reflected visually

Slice 3: Navigator WebviewView

Status: done

Acceptance criteria:

• navigator adapter renders current beacon title, summary, explanation, and position
• webview message bridge supports Prev, Next, and Reveal
• navigator re-renders from runtime refresh events
• empty states are handled explicitly
• concrete VS Code WebviewView registration exists

Slice 4: Editor Reveal And Highlight

Status: done

Acceptance criteria:

• editor navigation adapter exists
• current beacon opens the target document
• target range is revealed in the editor
• one active beacon highlight is applied
• invalid file/range cases fail without throwing

Slice 5: Workspace Persistence Integration

Status: done

Acceptance criteria:

• extension uses workspace-scoped persistence in the real runtime
• reload preserves active path and current beacon
• invalid persisted state falls back safely

Slice 6: Agent Enablement

Status: done

Acceptance criteria:

• a pure app service exposes listPaths, getPath, upsertPath, setActivePath, setCurrentBeacon, and deletePath
• the app service accepts canonical Faro types from src/core/model/document.ts
• every write reuses canonical validation and mutates the same store instance used by the UI
• Faro skill exists and explains how an agent should create/update paths
• skill uses the canonical Faro document shape, not a parallel schema
• root AGENTS.md constrains the beacon/path-selection agent role
• the agent is explicitly instructed to use the Faro skill pragmatically

Slice 7: MCP Integration

Status: done

Acceptance criteria:

• MCP tools are a thin adapter over the app service with no duplicated business rules
• MCP tools expose listPaths, getPath, upsertPath, setActivePath, setCurrentBeacon, and deletePath
• read tools are marked read-only where applicable
• read/write operations are consistent with extension state
• MCP-driven writes refresh the same runtime/view loop used by the sidebar
• invalid inputs fail safely without corrupting persisted state
• VS Code registers one local stdio MCP server definition over the runtime MCP surface
• happy-path agent flow works end to end

Immediate Next Slice

Next Slice

Manual chat validation and authoring ergonomics

Deliverables:

• manually validate the Faro MCP server from a real VS Code chat session
• tighten the first-path authoring UX and empty states
• add only the next authoring operation the workflow proves necessary
• keep AGENTS.md, the Faro skill, and the implemented MCP surface aligned

Why this next:

• the runtime, sidebar, and MCP loop are now proven at the protocol level
• the highest remaining risk is workflow quality, not basic integration
• the next product value is making authoring usable from a real agent session

Product TODOs

Extension-driven agent install UX

Status: planned

Need a first-class extension UX for installing Faro agent/skill artifacts without requiring terminal commands.

Acceptance criteria:

• Faro exposes a visible UI entrypoint inside VS Code for agent/skill installation
• the UI makes the install scope explicit: local vs global
• the UI covers the current Faro targets for Claude, Copilot, and Codex
• global installs preserve the current overwrite protections and require explicit confirmation when force would be needed
• install state and failure modes are surfaced in the extension UX instead of only through terminal output

Notes:

• this should likely be implemented as a menu, view action, or similar extension-native affordance
• do not hide scope selection behind opaque commands
• keep the extension UI aligned with the existing install semantics already implemented in the CLI/Make layer

Active path deletion UX

Status: planned

Need a first-class extension UX for deleting the current Faro path without dropping to indirect tooling.

Acceptance criteria:

• Faro exposes a visible delete action for the active path
• deletion requires explicit confirmation
• the action delegates to the canonical deletePath service behavior
• deleting the active path selects the next path when one exists
• deleting the last path falls back to Faro's normal empty state

Notes:

• keep the first slice focused on deleting the active path, not bulk path management
• reuse existing empty-state and refresh behavior instead of introducing a parallel delete workflow

Open Risks

• type drift between layers if local types are reintroduced outside src/core/model/document.ts
• accidental business logic leaking into VS Code adapters
• duplicated state if future MCP wiring bypasses the canonical store
• redundant refreshes if future write paths cause multiple equivalent store mutations
• overbuilding branch support before the linear MVP loop works
• contract drift between the Faro skill, AGENTS.md, and the eventual MCP tool schema

Update Rules

When finishing a slice:

1. update the slice status
2. update the acceptance criteria if scope changed
3. record any new blocker or risk
4. keep Current Repository Status aligned with reality
5. run npm run check and npm test
6. create a commit for that slice

Related Documents

• README.md
• docs/faro-plan.md
• Proposals README