npm - pi-agent-toolkit - Versions diffs - 0.1.0 - Mend

pi-agent-toolkit 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (53) hide show

package/dist/dotfiles/AGENTS.md +197 -0
package/dist/dotfiles/APPEND_SYSTEM.md +78 -0
package/dist/dotfiles/agent-modes.json +12 -0
package/dist/dotfiles/agent-skills/exa-search/.env.example +4 -0
package/dist/dotfiles/agent-skills/exa-search/SKILL.md +234 -0
package/dist/dotfiles/agent-skills/exa-search/scripts/exa-api.cjs +197 -0
package/dist/dotfiles/auth.json.template +5 -0
package/dist/dotfiles/damage-control-rules.yaml +318 -0
package/dist/dotfiles/extensions/btw.ts +1031 -0
package/dist/dotfiles/extensions/commit-approval.ts +590 -0
package/dist/dotfiles/extensions/context.ts +578 -0
package/dist/dotfiles/extensions/control.ts +1748 -0
package/dist/dotfiles/extensions/damage-control/index.ts +543 -0
package/dist/dotfiles/extensions/damage-control/node_modules/.package-lock.json +22 -0
package/dist/dotfiles/extensions/damage-control/package-lock.json +28 -0
package/dist/dotfiles/extensions/damage-control/package.json +7 -0
package/dist/dotfiles/extensions/dirty-repo-guard.ts +56 -0
package/dist/dotfiles/extensions/exa-enforce.ts +51 -0
package/dist/dotfiles/extensions/exa-search-tool.ts +384 -0
package/dist/dotfiles/extensions/execute-command/index.ts +82 -0
package/dist/dotfiles/extensions/files.ts +1112 -0
package/dist/dotfiles/extensions/loop.ts +446 -0
package/dist/dotfiles/extensions/pr-approval.ts +730 -0
package/dist/dotfiles/extensions/qna-interactive.ts +532 -0
package/dist/dotfiles/extensions/question-mode.ts +242 -0
package/dist/dotfiles/extensions/require-session-name-on-exit.ts +141 -0
package/dist/dotfiles/extensions/review.ts +2091 -0
package/dist/dotfiles/extensions/session-breakdown.ts +1629 -0
package/dist/dotfiles/extensions/term-notify.ts +150 -0
package/dist/dotfiles/extensions/tilldone.ts +527 -0
package/dist/dotfiles/extensions/todos.ts +2082 -0
package/dist/dotfiles/extensions/tools.ts +146 -0
package/dist/dotfiles/extensions/uv.ts +123 -0
package/dist/dotfiles/global-skills/brainstorm/SKILL.md +10 -0
package/dist/dotfiles/global-skills/cli-detector/SKILL.md +192 -0
package/dist/dotfiles/global-skills/gh-issue-creator/SKILL.md +173 -0
package/dist/dotfiles/global-skills/google-chat-cards-v2/SKILL.md +237 -0
package/dist/dotfiles/global-skills/google-chat-cards-v2/references/bridge_tap_implementation.md +466 -0
package/dist/dotfiles/global-skills/technical-docs/SKILL.md +204 -0
package/dist/dotfiles/global-skills/technical-docs/references/diagrams.md +168 -0
package/dist/dotfiles/global-skills/technical-docs/references/examples.md +449 -0
package/dist/dotfiles/global-skills/technical-docs/scripts/validate_docs.py +352 -0
package/dist/dotfiles/global-skills/whats-new/SKILL.md +159 -0
package/dist/dotfiles/intercepted-commands/pip +7 -0
package/dist/dotfiles/intercepted-commands/pip3 +7 -0
package/dist/dotfiles/intercepted-commands/poetry +10 -0
package/dist/dotfiles/intercepted-commands/python +104 -0
package/dist/dotfiles/intercepted-commands/python3 +104 -0
package/dist/dotfiles/mcp.json.template +32 -0
package/dist/dotfiles/models.json +27 -0
package/dist/dotfiles/settings.json +25 -0
package/dist/index.js +1344 -0
package/package.json +34 -0

package/dist/dotfiles/AGENTS.md ADDED Viewed

