pi-skill-search 0.1.0

package/skills/orchestration/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: orchestration
+description: Multi-phase orchestration skill for pi-crew planners and executors. Use when decomposing complex tasks into parallel phases, dispatching workers, verifying gates, and iterating until closure.
+---
+
+
+# orchestration
+
+Use this skill when orchestrating multi-phase tasks across pi-crew teams and workers.
+
+## Role definition
+
+You are the orchestrator — bạn là người điều phối, không phải người thực thi.
+
+You decompose, dispatch, verify, and iterate. You do NOT edit code directly. If you find yourself opening a file to fix a typo "real quick," stop — spawn a worker instead.
+
+## Rules (8 orchestration rules)
+
+Adapted from oh-my-pi's orchestrate command pattern for pi-crew context.
+
+### 1. Do not yield until everything is closed
+
+Không trả lại control khi vẫn còn việc chưa xong. Run every phase to completion. The orchestrator owns the full lifecycle — from first dispatch to final green gate.
+
+### 2. Enumerate the full surface before dispatching
+
+Before writing any task packet, read every referenced file and understand the complete work surface. Liệt kê toàn bộ surface trước khi giao việc — không giao việc khi chưa hiểu hết scope.
+
+### 3. Parallelize maximally
+
+Every set of edits with disjoint file scope MUST ship as one batch. Nếu 5 tasks chỉnh 5 file khác nhau và không phụ thuộc nhau, dispatch tất cả cùng lúc. Never serialize what can be parallelized.
+
+### 4. Each task assignment is self-contained
+
+Subagents have no shared context. Mỗi worker chỉ biết những gì bạn ghi trong task packet. Include all necessary context, file paths, constraints, and acceptance criteria in every task.
+
+### 5. Verify after every phase before launching the next
+
+Run appropriate gates between phases: typecheck, tests, lint. Không bỏ qua verification — một phase đỏ không được phép chuyển sang phase tiếp theo.
+
+### 6. Commit policy — green only
+
+Commit after each green phase. Never commit a red tree. Chỉ commit khi tất cả gates pass. If the phase fails, fix it first.
+
+### 7. Respawn, do not absorb
+
+If a subagent returns incomplete or broken work, spawn a corrective subagent with a focused fix-up task packet. Không tự sửa lỗi của worker — respawn worker mới để sửa.
+
+### 8. No scope creep, no scope shrink
+
+Maintain the original scope exactly. Không mở rộng scope vì "thấy thêm việc," cũng không thu hẹp vì "tạm đủ." If scope needs to change, escalate to the requester.
+
+## Workflow (7 steps)
+
+### Step 1 — Ingest
+
+- Read every referenced file in the goal/task description.
+- Run `git status` and `git diff` to understand current tree state.
+- Identify all files, symbols, and subsystems in scope.
+- Check workspace tree for project context and existing patterns.
+
+### Step 2 — Plan
+
+- Materialize the full work surface as ordered phases.
+- For each phase, enumerate: files to touch, workers needed, dependencies on other phases.
+- Phases must be ordered by dependency; tasks within a phase must be independent (disjoint file scope).
+- Write the plan down — không giữ plan trong head.
+
+### Step 3 — Dispatch phase
+
+- Launch all parallel subagents in one `team` call.
+- Each subagent receives a complete task packet (see `task-packet` skill).
+- Set explicit file ownership per worker — no two workers touch the same file.
+- Use `workspaceMode: 'worktree'` when parallel edits risk conflict.
+
+### Step 4 — Verify phase
+
+- Run verification gates: typecheck, tests, lint as appropriate.
+- If green → proceed to commit.
+- If red → dispatch fix-up subagents with precise failure context (error output, file, line). Do NOT fix it yourself.
+
+### Step 5 — Commit phase (if applicable)
+
+- Only when all gates are green.
+- Commit message should reference the phase and what was accomplished.

