@bgicli/bgicli 2.1.1 → 2.2.0

package/data/skills/uniprot-database/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: uniprot-database
+description: "Direct REST API access to UniProt. Protein searches, FASTA retrieval, ID mapping, Swiss-Prot/TrEMBL. For Python workflows with multiple databases, prefer bioservices (unified interface to 40+ services). Use this for direct HTTP/REST work or UniProt-specific control."
+---
+
+# UniProt Database
+
+## Overview
+
+UniProt is the world's leading comprehensive protein sequence and functional information resource. Search proteins by name, gene, or accession, retrieve sequences in FASTA format, perform ID mapping across databases, access Swiss-Prot/TrEMBL annotations via REST API for protein analysis.
+
+## When to Use This Skill
+
+This skill should be used when:
+- Searching for protein entries by name, gene symbol, accession, or organism
+- Retrieving protein sequences in FASTA or other formats
+- Mapping identifiers between UniProt and external databases (Ensembl, RefSeq, PDB, etc.)
+- Accessing protein annotations including GO terms, domains, and functional descriptions
+- Batch retrieving multiple protein entries efficiently
+- Querying reviewed (Swiss-Prot) vs. unreviewed (TrEMBL) protein data
+- Streaming large protein datasets
+- Building custom queries with field-specific search syntax
+
+## Core Capabilities
+
+### 1. Searching for Proteins
+
+Search UniProt using natural language queries or structured search syntax.
+
+**Common search patterns:**
+```python
+# Search by protein name
+query = "insulin AND organism_name:\"Homo sapiens\""
+
+# Search by gene name
+query = "gene:BRCA1 AND reviewed:true"
+
+# Search by accession
+query = "accession:P12345"
+
+# Search by sequence length
+query = "length:[100 TO 500]"
+
+# Search by taxonomy
+query = "taxonomy_id:9606"  # Human proteins
+
+# Search by GO term
+query = "go:0005515"  # Protein binding
+```
+
+Use the API search endpoint: `https://rest.uniprot.org/uniprotkb/search?query={query}&format={format}`
+
+**Supported formats:** JSON, TSV, Excel, XML, FASTA, RDF, TXT
+
+### 2. Retrieving Individual Protein Entries
+
+Retrieve specific protein entries by accession number.
+
+**Accession number formats:**
+- Classic: P12345, Q1AAA9, O15530 (6 characters: letter + 5 alphanumeric)
+- Extended: A0A022YWF9 (10 characters for newer entries)
+
+**Retrieve endpoint:** `https://rest.uniprot.org/uniprotkb/{accession}.{format}`
+
+Example: `https://rest.uniprot.org/uniprotkb/P12345.fasta`
+
+### 3. Batch Retrieval and ID Mapping
+
+Map protein identifiers between different database systems and retrieve multiple entries efficiently.
+
+**ID Mapping workflow:**
+1. Submit mapping job to: `https://rest.uniprot.org/idmapping/run`
+2. Check job status: `https://rest.uniprot.org/idmapping/status/{jobId}`
+3. Retrieve results: `https://rest.uniprot.org/idmapping/results/{jobId}`
+
+**Supported databases for mapping:**
+- UniProtKB AC/ID
+- Gene names
+- Ensembl, RefSeq, EMBL
+- PDB, AlphaFoldDB
+- KEGG, GO terms
+- And many more (see `/references/id_mapping_databases.md`)
+
+**Limitations:**
+- Maximum 100,000 IDs per job
+- Results stored for 7 days
+
+### 4. Streaming Large Result Sets
+
+For large queries that exceed pagination limits, use the stream endpoint:
+
+`https://rest.uniprot.org/uniprotkb/stream?query={query}&format={format}`
+
+The stream endpoint returns all results without pagination, suitable for downloading complete datasets.
+
+### 5. Customizing Retrieved Fields
+
+Specify exactly which fields to retrieve for efficient data transfer.
+
+**Common fields:**
+- `accession` - UniProt accession number
+- `id` - Entry name
+- `gene_names` - Gene name(s)
+- `organism_name` - Organism
+- `protein_name` - Protein names
+- `sequence` - Amino acid sequence
+- `length` - Sequence length
+- `go_*` - Gene Ontology annotations
+- `cc_*` - Comment fields (function, interaction, etc.)
+- `ft_*` - Feature annotations (domains, sites, etc.)
+
+**Example:** `https://rest.uniprot.org/uniprotkb/search?query=insulin&fields=accession,gene_names,organism_name,length,sequence&format=tsv`
+
+See `/references/api_fields.md` for complete field list.
+
+## Python Implementation
+
+For programmatic access, use the provided helper script `scripts/uniprot_client.py` which implements:
+
+- `search_proteins(query, format)` - Search UniProt with any query
+- `get_protein(accession, format)` - Retrieve single protein entry
+- `map_ids(ids, from_db, to_db)` - Map between identifier types
+- `batch_retrieve(accessions, format)` - Retrieve multiple entries
+- `stream_results(query, format)` - Stream large result sets
+
+**Alternative Python packages:**
+- **Unipressed**: Modern, typed Python client for UniProt REST API
+- **bioservices**: Comprehensive bioinformatics web services client
+
+## Query Syntax Examples
+
+**Boolean operators:**
+```
+kinase AND organism_name:human
+(diabetes OR insulin) AND reviewed:true
+cancer NOT lung
+```
+
+**Field-specific searches:**
+```
+gene:BRCA1
+accession:P12345
+organism_id:9606
+taxonomy_name:"Homo sapiens"
+annotation:(type:signal)
+```
+
+**Range queries:**
+```
+length:[100 TO 500]
+mass:[50000 TO 100000]
+```
+
+**Wildcards:**
+```
+gene:BRCA*
+protein_name:kinase*
+```
+
+See `/references/query_syntax.md` for comprehensive syntax documentation.
+
+## Best Practices
+
+1. **Use reviewed entries when possible**: Filter with `reviewed:true` for Swiss-Prot (manually curated) entries
+2. **Specify format explicitly**: Choose the most appropriate format (FASTA for sequences, TSV for tabular data, JSON for programmatic parsing)
+3. **Use field selection**: Only request fields you need to reduce bandwidth and processing time
+4. **Handle pagination**: For large result sets, implement proper pagination or use the stream endpoint
+5. **Cache results**: Store frequently accessed data locally to minimize API calls
+6. **Rate limiting**: Be respectful of API resources; implement delays for large batch operations
+7. **Check data quality**: TrEMBL entries are computational predictions; Swiss-Prot entries are manually reviewed
+
+## Resources
+
+### scripts/
+`uniprot_client.py` - Python client with helper functions for common UniProt operations including search, retrieval, ID mapping, and streaming.
+
+### references/
+- `api_fields.md` - Complete list of available fields for customizing queries
+- `id_mapping_databases.md` - Supported databases for ID mapping operations
+- `query_syntax.md` - Comprehensive query syntax with advanced examples
+- `api_examples.md` - Code examples in multiple languages (Python, curl, R)
+
+## Additional Resources
+
+- **API Documentation**: https://www.uniprot.org/help/api
+- **Interactive API Explorer**: https://www.uniprot.org/api-documentation
+- **REST Tutorial**: https://www.uniprot.org/help/uniprot_rest_tutorial
+- **Query Syntax Help**: https://www.uniprot.org/help/query-fields
+- **SPARQL Endpoint**: https://sparql.uniprot.org/ (for advanced graph queries)

