@spences10/pi-tool-guidance 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Scott Spence
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,86 @@
-# Temporary Holding Version
+# @spences10/pi-tool-guidance
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<!-- package-readme:header:start -->
+
+[![built with Vite+](https://img.shields.io/badge/built%20with-Vite+-646CFF?logo=vite&logoColor=white)](https://viteplus.dev)
+[![tested with Vitest](https://img.shields.io/badge/tested%20with-Vitest-6E9F18?logo=vitest&logoColor=white)](https://vitest.dev)
+[![npm version](https://img.shields.io/npm/v/@spences10/pi-tool-guidance?color=CB3837&logo=npm&logoColor=white)](https://www.npmjs.com/package/@spences10/pi-tool-guidance)
+[![license](https://img.shields.io/npm/l/@spences10/pi-tool-guidance)](https://www.npmjs.com/package/@spences10/pi-tool-guidance)
+
+![my-pi package preview](https://raw.githubusercontent.com/spences10/my-pi/main/assets/pi-package-preview.png)
+
+<!-- package-readme:header:end -->
+
+## Tool workflow guidance
+
+Distributes native Pi skills and concise system-prompt reminders for
+nopeek, Omnisearch, and SQLite. It does not depend on the maintainer's
+local files.
+
+## What ships
+
+- `my-pi-nopeek`: one-shot credential loading, explicit key
+  allowlists, separate-shell limitations, and output disclosure
+  precautions.
+- `my-pi-omnisearch`: tool discovery, source extraction, and verified
+  research.
+- `my-pi-sqlite`: schema inspection, bounded queries, backups,
+  transactions, and respecting database safety gates.
+
+Pi advertises these native skills and loads their full contents on
+demand. Invoke `/skill:my-pi-nopeek`, `/skill:my-pi-omnisearch`, or
+`/skill:my-pi-sqlite` to request one explicitly.
+
+Essential reminders are contributed through a named structured prompt
+section. Secret guidance is active with shell access; MCP guidance is
+conditional on reachable tools or Pi's configured indirect-server
+listing. Both codemode and tool-search exposure work without requiring
+direct tool declarations.
+
+## User configuration remains yours
+
+The package does not install the nopeek CLI, start MCP servers, set
+provider credentials, or modify `SYSTEM.md`, `APPEND_SYSTEM.md`, or
+`mcp.json`. Configure the required tools through Pi's normal
+mechanisms. Native prompt files coexist with the package's section;
+disabling this extension removes its bundled resources on reload in
+my-pi.
+
+Instructions are guidance, not a security boundary. Child processes
+can still print secrets; redaction and database permission enforcement
+remain separate. Third-party extensions that force a complete prompt
+can hide later structured sections; prefer Pi's structured prompt API.
+
+Bundled into my-pi as `tool-guidance`. Use
+`/extensions disable tool-guidance` to remove its reminders and
+bundled skills on reload. The package manifest exposes the same skills
+in standalone Pi.
+
+## Install
+
+<!-- package-readme:install:start -->
+
+```bash
+pi install npm:@spences10/pi-tool-guidance
+```
+
+<!-- package-readme:install:end -->
+
+## Development
+
+<!-- package-readme:development:start commands="check,test,build" -->
+
+Package scripts build transitive workspace dependencies first, then
+run local tools through Vite+ with `vp exec`.
+
+```bash
+pnpm --filter @spences10/pi-tool-guidance run check
+pnpm --filter @spences10/pi-tool-guidance run test
+pnpm --filter @spences10/pi-tool-guidance run build
+```
+
+<!-- package-readme:development:end -->
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+import type { BuildSystemPromptOptions, ExtensionAPI } from '@earendil-works/pi-coding-agent';
+type Tool = Pick<ReturnType<ExtensionAPI['getAllTools']>[number], 'name' | 'exposure' | 'namespace'>;
+export declare function tool_guidance(options: BuildSystemPromptOptions, tools: readonly Tool[]): string;
+export default function tool_guidance_extension(pi: ExtensionAPI): void;
+export {};

package/dist/index.js

@@ -0,0 +1,51 @@
+const NOPEEK_GUIDANCE = `## Secret-safe commands
+Never read secret files or print credential values into model context. Read the bundled my-pi-nopeek skill before credential-dependent commands. Use one-shot nopeek run with only the required keys; separate Pi shells do not share loaded environment changes. Child-process output can still leak secrets; redaction is best-effort, not a guarantee.`;
+const OMNISEARCH_GUIDANCE = `## Web research
+For research and current external facts, prefer the configured Omnisearch MCP server. Read the bundled my-pi-omnisearch skill. Discover its actual tools with tool search or codemode, and read source content before presenting claims; snippets alone are not verification.`;
+const SQLITE_GUIDANCE = `## SQLite databases
+Prefer the configured SQLite MCP tools over ad-hoc shell SQL. Read the bundled my-pi-sqlite skill; inspect schema before querying, keep result limits small, and prefer a backup plus an explicit transaction before authorized writes. Do not bypass safety gates to make destructive operations easier.`;
+export function tool_guidance(options, tools) {
+    const selected = options.selectedTools ?? [
+        'read',
+        'bash',
+        'edit',
+        'write',
+    ];
+    const indirect = selected.includes('codemode') || selected.includes('tool_search');
+    const reachable = tools.filter((tool) => tool.exposure !== 'hidden' &&
+        (selected.includes(tool.name) ||
+            (indirect &&
+                ['codemode', 'deferred'].includes(tool.exposure))));
+    const names = reachable
+        .flatMap((tool) => [
+        tool.name,
+        tool.namespace?.name ?? '',
+        ...(tool.namespace?.aliases ?? []),
+    ])
+        .join('\n');
+    // Pi lists configured indirect servers before their background connections complete.
+    const servers = indirect
+        ? (options.sections?.mcp_servers ?? '')
+        : '';
+    const available = `${names}\n${servers}`.toLowerCase();
+    const shell = selected.some((name) => ['bash', 'powershell'].includes(name)) ||
+        reachable.some((tool) => ['bash', 'powershell'].includes(tool.name));
+    return [
+        shell ? NOPEEK_GUIDANCE : '',
+        available.includes('omnisearch') ? OMNISEARCH_GUIDANCE : '',
+        available.includes('sqlite') ? SQLITE_GUIDANCE : '',
+    ]
+        .filter(Boolean)
+        .join('\n\n');
+}
+export default function tool_guidance_extension(pi) {
+    pi.on('before_agent_start', (event) => {
+        const guidance = tool_guidance(event.systemPromptOptions, pi.getAllTools());
+        if (guidance)
+            event.systemPromptOptions.sections.my_pi_tool_guidance =
+                guidance;
+        else
+            delete event.systemPromptOptions.sections.my_pi_tool_guidance;
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAUA,MAAM,eAAe,GAAG;0VACkU,CAAC;AAE3V,MAAM,mBAAmB,GAAG;8QACkP,CAAC;AAE/Q,MAAM,eAAe,GAAG;0SACkR,CAAC;AAE3S,MAAM,UAAU,aAAa,CAC5B,OAAiC,EACjC,KAAsB;IAEtB,MAAM,QAAQ,GAAG,OAAO,CAAC,aAAa,IAAI;QACzC,MAAM;QACN,MAAM;QACN,MAAM;QACN,OAAO;KACP,CAAC;IACF,MAAM,QAAQ,GACb,QAAQ,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,QAAQ,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC;IACnE,MAAM,SAAS,GAAG,KAAK,CAAC,MAAM,CAC7B,CAAC,IAAI,EAAE,EAAE,CACR,IAAI,CAAC,QAAQ,KAAK,QAAQ;QAC1B,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC;YAC5B,CAAC,QAAQ;gBACR,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CACrD,CAAC;IACF,MAAM,KAAK,GAAG,SAAS;SACrB,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;QAClB,IAAI,CAAC,IAAI;QACT,IAAI,CAAC,SAAS,EAAE,IAAI,IAAI,EAAE;QAC1B,GAAG,CAAC,IAAI,CAAC,SAAS,EAAE,OAAO,IAAI,EAAE,CAAC;KAClC,CAAC;SACD,IAAI,CAAC,IAAI,CAAC,CAAC;IACb,qFAAqF;IACrF,MAAM,OAAO,GAAG,QAAQ;QACvB,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,WAAW,IAAI,EAAE,CAAC;QACvC,CAAC,CAAC,EAAE,CAAC;IACN,MAAM,SAAS,GAAG,GAAG,KAAK,KAAK,OAAO,EAAE,CAAC,WAAW,EAAE,CAAC;IACvD,MAAM,KAAK,GACV,QAAQ,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC9D,SAAS,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CACvB,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAC1C,CAAC;IACH,OAAO;QACN,KAAK,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE;QAC5B,SAAS,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,EAAE;QAC3D,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE;KACnD;SACC,MAAM,CAAC,OAAO,CAAC;SACf,IAAI,CAAC,MAAM,CAAC,CAAC;AAChB,CAAC;AAED,MAAM,CAAC,OAAO,UAAU,uBAAuB,CAC9C,EAAgB;IAEhB,EAAE,CAAC,EAAE,CAAC,oBAAoB,EAAE,CAAC,KAAK,EAAE,EAAE;QACrC,MAAM,QAAQ,GAAG,aAAa,CAC7B,KAAK,CAAC,mBAAmB,EACzB,EAAE,CAAC,WAAW,EAAE,CAChB,CAAC;QACF,IAAI,QAAQ;YACX,KAAK,CAAC,mBAAmB,CAAC,QAAQ,CAAC,mBAAmB;gBACrD,QAAQ,CAAC;;YAEV,OAAO,KAAK,CAAC,mBAAmB,CAAC,QAAQ,CAAC,mBAAmB,CAAC;IAChE,CAAC,CAAC,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,65 @@
 {
   "name": "@spences10/pi-tool-guidance",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Packaged nopeek, Omnisearch and SQLite workflow guidance for Pi",
+  "keywords": [
+    "pi",
+    "pi-package"
+  ],
+  "homepage": "https://github.com/spences10/my-pi/tree/main/packages/pi-tool-guidance#readme",
+  "license": "MIT",
+  "author": "Scott Spence <me@scottspence.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/spences10/my-pi.git",
+    "directory": "packages/pi-tool-guidance"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "skills"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "1.4.0",
+    "@types/node": "^26.0.0",
+    "typescript": "^7.0.0",
+    "vite-plus": "1.4.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=1.4.0"
+  },
+  "engines": {
+    "node": ">=24.15.0"
+  },
+  "pi": {
+    "extensions": [
+      "./dist/index.js"
+    ],
+    "image": "https://raw.githubusercontent.com/spences10/my-pi/main/assets/pi-package-preview.png",
+    "skills": [
+      "./skills"
+    ]
+  },
+  "scripts": {
+    "build": "pnpm --filter \"$npm_package_name^...\" run build:self && pnpm run build:self",
+    "build:self": "vp exec tsc -p tsconfig.build.json",
+    "check": "pnpm --filter \"$npm_package_name^...\" run build:self && pnpm run check:self",
+    "check:self": "vp exec tsc --noEmit -p tsconfig.json",
+    "test": "pnpm --filter \"$npm_package_name^...\" run build:self && pnpm run test:self",
+    "test:self": "vp test run",
+    "coverage:self": "vp test run --coverage",
+    "coverage": "pnpm --filter \"$npm_package_name^...\" run build:self && pnpm run coverage:self"
+  }
 }

package/skills/my-pi-nopeek/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: my-pi-nopeek
+# prettier-ignore
+description: Use when loading .env credentials, running authenticated commands, or keeping secret values out of Pi context.
+compatibility: Requires Pi with shell access and the nopeek CLI.
+---
+
+# Credential-dependent commands
+
+Use the nopeek CLI to reduce accidental disclosure. This skill does
+not install hooks, load credentials automatically, or guarantee safe
+output.
+
+1. Inspect key names with `pnpx nopeek list` or `pnpx nopeek status`;
+   never read secret files into model context.
+2. In pnpm projects use `pnpx nopeek`; otherwise use `npx nopeek`.
+3. Prefer one-shot execution with an explicit key allowlist:
+
+   ```bash
+   pnpx nopeek run .env --only DATABASE_URL -- sh -c 'psql "$DATABASE_URL" -c "select 1"'
+   ```
+
+4. Keep variable expansion inside the child shell. Do not print keys,
+   run `env`/`printenv`, enable tracing, or place secret values in
+   arguments.
+5. Review what the child command prints: nopeek cannot prevent
+   arbitrary applications from leaking credentials through stdout or
+   stderr.
+6. Use `nopeek load` only with confirmed persistent harness injection,
+   or when loading and execution happen in the same trusted shell. A
+   source-file result does not persist into another Pi tool call.
+7. Use `pnpx nopeek audit` for exposure and gitignore checks.
+
+Pi's redaction extension is a separate best-effort safety net, not a
+security boundary. If secret output is unavoidable, stop and agree on
+a safer workflow rather than exposing it.
+
+The CLI must be available through the user's package runner or
+installed locally. Do not change their credential storage or
+configuration implicitly. See
+[nopeek's threat model](https://github.com/spences10/nopeek#threat-model-and-non-goals).

package/skills/my-pi-omnisearch/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: my-pi-omnisearch
+# prettier-ignore
+description: Use when researching current facts, verifying documentation, or finding sources with a configured Omnisearch MCP server.
+compatibility: Requires Pi with a configured Omnisearch MCP server.
+---
+
+# Verified web research
+
+This skill supplies guidance, not an MCP server or provider
+credentials. Use the user's configured integration; do not install or
+configure one without authorization.
+
+1. Discover the actual namespace and tool names. In codemode use
+   `searchTools("web search")`, `describeNamespace(namespace)`, and
+   `describeTool(name)`; use tool search when that is the available
+   route. Never assume hyphenated server names are valid JavaScript
+   identifiers.
+2. Use `web_search` for discovery. Choose providers deliberately:
+   Tavily for factual/cited searches, Brave or Kagi for operators, and
+   Exa for semantic discovery, when those providers are available.
+3. Use `web_extract` to read actual source content before making
+   claims. Search snippets alone are not verified evidence.
+4. Use `ai_search` when a synthesis with sources helps; verify
+   important claims against those sources.
+5. Prefer official documentation, repositories, release notes, and
+   source. State source conflicts, uncertainty, and partial tool
+   failures.
+6. In codemode inspect MCP `isError` results, not just promise
+   resolution.
+
+If the server is unavailable, say so and use an available research
+tool without claiming Omnisearch verified the result. Never invent
+sources.

package/skills/my-pi-sqlite/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: my-pi-sqlite
+# prettier-ignore
+description: Use when inspecting, querying, or modifying SQLite databases through a configured SQLite MCP server.
+compatibility: Requires Pi with a configured SQLite MCP server.
+---
+
+# SQLite workflow
+
+This skill does not install an MCP server, open databases
+automatically, or authorize writes. Keep the user's server
+configuration and permissions.
+
+1. Discover actual tool names with codemode `searchTools("SQLite")`,
+   `describeNamespace(namespace)`, and `describeTool(name)`, or tool
+   search.
+2. Use `open_database` for existing files. Use `create_database` only
+   when creating a database is explicitly intended.
+3. Inspect with `database_info`, `list_tables`, `describe_table`, or
+   `export_schema` before constructing queries.
+4. Use `execute_read_query` for SELECT, PRAGMA, and EXPLAIN. Keep
+   limits small, avoid selecting credential columns, and bound
+   model-visible output.
+5. Before authorized writes or schema changes, prefer
+   `backup_database` and an explicit transaction. Use
+   `execute_write_query` or `execute_schema_query` only when the
+   intent and affected data are clear.
+6. Commit only on success; roll back failed transactions. Close
+   databases with `close_database` when finished.
+7. In codemode inspect MCP `isError` results before continuing.
+
+Prefer MCP over raw sqlite3 or one-off Python SQL scripts. Use a shell
+fallback only when MCP is unavailable or the user explicitly requests
+it, and retain the same backup, transaction, and approval precautions.
+Never bypass MCP safety gates merely to make destructive SQL easier.