Amplicon ASV Codex workflow kit

A reusable Chinese runbook for using Codex to process amplicon FASTQ data into ASV outputs. Last verified: 2026-07-03.

---

Overview

This folder is a portable workflow bundle. Give it to a user who has raw or trimmed amplicon FASTQ files and wants Codex to run an ASV pipeline with QIIME 2 and DADA2.

The intended handoff is:

1. The user fills 01_user_questionnaire.md.
2. The user places FASTQ files in a project folder.
3. The user sends Codex one of the prompts in 02_how_to_ask_codex.md.
4. Codex follows 03_agent_runbook_fastq_to_asv.md.
5. Codex exports feature-table.tsv, representative ASV sequences, denoising stats, and a short run report.

flowchart TB
    accTitle: Amplicon ASV Codex Flow
    accDescr: The workflow starts with a completed questionnaire and FASTQ files, then Codex checks the environment, imports reads, runs DADA2, and exports ASV deliverables.

    questionnaire([Completed questionnaire]) --> inspect[Inspect FASTQ files]
    inspect --> environment{Environment ready?}
    environment -->|No| install[Install WSL, Miniconda, QIIME 2]
    environment -->|Yes| import_reads[Import into QIIME 2]
    install --> import_reads
    import_reads --> quality[Review demux quality]
    quality --> dada2[Run DADA2 ASV denoising]
    dada2 --> verify{Outputs valid?}
    verify -->|No| adjust[Adjust trim or truncation]
    adjust --> dada2
    verify -->|Yes| export[Export ASV table and sequences]
    export --> report([Run report])

Loading

Folder contents

File	Purpose
00_dependencies_and_skills.md	What software, databases, and Codex skills are needed
01_user_questionnaire.md	Questionnaire the data owner fills before running
02_how_to_ask_codex.md	Copy-paste prompt templates for Codex
03_agent_runbook_fastq_to_asv.md	Operational runbook for Codex to execute the whole ASV pipeline
04_qc_decision_guide.md	How to choose trim, truncation, and rerun parameters
05_outputs_and_handoff.md	What files should exist at the end and how to interpret them
templates/questionnaire_template.yml	Machine-readable questionnaire template
templates/sample_metadata_template.tsv	Sample metadata starter table
scripts/inspect_fastq.py	FASTQ inventory, read count, length, and quality sampler
scripts/make_qiime_manifest.py	Generates QIIME 2 manifest files for single-end or paired-end FASTQ
sources/official_links.md	Source links checked while preparing this kit
validation/	Test outputs generated from the current local 16S example data

Scope

This bundle is for amplicon ASV workflows, especially:

• 16S, ITS, 18S, or other marker-gene FASTQ data
• Demultiplexed single-end or paired-end reads
• Already joined reads treated as single-end
• ASV generation with QIIME 2 dada2
• Optional taxonomy assignment after ASV generation

It is not designed for shotgun metagenomics, metatranscriptomics, MAG reconstruction, host genome alignment, or qPCR analysis.

Minimum user inputs

The workflow can start only after these are known:

Required item	Why it matters
FASTQ folder path	Codex must find and import the raw data
Marker type, such as 16S or ITS	Determines database and interpretation
Single-end, paired-end, or joined reads	Determines QIIME 2 import and DADA2 command
Whether primers/adapters are still present	Determines whether cutadapt is needed
Primer sequences if present	Required for correct primer trimming
Sample naming and metadata	Needed for manifest and downstream grouping
Desired final deliverables	Determines whether taxonomy, tree, and diversity steps are included

Recommended default

For most modern demultiplexed amplicon data, use:

• QIIME 2 amplicon distribution
• DADA2 ASV workflow
• PHRED 33 manifest import
• Taxonomy with SILVA or Greengenes2 for 16S
• UNITE-derived references for ITS

External installation and database links are listed in 00_dependencies_and_skills.md.