Configuration

GitHub Labels

Label a GitHub issue with one of the agent labels below and ShipCode will route it to the corresponding executor. Source of truth: packages/agents/src/github/model-router.ts. Unknown or missing labels fall back to shipcode:agent:claude; multi-agent-label issues return an error.

Workflow State

ShipCode writes transient shipcode:pipeline:* labels for agent-loop debugging, but board-level workflow state belongs in a typed GitHub Projects v2 Status field, such as Backlog, In Progress, Human Review, Done, and Deferred.

WORKFLOW.md

Repos can override the prompt for every pipeline phase and tune agent policy (concurrency, max turns, execute fan-out) with a WORKFLOW.md file at .shipcode/WORKFLOW.md or the repo root. See WORKFLOW.md for the full format, template context, and live-reload behavior.

Repo Setup Contract

Repos can declare fresh-worktree setup in .shipcode/setup.json. This file is read directly from the repo, so desktop and CLI use the same contract.

{
  "version": 1,
  "envFiles": [
    { "source": ".env.local", "required": true }
  ],
  "setupCommands": [
    "<repo-specific install command>"
  ],
  "verifyCommands": [
    "<repo-specific scoped verify command>"
  ],
  "runtimeQa": {
    "server": {
      "command": "<repo-specific dev server command using $PORT>",
      "readinessUrl": "http://127.0.0.1:$PORT",
      "startupTimeoutMs": 60000,
      "portEnvVar": "PORT"
    },
    "testCommands": [
      "<repo-specific runtime test command>"
    ],
    "discoverAgentTests": true
  },
  "setupBeforeVerify": false,
  "testingContext": "Explain the repo's test runner, scope rules, and expensive commands to avoid."
}

• envFiles: copied from the repo root into the worktree before execution. Use target to write to a different relative path inside the worktree.
• setupCommands: run inside the worktree before the execute phase starts.
• verifyCommands: run inside the worktree after execute and before the verifier model runs.
• runtimeQa.server: optional dev server command, readiness URL, startup timeout, and port environment variable used for browser/runtime QA.
• runtimeQa.testCommands: optional browser, E2E, or runtime checks run against the feature worktree.
• runtimeQa.discoverAgentTests: when true, generated agent QA tests can be discovered and run during runtime QA.
• setupBeforeVerify: when true, reruns setupCommands before verifyCommands.
• testingContext: repo-owned testing guidance injected into the execute prompt.

If the file is missing, ShipCode falls back to the existing per-install settings (testCommand, testingContext) and current behavior.

When a PRD contains a ## QA State section with visual assertions, ShipCode can generate a temporary Playwright visual QA test during verification. The generated artifacts live under .shipcode/qa-artifacts/ in the worktree and are excluded from commits.