Ben Stull
100 lines
4.7 KiB
Markdown
100 lines
4.7 KiB
Markdown
<!-- Set the type/* label: type/epic -->
|
|
|
|
## Summary
|
|
|
|
An inner-loop **VS Code extension** that delivers human+machine **coauthoring** on
|
|
local files — live **human/Claude attribution** (what the machine changed vs. what
|
|
you changed, in the buffer), **region-anchored threads**, and a **propose/accept**
|
|
flow — built as a **standalone extension on Cline's `@cline/sdk`** agent.
|
|
|
|
## Problem / pain
|
|
|
|
Coauthoring with an AI in the editor today has **no persistent threads** and **no
|
|
solid attribution/provenance**: you can't see which spans the machine wrote vs.
|
|
which you wrote, and discussion isn't anchored to document regions. Claude for VS
|
|
Code can take a highlighted region as context but keeps **no durable record**. The
|
|
forge (Gitea / rfc-app) is the *outer* loop — review, multi-party deliberation, a
|
|
durable record. The **inner loop**, where writing actually happens keystroke by
|
|
keystroke, has no home.
|
|
|
|
## Who feels it
|
|
|
|
A writer/engineer **coauthoring prose or specs with Claude inside VS Code** — one
|
|
human + one machine to start. (Later rungs add teams and the public process.)
|
|
|
|
## Desired outcome / value
|
|
|
|
The editor becomes a **real coauthoring surface**: attribution + anchored threads
|
|
+ propose/accept, persisted **git-natively** so it is serverless, durable, and
|
|
**portable up to the Gitea rung later** without re-homing. This validates the
|
|
coauthoring UX as the cheapest, fastest path to the core value — **before** any
|
|
server or Gitea investment.
|
|
|
|
## Acceptance — "done right"
|
|
|
|
A human can coauthor a document with Claude in VS Code and:
|
|
|
|
- see, live in the buffer, which spans are **human** vs. **Claude** (attribution);
|
|
- attach **threads to document regions** that survive the document being edited;
|
|
- **accept / reject** Claude's proposed diffs (propose-by-default);
|
|
- with all provenance and threads stored as **git-native artifacts** (no server).
|
|
|
|
(Epic-level end-state; the Features below refine each piece.)
|
|
|
|
## Scope / non-goals
|
|
|
|
**In scope:** standalone extension on `@cline/sdk`; 1 human + 1 machine; local
|
|
files; git-native persistence of attribution + threads.
|
|
|
|
**Out of scope (deferred, not forgotten):** turn-taking choreography; multi-file
|
|
orchestration; the **Gitea team rung** (rfc-app#46); the **rfc-app public-process
|
|
rung**; other editors (JetBrains, etc.); **any server** for v1.
|
|
|
|
## Assumptions · constraints · dependencies
|
|
|
|
- **Architecture = Approach A:** a *standalone* extension that drives the agent via
|
|
`@cline/sdk` — **not** a fork of Cline, **not** a companion trying to extend
|
|
Cline's UI (VS Code extensions can't easily extend another's UI — rfc-app#48 Q2).
|
|
- Built on **Cline `@cline/sdk`** (Apache-2.0; programmatic agent + tool/plugin
|
|
registration + MCP). Depends on its API stability.
|
|
- Part of a **three-rung ladder**, each a client of **one shared git-native model**
|
|
(provenance, attributed diffs, anchored threads): editor (this) → Gitea
|
|
substrate (#46) → rfc-app. *git is truth; the surfaces are clients.*
|
|
- **Blocks:** nothing yet. **Source:** rfc-app#48.
|
|
|
|
## Source / signal
|
|
|
|
- `ben.stull/rfc-app#48` — "VS Code coauthoring plugin: the inner-loop rung" (the
|
|
capture-phase seed for this Epic), sibling of #46 (Gitea substrate rung).
|
|
- Capture session `vs-code-cowriting-plugin-0001` — Approach decision (standalone
|
|
on `@cline/sdk`) explored here against Cline's published SDK.
|
|
|
|
## Priority (WSJF)
|
|
|
|
Provisional: **Value** high (core new capability + seeds the ladder) ·
|
|
**Time-criticality** medium · **Opportunity-enablement** high ÷ **Size** large
|
|
(epic) → **P1**.
|
|
|
|
## Decomposition (Epic → Features)
|
|
|
|
Decomposed **one level at a time** — only the first Feature is filed now; the rest
|
|
are the planned shape, filed later as the Epic advances:
|
|
|
|
- [ ] **F1 — POC: runnable extension skeleton that drives `@cline/sdk`** → **#2**
|
|
*(filed this session — de-risks Approach A and establishes the project skeleton).*
|
|
- [ ] F2 — Region-anchored threads (VS Code Comments API), persisted git-natively.
|
|
- [ ] F3 — Live human/Claude attribution (Decorations API), tracking
|
|
applied-proposal edits vs. human keystrokes.
|
|
- [ ] F4 — Propose/accept diff flow (inline-diff keep/reject).
|
|
- [ ] F5 — Git-native persistence format (`.threads/` sidecar vs. git notes vs.
|
|
trailers) + round-trip to the Gitea rung (#46).
|
|
|
|
## Solution notes (optional — NOT a design)
|
|
|
|
Native primitives already exist for the differentiated bits: **Comments API** for
|
|
region threads, **Decorations API** for attribution, **inline-diff keep/reject**
|
|
for propose-by-default. `@cline/sdk` supplies the agent without a fork. The full
|
|
Solution Design (git-native format, live-attribution anchoring, where Claude runs,
|
|
server-or-not) is a follow-on brainstorming session — see rfc-app#48's open
|
|
questions.
|