Using coding agents with Windshift
Give coding agents a structured place to plan, create, update, and explain work — with the right interface for the job.
A coding agent can write a useful plan in chat. The problem starts after that. Someone still has to copy the plan into the backlog, split it into work items, attach the relevant spec, and update status as the work moves.
Windshift gives agents a better place to act. An agent can read workspace documentation, create work items, add comments, move items through valid workflow transitions, create pages, and link pages back to the work they describe.
There are two ways to give an agent that access:
Start with the workspace context
Agents need the same operating details that a teammate would need. They need to know the workspace key, the item types, the statuses, and the workflow transitions. They also need to know where the team keeps long-form documentation.
`ws init` writes that context into `WINDSHIFT.md` in the project root. Editor agents such as Claude Code, Cursor, Codex, and Copilot can read it before running commands.
Use MCP when the agent speaks tools
Windshift also includes an optional MCP server. Enable it with the `--mcp` server flag or `MCP_ENABLED=true`, then point an MCP client at your Windshift instance's `/mcp` endpoint.
```bash
Use the CLI when the work lives in the terminal
The CLI is still the better fit when the agent is operating inside a repository. It can combine Windshift operations with local files, `jq`, tests, Git, build commands, and editor-specific slash commands.
For example, an agent can create a spec file locally, run tests, update the spec based on the test result, publish the Markdown as a Windshift page, and link it to the work item. That workflow is natural in a shell and easy for a human to repeat.
Ask the agent to create an Initiative
For larger work, the useful output is a hierarchy. The Initiative names the outcome. Child items break it into work that people can assign, review, and finish.
The exact item type IDs come from `WINDSHIFT.md` or `ws item-type ls`.
Create the page that explains the work
An Initiative description is useful for a short summary. A spec page is better for the longer record: goals, constraints, prior decisions, open questions, rollout notes, and links to existing documentation.
The agent can create that page from Markdown and link it to the Initiative.
Goal
Help new users create their first workspace and first work item without a support touch.
Documentation reviewed
Work items to create
Open questions
EOF
page_id=$(ws page create \
Pull from existing pages first
A good agent workflow starts with reading, not writing. Before creating a new Initiative, ask the agent to inspect relevant workspace pages and use them as input.
For example:
Keep the record current
After the initial breakdown, the agent can keep the Windshift record up to date while the developer works.
List assigned work:
Let transitions trigger the next step
This gets more powerful when the workspace uses Windshift Actions. Actions can run automations based on work item events, including status transitions. That means an agent does not have to remember every downstream step. It can move the item through the correct workflow transition, and Windshift can trigger the next part of the process.
For example, when an item moves to `review`, an Action can start the review flow immediately: request approval, notify the right channel, create a review checklist, call an internal webhook, or add the reviewer instructions as a comment. The agent updates the work item. Windshift handles the repeatable handoff.
Choosing between MCP and CLI
There is no universal default. The better choice depends on where the agent is working.
Use **MCP** when:
Keep permissions narrow
Agents should have enough access to do the job and no more. Windshift's CLI flow supports scoped tokens, and normal Windshift permissions still apply. The MCP server requires a token with `mcp:access`; because that scope exposes both read and write tools, pair it with a user or agent account whose workspace roles are deliberately limited.
Page ACLs are enforced. Workflow transitions are validated. The agent reads item types and statuses from the workspace instead of inventing them.
A connected result
The practical value is simple. A team can ask an agent to plan work, and the result can land directly in Windshift as structured, reviewable work.
The Initiative holds the outcome. Child items hold the tasks. The page holds the explanation. Links connect them, so the next person or agent can see what was decided and why.