package/skills/ownership-session-security/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: ownership-session-security
+description: Session ownership and authorization workflow. Use when implementing cancel, respond, steer, run ownership, cwd overrides, imported runs, or cross-session actions.
+---
+
+
+# ownership-session-security
+
+Use this skill for cross-session safety and trust-boundary work.
+
+## Source patterns distilled
+
+- Pi session IDs: `ctx.sessionManager.getSessionId()` from Pi core `ExtensionContext`
+- pi-crew ownership: `TeamRunManifest.ownerSessionId`, `src/extension/team-tool/run.ts`, `cancel.ts`, `respond.ts`
+- Path safety: `src/utils/safe-paths.ts`, `src/state/state-store.ts`, `src/state/mailbox.ts`
+- Destructive actions: `src/extension/team-tool/lifecycle-actions.ts`, `src/worktree/cleanup.ts`
+
+## Rules
+
+- Propagate the active Pi session ID into `TeamContext` for every production tool/command path.
+- New runs should record `ownerSessionId` when available.
+- For owned runs, cross-session actions that mutate state must be rejected unless explicit force/admin semantics are designed and tested.
+- Legacy runs without `ownerSessionId` may remain permissive for backward compatibility, but document this behavior.
+- User/LLM-controlled path fields (`cwd`, import paths, artifact paths, task IDs) must be normalized and contained under an allowed base.
+- Use `resolveContainedPath`, `resolveRealContainedPath`, `assertSafePathId`, and symlink checks rather than ad-hoc `startsWith` checks.
+- Destructive management actions must require `confirm: true`; referenced resource deletes must require `force: true` where applicable.
+
+## Anti-patterns
+
+- Assuming `ctx.sessionId` exists directly on Pi context.
+- Letting `cwd: ../other-project` move run state into another project.
+- Letting `respond`/`cancel` mutate a foreign owned run.
+- Trusting task IDs, run IDs, or artifact paths from tool params without validation.
+
+## Verification
+
+```bash
+cd pi-crew
+npx tsc --noEmit
+node --experimental-strip-types --test test/unit/cancel-ownership.test.ts test/unit/respond-tool.test.ts test/unit/cwd-override-security.test.ts test/unit/api-artifact-security.test.ts
+npm test
+```
+

