scoop

name

scoop

description

Execute and review auditable single-cell and spatial omics workflows with SCOOP. Use for H5AD validation, per-sample QC and doublet detection, embedding and clustering, FastCNMF programmes, evidence-based annotation, tumor CNV review, large-atlas scVI annotation and scPoli gating, spatial deconvolution, cell-cell communication, pseudobulk differential expression, abundance analysis, delivery, or maintenance of the SCOOP runtime and references.

SCOOP

Use SCOOP as one skill with one managed CLI. Keep biological decisions in the Skill and references; keep deterministic computation in the installed runtime.

Runtime boundary

Resolve SCOOP_HOME from a non-empty absolute environment value. Otherwise use ~/.scoop. Require the directory to exist before analysis. Invoke only:

"${SCOOP_HOME:-$HOME/.scoop}/bin/scoop" ...

Do not use a repository script, host Python, Conda executable, or a bare fast* command when the managed CLI is available. Run the relevant capability check before computation:

"${SCOOP_HOME:-$HOME/.scoop}/bin/scoop" doctor --json

Read runtime when installing, diagnosing dependencies, checking runtime capabilities, or resolving paths.

Operating contract

• Keep raw data read-only and retain raw counts in layers["counts"].
• Keep project data and run outputs in the caller's project, not in SCOOP Home.
• Use semantic stage names. Do not create order-prefixed files or directories.
• Write large tables externally; keep only stable per-cell state and registry references in H5AD.
• Require every stage to emit a receipt with inputs, outputs, hashes, quality, software versions, warnings, and review state.
• Consume only committed upstream artifacts. Invalidate descendants when an input, configuration, label table, or approval-bound hash changes.
• Never silently switch algorithms. Record fallbacks in the decision log.
• Do not let an Agent directly mutate H5AD annotation fields. Export evidence, validate structured decisions, then use the deterministic committer.

Read workflow contract for stage dependencies, resume rules, artifacts, and hard gates. Read design principles and storage structure when creating a run.

Route the workflow

Choose the narrowest workflow that satisfies the request:

Request	Route	Read before execution
Validate input, QC, embedding, programmes, annotation, delivery	standard	modules, QC, core, programmes, annotation
Tumor annotation or malignant/normal separation	tumor	Standard references plus tumor rules and the matching tissue reference
Multi-study or population atlas with scVI/scPoli	atlas	large atlas, annotation workflow
Spatial deconvolution or spatial graph	spatial	spatial stage, parameter rules
Candidate cell-cell communication	ccc	CCC stage, modules
Marker, condition DE, abundance, or survival	differential-expression	DE stage, modules

Create a plan before expensive computation:

"${SCOOP_HOME:-$HOME/.scoop}/bin/scoop" plan \
  --workflow <workflow> \
  --config <project>/runs/<run-id>/config/run.yaml

Execute only ready stages. Stop at any receipt with review_required=true.

Annotation

Read annotation workflow and naming strategy. Load only the relevant marker references:

• major cell types
• T cells
• myeloid
• fibroblast
• tumor general
• BRCA
• CRC
• GBM

Treat marker, negative-marker, programme, reference, CNV, neighbourhood, sample distribution, and QC evidence as separate evidence classes. Never accept a label from one method alone. Keep state programmes separate from cell identity.

Atlas gate

Treat the scVI stage as representation learning followed by graph construction, clustering, full annotation, confidence assignment, and a user-facing report. scVI itself does not predict biological labels.

The report must show subtype distributions, graph-neighbouring groups, positive/negative markers, reference conflicts, cluster-specific cNMF identity and functional programmes, QC risks, confidence, and the exact cells proposed for scPoli supervision.

Do not run scPoli until the managed CLI verifies an approved annotation gate. The approval must bind the annotation report, label table, input H5AD fingerprint, and labeled indices by SHA-256. Reject missing, rejected, incomplete, or stale approval. Exclude legacy, scANVI, medium-confidence, low-confidence, ambiguous, and suspicious cells from supervised indices.

Delivery

Return the requested biological or analytical result in the final response; do not return only internal paths. Also report the run ID, committed artifact, review state, important warnings, and reproducibility manifest path.