Skip to content

feat: add collaborative review sessions #316

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
eprj453 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

feat: add collaborative review sessions #316

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 38 additions & 0 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -150,6 +150,34 @@ User annotates markdown, provides feedback
Send Annotations → feedback sent to agent session
```

## Collaborative Review Flow

```
User clicks "Start Collaborative Review" in plan editor
↓
POST /api/review-session → creates session with unique ID
↓
Share URL displayed: /s/<session-id>
↓
User shares URL with team members (Reviewer A, B, C...)
↓
Each reviewer:
1. Opens /s/<session-id> → auto-joins session
2. Adds their annotations
3. Clicks "Submit" → PATCH /api/review-session/:id/annotations
(Optimistic locking: fails if version mismatch)
↓
Original user clicks "Refresh" → fetches all merged annotations
↓
User approves/denies plan with all team feedback → sent to agent
```

**Key features:**
- One fixed URL for all reviewers (no N-way URL ping-pong)
- Server merges annotations automatically (deduplicates)
- Version conflicts auto-resolve with refresh
- Works offline (local filesystem) or cloud (Cloudflare KV)

## Server API

### Plan Server (`packages/server/index.ts`)
Expand Down Expand Up @@ -205,9 +233,19 @@ All servers use random ports locally or fixed port (`19432`) in remote mode.
| --------------------- | ------ | ------------------------------------------ |
| `/api/paste` | POST | Store compressed plan data, returns `{ id }` |
| `/api/paste/:id` | GET | Retrieve stored compressed data |
| `/api/review-session` | POST | Create collaborative review session, returns `{ session, shareUrl }` |
| `/api/review-session/:id` | GET | Retrieve review session with all annotations |
| `/api/review-session/:id/annotations` | PATCH | Add annotations to session (optimistic locking) |

Runs as a separate service on port `19433` (self-hosted) or as a Cloudflare Worker (hosted).

**Collaborative Review Sessions:**
- Fixed session URL (`/s/<id>`) for multiple reviewers
- Server-side annotation merging with deduplication
- Optimistic locking (version field) prevents conflicts
- Auto-expires after 7 days (same as paste TTL)
- Supports both filesystem and Cloudflare KV storage

## Plan Version History

Every plan is automatically saved to `~/.plannotator/history/{project}/{slug}/` on arrival, before the user sees the UI. Versions are numbered sequentially (`001.md`, `002.md`, etc.). The slug is derived from the plan's first `# Heading` + today's date via `generateSlug()`, scoped by project name (git repo or cwd). Same heading on the same day = same slug = same plan being iterated on. Identical resubmissions are deduplicated (no new file if content matches the latest version).
Expand Down
Loading