Merge remote-tracking branch 'origin/main'

Author: MelbourneDeveloper

.claude/skills/build-extension/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: build-extension
+description: Build, test, and package VSCode extensions in the dart_node repo
+argument-hint: "[too-many-cooks|dart-node-vsix] [build|test|package|install]"
+disable-model-invocation: true
+allowed-tools: Bash
+---
+
+# Build VSCode Extensions
+
+This repo has two VSCode extension components:
+
+| Component | Location | What it is |
+|-----------|----------|------------|
+| **dart_node_vsix** | `packages/dart_node_vsix/` | The SDK package — Dart bindings for the VSCode extension API (commands, tree views, webviews, status bar, etc.) |
+| **too_many_cooks** | `examples/too_many_cooks_vscode_extension/` | A concrete extension built with that SDK — multi-agent coordination UI |
+
+## too-many-cooks extension
+
+**Full build** (MCP server + extension + .vsix package):
+```bash
+bash examples/too_many_cooks_vscode_extension/build.sh
+```
+
+This does:
+1. Compiles MCP server: `dart compile js` → `add_preamble.dart` → `server_node.js`
+2. Compiles extension: `dart compile js` → `wrap-extension.js` bridge → `out/lib/extension.js`
+3. Packages: `vsce package` → `.vsix` file
+
+**Test** (runs Mocha tests under a real VSCode instance):
+```bash
+cd examples/too_many_cooks_vscode_extension && npm run pretest && npm test
+```
+On headless Linux, prefix with `xvfb-run -a`.
+
+**Install into VSCode**:
+```bash
+code --install-extension examples/too_many_cooks_vscode_extension/*.vsix
+```
+
+## dart_node_vsix SDK package
+
+**Test the SDK** (Dart tests compiled to JS, run in VSCode):
+```bash
+cd packages/dart_node_vsix && npm install && npm run compile && npm test
+```
+
+**What it provides** — Dart bindings for:
+- `commands`, `window`, `workspace`, `statusBar`
+- `TreeView`, `Webview`, `OutputChannel`
+- `ExtensionContext`, `Disposable`
+- `Mocha` test API bindings
+- JS interop helpers (`Promise`, `EventEmitter`)
+
+## Architecture
+
+Both use the same pattern: Dart → `dart compile js` → wrapper script → VSCode-compatible JS module.
+
+The wrapper scripts (`scripts/wrap-extension.js`, `scripts/wrap-tests.js`) bridge dart2js output to VSCode's CommonJS `require`/`module.exports` system and inject polyfills (navigator, self) needed by dart2js async scheduling.

.claude/skills/create-pr/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: create-pr
+description: Create a pull request using the dart_node PR template
+disable-model-invocation: true
+allowed-tools: Bash, Read, Grep, Glob
+---
+
+# Create Pull Request
+
+Create a PR following the dart_node template and conventions.
+
+## Steps
+
+1. **Check state**:
+   ```bash
+   git status
+   git diff main...HEAD
+   git log main..HEAD --oneline
+   ```
+
+2. **ignore all commits** do not pay attention to the commit messages
+
+3. **Draft PR using the template** from `.github/PULL_REQUEST_TEMPLATE.md`
+
+4. **Create the PR**:
+   ```bash
+   gh pr create --title "Short title under 70 chars" --body "$(cat <<'EOF'
+   ## TLDR;
+   ...
+
+   ## What Does This Do?
+   ...
+
+   ## Brief Details?
+   ...
+
+   ## How Do The Tests Prove The Change Works?
+   ...
+   EOF
+   )"
+   ```
+
+## Rules
+
+- Keep the title under 70 chars
+- Keep documentation tight (per CLAUDE.md)
+- Only diff against `main` — ignore commit messages
+- Return the PR URL when done

.claude/skills/pub-get/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: pub-get
+description: Install all Dart and npm dependencies in dependency order
+disable-model-invocation: true
+allowed-tools: Bash
+---
+
+# Install Dependencies
+
+Run the dependency installer that handles the tiered monorepo structure.
+
+```bash
+./tools/pub_get.sh
+```
+
+## What it does
+
+Installs `dart pub get` and `npm install` across all packages and examples in dependency order:
+
+1. **Tier 1 (Core):** `dart_logging`, `dart_node_coverage`, `dart_node_core`, `reflux`
+2. **Tier 2 (Packages):** `dart_jsx`, `dart_node_express`, `dart_node_ws`, `dart_node_better_sqlite3`, `dart_node_mcp`, `dart_node_react`, `dart_node_react_native`
+3. **Tier 3 (Examples):** `frontend`, `markdown_editor`, `reflux_demo/web_counter`, `too_many_cooks`, `backend`, `mobile`, `jsx_demo`
+
+Order matters because Tier 2 depends on Tier 1, and Tier 3 depends on both.
+
+## After running
+
+Report any failures. If a package fails, it's usually because:
+- A dependency in an earlier tier hasn't been published yet (use `dart run tools/switch_deps.dart local` for local dev)
+- npm packages need `npm install` in a subdirectory (e.g., `examples/mobile/rn/`)

