Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions .changeset/ready-to-start-tasks.md
Original file line number Diff line number Diff line change
@@ -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`.
2 changes: 1 addition & 1 deletion packages/work-board-plugin/.claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -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"
Expand Down
2 changes: 1 addition & 1 deletion packages/work-board-plugin/AGENTS.md
Original file line number Diff line number Diff line change
@@ -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.

Expand Down
12 changes: 6 additions & 6 deletions packages/work-board-plugin/README.md
Original file line number Diff line number Diff line change
@@ -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

Expand All @@ -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

Expand Down
1 change: 0 additions & 1 deletion packages/work-board-plugin/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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:",
Expand Down
6 changes: 1 addition & 5 deletions packages/work-board-plugin/src/adapters/hostBoard.ts
Original file line number Diff line number Diff line change
Expand Up @@ -28,11 +28,7 @@ export async function withClient<A>($: 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 {
Expand Down
6 changes: 2 additions & 4 deletions packages/work-board-plugin/src/adapters/platformClient.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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<number>) {
export function platformClient(directory: string, post: Post) {
const client = browserClient(BOARD_ORIGIN, { live: false, protocol: hostProtocol(post) });
function run<A, E>(effect: Effect.Effect<A, E, Reader>) {
return client.run(effect).catch((error: unknown) => Promise.reject(problemOf(error)));
Expand All @@ -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": {
Expand All @@ -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(),
};
}
61 changes: 16 additions & 45 deletions packages/work-board-plugin/src/answers.ts
Original file line number Diff line number Diff line change
@@ -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<unknown> = new Set(STAGES);
export type TaskList = "ready" | "working";

export function flightsOf(value: unknown, now: number, titles: ReadonlyMap<string, string> = new Map()): WorkboardBlock<WorkboardFlight> {
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<string, string>): WorkboardBlock<WorkboardTask> {
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 };
}

Expand Down Expand Up @@ -68,17 +50,6 @@ export function goalsOf(value: unknown): WorkboardBlock<WorkboardGoal> {
return { items, problem: null };
}

function goalIdOf(metadata: unknown, titles: ReadonlyMap<string, string>): 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<string, string> {
const titles = new Map<string, string>();
if (!isRecord(value)) {
Expand Down
62 changes: 18 additions & 44 deletions packages/work-board-plugin/src/answers.unit.test.ts
Original file line number Diff line number Diff line change
@@ -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", () => {
Expand Down
26 changes: 0 additions & 26 deletions packages/work-board-plugin/src/areaAvailability.dom.spec.ts

This file was deleted.

65 changes: 0 additions & 65 deletions packages/work-board-plugin/src/areaView.tsx

This file was deleted.

Loading
Loading