spotlight_line

The spotlight_line resource, and the line resource of the API: a team's workflow, made of its stations, the reactions that move tasks between them, and the repositories its runs work in.

The request body is the line definition. A read returns teamId, key and definition, the definition with every default filled in, beside the common fields. See Built-in lines for the lines Spotlight opens for the first team of a workspace created in the web app.

In Terraform, each element of repositories, stations and reactions is a repository, station or reaction block, and reviews, replayCheck and source are reviews, replay_check and source blocks. Within a station block, judge is a judge block and each element of alerts is an alert block.

ExampleCopy Anchor Link

resource "spotlight_line" "core_delivery" {
  team_id = spotlight_team.core.id
  key     = "delivery"
  name    = "Delivery"
  role    = "delivery"
  runners = ["vpc-internal"]

  repository {
    name  = "acme/api"
    image = "ghcr.io/acme/api-runner:main"
    setup = "npm ci"
  }

  station {
    key       = "backlog"
    name      = "Backlog"
    kind      = "backlog"
    passes_to = ["implementation"]
  }

  station {
    key       = "implementation"
    name      = "Implementation"
    harness   = "claude-code"
    profile   = spotlight_harness_profile.core_careful.key
    prompt    = file("${path.module}/prompts/core/delivery/implementation.md")
    check     = "npm test"
    diffs     = true
    decisions = true
    memories  = true
    tools     = ["${spotlight_integration.core_acme.source}.comment", "pull-request"]
    skills    = [spotlight_skill.core_grafana.key]
    runners   = ["gpu"]
    passes_to = ["code-review"]

    judge {
      rubric = file("${path.module}/judges/core/delivery/implementation.md")
      sample = 0.2
      trust  = 0.6
    }

    alert {
      measure  = "sent_back_rate"
      rises_by = 0.2
      over     = 20
    }
  }

  station {
    key       = "code-review"
    name      = "Code review"
    harness   = "claude-code"
    passes_to = ["implementation"]
    ends      = true
  }

  station {
    key  = "completed"
    name = "Completed"
    kind = "completed"
  }

  reaction {
    happening = "github.checks.failed"
    from      = "implementation"
    to        = "implementation"
  }

  replay_check {
    most_regressions = 0
    ceiling          = 10
    currency         = "USD"
    min_gain         = 0.05
  }

  source {
    repository = "acme/platform"
    path       = "teams/core/delivery.tf"
  }
}

The same line as a request body:

{
  "key": "delivery",
  "name": "Delivery",
  "role": "delivery",
  "runners": ["vpc-internal"],
  "repositories": [
    { "name": "acme/api", "image": "ghcr.io/acme/api-runner:main", "setup": "npm ci" }
  ],
  "stations": [
    { "key": "backlog", "name": "Backlog", "kind": "backlog", "passesTo": ["implementation"] },
    {
      "key": "implementation",
      "name": "Implementation",
      "harness": "claude-code",
      "profile": "careful",
      "prompt": "Implement the task.",
      "check": "npm test",
      "diffs": true,
      "decisions": true,
      "memories": true,
      "tools": ["acme.comment", "pull-request"],
      "skills": ["grafana"],
      "runners": ["gpu"],
      "passesTo": ["code-review"],
      "judge": { "rubric": "Did the run meet the task?", "sample": 0.2, "trust": 0.6 },
      "alerts": [{ "measure": "sent_back_rate", "risesBy": 0.2, "over": 20 }]
    },
    {
      "key": "code-review",
      "name": "Code review",
      "harness": "claude-code",
      "passesTo": ["implementation"],
      "ends": true
    },
    { "key": "completed", "name": "Completed", "kind": "completed" }
  ],
  "reactions": [
    { "happening": "github.checks.failed", "from": "implementation", "to": "implementation" }
  ],
  "replayCheck": { "mostRegressions": 0, "ceiling": 10, "currency": "USD" },
  "source": { "repository": "acme/platform", "path": "teams/core/delivery.tf" }
}

A reviews block, on a line whose role is review:

reviews {
  start   = "opened"
  mention = "@spotlight"
  label   = "spotlight"

  skip {
    spotlight = true
    drafts    = true
    authors   = ["dependabot[bot]", "renovate[bot]"]
  }
}

Line fieldsCopy Anchor Link

Station fieldsCopy Anchor Link

Spotlight checks catalog tools and skills against what the workspace's plan includes when the line is written. It does not check at write time that a harness exists or that a profile, a team skill or an integration tool is there.

Tool namesCopy Anchor Link

See Built-in tools and skills for the built-in and catalog tools, and Agent commands for how an agent calls a tool.

Judge fieldsCopy Anchor Link

A judge has sample, trust, and rubric, claims or both. See Judging for which runs are judged and when scores show.

