pi-skill-search 0.1.0

package/skills/mem-search/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: mem-search
+description: Search claude-mem's persistent cross-session memory database. Use when user asks "did we already solve this?", "how did we do X last time?", or needs work from previous sessions.
+---
+
+# Memory Search
+
+Search past work across all sessions. Simple workflow: search -> filter -> fetch.
+
+## When to Use
+
+Use when users ask about PREVIOUS sessions (not current conversation):
+
+- "Did we already fix this?"
+- "How did we solve X last time?"
+- "What happened last week?"
+
+## 3-Layer Workflow (ALWAYS Follow)
+
+**NEVER fetch full details without filtering first. 10x token savings.**
+
+### Step 1: Search - Get Index with IDs
+
+Use the `search` MCP tool:
+
+```
+search(query="authentication", limit=20, project="my-project")
+```
+
+**Returns:** Table with IDs, timestamps, types, titles (~50-100 tokens/result)
+
+```
+| ID | Time | T | Title | Read |
+|----|------|---|-------|------|
+| #11131 | 3:48 PM | 🟣 | Added JWT authentication | ~75 |
+| #10942 | 2:15 PM | 🔴 | Fixed auth token expiration | ~50 |
+
+### Step 2: Timeline - Get Context Around Interesting Results
+
+Use the `timeline` MCP tool:
+
+```
+timeline(anchor=11131, depth_before=3, depth_after=3, project="my-project")
+```
+
+Or find anchor automatically from query:
+
+```
+timeline(query="authentication", depth_before=3, depth_after=3, project="my-project")
+```
+
+**Returns:** `depth_before + 1 + depth_after` items in chronological order with observations, sessions, and prompts interleaved around the anchor.
+
+### Step 3: Fetch - Get Full Details ONLY for Filtered IDs
+
+Review titles from Step 1 and context from Step 2. Pick relevant IDs. Discard the rest.
+
+Use the `get_observations` MCP tool:
+
+```
+get_observations(ids=[11131, 10942])
+```
+
+**ALWAYS use `get_observations` for 2+ observations - single request vs N requests.**
+
+**Parameters:**
+
+- `ids` (array of numbers, required) - Observation IDs to fetch
+
+## Examples
+
+**Find recent bug fixes:**
+
+```
+search(query="bug", type="observations", obs_type="bugfix", limit=20, project="my-project")
+```
+
+**Find what happened last week:**
+
+```
+search(type="observations", dateStart="2025-11-11", limit=20, project="my-project")
+```
+
+**Understand context around a discovery:**
+
+## Why This Workflow?
+
+- **Search index:** ~50-100 tokens per result
+- **Full observation:** ~500-1000 tokens each
+- **Batch fetch:** 1 HTTP request vs N individual requests
+- **10x token savings** by filtering before fetching
+
+## Knowledge Agents
+
+Want synthesized answers instead of raw records? Use `/knowledge-agent` to build a queryable corpus from your observation history. The knowledge agent reads all matching observations and answers questions conversationally.
+```

