# Coding Agents

The `ws` CLI integrates with coding agents like Claude Code, Cursor, Windsurf, and Copilot. Once configured, agents can manage tasks, move work items through workflows, and run tests without leaving your editor.

## Quick Start

Run `ws init` in your project root:

```bash
ws init
```

This command:

1. Queries your workspace for item types, statuses, and workflow configuration
2. Generates a `WINDSHIFT.md` file with commands reference and workspace-specific config
3. Updates `CLAUDE.md` or `AGENTS.md` (if they exist) to include a reference to `WINDSHIFT.md`
4. Creates or updates `ws.toml` with workspace settings and auto-generated status aliases

You need a working `ws.toml` config before running `ws init`. See [CLI Installation](/docs/04-cli/01-installation) for initial setup.

### Flags

| Flag | Description |
|------|-------------|
| `--workspace` | Override the default workspace |
| `--config` | Path to a specific config file |

## What Gets Generated

`ws init` creates a `WINDSHIFT.md` file in your project root. This file is what agents read to understand your workspace and available commands.

The generated file includes:

| Section | Contents |
|---------|----------|
| Quick Commands | Common `ws` commands for task management |
| Status Aliases | Shorthand names mapped to your workspace statuses |
| Item Types | Available types (Task, Bug, Story, etc.) in your workspace |
| Statuses | All statuses and their workflow order |
| Workflow Transitions | Valid status transitions for each item type |
| Test Management | Commands for listing and viewing test cases |
| Configuration | Current workspace key and server info |

Re-run `ws init` after changing workspace configuration (adding statuses, item types, or workflow transitions) to keep the file in sync.

## Claude Code

If a `CLAUDE.md` file exists in your project root, `ws init` automatically adds a reference to `WINDSHIFT.md` so Claude Code picks it up.

### Allow the ws Tool

Add `ws` to your allowed tools in `.claude/settings.local.json`:

```json
{
  "permissions": {
    "allow": [
      "Bash(ws *)"
    ]
  }
}
```

This lets Claude Code run `ws` commands without prompting for approval each time.

### What Agents Can Do

With the integration configured, you can ask your agent to:

```
"Check what tasks are assigned to me"
→ ws task mine

"Move ENG-142 to in progress"
→ ws task move ENG-142 progress

"Create a bug for the auth redirect issue"
→ ws task create --type Bug --title "Auth redirect fails on logout"

"What's the status of ENG-138?"
→ ws task mine --output json | jq '.[] | select(.key == "ENG-138")'
```

The agent reads `WINDSHIFT.md` to know which statuses, item types, and transitions are available in your workspace.

### Custom Slash Commands

Claude Code supports custom slash commands via `.claude/commands/`. You can create shortcuts for common `ws` operations that your whole team can use.

Create a file at `.claude/commands/add-task.md`:

```markdown
Create a new task in the current Windshift workspace.

Use the ws CLI to create a task with the provided arguments:
- Title: $ARGUMENTS

Steps:
1. Run `ws task create --title "$ARGUMENTS"`
2. Show the created task key and status
```

Now anyone on the team can type `/add-task Fix the login redirect bug` in Claude Code to create a task without remembering the exact CLI syntax.

More examples:

**.claude/commands/my-tasks.md** - list assigned tasks:

```markdown
List my current tasks from Windshift.

Run `ws task mine` and summarize the results. Group by status.
```

**.claude/commands/start-task.md** - pick up a task:

```markdown
Start working on a Windshift task.

1. Run `ws task move $ARGUMENTS progress` to move the task to in progress
2. Read the task details and summarize what needs to be done
```

Commit the `.claude/commands/` directory to your repo so the whole team has access to the same commands.

## Other Agents

For agents that use `AGENTS.md` (like Cursor or Windsurf), `ws init` updates that file automatically - same as with `CLAUDE.md`.

For agents that use a different config file, add a reference to `WINDSHIFT.md` manually. The pattern is the same regardless of agent: point the agent's config to `WINDSHIFT.md` so it can read your workspace commands and configuration.

Example for a generic agent config:

```
See WINDSHIFT.md for Windshift CLI commands and workspace configuration.
```

## Status Aliases

`ws init` auto-generates aliases so agents can use consistent commands regardless of your actual workspace status names. The default aliases:

| Alias | Typical Mapping |
|-------|-----------------|
| `todo` | Open / To Do |
| `progress` | In Progress |
| `review` | To Review / In Review |
| `done` | Done / Closed |
| `blocked` | Blocked |

These are saved in `ws.toml` and can be customized:

```toml
[status_aliases]
done = "Ready for QA"
progress = "Working"
review = "Peer Review"
todo = "Backlog"
blocked = "On Hold"
```

Agents use aliases in commands like `ws task move ENG-142 done` - the CLI resolves the alias to the actual status name. See [CLI Configuration](/docs/04-cli/02-configuration) for more on status aliases.

## Example Workflow

A typical session with a coding agent:

```bash
# Developer asks the agent to check their tasks
ws task mine
# KEY        TITLE                    STATUS        ASSIGNEE
# ENG-142    Fix auth redirect        Open          alice
# ENG-155    Add rate limiting         Open          alice

# Agent picks up a task and moves it to in progress
ws task move ENG-142 progress

# Developer works on the fix with the agent's help...

# Agent moves the task to review when done
ws task move ENG-142 review

# Agent creates a follow-up task if needed
ws task create --type Task --title "Add auth redirect tests" --status todo
```

The agent handles the workflow transitions while the developer stays focused on the code.