From 01b593c1c2a71386dfd2a169ecccb93efa998e08 Mon Sep 17 00:00:00 2001 From: Ben Stull Date: Tue, 9 Jun 2026 23:34:15 -0700 Subject: [PATCH] Add draft issue files for coauthoring plugin epic and PoC feature Co-Authored-By: Claude Opus 4.8 (1M context) --- issues/coauthoring-plugin-on-cline.md | 99 +++++++++++++++++++++++++++ issues/poc-extension-cline-sdk.md | 96 ++++++++++++++++++++++++++ 2 files changed, 195 insertions(+) create mode 100644 issues/coauthoring-plugin-on-cline.md create mode 100644 issues/poc-extension-cline-sdk.md diff --git a/issues/coauthoring-plugin-on-cline.md b/issues/coauthoring-plugin-on-cline.md new file mode 100644 index 0000000..0c0f09f --- /dev/null +++ b/issues/coauthoring-plugin-on-cline.md @@ -0,0 +1,99 @@ + + +## 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. diff --git a/issues/poc-extension-cline-sdk.md b/issues/poc-extension-cline-sdk.md new file mode 100644 index 0000000..3ae170e --- /dev/null +++ b/issues/poc-extension-cline-sdk.md @@ -0,0 +1,96 @@ + + +## Summary + +A **standalone VS Code extension** that activates in the Extension Development Host +and runs **one trivial Cline interaction via `@cline/sdk`** — proving Approach A +and giving every later coauthoring feature a place to land. A walking skeleton, not +a shippable product. + +## Problem / pain + +The whole Epic rests on **one unproven bet**: that *our own* standalone extension +can programmatically drive the Cline agent through `@cline/sdk`. Until that is +demonstrated end-to-end — repo builds → F5 launches the extension → a command +invokes the SDK → a result comes back — there is **no skeleton** to build +coauthoring into and the architecture is **unvalidated**. Every later Feature is +blocked on this foundation existing. + +## Who feels it + +The **dev team** building the plugin (this de-risks the architecture and unblocks +all subsequent work); ultimately the coauthoring user who benefits from a sound +foundation. + +## Desired outcome / value + +A **known-good starting point**: the repo builds, the extension loads, and a +command invokes `@cline/sdk` and surfaces a result — so subsequent Features +(threads, attribution, propose/accept) have a foundation, and the `@cline/sdk` +approach is **confirmed early** (or we learn early that it isn't viable, while the +cost of changing course is still near zero). + +## Acceptance — "done right" + +- The repo contains a **buildable** VS Code extension: `package.json` (publisher, + `engines.vscode`, one contributed command + activation), `tsconfig.json`, an + esbuild bundle, ESLint, `.vscode/launch.json`. +- Pressing **F5** launches the Extension Development Host with the extension + **active**. +- A contributed command (e.g. *"Cowriting: Hello via Cline"*) invokes `@cline/sdk` + to run **one trivial interaction** and surfaces the result (a notification or + output-channel line). *If a live agent turn needs credentials not present in CI, + it is acceptable for the smoke path to instantiate the SDK and confirm the + integration surface (version/connectivity) instead — the point is the wiring.* +- **One smoke test passes in CI** (build + activate/import). +- It is **explicitly NOT shippable** and implements **no coauthoring** behavior — + pure proof of concept + skeleton. + +## Scope / non-goals + +**In scope:** the extension scaffold; `@cline/sdk` declared and wired; one +SDK-driven command; the build / test / run (F5) loop; a one-line README on how to +run it. + +**Out of scope:** any coauthoring (threads, attribution, diff flow); packaging / +marketplace publishing; auth/secret hardening beyond what a local dev run needs; +multi-file or agent choreography. + +## Assumptions · constraints · dependencies + +- `@cline/sdk` is installable via npm and runs under Node ≥22. +- A local Claude credential/config is available for a live SDK turn (the dev's + existing setup); **no secret bytes** go in this repo or issue — the SDK reads + them from the environment. *(Open question: exactly what `@cline/sdk` needs to + run a turn vs. just initialize — resolved during the build.)* +- **Parent:** #1 (the coauthoring Epic). **Blocks:** F2–F5 (all later Features). +- **Source:** this capture session. + +## Source / signal + +Capture session `vscode-cowriting-plugin-0001`; parent Epic #1 +(`coauthoring-plugin-on-cline`). Architecture lineage: `ben.stull/rfc-app#48`. + +## Priority (WSJF) + +Provisional: **Value** medium (pure enabler) · **Time-criticality** high (blocks +every other Feature) · **Opportunity-enablement** high ÷ **Size** small → **P1**, +do first. + +## Decomposition (Feature → slice checklist) + +- [ ] Scaffold the extension (`package.json`, `tsconfig.json`, esbuild, ESLint, + `.vscode/launch.json`). +- [ ] Add `@cline/sdk` as a dependency and wire a minimal client. +- [ ] Contribute one command that runs a trivial `@cline/sdk` interaction and shows + the result. +- [ ] Add one smoke test + a CI workflow (build + test). +- [ ] README: "run it with F5" note. + +## Solution notes (optional — NOT a design) + +Keep the SDK call **trivial** (a one-shot prompt, or even a version/connectivity +check) — the value is the *wiring*, not capability. If `@cline/sdk`'s surface +differs from what we expect, that discovery **is** the value of this POC. Use +conventional npm + TypeScript + esbuild for our extension (Cline's own monorepo +uses Bun/Biome, but `@cline/sdk` is a plain Node package npm consumes fine).