Skip to content

Playbooks

Playbooks are YAML knowledge files that encode best practices, recommended tools, and domain-specific context for a given omics type. When you start a pipeline build, Codaris automatically detects the biological domain from your description and loads the matching playbook into the agent's context before generating a single line of Nextflow.

What a Playbook Does

When Codaris builds a pipeline, the playbook injects three things into the system context:

  1. Domain name — so the agent knows it's working in WGS vs RNA-seq vs metagenomics territory
  2. Recommended tools — the curated list of nf-core modules the agent will prefer and install
  3. Best practices — domain-specific rules the agent enforces automatically (aligner choice, QC thresholds, required steps)

You never need to specify these manually. Describe your experiment in plain language and the agent resolves the playbook.

Built-in Playbooks

Domain Playbook Key Tools
Bulk RNA-seq rnaseq STAR, Salmon, featureCounts, MultiQC
WGS Germline wgs bwa-mem2, GATK4 HaplotypeCaller
WGS Somatic wgs-somatic Mutect2, Strelka, Manta
ChIP-seq chipseq BWA, MACS2, deepTools
ATAC-seq atacseq Bowtie2, MACS2, ataqv
Single-cell single-cell CellRanger, STARsolo, Seurat
Metagenomics metagenomics Kraken2, MetaPhlAn4, MEGAHIT
Amplicon / 16S amplicon DADA2, QIIME2, PICRUSt2

Playbook YAML Schema

Every playbook follows this schema:

domain: "rnaseq"               # Unique machine-readable identifier
name: "Bulk RNA Sequencing"    # Human-readable display name

recommended_tools:             # nf-core module names Codaris will install
  - fastqc
  - trimgalore
  - star
  - salmon
  - subread/featurecounts
  - multiqc

best_practices:                # Rules injected verbatim into the agent context
  - "Use TrimGalore for adapter trimming before alignment."
  - "For transcript-level quantification, use Salmon."

Fields must be exact nf-core module names (lowercase, slash-separated for subcommands) so the agent can call nf-core modules install <name> directly.

How to Trigger a Specific Playbook

Codaris selects the playbook automatically, but you can force one explicitly:

codaris > Build a WGS somatic variant calling pipeline for tumour-normal pairs

The phrase "WGS somatic" and "tumour-normal" is enough to resolve wgs-somatic. If your experiment is ambiguous, the agent will ask one clarifying question before proceeding.

Creating Your Own Playbook

To add a custom domain (e.g., long-read sequencing, spatial transcriptomics):

  1. Copy any existing playbook YAML as a template
  2. Save it to src/codaris/knowledge/playbooks/<your-domain>.yaml
  3. Follow the schema above exactly — domain must be unique and lowercase
  4. Restart the Codaris session; your playbook is picked up automatically

Draft playbooks

Save work-in-progress playbooks to src/codaris/knowledge/playbooks/drafts/ while you're testing. They won't be loaded by the agent until you move them to the main playbooks/ directory.