package/data/skills/universal-single-cell-annotator/SKILL.md

@@ -0,0 +1,72 @@
+<!--
+# COPYRIGHT NOTICE
+# This file is part of the "Universal Biomedical Skills" project.
+# Copyright (c) 2026 MD BABU MIA, PhD <md.babu.mia@mssm.edu>
+# All Rights Reserved.
+#
+# This code is proprietary and confidential.
+# Unauthorized copying of this file, via any medium is strictly prohibited.
+#
+# Provenance: Authenticated by MD BABU MIA
+
+-->
+
+---
+name: 'universal-single-cell-annotator'
+description: 'Annotate scRNA-seq'
+measurable_outcome: Execute skill workflow successfully with valid output within 15 minutes.
+allowed-tools:
+  - read_file
+  - run_shell_command
+---
+
+
+# Universal Single-Cell Annotator
+
+This skill wraps multiple cell type annotation strategies into a single Python class. It allows agents to flexibly choose between rule-based (markers), data-driven (CellTypist), or reasoning-based (LLM) approaches depending on the context.
+
+## When to Use This Skill
+
+*   **Initial Analysis**: When processing raw AnnData objects.
+*   **Validation**: When cross-referencing automated labels with known markers.
+*   **Discovery**: When identifying rare cell types using LLM reasoning on marker lists.
+
+## Core Capabilities
+
+1.  **Marker-Based Scoring**: Scores cells based on provided gene lists (e.g., "T-cell": ["CD3D", "CD3E"]).
+2.  **Deep Learning Reference**: Wraps `celltypist` to transfer labels from massive atlases.
+3.  **LLM Reasoning**: Extracts top markers per cluster and constructs prompts for LLM interpretation.
+
+## Workflow
+
+1.  **Load Data**: Ensure data is in `AnnData` format (standard for Scanpy).
+2.  **Choose Strategy**:
+    *   Use **Markers** if you have a known gene panel.
+    *   Use **CellTypist** for broad immune/tissue profiling.
+    *   Use **LLM** for novel clusters.
+3.  **Annotate**: Run the corresponding method.
+4.  **Inspect**: Check `adata.obs` for the new annotation columns.
+
+## Example Usage
+
+**User**: "Annotate this dataset looking for T-cells and B-cells."
+
+**Agent Action**:
+```python
+from universal_annotator import UniversalAnnotator
+import scanpy as sc
+
+adata = sc.read_h5ad('data.h5ad')
+annotator = UniversalAnnotator(adata)
+
+markers = {
+    'T-cell': ['CD3D', 'CD3E', 'CD8A'],
+    'B-cell': ['CD79A', 'MS4A1']
+}
+
+annotator.annotate_marker_based(markers)
+# Results in adata.obs['predicted_cell_type']
+```
+
+
+<!-- AUTHOR_SIGNATURE: 9a7f3c2e-MD-BABU-MIA-2026-MSSM-SECURE -->

