Skip to main content
Glama
Sign In
bantamkit

bantamkit

by Ink01101011
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Shift work: clock in

shiftwork_clock_in

Validates the checkpoint and returns one ready unit’s brief to hand verbatim to the agent you spawn; call once per unit before spawning.

Instructions

Shift-work clock-in: validate the checkpoint against the checkpoint schema and return the brief of ONE unit — {unit, role, invariants, handoff, do_not, files} — to hand to the agent you spawn, verbatim. Call it once per unit, right before spawning; use shiftwork_plan first to see the ready batch when several units are to run at once, and shiftwork_clock_out, not this tool, when a unit finishes. The unit briefed is plan.cursor, or unit_id when given; either way it must be in shiftwork_plan's ready — a done or dropped cursor, a cursor whose dependencies have not run, or a unit_id naming no unit answers {"result": "error", "reason": "unit is not ready; ready is <a, b>"}, and the batch view's own refusals (cycle, unknown dependency, unreadable checkpoint) pass through verbatim. A ready unit whose touches shares a path with a unit briefed and not yet clocked out is refused too, before any brief: unit <id> touches <path>, which <other> holds until its clock-out. A checkpoint whose reviews break review independence is refused with shiftwork_plan's sentence. With job.budget declared, a brief that does not fit is refused: budget <dim> spent: <n> of <limit>; raise job.budget or stop the job. The other outcomes, never exceptions: escalate when handoff.open_questions is non-empty (stop and ask the user) or when the cursor names no unit, success when every unit is done or dropped, error when the checkpoint fails validation. It never moves plan.cursor; clock_out does. What it WRITES: on result=brief, and only then, one line {event: brief, ts, unit, role} appended to .log.jsonl — best-effort, so a log it cannot write costs the brief nothing. That line is what later lets clock_out accept the unit while the cursor is elsewhere and sets briefed on its accounting line. The checkpoint file itself is never modified. See docs/shiftwork.md.

Input Schema

NameRequiredDescriptionDefault
unit_idNoThe unit to brief instead of plan.cursor; it must be in shiftwork_plan's `ready` for this checkpoint. Omit it, or pass null, to brief the cursor unit.
checkpointYesPath to the shift-work checkpoint JSON file (by convention .shiftwork/checkpoint.json in the repo the job works on), absolute or relative to the server's working directory. The same file shiftwork_plan, shiftwork_clock_in and shiftwork_clock_out take; it must validate against assets/schemas/shiftwork-checkpoint.json.

Output Schema

