@centerforagenticai/pi-work

Structured workspec authoring, verification, and plan compilation for pi.

Packages

Package details

extensionskill

Install @centerforagenticai/pi-work from npm and Pi will load the resources declared by the package manifest.

npm repo home report

$ pi install npm:@centerforagenticai/pi-work

Package: @centerforagenticai/pi-work
Version: 0.1.3
Published: Oct 1, 2026
Downloads: 166/mo · 166/wk
Author: centerforagenticai-dev
License: MIT
Types: extension, skill
Size: 890.3 KB
Dependencies: 1 dependency · 2 peers

Pi manifest JSON

{
  "skills": [
    "./skills"
  ],
  "extensions": [
    "./dist/index.js"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

@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 pi-delegate 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

How pi-work fits between a session and delegated work

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 asks the loaded pi-delegate runtime to dispatch one node; pi-delegate then owns the worker, isolation, escalation, and result handling. 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.
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 pi-delegate, 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.

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 no Pi lifecycle event handlers and starts no background process. work_dispatch performs at most one pi-delegate dispatch per call; it never waits, sequences, retries, or polls. 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.