Work scope
ProThe 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.
Preview
Loading the preview
Install
First time? Get started sets up the registry and theme. Or with shadcn directly: npx shadcn@latest add @candor/work-scope
Brings in: agent-avatar, bidi, button, chat, heading-level, heading-scope, locale, tokens, utils · npm: lucide-react@^1.67.0
Usage
"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'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>
| Prop | Type | Default | Description |
|---|---|---|---|
| agentrequired | 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". |
| commitmentsrequired | 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 | "full" | "compact" for a card in a thread, "full" (the default) for a page or a reader. |
| delta | boolean | undefined | 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
The fixed words, in English by default. Change any of them under workScope in <LocaleProvider strings={{ … }}>; the table is exported as workScopeStrings.
| Key | English |
|---|---|
| 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").
"added" | "changed" | "unchanged" | "unmet"- WorkScopeCheck
- How a commitment will be checked once the work is done: a planned check, never a result.
{ /** 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.
{ /** 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.
{ /** 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.
{ /** 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 from @/lib/candor/chat
{ id: string; /** The displayed name, e.g. "Architect agent". Never derived from model output. */ name: string; role: AgentRole; specialty?: string | undefined; }- HeadingLevel from @/lib/candor/heading-level
- 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.
1 | 2 | 3 | 4 | 5 | 6- AgentRole from @/lib/candor/chat
- What an agent does: "assistant", "coder", "reviewer"… The app registers each role's glyph and hue (AgentRolesProvider).
string