NameRequiredDescriptionDefault
roleNoThe unit's role, the key job.roles may bind models to.
unitNoThe plan.units entry briefed: id, role, status, depends_on and its own fields.
filesNostate.artifacts: the files the job has produced so far.
do_notNohandoff.do_not: near-mistakes past sessions made.
reasonNoWith result `escalate`, `success` or `error`: one sentence saying why.
resultYes`brief` (the unit is yours to spawn), `escalate` (stop and ask: see `reason` and `open_questions`), `success` (every unit done or dropped), or `error` with `reason`.
handoffNoThe checkpoint's handoff block: next_action, open_questions, do_not, notes.
upstreamNoOne {unit, title, status, last} per depends_on id, in depends_on order: last is that unit's newest attempt (status, outcome, notes?, produced?) or null. Always present with a brief.
agreementsNojob.agreements: the working agreements adopted so far through clock_out, carried on every brief; [] when none.
invariantsNojob.constraints: what every unit must keep true.
open_questionsNoWith result `escalate`: the questions the orchestrator must put to the user before any unit runs. An irreversible unit whose verb job.authorized does not grant also escalates (#225), with no open_questions.
prior_attemptsNoThis unit's own attempts, oldest first, at most 3; [] when none. A unit clocked out todo and briefed again is a rework, and this is what it found.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed6 schema fields changedv0.38.0
    • addedOutput schema / properties / agreements
      Added value: +{
+  "description": "job.agreements: the working agreements adopted so far through clock_out, carried on every brief; [] when none.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
    • changedOutput schema / properties / open_questions / description
      Previous value: -"With result `escalate`: the questions the orchestrator must put to the user before any unit runs."New value: +"With result `escalate`: the questions the orchestrator must put to the user before any unit runs. An irreversible unit whose verb job.authorized does not grant also escalates (#225), with no open_questions."
    • addedOutput schema / properties / open_questions / items / anyOf
      Added value: +[
+  {
+    "description": "A decision question.",
+    "type": "string"
+  },
+  {
+    "description": "A question with a kind (#225): {q, kind: relay|decision, probe}. Escalation happens only for a decision or a relay whose probe did not exit 0; an answered relay is logged as a `resolved` ledger event.",
+    "type": "object"
+  }
+]
    • removedOutput schema / properties / open_questions / items / type
      Removed value: -"string"
    • addedOutput schema / properties / prior_attempts
      Added value: +{
+  "description": "This unit's own attempts, oldest first, at most 3; [] when none. A unit clocked out todo and briefed again is a rework, and this is what it found.",
+  "type": "array"
+}
    • addedOutput schema / properties / upstream
      Added value: +{
+  "description": "One {unit, title, status, last} per depends_on id, in depends_on order: last is that unit's newest attempt (status, outcome, notes?, produced?) or null. Always present with a brief.",
+  "type": "array"
+}
  2. Changed4 schema fields changedv0.36.2
    • addedInput schema / properties / checkpoint / description
      Added value: +"Path to the shift-work checkpoint JSON file (by convention .shiftwork/checkpoint.json in the repo the job works on), absolute or relative to the server's working directory. The same file shiftwork_plan, shiftwork_clock_in and shiftwork_clock_out take; it must validate against assets/schemas/shiftwork-checkpoint.json."
    • addedInput schema / properties / unit_id / description
      Added value: +"The unit to brief instead of plan.cursor; it must be in shiftwork_plan's `ready` for this checkpoint. Omit it, or pass null, to brief the cursor unit."
    • addedOutput schema / properties
      Added value: +{
+  "do_not": {
+    "description": "handoff.do_not: near-mistakes past sessions made.",
+    "items": {
+      "type": "string"
+    },
+    "type": "array"
+  },
+  "files": {
+    "description": "state.artifacts: the files the job has produced so far.",
+    "type": "array"
+  },
+  "handoff": {
+    "description": "The checkpoint's handoff block: next_action, open_questions, do_not, notes.",
+    "type": "object"
+  },
+  "invariants": {
+    "description": "job.constraints: what every unit must keep true.",
+    "items": {
+      "type": "string"
+    },
+    "type": "array"
+  },
+  "open_questions": {
+    "description": "With result `escalate`: the questions the orchestrator must put to the user before any unit runs.",
+    "items": {
+      "type": "string"
+    },
+    "type": "array"
+  },
+  "reason": {
+    "description": "With result `escalate`, `success` or `error`: one sentence saying why.",
+    "type": "string"
+  },
+  "result": {
+    "description": "`brief` (the unit is yours to spawn), `escalate` (stop and ask: see `reason` and `open_questions`), `success` (every unit done or dropped), or `error` with `reason`.",
+    "type": "string"
+  },
+  "role": {
+    "description": "The unit's role, the key job.roles may bind models to.",
+    "type": "string"
+  },
+  "unit": {
+    "description": "The plan.units entry briefed: id, role, status, depends_on and its own fields.",
+    "type": "object"
+  }
+}
    • addedOutput schema / required
      Added value: +[
+  "result"
+]
  3. First observedv0.36.0

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint=false and destructiveHint=false, and the description explains exactly why: 'on result=brief, and only then, one line {event: brief, ts, unit, role} appended to <checkpoint>.log.jsonl — best-effort' plus 'The checkpoint file itself is never modified' and 'It never moves plan.cursor'. That is genuine context beyond the annotations, including failure tolerance of the log write. It stops short of describing concurrency behavior or ordering guarantees across parallel clock-ins.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded well: purpose and return shape land in the first sentence. But the body collapses into a dense run-on enumerating refusal strings and outcome names ('escalate', 'success', 'error') in a single paragraph, mixing guidance, error catalogs, and write semantics. It is informative rather than wasteful, but a bulleted outcome list would carry the same content with far less parsing cost.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a stateful tool that reads a checkpoint and appends a log, the description covers preconditions, all outcome variants, side effects, and non-effects (cursor untouched, checkpoint unmodified), and it points at docs/shiftwork.md for depth. Even though an output schema exists, the inline brief and refusal shapes make the contract unambiguous.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds resolution semantics the schema only implies: 'The unit briefed is plan.cursor, or `unit_id` when given; either way it must be in shiftwork_plan's `ready`', including what happens for a done/dropped cursor or a dependent cursor. The `checkpoint` parameter adds nothing beyond the schema, but the unit selection logic is meaningfully elaborated.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource plus the exact payload: 'return the brief of ONE unit — {unit, role, invariants, handoff, do_not, files} — to hand to the agent you spawn, verbatim.' It then names the two siblings it must not be confused with (shiftwork_plan for the `ready` batch, shiftwork_clock_out for unit completion), so an agent can route correctly without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit timing ('Call it once per unit, right before spawning'), an explicit alternative for the multi-unit case ('use shiftwork_plan first to see the `ready` batch when several units are to run at once'), and an explicit exclusion ('shiftwork_clock_out, not this tool, when a unit finishes'). It also states the precondition that the target unit must appear in shiftwork_plan's `ready`.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools