@centerforagenticai/pi-work

Kind: extension · Status: experimental · Pi: ^0.85.1 · Node: >=22.19

Structured workspec authoring, verification, and plan compilation for Pi. A workspec is a YAML description of agent-directed work and its completion criteria.

What it does

pi-work helps an agent turn an outcome into a checked graph of work. It owns the workspec format and the evidence used to establish completion. The agent in the current Pi session still decides what runs next, while the selected dispatch backend owns worker execution.

• Draft and promote a workspec without losing its criteria.
• Validate the graph, dependencies, write scope, and evidence declarations.
• Derive node state from source files and evidence instead of storing status in the workspec.
• Compile ready nodes into worker briefs and dispatch exactly one node per call.
• Verify declared evidence against a named Git tree; report failure instead of guessing when a kind is unavailable.

A failed or unexecuted check does not pass. Detailed evidence rules are in docs/EVIDENCE.md.

How it fits

The agent running the Pi session calls pi-work tools and commands. pi-work reads and writes Markdown drafts, YAML workspecs, and a cache under .work/ that it can rebuild from those sources. It checks evidence in the target Git worktree. For execution, work_dispatch submits one node to Fabric by default, or to pi-delegate when selected. pi-work keeps the brief, plan receipt, digests, and status cache; the backend supplies the worker run and result. pi-work has no scheduler, daemon, or persistent run-state service.

Install and enable

pi-work is opt-in per project. Install the npm package into the consuming project's .pi/settings.json:

cd <project>
pi install npm:@centerforagenticai/pi-work -l

For an unpublished checkout, add its absolute path instead, merging it into any existing packages array:

{
  "packages": ["/absolute/path/to/pi-work"]
}

Restart Pi, then verify the package is listed under Project packages:

pi list

It needs Pi ^0.85.1 and Node >=22.19. Read docs/INSTALLING.md for npm installation, linked worktrees, one-run loading, and limiting which package resources load.

Surface

| Kind | Name | Purpose | | --- | --- | --- | | Tool | work_validate | Parse and validate a workspec; return typed findings and advisory lints. | | Tool | work_promote | Promote a Markdown draft to a YAML workspec while preserving criteria. | | Tool | work_amend_criterion | Change one criterion through an append-only recorded amendment. | | Tool | work_status | Derive each node as done, ready, blocked, or needing a decision. An open decision with gates prevents planning and dispatch of the named top-level nodes and their subtrees; one without gates blocks every node. An applicable decision makes a node needs-decision unless another prerequisite already makes it blocked. | | Tool | work_plan | Compile ready node addresses into plans that point to stored worker briefs, without dispatching. | | Tool | work_dispatch | Compile and submit exactly one node through the selected backend, or return the plan without claiming dispatch occurred. | | Tool | work_verify | Verify a node's declared evidence in a named Git tree. | | Commands | /work-draft, /work-promote, /work-decompose | Guide authoring, promotion, and decomposition. | | Commands | /work-status, /work-next | Show derived state or hand off one ready round. | | Skill | work-authoring | Draft an outcome and observable criteria. | | Skill | work-decomposition | Assign node boundaries, dependencies, proof, and write scopes. | | Skill | work-execution | Plan, dispatch, verify, and remediate ready work. |

Paths passed to tools are relative to the allowed base directory for that call. Absolute paths are rejected rather than rewritten.

Dispatch backends

work_dispatch accepts backend: "fabric" or backend: "pi-delegate". Selection is ordered:

1. An explicit backend selects that executor; it never falls back to another.
2. With no override, an available Fabric host adapter is the default.
3. Without a Fabric host adapter, pi-work uses pi-delegate. An explicitly selected Fabric backend without an adapter, or an unavailable selected pi-delegate client, returns a plan-only result rather than claiming dispatch occurred.

Load pi-fabric alongside pi-work and restart Pi for Fabric dispatch. Fabric needs no pi-delegate installation. Fabric is discovered only when the fabric_exec tool is registered and Pi exposes an event bus. Without that discovery, dispatch uses pi-delegate, then plan-only if pi-delegate is unavailable. An event bus alone does not select Fabric. A missing or silent discovered listener causes a bounded timeout, not an automatic pi-delegate retry. An unknown dispatch state is not permission to submit a second worker.

Before submitting a Fabric run, pi-work automatically bootstraps the fixed pi-work-dispatch program in .pi/fabric/programs/<digest>.json under PI_FABRIC_PROJECT_ROOT, or the session cwd when that variable is absent. It writes a candidate record atomically, reuses an existing digest record, and invokes it by full digest through pi-fabric:program:run:v1. No manual programs.save call or program promotion is required. pi-work registers a Fabric provider for its tools as well.

Fabric supplies the worktree, model, tool-level write confinement, completion delivery, and schema-validated worker result. File touches become parent-directory write roots; the brief still limits the worker to the declared files. Nodes with write roots run with shell: "unconfined" to execute evidence commands. This is not a shell sandbox. Fabric's agents.childQuestions must remain "cancel" (the default); "route" is rejected because node escalation is disabled.

Fabric dispatch confinement is directory-level writableRoots plus a best-effort post-run content diff, not a hard file-level guard. Files over 8 MiB are compared by size and mtime. Snapshot traversal has no file-count or time bound.

A dispatch receipt proves submission and correlation, not completion: work_verify must rerun evidence against the returned tree and commit.

Configuration

The extension reads no package-specific settings. Loading it through the project's .pi/settings.json enables all seven tools and discovers all three skills. The workspec itself carries node, worker, evidence, and write-scope settings; see the design record for the schema and decisions.

Development hooks are optional. npm run hooks:install installs all tracked hooks. sh scripts/install-git-hooks.sh --build-only installs only the four dist/ rebuild hooks. Their controls are:

| Setting | Effect | | --- | --- | | git config piwork.autobuild true | Rebuild in linked worktrees too. | | git config piwork.autobuild false | Disable automatic rebuilds. | | PI_WORK_NO_AUTOBUILD=1 git commit | Skip the rebuild for one command. |

The full hook behaviour is in docs/INSTALLING.md.

When it runs

pi-work runs only when an agent or person invokes one of its tools or slash commands. It registers context and session-start hooks for Fabric completion announcements, but starts no scheduler or background service. work_dispatch submits at most one node per call; it never sequences, retries, or polls. The Fabric host-event call awaits a bounded reply. work_verify runs only the evidence declared for the selected node.

Develop

Use an isolated worktree because Pi sessions load compiled code from dist/. Give the worktree its own node_modules; do not link dependencies back to a shared checkout.

git clone https://github.com/CenterForAgenticAI/tools.git
cd tools/packages/pi-work
npm ci
env NPM_CONFIG_USERCONFIG=/dev/null npm run check

The gate runs lint, source and test typechecks, hook tests, the compiled JavaScript tests with coverage, the production build, and the package smoke. The package smoke must run after the build because the published extension entry is ./dist/index.js.

Documentation

• docs/INSTALLING.md: installation, project opt-in, development commands, rebuild hooks, and repository layout.
• docs/SURFACE.md: tools, commands, skills, and path rules.
• docs/DESIGN.md: the design constraints behind pi-work's current shape.
• docs/EVIDENCE.md: evidence kinds, environment controls, redaction, and command containment.
• docs/GLOSSARY.md: project terms used in the design and implementation.
• docs/diagrams/: architecture diagram source and generated SVG.
• Design record: architecture, schema, boundaries, and deferred decisions.
• ADR index: accepted architecture decisions.
• Postmortem: the predecessor failures that shaped the constraints.

License

MIT. See LICENSE.