dsh-compound-engineering 0.0.0-stage → 0.1.0

package/skills/ce-test-browser/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: ce-test-browser
+description: Run browser tests for pages affected by the current branch or PR. Use when asked to run or check browser tests for the current change.
+argument-hint: "[PR number, branch name, 'current', or --port PORT]"
+---
+
+# Browser Test Skill
+
+Run end-to-end browser tests on pages affected by a PR or branch using the best approved browser driver available in the active harness.
+
+**Done:** the run ends by reporting what it found — either the summary, with every affected route marked Pass, Fail, or Skip and each Skip carrying its reason, or, when a preflight blocker stops testing before any route can be exercised, the blocker and what would clear it. Reaching neither, or dropping a route from the summary because nobody could reach it, is the failure this done condition exists to prevent.
+
+## Modes
+
+- **Manual (default):** the user controls the dev server. When the fallback driver is `agent-browser`, ask whether to run headed or headless.
+- **Pipeline (`mode:pipeline`):** invoked by LFG or another automated runner. The run is unattended — never block on a question. Read `references/pipeline-orchestration.md` from this skill's directory and follow it; it overrides port selection (step 4, Determine the dev server port), dev-server startup (step 5, Verify the dev server is running), and visibility prompts (step 6, Set visibility), running the same port script with `--free` inside the block that starts the server.
+
+## Browser Driver Policy
+
+Select the driver before the first browser action:
+
+1. **Prefer a host-native integrated browser.** Use a browser-control surface embedded in or directly owned by the active harness when it can navigate local URLs, inspect rendered and interactive state, click/fill/press, capture screenshots, and inspect console errors. A separately configured browser extension or integration is not host-native. Load and follow the selected capability's own instructions before browser work.
+2. **Otherwise fall back to `agent-browser`.** Read `references/agent-browser-driver.md` before running any command.
+3. **Do not introduce a third browser stack.** Never install or substitute standalone Playwright, Puppeteer, a separately configured browser extension or MCP, or other ad hoc browser automation. A Playwright API exposed inside the selected host-native browser remains host-native; it is not standalone Playwright.
+
+Use one driver for the entire run. A selected host-native driver may fall back to `agent-browser` only if initialization fails before the first route is tested. After testing begins, do not mix driver sessions, element references, screenshots, or authentication state.
+
+## Workflow
+
+Read `references/route-and-report.md` from this skill's directory before step 3 (Map changed files to routes). It carries the route-mapping patterns, the port and server commands, the per-page checks, the two human-facing prompts, and the summary format.
+
+1. **Select the driver** per the policy above and record it. This also requires a git repository with changes to test.
+2. **Determine test scope** from the argument: a PR number → `gh pr view [number] --json files -q '.files[].path'`; `current` or empty → `git diff --name-only main...HEAD`; a branch name → `git diff --name-only main...[branch]`.
+3. **Map changed files to routes** and build the list of URLs to test.
+4. **Determine the dev server port.** `scripts/resolve-port.sh` resolves it and prints the port alone on stdout: an explicit port argument; else a `--port` flag in a `package.json` dev/start script; else `PORT=` in `.env`, `.env.local`, or `.env.development`; else `3000`. Pass an explicit port when the user gave `--port N`, or when your active project instructions already in context state the dev-server port. Do not grep instruction files for one: prose mentions in docs, examples, and troubleshooting are unreliable and false-positive-prone, while config files and `.env` are trustworthy. Each mode runs the script in the shell call that needs the port, so no port value has to survive between shell calls or be transcribed out of prose; the reference gives the command. Manual mode uses that port as-is: the user controls their own server, so do not scan for alternatives.
+5. **Verify the dev server is running** before asking the headed/headless question — a manual run with no server stops here, so asking first would waste the question.
+6. **Set visibility, then verify the root.** Visibility is independent from unattended execution:
+   - **Host-native integrated browser:** keep its normal integrated surface visible and non-blocking so the user can watch progress when useful. Do not repeatedly steal focus as routes change. This applies in both manual and pipeline modes.
+   - **`agent-browser` fallback, pipeline mode:** run headless without asking.
+   - **`agent-browser` fallback, manual mode:** ask the user whether to run headed or headless using the host's blocking question tool already in the current tool list (match by capability, not by a host-specific name). Presence in the current tool list is proof the tool exists; never call a user-facing question tool to discover whether it exists. If a matching tool is listed but unloaded, use the host's tool-discovery primitive to load that capability — do not search for another host's tool name. Fall back to presenting options on the host's user-visible chat surface only when no such tool is in the list or a real question call errors. Never silently skip the question.
+
+   Then navigate to `http://localhost:<port>`, capture its rendered or interactive state, and confirm the root is served before iterating.
+7. **Test each affected page** — navigate, inspect fresh state, exercise the critical interactions, capture evidence.
+8. **Human verification** where a flow needs external interaction (OAuth, email, payments, SMS, third-party APIs): pause and ask. **Pipeline mode does not pause** — log each such flow as Skip with the reason and continue.
+9. **Handle failures** by capturing the error state and the exact repro, then asking whether to fix now or skip. **Pipeline mode does not ask** — log the failure and continue.
+10. **Report the summary** in the format the reference gives.
+
+## Driver Reference
+
+When `agent-browser` is selected as the fallback, read `references/agent-browser-driver.md` from this skill's directory before running its commands. Host-native drivers follow their harness-provided instructions instead.