@@ -0,0 +1,197 @@
+# AGENTS.md
+## Global Agent Rules
+These rules apply to all repositories unless a project-level AGENTS.md adds stricter rules.
+### Git safety
+- Do **not** create commits unless the user explicitly asks to commit.
+- Do **not** push branches unless the user explicitly asks to push.
+- **Never** use `--no-verify` when committing. All pre-commit hooks must pass.
+- After making code changes, stop at diff + validation results and ask for approval before any commit.
+- If the user asks to "proceed" or "continue," do not infer commit permission.
+### Commit message style
+When the user explicitly asks to commit, use Conventional Commits:
+```text
+<type>(<scope>): <subject>
+<body>
+<footer>
+```
+- Allowed types: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `style`, `perf`, `ci`, `build`
+- Use imperative mood (e.g., "add" not "added")
+- Start subject lowercase, no trailing punctuation, max 50 chars
+- Separate subject/body with a blank line; wrap body at 72 chars
+- Focus on **why** (the diff already shows what changed)
+- No AI attribution and no emojis
+- **Always include a body** — single-line commits are not acceptable
+Example:
+```text
+feat(search): add debounced input to federated search
+The raw keypress handler was firing a request per keystroke,
+causing rate-limit hits on accounts with many companies.
+Added a 300ms debounce using useRef + setTimeout so requests
+only fire after the user stops typing.
+```
+### Pull request style
+When the user explicitly asks to create a PR, always provide a title and body.
+**Title**: Short, descriptive summary of the change (imperative mood, max 72 chars).
+**Body** format:
+```text
+## What changed
+Concise summary of the changes. List key files or areas affected.
+## Why
+Motivation, context, or problem being solved. Link related issues if applicable.
+## How tested
+What validation was done — tests added/updated, manual checks, commands run.
+## Notes (optional)
+Breaking changes, follow-ups, deployment considerations, or anything reviewers should know.
+```
+- Be reasonably detailed without being verbose — a reviewer should understand the change without reading every diff line
+- No AI attribution and no emojis
+- Always use `--title` and `--body` flags with `gh pr create`
+Example:
+```text
+Title: fix(cache): prevent stale Redis entries after credential rotation
+Body:
+## What changed
+Updated `src/lib/cache/query-cache.ts` to include a credential version
+hash in cache keys. Added a cache-bust helper in `src/lib/credentials/`.
+## Why
+After rotating a company's database credentials, cached query results
+continued using the old connection pool key, returning stale or errored
+responses until TTL expiry.
+## How tested
+- Added unit tests for new cache key generation
+- Verified manually by rotating credentials and confirming immediate
+  cache invalidation
+- Ran full CI suite, all checks pass
+## Notes
+Existing cache entries will expire naturally via TTL. No migration needed.
+```
+### Code style
+- Do **not** use emojis in code (strings, comments, log messages, docstrings).
+- To make text stand out, use colors (ANSI codes), bolding, or ASCII symbols instead of emojis.
+### Try before asking
+When about to ask the user whether they have a tool, command, or dependency installed -- don't ask, just try it. If it works, proceed. If it fails, inform the user and suggest installation. Saves back-and-forth and gives a definitive answer immediately.
+### Verify before claiming done
+Never claim success without proving it. Before saying "done", "fixed", or "tests pass":
+1. Run the actual verification command.
+2. Show the output.
+3. Confirm it matches the claim.
+Evidence before assertions. If about to say "should work now" -- stop. That's a guess. Run the command first.
+### Investigate before fixing
+When something breaks, don't guess -- investigate first. No fixes without understanding the root cause:
+1. **Observe** -- Read error messages carefully, check the full stack trace.
+2. **Hypothesize** -- Form a theory based on evidence.
+3. **Verify** -- Test the hypothesis before implementing a fix.
+4. **Fix** -- Target the root cause, not the symptom.
+Avoid shotgun debugging. If making random changes hoping something works, the problem isn't understood yet.
+### Clean up after yourself
+Never leave debugging or testing artifacts in the codebase:
+- `console.log` / `print` statements added for debugging -- remove once understood.
+- Commented-out code used for testing alternatives -- delete, don't commit.
+- Temporary test files, scratch scripts, throwaway fixtures -- delete when done.
+- Hardcoded test values (URLs, tokens, IDs) -- revert to proper configuration.
+- Disabled tests or skipped assertions (`it.skip`, `xit`, `@Ignore`) -- re-enable or remove.
+Before every commit, scan changes for artifacts. If `git diff` shows `console.log("DEBUG")`, a `TODO: remove this`, or a commented-out block -- clean it up first.
+### Path discipline
+- Do **not** read, search, or inspect files inside `node_modules/` by default.
+- Treat `node_modules/` as off-limits unless the user explicitly asks to inspect an installed dependency/package or the installed package is the only source of truth for the behavior in question.
+- If inspection of `node_modules/` is genuinely necessary and the user did not explicitly ask for it, ask for permission first.
+- When inspection is allowed, keep it tightly scoped to the smallest possible set of named files and never run broad recursive searches over `node_modules/`.
+- **Exception — Pi packages:** Reading files under `@mariozechner/` is always allowed without permission. This namespace contains Pi and its related packages (docs, examples, extensions, themes, skills, SDK source).
+### Default workflow
+1. Make requested edits.
+2. Run relevant checks (lint/typecheck/tests as appropriate).
+3. Report changed files and results.
+4. Wait for explicit commit/push instruction.
+### cmux environment
+This machine runs cmux (Ghostty-based terminal multiplexer).
+When `CMUX_WORKSPACE_ID` is set, the following are available:
+**Notifications** — use after long-running tasks complete or fail:
+```bash
+cmux notify --title "Done" --body "All tests passed"
+cmux notify --title "Failed" --body "3 lint errors"
+```
+**Visual flash** — draw attention to a surface or workspace:
+```bash
+cmux trigger-flash
+```
+**Sidebar metadata** — surface progress and status at a glance:
+```bash
+cmux set-status build "running" --color "#ff9500"
+cmux set-progress 0.5 --label "Building..."
+cmux log --level success "Deploy complete"
+```
+**Subagent in split pane** — spawn work in a new split, then read results:
+```bash
+cmux new-split right
+cmux send --surface surface:N "command\n"
+cmux read-screen --surface surface:N --lines 50
+```
+Detailed usage is covered by the `cmux`, `cmux-and-worktrees`, and
+`cmux-browser` skills — load those for full reference.