package/skills/paper-lookup/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: paper-lookup
+description: Search 10 academic paper databases via REST APIs for research papers, preprints, and scholarly articles. Covers PubMed, PMC (full text), bioRxiv, medRxiv, arXiv, OpenAlex, Crossref, Semantic Scholar, CORE, Unpaywall. Use when searching for papers, citations, DOI/PMID lookups, abstracts, full text, open access, preprints, citation graphs, author search, or any scholarly literature query. Triggers on mentions of any supported database or requests like "find papers on X" or "look up this DOI".
+---
+
+# Paper Lookup
+
+You have access to 10 academic paper databases through their REST APIs. Your job is to figure out which database(s) best serve the user's query, call them, and return the results.
+
+## Core Workflow
+
+1. **Understand the query** -- What is the user looking for? A specific paper by DOI? Papers on a topic? An author's publications? Open access PDFs? Full text? This determines which database(s) to hit.
+
+2. **Select database(s)** -- Use the database selection guide below. Many queries benefit from hitting multiple databases -- for example, searching PubMed for papers and then checking Unpaywall for open access copies.
+
+3. **Read the reference file** -- Each database has a reference file in `references/` with endpoint details, query formats, and example calls. Read the relevant file(s) before making API calls.
+
+4. **Make the API call(s)** -- See the **Making API Calls** section below for which HTTP fetch tool to use on your platform.
+
+5. **Return results** -- Always return:
+   - The **raw JSON** (or parsed XML for arXiv) response from each database
+   - A **list of databases queried** with the specific endpoints used
+   - If a query returned no results, say so explicitly rather than omitting it
+
+## Database Selection Guide
+
+Match the user's intent to the right database(s).
+
+### By Use Case
+
+| User is asking about... | Primary database(s) | Also consider |
+|---|---|---|
+| Papers on a biomedical topic | PubMed | Semantic Scholar, OpenAlex |
+| Full text of a biomedical article | PMC | CORE |
+| Biology preprints | bioRxiv | Semantic Scholar, OpenAlex |
+| Health/medical preprints | medRxiv | Semantic Scholar, OpenAlex |
+| Physics, math, or CS preprints | arXiv | Semantic Scholar, OpenAlex |
+| Papers across all fields | OpenAlex | Semantic Scholar, Crossref |
+| A specific paper by DOI | Crossref | Unpaywall, Semantic Scholar |
+| Open access PDF for a paper | Unpaywall | CORE, PMC |
+| Citation graph (who cites whom) | Semantic Scholar | OpenAlex |
+| Author's publications | Semantic Scholar | OpenAlex |
+| Paper recommendations | Semantic Scholar | -- |
+
+### Cross-Database Queries
+
+| User is asking about... | Databases to query |
+|---|---|
+| Everything about a paper (metadata + citations + OA) | Crossref + Semantic Scholar + Unpaywall |
+| Comprehensive literature search | PubMed + OpenAlex + Semantic Scholar |
+| Find and read a paper | PubMed (find) + Unpaywall (OA link) + PMC or CORE (full text) |
+| Preprint and its published version | bioRxiv/medRxiv + Crossref |
+| Author overview with citation metrics | Semantic Scholar + OpenAlex |
+
+When a query spans multiple needs (e.g., "find papers about CRISPR and get me the PDFs"), query the relevant databases in parallel.
+
+## Common Identifier Formats
+
+Different databases use different identifier systems. If a query fails, the identifier format may be wrong.
+
+| Identifier | Format | Example | Used by |
+|---|---|---|---|
+| DOI | `10.xxxx/xxxxx` | `10.1038/nature12373` | All databases |
+| PMID | Integer | `34567890` | PubMed, PMC, Semantic Scholar |
+| PMCID | `PMC` + digits | `PMC7029759` | PMC, Europe PMC |
+| arXiv ID | `YYMM.NNNNN` | `2103.15348` | arXiv, Semantic Scholar |
+| OpenAlex ID | `W` + digits | `W2741809807` | OpenAlex |
+| Semantic Scholar ID | 40-char hex | `649def34f8be...` | Semantic Scholar |
+| ORCID | `0000-XXXX-XXXX-XXXX` | `0000-0001-6187-6610` | OpenAlex, Crossref |
+| ISSN | `XXXX-XXXX` | `0028-0836` | Crossref, OpenAlex |
+
+**Cross-referencing IDs:** Semantic Scholar accepts DOI, PMID, PMCID, and arXiv ID via prefixes (e.g., `DOI:10.1038/nature12373`, `PMID:34567890`, `ARXIV:2103.15348`). OpenAlex accepts DOI and PMID via prefixes (`doi:10.1038/...`, `pmid:34567890`). Use the PMC ID Converter to translate between PMID, PMCID, and DOI.
+
+## API Keys and Access
+
+Most of these databases are fully open. A few benefit from API keys for higher rate limits.
+
+### Databases requiring or benefiting from API keys
+
+| Database | Env Variable | Required? | Registration |
+|---|---|---|---|
+| NCBI (PubMed, PMC) | `NCBI_API_KEY` | No (3 req/s without, 10 with) | https://www.ncbi.nlm.nih.gov/account/settings/ |
+| CORE | `CORE_API_KEY` | Yes for full text | https://core.ac.uk/services/api |
+| Semantic Scholar | `S2_API_KEY` | No (shared pool without) | https://www.semanticscholar.org/product/api#api-key-form |
+| OpenAlex | `OPENALEX_API_KEY` | Recommended | https://openalex.org/settings/api |
+
+### Fully open databases (no key needed)
+
+| Database | Notes |
+|---|---|
+| bioRxiv / medRxiv | No auth, no documented rate limits |
+| arXiv | No auth, max 1 request per 3 seconds |
+| Crossref | No auth; add `mailto` param for polite pool (2x rate limit) |
+| Unpaywall | No auth; requires `email` parameter |
+
+### Loading API keys
+
+1. **Check the environment first** -- the key may already be exported (e.g., `$NCBI_API_KEY`).
+2. **Fall back to `.env`** -- check `.env` in the current working directory.
+3. **Proceed without** -- most APIs still work at lower rate limits. Tell the user which key is missing and how to get one.
+
+## Making API Calls
+
+Use your environment's HTTP fetch tool to call REST endpoints:
+
+| Platform | HTTP Fetch Tool | Fallback |
+|---|---|---|
+| Claude Code | `WebFetch` | `curl` via Bash |
+| Gemini CLI | `web_fetch` | `curl` via shell |
+| Windsurf | `read_url_content` | `curl` via terminal |
+| Cursor | No dedicated fetch tool | `curl` via `run_terminal_cmd` |
+| Codex CLI | No dedicated fetch tool | `curl` via `shell` |
+| Cline | No dedicated fetch tool | `curl` via `execute_command` |
+
+If the fetch tool fails, fall back to `curl` via whatever shell tool is available.
+
+### Special cases
+
+

