WorkGraph PI Harness CLI

TypeScript/Node.js CLI that runs an autoresearch-style PI loop for business operations on top of WorkGraph MCP.

It includes:

• src/gather/ — Context Gatherer (business.yaml producer)
• src/workgraph/ — Typed WorkGraph MCP client over JSON-RPC HTTP
• src/metrics/ — Health score calculator from program.md
• src/harness/ — Bootstrap + observe/hypothesize/execute/measure loop
• src/cli.ts — CLI entrypoint (gather, bootstrap, run, health)

Requirements

• Node.js 20+
• A reachable WorkGraph MCP endpoint

Install

npm install
npm run build

Run directly after build:

node dist/cli.js --help

Or install globally from this directory:

npm link
workgraph-pi-harness --help

Configuration

config.yaml must include:

workgraph:
  url: https://your-workgraph-host
  mcp_endpoint: /mcp
  token: wgk_...
  actor: pi-agent

Optional env overrides:

• WORKGRAPH_URL
• WORKGRAPH_TOKEN
• WORKGRAPH_ACTOR

Commands

1) Gather context

Discovery-first context gatherer with interview prompts; writes business.yaml.

node dist/cli.js gather --config config.yaml --output business.yaml

Non-interactive mode:

node dist/cli.js gather --non-interactive

2) Bootstrap WorkGraph

Reads business.yaml, checks graph state, and attempts bootstrap.

node dist/cli.js bootstrap --config config.yaml --business business.yaml

3) Run PI loop

Runs bootstrap preflight (unless skipped), then loops forever:

• observe (status, hygiene, ledger, list_threads)
• hypothesize (pick highest-value thread)
• execute (claim; optional auto-complete)
• measure (health score)
• record (results.tsv)

node dist/cli.js run --config config.yaml --business business.yaml

One cycle only:

node dist/cli.js run --once

Skip bootstrap and set interval:

node dist/cli.js run --skip-bootstrap --interval 3

Enable auto-complete:

node dist/cli.js run --auto-complete

4) Compute health

Calculates health score from live WorkGraph data:

node dist/cli.js health --config config.yaml

Health Formula

Implemented from program.md:

health = 100
  - (orphan_links × 0.5)
  - (stale_threads × 2)
  - (blocked_threads × 3)
  - (overdue_threads × 5)
  - (missing_evidence × 2)
  + (threads_completed_today × 1)
  + (revenue_threads_completed × 3)
  + (automation_triggers_fired × 0.5)

Notes

• Results are appended to results.tsv.
• run defaults to conservative behavior: claim-only execution unless --auto-complete is set.
• Bootstrap uses workgraph.workgraph_bootstrap when available and falls back to workgraph.workgraph_query.