From 3b4e0ae11f8b92dc0f0e77b74767c17456210fe5 Mon Sep 17 00:00:00 2001 From: Kieran Klaassen Date: Mon, 23 Feb 2026 13:24:08 -0800 Subject: [PATCH 1/2] feat: Add Proof editor integration Add proof skill for collaborative document editing via Proof's web API and local bridge. Integrate Proof uploads into brainstorm and plan workflows so outputs get a shareable URL automatically. Co-Authored-By: Claude Opus 4.6 --- .claude-plugin/marketplace.json | 4 +- .../.claude-plugin/plugin.json | 4 +- plugins/compound-engineering/CHANGELOG.md | 10 + plugins/compound-engineering/README.md | 3 +- .../commands/workflows/brainstorm.md | 25 +++ .../commands/workflows/plan.md | 25 +++ .../skills/proof/SKILL.md | 185 ++++++++++++++++++ 7 files changed, 251 insertions(+), 5 deletions(-) create mode 100644 plugins/compound-engineering/skills/proof/SKILL.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index de0fa74..725abd0 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -11,8 +11,8 @@ "plugins": [ { "name": "compound-engineering", - "description": "AI-powered development tools that get smarter with every use. Make each unit of engineering work easier than the last. Includes 29 specialized agents, 22 commands, and 19 skills.", - "version": "2.35.2", + "description": "AI-powered development tools that get smarter with every use. Make each unit of engineering work easier than the last. Includes 29 specialized agents, 22 commands, and 20 skills.", + "version": "2.36.0", "author": { "name": "Kieran Klaassen", "url": "https://github.com/kieranklaassen", diff --git a/plugins/compound-engineering/.claude-plugin/plugin.json b/plugins/compound-engineering/.claude-plugin/plugin.json index 5bb71ad..4d03ce3 100644 --- a/plugins/compound-engineering/.claude-plugin/plugin.json +++ b/plugins/compound-engineering/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "compound-engineering", - "version": "2.35.2", - "description": "AI-powered development tools. 29 agents, 22 commands, 19 skills, 1 MCP server for code review, research, design, and workflow automation.", + "version": "2.36.0", + "description": "AI-powered development tools. 29 agents, 22 commands, 20 skills, 1 MCP server for code review, research, design, and workflow automation.", "author": { "name": "Kieran Klaassen", "email": "kieran@every.to", diff --git a/plugins/compound-engineering/CHANGELOG.md b/plugins/compound-engineering/CHANGELOG.md index ede6b06..a6f04cd 100644 --- a/plugins/compound-engineering/CHANGELOG.md +++ b/plugins/compound-engineering/CHANGELOG.md @@ -5,6 +5,16 @@ All notable changes to the compound-engineering plugin will be documented in thi The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [2.36.0] - 2026-02-23 + +### Added + +- **`proof` skill** — Create, edit, comment on, and share markdown documents via Proof's web API and local bridge. Supports document creation, track-changes suggestions, comments, and bulk rewrites. No authentication required for creating shared documents. +- **Proof upload in `/workflows:brainstorm`** — After writing the brainstorm document, automatically uploads it to Proof and displays a shareable URL for collaborative review. +- **Proof upload in `/workflows:plan`** — After writing the plan file, automatically uploads it to Proof and displays a shareable URL for collaborative review. + +--- + ## [2.35.2] - 2026-02-20 ### Changed diff --git a/plugins/compound-engineering/README.md b/plugins/compound-engineering/README.md index ec1ad83..59b441b 100644 --- a/plugins/compound-engineering/README.md +++ b/plugins/compound-engineering/README.md @@ -8,7 +8,7 @@ AI-powered development tools that get smarter with every use. Make each unit of |-----------|-------| | Agents | 29 | | Commands | 22 | -| Skills | 19 | +| Skills | 20 | | MCP Servers | 1 | ## Agents @@ -134,6 +134,7 @@ Core workflow commands use `workflows:` prefix to avoid collisions with built-in | `every-style-editor` | Review copy for Every's style guide compliance | | `file-todos` | File-based todo tracking system | | `git-worktree` | Manage Git worktrees for parallel development | +| `proof` | Create, edit, and share documents via Proof collaborative editor | | `resolve-pr-parallel` | Resolve PR review comments in parallel | | `setup` | Configure which review agents run for your project | diff --git a/plugins/compound-engineering/commands/workflows/brainstorm.md b/plugins/compound-engineering/commands/workflows/brainstorm.md index b4f3a0f..06e6b77 100644 --- a/plugins/compound-engineering/commands/workflows/brainstorm.md +++ b/plugins/compound-engineering/commands/workflows/brainstorm.md @@ -119,6 +119,31 @@ Key decisions: Next: Run `/workflows:plan` when ready to implement. ``` +### Share to Proof + +After writing the brainstorm document, upload it to Proof for collaborative review: + +```bash +# Read the brainstorm file content +CONTENT=$(cat docs/brainstorms/YYYY-MM-DD--brainstorm.md) +TITLE="Brainstorm: " + +# Upload to Proof +RESPONSE=$(curl -s -X POST https://www.proofeditor.ai/share/markdown \ + -H "Content-Type: application/json" \ + -d "$(jq -n --arg title "$TITLE" --arg markdown "$CONTENT" --arg by "ai:compound" '{title: $title, markdown: $markdown, by: $by}')") + +PROOF_URL=$(echo "$RESPONSE" | jq -r '.tokenUrl') +``` + +Display the Proof URL prominently: + +``` +View & collaborate in Proof: +``` + +If the curl fails (network error, non-JSON response), skip silently and continue — Proof sharing is optional. + ## Important Guidelines - **Stay focused on WHAT, not HOW** - Implementation details belong in the plan diff --git a/plugins/compound-engineering/commands/workflows/plan.md b/plugins/compound-engineering/commands/workflows/plan.md index 9b1ab88..3a4a346 100644 --- a/plugins/compound-engineering/commands/workflows/plan.md +++ b/plugins/compound-engineering/commands/workflows/plan.md @@ -544,6 +544,31 @@ Use the Write tool to save the complete plan to `docs/plans/YYYY-MM-DD----plan.md) +TITLE="Plan: " + +# Upload to Proof +RESPONSE=$(curl -s -X POST https://www.proofeditor.ai/share/markdown \ + -H "Content-Type: application/json" \ + -d "$(jq -n --arg title "$TITLE" --arg markdown "$CONTENT" --arg by "ai:compound" '{title: $title, markdown: $markdown, by: $by}')") + +PROOF_URL=$(echo "$RESPONSE" | jq -r '.tokenUrl') +``` + +Display the Proof URL prominently: + +``` +View & collaborate in Proof: +``` + +If the curl fails (network error, non-JSON response), skip silently and continue — Proof sharing is optional. + **Pipeline mode:** If invoked from an automated workflow (LFG, SLFG, or any `disable-model-invocation` context), skip all AskUserQuestion calls. Make decisions automatically and proceed to writing the plan without interactive prompts. ## Output Format diff --git a/plugins/compound-engineering/skills/proof/SKILL.md b/plugins/compound-engineering/skills/proof/SKILL.md new file mode 100644 index 0000000..f4f5c4f --- /dev/null +++ b/plugins/compound-engineering/skills/proof/SKILL.md @@ -0,0 +1,185 @@ +--- +name: proof +description: Create, edit, comment on, and share markdown documents via Proof's web API and local bridge. Use when asked to "proof", "share a doc", "create a proof doc", "comment on a document", "suggest edits", "review in proof", or when given a proofeditor.ai URL. +allowed-tools: + - Bash + - Read + - Write + - WebFetch +--- + +# Proof - Collaborative Markdown Editor + +Proof is a collaborative document editor for humans and agents. It supports two modes: + +1. **Web API** - Create and edit shared documents via HTTP (no install needed) +2. **Local Bridge** - Drive the macOS Proof app via localhost:9847 + +## Web API (Primary for Sharing) + +### Create a Shared Document + +No authentication required. Returns a shareable URL with access token. + +```bash +curl -X POST https://www.proofeditor.ai/share/markdown \ + -H "Content-Type: application/json" \ + -d '{"title":"My Doc","markdown":"# Hello\n\nContent here."}' +``` + +**Response format:** +```json +{ + "slug": "abc123", + "tokenUrl": "https://www.proofeditor.ai/d/abc123?token=xxx", + "accessToken": "xxx", + "ownerSecret": "yyy", + "_links": { + "state": "https://www.proofeditor.ai/api/agent/abc123/state", + "ops": "https://www.proofeditor.ai/api/agent/abc123/ops" + } +} +``` + +Use the `tokenUrl` as the shareable link. The `_links` give you the exact API paths. + +### Read a Shared Document + +```bash +curl -s "https://www.proofeditor.ai/api/agent/{slug}/state" \ + -H "x-share-token: " +``` + +### Edit a Shared Document + +All operations go to `POST https://www.proofeditor.ai/api/agent/{slug}/ops` + +**Note:** Use the `/api/agent/{slug}/ops` path (from `_links` in create response), NOT `/api/documents/{slug}/ops`. + +**Authentication for protected docs:** +- Header: `x-share-token: ` or `Authorization: Bearer ` +- Token comes from the URL parameter: `?token=xxx` or the `accessToken` from create response + +**Comment on text:** +```json +{"op": "comment.add", "quote": "text to comment on", "by": "ai:", "text": "Your comment here"} +``` + +**Reply to a comment:** +```json +{"op": "comment.reply", "markId": "", "by": "ai:", "text": "Reply text"} +``` + +**Resolve a comment:** +```json +{"op": "comment.resolve", "markId": "", "by": "ai:"} +``` + +**Suggest a replacement:** +```json +{"op": "suggestion.add", "kind": "replace", "quote": "original text", "by": "ai:", "content": "replacement text"} +``` + +**Suggest a deletion:** +```json +{"op": "suggestion.add", "kind": "delete", "quote": "text to delete", "by": "ai:"} +``` + +**Bulk rewrite:** +```json +{"op": "rewrite.apply", "content": "full new markdown", "by": "ai:"} +``` + +### Known Limitations (Web API) + +- `suggestion.add` with `kind: "insert"` returns Bad Request on the web ops endpoint. Use `kind: "replace"` with a broader quote instead, or use `rewrite.apply` for insertions. +- Bridge-style endpoints (`/d/{slug}/bridge/*`) require client version headers (`x-proof-client-version`, `x-proof-client-build`, `x-proof-client-protocol`) and return 426 CLIENT_UPGRADE_REQUIRED without them. Use the `/api/agent/{slug}/ops` endpoint instead. + +## Local Bridge (macOS App) + +Requires Proof.app running. Bridge at `http://localhost:9847`. + +**Required headers:** +- `X-Agent-Id: claude` (identity for presence) +- `Content-Type: application/json` +- `X-Window-Id: ` (when multiple docs open) + +### Key Endpoints + +| Method | Endpoint | Purpose | +|--------|----------|---------| +| GET | `/windows` | List open documents | +| GET | `/state` | Read markdown, cursor, word count | +| GET | `/marks` | List all suggestions and comments | +| POST | `/marks/suggest-replace` | `{"quote":"old","by":"ai:","content":"new"}` | +| POST | `/marks/suggest-insert` | `{"quote":"after this","by":"ai:","content":"insert"}` | +| POST | `/marks/suggest-delete` | `{"quote":"delete this","by":"ai:"}` | +| POST | `/marks/comment` | `{"quote":"text","by":"ai:","text":"comment"}` | +| POST | `/marks/reply` | `{"markId":"","by":"ai:","text":"reply"}` | +| POST | `/marks/resolve` | `{"markId":"","by":"ai:"}` | +| POST | `/marks/accept` | `{"markId":""}` | +| POST | `/marks/reject` | `{"markId":""}` | +| POST | `/rewrite` | `{"content":"full markdown","by":"ai:"}` | +| POST | `/presence` | `{"status":"reading","summary":"..."}` | +| GET | `/events/pending` | Poll for user actions | + +### Presence Statuses + +`thinking`, `reading`, `idle`, `acting`, `waiting`, `completed` + +## Workflow: Review a Shared Document + +When given a Proof URL like `https://www.proofeditor.ai/d/abc123?token=xxx`: + +1. Extract the slug (`abc123`) and token from the URL +2. Read the document state via the API +3. Add comments or suggest edits using the ops endpoint +4. The author sees changes in real-time + +```bash +# Read +curl -s "https://www.proofeditor.ai/api/agent/abc123/state" \ + -H "x-share-token: xxx" + +# Comment +curl -X POST "https://www.proofeditor.ai/api/agent/abc123/ops" \ + -H "Content-Type: application/json" \ + -H "x-share-token: xxx" \ + -d '{"op":"comment.add","quote":"text","by":"ai:compound","text":"comment"}' + +# Suggest edit +curl -X POST "https://www.proofeditor.ai/api/agent/abc123/ops" \ + -H "Content-Type: application/json" \ + -H "x-share-token: xxx" \ + -d '{"op":"suggestion.add","kind":"replace","quote":"old","by":"ai:compound","content":"new"}' +``` + +## Workflow: Create and Share a New Document + +```bash +# 1. Create +RESPONSE=$(curl -s -X POST https://www.proofeditor.ai/share/markdown \ + -H "Content-Type: application/json" \ + -d '{"title":"My Doc","markdown":"# Title\n\nContent here."}') + +# 2. Extract URL and token +URL=$(echo "$RESPONSE" | jq -r '.tokenUrl') +SLUG=$(echo "$RESPONSE" | jq -r '.slug') +TOKEN=$(echo "$RESPONSE" | jq -r '.accessToken') + +# 3. Share the URL +echo "$URL" + +# 4. Make edits using the ops endpoint +curl -X POST "https://www.proofeditor.ai/api/agent/$SLUG/ops" \ + -H "Content-Type: application/json" \ + -H "x-share-token: $TOKEN" \ + -d '{"op":"comment.add","quote":"Content here","by":"ai:compound","text":"Added a note"}' +``` + +## Safety + +- Use `/state` content as source of truth before editing +- Prefer suggest-replace over full rewrite for small changes +- Don't span table cells in a single replace +- Always include `by` field for attribution tracking From 6b46fb2ccf4786e91ed1f8b2d215ba1233484760 Mon Sep 17 00:00:00 2001 From: Kieran Klaassen Date: Sun, 1 Mar 2026 15:01:11 -0800 Subject: [PATCH 2/2] refactor: Make Proof sharing optional in brainstorm and plan workflows MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Remove automatic Proof upload from /workflows:brainstorm and /workflows:plan - Add "Share to Proof" as an explicit menu option in each workflow's handoff step - Default behavior is unchanged: documents are saved to MD files only - Users can opt in to Proof sharing when they want collaborative review 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- plugins/compound-engineering/CHANGELOG.md | 4 +- .../commands/workflows/brainstorm.md | 45 ++++++++----------- .../commands/workflows/plan.md | 42 ++++++----------- 3 files changed, 34 insertions(+), 57 deletions(-) diff --git a/plugins/compound-engineering/CHANGELOG.md b/plugins/compound-engineering/CHANGELOG.md index a6f04cd..dcdef22 100644 --- a/plugins/compound-engineering/CHANGELOG.md +++ b/plugins/compound-engineering/CHANGELOG.md @@ -10,8 +10,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added - **`proof` skill** — Create, edit, comment on, and share markdown documents via Proof's web API and local bridge. Supports document creation, track-changes suggestions, comments, and bulk rewrites. No authentication required for creating shared documents. -- **Proof upload in `/workflows:brainstorm`** — After writing the brainstorm document, automatically uploads it to Proof and displays a shareable URL for collaborative review. -- **Proof upload in `/workflows:plan`** — After writing the plan file, automatically uploads it to Proof and displays a shareable URL for collaborative review. +- **Optional Proof sharing in `/workflows:brainstorm`** — "Share to Proof" is now a menu option in Phase 4 handoff, letting you upload the brainstorm document when you want to, rather than automatically on every run. +- **Optional Proof sharing in `/workflows:plan`** — "Share to Proof" is now a menu option in Post-Generation Options, letting you upload the plan file on demand rather than automatically. --- diff --git a/plugins/compound-engineering/commands/workflows/brainstorm.md b/plugins/compound-engineering/commands/workflows/brainstorm.md index 06e6b77..08c44ca 100644 --- a/plugins/compound-engineering/commands/workflows/brainstorm.md +++ b/plugins/compound-engineering/commands/workflows/brainstorm.md @@ -89,8 +89,24 @@ Use **AskUserQuestion tool** to present next steps: **Options:** 1. **Review and refine** - Improve the document through structured self-review 2. **Proceed to planning** - Run `/workflows:plan` (will auto-detect this brainstorm) -3. **Ask more questions** - I have more questions to clarify before moving on -4. **Done for now** - Return later +3. **Share to Proof** - Upload to Proof for collaborative review and sharing +4. **Ask more questions** - I have more questions to clarify before moving on +5. **Done for now** - Return later + +**If user selects "Share to Proof":** + +```bash +CONTENT=$(cat docs/brainstorms/YYYY-MM-DD--brainstorm.md) +TITLE="Brainstorm: " +RESPONSE=$(curl -s -X POST https://www.proofeditor.ai/share/markdown \ + -H "Content-Type: application/json" \ + -d "$(jq -n --arg title "$TITLE" --arg markdown "$CONTENT" --arg by "ai:compound" '{title: $title, markdown: $markdown, by: $by}')") +PROOF_URL=$(echo "$RESPONSE" | jq -r '.tokenUrl') +``` + +Display the URL prominently: `View & collaborate in Proof: ` + +If the curl fails, skip silently. Then return to the Phase 4 options. **If user selects "Ask more questions":** YOU (Claude) return to Phase 1.2 (Collaborative Dialogue) and continue asking the USER questions one at a time to further refine the design. The user wants YOU to probe deeper - ask about edge cases, constraints, preferences, or areas not yet explored. Continue until the user is satisfied, then return to Phase 4. @@ -119,31 +135,6 @@ Key decisions: Next: Run `/workflows:plan` when ready to implement. ``` -### Share to Proof - -After writing the brainstorm document, upload it to Proof for collaborative review: - -```bash -# Read the brainstorm file content -CONTENT=$(cat docs/brainstorms/YYYY-MM-DD--brainstorm.md) -TITLE="Brainstorm: " - -# Upload to Proof -RESPONSE=$(curl -s -X POST https://www.proofeditor.ai/share/markdown \ - -H "Content-Type: application/json" \ - -d "$(jq -n --arg title "$TITLE" --arg markdown "$CONTENT" --arg by "ai:compound" '{title: $title, markdown: $markdown, by: $by}')") - -PROOF_URL=$(echo "$RESPONSE" | jq -r '.tokenUrl') -``` - -Display the Proof URL prominently: - -``` -View & collaborate in Proof: -``` - -If the curl fails (network error, non-JSON response), skip silently and continue — Proof sharing is optional. - ## Important Guidelines - **Stay focused on WHAT, not HOW** - Implementation details belong in the plan diff --git a/plugins/compound-engineering/commands/workflows/plan.md b/plugins/compound-engineering/commands/workflows/plan.md index 3a4a346..fd18ff5 100644 --- a/plugins/compound-engineering/commands/workflows/plan.md +++ b/plugins/compound-engineering/commands/workflows/plan.md @@ -544,31 +544,6 @@ Use the Write tool to save the complete plan to `docs/plans/YYYY-MM-DD----plan.md) -TITLE="Plan: " - -# Upload to Proof -RESPONSE=$(curl -s -X POST https://www.proofeditor.ai/share/markdown \ - -H "Content-Type: application/json" \ - -d "$(jq -n --arg title "$TITLE" --arg markdown "$CONTENT" --arg by "ai:compound" '{title: $title, markdown: $markdown, by: $by}')") - -PROOF_URL=$(echo "$RESPONSE" | jq -r '.tokenUrl') -``` - -Display the Proof URL prominently: - -``` -View & collaborate in Proof: -``` - -If the curl fails (network error, non-JSON response), skip silently and continue — Proof sharing is optional. - **Pipeline mode:** If invoked from an automated workflow (LFG, SLFG, or any `disable-model-invocation` context), skip all AskUserQuestion calls. Make decisions automatically and proceed to writing the plan without interactive prompts. ## Output Format @@ -599,15 +574,26 @@ After writing the plan file, use the **AskUserQuestion tool** to present these o 2. **Run `/deepen-plan`** - Enhance each section with parallel research agents (best practices, performance, UI) 3. **Run `/technical_review`** - Technical feedback from code-focused reviewers (DHH, Kieran, Simplicity) 4. **Review and refine** - Improve the document through structured self-review -5. **Start `/workflows:work`** - Begin implementing this plan locally -6. **Start `/workflows:work` on remote** - Begin implementing in Claude Code on the web (use `&` to run in background) -7. **Create Issue** - Create issue in project tracker (GitHub/Linear) +5. **Share to Proof** - Upload to Proof for collaborative review and sharing +6. **Start `/workflows:work`** - Begin implementing this plan locally +7. **Start `/workflows:work` on remote** - Begin implementing in Claude Code on the web (use `&` to run in background) +8. **Create Issue** - Create issue in project tracker (GitHub/Linear) Based on selection: - **Open plan in editor** → Run `open docs/plans/.md` to open the file in the user's default editor - **`/deepen-plan`** → Call the /deepen-plan command with the plan file path to enhance with research - **`/technical_review`** → Call the /technical_review command with the plan file path - **Review and refine** → Load `document-review` skill. +- **Share to Proof** → Upload the plan to Proof: + ```bash + CONTENT=$(cat docs/plans/.md) + TITLE="Plan: " + RESPONSE=$(curl -s -X POST https://www.proofeditor.ai/share/markdown \ + -H "Content-Type: application/json" \ + -d "$(jq -n --arg title "$TITLE" --arg markdown "$CONTENT" --arg by "ai:compound" '{title: $title, markdown: $markdown, by: $by}')") + PROOF_URL=$(echo "$RESPONSE" | jq -r '.tokenUrl') + ``` + Display: `View & collaborate in Proof: ` — skip silently if curl fails. Then return to options. - **`/workflows:work`** → Call the /workflows:work command with the plan file path - **`/workflows:work` on remote** → Run `/workflows:work docs/plans/.md &` to start work in background for Claude Code web - **Create Issue** → See "Issue Creation" section below