package/skills/ce-test-browser/references/agent-browser-driver.md

@@ -0,0 +1,47 @@
+# `agent-browser` Fallback Driver
+
+Read this file only after the main skill selects `agent-browser` because no qualifying host-native integrated browser is available.
+
+## Bootstrap
+
+Verify the direct CLI is installed:
+
+```bash
+command -v agent-browser >/dev/null 2>&1 && echo "Ready" || echo "NOT INSTALLED"
+```
+
+If it is missing, tell the user: "`agent-browser` is not installed. Use the `ce-setup` skill to print the current install command, then install `agent-browser` and retry." Then stop. An installed discovery skill does not imply that the CLI or its browser runtime is installed.
+
+Before running browser actions, load the workflow and troubleshooting content that matches the installed CLI:
+
+```bash
+agent-browser skills get core
+```
+
+If the CLI exists but cannot launch its browser, follow the current core troubleshooting instructions and report the exact launch failure. Do not misreport a missing browser runtime or launch error as a missing CLI.
+
+## Commands Used by This Skill
+
+Add `--headed` to commands when manual mode selected a visible browser. Pipeline mode defaults this fallback driver to headless.
+
+```bash
+# Navigate and inspect
+agent-browser open <url>
+agent-browser snapshot -i
+
+# Interact using refs from the latest snapshot
+agent-browser click @e1
+agent-browser fill @e1 "text"
+agent-browser type @e1 "text"
+agent-browser press Enter
+
+# Capture evidence
+agent-browser screenshot out.png
+agent-browser screenshot --full out-full.png
+
+# Navigation and waits
+agent-browser back
+agent-browser wait @e1
+```
+
+Use the installed core documentation for console-error inspection and any command not shown here. Do not switch to another browser driver after the first route is tested.

package/skills/ce-test-browser/references/pipeline-orchestration.md