package/dist/dotfiles/APPEND_SYSTEM.md ADDED Viewed

@@ -0,0 +1,78 @@
+## Rule priority
+When instructions in this file conflict with project-level AGENTS.md rules, this file takes precedence. Within this file, more specific rules override general ones.
+## Reasoning and feedback quality
+- Avoid sycophancy and uncritical agreement.
+- Challenge user assumptions respectfully when needed.
+- Ground responses in facts, best practices, and clear logic.
+- Present pros and cons (trade-offs) to the user instead of always agreeing.
+- If a user request conflicts with evidence or best practices, explain why and propose better alternatives.
+## jCodeMunch MCP usage policy
+- On session start, **only if the current working directory is inside a git
+  repository** (i.e., `git rev-parse --is-inside-work-tree` succeeds), call
+  `jcodemunch_index_folder` with `path` set to the current working directory.
+  Skip indexing entirely for non-repo directories (e.g., `~`, `~/Downloads`,
+  `~/Documents`) to avoid needlessly indexing personal files. Incremental
+  indexing (the default) is cheap — it only re-processes changed files, so
+  this is safe to run unconditionally when inside a repo. If the call fails
+  on the first attempt (server still connecting), retry once before falling
+  back.
+- All jCodeMunch tools are prefixed with `jcodemunch_`. The `index_folder`
+  tool requires the parameter name `path` (not `folder_path`).
+- **Do not begin code exploration until `index_folder` has fully completed.**
+  Wait for the indexing result before calling any other jCodeMunch tools or
+  reading source files. Never index "in parallel" with analysis.
+- Re-index (`index_folder`) after git pull, branch switches, or when retrieved
+  symbols appear stale or do not match file contents.
+- For code exploration and understanding, prefer jCodeMunch tools over reading
+  full files:
+  - Use `get_repo_outline` or `get_file_tree` to understand project structure.
+  - Use `search_symbols` to locate functions, classes, and methods by name.
+  - Use `get_symbol` or `get_symbols` for precise source retrieval.
+  - Use `get_context_bundle` before making edits to understand a symbol's
+    imports, neighbors, and related code.
+  - Use `get_blast_radius` before modifying widely-used symbols.
+  - Use `get_file_outline` to inspect a file's symbols before pulling source.
+- Reserve Read/Bash/grep for: exact-string lookups (error messages, config
+  values, log text), non-code files (config, JSON, YAML, markdown), and files
+  outside the indexed repository.
+## Documentation lookups
+- When giving advice about library/framework APIs, state your confidence
+  level about version currency.
+- If the user is working with a recent or rapidly-changing library, use
+  Exa to verify against current docs before answering.
+- When uncertain about API details, search the library's official docs
+  site via Exa (e.g., includeDomains: ["react.dev"]) rather than
+  guessing from training data.
+- Do not substitute browser automation or ad-hoc web fetching for normal
+  documentation lookup when Exa is available. If Exa cannot satisfy the
+  request, say so explicitly before considering another path.
+## Tool-first approach
+- Before writing custom code to accomplish a task, scan all available tools (MCP servers, skills, CLI utilities) for existing capabilities that already handle the request.
+- Purpose-built tools are often faster, more reliable, and better maintained than ad-hoc scripts.
+- Only fall back to writing custom code when no available tool covers the requirement or when the tool's output needs non-trivial post-processing.
+## Writing style
+- Never use em dashes (--) in responses, written content, or any text the user may copy and paste.
+- Use alternatives instead: commas, parentheses, colons, semicolons, or separate sentences.
+## External data preference
+- For factual claims, version-specific APIs, and time-sensitive information, prefer external verification over internal knowledge.
+- If accuracy is uncertain or information may be outdated, search for external data before answering.
+- Do not guess when data can be retrieved. When in doubt, retrieve.
+- If information cannot be confidently verified, state the uncertainty explicitly rather than presenting it as fact.
+- Ask a clarifying question if missing inputs would lead to an unreliable answer.
+- For web search, semantic lookup, similar-page discovery, and general web research, use the `exa_search` tool.
+- Do not use ad-hoc web search methods (`python requests`, `curl`, direct scraping) unless the user explicitly requests direct URL fetch.
+- Do not use browser automation as a fallback for ordinary web lookup when Exa can handle the task. Reserve browser tools for interactive flows, authentication, screenshots, UI testing, or explicit user requests.
+- Prefer responses with cited source links from search results.

