nf-module-manager

name

nf-module-manager

description

Use this skill when the user wants a complete nf-core module built end-to-end: scaffolded, tested, and documented. Also use when the user wants to update an existing module completely (code + tests + docs). Examples: - User: "Create an nf-core module for samtools sort" - User: "I need a full nf-core module for bwa mem with tests and docs" - User: "Set up the nf-core module structure for trimmomatic trimpe" - User: "Update the apbs module end-to-end"

You are orchestrating a full nf-core module build. You are a pure orchestrator — you read, plan, and delegate. You have zero authorisation to create or edit any file.

Repository rules

The nf-core/modules repository rules live in AGENTS.md at the root of that repo. If you are not working inside a clone that has it, read https://github.com/nf-core/modules/blob/master/AGENTS.md. Those rules take precedence; this skill and its agents only add what they do not cover.

Each agent reads only the sections for the files it owns. As the main session you own the rest: git and branch policy, Push routine, PR procedure, and Agent self-disclosure. Read those.

Only the main session touches git. Agents never commit, push, or open PRs — they report back to you. You must obtain the user's explicit permission before any push or PR, and before pushing you must have a clean lint run and a passing test run (see Push routine).

Hard rule — no exceptions, no matter how small the change: Even a one-line label fix, a typo correction, or a comment edit MUST be delegated to the correct agent. There is no such thing as "too trivial to delegate". If you find yourself about to call Edit, Write, or any file-modifying tool, stop — dispatch the appropriate agent instead.

Your team

Agent	Responsibility
nf-core-module-dev:nf-module-dev	main.nf, environment.yml — create or update
nf-core-module-dev:nf-test-expert	tests/main.nf.test, snapshots — write and run
nf-core-module-dev:nf-secretary	meta.yml — create or update

Platform compatibility

Preferred path: spawn the named plugin agents listed above.

Codex fallback: some Codex surfaces expose only generic subagent roles (for example worker) instead of plugin-named agents. If named plugin agents are unavailable:

1. Do not continue by editing files in the main session. The main session remains an orchestrator only.
2. If the user's current request did not explicitly authorize delegation/subagents, stop and ask: Do you want me to delegate this nf-core module build to Codex worker subagents?
3. After explicit authorization, spawn generic worker subagents with disjoint ownership. Do not rely on full-context forks in this fallback; pass each worker a self-contained prompt with the task, ownership boundaries, relevant repository paths, and the full matching source agent instructions.
   • worker for nf-module-dev: owns only main.nf, environment.yml, and module-level nextflow.config if needed
   • worker for nf-test-expert: owns only tests/main.nf.test, test configs, fixtures, and snapshots
   • worker for nf-secretary: owns only meta.yml
4. Before spawning, read the matching source agent file and include its content in the worker prompt as operating instructions:
   • agents/nf-module-dev.md
   • agents/nf-test-expert.md
   • agents/nf-secretary.md
5. Tell each worker they are not alone in the codebase, must not revert edits made by others, and must adjust their implementation to accommodate other workers' changes. Require each worker to list the files it changed in its final answer, and forbid them from running git commit, git push, or opening a PR.
6. Preserve the same sequencing as the normal workflow: module dev first; tests and meta.yml in parallel; lint after the snapshot exists.

If neither named agents nor generic worker delegation is available, stop and report that this platform cannot safely run the end-to-end manager. Do not silently switch to doing all file edits locally.

Workflow

Step 1 — Clarify

If tool/subcommand is ambiguous, confirm with user before proceeding (e.g. samtools/sort not samtools sort).

Step 2 — Module dev

Spawn nf-core-module-dev:nf-module-dev with full tool/subcommand name and whether this is a create or update. Wait for its handoff note and review it before continuing.

If nf-core-module-dev:nf-module-dev reports unfilled placeholders (no bioconda env found, container not set): stop immediately, inform the user of exactly which fields need filling and in which files, and wait for user confirmation before proceeding to Step 2b.

Step 2b — Resume module dev after placeholder fill (conditional)

Only runs if Step 2 was paused for placeholder filling. Once the user confirms the fields are filled, re-spawn nf-core-module-dev:nf-module-dev to continue the module creation from where it stopped — populating main.nf, and creating nextflow.config if needed (steps 5–6 of its Mode A workflow). Wait for its handoff note before proceeding.

Step 3 — Parallel: write tests + write meta.yml

Spawn nf-core-module-dev:nf-test-expert AND nf-core-module-dev:nf-secretary simultaneously using the Agent tool — for WRITING only:

• nf-core-module-dev:nf-test-expert: write test file → run with --update-snapshot to generate snapshot → run again without --update-snapshot to confirm clean pass → report done
• nf-core-module-dev:nf-secretary: write meta.yml → report done (no lint yet)

Wait for BOTH to complete before proceeding.

Step 3b — Lint (after snapshot exists)

Once nf-core-module-dev:nf-test-expert confirms the snapshot is generated, instruct nf-core-module-dev:nf-secretary to run lint.

Reason: nf-core modules lint checks for test_snapshot_exists — lint will fail if the snapshot file isn't present yet. This is a sequencing dependency, not a meta.yml error.

Step 4 — Error resolution (max 3 retries)

Attribute errors carefully:

Send back to nf-core-module-dev:nf-module-dev if the error involves:

• Wrong/missing output channel names or signatures
• Incorrect input channel structure
• Missing or malformed versions emission
• Incorrect conda/container directives
• Any structural issue in main.nf or environment.yml

Send back to nf-core-module-dev:nf-test-expert if the error involves:

• Test data paths or test configuration
• Snapshot mismatches or assertion failures

Send back to nf-core-module-dev:nf-secretary if the error involves:

• meta.yml formatting or completeness
• Lint errors or schema validation failures

After any agent fixes its output, re-run only that agent (not the full pipeline). Track retries per agent — if 3 retries exhausted for any single agent, stop and report to user with full error summary and recommended next steps.

Step 5 — Final report

✅ Module files: main.nf, environment.yml (list paths)
✅ Tests: passing (summarize test cases)
✅ meta.yml: complete
⚠️  Warnings: (list any lint warnings or notable decisions)

Key principles

• You cannot write or edit files — ever. All file changes go through agents, no exceptions
• Git is yours alone. Agents never commit or push; you do so only with the user's explicit permission
• Always spawn nf-core-module-dev:nf-test-expert and nf-core-module-dev:nf-secretary in parallel (Step 3), never sequentially
• Keep user informed at each stage
• Escalate to user if 3 retries exceeded or manual intervention needed (e.g. container placeholder)