@@ -0,0 +1,45 @@
+# Pipeline-Mode Server Orchestration
+
+Read and follow this file only when invoked with `mode:pipeline` (LFG or another automated runner). It overrides visibility prompts, free-port selection, and dev-server startup. It does not change browser-driver selection. In pipeline mode you run unattended — never block on a question.
+
+The run's report, either the summary or the preflight blocker that stopped testing, is the last thing this skill writes. It ends this skill, not the turn. The caller runs in this same session, and its next step follows the report.
+
+## 1. No visibility question
+
+Unattended execution does not mean hidden execution. Do not ask a visibility question:
+
+- When a host-native integrated browser is selected, keep its normal integrated surface visible and non-blocking so the user can watch progress without interrupting the run. Do not repeatedly steal focus.
+- When the fallback `agent-browser` driver is selected, run it headless without passing `--headed`.
+
+## 2. Claim a free port and start the server
+
+Multiple agents may run on the same machine, so never assume the resolved port is free: `scripts/resolve-port.sh --free` in this skill's directory resolves the port and scans upward to the first port with no listener, printing it alone on stdout.
+
+Run the whole thing as **one** command. Shell variables do not survive between separate Bash calls, so the port resolution, the free scan, and the startup all happen inside this block — it seeds `PORT` by capturing the script's output, not from anything an earlier step printed. Add the explicit port as a second argument when the user gave `--port N` or your in-context project instructions state the dev-server port.
+
+```bash
+SKILL_DIR="<absolute path of the directory containing the SKILL.md you just read>";
+PORT=$(bash "$SKILL_DIR/scripts/resolve-port.sh" --free);   # append the explicit port as a further argument when you have one
+echo "Using dev server port: $PORT"
+
+# start in the background (the scan guarantees this port is free), then wait up to 30s
+echo "Starting dev server on port ${PORT}..."
+if [ -f "bin/dev" ]; then
+  PORT=${PORT} bin/dev > /tmp/dev-server-${PORT}.log 2>&1 &
+elif [ -f "bin/rails" ]; then
+  bin/rails server -p ${PORT} > /tmp/dev-server-${PORT}.log 2>&1 &
+elif [ -f "package.json" ]; then
+  PORT=${PORT} npm run dev > /tmp/dev-server-${PORT}.log 2>&1 &
+fi
+for i in $(seq 1 30); do
+  lsof -i ":${PORT}" -sTCP:LISTEN -t >/dev/null 2>&1 && break
+  sleep 1
+done
+if ! lsof -i ":${PORT}" -sTCP:LISTEN -t >/dev/null 2>&1; then
+  echo "Server did not start in 30s. Last output:"
+  tail -20 /tmp/dev-server-${PORT}.log 2>/dev/null
+  exit 1
+fi
+```
+
+The scan may land on a different port than the resolved one, and `$PORT` does not survive into later shell calls. Note the number this block echoes ("Using dev server port: N") and use that literal port in every subsequent selected-driver navigation — do not rely on `${PORT}` carrying over. Then return to the "Test Each Affected Page" step, navigate to `http://localhost:<N>`, inspect the rendered state, and test each route.

package/skills/ce-test-browser/references/route-and-report.md

@@ -0,0 +1,129 @@
+# Routes, server, and reporting
+
+Read this before mapping changed files to routes (workflow step 3). It carries the route-mapping starting points, the port and server commands, what to check on each page, the two human-facing prompts, and the summary format.
+
+## Map changed files to routes
+
+Map each changed file to the route(s) that render it, then build the list of URLs to test. The table below is a starting point of common patterns, not an exhaustive rule set — apply judgment for the project's actual layout:
+
+| File Pattern | Route(s) |
+|-------------|----------|
+| `app/views/users/*` | `/users`, `/users/:id`, `/users/new` |
+| `app/controllers/settings_controller.rb` | `/settings` |
+| `app/javascript/controllers/*_controller.js` | Pages using that Stimulus controller |
+| `app/components/*_component.rb` | Pages rendering that component |
+| `app/views/layouts/*` | All pages (test homepage at minimum) |
+| `app/assets/stylesheets/*` | Visual regression on key pages |
+| `app/helpers/*_helper.rb` | Pages using that helper |
+| `src/app/*` (Next.js) | Corresponding routes |
+| `src/components/*` | Pages using those components |
+
+## Determine the port and verify the dev server is running
+
+`scripts/resolve-port.sh` resolves the port and prints it alone on stdout, so the shell call that needs it captures the value instead of a later step re-typing a printed number. Append the explicit port as an argument when you have one.
+
+```bash
+SKILL_DIR="<absolute path of the directory containing the SKILL.md you just read>";
+PORT=$(bash "$SKILL_DIR/scripts/resolve-port.sh");
+if lsof -i ":${PORT}" -sTCP:LISTEN -t >/dev/null 2>&1; then
+  echo "Server running on port ${PORT}";
+else
+  echo "Server not running on port ${PORT}";
+  echo "Start your dev server, then re-run:";
+  echo "  Rails: bin/dev  or  rails server -p ${PORT}";
+  echo "  Node/Next.js: npm run dev";
+  echo "  Custom port: run this skill again with --port <your-port>";
+  exit 0;
+fi
+```
+
+## Test each affected page
+
+For each affected route, use the selected driver to navigate and capture fresh rendered or interactive state.
+
+**Verify key elements:**
+- Page title/heading present
+- Primary content rendered
+- No error messages visible
+- Forms have expected fields
+- No new console errors attributable to the tested flow
+
+**Test critical interactions:** derive locators or element references from the selected driver's latest inspected state, perform the click/fill/press action, then inspect the resulting state. Do not guess selectors or reuse stale references.
+
+**Take screenshots:** capture viewport and full-page evidence when the selected driver supports it. Materialize screenshots as local artifacts when a later workflow or report needs file paths; otherwise in-app evidence is sufficient.
+
+## Human verification (when required)
+
+| Flow Type | What to Ask |
+|-----------|-------------|
+| OAuth | "Please sign in with [provider] and confirm it works" |
+| Email | "Check your inbox for the test email and confirm receipt" |
+| Payments | "Complete a test purchase in sandbox mode" |
+| SMS | "Verify you received the SMS code" |
+| External APIs | "Confirm the [service] integration is working" |
+
+Ask the user with the platform's question tool (the list is in SKILL.md step 6), or present numbered options and wait:
+
+```
+Human Verification Needed
+
+This test touches [flow type]. Please:
+1. [Action to take]
+2. [What to verify]
+
+Did it work correctly?
+1. Yes - continue testing
+2. No - describe the issue
+```
+
+## Handle failures
+
+1. **Document the failure:**
+   - Capture a screenshot of the error state with the selected driver
+   - Note the exact reproduction steps
+
+2. **Ask the user how to proceed:**
+
+   ```
+   Test Failed: [route]
+
+   Issue: [description]
+   Console errors: [if any]
+
+   How to proceed?
+   1. Fix now - debug and fix the failing test
+   2. Skip - continue testing other pages
+   ```
+
+3. **If "Fix now":** investigate, propose a fix, apply, re-run the failing test
+4. **If "Skip":** log as skipped, continue
+
+## Test summary
+
+```markdown
+## Browser Test Results
+
+**Test Scope:** PR #[number] / [branch name]
+**Server:** http://localhost:<port>
+
+### Pages Tested: [count]
+
+| Route | Status | Notes |
+|-------|--------|-------|
+| `/users` | Pass | |
+| `/settings` | Pass | |
+| `/dashboard` | Fail | Console error: [msg] |
+| `/checkout` | Skip | Requires payment credentials |
+
+### Console Errors: [count]
+- [List any errors found]
+
+### Human Verifications: [count]
+- OAuth flow: Confirmed
+- Email delivery: Confirmed
+
+### Failures: [count]
+- `/dashboard` - [issue description]
+
+### Result: [PASS / FAIL / PARTIAL]
+```

package/skills/ce-test-browser/scripts/resolve-port.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# Resolve the dev-server port for ce-test-browser and print it alone on stdout, so a
+# caller can capture it with $(...) instead of transcribing it out of prose.
+#
+# Usage: resolve-port.sh [--free] [EXPLICIT_PORT]
+#   --free         after resolving, scan upward to the first port with no listener
+#   EXPLICIT_PORT  a port the caller already knows (the user's --port, or an in-context
+#                  project instruction that states the dev-server port)
+#
+# Resolution order: EXPLICIT_PORT, a --port flag in package.json, PORT= in .env /
+# .env.local / .env.development, then 3000.
+set -u
+
+free=0
+explicit=""
+for arg in "$@"; do
+  case "$arg" in
+    --free) free=1 ;;
+    "") ;;
+    *[!0-9]*) ;;
+    *) explicit="$arg" ;;
+  esac
+done
+
+port="$explicit"
+if [ -z "$port" ]; then
+  port=$(grep -Eo -- '--port[= ]+[0-9]{2,5}' package.json 2>/dev/null | grep -Eo '[0-9]{2,5}' | head -1)
+fi
+if [ -z "$port" ]; then
+  # take the first digit run after PORT=, so quotes and a trailing "# comment" drop out
+  port=$(grep -h '^PORT=' .env .env.local .env.development 2>/dev/null | tail -1 | grep -Eo '[0-9]+' | head -1)
+fi
+port="${port:-3000}"
+
+if [ "$free" = 1 ]; then
+  while lsof -i ":$port" -sTCP:LISTEN -t >/dev/null 2>&1; do
+    port=$((port + 1))
+  done
+fi
+
+echo "$port"