A judge with claims scores claim by claim: its score is the share of claims met. A rubric beside them is given to the judge with the claims, and needs no scores: line. passShare decides only whether a replayed run passes; see Results. A read returns claims and passShare only when the judge has claims, and rubric only when it has one.

judge {
  claims = [
    "The change adds a test that fails without it.",
    "The change touches only what the task names.",
  ]
  pass_share = 1
  sample     = 0.2
  trust      = 0.6
}

Without claims, the rubric names its scale on its first line that is not blank, or on a line of a front matter block that opens the rubric between two --- lines:

scores is matched without regard to case, with any spaces around the colon. A scores: line further down is not read.

An export writes each rubric to judges/<team>/<line>/<station>.md and reads it with file(). It writes claims in the block, one claim to a line, with pass_share.

The judge is part of the station's config: a run records one SHA-256 of its rubric, claims and pass share together, its rubric version, with sample and trust. A change to any of them changes the config fingerprint, and a change to the rubric, a claim or the pass share starts a new rubric version.

Each is returned with 422 at the path stations[<n>].judge.<field>.

Alert fieldsCopy Anchor Link

In Terraform, risesBy and fallsBy are rises_by and falls_by. An alert sets exactly one of risesBy, fallsBy, above and below; a read returns the others as null.

A station may have any number of alerts, but not two on the same measure with the same kind of threshold: of two alerts that both set risesBy on sent_back_rate, the later one is refused. Alerts are not part of the station's config, so changing them does not change the config fingerprint. Alerts are kept with the line, exported, listed on the Station page, and checked as the station's runs end and settle. See Station alerts.

Each is returned with 422 at the path stations[<n>].alerts[<n>], followed by .<field> where the message names one. Paths and messages use the API's field names, as in risesBy, also for a line written in Terraform.

Repository fieldsCopy Anchor Link

The repositories of one line name at most one distinct image. A read returns repositories sorted by name.

Reaction fieldsCopy Anchor Link

See GitHub events for the happenings GitHub raises. An integration raises its own.

Review policy fieldsCopy Anchor Link

The review policy (reviews) decides which pull requests a review line takes. See Review tasks for how a line is chosen and the task it opens.

Replay check fieldsCopy Anchor Link

The replay check (replayCheck, in Terraform replay_check) sets the threshold a planned change of one of the line's work stations is held to by spotlight replay check. A check reads it from the line as it is applied, never from the plan. A line read through the team's GET /api/teams/{teamId}/lines carries it as replayCheck, and a replay set's page shows it in the ⓘ of its "Checks" panel. See Replay checks API.

Source fieldsCopy Anchor Link

The source (source) names the file that holds this spotlight_line resource. A picked search candidate is opened as a pull request against it.

For Spotlight to edit the station, the file must hold exactly one resource "spotlight_line" with the line's key written as a plain string, and in it exactly one station block with the station's key written the same way. An attribute a search may change that is read from a file must be read as file("${path.module}/<path>"); a plain file("<path>") cannot be followed. See The pull request.

PlacementCopy Anchor Link

A run at a station goes to a runner that carries at least one of the station's runners labels. A station's runners, when set, are the only labels that apply. A station without runners uses the line's. With neither, any runner of the workspace qualifies.

A label is one a runner pool or runner trust gives the runners it admits. A pool's key is not a label. Each entry, trimmed of surrounding whitespace, is shaped as a label is, lowercase words joined by dashes of at most 64 characters, and named once; any other entry is refused.

Each is returned with 422 at the path runners, or stations[<n>].runners for a station.

Where the line's repositories name an image, the runner must also run that image. Where they name none, the runner must run its host's default image. See Host settings for the images a host serves.

Layout rulesCopy Anchor Link

A line's stations are refused unless they follow every rule below.

• A line must have at least one station.
• Each station key must be used once.
• A line must have exactly one backlog station, and it must be first.
• A line must have exactly one completed station, and it must be last.
• The completed station must not pass to any station.
• A station must not pass to itself.
• A station must pass only to work stations.
• A reaction's to and from must be stations on the line.
• A line must not have two reactions with the same happening and from.
• If any station has both check and diffs: true, every repository must have setup.
• A line must name reviews only if its role is review.
• Only a work station may have a judge or alerts. On a backlog the refusal reads Line <line> station <station> is a backlog and has no runs to judge., and on the completed station Line <line> station <station> is the completed station and has no runs to judge.; for alerts both end and has no runs to alert on. <line> and <station> are keys. The refusal is returned at stations[<n>].judge or stations[<n>].alerts.

Reserved station keysCopy Anchor Link

Update and deleteCopy Anchor Link

A second line claiming a role another line of the team holds is refused with 422 on role.