pi-human-inquire

pi-human-inquire turns plans, notes, specs, RFCs, recaps, research, diffs, and other structured content into reviewable HTML where humans can ask agent questions and leave feedback directly inside the document.

It includes:

• a human-review skill that creates reviewable HTML from structured content
• a browser surface for comments, contextual questions, threaded discussion, and feedback submission

Install

Pi packages can be installed from git, npm, or a local path. Git is the recommended install path once the repo is published/renamed.

Try without installing

pi -e npm:pi-human-inquire

Install globally

pi install npm:pi-human-inquire

Install for a project

pi install -l npm:pi-human-inquire

Install from git

pi install git:github.com/alpeshvas/pi-human-inquire

Usage

Generate reviewable HTML from content

Use the skill:

/skill:human-review

You can invoke it with no arguments, with a file path, or with an instruction:

/skill:human-review notes.md
/skill:human-review turn this RFC into review HTML
/skill:human-review make the previous plan reviewable

The skill uses the provided content, or the most recent structured content in the conversation. It then creates an HTML file and opens it in the browser. If it cannot find suitable content, it asks you for a path or content.

Open existing HTML

If you already have an HTML file:

/annotate-html /absolute/path/to/document.html

Legacy alias:

/annotate-plan-html /absolute/path/to/document.html

Browser surface

In the opened HTML review page, you can:

• click any block to ask agent questions or leave feedback
• select text for comments
• continue threaded agent Q&A in place
• add document-level notes
• edit or remove comments
• submit feedback back into the active Pi session

Agent answers use the document, current block, selected text, existing comments, thread history, and recent session context.

Architecture

flowchart TD
  P["Pi package<br/>package.json"] --> S["Skill<br/>/skill:human-review"]
  P --> E["Extension<br/>commands + tool"]

  S --> H["Reviewable HTML"]
  S --> T["open_html_review"]
  E --> T
  E --> C["/annotate-html"]

  T --> B["Browser review page"]
  C --> B

  B --> BR["ctx.sessionManager.getBranch<br/>recent session context"]
  BR --> M["Active Pi model<br/>for threaded agent Q and A"]
  M --> B

  B --> F["pi.sendUserMessage<br/>deliverAs: followUp"]
  F --> PI["Active Pi session"]

Skill options

Use lite mode for quick/minimal output:

/skill:human-review --lite notes.md

Use stubs when iterating on a plan or spec and you want sections to remain stable across revisions:

/skill:human-review --with-stubs spec.md

By default, generated HTML is written to:

~/.agent/diagrams/<slug>.html

Feedback submission

Submitted feedback is saved locally and sent back into the active Pi session.

Compatibility notes

For now, /annotate-plan-html remains an alias for /annotate-html.