# Work scope

The scope of work an agent proposes before it starts, and before any money is spent: what it commits to (numbered, each with how it will be checked), what is not included, what it needs from the person, and the estimate. The app adds where the work will be checked (`environment`), a `diagram`, a `limit` (its MoneyInput, the most the agent may spend) and `actions` (its agree-and-start dialog's trigger).

It is the agent's proposal and says so: "Proposed by" names the agent the app gives, and "Nothing here is agreed until you agree to it." is always drawn; nothing in it is pre-agreed or pre-selected, and agreeing is the app's own action. A check is planned, in future words ("Will be checked by running it"), never green. The estimate is always under the "Estimate" heading, with its note and how far it could be out; with no estimate it says so and why. The agent's words are drawn as text, never as HTML or a link.

Sizes: `compact` for a card in a thread (smaller type and spacing, each check on the commitment's line, no diagram); `full` for a page or a reader (the diagram drawn under the estimate).

Delta mode, for a later round (`delta`): each item says how it changed against the round before, in words ("Added", "Changed" with what it was, "Unchanged"), unchanged items are collapsed behind "Show N unchanged" in each list, and commitments from earlier rounds that weren't met (`change: "unmet"`) are listed under "Still not met" after the commitments, numbered on from them (after three commitments, the first is 4), so no two numbers on the scope are the same. Out of delta mode, `change` is ignored.

An empty not-included or needed-from-you list says there is nothing listed, so an empty list isn't read as "everything is included"; leave the prop out to leave the section out.

- Registry name: `work-scope` (`@candor/work-scope`)
- Tier: Pro. Installing it needs a Pro, Premium or Team licence key: the person runs `npx candor-ui key <key>` themselves; never ask for the key in chat or write it to a file.
- Docs: https://candor.themethodic.com/docs/work-scope

## Install

```bash
npx candor-ui@4 add work-scope
```

Run `npx candor-ui@latest init` once first (https://candor.themethodic.com/get-started.md). Without the CLI: `npx shadcn@latest add @candor/work-scope`.
It brings in: agent-avatar, bidi, button, chat, heading-level, heading-scope, locale, tokens, utils.
npm packages: lucide-react@^1.67.0.

## Example

```tsx
"use client"

import { WorkScope, type WorkScopeCommitment } from "@/components/candor/work-scope"
import { Button } from "@/components/candor/ui/button"
import { formatMoney } from "@/lib/candor/ops"
import { useFormat } from "@/components/candor/locale"

const builder = { id: "builder", name: "Build agent", role: "builder" }

// The app's kinds of check and their words; WorkScope draws them as "Will be checked by running it".
const running = { kind: "run", label: "by running it" }
const test = { kind: "test", label: "by a test" }
const reading = { kind: "read", label: "by reading it" }

const commitments: WorkScopeCommitment[] = [
  { id: "c1", text: "Import the supplier file every night and flag rows that don't match.", check: running },
  { id: "c2", text: "Keep the totals equal to last month's report for the same rows.", check: test },
  { id: "c3", text: "Write a one-page note on how to rerun the import by hand.", check: reading },
]

const round2: WorkScopeCommitment[] = [
  { ...commitments[0]!, change: "unchanged" },
  { ...commitments[1]!, text: "Keep the totals equal to last month's report, rounding to the cent.", change: "changed", from: commitments[1]!.text },
  { id: "c4", text: "Email the flagged rows to the supplier contact.", check: running, change: "added" },
  { ...commitments[2]!, change: "unmet" },
]

export default function Example() {
  const fmt = useFormat()
  return (
    <div className="flex max-w-xl flex-col gap-6">
      <WorkScope
        agent={builder}
        commitments={commitments}
        excluded={[{ id: "x1", text: "Changing the supplier's own file format" }]}
        needed={[{ id: "n1", text: "A sample of last month's supplier file" }]}
        // The figure is a slot: the app's Money, or text it formats with formatMoney, as here.
        estimate={{
          figure: `${formatMoney(fmt.number, 12, "USD")}–${formatMoney(fmt.number, 30, "USD")}`,
          note: "From 14 similar imports.",
          uncertainty: "It could come in at half or one and a half times this.",
        }}
        environment="the Sandbox 2 copy"
        // The app's MoneyInput and its agree-and-start dialog's trigger go here.
        limit={<p className="text-xs text-muted-foreground">The app&apos;s limit field goes here.</p>}
        actions={<Button>Review and agree</Button>}
      />
      {/* A later round, compact: changes in words, unchanged collapsed, and what is still not met in its own list, numbered
          on from the commitments (4), so it can't be read as one of them. */}
      <WorkScope
        agent={builder}
        size="compact"
        delta
        title="Revised scope"
        commitments={round2}
        excluded={[{ id: "x1", text: "Changing the supplier's own file format", change: "unchanged" }]}
        needed={[]}
        estimate={{ figure: null, reason: "the new email step hasn't been timed yet" }}
      />
    </div>
  )
}
```

## <WorkScope>

Props:

- `agent: AgentIdentity`: The agent whose proposal this is, named by the app: drawn as its badge after "Proposed by".
- `title?: string | undefined`: The heading, in the app's words. Defaults to the `title` string, "Proposed scope of work".
- `commitments: WorkScopeCommitment[]`: What the agent commits to, numbered in order, each with its planned check.
- `excluded?: WorkScopeItem[] | undefined`: What is not included. Left out, the section isn't drawn; empty, it says nothing is listed.
- `needed?: WorkScopeItem[] | undefined`: What the agent needs from the person. Left out, the section isn't drawn; empty, it says nothing is listed.
- `estimate?: WorkScopeEstimate | undefined`: The estimate: the app's figure or range (its `Money`), a note and an uncertainty line; or none, with the reason.
- `environment?: string | undefined`: Where the work will be checked, in the app's words ("the second test copy"), drawn as "Checked in …" under the commitments.
- `diagram?: React.ReactNode | undefined`: The app's diagram of the work (a GraphView, an image). Drawn at `size="full"` only.
- `limit?: React.ReactNode | undefined`: The app's field for the most the agent may spend (its MoneyInput), drawn after the estimate.
- `actions?: React.ReactNode | undefined`: The app's actions, last: its agree-and-start dialog's trigger. Nothing here agrees by itself.
- `size?: Size | undefined` (default `"full"`): "compact" for a card in a thread, "full" (the default) for a page or a reader.
- `delta?: boolean | undefined` (default `false`): A later round: marks each item's change, collapses unchanged items and lists unmet commitments under "Still not met".
- `headingLevel?: HeadingLevel | undefined`: The level of the heading. Defaults to one below the nearest `HeadingScope`, else 2; the sections sit one below it.
- `className?: string | undefined`: Classes for the scope, merged with Candor's.

## Strings (`workScope`)

The fixed words, English by default. Override any of them under `workScope` in `<LocaleProvider strings={{ workScope: { … } }}>`; the table is exported as `workScopeStrings`.

- `title`: Proposed scope of work
- `proposedBy`: Proposed by {agent}
- `notAgreed`: Nothing here is agreed until you agree to it.
- `commitments`: What the agent commits to
- `noCommitments`: No commitments proposed.
- `check`: Will be checked {how}
- `environment`: Checked in {where}
- `stillNotMet`: Still not met
- `excluded`: Not included
- `noneExcluded`: Nothing listed as not included.
- `needed`: Needed from you
- `noneNeeded`: Nothing listed as needed from you.
- `estimate`: Estimate
- `noEstimate`: No estimate yet: {reason}
- `added`: Added
- `changed`: Changed
- `unchanged`: Unchanged
- `was`: Was: {from}
- `showUnchanged`: { one: "Show {count} unchanged", other: "Show {count} unchanged" }
- `hideUnchanged`: Hide unchanged

## Types

### WorkScopeChange

How an item stands against the round before, in delta mode: "added" (new this round), "changed" (its words changed; `from` says what it was), "unchanged" (collapsed until the person shows it), or "unmet" (from an earlier round and still not met; a commitment like this is listed under "Still not met").

```ts
"added" | "changed" | "unchanged" | "unmet"
```

### WorkScopeCheck

How a commitment will be checked once the work is done: a planned check, never a result.

```ts
{
  /** The app's kind of check ("run", "test", "read"), set on the row as `data-check` for the app's styling. */
  kind: string;
  /** How it will be checked, in the app's words as they follow "Will be checked": "by running it", "by a test". */
  label: string;
}
```

### WorkScopeCommitment

One commitment the agent proposes. Its words are the agent's: drawn as text, never as HTML or a link.

```ts
{
  /** Stable within the scope. */
  id: string;
  /** What the agent commits to, in its own words. */
  text: string;
  /** How it will be checked. */
  check: WorkScopeCheck;
  /** How it stands against the round before. Read only in delta mode. */
  change?: WorkScopeChange | undefined;
  /** With `change: "changed"`, what it said before, drawn as "Was: …". */
  from?: string | undefined;
}
```

### WorkScopeItem

One line of the not-included or needed-from-you lists. Its words are drawn as text.

```ts
{
  /** Stable within its list. */
  id: string;
  /** The line, in the agent's or the app's words. */
  text: string;
  /** How it stands against the round before. Read only in delta mode. */
  change?: WorkScopeChange | undefined;
  /** With `change: "changed"`, what it said before, drawn as "Was: …". */
  from?: string | undefined;
}
```

### WorkScopeEstimate

The estimate, always under the "Estimate" heading. `figure` is a slot: pass the app's `Money` (a figure or a range), or a string the app formatted with `formatMoney` from `foundation/ops`. With no estimate, pass `figure: null` and the reason: it says "No estimate yet", never a figure made up.

```ts
{
  /** The figure or range, as the app draws it: its `Money` element, or text. */
  figure: React.ReactElement | string;
  /** What the estimate is based on, or what it covers, in the app's or the agent's words. */
  note?: string | undefined;
  /** How far it could be out, in the app's words: "It could be half as much again, or half as little." */
  uncertainty?: string | undefined;
} | {
  figure: null;
  /** Why there is no estimate. */
  reason: string;
}
```

## Types from other items

The props above take these. Each is defined by another item; import it from the path shown.

### AgentIdentity

Import: `import type { AgentIdentity } from "@/lib/candor/chat"` (item `chat`, https://candor.themethodic.com/docs/chat.md)

```ts
{
  id: string;
  /** The displayed name, e.g. "Architect agent". Never derived from model output. */
  name: string;
  role: AgentRole;
  specialty?: string | undefined;
}
```

### HeadingLevel

Import: `import type { HeadingLevel } from "@/lib/candor/heading-level"` (item `heading-level`, https://candor.themethodic.com/docs/heading-level.md)

A heading's level in the page's outline: `1` is `<h1>`, `6` is `<h6>`. Every Candor item that draws a heading takes its `headingLevel` as this type; the level is where the heading sits in the outline, never how large it looks.

```ts
1 | 2 | 3 | 4 | 5 | 6
```

### AgentRole

Import: `import type { AgentRole } from "@/lib/candor/chat"` (item `chat`, https://candor.themethodic.com/docs/chat.md)

What an agent does: "assistant", "coder", "reviewer"… The app registers each role's glyph and hue (AgentRolesProvider).

```ts
string
```

## Rules for using Candor UI

- Components take plain typed data. Never pass model output as HTML or render it as a link; messages are typed blocks.
- A control that can't be used says why: wrap it in `<Locked reason="…">`, don't just disable it.
- Don't show a value you don't have: leave it out (it renders as —) rather than guess. An estimate is labelled as one.
- Nothing is pre-selected in a decision a person makes, and the agent is named from your app's data, never from model output.
- Your app's words go in `LocaleProvider`: its fixed strings in `strings`, its nouns in `nouns`; entity kinds and agent roles in `EntityKindsProvider` and `AgentRolesProvider`.