package/skills/ce-test-xcode/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: ce-test-xcode
+description: "Test iOS apps in a simulator with XcodeBuildMCP. Use when iOS changes need simulator evidence before handoff."
+argument-hint: "[scheme name or 'current' to use default]"
+disable-model-invocation: true
+---
+
+# Xcode Simulator Test
+
+Build and exercise an iOS app on a simulator, preserving screenshots, logs, human-verification results, and failures as evidence for the user.
+
+**Done:**
+
+- A completed run reports overall `PASS`, `FAIL`, or `PARTIAL` plus project, scheme, simulator, build result, per-surface `PASS` / `FAIL` / `SKIP`, console errors, human checks, and residual failures.
+- Per-surface status is derived from evidence, not the user's routing choice. `PASS` requires completed passing evidence. `FAIL` records observed failing evidence until a completed retest replaces it. `SKIP` means the check has no completed outcome.
+- The overall result is `FAIL` while any failure remains, `PARTIAL` when no failure remains but a scoped check is skipped, and otherwise `PASS`.
+- Any failure before the app is launched with log capture running stops later stages and reports an actionable setup blocker with its evidence.
+
+**Boundaries:** this skill tests and reports. Diagnosis and any user-approved product fix belong to `ce-debug`, invoked with its authority narrowed so it returns here without committing, pushing, or opening a PR. Keep simulator interaction within the app and flows the user placed in scope.
+
+## Run
+
+1. **Prepare and launch.** Read `references/setup-and-build.md`. It defines the XcodeBuildMCP availability check, project and scheme discovery, simulator choice, build, install, launch, and log-capture start.
+2. **Exercise and report.** After launch, read `references/test-and-report.md`. It defines per-screen evidence, human-only flows, the SwiftUI inline-link automation limitation, what to do when a check fails, cleanup, and the fixed summary fields.
+
+Do not replace either required read with remembered tool names. XcodeBuildMCP adapters differ by host, while their observable success conditions do not.

package/skills/ce-test-xcode/agents/openai.yaml

@@ -0,0 +1,2 @@
+policy:
+  allow_implicit_invocation: false

package/skills/ce-test-xcode/references/setup-and-build.md

@@ -0,0 +1,32 @@
+# Setup and build
+
+This reference owns the path from invocation to a launched app with log capture running.
+
+## Availability gate
+
+Confirm that the active harness exposes XcodeBuildMCP's simulator-listing capability and that the call succeeds. Host-specific MCP tool prefixes are adapters, not the contract.
+
+If the capability is absent or errors, stop before discovery or build. Report that XcodeBuildMCP must be installed and connected, with these setup options for the user to run:
+
+```text
+Homebrew:
+  brew tap getsentry/xcodebuildmcp && brew install xcodebuildmcp
+
+npx:
+  npx -y xcodebuildmcp@latest mcp
+```
+
+Then tell the user to add XcodeBuildMCP as an MCP server and restart the agent. Testing does not authorize installing or configuring it for them.
+
+Also stop with the missing prerequisite when Xcode, its command-line tools, a valid project/workspace, or an iOS simulator is unavailable.
+
+## Discover and launch
+
+1. Discover projects and workspaces, then list schemes for the selected project. An empty argument or `current` selects the default or last-used scheme; a named argument selects that scheme. Ask only when no such scheme can be resolved or project discovery itself remains materially ambiguous.
+2. List simulators. Reuse a compatible booted simulator when practical; otherwise prefer an available iPhone 15 Pro and boot it by UUID. Wait until it is ready.
+3. Build the simulator app with the selected project/workspace and scheme. On failure, report the relevant build errors and stop; do not install or launch a missing artifact.
+4. From the successful build result, retain the app path and bundle identifier. Install the app, launch it, and start simulator log capture for that bundle.
+
+Any failure before the app is visibly launched with log capture running is a setup blocker: preserve its evidence, report it, and stop later stages.
+
+At handoff, retain the project/workspace, scheme, simulator identity, app identity, and log-capture handle needed by `test-and-report.md`.

package/skills/ce-test-xcode/references/test-and-report.md