package/skills/paperzilla/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: paperzilla
+description: Chat with your agent about projects, recommendations, and canonical papers in Paperzilla. Use when users ask for recent project recommendations, canonical paper details, markdown-based summaries, recommendation feedback, feed export, or Atom feed URLs.
+---
+
+# Paperzilla
+
+Use this skill when you want to chat with your agent about projects, recommendations, and canonical papers in Paperzilla.
+
+## What you can ask
+
+- "Give me the latest recommendations from project X."
+- "Open recommendation Y and explain why it matters."
+- "Fetch canonical paper Z as markdown and summarize it."
+- "Tell me how this paper is relevant to my research."
+- "Show me the feed for project X."
+- "Leave feedback on a recommendation."
+- "Export this paper, recommendation, or feed as JSON."
+
+This is the core Paperzilla skill. It gives your agent direct access to Paperzilla data, but it does not impose a workflow or external delivery integration.
+
+## Access method
+
+Most current profiles in this repo use the `pz` CLI.
+
+If the current profile ships extra agent-specific instructions, follow those as well.
+
+### macOS
+```bash
+brew install paperzilla-ai/tap/pz
+```
+
+### Windows (Scoop)
+```bash
+scoop bucket add paperzilla-ai https://github.com/paperzilla-ai/scoop-bucket
+scoop install pz
+```
+
+### Linux
+Use the official Linux install guide:
+
+- https://docs.paperzilla.ai/guides/cli-getting-started
+
+### Build from source (Go 1.23+)
+See the CLI repository for source builds:
+
+- https://github.com/paperzilla-ai/pz
+
+## Update
+
+Check whether your CLI is up to date and get install-specific upgrade steps:
+
+```bash
+pz update
+```
+
+If detection is ambiguous, override it explicitly:
+
+```bash
+pz update --install-method homebrew
+pz update --install-method scoop
+pz update --install-method release
+pz update --install-method source
+
+## Authentication
+
+```bash
+pz login
+```
+
+## CLI reference
+
+If the current profile uses `pz`, these are the core commands.
+
+### List projects
+```bash
+pz project list
+```
+
+### Show one project
+```bash
+pz project <project-id>
+```
+
+### Browse project feed
+```bash
+pz feed <project-id>
+```
+
+Useful flags:
+- `--must-read`
+- `--since YYYY-MM-DD`
+- `--limit N`
+- `--json`
+- `--atom`
+
+Examples:
+```bash
+pz feed <project-id> --must-read --since 2026-03-01 --limit 5
+
+### Read a canonical paper
+```bash
+pz paper <paper-id>
+pz paper <paper-id> --json
+pz paper <paper-id> --markdown
+pz paper <paper-id> --project <project-id>
+```
+
+### Open a recommendation from one of your projects
+```bash
+pz rec <project-paper-id>
+pz rec <project-paper-id> --json
+pz rec <project-paper-id> --markdown
+```

