Deepwork for Windsurf

Documentation | Security policy | Windsurf problem matrix | Claude Code pattern study

Independent community project. Deepwork is not affiliated with or endorsed by Cognition, Windsurf, Devin, or Anthropic.

Deepwork is a max-effort quality-and-safety layer for Cascade. It makes difficult coding work follow an evidence-first cycle: contract, inspect, research, compare designs, plan, checkpoint, implement, verify, review, and only then claim completion. Windsurf's native Arena mode supplies genuine multi-model execution.

It addresses the fixable parts of the recurring problems summarized in research/problem-matrix.md: shallow repository scans, lost requirements, broad edits, repair loops, missing tests, unsupported completion claims, unsafe paths, MCP configuration risk, and weak durable state. The Claude Code pattern study records the official Anthropic mechanisms adapted into the max-effort design.

Components

• .windsurf/skills/deep-build/: the reusable @deep-build procedure and focused references, including capability-extraction.md for pushing under-provisioned model tiers.

• .windsurf/workflows/deep-build.md: the 22-step /deep-build max-effort runbook.

• .windsurf/workflows/deep-ultra.md: the deep route, adding hypotheses, an adversarial challenge gate, and seven review lenses.

• .windsurf/workflows/deep-ultramax.md: the campaign route for the most complex multi-session work, with a twenty-step plan and a double challenge gate.

• .windsurf/workflows/deep-plan.md, deep-debug.md, and deep-review.md: plan-only, reproduce-first, and review-panel routes.

• .windsurf/rules/deep-build.md: short always-on behavioral constraints.

• .windsurf/hooks.json: fail-closed pre-action policy and metadata-only post-action audit hooks.

• src/: a thirteen-tool local deepwork MCP, four effort profiles, user-global locked state, content-fingerprinted checkpoints/reviews, constrained verifier, and hook engine.

• ARCHITECTURE.md: the full system design, layer by layer.

• scripts/install.ps1: idempotent global installation with ownership metadata, predecessor restoration, atomic config writes, and path-link defenses.

Related MCP server: cleanroom-mcp

Max-effort gates

For a non-trivial task, effortProfile: "max" requires:

1. one measurable completion condition;

2. three distinct repository-research lanes and eight successful unique file reads, or the complete inventory when the repository has fewer than eight files;

3. three architecture alternatives and no unresolved design question;

4. at least eight plan steps, three risks, acceptance-to-test mapping, exact file scope, and rollback;

5. two content-fingerprinted checkpoints, with every plan step complete in the final checkpoint;

6. every planned verification command against the current workspace;

7. correctness, tests, security, error-handling, and simplicity review passes;

8. only findings at confidence 80-100, with every critical/high issue resolved or disproved;

9. a passing final gate against current Git scope and acceptance evidence.

Ultra effort

effortProfile: "ultra" exists for high-consequence work and for Enterprise deployments whose hosted models are weaker than the task deserves. It raises every max gate — four research lanes, four design alternatives, twelve plan steps, five risks, twelve unique reads, three checkpoints — and adds three mechanisms:

1. record_challenge: a mandatory adversarial round with at least three distinct attack vectors against the current design and plan. Writes stay blocked until a round is withstood; an exposed gap forces a revise verdict, a repaired plan, and a fresh challenge.

2. record_hypotheses: competing falsifiable hypotheses with discriminating checks. Any hypothesis left open blocks the final gate.

3. Seven review lenses: the five max lenses plus performance and compatibility.

task_briefing complements the deeper pipeline by rehydrating a fresh or degraded session from durable state — contract, design, plan progress, challenge/hypothesis status, verification results, and workspace-drift detection — instead of chat memory.

Ultramax effort

effortProfile: "ultramax" is the campaign tier for the most complex work: cross-cutting features, migrations, security-sensitive rewrites, and tasks expected to span multiple sessions. It raises every ultra gate again — five research lanes, five design alternatives, a twenty-step plan with eight risks, twenty unique reads, five milestone checkpoints — and requires two withstood adversarial challenge rounds before implementation: one attacking the selected design, one attacking the plan. Revising either invalidates the rounds and forces a fresh challenge. /deep-ultramax is the matching runbook and treats session boundaries as first-class: every resume starts from task_briefing, not chat memory.

Honest boundary