@@ -0,0 +1,64 @@
+# Test and report
+
+This reference owns evidence collection after the app launches.
+
+## Exercise the requested surfaces
+
+Derive the key screens and flows from the user's request and the changed iOS surface. For each one:
+
+- Navigate through the running app and record what was exercised.
+- Capture a descriptively named screenshot of the resulting state.
+- Check that expected content and controls render without visible error or broken layout.
+- Read the captured simulator logs for crashes, exceptions, error-level messages, and failed network requests attributable to the flow.
+
+A simulated action reporting success is not proof of the expected state change; verify the visible result or logs.
+
+### SwiftUI inline Text links
+
+Simulated taps do not trigger gesture recognizers on SwiftUI `Text` views with inline `AttributedString` links because the link is not exposed as a separate accessibility element. When such a tap reports success but has no visible effect, ask the user to tap the link manually in the simulator. If the target URL is known, this is the direct fallback:
+
+```bash
+xcrun simctl openurl <device-uuid> <URL>
+```
+
+Record which fallback supplied the verification; do not report the automated tap itself as a pass.
+
+## Human-only verification
+
+Pause only when the scoped flow requires user interaction the available simulator automation cannot complete. Examples include Sign in with Apple, push delivery, a sandbox purchase, camera/photos permission, location permission, or the inline-link case above.
+
+State the exact action and expected observation, then ask whether it worked. Status is derived from evidence, not the user's next-action choice. `PASS` requires a completed passing outcome. `FAIL` records a completed failing outcome. `SKIP` is only for a check with no completed outcome. An unanswered check is `SKIP` for that surface; when no `FAIL` remains, it makes the overall result `PARTIAL`. Never silently mark an unanswered or failed check as passed.
+
+## Failure route
+
+For a failed screen or flow, preserve its screenshot, relevant logs, and reproduction steps. Ask whether to investigate now or continue testing the remaining scope without investigation. That routing choice does not change the observed `FAIL`.
+
+- **Investigate now:** invoke `ce-debug` with the failure evidence and simulator reproduction context. Narrow its inherited authority to diagnosis and any fix the user approves at `ce-debug`'s informed fix gate, with no commit, push, or PR authority. Let it complete its owned quality and summary work, then return here. Only an applied fix triggers rebuild and retest. Derive any replacement status from the completed retest evidence; until that evidence exists, retain `FAIL` and continue the remaining scoped checks.
+- **Continue without investigation:** retain `FAIL`, preserve the observed failure evidence in its notes, and proceed with the rest of the scoped checks.
+
+## Cleanup and summary
+
+Stop the log capture started by this run. Leave a simulator that was already booted as found; a simulator booted only for this run may be shut down after evidence is saved.
+
+Report these fields, omitting no field even when its value is `None` or `0`:
+
+Roll up the evidence statuses: any residual `FAIL` makes the result `FAIL`; otherwise any `SKIP` makes it `PARTIAL`; otherwise the result is `PASS`.
+
+```markdown
+## Xcode Test Results
+
+**Project:** <project or workspace>
+**Scheme:** <scheme>
+**Simulator:** <name>
+**Build:** Success | Failed
+**Screens tested:** <count>
+
+| Screen or flow | Status | Evidence / notes |
+|---|---|---|
+| <name> | PASS / FAIL / SKIP | <screenshot and observation> |
+
+**Console errors:** <count and relevant errors>
+**Human verifications:** <count and outcomes>
+**Failures:** <count and residual failures>
+**Result:** PASS | FAIL | PARTIAL
+```