package/dist/dotfiles/agent-modes.json ADDED Viewed

@@ -0,0 +1,12 @@
+{
+  "debug": {
+    "provider": "openai-codex",
+    "model": "gpt-5.4",
+    "thinkingLevel": "medium"
+  },
+  "review": {
+    "provider": "openai-codex",
+    "model": "gpt-5.4",
+    "thinkingLevel": "medium"
+  }
+}

package/dist/dotfiles/agent-skills/exa-search/.env.example ADDED Viewed

@@ -0,0 +1,4 @@
+# Exa API Key Configuration
+# Get your API key from: https://dashboard.exa.ai/api-keys
+EXA_API_KEY=your_api_key_here

package/dist/dotfiles/agent-skills/exa-search/SKILL.md ADDED Viewed

@@ -0,0 +1,234 @@
+---
+name: exa-search
+description: "Semantic web search and structured research using Exa. Use when you need web search, semantic search, similar-page discovery, content extraction from search results, direct answers with sources, or structured research over web sources. Triggers: exa, web search, semantic search, find similar, research, docs lookup, github search."
+compatibility: "Requires Node.js plus an Exa API key via EXA_API_KEY or .env in this skill directory."
+---
+# Exa Search
+Use this skill as the default Pi pathway for web search and research.
+This skill is intentionally Pi-native. It does **not** rely on Claude-specific task orchestration or legacy harness path conventions. When this skill is loaded, choose the right Exa endpoint, build a JSON payload, run the local helper script with `bash`, and summarize the results with source links.
+## When to use it
+Use this skill when the user needs:
+- semantic web search
+- similar-page discovery from an existing URL
+- content extraction from known Exa result IDs
+- a direct answer sourced from web search
+- structured research output over web sources
+- current docs or recent web information that should not be guessed from memory
+Do **not** use ad-hoc web fetching (`curl`, `wget`, custom requests scripts) when Exa can handle the request. This skill is the sanctioned web-search path for this Pi setup.
+## Explicit invocation
+You can load it directly with:
+```text
+/skill:exa-search <user request>
+```
+When invoked this way, treat the appended text as the user’s actual search/research request.
+## Endpoint selection
+Choose the endpoint that best matches intent:
+- **search** — semantic web search, finding pages, docs, articles, repos, or papers
+- **contents** — fetch full content for known Exa result IDs
+- **findsimilar** — find pages similar to a given URL
+- **answer** — produce a direct answer backed by Exa results
+- **research** — produce structured research output following a requested schema
+## Standard workflow
+1. Understand the user’s question.
+2. Pick the correct Exa endpoint.
+3. Build a focused JSON payload.
+4. Run the helper script with `bash`.
+5. Read the JSON response.
+6. Return a concise answer with cited source links.
+If the user asks for current framework or library guidance, prefer official docs by setting `includeDomains` when appropriate.
+## Helper script
+Use the local helper script in this skill directory:
+```text
+scripts/exa-api.cjs
+```
+Run it with `node` and provide JSON through stdin, `--data`, or `--file`.
+### General form
+```bash
+cat <<'JSON' | node scripts/exa-api.cjs <search|contents|findsimilar|answer|research>
+{ ...payload... }
+JSON
+```
+## Payload examples
+### 1) Search
+```bash
+cat <<'JSON' | node scripts/exa-api.cjs search
+{
+  "query": "Latest research in LLMs",
+  "type": "auto",
+  "numResults": 10,
+  "category": "research paper",
+  "includeDomains": [],
+  "excludeDomains": [],
+  "startPublishedDate": "2025-01-01",
+  "endPublishedDate": "2025-12-31",
+  "includeText": [],
+  "excludeText": [],
+  "contents": {
+    "text": true,
+    "highlights": true,
+    "summary": true
+  }
+}
+JSON
+```
+**Search types:**
+- `neural` — semantic search using embeddings
+- `fast` — faster keyword-oriented search
+- `auto` — default unless you have a reason to force another mode
+- `deep` — more exhaustive search
+**Common categories:**
+- `company`
+- `people`
+- `research paper`
+- `news`
+- `pdf`
+- `github`
+- `tweet`
+### 2) Contents
+```bash
+cat <<'JSON' | node scripts/exa-api.cjs contents
+{
+  "ids": ["result-id-1", "result-id-2"],
+  "text": true,
+  "highlights": true,
+  "summary": true
+}
+JSON
+```
+### 3) Find Similar
+```bash
+cat <<'JSON' | node scripts/exa-api.cjs findsimilar
+{
+  "url": "https://example.com/article",
+  "numResults": 10,
+  "category": "news",
+  "includeDomains": [],
+  "excludeDomains": [],
+  "startPublishedDate": "2025-01-01",
+  "contents": {
+    "text": true,
+    "summary": true
+  }
+}
+JSON
+```
+### 4) Answer
+```bash
+cat <<'JSON' | node scripts/exa-api.cjs answer
+{
+  "query": "What is the capital of France?",
+  "numResults": 5,
+  "includeDomains": [],
+  "excludeDomains": []
+}
+JSON
+```
+### 5) Research
+```bash
+cat <<'JSON' | node scripts/exa-api.cjs research
+{
+  "input": "What are the latest developments in AI?",
+  "model": "auto",
+  "stream": false,
+  "output_schema": {
+    "properties": {
+      "topic": {
+        "type": "string",
+        "description": "The main topic"
+      },
+      "key_findings": {
+        "type": "array",
+        "description": "List of key findings",
+        "items": {
+          "type": "string"
+        }
+      }
+    },
+    "required": ["topic"]
+  },
+  "citation_format": "numbered"
+}
+JSON
+```
+## API key configuration
+The helper script checks for an API key in this order:
+1. `EXA_API_KEY` environment variable
+2. `.env` in this skill directory
+3. `.env` next to `scripts/exa-api.cjs`
+Example `.env`:
+```dotenv
+EXA_API_KEY=your_api_key_here
+```
+## Response handling
+The helper returns JSON. Typical fields include:
+- `requestId`
+- `results`
+- `searchType`
+- `context`
+- `costDollars`
+After the helper runs:
+- extract the most relevant findings
+- cite source URLs clearly
+- say when results are uncertain, sparse, or potentially stale
+- prefer official documentation domains when the task is about APIs or framework behavior
+## Practical guidance
+- Keep search queries specific and realistic.
+- Use `includeDomains` for official docs when verifying APIs.
+- Use `excludeDomains` to avoid noisy sources.
+- Use `contents` when you already have Exa result IDs and need fuller text.
+- Use `findsimilar` when the user gives a canonical page and wants adjacent resources.
+- Use `research` only when the user truly needs structured synthesis.
+- Do not dump raw JSON unless the user asks for it.
+## Output style
+Return concise, decision-useful results:
+- short summary first
+- then key findings
+- then source links
+- mention limitations or uncertainty when relevant