An MCP can expose tools to Cascade; the documented interface cannot switch Cascade's selected Windsurf-hosted model, launch another Cascade, or start Arena. Native Arena Mode is the supported path that runs multiple Windsurf models in isolated sessions/worktrees and charges their credit multipliers additively.

Deepwork mitigates but cannot repair provider outages, editor crashes, billing policy, finite model context, Enterprise allowlists, host MCP bugs, or editor vulnerabilities. The July 8, 2026 GhostApproval disclosure demonstrated a Windsurf trust-boundary failure; check the vendor's current remediation status before relying on editor-level approval UI. Hooks cannot remove filesystem time-of-check/time-of-use races. Use low-privilege OS isolation for untrusted repositories.

The public anthropics/claude-code repository was used as an official workflow reference. Its license is all rights reserved; Deepwork does not copy Claude Code core code or claim to reproduce its private agent loop.

Build and test

npm ci
npm test
node src/cli.js doctor

The automated suite covers max-effort depth gates, real stdio initialization/tool discovery, an external-project task through stdio, official hook payloads, fail-closed internal errors, hardlink/link escapes, Windows short-path aliases and PowerShell encodings, trajectory isolation, hostile command forms, repeat writes, verification-time mutations, stale same-file/untracked changes, every planned command, high-confidence review filtering, and final Git scope enforcement.

Install globally

Clone and validate the package from PowerShell before opening the clone as a Windsurf workspace:

npm ci
npm run check
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\install.ps1

The installer:

1. stages and atomically installs a runtime under ~\.codeium\windsurf\deepwork-runtime;

2. installs the global skill plus /deep-build, /deep-ultra, /deep-ultramax, /deep-plan, /deep-debug, and /deep-review;

3. appends a bounded managed block to global_rules.md;

4. merges global hooks without removing existing hooks;

5. merges one deepwork entry into mcp_config.json;

6. stores an ownership manifest and predecessor backups, proves the Windows hook launcher, and runs the state/hook/stdio doctor.

Runtime task events and transcript metadata are stored outside projects under ~\.codeium\windsurf\deepwork-state, keyed by the canonical workspace. A repository .deepwork/task.md is used only when the MCP is unavailable and should remain uncommitted. Uninstall intentionally retains deepwork-state as audit/continuity data.

Enterprise administrators may still need to enable or allowlist the MCP. The runtime, skill, workflows, hooks, and MCP configuration are installed and protocol-tested locally; restart Windsurf to reload them, then confirm UI discovery under the account's live Enterprise policy.

Use

For a normal complex task:

1. Initialize Git and preserve or commit the intended baseline.

2. Invoke /deep-build and mention @deep-build. Use /deep-ultra for the deep gated route, /deep-ultramax for the heaviest multi-session campaigns, /deep-plan for no-edit architecture, /deep-debug for a defect, or /deep-review for an independent candidate review.

3. Let the workflow call the thirteen deepwork tools and obey blocking hooks. Planned tests/builds run through the approval-bearing verifier; non-Deepwork MCP tools are denied unless their exact server/tool identity is deliberately allowlisted.

For deliberate multi-model use of the Enterprise credit pool:

1. Open the model picker and enter Arena.

2. Select two strong, different models currently available; avoid Adaptive when deliberate comparison is the goal.

3. Send the identical /deep-build @deep-build contract to both isolated candidates.

4. Compare research coverage, architecture, diff, tests, risks, and evidence; select a winner.

5. Run /deep-review with retained Arena models, resolve high-severity findings, and require deepwork.final_gate to pass.

Spend additional prompts on different research hypotheses, architecture challenge, repeated-failure diagnosis, specialized review, and finding validation - not interchangeable summaries.

Completion states

• Verified: contract, research, design, traceable plan, completed checkpoints, five-lens review, Git scope, acceptance evidence, every planned command, and current fingerprint passed.

• Partially verified: useful work exists, but a relevant check is skipped, unavailable, or manual.

• Blocked: evidence contradicts completion or a required decision/platform capability is unavailable.

If the MCP/final gate is unavailable, the maximum honest status is Partially verified.

WhatsApp and remote control

This repository does not include a WhatsApp bot, hosted API, database, or remote Windsurf controller. The local MCP needs direct repository access, and native Arena is started manually. The documentation site explains a safe notification companion or separately built authenticated job service.

License status

The repository is publicly visible, but no software license has been selected. Public visibility alone does not grant reuse, redistribution, or derivative-work rights.