Documentation
Guides
Ship to AI Tools

Ship to AI Tools

Once SpecWright generates your implementation tasks, you can send them directly to your AI coding tool. Each shipped prompt includes the full specification context — requirements, design decisions, architecture, acceptance criteria — so the AI tool knows exactly what to build.

No API keys required. SpecWright doesn't call AI APIs directly. It works with whatever AI tool you already have installed and licensed.

Supported tools

ToolExecution modeHow it works
CursorHeadlessRuns via CLI — streams progress in real time
Claude CodeHeadlessRuns via CLI with session resumption — can continue where it left off
Codex CLIHeadlessCLI-only execution, no IDE needed
Gemini CLIHeadlessCLI-only execution, no IDE needed
GitHub CopilotKeyboard automationOpens VS Code chat, pastes the prompt
WindsurfKeyboard automationOpens Windsurf chat, pastes the prompt

Headless mode is the preferred execution method. SpecWright runs the AI tool's CLI directly, streams progress logs to the Web UI in real time, and captures results automatically. The process has a 5-minute timeout for safety.

Keyboard automation is the fallback for tools without CLI/headless support. SpecWright copies the prompt to your clipboard, activates the tool's window, opens a new chat, and pastes. The tool needs to be running already.

How to ship an issue

  1. Open a project and navigate to the Issues view (or the global Issues board)
  2. Click an issue to open its detail modal
  3. Click Ship
  4. The Ship Modal opens and:
    • Generates the full implementation prompt
    • Sends it to your selected AI tool
    • Shows streaming progress logs (for headless tools)
    • Reports success or failure

You can override the AI tool for a single ship action using the dropdown in the Ship Modal — useful if you want to try a different tool for one specific issue.

What the prompt contains

Each shipped prompt includes:

Issue context:

  • Title and description
  • Screens affected (from screens.json)
  • Key architecture decisions (from technology choices)
  • Acceptance criteria with IDs and descriptions
  • Technical implementation details
  • Testing strategy (automated tests + manual verification steps)
  • Human-in-the-loop verification steps
  • Dependencies on other issues

Specification references:

  • Links to the PRD (@path/to/prd.md)
  • Links to the technical specification
  • Links to technology choices
  • Links to the design brief and wireframes

Git workflow (if enabled):

  • Branch creation instructions based on your git strategy
  • Commit message format
  • Merge instructions

Status update instructions:

  • Tells the AI tool to update the issue status from "pending" to "in-review" in issues.json when work begins

Refinement

After shipping, if the result isn't right, you can refine the AI's output using the Refinement Panel:

  1. Open the document or issue in the Web UI
  2. Click the refinement panel
  3. Type feedback explaining what to change
  4. Optionally upload up to 5 reference images (mockups, screenshots, design examples)
  5. Submit — the AI revises based on your feedback with streaming progress

For Claude Code, SpecWright supports session resumption — it can continue the same session rather than starting fresh, which preserves context from the previous generation.

CLI shipping

You can also ship from the command line:

specwright ship

This opens the issues board in the Web UI where you can ship any issue. For headless tools (Codex, Gemini CLI), this is the primary workflow.

Playbook context

If you've generated a Playbook, its standards are automatically included in shipped prompts. This means the AI tool follows your project's naming conventions, folder structure, code patterns, and architectural decisions.

What's next?

Using the Web UILinear Integration