Local quality layer for Windsurf Cascade

Make Cascade
prove the work.

Deepwork replaces rushed “done” claims with a bounded engineering cycle: contract, inspect, plan, implement, verify, review, and pass an evidence-backed final gate.

Install on Windows View source
  • Six focused MCP tools
  • 51 automated cases
  • Native Arena playbook
cascade / deep-build gated

› /deep-build @deep-build fix checkout race

  1. 01task_begincontract recorded
  2. 02inspect_repository37 files mapped
  3. 03record_planscope locked
  4. 04run_verificationtests passed
  5. 05final_gatechecking evidence
VERIFIEDCurrent fingerprint and Git scope match.
Runs locallyWindows-first installerNode 22+Git-awareFail-closed hooks
01 / WHY

Less persuasion.
More evidence.

Cascade can still reason, edit, and use models normally. Deepwork changes what must be true before it is allowed to write broadly or call the result complete.

WITHOUT A GATE

Fast answer, fragile result

  • Reads only the obvious file
  • Loses requirements during a long session
  • Edits outside the intended scope
  • Repeats the same failed command
  • Says “fixed” before tests run
WITH DEEPWORK

Bounded work, inspectable proof

  • Task contract survives the session
  • Repository inventory precedes the plan
  • Allowed and protected paths are explicit
  • Retry circuits interrupt wasteful loops
  • Current tests and fingerprints decide status
01

Persistent contract

Objective, acceptance criteria, constraints, assumptions, non-goals, and protected paths are recorded before implementation.

02

Real Git scope

The gate compares actual tracked and untracked changes against the baseline, plan, and task contract.

03

Path defenses

Escaping links, junctions, reparse redirects, hardlinks, special files, and protected credential paths are rejected.

04

Constrained verification

Only exact planned checks run through the verifier, with source fingerprints captured before and after execution.

05

Trajectory isolation

Task evidence binds to the Cascade trajectory that began it, preventing one session from borrowing another session’s proof.

06

Honest status

Every outcome is classified as Verified, Partially verified, or Blocked—never upgraded by confident prose.

02 / INSTALL

From GitHub to Cascade
in five deliberate steps.

The runtime remains on your machine because it needs local repository access and must be launched by Windsurf as a `stdio` MCP.

Windows PowerShell Node.js 22+ npm Git recommended
  1. 01
    Clone the public repositoryGet the reviewed source on the machine that runs Windsurf.
  2. 02
    Install exact dependencies`npm ci` respects the lockfile.
  3. 03
    Run the full checksValidate the package before global installation.
  4. 04
    Install into WindsurfThe idempotent installer merges rules, hooks, skill, workflows, and MCP config.
  5. 05
    Reload and invokeEnterprise teams may need admin MCP enablement.
PowerShell 
# 1. Clone
git clone https://github.com/saisharan0103/windsurf-deepwork.git
cd windsurf-deepwork

# 2–3. Reproduce and verify the release
npm ci
npm run check
powershell -NoProfile -File .\scripts\test-installer.ps1

