pi-skill-search 0.1.0

package/skills/systematic-debugging/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: systematic-debugging
+description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
+---
+
+# Systematic Debugging
+
+## Overview
+
+Random fixes waste time and create new bugs. Quick patches mask underlying issues.
+
+**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
+
+**Violating the letter of this process is violating the spirit of debugging.**
+
+## The Iron Law
+
+```
+NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
+```
+
+If you haven't completed Phase 1, you cannot propose fixes.
+
+## When to Use
+
+Use for ANY technical issue:
+- Test failures
+- Bugs in production
+- Unexpected behavior
+- Performance problems
+- Build failures
+- Integration issues
+
+**Use this ESPECIALLY when:**
+- Under time pressure (emergencies make guessing tempting)
+- "Just one quick fix" seems obvious
+- You've already tried multiple fixes
+- Previous fix didn't work
+
+## The Four Phases
+
+You MUST complete each phase before proceeding to the next.
+
+### Phase 1: Root Cause Investigation
+
+**BEFORE attempting ANY fix:**
+
+1. **Read Error Messages Carefully**
+   - Don't skip past errors or warnings
+   - They often contain the exact solution
+   - Read stack traces completely
+   - Note line numbers, file paths, error codes
+
+2. **Reproduce Consistently**
+   - Can you trigger it reliably?
+   - What are the exact steps?
+   - Does it happen every time?
+   - If not reproducible → gather more data, don't guess
+
+### Phase 2: Pattern Analysis
+
+**Find the pattern before fixing:**
+
+1. **Find Working Examples**
+   - Locate similar working code in same codebase
+   - What works that's similar to what's broken?
+
+2. **Compare Against References**
+   - If implementing pattern, read reference implementation COMPLETELY
+   - Don't skim - read every line
+   - Understand the pattern fully before applying
+
+3. **Identify Differences**
+   - What's different between working and broken?
+
+### Phase 3: Hypothesis and Testing
+
+**Scientific method:**
+
+1. **Form Single Hypothesis**
+   - State clearly: "I think X is the root cause because Y"
+   - Write it down
+   - Be specific, not vague
+
+2. **Test Minimally**
+   - Make the SMALLEST possible change to test hypothesis
+   - One variable at a time
+   - Don't fix multiple things at once
+
+3. **Verify Before Continuing**
+
+### Phase 4: Implementation
+
+**Fix the root cause, not the symptom:**
+
+1. **Create Failing Test Case**
+   - Simplest possible reproduction
+   - Automated test if possible
+   - One-off test script if no framework
+   - MUST have before fixing
+   - Use the `superpowers:test-driven-development` skill for writing proper failing tests
+
+2. **Implement Single Fix**
+   - Address the root cause identified
+   - ONE change at a time
+   - No "while I'm here" improvements
+
+## Red Flags - STOP and Follow Process
+
+If you catch yourself thinking:
+- "Quick fix for now, investigate later"
+- "Just try changing X and see if it works"
+- "Add multiple changes, run tests"
+- "Skip the test, I'll manually verify"
+- "It's probably X, let me fix that"
+- "I don't fully understand but this might work"
+- "Pattern says X but I'll adapt it differently"
+
+