package/data/skills/using-git-worktrees/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: using-git-worktrees
+description: Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with smart directory selection and safety verification
+---
+
+# Using Git Worktrees
+
+## Overview
+
+Git worktrees create isolated workspaces sharing the same repository, allowing work on multiple branches simultaneously without switching.
+
+**Core principle:** Systematic directory selection + safety verification = reliable isolation.
+
+**Announce at start:** "I'm using the using-git-worktrees skill to set up an isolated workspace."
+
+## Directory Selection Process
+
+Follow this priority order:
+
+### 1. Check Existing Directories
+
+```bash
+# Check in priority order
+ls -d .worktrees 2>/dev/null     # Preferred (hidden)
+ls -d worktrees 2>/dev/null      # Alternative
+```
+
+**If found:** Use that directory. If both exist, `.worktrees` wins.
+
+### 2. Check CLAUDE.md
+
+```bash
+grep -i "worktree.*director" CLAUDE.md 2>/dev/null
+```
+
+**If preference specified:** Use it without asking.
+
+### 3. Ask User
+
+If no directory exists and no CLAUDE.md preference:
+
+```
+No worktree directory found. Where should I create worktrees?
+
+1. .worktrees/ (project-local, hidden)
+2. ~/.config/superpowers/worktrees/<project-name>/ (global location)
+
+Which would you prefer?
+```
+
+## Safety Verification
+
+### For Project-Local Directories (.worktrees or worktrees)
+
+**MUST verify directory is ignored before creating worktree:**
+
+```bash
+# Check if directory is ignored (respects local, global, and system gitignore)
+git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null
+```
+
+**If NOT ignored:**
+
+Per Jesse's rule "Fix broken things immediately":
+1. Add appropriate line to .gitignore
+2. Commit the change
+3. Proceed with worktree creation
+
+**Why critical:** Prevents accidentally committing worktree contents to repository.
+
+### For Global Directory (~/.config/superpowers/worktrees)
+
+No .gitignore verification needed - outside project entirely.
+
+## Creation Steps
+
+### 1. Detect Project Name
+
+```bash
+project=$(basename "$(git rev-parse --show-toplevel)")
+```
+
+### 2. Create Worktree
+
+```bash
+# Determine full path
+case $LOCATION in
+  .worktrees|worktrees)
+    path="$LOCATION/$BRANCH_NAME"
+    ;;
+  ~/.config/superpowers/worktrees/*)
+    path="~/.config/superpowers/worktrees/$project/$BRANCH_NAME"
+    ;;
+esac
+
+# Create worktree with new branch
+git worktree add "$path" -b "$BRANCH_NAME"
+cd "$path"
+```
+
+### 3. Run Project Setup
+
+Auto-detect and run appropriate setup:
+
+```bash
+# Node.js
+if [ -f package.json ]; then npm install; fi
+
+# Rust
+if [ -f Cargo.toml ]; then cargo build; fi
+
+# Python
+if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+if [ -f pyproject.toml ]; then poetry install; fi
+
+# Go
+if [ -f go.mod ]; then go mod download; fi
+```
+
+### 4. Verify Clean Baseline
+
+Run tests to ensure worktree starts clean:
+
+```bash
+# Examples - use project-appropriate command
+npm test
+cargo test
+pytest
+go test ./...
+```
+
+**If tests fail:** Report failures, ask whether to proceed or investigate.
+
+**If tests pass:** Report ready.
+
+### 5. Report Location
+
+```
+Worktree ready at <full-path>
+Tests passing (<N> tests, 0 failures)
+Ready to implement <feature-name>
+```
+
+## Quick Reference
+
+| Situation | Action |
+|-----------|--------|
+| `.worktrees/` exists | Use it (verify ignored) |
+| `worktrees/` exists | Use it (verify ignored) |
+| Both exist | Use `.worktrees/` |
+| Neither exists | Check CLAUDE.md → Ask user |
+| Directory not ignored | Add to .gitignore + commit |
+| Tests fail during baseline | Report failures + ask |
+| No package.json/Cargo.toml | Skip dependency install |
+
+## Common Mistakes
+
+### Skipping ignore verification
+
+- **Problem:** Worktree contents get tracked, pollute git status
+- **Fix:** Always use `git check-ignore` before creating project-local worktree
+
+### Assuming directory location
+
+- **Problem:** Creates inconsistency, violates project conventions
+- **Fix:** Follow priority: existing > CLAUDE.md > ask
+
+### Proceeding with failing tests
+
+- **Problem:** Can't distinguish new bugs from pre-existing issues
+- **Fix:** Report failures, get explicit permission to proceed
+
+### Hardcoding setup commands
+
+- **Problem:** Breaks on projects using different tools
+- **Fix:** Auto-detect from project files (package.json, etc.)
+
+## Example Workflow
+
+```
+You: I'm using the using-git-worktrees skill to set up an isolated workspace.
+
+[Check .worktrees/ - exists]
+[Verify ignored - git check-ignore confirms .worktrees/ is ignored]
+[Create worktree: git worktree add .worktrees/auth -b feature/auth]
+[Run npm install]
+[Run npm test - 47 passing]
+
+Worktree ready at /Users/jesse/myproject/.worktrees/auth
+Tests passing (47 tests, 0 failures)
+Ready to implement auth feature
+```
+
+## Red Flags
+
+**Never:**
+- Create worktree without verifying it's ignored (project-local)
+- Skip baseline test verification
+- Proceed with failing tests without asking
+- Assume directory location when ambiguous
+- Skip CLAUDE.md check
+
+**Always:**
+- Follow directory priority: existing > CLAUDE.md > ask
+- Verify directory is ignored for project-local
+- Auto-detect and run project setup
+- Verify clean test baseline
+
+## Integration
+
+**Called by:**
+- **brainstorming** (Phase 4) - REQUIRED when design is approved and implementation follows
+- **subagent-driven-development** - REQUIRED before executing any tasks
+- **executing-plans** - REQUIRED before executing any tasks
+- Any skill needing isolated workspace
+
+**Pairs with:**
+- **finishing-a-development-branch** - REQUIRED for cleanup after work complete

