Declare the user story or test case a code change is for

spec.start_workChanges dataCreates, updates or deletes something in your workspace.

What it does

Records that you are about to change code for one user story or test case on this branch, so the edit hooks let you work and every commit can be traced back to it. ref is a user story id (from feature.list type=user-story or userstory.create) or a test case id / caseId such as "TC-0042". Features and sub-features are rejected: pick one of their user stories. When the workspace requires acceptance criteria, a story with no test cases is rejected too: add them first (ac-to-testcase prompt, case.create_batch). When the workspace requires review, stories and test cases you created over MCP are rejected until a person reviews them in the web app; you cannot review them yourself, so tell the user what to review and wait. Starting new work closes the previous item on the same branch. Returns workItem and trailerLine: put that line at the end of every commit message for this work.

Ask your agent

You don’t call spec.start_work yourself. Say something like this to Claude Code, Cursor or another MCP-connected agent:

  • “Start work on the "pay with saved card" story before touching the checkout code”
  • “I am fixing the bug covered by TC-0042, register that with Test Maze”

Inputs

NameTypeDescription
ref
required
stringUser story id, or test case id / caseId, that this change implements or fixes.
branch
required
stringCurrent git branch, from git rev-parse --abbrev-ref HEAD in the repository root.
summary
optional
stringOne or two sentences on what you are about to change and why.

The MCP call

What the agent’s MCP client sends (placeholders in angle brackets):

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "spec.start_work",
    "arguments": {
      "ref": "<ref>",
      "branch": "<branch>"
    }
  }
}

Connect your agent

npx -y @testmaze/mcp init tmt_xxx
claude mcp add tm --scope project -- npx -y @testmaze/mcp

Create the token in your Test Maze workspace under Settings → MCP. Setup for Cursor, Cline, Gemini CLI and Codex CLI is shown there too.