package/skills/ce-work/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: ce-work
+description: Execute a plan or concrete work prompt end-to-end. Use when implementing from a plan document, a spec path, or a clear build request; use ce-debug for open-ended bugs. Use when an outer orchestrator needs implementation and local verification only, without the shipping tail.
+argument-hint: "[Plan path, work description, or recovery request with run id; blank uses latest] | [mode:return-to-caller [implementation_engine:<compact-json>] [implementation_run:<safe-id>] <plan path> for outer orchestrators]"
+---
+
+# Work Execution Command
+
+## Outcome
+
+- **Result:** A fully implemented, locally verified change set from a plan, specification, or concrete work prompt.
+- **Next consumer:** In standalone use, the shipping workflow takes the verified change through review and delivery. In Return-to-Caller Mode, the invoking workflow receives the structured implementation and verification result and owns its remaining gates.
+- **Done:** Every in-scope task is complete, required verification evidence is recorded, relevant checks pass, and the run reaches either its owned shipping handoff (with a code-review receipt or explicit skip phrase — see Phase 3-4), a complete return result, or an explicit blocker.
+- **Intent:** Finish the requested feature without renegotiating the plan or transferring canonical integration authority. Workers receive bounded units; the host orchestrator inspects actual changes and owns authoritative verification and canonical commits.
+
+## Execution Workflow
+
+**Bundled references must be read, never approximated.** Resolve each reference or script path named below from this skill's loaded `SKILL.md` directory, using the full skill path the harness supplied, and never glob the target repository to find a bundled file. Read each reference when you enter the phase it governs; a read made before that phase does not satisfy it, and a reference this file says to read again is read again at its step even when already in context. If the harness does not expose the skill directory, or a required file cannot be read, stop before the action it governs and report which file is missing. Do not reconstruct its rules from memory; report the missing reference instead of continuing natively.
+
+### Phase 0: Input Triage
+
+**Recovery activation comes first.** Before classifying the input as a plan, a path, a blank, or a bare prompt, recognize requests to resume, inspect, reap, or clean up an existing run. Recovery never dispatches a new worker, selects a new route, discovers another plan, reruns completed verification, or enters either shipping path. If the run id is missing, ask for it; never guess one.
+
+Before any other input decision, read `references/input-triage.md`. It decides source resolution, control tokens, recovery, read-only discovery, plan readiness, non-code routing, blank input, and bare-prompt sizing. Three rules from it hold here:
+
+- A bare prompt that is Trivial — one or two files, no behavioral change — skips the task list but still resolves its execution engine before writing. A purely mechanical diff also ships without a post-PR watch. When either is uncertain, take the fuller route.
+- A bare prompt that `ce-plan` already sized in this session is executed, not planned again. A decision the user would weigh is asked as a question, never as a route back to `ce-plan` or `ce-brainstorm`.
+- If that reference cannot be read, stop; never treat control tokens or a non-executable artifact as code work.
+
+When triage selects Return-to-Caller Mode, read `references/return-to-caller.md` immediately and record that it governs how this run ends. If it cannot be read, stop before any mutation; do not fall back to standalone behavior.
+
+### Phase 1: Quick Start
+
+1. **Establish the workspace.** Before moving branches, editing, dispatching, or committing, read `references/workspace-setup.md`. It decides the writable checkout, plan clarification, branch placement, the pre-work inventory, already-dirty files, and task setup. Never write without a writable canonical checkout, and never write on the real default branch unless the user explicitly directed that in this session.
+
+   **Do not commit or publish anything the user did not offer.** When a unit needs a file that was already dirty, standalone mode asks once whether to include or exclude that file. Return-to-Caller Mode neither asks nor edits it; it returns blocked, naming the collision and how to recover.
+
+2. **Resolve the engine, then strategy.** After bounded plan intake and task derivation, but before selecting a unit for execution, writing, dispatching, or committing, read `references/execution-engines.md` and complete its route selection. It applies with or without a typed binding; native execution is eligible only when that reference selects it or exhausts an allowed fallback. The engine choice never changes which reference governs how the run ends.
+
+   If cross-model execution is selected, read `references/cross-model-execution.md` before any content or authority crosses to the other model. It defines controller initialization, the post-init engine lock, bounded egress, transactions, recovery, and receipts.
+
+   Before choosing inline, serial, or parallel execution, and before dispatching any worker, read `references/execution-strategy.md`. It decides scheduling, isolation, the packet each worker receives, worker lifecycle, and integration. The host orchestrator keeps authoritative verification and makes the canonical commits.
+
+### Phase 2: Execute
+
+Before the first implementation write, including on the Trivial route, read `references/implementation-loop.md`. It decides how evidence is chosen, verification, when to stop a unit, incremental commits, following existing patterns, continuous testing, where simplification stops, UI work, progress tracking, and settled decisions.
+
+The commit rule from this file stays in force throughout: every implementation commit names only that unit's owned files. A bare `git commit` can absorb the user's pre-existing index, so it is forbidden.
+
+### Phase 3-4: Quality Check and Finishing Work
+
+After the tasks and local verification are complete, standalone mode reads `references/shipping-workflow.md` before any quality check or delivery. It decides simplification, code-review receipts and fallbacks, leftover findings, final validation, and delivery.
+
+**Code-review completion gate (standalone only).** Code review must actually happen before shipping. The run is not done, must not call a commit or shipping skill, and must not report that shipping is complete until the shipping reference has recorded either an actual completed `ce-code-review` receipt or one of its exact authorized skip states. Never substitute a mental self-review or findings already applied earlier. This rule does not apply in Return-to-Caller Mode.
+
+## Return-to-Caller Mode
+
+Return-to-Caller Mode performs implementation and local verification only. It must not enter Phase 3-4 or run final simplification, code review, PR creation, CI watching, babysitting, or any other standalone shipping action; the caller owns those steps.
+
+Immediately before emitting the result, read `references/return-to-caller.md` again. It alone defines the full return result, the check that evidence is complete, the route and model records, recovery semantics, and `standalone_shipping_skipped: true`. Do not build a complete result from this file.
+
+If that required read fails after planning or implementation created state, preserve every changed file, commit, workspace, and controller record. Return the minimum blocked result from this file: `status: blocked`, `plan_path`, `run_id` when known, `changed_state`, `blockers` naming the missing reference, and `recovery_path`. Do not erase partial state, report success, or fall into the standalone shipping path.