package/data/skills/using-superpowers/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: using-superpowers
+description: Use when starting any conversation - establishes how to find and use skills, requiring Skill tool invocation before ANY response including clarifying questions
+---
+
+<EXTREMELY-IMPORTANT>
+If you think there is even a 1% chance a skill might apply to what you are doing, you ABSOLUTELY MUST invoke the skill.
+
+IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT.
+
+This is not negotiable. This is not optional. You cannot rationalize your way out of this.
+</EXTREMELY-IMPORTANT>
+
+## How to Access Skills
+
+**In Claude Code:** Use the `Skill` tool. When you invoke a skill, its content is loaded and presented to you—follow it directly. Never use the Read tool on skill files.
+
+**In other environments:** Check your platform's documentation for how skills are loaded.
+
+# Using Skills
+
+## The Rule
+
+**Invoke relevant or requested skills BEFORE any response or action.** Even a 1% chance a skill might apply means that you should invoke the skill to check. If an invoked skill turns out to be wrong for the situation, you don't need to use it.
+
+```dot
+digraph skill_flow {
+    "User message received" [shape=doublecircle];
+    "About to EnterPlanMode?" [shape=doublecircle];
+    "Already brainstormed?" [shape=diamond];
+    "Invoke brainstorming skill" [shape=box];
+    "Might any skill apply?" [shape=diamond];
+    "Invoke Skill tool" [shape=box];
+    "Announce: 'Using [skill] to [purpose]'" [shape=box];
+    "Has checklist?" [shape=diamond];
+    "Create TodoWrite todo per item" [shape=box];
+    "Follow skill exactly" [shape=box];
+    "Respond (including clarifications)" [shape=doublecircle];
+
+    "About to EnterPlanMode?" -> "Already brainstormed?";
+    "Already brainstormed?" -> "Invoke brainstorming skill" [label="no"];
+    "Already brainstormed?" -> "Might any skill apply?" [label="yes"];
+    "Invoke brainstorming skill" -> "Might any skill apply?";
+
+    "User message received" -> "Might any skill apply?";
+    "Might any skill apply?" -> "Invoke Skill tool" [label="yes, even 1%"];
+    "Might any skill apply?" -> "Respond (including clarifications)" [label="definitely not"];
+    "Invoke Skill tool" -> "Announce: 'Using [skill] to [purpose]'";
+    "Announce: 'Using [skill] to [purpose]'" -> "Has checklist?";
+    "Has checklist?" -> "Create TodoWrite todo per item" [label="yes"];
+    "Has checklist?" -> "Follow skill exactly" [label="no"];
+    "Create TodoWrite todo per item" -> "Follow skill exactly";
+}
+```
+
+## Red Flags
+
+These thoughts mean STOP—you're rationalizing:
+
+| Thought | Reality |
+|---------|---------|
+| "This is just a simple question" | Questions are tasks. Check for skills. |
+| "I need more context first" | Skill check comes BEFORE clarifying questions. |
+| "Let me explore the codebase first" | Skills tell you HOW to explore. Check first. |
+| "I can check git/files quickly" | Files lack conversation context. Check for skills. |
+| "Let me gather information first" | Skills tell you HOW to gather information. |
+| "This doesn't need a formal skill" | If a skill exists, use it. |
+| "I remember this skill" | Skills evolve. Read current version. |
+| "This doesn't count as a task" | Action = task. Check for skills. |
+| "The skill is overkill" | Simple things become complex. Use it. |
+| "I'll just do this one thing first" | Check BEFORE doing anything. |
+| "This feels productive" | Undisciplined action wastes time. Skills prevent this. |
+| "I know what that means" | Knowing the concept ≠ using the skill. Invoke it. |
+
+## Skill Priority
+
+When multiple skills could apply, use this order:
+
+1. **Process skills first** (brainstorming, debugging) - these determine HOW to approach the task
+2. **Implementation skills second** (frontend-design, mcp-builder) - these guide execution
+
+"Let's build X" → brainstorming first, then implementation skills.
+"Fix this bug" → debugging first, then domain-specific skills.
+
+## Skill Types
+
+**Rigid** (TDD, debugging): Follow exactly. Don't adapt away discipline.
+
+**Flexible** (patterns): Adapt principles to context.
+
+The skill itself tells you which.
+
+## User Instructions
+
+Instructions say WHAT, not HOW. "Add X" or "Fix Y" doesn't mean skip workflows.

