@peteturnbull/pi-extensions

A pi extension pack that includes:

• A TUI task board backed by .pi/task-board/tasks.json
• A deterministic docs-store backed by .pi/docs-store/ with qmd-powered search

Features

Task board

• Ticket tools: create_ticket, update_ticket, list_tickets, list_ready_tickets, get_ticket
• /task-board command launches the terminal UI
• Ready/active/blocked/all workflow views
• Keyboard-first ticket inspect + status transitions + progress + notes
• Feature tags (feature:<slug>) for feature-isolated planning/filtering
• JSON persistence with dependency-aware readiness and blocked-state reasoning

Docs-store

Why this exists

When agents only use ad-hoc files, knowledge gets fragmented and hard to recover. Docs-store gives agents a single, structured memory surface with two goals:

1. Deterministic writes

   • Agents write via typed tools, not arbitrary file paths.
   • This reduces random file dumping and keeps stored knowledge consistent.

2. High-quality retrieval

   • Stored docs are indexed for qmd search (query/search/vsearch).
   • Agents can reliably find prior decisions, notes, and context by meaning or keywords.

In short: docs-store is for durable project memory that stays organized and searchable as runs accumulate.

• Deterministic write/read tools (no arbitrary write paths in tool inputs)
• Tools: docs_store_put, docs_store_get, docs_store_list, docs_store_search, docs_store_delete, docs_store_status, docs_store_set_base_dir, docs_store_refresh
• /docs-store helper command (help, status, where, set-dir, use-default, refresh, refresh-embed)
• Configurable base directory (default: <project>/.pi/docs-store)
• Markdown documents persisted under <base-dir>/docs/*.md
• qmd integration (query/search/vsearch) on a project-scoped qmd index

Install

# global
pi install npm:@peteturnbull/pi-extensions

# project-local
pi install -l npm:@peteturnbull/pi-extensions

Usage

Task board

/task-board
/task-board <feature>
/task-board help

• /task-board opens the board with tickets from all features.
• /task-board <feature> opens a feature-scoped board (tickets where ticket.feature === <feature>).

TUI keys

• List: ↑/↓, Enter, 1..4, /, Esc
• Detail: s (start), b (block), c (complete), p (progress), n (note), Esc

Docs-store

/docs-store
/docs-store status
/docs-store where
/docs-store set-dir ../shared/docs-store
/docs-store use-default
/docs-store refresh
/docs-store refresh-embed

Docs-store data location defaults to:

<project>/.pi/docs-store/
  docs/      # managed markdown docs
  index.json # metadata index

Override options (highest precedence first):

1. Environment variable: PI_DOCS_STORE_DIR
2. Config file: <project>/.pi/docs-store.config.json (set by /docs-store set-dir or docs_store_set_base_dir)
3. Default: <project>/.pi/docs-store

qmd requirement

Docs-store search uses the qmd CLI. Install globally:

npm install -g @tobilu/qmd

Docs-store smoke test

Run the integration smoke flow (set-base-dir -> put -> list -> get -> search -> delete -> use-default):

# Runs search only if qmd is available
npm run smoke:docs-store

# Enforce qmd availability (fails if qmd is missing)
npm run smoke:docs-store:qmd

Task board data file

<project>/.pi/task-board/tasks.json

Seed task board demo data

node .pi/scripts/seed-task-board.mjs --force

Publishing to npm

One-time setup

1. Ensure you have an npm account and are logged in:

   npm login
   npm whoami

2. Confirm package name availability (first publish only):

   npm view @peteturnbull/pi-extensions name

   • If this returns E404, the name is available.
   • If it exists and you do not own it, choose a new package name in package.json.

3. Confirm access rights if package already exists:

   npm access ls-packages $(npm whoami)

Preflight checks

npm run preflight
npm run pack:dry

Release script workflow (recommended)

This repo includes scripts/release.sh, which handles:

• clean working tree check
• preflight + npm pack --dry-run
• version bump
• changelog section rollover
• release commit + git tag
• optional push + npm publish

Prepare release only (no publish)

npm run release
# or: npm run release:patch | release:minor | release:major

Release + publish in one command

npm run release:publish:patch
# or: release:publish:minor | release:publish:major

Dry-run publish (safe test)

npm run release:publish:dry-run

Manual fallback

# after release commit + tag exists
git push && git push --tags
npm publish --access public

Package layout

extensions/
  task-board.ts
  docs-store.ts
  docs-store-paths.ts
test/
  docs-store-paths.test.ts
  smoke/
    mock-loader.mjs
    register-loader.mjs
    shims/
      pi-ai.mjs
      typebox.mjs
      pi-coding-agent.mjs
CHANGELOG.md
README.md
package.json
scripts/
  preflight.mjs
  release.sh
  smoke-docs-store.mjs