In Windsurf, Paqad is advisory: onboarding writes .windsurfrules, a rules file that tells Windsurf's AI (Cascade) how to load your project's rules and workflows. Nothing in Windsurf makes the AI follow it, and Paqad installs no hooks for Windsurf.
What Paqad can enforce in Windsurf
Nothing, during the session. Windsurf is at the advisory level: the tool is given the rules but nothing stops it ignoring them.
- No edit is refused by Paqad.
- No verification runs when Cascade finishes.
- Paqad's evidence files are only written if the AI runs Paqad's commands itself.
Older Paqad material listed Windsurf as enforced. Paqad corrected that; in 1.91.1 the source records Windsurf as advisory, with hooks switched off.
Files onboarding writes
| File | What it is |
|---|---|
.windsurfrules | The entry file, at the project root. It tells the AI to open .paqad/framework-path.txt and follow the installed framework, or to act as a normal assistant if Paqad is missing or off. An existing file keeps its text; Paqad's lines go in a marked block. |
.windsurf/mcp.json | The MCP servers Paqad suggests for your stack. MCP (Model Context Protocol) lets AI tools connect to extra information sources. The file names servers but holds no start commands, so it connects nothing by itself. |
.windsurf/cache.json, .windsurf/memory.json | Paqad bookkeeping. Not Windsurf settings. |
The entry file is a short pointer. It does not contain sections for your stack, rules or design system; those stay in docs/instructions/ and the installed framework. Onboarding does not create .windsurf/skills/ or .windsurf/agents/.
Paqad writes the single-file .windsurfrules format. If your Windsurf version expects rules somewhere else, check that it still loads this file.
Getting evidence without hooks
Paqad's instructions ask the AI, on advisory tools, to record each stage of feature work by running Paqad's commands in the terminal:
npx paqad-ai stage start planning
npx paqad-ai stage end planning --artifact <plan file>These write to the ledger, Paqad's evidence files under .paqad/ledger/. Nothing checks that Cascade runs them. Look in .paqad/ledger/paqad.stage-evidence/ after a change to see what was recorded; if the AI only described the stages in chat, it will be empty.
Independently of the AI, git post-commit and post-merge hooks link commits to their feature, and you can add Paqad's verification script to your CI pipeline. See Adapters overview.
Setting it up
- Run
paqad-ai onboard --providers windsurf, or tick Windsurf when onboarding asks. - Open the project in Windsurf and confirm that Cascade has picked up
.windsurfrules.
If you need edits to be refused when the process is skipped, use Claude Code or Codex CLI.