@bgicli/bgicli 2.1.1 → 2.2.1

package/data/skills/scikit-survival/SKILL.md

@@ -0,0 +1,393 @@
+---
+name: scikit-survival
+description: Comprehensive toolkit for survival analysis and time-to-event modeling in Python using scikit-survival. Use this skill when working with censored survival data, performing time-to-event analysis, fitting Cox models, Random Survival Forests, Gradient Boosting models, or Survival SVMs, evaluating survival predictions with concordance index or Brier score, handling competing risks, or implementing any survival analysis workflow with the scikit-survival library.
+---
+
+# scikit-survival: Survival Analysis in Python
+
+## Overview
+
+scikit-survival is a Python library for survival analysis built on top of scikit-learn. It provides specialized tools for time-to-event analysis, handling the unique challenge of censored data where some observations are only partially known.
+
+Survival analysis aims to establish connections between covariates and the time of an event, accounting for censored records (particularly right-censored data from studies where participants don't experience events during observation periods).
+
+## When to Use This Skill
+
+Use this skill when:
+- Performing survival analysis or time-to-event modeling
+- Working with censored data (right-censored, left-censored, or interval-censored)
+- Fitting Cox proportional hazards models (standard or penalized)
+- Building ensemble survival models (Random Survival Forests, Gradient Boosting)
+- Training Survival Support Vector Machines
+- Evaluating survival model performance (concordance index, Brier score, time-dependent AUC)
+- Estimating Kaplan-Meier or Nelson-Aalen curves
+- Analyzing competing risks
+- Preprocessing survival data or handling missing values in survival datasets
+- Conducting any analysis using the scikit-survival library
+
+## Core Capabilities
+
+### 1. Model Types and Selection
+
+scikit-survival provides multiple model families, each suited for different scenarios:
+
+#### Cox Proportional Hazards Models
+**Use for**: Standard survival analysis with interpretable coefficients
+- `CoxPHSurvivalAnalysis`: Basic Cox model
+- `CoxnetSurvivalAnalysis`: Penalized Cox with elastic net for high-dimensional data
+- `IPCRidge`: Ridge regression for accelerated failure time models
+
+**See**: `references/cox-models.md` for detailed guidance on Cox models, regularization, and interpretation
+
+#### Ensemble Methods
+**Use for**: High predictive performance with complex non-linear relationships
+- `RandomSurvivalForest`: Robust, non-parametric ensemble method
+- `GradientBoostingSurvivalAnalysis`: Tree-based boosting for maximum performance
+- `ComponentwiseGradientBoostingSurvivalAnalysis`: Linear boosting with feature selection
+- `ExtraSurvivalTrees`: Extremely randomized trees for additional regularization
+
+**See**: `references/ensemble-models.md` for comprehensive guidance on ensemble methods, hyperparameter tuning, and when to use each model
+
+#### Survival Support Vector Machines
+**Use for**: Medium-sized datasets with margin-based learning
+- `FastSurvivalSVM`: Linear SVM optimized for speed
+- `FastKernelSurvivalSVM`: Kernel SVM for non-linear relationships
+- `HingeLossSurvivalSVM`: SVM with hinge loss
+- `ClinicalKernelTransform`: Specialized kernel for clinical + molecular data
+
+**See**: `references/svm-models.md` for detailed SVM guidance, kernel selection, and hyperparameter tuning
+
+#### Model Selection Decision Tree
+
+```
+Start
+├─ High-dimensional data (p > n)?
+│  ├─ Yes → CoxnetSurvivalAnalysis (elastic net)
+│  └─ No → Continue
+│
+├─ Need interpretable coefficients?
+│  ├─ Yes → CoxPHSurvivalAnalysis or ComponentwiseGradientBoostingSurvivalAnalysis
+│  └─ No → Continue
+│
+├─ Complex non-linear relationships expected?
+│  ├─ Yes
+│  │  ├─ Large dataset (n > 1000) → GradientBoostingSurvivalAnalysis
+│  │  ├─ Medium dataset → RandomSurvivalForest or FastKernelSurvivalSVM
+│  │  └─ Small dataset → RandomSurvivalForest
+│  └─ No → CoxPHSurvivalAnalysis or FastSurvivalSVM
+│
+└─ For maximum performance → Try multiple models and compare
+```
+
+### 2. Data Preparation and Preprocessing
+
+Before modeling, properly prepare survival data:
+
+#### Creating Survival Outcomes
+```python
+from sksurv.util import Surv
+
+# From separate arrays
+y = Surv.from_arrays(event=event_array, time=time_array)
+
+# From DataFrame
+y = Surv.from_dataframe('event', 'time', df)
+```
+
+#### Essential Preprocessing Steps
+1. **Handle missing values**: Imputation strategies for features
+2. **Encode categorical variables**: One-hot encoding or label encoding
+3. **Standardize features**: Critical for SVMs and regularized Cox models
+4. **Validate data quality**: Check for negative times, sufficient events per feature
+5. **Train-test split**: Maintain similar censoring rates across splits
+
+**See**: `references/data-handling.md` for complete preprocessing workflows, data validation, and best practices
+
+### 3. Model Evaluation
+
+Proper evaluation is critical for survival models. Use appropriate metrics that account for censoring:
+
+#### Concordance Index (C-index)
+Primary metric for ranking/discrimination:
+- **Harrell's C-index**: Use for low censoring (<40%)
+- **Uno's C-index**: Use for moderate to high censoring (>40%) - more robust
+
+```python
+from sksurv.metrics import concordance_index_censored, concordance_index_ipcw
+
+# Harrell's C-index
+c_harrell = concordance_index_censored(y_test['event'], y_test['time'], risk_scores)[0]
+
+# Uno's C-index (recommended)
+c_uno = concordance_index_ipcw(y_train, y_test, risk_scores)[0]
+```
+
+#### Time-Dependent AUC
+Evaluate discrimination at specific time points:
+
+```python
+from sksurv.metrics import cumulative_dynamic_auc
+
+times = [365, 730, 1095]  # 1, 2, 3 years
+auc, mean_auc = cumulative_dynamic_auc(y_train, y_test, risk_scores, times)
+```
+
+#### Brier Score
+Assess both discrimination and calibration:
+
+```python
+from sksurv.metrics import integrated_brier_score
+
+ibs = integrated_brier_score(y_train, y_test, survival_functions, times)
+```
+
+**See**: `references/evaluation-metrics.md` for comprehensive evaluation guidance, metric selection, and using scorers with cross-validation
+
+### 4. Competing Risks Analysis
+
+Handle situations with multiple mutually exclusive event types:
+
+```python
+from sksurv.nonparametric import cumulative_incidence_competing_risks
+
+# Estimate cumulative incidence for each event type
+time_points, cif_event1, cif_event2 = cumulative_incidence_competing_risks(y)
+```
+
+**Use competing risks when**:
+- Multiple mutually exclusive event types exist (e.g., death from different causes)
+- Occurrence of one event prevents others
+- Need probability estimates for specific event types
+
+**See**: `references/competing-risks.md` for detailed competing risks methods, cause-specific hazard models, and interpretation
+
+### 5. Non-parametric Estimation
+
+Estimate survival functions without parametric assumptions:
+
+#### Kaplan-Meier Estimator
+```python
+from sksurv.nonparametric import kaplan_meier_estimator
+
+time, survival_prob = kaplan_meier_estimator(y['event'], y['time'])
+```
+
+#### Nelson-Aalen Estimator
+```python
+from sksurv.nonparametric import nelson_aalen_estimator
+
+time, cumulative_hazard = nelson_aalen_estimator(y['event'], y['time'])
+```
+
+## Typical Workflows
+
+### Workflow 1: Standard Survival Analysis
+
+```python
+from sksurv.datasets import load_breast_cancer
+from sksurv.linear_model import CoxPHSurvivalAnalysis
+from sksurv.metrics import concordance_index_ipcw
+from sklearn.model_selection import train_test_split
+from sklearn.preprocessing import StandardScaler
+
+# 1. Load and prepare data
+X, y = load_breast_cancer()
+X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, random_state=42)
+
+# 2. Preprocess
+scaler = StandardScaler()
+X_train_scaled = scaler.fit_transform(X_train)
+X_test_scaled = scaler.transform(X_test)
+
+# 3. Fit model
+estimator = CoxPHSurvivalAnalysis()
+estimator.fit(X_train_scaled, y_train)
+
+# 4. Predict
+risk_scores = estimator.predict(X_test_scaled)
+
+# 5. Evaluate
+c_index = concordance_index_ipcw(y_train, y_test, risk_scores)[0]
+print(f"C-index: {c_index:.3f}")
+```
+
+### Workflow 2: High-Dimensional Data with Feature Selection
+
+```python
+from sksurv.linear_model import CoxnetSurvivalAnalysis
+from sklearn.model_selection import GridSearchCV
+from sksurv.metrics import as_concordance_index_ipcw_scorer
+
+# 1. Use penalized Cox for feature selection
+estimator = CoxnetSurvivalAnalysis(l1_ratio=0.9)  # Lasso-like
+
+# 2. Tune regularization with cross-validation
+param_grid = {'alpha_min_ratio': [0.01, 0.001]}
+cv = GridSearchCV(estimator, param_grid,
+                  scoring=as_concordance_index_ipcw_scorer(), cv=5)
+cv.fit(X, y)
+
+# 3. Identify selected features
+best_model = cv.best_estimator_
+selected_features = np.where(best_model.coef_ != 0)[0]
+```
+
+### Workflow 3: Ensemble Method for Maximum Performance
+
+```python
+from sksurv.ensemble import GradientBoostingSurvivalAnalysis
+from sklearn.model_selection import GridSearchCV
+
+# 1. Define parameter grid
+param_grid = {
+    'learning_rate': [0.01, 0.05, 0.1],
+    'n_estimators': [100, 200, 300],
+    'max_depth': [3, 5, 7]
+}
+
+# 2. Grid search
+gbs = GradientBoostingSurvivalAnalysis()
+cv = GridSearchCV(gbs, param_grid, cv=5,
+                  scoring=as_concordance_index_ipcw_scorer(), n_jobs=-1)
+cv.fit(X_train, y_train)
+
+# 3. Evaluate best model
+best_model = cv.best_estimator_
+risk_scores = best_model.predict(X_test)
+c_index = concordance_index_ipcw(y_train, y_test, risk_scores)[0]
+```
+
+### Workflow 4: Comprehensive Model Comparison
+
+```python
+from sksurv.linear_model import CoxPHSurvivalAnalysis
+from sksurv.ensemble import RandomSurvivalForest, GradientBoostingSurvivalAnalysis
+from sksurv.svm import FastSurvivalSVM
+from sksurv.metrics import concordance_index_ipcw, integrated_brier_score
+
+# Define models
+models = {
+    'Cox': CoxPHSurvivalAnalysis(),
+    'RSF': RandomSurvivalForest(n_estimators=100, random_state=42),
+    'GBS': GradientBoostingSurvivalAnalysis(random_state=42),
+    'SVM': FastSurvivalSVM(random_state=42)
+}
+
+# Evaluate each model
+results = {}
+for name, model in models.items():
+    model.fit(X_train_scaled, y_train)
+    risk_scores = model.predict(X_test_scaled)
+    c_index = concordance_index_ipcw(y_train, y_test, risk_scores)[0]
+    results[name] = c_index
+    print(f"{name}: C-index = {c_index:.3f}")
+
+# Select best model
+best_model_name = max(results, key=results.get)
+print(f"\nBest model: {best_model_name}")
+```
+
+## Integration with scikit-learn
+
+scikit-survival fully integrates with scikit-learn's ecosystem:
+
+```python
+from sklearn.pipeline import Pipeline
+from sklearn.preprocessing import StandardScaler
+from sklearn.model_selection import cross_val_score, GridSearchCV
+
+# Use pipelines
+pipeline = Pipeline([
+    ('scaler', StandardScaler()),
+    ('model', CoxPHSurvivalAnalysis())
+])
+
+# Use cross-validation
+scores = cross_val_score(pipeline, X, y, cv=5,
+                         scoring=as_concordance_index_ipcw_scorer())
+
+# Use grid search
+param_grid = {'model__alpha': [0.1, 1.0, 10.0]}
+cv = GridSearchCV(pipeline, param_grid, cv=5)
+cv.fit(X, y)
+```
+
+## Best Practices
+
+1. **Always standardize features** for SVMs and regularized Cox models
+2. **Use Uno's C-index** instead of Harrell's when censoring > 40%
+3. **Report multiple evaluation metrics** (C-index, integrated Brier score, time-dependent AUC)
+4. **Check proportional hazards assumption** for Cox models
+5. **Use cross-validation** for hyperparameter tuning with appropriate scorers
+6. **Validate data quality** before modeling (check for negative times, sufficient events per feature)
+7. **Compare multiple model types** to find best performance
+8. **Use permutation importance** for Random Survival Forests (not built-in importance)
+9. **Consider competing risks** when multiple event types exist
+10. **Document censoring mechanism** and rates in analysis
+
+## Common Pitfalls to Avoid
+
+1. **Using Harrell's C-index with high censoring** → Use Uno's C-index
+2. **Not standardizing features for SVMs** → Always standardize
+3. **Forgetting to pass y_train to concordance_index_ipcw** → Required for IPCW calculation
+4. **Treating competing events as censored** → Use competing risks methods
+5. **Not checking for sufficient events per feature** → Rule of thumb: 10+ events per feature
+6. **Using built-in feature importance for RSF** → Use permutation importance
+7. **Ignoring proportional hazards assumption** → Validate or use alternative models
+8. **Not using appropriate scorers in cross-validation** → Use as_concordance_index_ipcw_scorer()
+
+## Reference Files
+
+This skill includes detailed reference files for specific topics:
+
+- **`references/cox-models.md`**: Complete guide to Cox proportional hazards models, penalized Cox (CoxNet), IPCRidge, regularization strategies, and interpretation
+- **`references/ensemble-models.md`**: Random Survival Forests, Gradient Boosting, hyperparameter tuning, feature importance, and model selection
+- **`references/evaluation-metrics.md`**: Concordance index (Harrell's vs Uno's), time-dependent AUC, Brier score, comprehensive evaluation pipelines
+- **`references/data-handling.md`**: Data loading, preprocessing workflows, handling missing data, feature encoding, validation checks
+- **`references/svm-models.md`**: Survival Support Vector Machines, kernel selection, clinical kernel transform, hyperparameter tuning
+- **`references/competing-risks.md`**: Competing risks analysis, cumulative incidence functions, cause-specific hazard models
+
+Load these reference files when detailed information is needed for specific tasks.
+
+## Additional Resources
+
+- **Official Documentation**: https://scikit-survival.readthedocs.io/
+- **GitHub Repository**: https://github.com/sebp/scikit-survival
+- **Built-in Datasets**: Use `sksurv.datasets` for practice datasets (GBSG2, WHAS500, veterans lung cancer, etc.)
+- **API Reference**: Complete list of classes and functions at https://scikit-survival.readthedocs.io/en/stable/api/index.html
+
+## Quick Reference: Key Imports
+
+```python
+# Models
+from sksurv.linear_model import CoxPHSurvivalAnalysis, CoxnetSurvivalAnalysis, IPCRidge
+from sksurv.ensemble import RandomSurvivalForest, GradientBoostingSurvivalAnalysis
+from sksurv.svm import FastSurvivalSVM, FastKernelSurvivalSVM
+from sksurv.tree import SurvivalTree
+
+# Evaluation metrics
+from sksurv.metrics import (
+    concordance_index_censored,
+    concordance_index_ipcw,
+    cumulative_dynamic_auc,
+    brier_score,
+    integrated_brier_score,
+    as_concordance_index_ipcw_scorer,
+    as_integrated_brier_score_scorer
+)
+
+# Non-parametric estimation
+from sksurv.nonparametric import (
+    kaplan_meier_estimator,
+    nelson_aalen_estimator,
+    cumulative_incidence_competing_risks
+)
+
+# Data handling
+from sksurv.util import Surv
+from sksurv.preprocessing import OneHotEncoder, encode_categorical
+from sksurv.datasets import load_gbsg2, load_breast_cancer, load_veterans_lung_cancer
+
+# Kernels
+from sksurv.kernels import ClinicalKernelTransform
+```

package/data/skills/scrna-orchestrator/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: scrna-orchestrator
+description: Local Scanpy pipeline for single-cell RNA-seq QC, clustering, marker discovery, and optional two-group differential expression from raw-count .h5ad.
+version: 0.1.0
+author: Yonghao Zhao
+license: MIT
+tags: [scrna, single-cell, scanpy, clustering, differential-expression]
+metadata:
+  openclaw:
+    requires:
+      bins:
+        - python3
+      env: []
+      config: []
+    always: false
+    emoji: "🦖"
+    homepage: https://github.com/ClawBio/ClawBio
+    os: [macos, linux]
+    install:
+      - kind: uv
+        package: scanpy
+        bins: []
+      - kind: uv
+        package: anndata
+        bins: []
+    trigger_keywords:
+      - scrna
+      - single-cell
+      - scanpy
+      - h5ad
+      - leiden
+      - marker genes
+      - differential expression
+---
+
+# 🦖 scRNA Orchestrator
+
+You are **scRNA Orchestrator**, a specialised ClawBio agent for local single-cell RNA-seq analysis with Scanpy.
+
+## Why This Exists
+
+Single-cell workflows are easy to misconfigure and hard to reproduce when run ad hoc.
+
+- **Without it**: Users manually stitch QC, normalization, clustering, and marker/DE steps with inconsistent defaults.
+- **With it**: One command produces a consistent `report.md`, figures, tables, and reproducibility bundle.
+- **Why ClawBio**: The workflow is local-first, explicit about assumptions (raw counts), and ships machine-readable outputs.
+
+## Core Capabilities
+
+1. **QC and Filtering**: Mitochondrial percentage filtering and min genes/cells thresholds.
+2. **Preprocessing**: Library-size normalization, `log1p`, and HVG selection.
+3. **Embedding and Clustering**: PCA, neighbors graph, UMAP, Leiden clustering.
+4. **Cluster Markers**: Wilcoxon cluster-vs-rest marker detection.
+5. **Optional Group DE (v1)**: Two-group Wilcoxon DE on any `obs` column.
+6. **Optional Volcano Plot**: Generate DE volcano plot with `--de-volcano`.
+7. **Reporting**: Markdown report, CSV/TSV tables, PNG figures, reproducibility files.
+
+## Input Formats
+
+| Format | Extension | Required Fields | Example |
+|--------|-----------|-----------------|---------|
+| AnnData raw counts | `.h5ad` | Raw count matrix in `X`; cell metadata in `obs`; gene metadata in `var` | `pbmc_raw.h5ad` |
+| Demo mode | n/a | none | `python clawbio.py run scrna --demo` |
+
+Notes:
+- Processed/normalized/scaled `.h5ad` inputs are rejected with an actionable error.
+- `pbmc3k_processed`-style inputs are out of scope for this skill.
+
+## Workflow
+
+When the user asks for scRNA QC/clustering/markers/DE:
+
+1. **Validate**: Check `.h5ad` input (or `--demo`), and reject processed-like matrices.
+2. **Process**: Run QC filtering, normalization, HVG selection, PCA, neighbors, UMAP, and Leiden.
+3. **Analyze**:
+- Always run cluster marker analysis (`leiden`, Wilcoxon).
+- Optionally run DE if `--de-groupby --de-group1 --de-group2` are all provided.
+4. **Generate**: Write `report.md`, `result.json`, tables, figures, and reproducibility bundle.
+
+## CLI Reference
+
+```bash
+# Standard usage
+python skills/scrna-orchestrator/scrna_orchestrator.py \
+  --input <input.h5ad> --output <report_dir>
+
+# Demo mode
+python skills/scrna-orchestrator/scrna_orchestrator.py \
+  --demo --output <report_dir>
+
+# Optional two-group DE
+python skills/scrna-orchestrator/scrna_orchestrator.py \
+  --input <input.h5ad> --output <report_dir> \
+  --de-groupby <obs_column> --de-group1 <group_a> --de-group2 <group_b>
+
+# Optional DE volcano plot
+python skills/scrna-orchestrator/scrna_orchestrator.py \
+  --input <input.h5ad> --output <report_dir> \
+  --de-groupby <obs_column> --de-group1 <group_a> --de-group2 <group_b> \
+  --de-volcano
+
+# Via ClawBio runner
+python clawbio.py run scrna --input <input.h5ad> --output <report_dir>
+python clawbio.py run scrna --demo
+```
+
+## Demo
+
+```bash
+python clawbio.py run scrna --demo
+```
+
+Expected output:
+- `report.md` with QC, clustering, and marker summaries
+- figure files (`qc_violin.png`, `umap_leiden.png`, `marker_dotplot.png`)
+- optional DE figure (`de_volcano.png`) when `--de-volcano` is set
+- marker tables and reproducibility bundle
+
+## Algorithm / Methodology
+
+1. **QC**:
+- Compute QC metrics (`n_genes_by_counts`, `total_counts`, `pct_counts_mt`)
+- Filter by `min_genes`, `min_cells`, `max_mt_pct`
+2. **Preprocess**:
+- Normalize total counts to `1e4`
+- Apply `log1p`
+- Select HVGs (`flavor="seurat"`)
+3. **Embed and cluster**:
+- Scale (`max_value=10`)
+- PCA, neighbors graph, UMAP
+- Leiden clustering
+4. **Markers**:
+- `scanpy.tl.rank_genes_groups(groupby="leiden", method="wilcoxon", pts=True)`
+5. **Optional DE v1**:
+- `scanpy.tl.rank_genes_groups(groupby=<de_groupby>, groups=[group1], reference=group2, method="wilcoxon", pts=True)`
+- Export full statistics and top genes by score
+6. **Optional volcano plot**:
+- Plot `logfoldchanges` vs `-log10(pvals_adj)` (fallback to `pvals` if needed)
+- Highlight genes with `p < 0.05` and `|log2FC| >= 1`
+
+## Example Queries
+
+- "Run standard QC and clustering on my h5ad file"
+- "Find marker genes for each cluster"
+- "Generate a UMAP coloured by cluster"
+- "Run differential expression for treated vs control"
+
+## Output Structure
+
+```text
+output_directory/
+├── report.md
+├── result.json
+├── figures/
+│   ├── qc_violin.png
+│   ├── umap_leiden.png
+│   ├── marker_dotplot.png
+│   └── de_volcano.png    # only when DE volcano is enabled
+├── tables/
+│   ├── cluster_summary.csv
+│   ├── markers_top.csv
+│   ├── markers_top.tsv
+│   ├── de_full.csv      # only when DE is enabled
+│   └── de_top.csv       # only when DE is enabled
+└── reproducibility/
+    ├── commands.sh
+    ├── environment.yml
+    └── checksums.sha256
+```
+
+## Dependencies
+
+**Required**:
+- `scanpy` >= 1.10
+- `anndata` >= 0.10
+- `numpy`, `pandas`, `matplotlib`, `leidenalg`, `python-igraph`
+
+**Optional (future)**:
+- `celltypist` (cell-type annotation)
+- `scvi-tools` (deep generative modeling)
+
+## Safety
+
+- **Local-first**: No patient data upload.
+- **Disclaimer**: Reports include the ClawBio medical disclaimer.
+- **Input guardrails**: Rejects processed-like matrices to reduce invalid biological inferences.
+- **Reproducibility**: Writes command/environment/checksum bundle.
+
+## Integration with Bio Orchestrator
+
+**Trigger conditions**:
+- File extension `.h5ad`
+- User intent includes scRNA terms (single-cell, Scanpy, clustering, marker genes, DE)
+
+**Current limitations**:
+- Raw-count `.h5ad` only
+- Seurat input/output is not implemented in Python path
+- Multi-group pairwise DE, within-cluster DE, and automated annotation are future work
+
+## Citations
+
+- [Scanpy documentation](https://scanpy.readthedocs.io/) — analysis API and methods.
+- [AnnData documentation](https://anndata.readthedocs.io/) — data model.
+- [Leiden algorithm paper](https://www.nature.com/articles/s41598-019-41695-z) — community detection.

package/data/skills/scrna-qc/SKILL.md

@@ -0,0 +1,43 @@
+<!--
+# 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: scrna-qc
+description: Execute the MAD-based single-cell RNA-seq QC workflow (scripts + Python API) to filter low-quality cells and emit reports plus filtered AnnData files.
+measurable_outcome: Produce filtered .h5ad files, before/after plots, and qc_summary.json within 20 minutes per dataset.
+allowed-tools:
+  - read_file
+  - run_shell_command
+---
+
+## At-a-Glance
+- **description (10-20 chars):** QC autopilot
+- **keywords:** scRNAseq, MAD, h5ad, QC, plots
+
+## Workflow
+1. Accept `.h5ad`, 10x `.h5`, or 10x directory inputs; set mitochondrial/ribosomal patterns as needed.
+2. Run `qc_analysis.py` (CLI) or call `qc_core` helpers to compute metrics, apply MAD thresholds, and filter cells/genes.
+3. Generate standard plots (metrics before/after, threshold overlays) plus filtered data artifacts.
+4. Document parameters (mad_counts/genes/mt, mt_threshold, min_cells, log1p flag) inside the summary JSON.
+5. Provide guidance on next steps (doublet detection, downstream analysis).
+
+## Guardrails
+- Adjust MT% expectations for tissue context; avoid over-filtering rare populations.
+- This workflow is QC only—doublet handling and batch correction stay separate.
+- Keep reproducibility by storing command invocations and environment info.
+
+## References
+- See `README.md`, `qc_core.py`, `qc_analysis.py`, and `qc_plotting.py` for API usage and schema details.
+
+
+<!-- AUTHOR_SIGNATURE: 9a7f3c2e-MD-BABU-MIA-2026-MSSM-SECURE -->