feat(agent): add windsurf as an install target

Windsurf (Cascade) reads workspace rules from `.windsurf/rules/*.md`. Add it
as an own-file agent target so `testsprite agent install --target windsurf`
(and `setup --agent windsurf`) installs the TestSprite skills into a Windsurf
project. Reworked onto the v0.2.0 multi-skill agent-targets API (pathFor /
SKILLS / DEFAULT_SKILLS).

Rule files use Cascade frontmatter with `trigger: model_decision` — the
equivalent of the Cursor `.mdc` `alwaysApply: false` mode (description shown
up front; full body pulled in on relevance).

Budget handling: a `.windsurf/rules/*.md` file caps at ~12 K characters and
Cascade silently truncates beyond it, which would cut the full ~22 KB verify
skill in half. The windsurf target therefore renders the COMPACT body per
skill (new `compactBody` flag + `compactBodyFor`): a skill that ships a
trimmed codex asset (`testsprite-verify` → ~5 KB) uses it, while a skill whose
codex contribution is only a one-liner (`testsprite-onboard`, ~6.5 KB full)
keeps its full body — both land well under the cap. `agent.ts` and
`renderForTarget` select the same body so installed bytes match the render.

Everything else derives from the TARGETS map automatically (agent list, the
setup --agent choices, skill-nudge install detection). Updated the hardcoded
help strings, the --help snapshot, the agent-targets/agent unit tests (incl.
Cascade-frontmatter and per-skill budget tests), the e2e matrix guards /
content-integrity (gated on compactBody), and the README/DOCUMENTATION target
lists (incl. the --force own-file list).

Author: Davidson3556

DOCUMENTATION.md

@@ -112,15 +112,16 @@ testsprite agent install claude     # install the skill for Claude Code
 testsprite agent install codex      # install into AGENTS.md for Codex (managed-section)
 testsprite agent install cursor     # .cursor/rules/testsprite-verify.mdc
 testsprite agent install cline      # .clinerules/testsprite-verify.md
+testsprite agent install windsurf   # .windsurf/rules/testsprite-verify.md
 testsprite agent install antigravity  # .agents/skills/testsprite-verify/SKILL.md
-testsprite agent list               # list all 5 targets with status + mode + path
+testsprite agent list               # list all 6 targets with status + mode + path
 ```
 
-Supported targets: `claude` (GA), `codex` (experimental), `cursor` (experimental), `cline` (experimental), `antigravity` (experimental).
+Supported targets: `claude` (GA), `codex` (experimental), `cursor` (experimental), `cline` (experimental), `windsurf` (experimental), `antigravity` (experimental).
 
 The `codex` target uses **managed-section mode** — it writes only a sentinel-delimited section inside your existing `AGENTS.md`, so your project instructions are never clobbered. Re-running without `--force` replaces the section in-place; user content outside the sentinels is always preserved.
 
-Re-running with `--force` on **own-file targets** (claude, cursor, cline, antigravity) backs up the existing file to `<path>.bak` first.
+Re-running with `--force` on **own-file targets** (claude, cursor, cline, windsurf, antigravity) backs up the existing file to `<path>.bak` first.
 
 ## Command reference
 

README.md

@@ -61,7 +61,7 @@ npm install -g @testsprite/testsprite-cli
 testsprite setup
 ```
 