.claude/skills/setup-claude/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: setup-claude
+description: Install Claude Code CLI and the Too Many Cooks VSCode extension for multi-agent development
+disable-model-invocation: true
+allowed-tools: Bash
+---
+
+# Install Claude Code & Extension
+
+Sets up Claude Code CLI and the Too Many Cooks VSCode extension for multi-agent coordination.
+
+## Step 1: Install Claude Code CLI
+
+```bash
+npm install -g @anthropic-ai/claude-code
+```
+
+Verify:
+```bash
+claude --version
+```
+
+## Step 2: Build the Too Many Cooks VSCode Extension
+
+The extension provides visual agent coordination (locks, messages, plans) via the MCP server.
+
+### 2a. Build the MCP Server first
+
+```bash
+cd examples/too_many_cooks && dart pub get && npm install
+dart compile js -o examples/too_many_cooks/build/bin/server.js examples/too_many_cooks/bin/server.dart
+dart run tools/build/add_preamble.dart \
+  examples/too_many_cooks/build/bin/server.js \
+  examples/too_many_cooks/build/bin/server_node.js \
+  --shebang
+```
+
+### 2b. Build and package the extension
+
+```bash
+cd examples/too_many_cooks_vscode_extension
+npm install
+npm run compile
+npx @vscode/vsce package
+```
+
+This creates a `.vsix` file in `examples/too_many_cooks_vscode_extension/`.
+
+### 2c. Install the extension
+
+```bash
+code --install-extension examples/too_many_cooks_vscode_extension/*.vsix
+```
+
+Or use the full build script that does steps 2a-2b:
+```bash
+bash examples/too_many_cooks_vscode_extension/build.sh
+```
+
+## Step 3: Configure Claude Code for this project
+
+The project's `.claude/settings.local.json` already has the required permissions:
+- `Bash(dart pub get:*)` — dependency installation
+- `mcp__too-many-cooks__register` — MCP agent registration
+- `Bash(docker ps:*)` — Docker status checks
+
+Custom skills are in `.claude/skills/` — run `/help` to see them.
+
+## Multi-Agent Usage
+
+After setup, agents coordinate via the Too Many Cooks MCP server:
+- **Lock files** before editing, unlock after
+- **Check messages** regularly between agents
+- **Update plans** so other agents can see your intent
+- Keep your agent key — it's critical for authentication

.claude/skills/setup-playwright/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: setup-playwright
+description: Install Chromium and Playwright for website E2E testing
+disable-model-invocation: true
+allowed-tools: Bash
+---
+
+# Install Chromium & Playwright
+
+Sets up Playwright with Chromium for running the website's E2E test suite.
+
+## Steps
+
+1. **Install website npm dependencies** (includes `@playwright/test`):
+   ```bash
+   cd website && npm ci
+   ```
+
+2. **Install Chromium browser and OS dependencies**:
+   ```bash
+   cd website && npx playwright install --with-deps chromium
+   ```
+   This installs the Chromium binary plus required system libraries (libgbm, libasound, etc.).
+
+3. **Verify installation**:
+   ```bash
+   cd website && npx playwright --version
+   ```
+
+## Notes
+
+- Only Chromium is needed — this project does not test against Firefox or WebKit.
+- On the Dev Container (Ubuntu 24.04), `--with-deps` installs the OS packages automatically.
+- On macOS, Playwright downloads its own Chromium binary — no Homebrew needed.
+- Browser cache lives at `~/.cache/ms-playwright/`. Delete this to force a clean reinstall.
+- The website tests are at `website/tests/` and configured in `website/playwright.config.js`.
+- Base URL: `http://localhost:8080` (Eleventy dev server).
+
+## After installing
+
+Run the website tests:
+```bash
+cd website && npm test
+```
+
+Or with UI mode:
+```bash
+cd website && npm run test:ui
+```

.claude/skills/taskflow/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: taskflow
+description: Build and run the full TaskFlow demo stack (Express backend + React frontend + mobile)
+disable-model-invocation: true
+allowed-tools: Bash
+---
+
+# TaskFlow Demo
+
+Build and run the full-stack demo that showcases dart_node's capabilities.
+
+## Run it
+
+```bash
+sh examples/run_taskflow.sh
+```
+
+This:
+1. Kills any existing processes on ports 3000 and 8080
+2. Builds backend, mobile, and frontend from Dart to JS
+3. Starts the Express backend on **http://localhost:3000**
+4. Starts the frontend dev server on **http://localhost:8080/web/**
+5. Traps Ctrl+C for clean shutdown
+
+## Ports
+
+| Service | Port | How |
+|---------|------|-----|
+| Backend API (Express) | 3000 | `node examples/backend/build/server.js` |
+| Frontend (static) | 8080 | `python3 -m http.server 8080` |
+| Mobile (Expo) | — | `cd examples/mobile/rn && npm run ios` or `npm run android` |
+
+## Prerequisites
+
+Dependencies must be installed first. If the build fails, run:
+```bash
+./tools/pub_get.sh
+```
+
+Or use the Dev Container which runs `post-create.sh` automatically.
+
+## Manual start (individual services)
+
+Backend only:
+```bash
+dart run tools/build/build.dart backend && node examples/backend/build/server.js
+```
+
+Frontend only:
+```bash
+cd examples/frontend && bash build.sh && python3 -m http.server 8080
+```