diff --git a/.changeset/ready-to-start-tasks.md b/.changeset/ready-to-start-tasks.md new file mode 100644 index 00000000..983ab8b2 --- /dev/null +++ b/.changeset/ready-to-start-tasks.md @@ -0,0 +1,8 @@ +--- +"@shivaedev/work-board": minor +--- + +### Added + +- Accept `working` as an authored status for a task an agent is working on. Goal progress counts it as running, Now shows it under Working, and the file fallback for In progress lists it beside ready tasks. +- `client.api.overview.query()` and the `board_overview` MCP tool return `tasks`: `ready` lists the tasks ready to start now (approved, not working, done, deferred or dropped, no open ask blocking them, every `depends_on` target done) and `working` lists the tasks with status `working`. diff --git a/packages/work-board-plugin/.claude-plugin/plugin.json b/packages/work-board-plugin/.claude-plugin/plugin.json index 9f93e164..4b019904 100644 --- a/packages/work-board-plugin/.claude-plugin/plugin.json +++ b/packages/work-board-plugin/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "author": { "name": "ShivaeDev" }, - "description": "A live pane of the platform Work Board: what needs you, what is in flight, and goal progress", + "description": "A live pane of the platform Work Board: what needs you, what is in progress, what is ready to start, and goal progress", "name": "workboard", "types": "./types/index.d.ts", "version": "0.1.0" diff --git a/packages/work-board-plugin/AGENTS.md b/packages/work-board-plugin/AGENTS.md index 52b81f4f..23999f56 100644 --- a/packages/work-board-plugin/AGENTS.md +++ b/packages/work-board-plugin/AGENTS.md @@ -1,6 +1,6 @@ # @shivaedev/work-board-plugin -The Work Board plugin brings the running Work Board into Claude Code, so a session sees what needs the maintainer, what Fleet has in flight and how goals are progressing without leaving the prompt. It is a Claude Code mod: a hooks module the Claude Code engine loads and draws, shipped from this repository's plugin marketplace and never published to npm. +The Work Board plugin brings the running Work Board into Claude Code, so a session sees what needs the maintainer, which tasks are in progress, which are ready to start and how goals are progressing without leaving the prompt. It is a Claude Code mod: a hooks module the Claude Code engine loads and draws, shipped from this repository's plugin marketplace and never published to npm. The Board stays the source of truth. The plugin only reads it. It finds the `board.sock` of the nearest `.work` folder at or above the session's folder and runs the Board's authorized contract queries through Platform's contract client, each request one `$.http.fetch` over that socket, because the host gives a hooks module no WebSocket. With no live push, it reads the Board again on session start, on Refresh and on a timer. It answers with what the Board said or why it could not ask: no Board in this folder, a Board that is not running, or a request it refused. It never writes to the Board and never guesses state it was not given. diff --git a/packages/work-board-plugin/README.md b/packages/work-board-plugin/README.md index 4ddfb602..ff20b756 100644 --- a/packages/work-board-plugin/README.md +++ b/packages/work-board-plugin/README.md @@ -1,14 +1,14 @@ # @shivaedev/work-board-plugin -The Work Board inside Claude Code: what needs you, what Fleet has in flight and how your goals are doing, one glance from the prompt. +The Work Board inside Claude Code: what needs you, what is in progress, what is ready to start and how your goals are doing, one glance from the prompt. ## Why you want this A Work Board runs beside your sessions, but its browser tab is not where you are looking. With the plugin, each Claude Code session finds its own Board and shows it where you work: -- a one-line band above the prompt that sums Needs you, In flight and Goals, with a button that opens the pane; -- a `/workboard` pane listing each Needs you item as a pressable line, started Fleet work grouped by goal with each agent’s activity, current or finished turn duration and PR number, and goal progress bars or a plain “all tasks done” check; +- a one-line band above the prompt that sums Needs you, In progress, Ready and Goals, with a button that opens the pane; +- a `/workboard` pane listing each Needs you item as a pressable line, the tasks in progress and the tasks ready to start grouped by goal with each task’s owner, and goal progress bars or a plain “all tasks done” check; - a toast when a new decision lands for you; -- three read-only tools the model can call, named after the Board's own MCP tools: `board_overview`, `needs_you` and `item`. +- three read-only tools the model can call, named after the Board's own MCP tools: `board_overview` for what needs you, the tasks in progress and ready to start, and goal progress; `needs_you` for each waiting decision with its options and age; and `item` for one item's authored status, owner, criteria, relationships and open decisions. ## Using it @@ -26,9 +26,9 @@ The plugin only reads the Board. Answer decisions in the Board itself or through ### The pane -The pane folds goals with status `done` under an “Achieved (N)” row, closed by default. Click it to show those goals. Open goals stay visible, including goals whose tasks are all done. In flight and goal running counts use the same Board overview snapshot. If Fleet cannot be reached, In flight shows why it is unavailable. +The pane folds goals with status `done` under an “Achieved (N)” row, closed by default. Click it to show those goals. Open goals stay visible, including goals whose tasks are all done. In progress, Ready to start and goal running counts use the same Board overview snapshot, so they agree. -Areas lists only the areas Fleet holds or queues work for, as wrapping chips with held areas first; free areas are left out, and with none busy the section says no area is held or queued. Amber marks a held area or a queue of fewer than five tasks; red marks five or more queued tasks. Each chip names its state and queue count. Open a chip to read its holders, stages and PR links, followed by the approved queue in Fleet's order. A Fleet daemon that does not supply availability is shown as unknown. +In progress lists the tasks whose status is `working`: whoever starts an agent on a task sets that status, and sets `done` when the work merges. Ready to start lists what the Board computes as startable now: tasks with `fleet: approved` that are not working, done, deferred or dropped, have no open ask blocking them and whose every `depends_on` target is done. Both group their tasks by the goal each implements, the largest group first and tasks without a goal under Other. A Board too old to send these lists leaves both sections unknown and says to update it. ### Install diff --git a/packages/work-board-plugin/package.json b/packages/work-board-plugin/package.json index 392ffd5d..f57ea0c7 100644 --- a/packages/work-board-plugin/package.json +++ b/packages/work-board-plugin/package.json @@ -35,7 +35,6 @@ "devDependencies": { "@shivaedev/quality": "catalog:", "@shivaedev/test-story": "catalog:", - "@shivaedev/work-fleet": "workspace:*", "@types/node": "catalog:", "@types/react": "catalog:", "@types/react-dom": "catalog:", diff --git a/packages/work-board-plugin/src/adapters/hostBoard.ts b/packages/work-board-plugin/src/adapters/hostBoard.ts index 2f5cd61d..1fa14563 100644 --- a/packages/work-board-plugin/src/adapters/hostBoard.ts +++ b/packages/work-board-plugin/src/adapters/hostBoard.ts @@ -28,11 +28,7 @@ export async function withClient($: EngineInterface, use: (client: Client) => if (directory === null) { throw new Error(waitingLine({ cwd, kind: "none" })); } - const client = platformClient( - directory, - (body) => post($, directory, body), - () => $.clock.now(), - ); + const client = platformClient(directory, (body) => post($, directory, body)); try { return await use(client); } finally { diff --git a/packages/work-board-plugin/src/adapters/platformClient.ts b/packages/work-board-plugin/src/adapters/platformClient.ts index d323f724..b39ab788 100644 --- a/packages/work-board-plugin/src/adapters/platformClient.ts +++ b/packages/work-board-plugin/src/adapters/platformClient.ts @@ -13,7 +13,7 @@ function problemOf(error: unknown): Error { return error instanceof Error ? error : new Error(String(error)); } -export function platformClient(directory: string, post: Post, now: () => Promise) { +export function platformClient(directory: string, post: Post) { const client = browserClient(BOARD_ORIGIN, { live: false, protocol: hostProtocol(post) }); function run(effect: Effect.Effect) { return client.run(effect).catch((error: unknown) => Promise.reject(problemOf(error))); @@ -26,8 +26,6 @@ export function platformClient(directory: string, post: Post, now: () => Promise return run(client.api.inbox.run(undefined)); case "work-board.overview": return run(client.api.overview.run(undefined)); - case "work-board.fleetItems": - return run(client.api.fleetItems.run(undefined)); case "work-board.server": return run(client.api.server.run(undefined)); case "work-board.document": { @@ -48,7 +46,7 @@ export function platformClient(directory: string, post: Post, now: () => Promise { inbox: client.api.inbox.run(undefined), overview: client.api.overview.run(undefined), server: client.api.server.run(undefined) }, { concurrency: "unbounded" }, ), - ).then(async (values) => readSnapshot(values, await now())), + ).then(readSnapshot), close: () => client.registry.dispose(), }; } diff --git a/packages/work-board-plugin/src/answers.ts b/packages/work-board-plugin/src/answers.ts index 98f7a234..817df759 100644 --- a/packages/work-board-plugin/src/answers.ts +++ b/packages/work-board-plugin/src/answers.ts @@ -1,41 +1,23 @@ -import type { WorkboardBlock, WorkboardFlight, WorkboardGoal } from "#types/index.d.ts"; +import type { WorkboardBlock, WorkboardGoal, WorkboardTask } from "#types/index.d.ts"; import { isRecord, records, text } from "./rpc.ts"; -export const STAGES = ["queued", "working", "reviewing", "waiting"] as const; -const STAGE_NAMES: ReadonlySet = new Set(STAGES); +export type TaskList = "ready" | "working"; -export function flightsOf(value: unknown, now: number, titles: ReadonlyMap = new Map()): WorkboardBlock { - if (!isRecord(value)) { - return { items: [], problem: "Fleet sent no items." }; - } - if (value.state !== "ready") { - return { items: [], problem: `Fleet is unavailable: ${text(value.reason) ?? "no reason given"}` }; +export function tasksOf(value: unknown, list: TaskList, titles: ReadonlyMap): WorkboardBlock { + const rows = isRecord(value) ? value[list] : undefined; + if (!Array.isArray(rows)) { + return { items: [], problem: "This Board does not list tasks to start; update it." }; } - const items = records(value.items) - .filter((row) => STAGE_NAMES.has(row.stage) && row.inFlight === true) - .map((row) => { - const workId = text(row.workId) ?? "unknown"; - const document = isRecord(row.document) ? row.document : {}; - const goalId = goalIdOf(document.metadata, titles); - return { - agents: records(row.agents).map((agent) => ({ - id: text(agent.id) ?? "agent", - role: text(agent.role) ?? "agent", - state: text(agent.state) ?? "not started yet", - turnMs: - typeof agent.startedAt === "number" && (agent.running === true || typeof agent.finishedAt === "number") - ? Math.max(0, (typeof agent.finishedAt === "number" ? agent.finishedAt : now) - agent.startedAt) - : null, - })), - attentionOwner: text(row.attentionOwner), - goal: goalId === null ? null : { id: goalId, title: titles.get(goalId) ?? goalId }, - prUrl: text(row.prUrl) ?? null, - stage: text(row.stage) ?? "unknown", - title: text(document.title) ?? workId, - waitingReason: text(row.waitingReason), - workId, - }; - }); + const items = records(rows).map((row) => { + const id = text(row.id) ?? "task"; + const goal = text(row.goal); + return { + goal: goal === undefined ? null : { id: goal, title: titles.get(goal) ?? goal }, + id, + owner: text(row.owner) ?? null, + title: text(row.title) ?? id, + }; + }); return { items, problem: null }; } @@ -68,17 +50,6 @@ export function goalsOf(value: unknown): WorkboardBlock { return { items, problem: null }; } -function goalIdOf(metadata: unknown, titles: ReadonlyMap): string | null { - const links = isRecord(metadata) ? records(metadata.relationships) : []; - for (const link of links) { - const id = link.kind === "implements" ? text(link.target)?.split("#")[0] : undefined; - if (id !== undefined && (titles.has(id) || id.startsWith("goal."))) { - return id; - } - } - return null; -} - export function goalTitlesOf(value: unknown): Map { const titles = new Map(); if (!isRecord(value)) { diff --git a/packages/work-board-plugin/src/answers.unit.test.ts b/packages/work-board-plugin/src/answers.unit.test.ts index b662d369..3a3c6993 100644 --- a/packages/work-board-plugin/src/answers.unit.test.ts +++ b/packages/work-board-plugin/src/answers.unit.test.ts @@ -1,60 +1,34 @@ import { describe, expect, it } from "vitest"; -import { flightsOf, goalsOf, goalTitlesOf } from "#answers.ts"; +import { goalsOf, goalTitlesOf, tasksOf } from "#answers.ts"; -const NOW = 1_800_000_000_000; - -describe("Fleet items and goals", () => { - it("keeps started unfinished work, links each item to the goal it implements and times each agent turn", () => { +describe("task lists and goals", () => { + it("names each listed task's goal by its title, from open, deferred or closed goals", () => { const titles = goalTitlesOf({ closedGoals: [{ id: "goal.closed", title: "Closed goal" }], deferredGoals: [{ id: "goal.parked", title: "Parked goal" }], goals: [{ id: "project.open" }], }); - expect(titles.get("goal.parked")).toBe("Parked goal"); - const flights = flightsOf( - { - items: [ - { - agents: [{ finishedAt: NOW - 60_000, id: "worker", role: "worker", startedAt: NOW - 120_000, state: "done" }], - document: { metadata: { relationships: [{ kind: "implements", target: "goal.closed#part" }] }, title: "Linked" }, - inFlight: true, - prUrl: "https://github.com/example/repo/pull/7", - stage: "reviewing", - stageEnteredAt: NOW - 60_000, - workId: "task.linked", - }, - { - document: { metadata: { relationships: [{ kind: "implements", target: "project.x" }] } }, - inFlight: true, - stage: "working", - workId: "task.loose", - }, - { stage: "queued", workId: "task.waiting" }, - ], - state: "ready", - }, - NOW, - titles, - ); - expect(flights).toEqual({ + const tasks = { + ready: [ + { file: "a.md", goal: "goal.parked", id: "task.a", owner: "claude", title: "Linked" }, + { file: "b.md", goal: "goal.unknown", id: "task.b" }, + { file: "c.md", id: "task.c", title: "Loose" }, + ], + working: [], + }; + expect(tasksOf(tasks, "ready", titles)).toEqual({ items: [ - { - agents: [{ id: "worker", role: "worker", state: "done", turnMs: 60_000 }], - goal: { id: "goal.closed", title: "Closed goal" }, - prUrl: "https://github.com/example/repo/pull/7", - stage: "reviewing", - title: "Linked", - workId: "task.linked", - }, - { agents: [], goal: null, prUrl: null, stage: "working", title: "task.loose", workId: "task.loose" }, + { goal: { id: "goal.parked", title: "Parked goal" }, id: "task.a", owner: "claude", title: "Linked" }, + { goal: { id: "goal.unknown", title: "goal.unknown" }, id: "task.b", owner: null, title: "task.b" }, + { goal: null, id: "task.c", owner: null, title: "Loose" }, ], problem: null, }); + expect(tasksOf(tasks, "working", titles)).toEqual({ items: [], problem: null }); }); - it("says why Fleet has no items", () => { - expect(flightsOf({ reason: "Fleet is not configured", state: "unavailable" }, NOW).problem).toBe("Fleet is unavailable: Fleet is not configured"); - expect(flightsOf(null, NOW).problem).toBe("Fleet sent no items."); + it("says the Board needs updating when it sends no task lists", () => { + expect(tasksOf(undefined, "ready", new Map()).problem).toBe("This Board does not list tasks to start; update it."); }); it("keeps the five progress states and standing-home flag from the Board", () => { diff --git a/packages/work-board-plugin/src/areaAvailability.dom.spec.ts b/packages/work-board-plugin/src/areaAvailability.dom.spec.ts deleted file mode 100644 index 153b9627..00000000 --- a/packages/work-board-plugin/src/areaAvailability.dom.spec.ts +++ /dev/null @@ -1,26 +0,0 @@ -import { outcomes } from "@shivaedev/test-story/server/outcomes.ts"; -import { task } from "@shivaedev/work-fleet/test-support/fleetHost.ts"; -import { boardWork } from "@shivaedev/work-fleet/test-support/hostStory.ts"; -import { pluginFleet } from "#test/fleetPane.ts"; - -const files = Object.fromEntries( - ["holder", "one", "two", "three", "four", "five", "short"].map((id) => [ - `${id}.md`, - task(id, "approved").replace("kind: task", `kind: task\nareas: [${id === "short" ? "work-board" : "work-fleet"}]`), - ]), -); - -pluginFleet.it( - "the plugin's area chips read live Fleet ownership and queues through Board HTTP and leave idle folders out", - [boardWork(files)], - function* ({ approve, admit, openPane }) { - yield* approve("holder"); - yield* admit(); - const pane = yield* openPane(); - yield* outcomes([ - ["Chips", () => pane.areaChips(), ["work-fleet", "work-board"]], - ["Held area", () => pane.areaState("work-fleet"), { color: "#d74253", state: "held · 5 queued" }], - ["Short queue", () => pane.areaState("work-board"), { color: "#ad7400", state: "unheld · 1 queued" }], - ]); - }, -); diff --git a/packages/work-board-plugin/src/areaView.tsx b/packages/work-board-plugin/src/areaView.tsx deleted file mode 100644 index 99dceab4..00000000 --- a/packages/work-board-plugin/src/areaView.tsx +++ /dev/null @@ -1,65 +0,0 @@ -import { prLabel } from "#lines.ts"; -import type { PaneView, Table } from "#pane.tsx"; -import type { WorkboardArea, WorkboardAreaTask, WorkboardBlock } from "#types/index.d.ts"; - -function stateOf(area: WorkboardArea) { - const count = area.queue.length; - return { color: count >= 5 ? "#d74253" : "#ad7400", label: `${area.holders.length > 0 ? "held" : "unheld"} · ${count} queued` }; -} - -export function areaView(t: Table, areas: WorkboardBlock, view: PaneView) { - const { Box, Text } = t; - const selected = areas.items.find((area) => area.area === view.openArea); - return ( - - Areas - {areas.problem === null ? areaChips(t, areas.items, view.onToggleArea) : {areas.problem}} - {areas.problem === null && selected !== undefined ? ( - - {selected.area} - {selected.holders.length === 0 ? No holder : selected.holders.map((task) => taskLine(t, task, "Holds"))} - {selected.queue.length === 0 ? ( - No approved tasks queued - ) : ( - selected.queue.map((task, index) => taskLine(t, task, `${index + 1}.`)) - )} - - ) : null} - - ); -} - -function areaChips(t: Table, areas: WorkboardArea[], onToggle: (area: string) => void) { - const { Box, Text } = t; - if (areas.length === 0) { - return No area is held or queued.; - } - return ( - - {areas.map((area) => areaChip(t, area, onToggle))} - - ); -} - -function areaChip(t: Table, area: WorkboardArea, onToggle: (area: string) => void) { - const { Box, Text, Button } = t; - const state = stateOf(area); - return ( - -