package/data/skills/usmle/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: usmle
+slug: usmle
+version: 1.0.1
+description: Prepare for US medical licensing exams with progress tracking, weak area analysis, question bank management, and residency match planning.
+---
+
+## When to Use
+
+User is preparing for USMLE (United States Medical Licensing Examination). Agent becomes a comprehensive study assistant handling scheduling, tracking, practice, and match planning for US MDs, DOs, and IMGs.
+
+## Quick Reference
+
+| Topic | File |
+|-------|------|
+| Exam structure and scoring | `exam-config.md` |
+| Progress tracking system | `tracking.md` |
+| Study methods and resources | `study-methods.md` |
+| Stress management and wellbeing | `wellbeing.md` |
+| Residency targeting | `targets.md` |
+| User type adaptations | `user-types.md` |
+
+## Data Storage
+
+User data lives in `~/usmle/`:
+```
+~/usmle/
+├── profile.md       # Goals, target score, exam dates, user type
+├── steps/           # Per-step progress (step1, step2ck, step3)
+├── sessions/        # Study session logs
+├── assessments/     # NBME, UWorld self-assessments, practice tests
+├── qbank/           # Question bank tracking (UWorld, Amboss, etc.)
+└── feedback.md      # What works, what doesn't
+```
+
+## Core Capabilities
+
+1. **Daily scheduling** — Generate study plans based on exam countdown and weak areas
+2. **Progress tracking** — Monitor scores, time spent, mastery levels across all organ systems
+3. **Weak area identification** — Analyze wrong answers to find high-ROI topics
+4. **Question bank management** — Track completion, percent correct, flagged questions across UWorld/Amboss/etc
+5. **Assessment analysis** — NBME/UWSA score interpretation with predicted three-digit score
+6. **Residency targeting** — Match score expectations to specialty competitiveness
+
+## Decision Checklist
+
+Before study planning, gather:
+- [ ] Target Step (1, 2 CK, or 3)
+- [ ] Exam date and days remaining
+- [ ] User type (US MD, US DO, IMG, retaker)
+- [ ] Target score range or specialty
+- [ ] Current baseline (NBME/UWSA score if available)
+- [ ] Resources in use (UWorld, First Aid, Anki, etc.)
+
+## Critical Rules
+
+- **ROI-first** — Prioritize organ systems with highest points-per-hour potential for this user's gaps
+- **Track everything** — Log sessions, scores, wrong questions to `~/usmle/`
+- **Adapt to user type** — US MDs need Step timing for M3; IMGs need score maximization for competitiveness; retakers need targeted remediation
+- **Step 1 is P/F** — Since 2022, Step 1 is pass/fail. Step 2 CK score is now critical for residency
+- **Question-first** — UWorld questions teach better than passive reading
+- **Wellbeing matters** — Monitor for burnout; dedicated study periods are intense