package/skills/parallel-web/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: parallel-web
+description: "All-in-one web toolkit powered by parallel-cli, with a strong emphasis on academic and scientific sources. Use this skill whenever the user needs to search the web, fetch/extract URL content, enrich data with web-sourced fields, or run deep research reports. Covers: web search (fast lookups, research, current info — prioritizing peer-reviewed papers, preprints, and scholarly databases), URL extraction (fetching pages, articles, academic PDFs), bulk data enrichment (adding fields to CSV/lists from the web), and deep research (exhaustive multi-source reports grounded in academic literature). Also handles setup, status checks, and result retrieval. Use this skill for ANY web-related task — even if the user doesn't mention 'parallel' or 'web' explicitly. If they want to look something up, fetch a page, enrich a dataset, investigate a topic, find academic papers, check citations, or review scientific literature, this is the skill to use."
+---
+
+# Parallel Web Toolkit
+
+A unified skill for all web-powered tasks: searching, extracting, enriching, and researching — with academic and scientific sources as the default priority.
+
+## Routing — pick the right capability
+
+Read the user's request and match it to one of the capabilities below. For web search, extract, enrichment, and deep research, read the corresponding reference file for detailed instructions.
+
+| User wants to... | Capability | Where |
+|---|---|---|
+| Look something up, research a topic, find current info | **Web Search** | `(see docs)` |
+| Fetch content from a specific URL (webpage, article, PDF) | **Web Extract** | `(see docs)` |
+| Add web-sourced fields to a list of companies/people/products | **Data Enrichment** | `(see docs)` |
+| Get an exhaustive, multi-source report (user says "deep research", "exhaustive", "comprehensive") | **Deep Research** | `(see docs)` |
+| Install or authenticate parallel-cli | **Setup** | Below |
+| Check status of a running research/enrichment task | **Status** | Below |
+| Retrieve completed research results by run ID | **Result** | Below |
+
+### Decision guide
+
+- **Default to Web Search** for a single lookup, research question, or "what is X?" query. It's fast and cost-effective. When the query touches a scientific or technical topic, include academic domains (see `(see docs)`) to surface peer-reviewed and preprint sources alongside general results.
+- **Use Web Extract** when the user provides a URL or asks you to read/fetch a specific page. Prefer this over the built-in WebFetch tool. Particularly useful for extracting full text from academic PDFs, preprint servers, and journal articles.
+- **Use Data Enrichment** when the user has **multiple entities** (a CSV, a list of companies/people/products, or even a short inline list) and wants to find or add the same kind of information for each one. The key signal is a repeated lookup across a set of items — e.g., "find the CEO for each of these companies" or "get the founding year for Apple, Stripe, and Anthropic." Even if the user doesn't say "enrich," use `parallel-cli enrich` whenever the task is the same query applied to multiple entities. Do NOT use Web Search in a loop for this — the enrichment pipeline handles batching, parallelism, and structured output automatically.
+- **Use Deep Research only** when the user explicitly asks for deep, exhaustive, or comprehensive research. It is 10-100x slower and more expensive than Web Search — never default to it. Deep research is especially valuable for literature reviews and multi-paper synthesis.
+- If `parallel-cli` is not found when running any command, follow the Setup section below.
+
+### Academic source priority
+
+Across all capabilities, prefer academic and scientific sources when the query is technical or scientific in nature. This means:
+- Peer-reviewed journal articles and conference proceedings over blog posts or news articles
+- Preprints (arXiv, bioRxiv, medRxiv) when peer-reviewed versions aren't available
+- Institutional and government sources (NIH, WHO, NASA, NIST) over commercial sites
+- Primary research over secondary summaries
+
+When citing academic sources, include author names and publication year where available (e.g., [Smith et al., 2025](url)) in addition to the standard citation format. If a DOI is present, prefer the DOI link.
+
+## Context chaining
+
+Several capabilities support multi-turn context via `interaction_id`. When a research or enrichment task completes, it returns an `interaction_id`. If the user asks a follow-up question related to that task, pass `--previous-interaction-id` to carry context forward automatically. This avoids restating what was already found.
+
+---
+
+## Check task status
+
+```bash
+parallel-cli research status "$RUN_ID" --json
+```
+
+Report the current status to the user (running, completed, failed, etc.).
+
+## Get completed result
+
+```bash
+parallel-cli research poll "$RUN_ID" --json
+```
+
+Present results in a clear, organized format.
+
+

