@felipe.3dfx/pi-workflow

A public Pi meta-configuration package for the pi-workflow foundation setup.

This package exposes only its own Pi extension. Companion packages such as Engram, MCP adapter, subagents, web access, and CodeGraph are installed explicitly as independent Pi packages so their ownership, updates, and resources stay transparent.

Requirements

• Node.js >=22.19
• Pi CLI available in the target environment
• Optional CodeGraph readiness requires the codegraph CLI on PATH and a project .codegraph/ index

Install

Install the meta package:

pi install npm:@felipe.3dfx/pi-workflow

Reload Pi so the local helper commands are available:

/reload

Inspect companion package status:

/pi-workflow-status
/pi-workflow-doctor

Install missing companions after reviewing the confirmation prompt:

/pi-workflow-install-companions

Then reload Pi again so companion resources are loaded:

/reload

In non-UI contexts, the install command prints the exact pi install npm:<pkg>@<version> commands instead of installing automatically.

MCP setup

The companion install flow also manages the Pi MCP catalog from assets/mcp-servers.json.

• It writes only ${PI_CODING_AGENT_DIR:-${PI_AGENT_HOME:-~/.pi/agent}}/mcp.json.
• It preserves unrelated top-level fields and unrelated MCP servers.
• After confirmation it re-reads the latest config before writing; if a targeted context7, sentry, or linear entry changed after preview, the command stops and asks you to rerun against the latest file.
• Exact context7, sentry, and linear entries are previewed before confirmation; malformed JSON or write failures are reported with the target path and manual recovery guidance.
• The flow never performs MCP authentication. After a successful install, run /reload and follow any Sentry or Linear OAuth prompts in Pi if those servers need them.
• Exact catalog contents are validated by npm run check:publish.

CodeGraph setup

CodeGraph support has three separate readiness checks:

1. Install the recommended companion package through the normal companion flow:

   /pi-workflow-install-companions

   Or install it manually when needed:

   pi install npm:@vndv/[email protected]

2. Make the codegraph CLI available on PATH. pi-workflow validates readiness by checking whether the codegraph command can be executed, not by checking for a globally installed npm package. This keeps the check package-manager agnostic for users who install CodeGraph with npm, pnpm, Homebrew, mise, a system package, or another tool.

   The companion package and CLI readiness are reported separately; installing the companion does not imply the CLI is usable.

3. Initialize the current project index explicitly from the project root:

   codegraph init <project-root>

Verify readiness after reloading Pi:

/reload
/pi-workflow-doctor

The doctor reports the CodeGraph companion package, CLI availability, and .codegraph/ index state independently. pi-workflow never runs codegraph init automatically.

Companion packages

Companion package names and pinned versions are defined in assets/companions.json, which is the single source of truth. Updating a companion version is a repository change and should be reviewed like any other supported workflow change.

Configured companions:

| Package | Pinned version | | --- | --- | | gentle-engram | 0.1.10 | | pi-mcp-adapter | 2.11.0 | | @tintinweb/pi-subagents | 0.13.0 | | pi-web-access | 0.13.0 | | @vndv/pi-codegraph | 0.1.10 |

Scope

In scope:

• one local pi-workflow helper extension;
• status and doctor commands for configured companions;
• CodeGraph companion, CLI, and project-index readiness diagnostics;
• explicit companion installation after user confirmation;
• exact companion versions controlled by this repository;
• install and update documentation.

Out of scope:

• bundling third-party Pi package source;
• re-exporting third-party extensions or skills through this package manifest;
• silently installing companion packages;
• automatically initializing CodeGraph indexes;
• proprietary company workflow behavior;
• automatic companion upgrades.

Package design

Pi packages declare resources in package.json using the pi manifest. This package keeps that manifest intentionally small:

{
  "pi": {
    "extensions": ["./extensions/pi-workflow.ts"]
  }
}

Third-party packages are not runtime dependencies of this package because Pi installs them independently with pi install. The source of truth for companion names and versions is assets/companions.json.

Validation

Refresh the lockfile without running lifecycle scripts, then run the release guard:

npm install --package-lock-only --ignore-scripts
npm run check

The release guard validates that:

• the package name and public publish config are correct;
• pi-package is present in keywords;
• only the local pi-workflow extension is exposed;
• no Pi manifest paths point into node_modules;
• no bundledDependencies or bundleDependencies field exists;
• companion metadata includes the expected packages and versions;
• package metadata declares Node.js >=22.19;
• package scripts and release basics remain present;
• npm pack --dry-run succeeds.

Companion update policy

To update a companion:

1. Change the version in assets/companions.json.
2. Run npm install --package-lock-only --ignore-scripts if package metadata changed.
3. Run npm run check.
4. Review the upstream package changelog/source for new resources or behavior.
5. Update this README's companion table.
6. Open a GitHub release for the new version.
7. Let .github/workflows/publish.yml publish to npm with provenance.

Release CI/CD

CI runs on pushes and pull requests to main via .github/workflows/ci.yml. Publishing runs only when a GitHub release is published via .github/workflows/publish.yml.

The publish workflow uses npm provenance and requires the GitHub environment named npm. Configure that environment with the npm publishing token/secrets required by the repository before the first release.

Research notes

The initial package shape was informed by reviewing context-mode as a mature Pi package example. The project later chose the explicit meta-configuration model documented here. See:

• docs/research/context-mode-package-patterns.md