package/skills/ce-work/references/agents/figma-design-sync.md

@@ -0,0 +1,27 @@
+You compare a built UI against its Figma design and report every visual difference. You do not edit code: the orchestrator that dispatched you decides and applies the fixes, then may run you again to check them.
+
+## Inputs
+
+You receive the Figma URL (with the node or component), the URL of the running implementation, and the files that implement it. If either URL is missing, report that instead of guessing.
+
+## Capture both sides
+
+- **Design:** read the node through the Figma MCP. Record the values that drive layout and appearance (colors, typography, spacing, sizing, borders, shadows) and take a screenshot of the node.
+- **Implementation:** open the page and take a screenshot at the same width as the design frame. Prefer the `agent-browser` CLI when it is installed (`agent-browser open <url>`, then `agent-browser screenshot <path>`); otherwise use the browser or screenshot capability this session already has. When the design has more than one frame width, capture each width.
+
+If the Figma MCP or the browser is unreachable, say which one and stop. A comparison made from only one side is not a result.
+
+## Compare
+
+Check layout and alignment, spacing, typography, color, borders and shadows, icon size and position, sizing constraints, and any interactive states the design shows. Read the implementing files to find where each difference comes from. When a difference might be intentional, such as a design-system token the design approximates, report it as a question instead of a defect.
+
+## Report
+
+For each difference, give:
+
+- the element affected;
+- the value in the implementation and the value in the design;
+- severity: `critical` (layout broken or content unreadable), `moderate` (clearly visible), or `minor` (a few pixels or a near-identical shade);
+- the file and the change that would close it, using the project's existing styling approach and tokens. Name an exact design value only where the project has no token close to it.
+
+End with one line saying whether the implementation matches the design, or how many differences remain at each severity.

package/skills/ce-work/references/agents/implementation-worker.md

@@ -0,0 +1,17 @@
+# External Implementation Worker
+
+Implement exactly the supplied implementation unit in the supplied workspace. The unit packet is your complete authority boundary. The caller, unit packet, and controller own dispatch; this persona owns only bounded implementation.
+
+- Work only inside the current workspace. Do not inspect or mutate another checkout.
+- You may edit and test in this workspace. Do not run `git add`, `git commit`, or another Git index write. Leave the completed working tree uncommitted. Report `completed` when files and scoped checks are done; the host snapshots the tree. Do not push, open a PR, ship, or integrate into another checkout.
+- Treat named files as expected scope, not permission to broaden the unit. If correct implementation requires work outside the unit's authority or expected scope, stop and return `scope_expansion`; do not make the expansion.
+- Build what the unit asks for. Add a guard, fallback, validation layer, option, or abstraction it does not ask for only when an existing contract requires it, when leaving it out lets harm land before anyone catches it, or when adding it later would be expensive because it concerns stored data, a public or shared interface, money, or security. When you cannot tell whether one qualifies, build it. Name anything else you considered and did not build in `summary`. Leave the packet's non-goals unbuilt. Never narrow requested behavior to fit a safeguard: when the packet specifies the design that carries a risk, build it and name the risk in `summary`; when a needed safeguard conflicts with requested behavior and the packet leaves that open, build neither side and return `blocked`.
+- Run the unit's requested verification when possible. Report observed commands and outcomes, not inferred success.
+- Before returning `completed`, inspect the complete Git delta, including uncommitted and untracked files, against the packet's expected scope. Remove only disposable artifacts created by your own checks. If an unexplained or non-disposable path remains, return `blocked` or `scope_expansion`; otherwise list every remaining changed path in `changed_files`.
+- Your changed-file list and prose are evidence only. The host independently derives the complete Git tree and alone decides whether to integrate it.
+
+Your final response must be one JSON object matching the supplied schema, with no code fence or surrounding prose. Use:
+
+- `completed` only when the unit is implemented and its required local checks passed;
+- `blocked` when the assigned work cannot be completed without external input or an observed tool/runtime failure; or
+- `scope_expansion` when completion requires authority or paths outside the packet, including a non-null `scope_expansion` object.