Your First Pipeline¶

This walkthrough builds a bulk RNA-seq pipeline from one sentence, in the web studio first and then with the equivalent commands.

1. Open a chat¶

Start the studio (container or source checkout), open http://localhost:3000, and confirm that a provider key is saved under Customizations. Create a project folder for the pipeline, or point the chat at an existing folder; the agent writes only inside the folders it has been given.

2. Describe the goal¶

Type the request as you would say it. The slash command is a shortcut; a plain sentence reaches the same place.

/build Bulk RNA-seq for human paired-end FASTQ files: FastQC, adapter trimming
with Trim Galore, STAR alignment against GRCh38, Salmon quantification, and MultiQC.

Codaris reads the request, asks the decision model what kind of turn it is, and starts planning.

3. Answer the plan questions¶

The planner resolves the assay, the module chain, and the reference assets, then asks in stages. Each stage appears as a question card with a default already filled in, and a stage opens once the earlier ones have no blocking question left:

The plan and the answers are saved in the project under .codaris/pipelines/<name>/ (plan.json and answers.json), so a later turn or codaris build reads the same decisions. The plan itself (the modules, the subworkflows, the assets, and the test-data choice) renders in the thread with a Mermaid DAG of the module chain.

4. What the build does¶

The build runs as a graph of nodes, and each one streams its progress into the thread:

1. Scaffold. nf-core pipelines create lays down the nf-core template with the pipeline name and description. The template's own switches remove FastQC or MultiQC when the Defaults stage dropped them.
2. Install. Each planned module is installed from nf-core/modules into modules/nf-core/; a matching nf-core subworkflow is installed when the Structure stage chose one.
3. Stitch. The compiler writes workflows/<name>.nf from the installed modules' real input: declarations, conf/modules.config with the curated ext.args, conf/test_codaris.config with self-contained fixtures, and the sample sheet. Reference assets become params with the production default from the References stage, and an asset the pipeline can build itself (a STAR index) becomes params.star_index ? Channel.value(file(params.star_index)) : STAR_GENOMEGENERATE(...).
4. Symbol repair. Generated code is reconciled against the installed modules: emit names, call arity, and include paths.
5. Compile gate. nextflow run . -profile test_codaris,docker -preview parses and resolves the whole workflow without running a task. The gate then confirms that main.nf includes and calls the pipeline workflow, that the workflow calls at least one process, and that nothing included is left dangling. A failure goes to the fix node, which adds a missing include deterministically when the error names one and asks the build model for a corrected file otherwise; a proposal that empties or guts a file is refused.
6. Lint. nf-core pipelines lint runs on the tree; failures take one more pass through the fix node within the budget (CODARIS_FIX_BUDGET, default 2).
7. Report. The thread shows whether the pipeline compiles and lints, the planned steps that are not wired (when a module's inputs could not be read), the parameters the pipeline needs, and the next step. .codaris/provenance.json records a sha256 of every generated file, computed after the last write.

5. Inspect the result¶

pipelines/rnaseq/
├── main.nf                       # the template entry point, which calls RNASEQ
├── nextflow.config
├── nextflow_schema.json
├── workflows/rnaseq.nf           # the compiled workflow
├── subworkflows/local/           # local subworkflows from the Structure stage
├── modules/nf-core/              # installed nf-core modules
├── conf/
│   ├── base.config               # the template's resource labels (resourceLimits)
│   ├── modules.config            # ext.args per process
│   ├── test.config
│   └── test_codaris.config       # self-contained fixtures, 2 CPUs, 4 GB, 1 h
├── assets/
│   ├── schema_input.json
│   ├── samplesheet.csv
│   └── test_fixtures/
└── .codaris/
    └── provenance.json           # sha256 per generated file

Preview the resolved workflow without running anything:

cd pipelines/rnaseq
nextflow run . -profile test_codaris,docker -preview

Run the test profile. In the studio, ask for it ("run the test profile"); the agent checks readiness first and resumes after resource and out-of-memory failures. From a shell:

nextflow run . -profile test_codaris,docker -stub-run    # seconds, no containers
nextflow run . -profile test_codaris,docker              # the real tools on the fixtures

Verify that the tree is the one the build reported:

cd /path/to/codaris/backend
python -m app.engine.security_scanner verify /path/to/pipelines/rnaseq

6. Score the pipeline¶

In the chat, /audit runs the read-only compliance scorecard on the active pipeline (/review --compliance is the same, /review --quick the quick pass). A bare /review is the faster structural review: it checks the wiring of channels, params, containers and configs and gives no score. Which one runs depends only on what you type, so the same message always runs the same one. From a shell:

codaris review ./pipelines/rnaseq            # the calibrated core profile
codaris review ./pipelines/rnaseq --quick    # deterministic checkers and lint only, no model

The command prints the Markdown report, then one line such as Review — overall 91.4% (grade A), and writes only docs/compliance-report.json inside the pipeline (a review changes nothing else). The score is the pipeline's conformance to the 249-rule nf-core ruleset; codaris remediate applies the rollback-safe fixes for the failed rules and reports what changed.

7. The same steps from a shell¶

codaris plan "Bulk RNA-seq for human paired-end FASTQ with Trim Galore, STAR, Salmon, and MultiQC" \
  --interactive --out rnaseq_plan.json
codaris build rnaseq_plan.json --output-dir ./pipelines
codaris test ./pipelines/rnaseq
codaris review ./pipelines/rnaseq

plan --interactive asks the same staged questions on the terminal; without it the planner writes rnaseq_plan.questions.json beside the plan for you to edit, and build refuses to start while a blocking question is open unless --use-defaults is passed.