package/skills/modal/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: modal
+description: Cloud computing platform for running Python on GPUs and serverless infrastructure. Use when deploying AI/ML models, running GPU-accelerated workloads, serving web endpoints, scheduling batch jobs, or scaling Python code to the cloud. Use this skill whenever the user mentions Modal, serverless GPU compute, deploying ML models to the cloud, serving inference endpoints, running batch processing in the cloud, or needs to scale Python workloads beyond their local machine. Also use when the user wants to run code on H100s, A100s, or other cloud GPUs, or needs to create a web API for a model.
+---
+
+# Modal
+
+## Overview
+
+Modal is a cloud platform for running Python code serverlessly, with a focus on AI/ML workloads. Key capabilities:
+- **GPU compute** on demand (T4, L4, A10, L40S, A100, H100, H200, B200)
+- **Serverless functions** with autoscaling from zero to thousands of containers
+- **Custom container images** built entirely in Python code
+- **Persistent storage** via Volumes for model weights and datasets
+- **Web endpoints** for serving models and APIs
+- **Scheduled jobs** via cron or fixed intervals
+- **Sub-second cold starts** for low-latency inference
+
+Everything in Modal is defined as code — no YAML, no Dockerfiles required (though both are supported).
+
+## When to Use This Skill
+
+Use this skill when:
+- Deploy or serve AI/ML models in the cloud
+- Run GPU-accelerated computations (training, inference, fine-tuning)
+- Create serverless web APIs or endpoints
+- Scale batch processing jobs in parallel
+- Schedule recurring tasks (data pipelines, retraining, scraping)
+- Need persistent cloud storage for model weights or datasets
+- Want to run code in custom container environments
+- Build job queues or async task processing systems
+
+### Authenticate
+
+Prefer existing credentials before creating new ones:
+
+1. Check whether `MODAL_TOKEN_ID` and `MODAL_TOKEN_SECRET` are already present in the current environment.
+2. If not, check for those values in a local `.env` file and load them if appropriate for the workflow.
+3. Only fall back to interactive `modal setup` or generating fresh tokens if neither source already provides credentials.
+
+```bash
+modal setup
+```
+
+This opens a browser for authentication. For CI/CD or headless environments, use environment variables:
+
+```bash
+
+## Core Concepts
+
+### App and Functions
+
+A Modal `App` groups related functions. Functions decorated with `@app.function()` run remotely in the cloud:
+
+```python
+import modal
+
+app = modal.App("my-app")
+
+@app.function()
+def square(x):
+    return x ** 2
+
+@app.local_entrypoint()
+def main():
+
+### Container Images
+
+Modal builds container images from Python code. The recommended package installer is `uv`:
+
+```python
+image = (
+    modal.Image.debian_slim(python_version="3.11")
+    .uv_pip_install("torch==2.8.0", "transformers", "accelerate")
+    .apt_install("git")
+)
+
+@app.function(image=image)
+def inference(prompt):
+    from transformers import pipeline
+    pipe = pipeline("text-generation", model="meta-llama/Llama-3-8B")
+
+### GPU Compute
+
+Request GPUs via the `gpu` parameter:
+
+```python
+@app.function(gpu="H100")
+def train_model():
+    import torch
+    device = torch.device("cuda")
+    # GPU training code here
+
+# Multiple GPUs
+@app.function(gpu="H100:4")
+def distributed_training():
+    ...
+
+# GPU fallback chain
+@app.function(gpu=["H100", "A100-80GB", "A100-40GB"])
+def flexible_inference():
+    ...
+
+

