feat: Add proof skill and optional Proof sharing in plan/brainstorm workflows (v2.37.0)

Merges feat/proof-integration with conflict resolution: - proof skill for creating/editing/sharing markdown docs via Proof API - "Share to Proof" added as opt-in menu option in /workflows:brainstorm Phase 4 - "Share to Proof" added as opt-in menu option in /workflows:plan Post-Generation Options - Bumped version 2.36.0 → 2.37.0 to avoid conflict with OpenClaw/Qwen/Windsurf release 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2026-03-01 15:02:08 -08:00
parent 2370da9c3c 6b46fb2ccf
commit 30d33270b9
7 changed files with 233 additions and 10 deletions
--- 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.37.0",
      "author": {
        "name": "Kieran Klaassen",
        "url": "https://github.com/kieranklaassen",
--- 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.37.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",
--- 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.37.0] - 2026-03-01
+
+### 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.
+- **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.
+
+---
+
 ## [2.36.0] - 2026-03-01

 ### Added
--- 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 |

--- 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-<topic>-brainstorm.md)
+TITLE="Brainstorm: <topic title>"
+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: <PROOF_URL>`
+
+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.

--- a/plugins/compound-engineering/commands/workflows/plan.md
+++ b/plugins/compound-engineering/commands/workflows/plan.md
@@ -574,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/<plan_filename>.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/<plan_filename>.md)
+  TITLE="Plan: <plan title from frontmatter>"
+  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: <PROOF_URL>` — 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/<plan_filename>.md &` to start work in background for Claude Code web
 - **Create Issue** → See "Issue Creation" section below
--- a/plugins/compound-engineering/skills/proof/SKILL.md
+++ 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: <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: <token>` or `Authorization: Bearer <token>`
+- 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:<agent-name>", "text": "Your comment here"}
+```
+
+**Reply to a comment:**
+```json
+{"op": "comment.reply", "markId": "<id>", "by": "ai:<agent-name>", "text": "Reply text"}
+```
+
+**Resolve a comment:**
+```json
+{"op": "comment.resolve", "markId": "<id>", "by": "ai:<agent-name>"}
+```
+
+**Suggest a replacement:**
+```json
+{"op": "suggestion.add", "kind": "replace", "quote": "original text", "by": "ai:<agent-name>", "content": "replacement text"}
+```
+
+**Suggest a deletion:**
+```json
+{"op": "suggestion.add", "kind": "delete", "quote": "text to delete", "by": "ai:<agent-name>"}
+```
+
+**Bulk rewrite:**
+```json
+{"op": "rewrite.apply", "content": "full new markdown", "by": "ai:<agent-name>"}
+```
+
+### 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: <uuid>` (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:<agent-name>","content":"new"}` |
+| POST | `/marks/suggest-insert` | `{"quote":"after this","by":"ai:<agent-name>","content":"insert"}` |
+| POST | `/marks/suggest-delete` | `{"quote":"delete this","by":"ai:<agent-name>"}` |
+| POST | `/marks/comment` | `{"quote":"text","by":"ai:<agent-name>","text":"comment"}` |
+| POST | `/marks/reply` | `{"markId":"<id>","by":"ai:<agent-name>","text":"reply"}` |
+| POST | `/marks/resolve` | `{"markId":"<id>","by":"ai:<agent-name>"}` |
+| POST | `/marks/accept` | `{"markId":"<id>"}` |
+| POST | `/marks/reject` | `{"markId":"<id>"}` |
+| POST | `/rewrite` | `{"content":"full markdown","by":"ai:<agent-name>"}` |
+| 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