-`testsprite setup` prompts for your [API key](https://www.testsprite.com), verifies it, and installs the verification-loop skill for your coding agent (`claude`, `cursor`, `cline`, `antigravity`, `codex`, etc.) — one command, so your agent is wired to verify its own work. Non-interactive (CI / onboarding scripts):
+`testsprite setup` prompts for your [API key](https://www.testsprite.com), verifies it, and installs the verification-loop skill for your coding agent (`claude`, `cursor`, `cline`, `windsurf`, `antigravity`, `codex`, etc.) — one command, so your agent is wired to verify its own work. Non-interactive (CI / onboarding scripts):
 
 ```bash
 TESTSPRITE_API_KEY=sk-... testsprite setup --from-env --yes --agent claude
@@ -110,7 +110,7 @@ Prefer to configure each step by hand (or learn the surface offline with `--dry-
 |           | `test rerun`                                        | Cheap replay of one/many tests (FE verbatim; BE with deps); `--all --project <id>` reruns all tests                   |
 |           | `test wait`                                         | Block on a `runId` until terminal                                                                                     |
 |           | `test artifact get`                                 | Download the failure bundle for a specific `runId`                                                                    |
-| **Agent** | `agent install` / `agent list`                      | Add or list coding-agent targets (pure-local): `claude`, `codex`, `cursor`, `cline`, `antigravity`                    |
+| **Agent** | `agent install` / `agent list`                      | Add or list coding-agent targets (pure-local): `claude`, `codex`, `cursor`, `cline`, `windsurf`, `antigravity`        |
 
 > The earlier command names — `init`, `auth configure`, `auth whoami`, `auth logout` — still work as hidden, deprecated aliases (each prints a one-line notice pointing at the new name), so existing scripts keep running. `auth configure` now runs the full `setup` (it also installs the skill).
 

src/commands/agent.test.ts

@@ -759,12 +759,13 @@ describe('runList', () => {
 
     const json = JSON.parse(capture.stdout.join('\n')) as ListResult[];
     expect(Array.isArray(json)).toBe(true);
-    // 5 targets × 2 default skills = 10 rows
-    expect(json).toHaveLength(10);
+    // 6 targets × 2 default skills = 12 rows
+    expect(json).toHaveLength(12);
     const targets = json.map(r => r.target);
     expect(targets).toContain('claude');
     expect(targets).toContain('cursor');
     expect(targets).toContain('cline');
+    expect(targets).toContain('windsurf');
     expect(targets).toContain('antigravity');
     expect(targets).toContain('codex');
     // skill field present on each row
@@ -908,8 +909,8 @@ describe('createAgentCommand wiring', () => {
 // All four own-file targets installed at once
 // ---------------------------------------------------------------------------
 
-describe('runInstall — all four own-file targets', () => {
-  it('installs all four own-file targets in one invocation', async () => {
+describe('runInstall — all own-file targets', () => {
+  it('installs every own-file target in one invocation', async () => {
     const { store, fs: agentFs } = makeMemFs();
     const { capture, deps } = makeCapture();
 
@@ -919,7 +920,7 @@ describe('runInstall — all four own-file targets', () => {
         output: 'text',
         debug: false,
         dryRun: false,
-        target: ['claude', 'cursor', 'cline', 'antigravity'],
+        target: [...OWN_FILE_TARGETS],
         skills: ['testsprite-verify'],
         force: false,
       },

src/commands/agent.ts

@@ -13,6 +13,7 @@ import {
   DEFAULT_SKILLS,
   pathFor,
   loadSkillBodyFor,
+  compactBodyFor,
   buildCodexAggregate,
   renderForTarget,
   MANAGED_SECTION_BEGIN,
@@ -434,6 +435,21 @@ export async function runInstall(opts: InstallOptions, deps: AgentDeps = {}): Pr
     }
     return b;
   };
+  // Budget-capped own-file targets (e.g. windsurf) render the compact per-skill
+  // body so the rule file isn't truncated by the agent. Cached separately; must
+  // match renderForTarget's default selection so written bytes equal the asserted
+  // render.
+  const compactBodyCache = new Map<string, string>();
+  const compactBodyForSkill = (skill: string): string => {
+    let b = compactBodyCache.get(skill);
+    if (b === undefined) {
+      b = compactBodyFor(skill);
+      compactBodyCache.set(skill, b);
+    }
+    return b;
+  };
+  const ownFileBodyFor = (t: AgentTarget, skill: string): string =>
+    TARGETS[t].compactBody ? compactBodyForSkill(skill) : bodyForSkill(skill);
   let codexSectionCache: string | undefined;
   const getCodexSection = (): string => {
     if (codexSectionCache === undefined) {
@@ -635,7 +651,7 @@ export async function runInstall(opts: InstallOptions, deps: AgentDeps = {}): Pr
       if (abs !== root && !abs.startsWith(root + path.sep)) {
         throw new CLIError(`refusing to write outside --dir: ${relPath}`, 5);
       }
-      const content = renderForTarget(t, skill, bodyForSkill(skill)).content;
+      const content = renderForTarget(t, skill, ownFileBodyFor(t, skill)).content;
 
       if (opts.dryRun) {
         const bytes = Buffer.byteLength(content, 'utf8');
@@ -788,7 +804,7 @@ function collect(v: string, prev: string[]): string[] {
 
 export function createAgentCommand(deps: AgentDeps = {}): Command {
   const agent = new Command('agent').description(
-    'Install TestSprite guidance into coding-agent config (Claude Code, Cursor, Cline, Antigravity, Codex)',
+    'Install TestSprite guidance into coding-agent config (Claude Code, Cursor, Cline, Windsurf, Antigravity, Codex)',
   );
 
   agent
@@ -798,7 +814,7 @@ export function createAgentCommand(deps: AgentDeps = {}): Command {
     )
     .option(
       '--target <t>',
-      'Agent target(s): claude, cursor, cline, antigravity, codex (comma-separated or repeated)',
+      'Agent target(s): claude, cursor, cline, windsurf, antigravity, codex (comma-separated or repeated)',
       collect,
       [],
     )

src/lib/agent-targets.test.ts

@@ -74,18 +74,19 @@ testsprite test artifact get <run-id> --out ./out/
 // ---------------------------------------------------------------------------
 
 describe('TARGETS', () => {
-  it('has all five required keys', () => {
+  it('has all six required keys', () => {
     const keys = Object.keys(TARGETS).sort();
-    expect(keys).toEqual(['antigravity', 'claude', 'cline', 'codex', 'cursor']);
+    expect(keys).toEqual(['antigravity', 'claude', 'cline', 'codex', 'cursor', 'windsurf']);
   });
 
   it('claude is GA', () => {
     expect(TARGETS.claude.status).toBe('ga');
   });
 
-  it('cursor, cline, antigravity, and codex are experimental', () => {
+  it('cursor, cline, windsurf, antigravity, and codex are experimental', () => {
     expect(TARGETS.cursor.status).toBe('experimental');
     expect(TARGETS.cline.status).toBe('experimental');
+    expect(TARGETS.windsurf.status).toBe('experimental');
     expect(TARGETS.antigravity.status).toBe('experimental');
     expect(TARGETS.codex.status).toBe('experimental');
   });
@@ -102,6 +103,7 @@ describe('TARGETS', () => {
     expect(TARGETS.antigravity.mode).toBe('own-file');
     expect(TARGETS.cursor.mode).toBe('own-file');
     expect(TARGETS.cline.mode).toBe('own-file');
+    expect(TARGETS.windsurf.mode).toBe('own-file');
   });
 
   it('codex target has mode managed-section', () => {
@@ -269,6 +271,52 @@ describe('renderForTarget("cline")', () => {
   });
 });
 
+describe('renderForTarget("windsurf")', () => {
+  const result = renderForTarget('windsurf', 'testsprite-verify', STUB_BODY);
+
+  it('returns the .windsurf/rules path', () => {
+    expect(result.path).toBe('.windsurf/rules/testsprite-verify.md');
+  });
+
+  it('uses the Cascade frontmatter (trigger: model_decision + description)', () => {
+    expect(result.content.startsWith('---\n')).toBe(true);
+    expect(result.content).toContain('trigger: model_decision');
+    expect(result.content).toContain(`description: ${SKILL_DESCRIPTION}`);
+  });
+
+  it('does NOT carry the Claude/Cursor frontmatter keys', () => {
+    const match = /^---\n([\s\S]*?)\n---/.exec(result.content);
+    const fm = match?.[1] ?? '';
+    expect(fm).not.toContain('name:'); // claude key
+    expect(fm).not.toContain('alwaysApply:'); // cursor .mdc key
+  });
+});
+
+describe('windsurf renders within the rules-file budget', () => {
+  // Regression: a `.windsurf/rules/*.md` file caps at ~12 K characters and
+  // Cascade silently truncates beyond that. The full verify body (~22 KB) would
+  // be cut in half, so windsurf renders the COMPACT body for verify (its trimmed
+  // codex asset) and the full body for onboard (which already fits). Uses the
+  // REAL bodies (no stub) so the size reflects what a user receives.
+  for (const skill of DEFAULT_SKILLS) {
+    it(`${skill} fits under 12 000 characters`, () => {
+      const r = renderForTarget('windsurf', skill);
+      expect(r.content.length).toBeLessThan(12_000);
+    });
+  }
+
+  it('verify uses the compact body (smaller than the full claude render)', () => {
+    const windsurf = renderForTarget('windsurf', 'testsprite-verify');
+    const claude = renderForTarget('claude', 'testsprite-verify');
+    expect(windsurf.content.length).toBeLessThan(claude.content.length);
+    // The full-body-only intro line is absent from the compact body...
+    expect(claude.content).toContain('The verification loop that flies');
+    expect(windsurf.content).not.toContain('The verification loop that flies');
+    // ...but the load-bearing command survives.
+    expect(windsurf.content).toContain('testsprite test run');
+  });
+});
+
 // ---------------------------------------------------------------------------
 // Content integrity — load-bearing command strings must survive any body trim
 // ---------------------------------------------------------------------------

src/lib/agent-targets.ts

@@ -1,6 +1,6 @@
 import { readFileSync } from 'node:fs';
 
-export type AgentTarget = 'claude' | 'cursor' | 'cline' | 'antigravity' | 'codex';
+export type AgentTarget = 'claude' | 'cursor' | 'cline' | 'antigravity' | 'codex' | 'windsurf';
 
 export interface TargetSpec {
   status: 'ga' | 'experimental';
@@ -12,11 +12,19 @@ export interface TargetSpec {
    */
   path: string;
   /**
-   * 'own-file': the CLI owns the whole file (claude/cursor/cline/antigravity).
+   * 'own-file': the CLI owns the whole file (claude/cursor/cline/antigravity/windsurf).
    * 'managed-section': the CLI writes only a sentinel-delimited section inside
    * a potentially user-authored file (codex target, AGENTS.md).
    */
   mode: 'own-file' | 'managed-section';
+  /**
+   * When true, render the budget-friendly body (see {@link compactBodyFor})
+   * instead of the full own-file skill body. Used for own-file targets whose
+   * rule files are size-capped — currently `windsurf` (`.windsurf/rules/*.md`
+   * files cap at ~12 K characters and Cascade silently truncates beyond that,
+   * which would cut the full ~22 KB verify skill in half).
+   */
+  compactBody?: boolean;
   /**
    * Wrap a skill body in this target's frontmatter/header. Takes the skill's
    * `name`+`description` (own-file targets emit them as frontmatter) and the body.
@@ -120,6 +128,18 @@ function wrapMdc(_name: string, description: string, body: string): string {
   return `---\ndescription: ${description}\nalwaysApply: false\n---\n\n${body}\n`;
 }
 
+/**
+ * Windsurf (Cascade) reads workspace rules from `.windsurf/rules/*.md` with YAML
+ * frontmatter. `trigger: model_decision` is the Cascade equivalent of the Cursor
+ * `.mdc` `alwaysApply: false` mode: only the `description` is surfaced up front,
+ * and Cascade pulls in the full rule body when the description shows it is
+ * relevant — exactly the on-demand activation these skills want. (The other
+ * triggers are `always_on`, `manual`, and `glob`.)
+ */
+function wrapWindsurf(_name: string, description: string, body: string): string {
+  return `---\ntrigger: model_decision\ndescription: ${description}\n---\n\n${body}\n`;
+}
+
 // ---------------------------------------------------------------------------
 // Landing paths
 // ---------------------------------------------------------------------------
@@ -140,6 +160,8 @@ export function pathFor(target: AgentTarget, skill: string): string {
       return `.cursor/rules/${skill}.mdc`;
     case 'cline':
       return `.clinerules/${skill}.md`;
+    case 'windsurf':
+      return `.windsurf/rules/${skill}.md`;
     case 'codex':
       return 'AGENTS.md';
   }
@@ -170,6 +192,15 @@ export const TARGETS: Record<AgentTarget, TargetSpec> = {
     mode: 'own-file',
     wrap: (_name, _description, body) => body,
   },
+  windsurf: {
+    status: 'experimental',
+    path: pathFor('windsurf', SKILL_NAME),
+    mode: 'own-file',
+    // Windsurf rules files are budget-capped (~12 K chars per `.windsurf/rules/*.md`),
+    // so render the compact body per skill (see compactBodyFor).
+    compactBody: true,
+    wrap: wrapWindsurf,
+  },
   /**
    * codex target — managed-section mode.
    *
@@ -227,6 +258,24 @@ export function loadSkillBodyFor(skill: string, read: ReadFn = defaultRead): str
   return readSkillAsset(spec.bodyFile, read);
 }
 
+/**
+ * Budget-friendly body for an own-file target whose rule files are size-capped
+ * (e.g. windsurf). For a skill that ships a trimmed codex asset (`codex.kind ===
+ * 'full'`, e.g. `testsprite-verify` — full body ~22 KB, codex ~5 KB) we render
+ * that compact asset so the wrapped file stays under the cap. For skills whose
+ * codex contribution is only a one-liner (`'line'`/`'none'`, e.g.
+ * `testsprite-onboard`), the one-liner is useless as a standalone rule and the
+ * full own-file body (~6.5 KB) already fits the budget — so the full body is
+ * used.
+ */
+export function compactBodyFor(skill: string, read: ReadFn = defaultRead): string {
+  const spec = SKILLS[skill];
+  if (!spec) throw new Error(`unknown skill: ${skill}`);
+  return spec.codex.kind === 'full'
+    ? readSkillAsset(spec.codex.file, read)
+    : loadSkillBodyFor(skill, read);
+}
+
 /**
  * Resolve a skill's codex (AGENTS.md) contribution as a Markdown string.
  * 'full' → read the `*.codex.md` asset; 'line' → the inline one-liner; 'none' → ''.
@@ -298,6 +347,7 @@ export function renderForTarget(
     const resolvedBody = body !== undefined ? body : codexContentFor(skill);
     return { path, content: spec.wrap(skillSpec.name, skillSpec.description, resolvedBody) };
   }
-  const resolvedBody = body !== undefined ? body : loadSkillBodyFor(skill);
+  const resolvedBody =
+    body !== undefined ? body : spec.compactBody ? compactBodyFor(skill) : loadSkillBodyFor(skill);
   return { path, content: spec.wrap(skillSpec.name, skillSpec.description, resolvedBody) };
 }

test/__snapshots__/help.snapshot.test.ts.snap

@@ -4,7 +4,7 @@ exports[`--help snapshots > agent 1`] = `
 "Usage: testsprite agent [options] [command]
 
 Install TestSprite guidance into coding-agent config (Claude Code, Cursor,
-Cline, Antigravity, Codex)
+Cline, Windsurf, Antigravity, Codex)
 
 Options:
   -h, --help         display help for command
@@ -25,8 +25,9 @@ Write the TestSprite agent skills (verification loop + first-run onboarding)
 into a project for a coding agent
 
 Options:
-  --target <t>    Agent target(s): claude, cursor, cline, antigravity, codex
-                  (comma-separated or repeated) (default: [])
+  --target <t>    Agent target(s): claude, cursor, cline, windsurf,
+                  antigravity, codex (comma-separated or repeated) (default:
+                  [])
   --skill <name>  Skill(s) to install: testsprite-verify, testsprite-onboard
                   (comma-separated or repeated; default: all) (default: [])
   --dir <path>    Project root to write into (default: cwd)
@@ -112,7 +113,8 @@ Options:
   --from-env        Read TESTSPRITE_API_KEY from the environment instead of
                     prompting (default: false)
   --agent <target>  Coding-agent target to install: claude, antigravity,
-                    cursor, cline, codex (default: claude) (default: "claude")
+                    cursor, cline, windsurf, codex (default: claude) (default:
+                    "claude")
   --no-agent        Skip the agent skill install (configure credentials only)
   --force           Overwrite an existing skill file (a .bak backup is kept)
   --dir <path>      Project root for the skill install (default: current
@@ -581,8 +583,8 @@ Commands:
   project                      Manage TestSprite projects
   test                         Inspect TestSprite tests
   agent                        Install TestSprite guidance into coding-agent
-                               config (Claude Code, Cursor, Cline, Antigravity,
-                               Codex)
+                               config (Claude Code, Cursor, Cline, Windsurf,
+                               Antigravity, Codex)
   usage|credits                Show credit balance and plan/entitlement info
                                (proactive pre-flight before a large test run)
   help [command]               display help for command