package/skills/team/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: team
+description: N coordinated agents on shared task list using Claude Code native teams
+---
+
+# Team Skill
+
+Spawn N coordinated agents working on a shared task list using Claude Code's native team tools. Replaces the legacy `/swarm` skill (SQLite-based) with built-in team management, inter-agent messaging, and task dependencies -- no external dependencies required.
+
+The `swarm` compatibility alias was removed in #1131.
+
+## Usage
+
+```
+team N:agent-type "task description"
+team "task description"
+team ralph "task description"
+```
+
+### Parameters
+
+- **N** - Number of teammate agents (1-20). Optional; defaults to auto-sizing based on task decomposition.
+- **agent-type** - OMC agent to spawn for the `team-exec` stage (e.g., executor, debugger, designer, codex, gemini). Optional; defaults to stage-aware routing. Use `codex` to spawn Codex CLI workers or `gemini` for Gemini CLI workers (requires respective CLIs installed). See Stage Agent Routing below.
+- **task** - High-level task to decompose and distribute among teammates
+- **ralph** - Optional modifier. When present, wraps the team pipeline in Ralph's persistence loop (retry on failure, architect verification before completion). See Team + Ralph Composition below.
+
+### Examples
+
+```bash
+/team 5:executor "fix all TypeScript errors across the project"
+/team 3:debugger "fix build errors in src/"
+/team 4:designer "implement responsive layouts for all page components"
+/team "refactor the auth module with security review"
+/team ralph "build a complete REST API for user management"
+# With Codex CLI workers (requires: npm install -g @openai/codex)
+/team 2:codex "review architecture and suggest improvements"
+# With Gemini CLI workers (requires: npm install -g @google/gemini-cli)
+/team 2:gemini "redesign the UI components"
+# Mixed: Codex for backend analysis, Gemini for frontend (use /ccg instead for this)
+```
+
+## Architecture
+
+```
+User: "/team 3:executor fix all TypeScript errors"
+              |
+              v
+      [TEAM ORCHESTRATOR (Lead)]
+              |
+              +-- TeamCreate("fix-ts-errors")
+              |       -> lead becomes team-lead@fix-ts-errors
+              |
+              +-- Analyze & decompose task into subtasks
+              |       -> explore/architect produces subtask list
+              |
+              +-- TaskCreate x N (one per subtask)
+              |       -> tasks #1, #2, #3 with dependencies
+              |
+              +-- TaskUpdate x N (pre-assign owners)
+              |       -> task #1 owner=worker-1, etc.
+              |
+              +-- Task(team_name="fix-ts-errors", name="worker-1") x 3
+              |       -> spawns teammates into the team
+              |
+              +-- Monitor loop
+              |       <- SendMessage from teammates (auto-delivered)
+              |       -> TaskList polling for progress
+              |       -> SendMessage to unblock/coordinate
+              |
+              +-- Completion
+                      -> SendMessage(shutdown_request) to each teammate
+                      <- SendMessage(shutdown_response, approve: true)
+                      -> TeamDelete("fix-ts-errors")
+                      -> rm .omc/state/team-state.json
+```
+
+**Storage layout (managed by Claude Code):**
+```
+~/.claude/
+  teams/fix-ts-errors/
+    config.json          # Team metadata + members array
+  tasks/fix-ts-errors/
+    .lock                # File lock for concurrent access
+    1.json               # Subtask #1
+```