package/skills/model-routing-context/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: model-routing-context
+description: Model routing, parent context, thinking level, and prompt construction workflow. Use when changing model fallback, child Pi args, inherited context, task prompts, or compact-read behavior.
+---
+
+
+# model-routing-context
+
+Use this skill when working on model/context propagation.
+
+## Source patterns distilled
+
+- Pi session context/model state: `source/pi-mono/packages/coding-agent/src/core/session-manager.ts`, `agent-session.ts`, compaction modules
+- pi-crew model and prompt code: `src/runtime/model-fallback.ts`, `src/runtime/pi-args.ts`, `src/runtime/task-runner/prompt-builder.ts`, `src/runtime/task-output-context.ts`, `src/extension/team-tool/context.ts`
+
+## Rules
+
+- Preserve parent model inheritance unless an agent/task/user explicitly provides a non-empty model override.
+- Treat empty strings and whitespace model values as absent.
+- Carry relevant parent conversation context as reference-only; do not let it override explicit task instructions or safety constraints.
+- Respect compact-read/compaction summaries when building context; avoid ballooning prompts with redundant transcript data.
+- Avoid inline dynamic imports for model providers or prompt helpers.
+- When changing model precedence, add tests for undefined, empty, whitespace, agent, task, parent, and explicit tool override cases.
+- Redact secrets in context snippets and child prompts where logs/artifacts may persist them.
+
+## Anti-patterns
+
+- Letting `agentModel: ""` block parent model fallback.
+- Treating parent conversation text as executable instructions rather than context.
+- Passing full session transcripts to every child by default.
+- Losing thinking level or model changes across session switch/fork flows.
+
+## Worked Examples
+
+### Model precedence chain with all fields
+
+When every level provides a model:
+
+```typescript
+// Requested by user/tool: "sonnet-4-2025-01-16"
+// Step model (workflow): undefined
+// Team role model: undefined
+// Agent model: "haiku-4"
+// Parent model: "sonnet-4-2025-01-16"
+// Model registry: { default: "claude-sonnet-4" }
+
+const result = buildConfiguredModelRouting({
+  overrideModel: "sonnet-4-2025-01-16",  // tool override wins
+  stepModel: undefined,
+  teamRoleModel: undefined,
+  agentModel: "haiku-4",
+  fallbackModels: ["haiku-3"],
+  parentModel: "sonnet-4-2025-01-16",
+  modelRegistry: { default: "claude-sonnet-4" },
+  cwd,
+});
+
+// Result: candidates = ["sonnet-4-2025-01-16"]
+// resolved = "sonnet-4-2025-01-16" (override wins)
+// reason = "tool override"
+```
+
+### Override at each level
+
+```typescript
+// Level 1: tool override (highest)
+buildConfiguredModelRouting({ overrideModel: "sonnet-4-2025-01-16" });
+// → candidates = ["sonnet-4-2025-01-16"]
+
+// Level 2: step model
+buildConfiguredModelRouting({ overrideModel: undefined, stepModel: "haiku-4" });
+// → candidates = ["haiku-4"]
+
+// Level 3: team role model
+buildConfiguredModelRouting({ overrideModel: undefined, stepModel: undefined, teamRoleModel: "sonnet-3.5" });
+// → candidates = ["sonnet-3.5"]
+
+// Level 4: agent model with fallback
+buildConfiguredModelRouting({ overrideModel: undefined, stepModel: undefined, teamRoleModel: undefined, agentModel: "haiku-3", fallbackModels: ["claude-3-5-haiku-20241022"] });
+// → candidates = ["haiku-3", "claude-3-5-haiku-20241022"]
+```
+
+### Empty/whitespace/null handling
+
+```typescript

package/skills/molecular-dynamics/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: molecular-dynamics
+description: Run and analyze molecular dynamics simulations with OpenMM and MDAnalysis. Set up protein/small molecule systems, define force fields, run energy minimization and production MD, analyze trajectories (RMSD, RMSF, contact maps, free energy surfaces). For structural biology, drug binding, and biophysics.
+---
+
+# Molecular Dynamics
+
+## Overview
+
+Molecular dynamics (MD) simulation computationally models the time evolution of molecular systems by integrating Newton's equations of motion. This skill covers two complementary tools:
+
+- **OpenMM** (https://openmm.org/): High-performance MD simulation engine with GPU support, Python API, and flexible force field support
+- **MDAnalysis** (https://mdanalysis.org/): Python library for reading, writing, and analyzing MD trajectories from all major simulation packages
+
+**Installation:**
+```bash
+conda install -c conda-forge openmm mdanalysis nglview
+# or
+pip install openmm mdanalysis
+
+## When to Use This Skill
+
+Use molecular dynamics when:
+
+- **Protein stability analysis**: How does a mutation affect protein dynamics?
+- **Drug binding simulations**: Characterize binding mode and residence time of a ligand
+- **Conformational sampling**: Explore protein flexibility and conformational changes
+- **Protein-protein interaction**: Model interface dynamics and binding energetics
+- **RMSD/RMSF analysis**: Quantify structural fluctuations from a reference structure
+- **Free energy estimation**: Compute binding free energy or conformational free energy
+- **Membrane simulations**: Model proteins in lipid bilayers
+- **Intrinsically disordered proteins**: Study IDR conformational ensembles
+
+## Core Workflow: OpenMM Simulation
+
+### 1. System Preparation
+
+```python
+from openmm.app import *
+from openmm import *
+from openmm.unit import *
+import sys
+
+def prepare_system_from_pdb(pdb_file, forcefield_name="amber14-all.xml",
+                              water_model="amber14/tip3pfb.xml"):
+    """
+    Prepare an OpenMM system from a PDB file.
+
+    Args:
+        pdb_file: Path to cleaned PDB file (use PDBFixer for raw PDB files)
+
+### 2. Energy Minimization
+
+```python
+from openmm.app import *
+from openmm import *
+from openmm.unit import *
+
+def minimize_energy(modeller, system, output_pdb="minimized.pdb",
+                     max_iterations=1000, tolerance=10.0):
+    """
+    Energy minimize the system to remove steric clashes.
+
+    Args:
+        modeller: Modeller object with topology and positions
+        system: OpenMM System
+
+### 3. NVT Equilibration
+
+```python
+from openmm.app import *
+from openmm import *
+from openmm.unit import *
+
+def run_nvt_equilibration(simulation, n_steps=50000, temperature=300,
+                            report_interval=1000, output_prefix="nvt"):
+    """
+    NVT equilibration: constant N, V, T.
+    Equilibrate velocities to target temperature.
+
+    Args:
+        simulation: OpenMM Simulation (after minimization)
+
+### 4. NPT Equilibration and Production
+
+```python
+def run_npt_production(simulation, n_steps=500000, temperature=300, pressure=1.0,
+                        report_interval=5000, output_prefix="npt"):
+    """
+    NPT production run: constant N, P, T.
+
+    Args:
+        n_steps: Production steps (500000 × 2fs = 1 ns)
+        temperature: Temperature in Kelvin
+        pressure: Pressure in bar
+        report_interval: Steps between reports
+    """
+    # Add Monte Carlo barostat for pressure control
+
+## Trajectory Analysis with MDAnalysis
+
+### 1. Load Trajectory
+
+```python
+import MDAnalysis as mda
+from MDAnalysis.analysis import rms, align, contacts
+import numpy as np
+import matplotlib.pyplot as plt
+
+def load_trajectory(topology_file, trajectory_file):
+    """
+    Load an MD trajectory with MDAnalysis.
+
+    Args:
+
+

package/skills/molfeat/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: molfeat
+description: Molecular featurization for ML (100+ featurizers). ECFP, MACCS, descriptors, pretrained models (ChemBERTa), convert SMILES to features, for QSAR and molecular ML.
+---
+
+# Molfeat - Molecular Featurization Hub
+
+## Overview
+
+Molfeat is a comprehensive Python library for molecular featurization that unifies 100+ pre-trained embeddings and hand-crafted featurizers. Convert chemical structures (SMILES strings or RDKit molecules) into numerical representations for machine learning tasks including QSAR modeling, virtual screening, similarity searching, and deep learning applications. Features fast parallel processing, scikit-learn compatible transformers, and built-in caching.
+
+## When to Use This Skill
+
+This skill should be used when working with:
+- **Molecular machine learning**: Building QSAR/QSPR models, property prediction
+- **Virtual screening**: Ranking compound libraries for biological activity
+- **Similarity searching**: Finding structurally similar molecules
+- **Chemical space analysis**: Clustering, visualization, dimensionality reduction
+- **Deep learning**: Training neural networks on molecular data
+- **Featurization pipelines**: Converting SMILES to ML-ready representations
+- **Cheminformatics**: Any task requiring molecular feature extraction
+
+# With all optional dependencies
+uv pip install "molfeat[all]"
+```
+
+**Optional dependencies for specific featurizers:**
+- `molfeat[dgl]` - GNN models (GIN variants)
+- `molfeat[graphormer]` - Graphormer models
+- `molfeat[transformer]` - ChemBERTa, ChemGPT, MolT5
+- `molfeat[fcd]` - FCD descriptors
+- `molfeat[map4]` - MAP4 fingerprints
+
+## Core Concepts
+
+Molfeat organizes featurization into three hierarchical classes:
+
+### 1. Calculators (`molfeat.calc`)
+
+Callable objects that convert individual molecules into feature vectors. Accept RDKit `Chem.Mol` objects or SMILES strings.
+
+**Use calculators for:**
+- Single molecule featurization
+- Custom processing loops
+- Direct feature computation
+
+**Example:**
+```python
+from molfeat.calc import FPCalculator
+
+calc = FPCalculator("ecfp", radius=3, fpSize=2048)
+features = calc("CCO")  # Returns numpy array (2048,)
+```
+
+### 2. Transformers (`molfeat.trans`)
+
+Scikit-learn compatible transformers that wrap calculators for batch processing with parallelization.
+
+**Use transformers for:**
+- Batch featurization of molecular datasets
+- Integration with scikit-learn pipelines
+- Parallel processing (automatic CPU utilization)
+
+**Example:**
+```python
+from molfeat.trans import MoleculeTransformer
+from molfeat.calc import FPCalculator
+
+transformer = MoleculeTransformer(FPCalculator("ecfp"), n_jobs=-1)
+features = transformer(smiles_list)  # Parallel processing
+```
+
+### 3. Pretrained Transformers (`molfeat.trans.pretrained`)
+
+Specialized transformers for deep learning models with batched inference and caching.
+
+**Use pretrained transformers for:**
+- State-of-the-art molecular embeddings
+- Transfer learning from large chemical datasets
+- Deep learning feature extraction
+
+**Example:**
+```python
+from molfeat.trans.pretrained import PretrainedMolTransformer
+
+transformer = PretrainedMolTransformer("ChemBERTa-77M-MLM", n_jobs=-1)
+embeddings = transformer(smiles_list)  # Deep learning embeddings
+```
+
+## Quick Start Workflow
+
+### Basic Featurization
+
+```python
+import datamol as dm
+from molfeat.calc import FPCalculator
+from molfeat.trans import MoleculeTransformer
+
+# Load molecular data
+smiles = ["CCO", "CC(=O)O", "c1ccccc1", "CC(C)O"]
+
+# Create calculator and transformer
+calc = FPCalculator("ecfp", radius=3)
+transformer = MoleculeTransformer(calc, n_jobs=-1)
+
+# Featurize molecules
+features = transformer(smiles)
+print(f"Shape: {features.shape}")  # (4, 2048)
+
+

package/skills/multi-perspective-review/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: multi-perspective-review
+description: Use when reviewing a plan, diff, implementation, worker output, release candidate, or external review feedback.
+---
+
+
+# multi-perspective-review
+
+Core principle: review early, review often, and separate concerns. Reviewer output is evidence to evaluate, not an instruction to obey blindly.
+
+Distilled from detailed reads of requesting-code-review, receiving-code-review, subagent review checkpoints, differential review, and specialized review-agent patterns.
+
+## Review Passes
+
+Run relevant passes separately:
+
+1. Spec compliance: Does the work match the request and nothing extra?
+2. Correctness: Are edge cases, state transitions, and failure paths right?
+3. Regression risk: Could config precedence, runtime defaults, or public APIs break?
+4. Security: Trust boundaries, path containment, prompt injection, secrets, permissions.
+5. Tests: Do tests assert the changed behavior and isolation concerns?
+6. Maintainability: Narrow diff, typed inputs, clear ownership, reversible changes.
+7. Operator experience: Error/status text, recovery hints, artifacts, logs.
+8. Compatibility: Windows paths, Node/Pi versions, CLI flags, legacy paths.
+
+## Finding Format
+
+```text
+[severity] path:line or symbol
+Issue: ...
+Impact: ...
+Fix: ...
+Verification: ...
+```
+
+Severity:
+
+- critical: data loss, secret leak, arbitrary command/path escape, unusable default install;
+- high: broken core workflow, ownership bypass, persistent incorrect state;
+- medium: important regression, flaky test, confusing recoverable behavior;
+- low: polish, maintainability, docs.
+
+## Example Findings by Perspective
+
+### Spec Compliance
+
+```
+[medium] src/runtime/task-runner.ts:89
+Issue: `executeWorkers` is checked once at top of runTeamTask but the value
+  is passed through an untyped parameter. The function comment says "workers
+  are disabled in scaffold mode" but the actual behavior is driven by `runtimeKind`.
+Impact: If someone changes the comment but not the code, the mismatch is invisible.
+Fix: Add a runtimeKind guard and deprecate the executeWorkers parameter.
+Verification: `npx tsc --noEmit` passes; test with `PI_TEAMS_MOCK_CHILD_PI=scaffold`.
+```
+
+### Correctness
+
+```
+[high] src/runtime/live-agent-manager.ts:47
+Issue: `registerLiveAgent` returns the new handle but callers may use the
+  old handle reference if they captured it before the call.
+Impact: Status updates may apply to the wrong handle if the agent re-registers.
+Fix: Always call `getLiveAgent` after `registerLiveAgent` to get the canonical handle.
+Verification: Add test that verifies status after re-registration.
+```
+
+### Regression Risk
+
+```
+[medium] src/state/state-store.ts:150
+Issue: `saveRunTasks` uses `atomicWriteJson` but the file may grow large.
+  No pagination or archiving strategy for long-running runs.
+Impact: Tasks file could exceed 10MB with many updates, causing slow I/O.
+Fix: Consider splitting into per-task files or adding a size warning.
+Verification: Load test with 10,000 task updates.
+```
+
+### Security
+
+```
+[critical] src/utils/safe-paths.ts:20
+Issue: `resolveRealContainedPath` follows symlinks but doesn't verify the
+  resolved path stays under the allowed base.
+Impact: A malicious symlink could escape the workspace boundary.