@schoolai/shipyard-mcp 0.1.0-next.433

package/LICENSE.md

@@ -0,0 +1,105 @@
+# Functional Source License, Version 1.1, ALv2 Future License
+
+## Abbreviation
+
+FSL-1.1-ALv2
+
+## Notice
+
+Copyright ${year} ${licensor name}
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following
+will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

package/README.md

@@ -0,0 +1,221 @@
+<div align="center">
+  <img src="apps/web/public/icon.svg" alt="Shipyard Logo" width="120" height="120">
+  <h1>Shipyard</h1>
+  <p><strong>Verify AI agent work with collaborative review and proof-of-work artifacts</strong></p>
+
+  <p>
+    <a href="https://github.com/SchoolAI/shipyard/actions"><img src="https://img.shields.io/github/actions/workflow/status/SchoolAI/shipyard/deploy.yml?branch=main&label=deploy" alt="Deploy Status"></a>
+    <img src="https://img.shields.io/badge/TypeScript-5.6-3178C6?logo=typescript&logoColor=white" alt="TypeScript">
+    <img src="https://img.shields.io/badge/pnpm-10.x-F69220?logo=pnpm&logoColor=white" alt="pnpm">
+    <a href="./LICENSE.md"><img src="https://img.shields.io/badge/license-FSL--1.1-blue" alt="License"></a>
+  </p>
+</div>
+
+---
+
+## The Problem
+
+AI agents can generate implementation tasks, but there's no good way to:
+- **Verify** the agent actually did what it claimed
+- **Review** tasks collaboratively with humans in real-time
+- **Provide feedback** that agents can act on
+
+Shipyard solves this with P2P collaborative review and proof-of-work artifacts.
+
+## Features
+
+- **Real-time collaboration** — Multiple reviewers sync via WebRTC, no server required
+- **Proof-of-work artifacts** — Screenshots, videos, test results stored in GitHub
+- **MCP integration** — Works with Claude Code, Cursor, and any MCP-compatible agent
+- **Zero infrastructure** — GitHub Pages + local MCP server, no paid services
+- **BlockNote editor** — Notion-like editing with inline comments and threads
+- **Offline-first** — IndexedDB persistence, works without network
+
+## Platform Support
+
+| Platform | Status | Installation | Notes |
+|----------|--------|--------------|-------|
+| **Claude Code** | ✅ Full support | GitHub plugin | Complete integration with hooks + skills |
+| **OpenCode** | ⚠️ Experimental | npm + config | Native plan mode, testing in progress |
+| **Cursor** | ⚠️ MCP only | npm + config | Works via MCP tools, manual workflow |
+| **Windsurf** | ⚠️ MCP only | npm + config | Works via MCP tools, testing needed |
+| **Devin** | ⚠️ MCP only | npm + config | API-only mode has limitations |
+| **Replit Agent** | ⚠️ MCP only | npm + config | Basic functionality |
+| **GitHub Copilot** | ⚠️ MCP only | npm + config | Basic functionality |
+| **Gemini Code Assist** | ⚠️ MCP only | npm + config | Basic functionality |
+| **Codex (OpenAI)** | ❓ Research needed | TBD | Feature completeness assessment in progress |
+
+**Key:** Only Claude Code provides the full experience with automatic plan creation and approval workflows. Other platforms work via manual MCP tool invocation.
+
+See [Platform Compatibility Matrix](./docs/INSTALLATION.md#platform-compatibility-matrix) for detailed feature comparison.
+
+## Installation
+
+### For Claude Code Users
+
+Install the complete Shipyard plugin (MCP server + hooks + skills):
+
+```bash
+# Step 1: Add the marketplace
+/plugin marketplace add SchoolAI/shipyard
+
+# Step 2: Install the plugin
+/plugin install shipyard@schoolai-shipyard
+```
+
+> **Note:** Claude Code requires adding a marketplace before installing plugins from it. This is intentional design (similar to app stores).
+
+**Enable auto-updates:** After installing, run `/plugin` → Marketplaces tab → select `schoolai-shipyard` → "Enable auto-update" to receive updates automatically.
+
+<details>
+<summary>Troubleshooting: If Step 1 fails with a cache error</summary>
+
+There's a known Claude Code bug (#14696) with case-sensitive GitHub org names. Try the full git URL instead:
+
+```bash
+/plugin marketplace add https://github.com/SchoolAI/shipyard.git
+```
+
+If that stalls, start a fresh Claude Code session and try again.
+</details>
+
+This gives you:
+- ✅ MCP tools for creating and managing plans
+- ✅ Automatic hooks for plan creation workflow
+- ✅ Skills for collaborative planning
+
+### For Other Platforms (Cursor, Windsurf, Replit, etc.)
+
+Install the MCP server via npm:
+
+```bash
+npx @schoolai/shipyard-mcp mcp-server-shipyard
+```
+
+Then configure in your platform's MCP settings:
+
+**Cursor** (`~/.cursor/mcp.json`):
+```json
+{
+  "mcpServers": {
+    "shipyard": {
+      "command": "npx",
+      "args": ["-y", "@schoolai/shipyard-mcp", "mcp-server-shipyard"]
+    }
+  }
+}
+```
+
+**Windsurf** (`~/.windsurf/settings.json`):
+```json
+{
+  "mcp.servers": {
+    "shipyard": {
+      "command": "npx @schoolai/shipyard-mcp mcp-server-shipyard"
+    }
+  }
+}
+```
+
+See **[docs/INSTALLATION.md](./docs/INSTALLATION.md)** for comprehensive platform-specific guides.
+
+### For Development
+
+```bash
+# Clone and install
+git clone https://github.com/SchoolAI/shipyard.git
+cd shipyard
+pnpm install
+
+# Start all services
+pnpm dev:all
+```
+
+**Important:** Do NOT install the `shipyard` plugin if you're developing this repo. The plugin is for end users only. Local hooks/skills/MCP are always used from the project directory.
+
+See **[SETUP.md](./docs/SETUP.md)** for full development setup.
+
+## How It Works
+
+```
+┌─────────────────┐     MCP      ┌─────────────────┐
+│   AI Agent      │─────────────►│  MCP Server     │
+│ (Claude, etc.)  │              │  (localhost)    │
+└─────────────────┘              └────────┬────────┘
+                                          │ WebSocket
+                                          ▼
+┌─────────────────┐   WebRTC    ┌─────────────────┐
+│ Remote Reviewer │◄───────────►│ Author Browser  │
+│    Browser      │   (P2P)     │                 │
+└─────────────────┘             └─────────────────┘
+```
+
+1. Agent creates a task via MCP tool → Browser opens automatically
+2. Reviewers join via shared URL → Real-time P2P sync
+3. Add comments, approve, or request changes → Agent sees feedback
+4. Agent uploads artifacts (screenshots, etc.) → Stored in GitHub
+
+## Packages
+
+| Package | Description |
+|---------|-------------|
+| [`@shipyard/server`](./apps/server) | MCP server with task tools |
+| [`@shipyard/web`](./apps/web) | React app with BlockNote editor |
+| [`@shipyard/schema`](./packages/schema) | Shared types, Yjs helpers, URL encoding |
+| [`@shipyard/signaling`](./apps/signaling) | WebRTC signaling server (Cloudflare Worker) |
+| [`@shipyard/hook`](./apps/hook) | Claude Code hooks for auto-task creation |
+
+## Documentation
+
+| Doc | Description |
+|-----|-------------|
+| [SETUP.md](./docs/SETUP.md) | Installation, configuration, troubleshooting |
+| [BRIEF.md](./docs/BRIEF.md) | 30-second project context |
+| [architecture.md](./docs/architecture.md) | Data model, sync topology, tech choices |
+| [milestones/](./docs/milestones/) | Implementation phases and progress |
+
+## Why "Shipyard"?
+
+The name captures two ideas:
+1. **Workspace metaphor** — A shipyard is where work is built
+2. **Dev culture** — "Shipping" is how developers talk about delivering value
+
+The Penrose triangle logo represents the "impossible triangle" of AI development: **quality**, **speed**, and **low effort**. Traditionally you sacrifice one. Shipyard enables all three through collaborative verification loops.
+
+> *See [ADR-0005](./docs/decisions/0005-rebrand-peer-plan-to-shipyard.md) for the full naming rationale.*
+
+## Claude Cowork Integration
+
+Use Shipyard with Claude Cowork via the included skill:
+
+```
+skills/shipyard/
+├── SKILL.md      # Instructions for Claude
+├── README.md     # Setup guide
+└── examples/     # Usage examples
+```
+
+See [skills/shipyard/README.md](./skills/shipyard/README.md) for setup.
+
+## Contributing
+
+We welcome contributions! Please read the codebase first:
+
+1. [BRIEF.md](./docs/BRIEF.md) — Understand the project
+2. [engineering-standards.md](./docs/engineering-standards.md) — Code quality expectations
+3. [architecture.md](./docs/architecture.md) — How it all fits together
+
+## License
+
+[FSL-1.1-ALv2](./LICENSE.md) (Functional Source License)
+
+- **Free** for all non-competing use
+- **Converts to Apache 2.0** automatically in 2 years
+
+We chose this to ensure that all core improvements help grow this main repository while keeping it free for developers.
+
+---
+
+<div align="center">
+  <sub>Built with Yjs, BlockNote, and the MCP protocol</sub>
+</div>

package/apps/hook/README.md

@@ -0,0 +1,273 @@
+// TODO: Convert to a runbook
+
+# @shipyard/hook
+
+Claude Code integration hook for shipyard. Automatically creates and syncs plans when agents enter plan mode.
+
+## How It Works
+
+This hook intercepts Claude Code events and bridges them to the shipyard system:
+
+1. **EnterPlanMode** → Creates plan, opens browser, sets "Claude is here" presence
+2. **Write/Edit** (in plan mode) → Syncs content in real-time
+3. **ExitPlanMode** → Blocks until human reviews and approves
+
+## Installation
+
+### Prerequisites
+
+- Node.js 22+ (LTS)
+- shipyard MCP server running (`@shipyard/server`)
+
+### Option 1: npm Global Install (Recommended for Users)
+
+```bash
+npm install -g @shipyard/hook
+```
+
+The postinstall script automatically configures Claude Code hooks in `~/.claude/settings.json`. Just restart Claude Code after installation.
+
+If the automatic setup didn't work, you can manually run:
+```bash
+shipyard-hook-install
+```
+
+### Option 2: Plugin Directory (Testing/Development)
+
+```bash
+# Build the hook first
+cd /path/to/shipyard
+pnpm build
+
+# Run Claude Code with explicit plugin directory
+claude --plugin-dir ./apps/hook
+```
+
+This loads the plugin without global installation - useful for testing.
+
+### Option 3: Local Development
+
+For active development on shipyard itself:
+
+```bash
+cd /path/to/shipyard
+
+# One-time: Create global symlink
+pnpm --filter @shipyard/hook dev:link
+
+# Run in watch mode (rebuilds on changes)
+pnpm --filter @shipyard/hook dev
+
+# The hooks.json expects "shipyard-hook" in PATH
+# pnpm link --global creates this symlink automatically
+```
+
+### Option 4: Manual Configuration
+
+If you prefer manual setup, add to `~/.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PermissionRequest": [
+      {
+        "matcher": "ExitPlanMode",
+        "hooks": [{ "type": "command", "command": "shipyard-hook", "timeout": 1800 }]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "ExitPlanMode",
+        "hooks": [{ "type": "command", "command": "shipyard-hook" }]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [{ "type": "command", "command": "shipyard-hook --context" }]
+      }
+    ]
+  }
+}
+```
+
+## Configuration (Automatic)
+
+The install script adds this to `~/.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "shipyard-hook"
+          }
+        ]
+      }
+    ],
+    "PermissionRequest": [
+      {
+        "matcher": "ExitPlanMode",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "shipyard-hook",
+            "timeout": 1800
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Note:** The `matcher: "*"` matches ALL tools, but the hook only acts on plan mode events (checked internally). This ensures Write/Edit trigger the hook while avoiding unnecessary overhead in non-plan modes.
+
+## Local Testing
+
+### 1. Start the shipyard stack
+
+```bash
+cd /path/to/shipyard
+
+# Terminal 1: Start MCP server (includes registry + WebSocket)
+pnpm dev:server
+
+# Terminal 2: Start web UI
+pnpm dev:web
+```
+
+### 2. Build the hook
+
+```bash
+pnpm --filter @shipyard/hook build
+```
+
+### 3. Run the test harness
+
+```bash
+cd apps/hook/test
+./test-harness.sh
+```
+
+This simulates the full hook lifecycle:
+- Creates a plan (simulates EnterPlanMode)
+- Updates content (simulates Write)
+- Edits content (simulates Edit)
+- Tries to exit (simulates ExitPlanMode - should block)
+- Tests passthrough (non-plan mode)
+
+### 4. Manual Testing with Real Claude Code
+
+1. Configure the hook in your Claude Code settings (see Configuration above)
+2. Restart Claude Code: `/quit` then relaunch
+3. Enter plan mode: Press Shift+Tab or use `/mode plan`
+4. Type something to trigger EnterPlanMode
+5. Check that a browser tab opens with your plan
+6. Write to the plan file - content should sync in real-time
+7. Try to exit plan mode - should block until you approve in browser
+
+### 5. Debug Logging
+
+Enable debug logs to see hook execution:
+
+```bash
+export LOG_LEVEL=debug
+```
+
+The hook logs to stderr, so you can see them in Claude Code's debug output.
+
+## State Management
+
+The hook maintains session state at:
+```
+~/.shipyard/hook-state.json
+```
+
+This file maps session IDs to plan IDs. It's automatically cleaned up after 24 hours.
+
+## Architecture
+
+```
+Claude Code → Hook CLI → HTTP API → Registry Server → Y.Doc
+                ↓
+            State File
+        (~/.shipyard/hook-state.json)
+```
+
+### Adapter Pattern
+
+The hook uses an adapter pattern to support multiple agent systems:
+
+- **Abstract Layer** (`src/adapters/types.ts`) - `AgentAdapter` interface
+- **Claude Code Adapter** (`src/adapters/claude-code.ts`) - Implements Claude Code hook protocol
+- **Future**: Open Agents adapter, custom agents, etc.
+
+## Development
+
+### Build
+
+```bash
+pnpm build
+```
+
+### Watch Mode
+
+```bash
+pnpm dev
+```
+
+### Type Check
+
+```bash
+pnpm typecheck
+```
+
+### Lint
+
+```bash
+pnpm lint
+pnpm lint:fix
+```
+
+## Troubleshooting
+
+### Hook not executing
+
+1. Check Claude Code settings are correct
+2. Restart Claude Code after changing settings
+3. Check hook binary exists: `which shipyard-hook`
+4. Check hook binary is executable: `ls -l $(which shipyard-hook)`
+
+### Plan not appearing
+
+1. Ensure registry server is running: `curl http://localhost:32191/registry`
+2. Check browser console for errors
+3. Check server logs: `LOG_LEVEL=debug pnpm dev:server`
+
+### Changes not syncing
+
+1. Check WebSocket connection in browser dev tools
+2. Verify plan ID matches between hook state and browser URL
+3. Check `~/.shipyard/hook-state.json` for session mapping
+
+### Review not blocking exit
+
+1. Check plan status in browser (should be "pending_review" or "changes_requested")
+2. Manually trigger status update in UI
+3. Check server logs for review status endpoint responses
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `REGISTRY_PORT` | `32191,32192` | Registry server port |
+| `LOG_LEVEL` | `info` | Log level (debug, info, warn, error) |
+| `SHIPYARD_STATE_DIR` | `~/.shipyard` | State directory |
+
+## License
+
+MIT