> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ticket-rs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Windsurf

> Set up tk with Windsurf for AI-powered issue tracking

Use tk with [Windsurf](https://codeium.com/windsurf) to manage issues directly from your editor with the power of Cascade AI.

***

## What is Windsurf?

[Windsurf](https://codeium.com/windsurf) is an AI-powered IDE from Codeium featuring **Cascade**, an agentic AI assistant that can write, run, and refactor code with full context awareness. Unlike traditional code editors, Windsurf is purpose-built for AI collaboration.

***

## Project Rules

Create a rules file in `.windsurf/rules/tk.md` to give Cascade context about tk:

````markdown theme={null}
# Issue Tracking with tk

This project uses **tk (ticket-rs)** for dependency-aware issue tracking.
Issues are stored as Markdown files in `.tickets/`.

## Quick Commands

- `tk ready` - Find work with no blockers
- `tk triage` - AI-powered recommendations
- `tk create "Title" -t task -p 2` - Create issue
- `tk show <id>` - View issue details
- `tk close <id>` - Complete work
- `tk dep add <blocked> <blocker>` - Add dependency
- `tk dep tree <id>` - Visualize dependencies

## Issue Format

Issues are Markdown files with YAML frontmatter:

```markdown
---
status: open
type: feature
priority: 1
deps: [tk-abc123]
labels: [backend]
---
# Issue Title

Description here.
```

## Status Values

- `open` - Ready to be worked on
- `in_progress` - Currently being worked on
- `blocked` - Waiting on dependencies
- `closed` - Completed

## Priority Levels

- P0 (0) - Critical
- P1 (1) - High
- P2 (2) - Medium (default)
- P3 (3) - Low
- P4 (4) - Lowest

## Graph Analytics

tk provides PageRank-based priority scoring, betweenness centrality for bottleneck detection, and critical path analysis. Use `tk insights` for detailed metrics.

## Workflow

1. Start session: `tk triage` for AI recommendations
2. Find work: `tk ready` for unblocked issues
3. Create issues: `tk create "Title" -t type -p priority`
4. Manage deps: `tk dep add <blocked> <blocker>`
5. Complete work: `tk close <id>`
````

<Tip>
  Rules in Windsurf are limited to 6000 characters per file. Keep your tk rules
  concise and focused on the most important commands.
</Tip>

***

## Rule Activation

Windsurf supports different rule activation modes:

<CardGroup cols={3}>
  <Card title="Always On" icon="circle-check">
    Rule applies to every Cascade interaction automatically
  </Card>

  <Card title="Manual" icon="hand-pointer">
    Activate by @mentioning the rule in Cascade chat
  </Card>

  <Card title="Model Decision" icon="brain">
    Cascade decides when to apply based on context
  </Card>
</CardGroup>

For tk rules, **"Always On"** mode works best since issue tracking is project-wide context.

***

## MCP Integration

Install the [`ticket-mcp`](https://pypi.org/project/ticket-mcp/) [MCP](https://modelcontextprotocol.io) server to give Cascade direct access to your issues:

### Installation

Add to your Windsurf settings (`~/.windsurf/settings.json` or workspace `.windsurf/settings.json`):

```json theme={null}
{
  "mcpServers": {
    "ticket-mcp": {
      "command": "uvx",
      "args": ["ticket-mcp"],
      "env": {}
    }
  }
}
```

<Accordion title="Requirements">
  **uv** installed via: `curl -LsSf https://astral.sh/uv/install.sh | sh`

  **Python** version 3.10 or higher (installed automatically by uv)
</Accordion>

### Verify Installation

Restart Windsurf and check that `ticket-mcp` appears in the MCP section of Windsurf settings. Cascade will now have access to:

* `tk triage` - AI recommendations
* `tk ready` - Unblocked issues
* `tk create` - Create issues
* `tk show` - View issue details
* `tk update` - Modify issues
* `tk close` - Complete work
* `tk dep tree` - Dependency visualization
* And all other tk commands

***

## Workflow Tips

### Starting a Session

Ask Cascade: *"Run tk triage and show me what I should work on today"*

Cascade will execute `tk triage` and present AI-powered recommendations with context.

### Creating Issues

Ask Cascade: *"Create a high-priority bug for the login timeout issue"*

Cascade will run:

```bash theme={null}
tk create "Fix login timeout" -t bug -p 1
```

### Closing Work

Ask Cascade: *"Close tk-abc123, I just fixed it"*

Cascade will mark the issue as completed and can optionally show what's now unblocked.

### Dependency Management

Ask Cascade: *"Show me the dependency tree for tk-xyz789"*

Cascade will run `tk dep tree tk-xyz789` and visualize the relationships.

### Project Health

Ask Cascade: *"Run tk doctor and fix any issues"*

Cascade will diagnose problems and suggest fixes.

***

## Cascade-Specific Features

Windsurf's Cascade AI can leverage tk in powerful ways:

<AccordionGroup>
  <Accordion title="Context-Aware Issue Creation">
    Cascade can analyze your current code changes and automatically create appropriately scoped issues with correct types and priorities.
  </Accordion>

  <Accordion title="Dependency Inference">
    When you ask Cascade to create a feature, it can analyze the codebase and
    automatically add `deps` for prerequisite issues.
  </Accordion>

  <Accordion title="Workflow Automation">
    Combine tk commands with Cascade workflows to automate common patterns like
    create-branch-implement-test-close workflows.
  </Accordion>

  <Accordion title="Natural Language Queries">
    Ask complex questions like *"What's blocking the authentication epic?"* and Cascade will run the right tk commands to answer.
  </Accordion>
</AccordionGroup>

***

## Global vs Workspace Rules

Windsurf supports both global and workspace-level rules:

### Workspace Rules (Project-Specific)

Location: `.windsurf/rules/tk.md` in your project

**Best for:** Project-specific tk configuration, custom workflows

### Global Rules (All Projects)

Location varies by OS:

* **macOS:** `~/Library/Application Support/Windsurf/User/globalStorage/rules/`
* **Linux:** `~/.config/Windsurf/User/globalStorage/rules/`
* **Windows:** `%APPDATA%\Windsurf\User\globalStorage\rules\`

**Best for:** tk commands you use across all projects

<Info>
  Total combined characters for global + workspace rules cannot exceed 12,000.
  Keep tk rules focused and concise.
</Info>

***

## Performance

tk's analytics cache ensures instant performance:

* **Cache hits:** \<10ms (instant)
* **Cache rebuilds:** \<20ms (imperceptible)
* **Auto-invalidation:** Updates when files change

This means Cascade gets near-instant responses from `tk triage`, `tk ready`, and other analytics commands.

***

## Example Cascade Interactions

### Morning Triage

> **You:** "What should I work on today?"
>
> **Cascade:** Runs `tk triage`, explains top recommendations with reasoning

### Feature Planning

> **You:** "I want to add OAuth authentication. What needs to happen?"
>
> **Cascade:** Creates epic, breaks down into tasks with dependencies, runs `tk dep tree` to visualize

### Dependency Check

> **You:** "What's blocking tk-abc123?"
>
> **Cascade:** Runs `tk show tk-abc123`, lists blocking issues, offers to show their status

### Health Check

> **You:** "How healthy is this project?"
>
> **Cascade:** Runs `tk insights`, explains PageRank scores, betweenness centrality, critical path

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Cascade doesn't recognize tk commands">
    Make sure the `.windsurf/rules/tk.md` file exists and is set to "Always On" mode in Windsurf settings.
  </Accordion>

  <Accordion title="MCP server not connecting">
    Check that `uvx` is in your PATH and restart Windsurf. Verify in Windsurf
    settings that `ticket-mcp` shows as active.
  </Accordion>

  <Accordion title="Rules not applying">
    Check file size - each rule file is limited to 6000 characters. Split into
    multiple files if needed.
  </Accordion>

  <Accordion title="Slow tk commands">
    Enable caching with `tk cache info` to verify cache is working. Cache should show recent hits.
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="CLI Reference" icon="terminal" href="/cli-reference/commands">
    Complete tk command documentation
  </Card>

  <Card title="MCP Server" icon="plug" href="/integrations/mcp">
    Deep dive into MCP server capabilities
  </Card>

  <Card title="Graph Analytics" icon="chart-network" href="/concepts/graph-analytics">
    Learn about PageRank and dependency analysis
  </Card>

  <Card title="Windsurf Docs" icon="book" href="https://docs.windsurf.com">
    Official Windsurf documentation
  </Card>
</CardGroup>

***

## Sources

* [Windsurf Documentation](https://docs.windsurf.com)
* [Windsurf Rules Guide](https://dev.to/yardenporat/codium-windsurf-ide-rules-file-1hn9)
* [Awesome Windsurfrules](https://github.com/SchneiderSam/awesome-windsurfrules)
* [Windsurf Rules Directory](https://windsurf.com/editor/directory)
* [MCP Documentation](https://modelcontextprotocol.io)