# 4. Install globally for the current Windows user
powershell -NoProfile -ExecutionPolicy Bypass `
  -File .\scripts\install.ps1

# 5. Reload Windsurf, then use in Cascade
/deep-build @deep-build <your task>

Installer safety: it stages the runtime, proves the real Windows hook command, preserves predecessor config, records ownership, and rolls back on failure.

INSTALLED RUNTIME~\.codeium\windsurf\deepwork-runtime
AUDIT STATE~\.codeium\windsurf\deepwork-state
MCP CONFIG~\.codeium\windsurf\mcp_config.json
03 / WORKFLOW

A completion claim
has prerequisites.

The always-on rule keeps the boundary short. The skill and workflows expand only when a non-trivial task needs the full procedure.

01

Contract

Freeze the goal and acceptance criteria.

02

Inspect

Map repository state and affected paths.

03

Plan

Bind files and checks to each criterion.

04

Implement

Edit one coherent unit at a time.

05

Verify

Run exact planned commands and fingerprint.

06

Review

Search independently for counterexamples.

07

Gate

Prove evidence and current Git scope agree.

VERIFIED

Inspection, plan, current fingerprints, every planned command, Git scope, and acceptance evidence pass.

PARTIALLY VERIFIED

Useful work exists, but a relevant check is manual, skipped, unavailable, or lacks the authoritative MCP gate.

BLOCKED

Evidence contradicts completion, a safety boundary was hit, or a required user/platform decision is unavailable.

RECOMMENDED STARTING PROMPT

Give both the task and the standard.

Use the same prompt in each Arena candidate so the comparison is meaningful.

/deep-build @deep-build

Objective: <what must change>
Acceptance criteria:
- <observable result one>
- <observable result two>
Constraints:
- preserve existing user changes
- ask before deployments, secrets, or destructive actions
Verification:
- run the repository-native focused and regression checks
- require deepwork.final_gate before claiming Verified
04 / MCP

Six tools.
One ordered state machine.

A small tool surface makes discovery predictable and keeps the model focused on evidence instead of an oversized integration catalog.

01deepwork.task_begin

Records the objective, acceptance criteria, non-goals, constraints, assumptions, allowed and protected paths, task ID, and canonical workspace.

CONTRACT
02deepwork.inspect_repository

Builds a bounded inventory from Git, manifests, ripgrep or a filesystem fallback, and a link/reparse scan.

READ ONLY
03deepwork.record_plan

Persists ordered steps, risks, exact intended files, and every verification command before implementation writes are allowed.

SCOPE
04deepwork.run_verification

Executes one exact planned check without a shell, in a minimal environment, and fails if relevant source changes during verification.

EXECUTES CODE
05deepwork.task_status

Returns the append-only task evidence and the current quality-gate stage for transparent recovery and handoff.

EVIDENCE
06deepwork.final_gate

Refuses PASS unless the plan, post-change checks, acceptance evidence, current fingerprints, diff summary, and actual Git scope agree.

AUTHORITATIVE
LOCAL ARCHITECTURE

Cloud models, local boundaries.

Cascade remains the MCP client. Deepwork runs as a local Node process, while task evidence stays outside the project and Git remains the source-of-truth for changed scope.

05 / MULTI-MODEL

Spend credits on
independent evidence.

Deepwork cannot switch hosted models or launch Arena through MCP. Windsurf’s native Arena is the documented route for genuine multi-model candidates.

01

Prepare a Git baseline

Initialize Git and commit or preserve the intended starting point. Untracked files are not copied into Arena worktrees by default.

02

Enter Arena manually

Open the live model picker and select two strong, different models available to your account.

03

Send one identical contract

Use the same `/deep-build @deep-build` task in both isolated candidates. Model multipliers are charged additively.

04

Compare artifacts, not confidence

Score repository coverage, diff scope, regression tests, security risk, and final-gate evidence.

05

Run adversarial review

Have the retained models review the winning diff without relying on its self-justification, then rerun affected checks.

Do not confuse prompting with routing.

A skill can require a careful process; it cannot secretly force a model’s hidden reasoning budget, select a Windsurf-hosted model, or start another Cascade session.

06 / WHATSAPP

Message the workflow.
Never expose the shell.

WhatsApp can become a notification or task-intake channel through a separate companion service. It cannot directly call a local Windsurf `stdio` MCP.

CURRENT RELEASE BOUNDARY

This repository does not include a WhatsApp bot, hosted API, database, queue, or remote Windsurf controller.

The diagrams below are a safe implementation blueprint. Deploying the current MCP to Heroku would not make Windsurf or native Arena remotely controllable.

RECOMMENDED FIRST

Keep Windsurf local. Send status outward.

A local watcher reads redacted Deepwork task metadata and sends milestone notifications through Meta’s WhatsApp Cloud API. Incoming messages can stay limited to safe queries such as `status TASK-ID`.

  • No remote code execution surface
  • No cloud copy of the repository
  • Simple opt-in sender allowlist
  • Useful completion and blocker alerts
01

Meta setup

Create a Meta app with WhatsApp, connect a business phone number, configure an HTTPS webhook, subscribe to message events, and store tokens outside source control.

02

Verify every request

Validate the webhook challenge and request signature, reject replayed events, allowlist senders, and enforce idempotency before creating a job.

03

Persist narrow state

Store task ID, sender, repository allowlist key, status, approval state, idempotency key, timestamps, and redacted evidence—not repository contents or secrets.

04

Isolate execution

Use a fresh low-privilege worker per job, a least-privilege GitHub App, an explicit branch, bounded time and cost, and a final pull request for human review.

SAFE MESSAGE CONTRACT

Small verbs. Explicit identity. Visible approval.

A parser should reject everything outside the documented grammar. Free-form context can be attached to a task, but it must never become a shell command.

YOU

build repo:acme/shop issue:123

09:41
BOT

Task DW-482 prepared on branch bot/issue-123. Reply approve DW-482 to permit repository writes, or cancel DW-482.

09:41
YOU

approve DW-482

09:42
BOT

DW-482 is Partially verified. Tests passed; deployment was not requested. Review PR #57.

09:49
COMPONENTGOOD HOSTWHYSTATUS HERE
DocumentationGitHub Pages

Static, public, versioned with the source.

DEPLOYED
Local Deepwork MCPYour Windows machine

Needs local filesystem and Windsurf `stdio` access.

INCLUDED
WhatsApp webhook APIHeroku, Render, Fly.io, or Cloud Run

Public HTTPS ingress and secret management.

BLUEPRINT
Job databaseManaged PostgreSQL

Durable idempotency, approval, and status records.

BLUEPRINT
Repository workerDisposable VM/container runner

Isolates untrusted code from the webhook service.

BLUEPRINT
Meta documentationWhatsApp Cloud API setup Meta’s official Postman workspaceWebhook reference
07 / SECURITY

Defense in depth.
Not a magic sandbox.

Deepwork constrains, detects, records, and refuses. It does not change the operating-system identity of Windsurf or make repository-controlled tests harmless.

PATH

Canonical containment

Reject workspace escapes, protected paths, unsafe links, hardlinks, special files, and mid-scan changes.

COMMAND

Fail-closed policy

Allow read-only terminal inspection; block network, deploy, destructive, chained, installer, and inline-interpreter forms.

MCP

Foreign tools denied

Non-Deepwork MCP calls remain blocked unless the exact lowercase `server/tool` is deliberately allowlisted.

STATE

Trajectory-bound evidence

Append-only state, task identity, and content fingerprints prevent proof reuse after later edits.

Untrusted repository? Turn off automatic command execution, remove secrets from the environment, and use a disposable low-privilege VM or container. Hooks are policy checks, not kernel mediation.

08 / SUPPORT

Diagnose the gate,
don’t work around it.

/
Showing all topics
01The Deepwork MCP does not appear in Cascade.

Reload Windsurf, inspect `~\.codeium\windsurf\mcp_config.json`, run the installed doctor, and check whether the Enterprise administrator enabled or allowlisted the exact `deepwork` server configuration.

node "$HOME\.codeium\windsurf\deepwork-runtime\src\cli.js" doctor
02A repository write is blocked.

Complete `task_begin`, `inspect_repository`, `record_plan`, and the required unique reads first. The hook is enforcing the intended order.

03A test or build command is blocked in the terminal.

Record the exact command in the task plan and run it through `deepwork.run_verification`. Direct terminal access is deliberately limited to read-only inspection.

04A different MCP tool is denied.

Review the tool’s trust boundary, then allowlist only its exact lowercase `server/tool` identity through `DEEPWORK_ALLOWED_MCP_TOOLS`. Keep the list minimal.

05The final gate returns REFUSE or PARTIAL.

Rerun every planned command after the latest write, remove out-of-scope changes, provide typed evidence for each criterion, and confirm current fingerprints. Manual evidence or unavailable Git keeps the result partial.

06The installer refuses to overwrite an existing artifact.

The installed file changed or ownership could not be proved. Preserve the change and inspect `deepwork-install.json` plus the ownership backups. Do not delete config just to force installation.

07Can I host the MCP on Heroku?

Not as a drop-in replacement for this release. The current MCP uses local `stdio` and needs the repository filesystem. A remote HTTP transport would require authentication, tenant isolation, repository provisioning, secret management, and a redesigned security boundary.

08Can WhatsApp select models or start Arena?

No documented Windsurf MCP interface does that. A WhatsApp companion can accept tasks and return status, while native Arena still starts manually unless a future supported API changes that boundary.

READY WHEN THE EVIDENCE IS

Install locally.
Work deliberately.

Use GitHub for distribution, Pages for the guide, Windsurf for the local client, and the final gate for the truth.

Open repository Read installation
Copied to clipboard