scraps: Instructions file for Codex

AGENTS.md - Developer Guide for scraps

This is the single guide for coding agents (Claude Code, Codex, opencode, ...) and humans working in the scraps repository: commands, architecture, conventions and gotchas. Claude Code reads this file directly; there is deliberately no separate CLAUDE.md.

Project: scraps - Single Cell RNA PolyA Site Discovery
Type: Snakemake bioinformatics pipeline that extracts mRNA polyadenylation (RT priming) sites from "TVN"-primed 3' single-cell RNA-seq FASTQs, or from pre-aligned, barcode-tagged BAMs, at near-nucleotide resolution
Primary Languages: Python 3, R, Snakemake, Shell (zsh)

Quick Start Commands

Running the Pipeline

# Dry-run to validate pipeline (recommended before any changes)
snakemake -np --configfile config.yaml

# Run pipeline (--cores/-j is mandatory for a real run; needs the STAR index and
# whitelists from the README Setup section, which are not bundled; each STAR job
# uses total_impact=5, so --resources total_impact=5 runs one STAR job at a time)
snakemake -j 8 --configfile config.yaml --resources total_impact=5 --keep-going

# Generate DAG visualization (the Snakefile's logger output goes to stderr outside
# dry-runs, so stdout is clean DOT)
snakemake --dag --configfile config.yaml | dot -Tpdf > dag.pdf

# Regenerate the README's inst/dag.pdf: rule graph with every arm and discovery on.
# dag_override.yaml contains:
#   GENOME_FASTA: "ref/genome.fa"
#   DISCOVERY: {enabled: true, read: [R1, R2, paired, bam]}
snakemake --rulegraph --configfile config.yaml dag_override.yaml | dot -Tpdf > inst/dag.pdf

--configfile other.yaml is deep-merged over the hardcoded config.yaml (Snakemake update_config), so SAMPLES from both files are unioned unless the override redefines every key. Add --replace-workflow-config (Snakemake 9) to use only the given file instead.

Cluster (SLURM): submit one job per rule with the bundled profile, after setting the account and partition (see profiles/slurm/README.md); --cluster/--drmaa no longer exist in Snakemake 8+.