TeamFlow in Windsurf

1. Install

npx -y github:macleodlabs-ai/teamflow-plugin skills install --for windsurf

That writes:

• .agents/skills/<skill>/SKILL.md — the ten skills, in the shared skills directory this tool reads
• .windsurf/rules/teamflow.md — the reporting instruction, as a Windsurf rule
• ~/.codeium/windsurf/mcp_config.json — the TeamFlow MCP server under serverUrl
• .teamflow/hooks/windsurf.sh — the hook itself; it calls teamflow hook --for windsurf, prints nothing the tool could read as a denial, and exits 0 whatever happens
• .windsurf/hooks.json — the hook registration: post_write_code, post_run_command and post_cascade_response

Add --scope user to install for every project on this machine, or --dry-run to see the file list without writing anything. Re-running it replaces TeamFlow's block and leaves the rest of each file alone.

2. The skills you get

The same ten the Claude Code plugin carries, generated from the same SKILL.md files. This tool loads them as skills, one directory each, with the name prefixed so they do not collide with anybody else’s in a shared directory.

Each one wraps a github:macleodlabs-ai/teamflow-plugin subcommand, so the skill and the shell command are the same thing. Inside Claude Code they are /teamflow:login, /teamflow:status and so on.

3. Sign in once

Open the MCPs panel from the top right of Cascade, or Settings -> Cascade -> MCP Servers, and use the server's connect control. Windsurf documents OAuth support on every transport but does not spell out the gesture, so the exact button label may differ from your build.

4. By hand

The installer writes this for you. If you would rather paste it: ~/.codeium/windsurf/mcp_config.json, the one global file. There is no documented per-project MCP config.

{
  "mcpServers": {
    "teamflow": {
      "serverUrl": "https://codercat.io/mcp"
    }
  }
}

The key is serverUrl, not url. This is the single most common way to get a Windsurf MCP entry silently ignored, and the installer gets it right so you do not have to remember which tool spells it which way.

Windsurf reads the shared .agents/skills root as well as its own .windsurf/skills, so one install serves it and six other tools.

Rules are the asymmetric part: newer builds prefer .devin/rules/ and fall back to .windsurf/rules/. The installer writes the .windsurf path, which both read. There is no .devin/skills.

5. The stages to report

JIRA is the thirteenth: the ticket exists and nothing has started. Statuses are running, success, waiting, blocked, failed and idle. This is the same vocabulary the Claude Code plugin derives, so a ticket moved from here sits in the same column as one moved by Claude.

6. Without the agent

Anything that runs in a shell posts the same report with no model involved. A git hook, an npm script, a run configuration, a CI step:

npx -y github:macleodlabs-ai/teamflow-plugin report --issue DAEMON-142 --stage LOCAL_TEST \
  --status success --summary "42 tests, 0 failing"

Same envelope, same transport, same credential. Prefer it wherever the board has to be right whether or not an agent remembered. npx -y github:macleodlabs-ai/teamflow-plugin report --help lists every flag.

7. What this is not

Windsurf / Devin Desktop reports automatically through its own hooks: post_write_code, post_run_command and post_cascade_response. Nothing to remember. Cascade hooks report every write and every finished command, so the board follows a Windsurf session without anyone typing a command. Cascade documents no exit status for post_run_command either, so a write always reports and a command whose outcome is unknown does not.

The hooks see this tool's own calls and nothing else. A test run in another terminal, a merge from the web UI, a deploy from a pipeline: put npx -y github:macleodlabs-ai/teamflow-plugin report in the git hook or the script that already runs on every change, and those land on the board too.

8. What leaves your machine

TeamFlow is a delivery map for Jira, Linear and GitHub issues, run by MacleodLabs. Reports carry derived state only: a ticket key, a stage, a status, a short summary and evidence links. Prompts, diffs, source code, commands and logs are never sent and are rejected before they are charged.

• Every client
• llms.txt
• Capabilities
• The reporting contract, in full