package/skills/pathfinder/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: pathfinder
+description: Map a codebase into feature-grouped flowcharts, identify duplicated concerns across features, and propose a unified architecture. Use when asked to "find the ideal path," unify duplicated systems, or audit architecture before a refactor. Emits a proposed unified flowchart plus per-system /make-plan prompts.
+---
+
+# Pathfinder
+
+You are an ORCHESTRATOR. Map the codebase into feature-grouped flowcharts, identify duplicated concerns, propose the simplest unified architecture, and hand off per-system plans to `/make-plan`.
+
+You do not write implementation code. You produce diagrams, a duplication report, a proposed unified flowchart, and handoff prompts.
+
+## Delegation Model
+
+Use subagents for *discovery and extraction* (file reading, flow tracing, grep, diagramming). Keep *synthesis* (deciding feature boundaries, picking unification strategies, final flowchart) with the orchestrator. Reject subagent reports that lack source citations and redeploy.
+
+### Subagent Reporting Contract (MANDATORY)
+
+Each subagent response must include:
+1. Sources consulted — exact file paths and line ranges read
+2. Concrete findings — exact function names, call sites, data flow
+3. Mermaid diagram(s) with nodes labeled by `file:line`
+4. Confidence note + known gaps
+
+## Output Artifacts
+
+All artifacts go in `PATHFINDER-<YYYY-MM-DD>/` at repo root:
+- `00-features.md` — feature inventory with boundaries
+- `01-flowcharts/<feature>.md` — one Mermaid flowchart per feature
+- `02-duplication-report.md` — cross-cutting duplicated concerns with evidence
+- `03-unified-proposal.md` — proposed unified architecture + Mermaid
+- `04-handoff-prompts.md` — copy-pasteable `/make-plan` prompts per unified system
+
+## Phases
+
+### Phase 0: Feature Discovery (ALWAYS FIRST)
+
+Deploy ONE "Feature Discovery" subagent to:
+1. Walk the source tree (not built artifacts) and read top-level README / CLAUDE.md
+2. Propose feature boundaries based on directory structure, import graph, and naming
+3. Return a flat list of features with: name, entry points (file:line), core files, brief purpose
+
+Orchestrator reviews the proposal, adjusts boundaries if needed, writes `00-features.md`. Do NOT fan out until feature boundaries are approved.
+
+### Phase 1: Per-Feature Flowcharts (FAN OUT)
+
+Deploy ONE "Flowchart" subagent per feature in parallel. Each receives only its feature's scope. Each must:
+1. Trace the feature's primary happy path from entry point to terminal state
+2. Identify side effects (DB writes, HTTP calls, file I/O, process spawns)
+3. Note error and fallback branches but do not let them dominate the diagram
+4. Produce a Mermaid `flowchart TD` with every node labeled `Name<br/>file:line`
+5. List external dependencies (other features it calls into) at the bottom
+
+Orchestrator writes each flowchart to `01-flowcharts/<feature>.md`. Reject any diagram missing `file:line` labels.
+
+### Phase 2: Duplication Hunt
+
+Deploy TWO subagents in parallel:
+
+**"Within-Feature Duplication"** subagent:
+- For each feature, find repeated code/logic patterns inside the feature only
+- Report only duplications worth consolidating (ignore trivial repetition)
+
+**"Cross-Feature Duplication"** subagent:
+- Compare flowcharts across features for concerns that appear in multiple places
+- Examples of what to look for: multiple capture paths, parallel queue implementations, duplicated storage/migration code, repeated agent scaffolding, parallel parsing layers
+- For each duplication, report: (a) the concern, (b) every location with `file:line`, (c) why they diverged, (d) whether the divergence is legitimate specialization or accidental
+
+Orchestrator synthesizes both into `02-duplication-report.md`. Every duplication claim must cite ≥2 `file:line` locations.
+
+### Phase 3: Unified Proposal (ORCHESTRATOR)
+
+The orchestrator writes `03-unified-proposal.md` itself — do not delegate synthesis.
+
+For each duplicated concern from Phase 2 that is NOT legitimate specialization:
+1. Propose the simplest unified design (one path, one store, one handler — whatever applies)
+2. Name the consolidated component and its single entry point
+3. Show what each old call site becomes
+4. Call out any loss of capability and whether it's acceptable
+
+End the document with ONE combined Mermaid flowchart showing the proposed unified system. Nodes still labeled with target `file:line` (new or existing) where knowable.
+
+**Anti-patterns to reject in your own proposal:**
+- Adding a new abstraction layer "for flexibility"
+- Keeping both old paths behind a feature flag
+- Introducing a registry/factory when a switch statement suffices
+- Preserving divergent behavior "just in case"
+
+### Phase 4: Per-System Handoff Prompts
+
+For each unified system in the proposal, write a ready-to-run `/make-plan` prompt to `04-handoff-prompts.md`. Each prompt must:
+1. State the target unified component and its single entry point
+2. List the exact call sites to rewrite (from Phase 2 evidence)
+3. Cite the relevant flowchart file from `01-flowcharts/`
+4. Include anti-pattern guards specific to this system
+
+Format each as a fenced code block the user can copy directly into `/make-plan`.
+
+## Key Principles
+
+- **Evidence over intuition** — every diagram node and duplication claim cites `file:line`
+- **Current state before ideal state** — Phases 0–2 describe what IS; Phase 3 describes what SHOULD BE
+- **Simplest unification wins** — prefer deletion over abstraction; prefer one path over configurable paths
+- **Specialization is not duplication** — two components serving different trust models or data sources are legitimate even if their code looks similar
+- **Handoff, don't implement** — Pathfinder ends at plan prompts; `/make-plan` and `/do` take it from there
+
+## Failure Modes to Prevent
+
+- Drawing flowcharts from memory instead of source — redeploy subagent with grep evidence requirement
+- Proposing unification of legitimately specialized components — re-examine trust/data-source divergence
+- Handoff prompts that lack concrete call sites — rewrite with Phase 2 evidence
+- Skipping Phase 0 boundary review — fanning out on bad feature boundaries wastes all of Phase 1
+
+
+