package/skills/test-driven-development/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: test-driven-development
+description: Use when implementing any feature or bugfix, before writing implementation code
+---
+
+# Test-Driven Development (TDD)
+
+## Overview
+
+Write the test first. Watch it fail. Write minimal code to pass.
+
+**Core principle:** If you didn't watch the test fail, you don't know if it tests the right thing.
+
+**Violating the letter of the rules is violating the spirit of the rules.**
+
+## When to Use
+
+**Always:**
+- New features
+- Bug fixes
+- Refactoring
+- Behavior changes
+
+**Exceptions (ask your human partner):**
+- Throwaway prototypes
+- Generated code
+- Configuration files
+
+Thinking "skip TDD just this once"? Stop. That's rationalization.
+
+## The Iron Law
+
+```
+NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
+```
+
+Write code before the test? Delete it. Start over.
+
+**No exceptions:**
+- Don't keep it as "reference"
+- Don't "adapt" it while writing tests
+- Don't look at it
+- Delete means delete
+
+Implement fresh from tests. Period.
+
+## Red-Green-Refactor
+
+```dot
+digraph tdd_cycle {
+    rankdir=LR;
+    red [label="RED\nWrite failing test", shape=box, style=filled, fillcolor="#ffcccc"];
+    verify_red [label="Verify fails\ncorrectly", shape=diamond];
+    green [label="GREEN\nMinimal code", shape=box, style=filled, fillcolor="#ccffcc"];
+    verify_green [label="Verify passes\nAll green", shape=diamond];
+    refactor [label="REFACTOR\nClean up", shape=box, style=filled, fillcolor="#ccccff"];
+    next [label="Next", shape=ellipse];
+
+    red -> verify_red;
+    verify_red -> green [label="yes"];
+    verify_red -> red [label="wrong\nfailure"];
+
+### RED - Write Failing Test
+
+Write one minimal test showing what should happen.
+
+```typescript
+test('retries failed operations 3 times', async () => {
+  let attempts = 0;
+  const operation = () => {
+    attempts++;
+    if (attempts < 3) throw new Error('fail');
+    return 'success';
+  };
+
+  const result = await retryOperation(operation);
+
+### Verify RED - Watch It Fail
+
+**MANDATORY. Never skip.**
+
+```bash
+npm test path/to/test.test.ts
+```

package/skills/tiledbvcf/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: tiledbvcf
+description: Efficient storage and retrieval of genomic variant data using TileDB. Scalable VCF/BCF ingestion, incremental sample addition, compressed storage, parallel queries, and export capabilities for population genomics.
+---
+
+# TileDB-VCF
+
+## Overview
+
+TileDB-VCF is a high-performance C++ library with Python and CLI interfaces for efficient storage and retrieval of genomic variant-call data. Built on TileDB's sparse array technology, it enables scalable ingestion of VCF/BCF files, incremental sample addition without expensive merging operations, and efficient parallel queries of variant data stored locally or in the cloud.
+
+## When to Use This Skill
+
+This skill should be used when:
+- Learning TileDB-VCF concepts and workflows
+- Prototyping genomics analyses and pipelines
+- Working with small-to-medium datasets (< 1000 samples)
+- Need incremental addition of new samples to existing datasets
+- Require efficient querying of specific genomic regions across many samples
+- Working with cloud-stored variant data (S3, Azure, GCS)
+- Need to export subsets of large VCF datasets
+- Building variant databases for cohort studies
+- Educational projects and method development
+- Performance is critical for variant data operations
+
+## Quick Start
+
+# Enter the following two lines if you are on a M1 Mac
+CONDA_SUBDIR=osx-64
+conda config --env --set subdir osx-64
+
+# Create the conda environment
+conda create -n tiledb-vcf "python<3.10"
+conda activate tiledb-vcf
+
+# Mamba is a faster and more reliable alternative to conda
+conda install -c conda-forge mamba
+
+### Basic Examples
+
+**Create and populate a dataset:**
+```python
+import tiledbvcf
+
+# Create a new dataset
+ds = tiledbvcf.Dataset(uri="my_dataset", mode="w",
+                      cfg=tiledbvcf.ReadConfig(memory_budget=1024))
+
+# Ingest VCF files (must be single-sample with indexes)
+# Requirements:
+# - VCFs must be single-sample (not multi-sample)
+# - Must have indexes: .csi (bcftools) or .tbi (tabix)
+ds.ingest_samples(["sample1.vcf.gz", "sample2.vcf.gz"])
+```
+
+**Query variant data:**
+```python
+# Open existing dataset for reading
+ds = tiledbvcf.Dataset(uri="my_dataset", mode="r")
+
+# Query specific regions and samples
+df = ds.read(
+    attrs=["sample_name", "pos_start", "pos_end", "alleles", "fmt_GT"],
+    regions=["chr1:1000000-2000000", "chr2:500000-1500000"],
+    samples=["sample1", "sample2", "sample3"]
+)
+print(df.head())
+```
+
+**Export to VCF:**
+```python
+import os
+
+# Export two VCF samples
+ds.export(
+    regions=["chr21:8220186-8405573"],
+    samples=["HG00101", "HG00097"],
+    output_format="v",
+    output_dir=os.path.expanduser("~"),
+)
+```
+
+## Core Capabilities
+
+### 1. Dataset Creation and Ingestion
+
+Create TileDB-VCF datasets and incrementally ingest variant data from multiple VCF/BCF files. This is appropriate for building population genomics databases and cohort studies.
+
+**Requirements:**
+- **Single-sample VCFs only**: Multi-sample VCFs are not supported
+- **Index files required**: VCF/BCF files must have indexes (.csi or .tbi)
+
+**Common operations:**
+- Create new datasets with optimized array schemas
+- Ingest single or multiple VCF/BCF files in parallel
+- Add new samples incrementally without re-processing existing data
+- Configure memory usage and compression settings
+- Handle various VCF formats and INFO/FORMAT fields
+- Resume interrupted ingestion processes
+- Validate data integrity during ingestion
+
+
+### 2. Efficient Querying and Filtering
+
+Query variant data with high performance across genomic regions, samples, and variant attributes. This is appropriate for association studies, variant discovery, and population analysis.
+
+**Common operations:**
+- Query specific genomic regions (single or multiple)
+- Filter by sample names or sample groups
+- Extract specific variant attributes (position, alleles, genotypes, quality)
+- Access INFO and FORMAT fields efficiently
+- Combine spatial and attribute-based filtering
+- Stream large query results
+- Perform aggregations across samples or regions
+
+
+### 3. Data Export and Interoperability
+
+

package/skills/timeline-report/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: timeline-report
+description: Generate a "Journey Into [Project]" narrative report analyzing a project's entire development history from claude-mem's timeline. Use when asked for a timeline report, project history analysis, development journey, or full project report.
+---
+
+# Timeline Report
+
+Generate a comprehensive narrative analysis of a project's entire development history using claude-mem's persistent memory timeline.
+
+## When to Use
+
+Use when users ask for:
+
+- "Write a timeline report"
+- "Journey into [project]"
+- "Analyze my project history"
+- "Full project report"
+- "Summarize the entire development history"
+- "What's the story of this project?"
+
+## Prerequisites
+
+The claude-mem worker must be running. The project must have claude-mem observations recorded.
+
+**Resolve the worker port** (do this once at the start and reuse `$WORKER_PORT` in every curl call below):
+
+```bash
+WORKER_PORT="${CLAUDE_MEM_WORKER_PORT:-$(node -e "const fs=require('fs'),p=require('path'),os=require('os');const uid=(typeof process.getuid==='function'?process.getuid():77);const fallback=String(37700+(uid%100));try{const s=JSON.parse(fs.readFileSync(p.join(os.homedir(),'.claude-mem','settings.json'),'utf-8'));process.stdout.write(String(s.CLAUDE_MEM_WORKER_PORT||fallback));}catch{process.stdout.write(fallback);}" 2>/dev/null)}"
+```
+
+This honors `CLAUDE_MEM_WORKER_PORT` env, then `~/.claude-mem/settings.json`, then falls back to the per-UID default `37700 + (uid % 100)` — matching how the worker itself picks its port. Required for multi-account setups (#2101) and any user who has overridden the default port (#2103).
+
+## Workflow
+
+### Step 1: Determine the Project Name
+
+Ask the user which project to analyze if not obvious from context. The project name is typically the directory name of the project (e.g., "tokyo", "my-app"). If the user says "this project", use the current working directory's basename.
+
+**Worktree Detection:** Before using the directory basename, check if the current directory is a git worktree. In a worktree, the data source is the **parent project**, not the worktree directory itself. Run:
+
+```bash
+git_dir=$(git rev-parse --git-dir 2>/dev/null)
+git_common_dir=$(git rev-parse --git-common-dir 2>/dev/null)
+if [ "$git_dir" != "$git_common_dir" ]; then
+  # We're in a worktree — resolve the parent project name
+  parent_project=$(basename "$(dirname "$git_common_dir")")
+  echo "Worktree detected. Parent project: $parent_project"
+else
+  parent_project=$(basename "$PWD")
+
+### Step 2: Fetch the Full Timeline
+
+Use Bash to fetch the complete timeline from the claude-mem worker API:
+
+```bash
+curl -s "http://localhost:${WORKER_PORT}/api/context/inject?project=PROJECT_NAME&full=true"
+```
+
+This returns the entire compressed timeline -- every observation, session boundary, and summary across the project's full history. The response is pre-formatted markdown optimized for LLM consumption.
+
+**Token estimates:** The full timeline size depends on the project's history:
+- Small project (< 1,000 observations): ~20-50K tokens
+- Medium project (1,000-10,000 observations): ~50-300K tokens
+- Large project (10,000-35,000 observations): ~300-750K tokens
+
+If the response is empty or returns an error, the worker may not be running or the project name may be wrong. Try `curl -s "http://localhost:${WORKER_PORT}/api/search?query=*&limit=1"` to verify the worker is healthy.
+
+### Step 3: Estimate Token Count
+
+Before proceeding, estimate the token count of the fetched timeline (roughly 1 token per 4 characters). Report this to the user:
+
+```
+Timeline fetched: ~X observations, estimated ~Yk tokens.
+This analysis will consume approximately Yk input tokens + ~5-10k output tokens.
+Proceed? (y/n)
+```
+
+Wait for user confirmation before continuing if the timeline exceeds 100K tokens.
+
+### Step 4: Analyze with a Subagent
+
+Deploy an Agent (using the Task tool) with the full timeline and the following analysis prompt. Pass the ENTIRE timeline as context to the agent. The agent should also be instructed to query the SQLite database at `~/.claude-mem/claude-mem.db` for the Token Economics section.
+
+**Agent prompt:**
+```

package/skills/timesfm-forecasting/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: timesfm-forecasting
+description: Zero-shot time series forecasting with Google's TimesFM foundation model. Use for any univariate time series (sales, sensors, energy, vitals, weather) without training a custom model. Supports CSV/DataFrame/array inputs with point forecasts and prediction intervals. Includes a preflight system checker script to verify RAM/GPU before first use.
+---
+
+# TimesFM Forecasting
+
+## Overview
+
+TimesFM (Time Series Foundation Model) is a pretrained decoder-only foundation model
+developed by Google Research for time-series forecasting. It works **zero-shot** — feed it
+any univariate time series and it returns point forecasts with calibrated quantile
+prediction intervals, no training required.
+
+This skill wraps TimesFM for safe, agent-friendly local inference. It includes a
+**mandatory preflight system checker** that verifies RAM, GPU memory, and disk space
+before the model is ever loaded so the agent never crashes a user's machine.
+
+> **Key numbers**: TimesFM 2.5 uses 200M parameters (~800 MB on disk, ~1.5 GB in RAM on
+> CPU, ~1 GB VRAM on GPU). The archived v1/v2 500M-parameter model needs ~32 GB RAM.
+> Always run the system checker first.
+
+## When to Use This Skill
+
+Use this skill when:
+
+- Forecasting **any univariate time series** (sales, demand, sensor, vitals, price, weather)
+- You need **zero-shot forecasting** without training a custom model
+- You want **probabilistic forecasts** with calibrated prediction intervals (quantiles)
+- You have time series of **any length** (the model handles 1–16,384 context points)
+- You need to **batch-forecast** hundreds or thousands of series efficiently
+- You want a **foundation model** approach instead of hand-tuning ARIMA/ETS parameters
+
+Do **not** use this skill when:
+
+- You need classical statistical models with coefficient interpretation → use `statsmodels`
+- You need time series classification or clustering → use `aeon`
+
+## ⚠️ Mandatory Preflight: System Requirements Check
+
+**CRITICAL — ALWAYS run the system checker before loading the model for the first time.**
+
+```bash
+python scripts/check_system.py
+```
+
+This script checks:
+
+1. **Available RAM** — warns if below 4 GB, blocks if below 2 GB
+2. **GPU availability** — detects CUDA/MPS devices and VRAM
+3. **Disk space** — verifies room for the ~800 MB model download
+4. **Python version** — requires 3.10+
+5. **Existing installation** — checks if `timesfm` and `torch` are installed
+
+### Hardware Requirements by Model Version
+
+| Model | Parameters | RAM (CPU) | VRAM (GPU) | Disk | Context |
+| ----- | ---------- | --------- | ---------- | ---- | ------- |
+| **TimesFM 2.5** (recommended) | 200M | ≥ 4 GB | ≥ 2 GB | ~800 MB | up to 16,384 |
+| TimesFM 2.0 (archived) | 500M | ≥ 16 GB | ≥ 8 GB | ~2 GB | up to 2,048 |
+| TimesFM 1.0 (archived) | 200M | ≥ 8 GB | ≥ 4 GB | ~800 MB | up to 2,048 |
+
+> **Recommendation**: Always use TimesFM 2.5 unless you have a specific reason to use an
+> older checkpoint. It is smaller, faster, and supports 8× longer context.
+
+### Step 1: Verify System (always first)
+
+```bash
+python scripts/check_system.py
+```
+
+# Using uv (recommended by this repo)
+uv pip install timesfm[torch]
+
+# Or using pip
+pip install timesfm[torch]
+
+# For JAX/Flax backend (faster on TPU/GPU)
+uv pip install timesfm[flax]
+```
+
+# CUDA 12.1 (NVIDIA GPU)
+pip install torch>=2.0.0 --index-url https://download.pytorch.org/whl/cu121
+
+# CPU only
+pip install torch>=2.0.0 --index-url https://download.pytorch.org/whl/cpu
+
+# Apple Silicon (MPS)
+pip install torch>=2.0.0  # MPS support is built-in
+```
+
+## 🎯 Quick Start
+
+### Minimal Example (5 Lines)
+
+```python
+import torch, numpy as np, timesfm
+
+torch.set_float32_matmul_precision("high")
+
+model = timesfm.TimesFM_2p5_200M_torch.from_pretrained(
+    "google/timesfm-2.5-200m-pytorch"
+)
+model.compile(timesfm.ForecastConfig(
+    max_context=1024, max_horizon=256, normalize_inputs=True,
+    use_continuous_quantile_head=True, force_flip_invariance=True,
+    infer_is_positive=True, fix_quantile_crossing=True,
+))
+
+# point.shape == (1, 24)        — median forecast
+# quantiles.shape == (1, 24, 10) — 10th–90th percentile bands
+```