package/skills/pathml/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: pathml
+description: Full-featured computational pathology toolkit. Use for advanced WSI analysis including multiplexed immunofluorescence (CODEX, Vectra), nucleus segmentation, tissue graph construction, and ML model training on pathology data. Supports 160+ slide formats. For simple tile extraction from H&E slides, histolab may be simpler.
+---
+
+# PathML
+
+## Overview
+
+PathML is a comprehensive Python toolkit for computational pathology workflows, designed to facilitate machine learning and image analysis for whole-slide pathology images. The framework provides modular, composable tools for loading diverse slide formats, preprocessing images, constructing spatial graphs, training deep learning models, and analyzing multiparametric imaging data from technologies like CODEX and multiplex immunofluorescence.
+
+## When to Use This Skill
+
+Apply this skill for:
+- Loading and processing whole-slide images (WSI) in various proprietary formats
+- Preprocessing H&E stained tissue images with stain normalization
+- Nucleus detection, segmentation, and classification workflows
+- Building cell and tissue graphs for spatial analysis
+- Training or deploying machine learning models (HoVer-Net, HACTNet) on pathology data
+- Analyzing multiparametric imaging (CODEX, Vectra, MERFISH) for spatial proteomics
+- Quantifying marker expression from multiplex immunofluorescence
+- Managing large-scale pathology datasets with HDF5 storage
+- Tile-based analysis and stitching operations
+
+## Core Capabilities
+
+PathML provides six major capability areas documented in detail within reference files:
+
+### 2. Preprocessing Pipelines
+
+Build modular preprocessing pipelines by composing transforms for image manipulation, quality control, stain normalization, tissue detection, and mask operations. PathML's Pipeline architecture enables reproducible, scalable preprocessing across large datasets.
+
+**Key transforms:**
+- `StainNormalizationHE` - Macenko/Vahadane stain normalization
+- `TissueDetectionHE`, `NucleusDetectionHE` - Tissue/nucleus segmentation
+- `MedianBlur`, `GaussianBlur` - Noise reduction
+- `LabelArtifactTileHE` - Quality control for artifacts
+
+**See:** `(see docs)` for complete transform catalog, pipeline construction, and preprocessing workflows.
+
+### 3. Graph Construction
+
+Construct spatial graphs representing cellular and tissue-level relationships. Extract features from segmented objects to create graph-based representations suitable for graph neural networks and spatial analysis.
+
+**See:** `(see docs)` for graph construction methods, feature extraction, and spatial analysis workflows.
+
+### 4. Machine Learning
+
+Train and deploy deep learning models for nucleus detection, segmentation, and classification. PathML integrates PyTorch with pre-built models (HoVer-Net, HACTNet), custom DataLoaders, and ONNX support for inference.
+
+**Key models:**
+- **HoVer-Net** - Simultaneous nucleus segmentation and classification
+- **HACTNet** - Hierarchical cell-type classification
+
+**See:** `(see docs)` for model training, evaluation, inference workflows, and working with public datasets.
+
+### 5. Multiparametric Imaging
+
+Analyze spatial proteomics and gene expression data from CODEX, Vectra, MERFISH, and other multiplex imaging platforms. PathML provides specialized slide classes and transforms for processing multiparametric data, cell segmentation with Mesmer, and quantification workflows.
+
+**See:** `(see docs)` for CODEX/Vectra workflows, cell segmentation, marker quantification, and integration with AnnData.
+
+### 6. Data Management
+
+Efficiently store and manage large pathology datasets using HDF5 format. PathML handles tiles, masks, metadata, and extracted features in unified storage structures optimized for machine learning workflows.
+
+**See:** `(see docs)` for HDF5 integration, tile management, dataset organization, and batch processing strategies.
+
+## Quick Start
+
+# With optional dependencies for all features
+uv pip install pathml[all]
+```
+
+### Basic Workflow Example
+
+```python
+from pathml.core import SlideData
+from pathml.preprocessing import Pipeline, StainNormalizationHE, TissueDetectionHE
+
+# Load a whole-slide image
+wsi = SlideData.from_slide("path/to/slide.svs")
+
+# Create preprocessing pipeline
+pipeline = Pipeline([
+    TissueDetectionHE(),
+    StainNormalizationHE(target='normalize', stain_estimation_method='macenko')
+])
+
+# Run pipeline
+pipeline.run(wsi)
+
+# Access processed tiles
+for tile in wsi.tiles:
+    processed_image = tile.image
+    tissue_mask = tile.masks['tissue']
+
+