diff --git a/adr/20251114-module-system.md b/adr/20251114-module-system.md
new file mode 100644
index 0000000000..01b7c38bec
--- /dev/null
+++ b/adr/20251114-module-system.md
@@ -0,0 +1,1184 @@
+# Module System for Nextflow
+
+- Authors: Paolo Di Tommaso
+- Status: draft
+- Date: 2025-01-06
+- Tags: modules, dsl, registry, versioning, architecture
+- Version: 2.4
+
+## Updates
+
+### Version 2.4 (2026-01-15)
+- **Removed transitive dependency resolution**: Module dependencies are explicit only; no automatic transitive resolution
+- **Removed `freeze` command**: No longer needed without transitive dependency management
+- **Simplified model**: Each module explicitly declares its dependencies in `nextflow.config`
+
+### Version 2.3 (2026-01-15)
+- **Resolution Rules table**: Added clear table specifying behavior for each combination of local state and declared version
+- **Local modification protection**: Locally modified modules (checksum mismatch) are NOT overridden unless `-force` flag is used
+- **Simplified storage model**: Single version per module locally (`modules/@scope/name/` without version in path)
+- **`.checksum` file**: Registry checksum cached locally for fast integrity verification without network calls
+
+### Version 2.2 (2025-01-06)
+- **Structured tool arguments**: Added `args` property to `tools` section for type-safe argument configuration
+- **New implicit variables**: `tools.<toolname>.args.<argname>` returns formatted flag+value; `tools.<toolname>.args` returns all args concatenated
+- **Deprecation**: All `ext.*` custom directives (e.g., `ext.args`, `ext.args2`, `ext.args3`, `ext.prefix`, `ext.suffix`) deprecated in favor of structured tool arguments
+
+### Version 2.1 (2024-12-11)
+- **Unified dependencies**: Consolidated `components`, `dependencies`, and `requires` into single `requires` field
+- **New sub-properties**: `requires.modules` and `requires.workflows` for declaring module dependencies
+- **Unified version syntax**: `[scope/]name[@constraint]` format across plugins, modules, and workflows
+- **Deprecation**: `components` field deprecated (use `requires.modules` instead)
+
+## Context and Problem Statement
+
+Nextflow supports local script inclusion via `include` directive but lacks standardized mechanisms for package management, versioning, and distribution of reusable process definitions. This limits code reuse and reproducibility across the ecosystem.
+
+Discussion/request goes back to at least 2019, see GitHub issues [#1376](https://github.com/nextflow-io/nextflow/issues/1376), [#1463](https://github.com/nextflow-io/nextflow/issues/1463) and [#4122](https://github.com/nextflow-io/nextflow/issues/4112).
+
+## Decision
+
+Implement a module system with four core capabilities:
+
+1. **Remote module inclusion** via registry
+2. **Semantic versioning** with dependency resolution
+3. **Unified Nextflow Registry** (rebrand existing Nextflow registry)
+4. **First-class CLI support** (install, publish, search, list, remove, run)
+
+## Core Capabilities
+
+### 1. Remote Module Inclusion
+
+**DSL Syntax**:
+```groovy
+// Import from registry (scoped module name, detected by @scope prefix)
+include { BWA_ALIGN } from '@nf-core/bwa-align'
+
+// Existing file-based includes remain supported
+include { MY_PROCESS } from './modules/my-process.nf'
+```
+
+**Module Naming**: NPM-style scoped packages `@scope/name` (e.g., `@nf-core/salmon`, `@myorg/custom`). Unscoped names (eg. local paths) supported for legacy compatibility. No nested paths with the module are allowed - each module must have a `main.nf` as the entry point.
+
+**Version Resolution**: Module versions pinned in `nextflow.config`. If not specified, use the latest available locally in `modules/` directory, or downloaded and cached in the `modules/` directory.
+
+**Resolution Order**:
+1. Check `nextflow.config` for declared version
+2. Check local `modules/@scope/name/` exists
+3. Verify integrity against `.checksum` file
+4. Apply resolution rules (see below)
+
+**Resolution Rules**:
+
+| Local State | Declared Version | Action |
+|-------------|------------------|--------|
+| Missing | Any | Download declared version (or latest if not declared) |
+| Exists, checksum valid | Same as declared | Use local module |
+| Exists, checksum valid | Different from declared | **Replace** local with declared version |
+| Exists, checksum mismatch | Same as declared | **Warn**: module was locally modified, do not override |
+| Exists, checksum mismatch | Different from declared | **Warn**: locally modified, will NOT replace unless `-force` is used |
+
+**Key Behaviors**:
+- **Version change**: When the declared version differs from the installed version (and local is unmodified), the local module is automatically replaced with the declared version
+- **Local modification**: When the local module content was manually changed (checksum mismatch with `.checksum`), Nextflow warns and does NOT override to prevent accidental loss of local changes
+- **Force flag**: Use `-force` with `nextflow module install` to override locally modified modules
+
+**Resolution Timing**: Modules resolved at workflow parse time (after plugin resolution at startup).
+
+**Local Storage**: Downloaded modules stored in `modules/@scope/name/` directory in project root (not global cache). Each module must contain a `main.nf` file as the required entry point. It is intended that module source code will be committed to the pipeline git repository.
+
+### 2. Semantic Versioning and Configuration
+
+**Version Format**: MAJOR.MINOR.PATCH
+- **MAJOR**: Breaking changes to process signatures, inputs, or outputs
+- **MINOR**: New processes, backward-compatible enhancements
+- **PATCH**: Bug fixes, documentation updates
+
+**Workflow Configuration** (`nextflow.config`):
+```groovy
+// Module versions (exact versions only, no ranges)
+modules {
+    '@nf-core/salmon' = '1.1.0'
+    '@nf-core/bwa-align' = '1.2.0'
+}
+
+// Registry configuration (separate block)
+registry {
+    url = 'https://registry.nextflow.io'     // Default registry
+
+    // allow the use of multiple registry url for resolving module
+    // across custom registries, e.g.
+    // url = [ 'https://custom.registry.com', 'https://registry.nextflow.io' ]
+
+    auth {
+        'registry.nextflow.io' = '${NXF_REGISTRY_TOKEN}'
+        'npm.myorg.com' = '${MYORG_TOKEN}'
+    }
+}
+```
+
+**Module Manifest** (`meta.yaml`):
+```yaml
+name: nf-core/bwa-align
+version: 1.2.4                    # This module's version
+
+requires:
+  nextflow: ">=24.04.0"
+  modules:                        # Required modules (version constraints)
+    - nf-core/samtools/view@>=1.0.0,<2.0.0
+    - nf-core/samtools/sort@>=2.1.0,<2.2.0
+```
+
+**Version Constraints** (unified `name@constraint` syntax):
+- `name`: Any version (latest)
+- `name@1.2.3`: Exact version
+- `name@>=1.2.3`: Greater or equal
+- `name@>=1.2.3,<2.0.0`: Range (comma-separated)
+
+**Version Notation Consistency**:
+
+Modules use the same version constraint syntax already supported by both `nextflowVersion` and plugins:
+
+| Notation | Meaning | nextflowVersion | Plugins | Modules |
+| :---- | :---- | :---- | :---- | :---- |
+| 1.2.3 | Exact version | ✓ | ✓ | ✓ |
+| >=1.2.3 | Greater or equal | ✓ | ✓ | ✓ |
+| <=1.2.3 | Less or equal | ✓ | ✓ | ✓ |
+| >1.2.3 | Greater than | ✓ | ✓ | ✓ |
+| <1.2.3 | Less than | ✓ | ✓ | ✓ |
+| >=1.2, <2.0 | Range (comma) | ✓ | ✓ | ✓ |
+| !=1.2.3 | Not equal | ✓ | - | - |
+| 1.2+ | >=1.2.x <2.0 | ✓ | - | - |
+| 1.2.+ | >=1.2.0 <1.3.0 | ✓ | - | - |
+| ~1.2.3 | >=1.2.3 <1.3.0 | - | ✓ | - |
+
+Using comparison operators (`>=`, `<`) with comma-separated ranges provides the same expressive power as
+npm-style `^` and `~` notation while maintaining consistency with existing Nextflow version constraint syntax.
+This avoids introducing new notation that would require additional parser support.
+
+**Dependency Resolution**:
+- Workflow's `nextflow.config` specifies exact versions for dependencies
+- Module dependencies declared in `meta.yaml` using version constraints
+
+### 3. Unified Nextflow Registry
+
+**Architecture Decision**: Extend existing Nextflow registry at `registry.nextflow.io` to host both plugins and modules.
+
+**Current Plugin API** (reference: https://registry.nextflow.io/openapi/):
+```
+GET  /api/v1/plugins                                  # List/search plugins
+GET  /api/v1/plugins/{pluginId}                       # Get plugin + all releases
+GET  /api/v1/plugins/{pluginId}/{version}             # Get specific release
+GET  /api/v1/plugins/{pluginId}/{version}/download/{fileName}  # Download artifact
+POST /api/v1/plugins/release                          # Create draft release
+POST /api/v1/plugins/release/{releaseId}/upload       # Upload artifact
+```
+
+**Module API** (reference: https://github.com/seqeralabs/plugin-registry/pull/266):
+```
+GET  /api/modules?query=<text>               # Search modules (semantic search)
+GET  /api/modules/{name}                     # Get module + latest release
+GET  /api/modules/{name}/releases            # List all releases
+GET  /api/modules/{name}/{version}           # Get specific release
+GET  /api/modules/{name}/{version}/download  # Download module bundle
+POST /api/modules/{name}                     # Publish module version (authenticated)
+```
+
+Note: The `{name}` parameter includes the namespace prefix (e.g., "nf-core/fastqc").
+
+**Registry URL**: `registry.nextflow.io`
+
+**Artifact Types**:
+- **Plugins**: JAR files with JSON metadata, resolved at startup
+- **Modules**: Source archives (.nf + meta.yaml), resolved at parse time
+
+**Benefits**:
+- Reuses existing infrastructure (HTTP service, S3 storage, authentication)
+- Consistent API patterns for both artifact types
+- Operational simplicity (one service vs. two)
+- Internal module API already partially implemented
+
+### 4. First-Class CLI Support
+
+**Commands**:
+```bash
+nextflow module run scope/name              # Run a module directly without a wrapper script
+nextflow module search <query>              # Search registry
+nextflow module install [scope/name]        # Install all from config, or specific module
+nextflow module list                        # Show installed vs configured
+nextflow module remove scope/name           # Remove from config + local cache
+nextflow module publish scope/name          # Publish to registry (requires api key)
+```
+
+#### `nextflow module run scope/name`
+
+Run a module directly without requiring a wrapper workflow script. This command enables standalone execution of any module by automatically mapping command-line arguments to the module's process inputs. If the module is not available locally, it is automatically installed before execution.
+
+**Arguments**:
+- `scope/name`: Module identifier to run (required)
+
+**Options**:
+- `-version <ver>`: Run a specific version (default: latest or configured version)
+- `--<input_name> <value>`: Map value to the corresponding module process input channel
+- `--tools:<toolname>:<argname> <value>`: Configure tool-specific arguments (validated against meta.yaml schema)
+- All standard `nextflow run` options (e.g., `-profile`, `-work-dir`, `-resume`, etc.)
+
+**Behavior**:
+1. Checks if module is installed locally; if not, downloads from registry
+2. Parses the module's `main.nf` to identify the main process and its input declarations
+3. Validates command-line arguments against the process input schema
+4. Validates tool arguments against the `tools.*.args` schema in `meta.yaml`
+5. Generates an implicit workflow that wires CLI arguments to process inputs
+6. Executes the workflow using standard Nextflow runtime
+
+**Input Mapping**:
+- Named arguments (`--reads`, `--reference`) are mapped to corresponding process inputs
+- File paths are automatically converted to file channels
+- Multiple values can be provided for inputs expecting collections
+- Required inputs without defaults must be provided; optional inputs use declared defaults
+
+**Tool Arguments**:
+- Arguments prefixed with `--tools:` configure tool-specific parameters
+- Format: `--tools:<toolname>:<argname> <value>` (e.g., `--tools:bwa:K 100000000`)
+- Boolean flags can be specified without value (e.g., `--tools:bwa:Y`)
+- Arguments are validated against the tool's `args` schema in `meta.yaml`
+- Invalid argument names or values that fail type/enum validation produce errors
+
+**Example**:
+```bash
+# Run BWA alignment module with input files
+nextflow module run nf-core/bwa-align \
+    --reads 'samples/*_{1,2}.fastq.gz' \
+    --reference genome.fa
+
+# Run a specific version with Nextflow options
+nextflow module run nf-core/fastqc -version 1.0.0 \
+    --input 'data/*.fastq.gz' \
+    -profile docker \
+    -resume
+
+# Run with work directory and output specification
+nextflow module run nf-core/salmon \
+    --reads reads.fq \
+    --index salmon_index \
+    -work-dir /tmp/work \
+    --outdir results/
+
+# Run with tool-specific arguments
+nextflow module run nf-core/bwa-align \
+    --reads 'samples/*_{1,2}.fastq.gz' \
+    --reference genome.fa \
+    --tools:bwa:K 100000000 \
+    --tools:bwa:Y \
+    --tools:samtools:output_fmt cram
+```
+
+---
+
+#### `nextflow module search <query>`
+
+Search the Nextflow registry for available modules matching the specified query. The search operates against module names, descriptions, tags, and author information. Results are displayed with module name, latest version, description, and download statistics.
+
+**Arguments**:
+- `<query>`: Search term (required) - matches against module metadata
+
+**Options**:
+- `-limit <n>`: Maximum number of results to return (default: 10)
+- `-json`: Output results in JSON format for programmatic use
+
+**Example**:
+```bash
+nextflow module search bwa
+nextflow module search "alignment" -limit 50
+```
+
+---
+
+#### `nextflow module install [scope/name]`
+
+Download and install modules to the local `modules/` directory. When called without arguments, installs all modules declared in `nextflow.config`. When a specific module is provided, installs that module and adds it to the configuration.
+
+**Arguments**:
+- `[scope/name]`: Optional module identifier. If omitted, installs all modules from config
+
+**Options**:
+- `-version <ver>`: Install a specific version (default: latest)
+- `-force`: Re-download even if already installed locally
+
+**Behavior**:
+1. If `-version` not specified, resolves the module version from `nextflow.config` or queries registry for latest
+2. Checks if local module exists and verifies integrity against `.checksum` file
+3. If local module is unmodified and version differs: replaces with requested version
+4. If local module was modified (checksum mismatch): warns and aborts unless `-force` is used
+5. Downloads the module archive from the registry
+6. Extracts to `modules/@scope/name/` directory
+7. Stores `.checksum` file from registry's X-Checksum response header
+8. Updates `nextflow.config` if installing a new module not already configured
+
+**Example**:
+```bash
+nextflow module install                      # Install all from config
+nextflow module install nf-core/bwa-align    # Install specific module (latest)
+nextflow module install nf-core/salmon -version 1.2.0
+```
+
+---
+
+#### `nextflow module list`
+
+Display the status of all modules, comparing what is configured in `nextflow.config` against what is actually installed in the `modules/` directory.
+
+**Options**:
+- `-json`: Output in JSON format
+- `-outdated`: Only show modules with available updates
+
+**Output columns**:
+- Module name (`@scope/name`)
+- Configured version (from `nextflow.config`)
+- Installed version (from `modules/` directory)
+- Latest available version (from registry)
+- Status indicator (up-to-date, outdated, missing, not configured)
+
+**Example**:
+```bash
+nextflow module list
+nextflow module list -outdated
+```
+
+---
+
+#### `nextflow module remove scope/name`
+
+Remove a module from both the local `modules/` directory and the `nextflow.config` configuration.
+
+**Arguments**:
+- `scope/name`: Module identifier to remove (required)
+
+**Options**:
+- `-keep-config`: Remove local files but keep the entry in `nextflow.config`
+- `-keep-files`: Remove from config but keep local files
+
+**Behavior**:
+1. Removes the module directory from `modules/@scope/name/`
+2. Removes the module entry from the `modules {}` block in `nextflow.config`
+3. Warns if the module is still referenced in workflow files
+
+**Example**:
+```bash
+nextflow module remove nf-core/bwa-align
+nextflow module remove myorg/custom -keep-files
+```
+
+---
+
+#### `nextflow module publish scope/name`
+
+Publish a module to the Nextflow registry, making it available for others to install. Requires authentication via API key and appropriate permissions for the target scope.
+
+**Arguments**:
+- `scope/name`: Module identifier to publish (required)
+
+**Options**:
+- `-registry <url>`: Target registry URL (default: `registry.nextflow.io`)
+- `-tag <tag>`: Additional tags for discoverability
+- `-dry-run`: Validate without publishing
+
+**Behavior**:
+1. Validates `meta.yaml` schema and required fields (name, version, description)
+2. Verifies `main.nf` exists and is valid Nextflow syntax
+3. Checks that `README.md` documentation is present
+4. Authenticates with registry using configured credentials
+5. Creates a release draft and uploads the module archive
+6. Publishes the release, making it available for installation
+
+**Requirements**:
+- Valid `meta.yaml` with name, version, and description
+- `main.nf` entry point file
+- `README.md` documentation
+- Authentication token configured in `registry.auth` or `NXF_REGISTRY_TOKEN`
+- Write permission for the target scope
+
+**Example**:
+```bash
+nextflow module publish myorg/my-process
+nextflow module publish myorg/my-process -dry-run
+```
+
+**General Notes**:
+- All commands respect the `registry.url` configuration for custom registries
+- Modules are automatically downloaded on `nextflow run` if missing but configured
+
+## Module Structure
+
+**Directory Layout**:
+Everything within the module directory should be uploaded. Module bundle should not exceed 1MB (uncompressed). Typically this is expected to look something like this:
+```
+my-module/
+├── main.nf      # Required: entry point for module
+├── meta.yaml    # Optional: Module spec (metadata, dependencies, I/O specs)
+├── README.md    # Required: Module description
+└── tests/       # Optional test workflows
+```
+
+**Module Spec extension** (`meta.yaml`):
+```yaml
+name: nf-core/bwa-align
+version: 1.2.4              # This module's version
+description: Align reads using BWA-MEM
+authors:
+  - nf-core community
+license: MIT
+
+requires:
+  nextflow: ">=24.04.0"
+  plugins:
+    - nf-amazon@2.0.0
+  modules:
+    - nf-core/samtools/view@>=1.0.0,<2.0.0
+    - nf-core/samtools/sort@>=2.1.0,<2.2.0
+```
+
+**Local Storage Structure**:
+```
+project-root/
+├── nextflow.config
+├── main.nf
+└── modules/                        # Local module cache
+    ├── @nf-core/
+    │   ├── bwa-align/
+    │   │   ├── .checksum           # Cached registry checksum
+    │   │   ├── meta.yaml
+    │   │   └── main.nf             # Required entry point
+    │   └── samtools/view/
+    │       ├── .checksum
+    │       ├── meta.yaml
+    │       └── main.nf             # Required entry point
+    └── @myorg/
+        └── custom-process/
+            ├── .checksum
+            ├── meta.yaml
+            └── main.nf             # Required entry point
+```
+
+**Module Integrity Verification**:
+- On install: `.checksum` file created from registry's X-Checksum response header
+- On run: Local module checksum compared against `.checksum` file
+- If match: Proceed without network call
+- If mismatch: Report warning (module may have been locally modified)
+
+## Implementation Strategy
+
+**Phase 1**: Module manifest schema, local module loading, validation tools
+
+**Phase 2**: Extend Nextflow registry for modules, implement caching, add `install` and `search` commands
+
+**Phase 3**: Extend DSL parser for `from module` syntax, implement dependency resolution from meta.yaml
+
+**Phase 4**: Implement `publish` command with authentication and `run` command
+
+**Phase 5**: Advanced features (search UI, language server integration, ontology validation)
+
+## Technical Details
+
+**Dependency Resolution Flow**:
+1. Parse `include` statements → extract module names (e.g., `@nf-core/bwa-align`)
+2. For each module:
+   a. Check `nextflow.config` modules section for declared version
+   b. Check local `modules/@scope/name/` exists
+   c. Verify local module integrity against `.checksum` file
+   d. Apply resolution rules:
+      - Missing → download declared version from registry
+      - Exists, checksum valid, same version → use local
+      - Exists, checksum valid, different version → replace with declared version
+      - Exists, checksum mismatch → warn and do NOT override (local changes detected)
+3. On download: store module to `modules/@scope/name/` with `.checksum` file
+4. Parse module's `main.nf` file → make processes available
+
+**Security**:
+- SHA-256 checksum verification on download (stored in `.checksum` file)
+- Integrity verification on run (local checksum vs `.checksum` file)
+- Authentication required for publishing
+- Support for private registries
+
+**Integration with Plugin System**:
+- Modules can declare plugin dependencies in meta.yaml
+- Both plugins and modules query same registry
+- Single authentication system
+- Separate cache locations: `$NXF_HOME/plugins/` (global) vs `modules/` (per-project)
+
+## Tool Arguments Configuration
+
+The module system introduces a structured approach to tool argument configuration, replacing the legacy `ext.args` pattern with type-safe, documented argument specifications.
+
+### Current Pattern (Deprecated)
+
+The traditional nf-core pattern uses `ext.args` strings in config files:
+
+```groovy
+// Config file
+withName: 'BWA_MEM' {
+    ext.args = "-K 100000000 -Y -B 3 -R ${meta.read_group}"
+    ext.args2 = "--output-fmt cram"
+}
+
+// Module script
+def args = task.ext.args ?: ''
+def args2 = task.ext.args2 ?: ''
+bwa mem $args -t $task.cpus $index $reads | samtools sort $args2 -o out.bam -
+```
+
+**Limitations:**
+- No documentation of available arguments
+- No validation or type checking
+- Unclear which `ext.argsN` maps to which tool
+- No IDE autocompletion support
+
+### New Pattern: Structured Tool Arguments
+
+Modules declare available arguments in `meta.yaml` under each tool's `args` property:
+
+```yaml
+tools:
+  - bwa:
+      description: BWA aligner
+      homepage: http://bio-bwa.sourceforge.net/
+      args:
+        K:
+          flag: "-K"
+          type: integer
+          description: "Process INT input bases in each batch"
+        Y:
+          flag: "-Y"
+          type: boolean
+          description: "Use soft clipping for supplementary alignments"
+
+  - samtools:
+      description: SAMtools
+      homepage: http://www.htslib.org/
+      args:
+        output_fmt:
+          flag: "--output-fmt"
+          type: string
+          enum: ["sam", "bam", "cram"]
+          description: "Output format"
+```
+
+### Configuration Usage
+
+Arguments are configured using `tools.<toolname>.args.<argname>`:
+
+```groovy
+withName: 'BWA_MEM' {
+    tools.bwa.args.K = 100000000
+    tools.bwa.args.Y = true
+    tools.samtools.args.output_fmt = "cram"
+}
+```
+
+### Script Usage
+
+In module scripts, access arguments via the `tools` implicit variable:
+
+```groovy
+// tools.bwa.args.K → "-K 100000000"
+// tools.bwa.args.Y → "-Y"
+// tools.bwa.args   → "-K 100000000 -Y"  (all args concatenated)
+
+bwa mem ${tools.bwa.args} -t $task.cpus $index $reads \
+    | samtools sort ${tools.samtools.args} -o ${prefix}.bam -
+```
+
+### Benefits
+
+| Aspect | `ext.args` (Legacy) | `tools.*.args` (New) |
+|--------|---------------------|----------------------|
+| Documentation | None | In meta.yaml |
+| Type Safety | None | Validated |
+| IDE Support | None | Autocompletion |
+| Multi-tool | Confusing (`ext.args2`) | Clear (`tools.samtools.args`) |
+| Defaults | Manual | Schema-defined |
+| Enums | None | Validated |
+
+## Comparison: Plugins vs. Modules
+
+| Aspect | Plugins | Modules |
+|--------|---------|---------|
+| Purpose | Extend runtime | Reusable processes |
+| Format | JAR files | Source code (.nf) |
+| Resolution | Startup | Parse time |
+| Metadata | JSON spec | YAML manifest |
+| Naming | `nf-amazon` | `@nf-core/salmon` |
+| Cache Location | `$NXF_HOME/plugins/` | `modules/@scope/name/` |
+| Version Config | `plugins {}` in config | `modules {}` in config |
+| Registry Path | `/api/v1/plugins/` | `/api/modules/{name}` |
+
+## Rationale
+
+**Why unified registry?**
+- Reuses battle-tested infrastructure (HTTP API, S3, auth)
+- Single discovery experience for ecosystem
+- Lower operational overhead
+- Type-specific handling maintains separation of concerns
+
+**Why versions in nextflow.config instead of separate lock file?**
+- Single source of truth for workflow dependencies
+- Simple: exact versions in config, no separate lock file to manage
+- Reproducibility via explicit version pinning in config
+
+**Why parse-time resolution?**
+- Modules are source code, not compiled artifacts
+- Allows inspection/modification for reproducibility
+- Enables dependency analysis before execution
+
+**Why NPM-style scoped packages?**
+- Organization namespacing prevents name collisions (`@nf-core/salmon` vs `@myorg/salmon`)
+- Clear ownership and provenance of modules
+- Supports private registries per scope
+- Industry-standard pattern (NPM, Terraform, others)
+- Enables ecosystem organization by maintainer/organization
+
+**Why semantic versioning?**
+- Clear compatibility guarantees
+- Industry standard (npm, cargo, Go modules)
+
+## Consequences
+
+**Positive**:
+- Enables ecosystem-wide code reuse
+- Reproducible workflows (exact versions pinned in nextflow.config)
+- Centralized discovery and distribution via unified registry
+- Minimal operational overhead (single registry for both plugins and modules)
+- NPM-style scoping enables organization namespaces and private registries
+- Local `modules/` directory provides project isolation
+- Simple config model: no separate lock file
+- Simple module structure: each module has single `main.nf` entry point
+
+**Negative**:
+- Registry becomes critical infrastructure (requires HA setup)
+- Type-specific handling adds registry complexity
+- Parse-time resolution adds latency to workflow startup
+- Local `modules/` directory duplicates storage across projects (unlike global cache)
+
+**Neutral**:
+- Modules and plugins conceptually distinct but share infrastructure
+- Different resolution timing supported by same API
+
+## Links
+
+- Related: [Plugin Spec ADR](20250922-plugin-spec.md)
+- Inspired by: [Go Modules](https://go.dev/ref/mod), [npm](https://docs.npmjs.com), [Cargo](https://doc.rust-lang.org/cargo/)
+- Related: [nf-core modules](https://nf-co.re/modules)
+
+## Open Questions
+
+1. **Local vs managed module distinction**: Should local modules use the `@` prefix in include statements, or should a dot file (e.g., `.nf-modules`) be used to distinguish local modules from managed/remote modules?
+
+2. **Tool arguments CLI syntax**: What is the preferred syntax for tool arguments on the command line?
+   - Colon-separated: `--tools:<tool>:<arg> <value>`
+   - Dot-separated: `--tools.<tool>.<arg> <value>`
+
+3. **Module version configuration**: Should pipeline module versions be specified in `nextflow.config` or in a dedicated pipeline spec file (e.g., `pipeline.yaml`)?
+
+---
+
+## Appendix A: Module Metadata Schema Specification
+
+This appendix defines the JSON schema for module `meta.yaml` files. The schema maintains backward compatibility with existing nf-core module metadata patterns while supporting the new Nextflow module system features.
+
+**Schema File:** [module-spec-schema.json](module-spec-schema.json)
+**Published URL:** `https://registry.nextflow.io/schemas/module-spec/v1.0.0`
+
+### Field Reference
+
+#### Core Fields (Existing nf-core Pattern)
+
+These fields are already widely adopted in the nf-core community and remain fully supported:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | Yes | Module identifier |
+| `description` | string | Yes | Brief description of module functionality |
+| `keywords` | array[string] | Recommended | Discovery and categorization keywords |
+| `authors` | array[string] | Recommended | Original authors (GitHub handles) |
+| `maintainers` | array[string] | Recommended | Current maintainers |
+| `tools` | array[object] | Conditional | Software tools wrapped by the module |
+| `input` | array/object | Recommended | Input channel specifications |
+| `output` | object/array | Recommended | Output channel specifications |
+
+#### Extension Fields (Nextflow Module System)
+
+These fields extend the schema to support the new Nextflow module system:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `version` | string | Registry | Semantic version (MAJOR.MINOR.PATCH) |
+| `license` | string | Registry | SPDX license identifier for module code |
+| `requires` | object | Optional | All requirements: runtime, plugins, and dependencies |
+| `requires.nextflow` | string | Optional | Nextflow version constraint |
+| `requires.plugins` | array[string] | Optional | Required Nextflow plugins |
+| `requires.modules` | array[string] | Optional | Required modules (processes) |
+| `requires.workflows` | array[string] | Optional | Required workflows/subworkflows |
+
+### Detailed Field Specifications
+
+#### `name`
+
+The module name must be a fully qualified scoped identifier in `scope/name` format:
+
+```yaml
+name: nf-core/fastqc
+name: nf-core/bwa-mem
+name: myorg/custom-aligner
+```
+
+**Naming Rules:**
+- Format: `scope/name` (e.g., `nf-core/salmon`, `myorg/custom`)
+- Scope: lowercase alphanumeric with hyphens (organization/owner identifier)
+- Name: lowercase alphanumeric with underscores/hyphens (module identifier)
+- Pattern: `^[a-z0-9][a-z0-9-]*/[a-z][a-z0-9_-]*$`
+
+**Note:** The `@` prefix is used only in Nextflow DSL `include` statements (e.g., `include { FASTQC } from '@nf-core/fastqc'`) to distinguish registry modules from local file paths. The meta.yaml `name` field should not include the `@` prefix.
+
+#### `version`
+
+Semantic version following [SemVer 2.0.0](https://semver.org/):
+
+```yaml
+version: "1.0.0"
+version: "2.3.1"
+version: "1.0.0-beta.1"
+```
+
+**Version Semantics:**
+- **MAJOR:** Breaking changes to process signatures, inputs, or outputs
+- **MINOR:** New processes, backward-compatible enhancements
+- **PATCH:** Bug fixes, documentation updates
+
+**Requirement:** Mandatory for registry-published modules (scoped names in `scope/name` format).
+
+#### `requires`
+
+Specifies all requirements for the module: runtime environment, plugins, and dependencies.
+
+```yaml
+requires:
+  nextflow: ">=24.04.0"
+  plugins:
+    - nf-amazon@2.0.0
+    - nf-wave@>=1.5.0
+  modules:
+    - nf-core/fastqc@>=1.0.0
+    - nf-core/samtools/sort@>=2.1.0,<3.0.0
+    - bwa/mem
+  workflows:
+    - nf-core/fastq-align-bwa@1.0.0
+```
+
+**Unified Version Constraint Syntax:**
+
+All requirements (except `nextflow`) use a unified `name@constraint` format:
+
+| Format | Meaning | Example |
+|--------|---------|---------|
+| `name` | Any version (latest) | `bwa/mem` |
+| `name@1.2.3` | Exact version | `nf-core/fastqc@1.0.0` |
+| `name@>=1.2.3` | Greater or equal | `nf-core/fastqc@>=1.0.0` |
+| `name@>=1.2.3,<2.0.0` | Range constraint | `nf-core/samtools/sort@>=2.1.0,<3.0.0` |
+
+**`requires.nextflow`** - Nextflow version constraint:
+```yaml
+requires:
+  nextflow: ">=24.04.0"           # minimum version
+  nextflow: ">=24.04.0,<25.0.0"   # version range
+```
+
+**`requires.plugins`** - Required Nextflow plugins:
+```yaml
+requires:
+  plugins:
+    - nf-amazon@2.0.0      # exact version
+    - nf-wave@>=1.5.0      # minimum version
+    - nf-azure             # any version
+```
+
+**`requires.modules`** - Required modules (processes):
+```yaml
+requires:
+  modules:
+    - nf-core/fastqc@>=1.0.0              # registry module with constraint
+    - nf-core/samtools/sort@>=2.1.0       # nested module path
+    - bwa/mem                              # local or registry (no constraint)
+```
+
+**`requires.workflows`** - Required workflows/subworkflows:
+```yaml
+requires:
+  workflows:
+    - nf-core/fastq-align-bwa@1.0.0       # registry workflow
+    - my-local-workflow                    # local workflow
+```
+
+**Resolution:**
+1. The resolver looks up dependencies locally first, then in configured registries
+2. Pinned versions are recorded in `nextflow.config` for reproducibility
+
+#### `tools`
+
+Documents the software tools wrapped by the module, including their command-line arguments:
+
+```yaml
+tools:
+  - bwa:
+      description: BWA aligner
+      homepage: http://bio-bwa.sourceforge.net/
+      license: ["GPL-3.0-or-later"]
+      args:
+        K:
+          flag: "-K"
+          type: integer
+          description: "Process INT input bases in each batch"
+        Y:
+          flag: "-Y"
+          type: boolean
+          description: "Use soft clipping for supplementary alignments"
+```
+
+**Tool Properties:**
+
+| Property | Required | Description |
+|----------|----------|-------------|
+| `description` | Yes | Tool description |
+| `homepage` | One of these | Tool homepage URL |
+| `documentation` | One of these | Documentation URL |
+| `tool_dev_url` | One of these | Development/source URL |
+| `doi` | One of these | Publication DOI |
+| `arxiv` | No | arXiv identifier |
+| `license` | Recommended | SPDX license(s) |
+| `identifier` | Recommended | bio.tools identifier |
+| `manual` | No | User manual URL |
+| `args` | No | Command-line argument specifications |
+
+**Argument Properties (`args.<name>`):**
+
+The `args` object maps argument names to their specifications. Argument names become accessible in scripts via `tools.<toolname>.args.<argname>`.
+
+| Property | Required | Description |
+|----------|----------|-------------|
+| `flag` | Yes | CLI flag (e.g., `-K`, `--output-fmt`) |
+| `type` | Yes | Data type: `boolean`, `integer`, `float`, `string`, `file`, `path` |
+| `description` | Yes | Human-readable description |
+| `default` | No | Default value |
+| `enum` | No | List of allowed values |
+| `required` | No | Whether the argument is mandatory (default: false) |
+
+**Argument Type Behavior:**
+
+| Type | Config Example | Output |
+|------|----------------|--------|
+| `boolean` | `tools.bwa.args.Y = true` | `-Y` |
+| `integer` | `tools.bwa.args.K = 100000` | `-K 100000` |
+| `string` | `tools.bwa.args.R = "@RG\tID:s1"` | `-R @RG\tID:s1` |
+| `string` + `enum` | `tools.samtools.args.output_fmt = "cram"` | `--output-fmt cram` |
+
+#### `input` and `output`
+
+The schema supports both nf-core patterns to ensure backward compatibility:
+
+**Module Pattern (Tuple-based):**
+```yaml
+input:
+  - - meta:
+        type: map
+        description: Sample metadata
+    - reads:
+        type: file
+        description: Input FastQ files
+        ontologies:
+          - edam: "http://edamontology.org/format_1930"
+  - - index:
+        type: directory
+        description: Reference index
+
+output:
+  bam:
+    - - meta:
+          type: map
+          description: Sample metadata
+      - "*.bam":
+          type: file
+          description: Aligned BAM file
+          pattern: "*.bam"
+  versions:
+    - versions.yml:
+        type: file
+        description: Software versions
+```
+
+**Subworkflow Pattern (Simplified):**
+```yaml
+input:
+  - ch_reads:
+      description: |
+        Input FastQ files
+        Structure: [ val(meta), [ path(reads) ] ]
+  - ch_index:
+      description: BWA index files
+      type: file
+
+output:
+  - bam:
+      description: Aligned BAM files
+  - versions:
+      description: Software versions
+```
+
+**Channel Element Properties:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `type` | string | Data type: `map`, `file`, `directory`, `string`, `integer`, `float`, `boolean`, `list`, `val` |
+| `description` | string | Human-readable description |
+| `pattern` | string | File glob pattern or value pattern |
+| `optional` | boolean | Whether input is optional (default: false) |
+| `default` | any | Default value if not provided |
+| `enum` | array | List of allowed values |
+| `ontologies` | array | EDAM or other ontology annotations |
+
+### Migration Guide
+
+#### From nf-core Module to Registry Module
+
+**Before (nf-core local):**
+```yaml
+name: bwa_mem
+description: Align reads using BWA-MEM
+keywords:
+  - alignment
+  - bwa
+tools:
+  - bwa:
+      description: BWA software
+      homepage: http://bio-bwa.sourceforge.net/
+      license: ["GPL-3.0-or-later"]
+      identifier: biotools:bwa
+authors:
+  - "@drpatelh"
+maintainers:
+  - "@drpatelh"
+input:
+  # ... existing input spec
+output:
+  # ... existing output spec
+```
+
+**After (Registry-ready):**
+```yaml
+name: nf-core/bwa-mem              # Added scope prefix
+version: "1.0.0"                    # Added version
+description: Align reads using BWA-MEM
+keywords:
+  - alignment
+  - bwa
+license: MIT                        # Added module license
+requires:                           # Added requirements
+  nextflow: ">=24.04.0"
+  modules:                          # Added module dependencies (if any)
+    - nf-core/samtools/sort@>=1.0.0
+tools:
+  - bwa:
+      description: BWA software
+      homepage: http://bio-bwa.sourceforge.net/
+      license: ["GPL-3.0-or-later"]
+      identifier: biotools:bwa
+authors:
+  - "@drpatelh"
+maintainers:
+  - "@drpatelh"
+input:
+  # ... unchanged
+output:
+  # ... unchanged
+```
+
+#### Schema Validation
+
+Use the schema reference in your `meta.yaml`:
+
+```yaml
+# yaml-language-server: $schema=https://registry.nextflow.io/schemas/module-spec/v1.0.0
+
+name: nf-core/my-module
+version: "1.0.0"
+# ...
+```
+
+### Compatibility Matrix
+
+| Feature | nf-core Current | Nextflow Module System |
+|---------|-----------------|------------------------|
+| Simple names | Yes | Yes (local only) |
+| Scoped names | No | Yes (registry) |
+| Version field | No | Yes (required for registry) |
+| `tools` section | Yes | Yes |
+| `components` | Yes (subworkflows) | Deprecated → use `requires.modules` |
+| `requires` | No | Yes (unified requirements field) |
+| I/O specifications | Yes | Yes |
+| Ontologies | Yes | Yes |
+
+### Unsupported nf-core Attributes
+
+The following attributes from the nf-core meta schema are **not supported** in the Nextflow module system:
+
+| Attribute | Reason | Future |
+|-----------|--------|--------|
+| `extra_args` | Not adopted in practice by nf-core modules | Will be redesigned as part of the `tools` schema attribute to document tool-specific arguments and configuration options |
+| `components` | Replaced by unified `requires.modules` | Use `requires.modules` for all module dependencies (local and registry) |
+
+### Complete Examples
+
+#### Minimal nf-core Module
+
+```yaml
+name: fastqc
+description: Run FastQC on sequenced reads
+keywords:
+  - quality control
+  - qc
+  - fastq
+tools:
+  - fastqc:
+      description: FastQC quality metrics
+      homepage: https://www.bioinformatics.babraham.ac.uk/projects/fastqc/
+      license: ["GPL-2.0-only"]
+      identifier: biotools:fastqc
+authors:
+  - "@drpatelh"
+maintainers:
+  - "@drpatelh"
+output:
+  html:
+    - "*.html":
+        type: file
+        description: FastQC HTML report
+  versions:
+    - versions.yml:
+        type: file
+        description: Software versions
+```
+
+#### Full Registry Module
+
+```yaml
+name: nf-core/bwa-align
+version: "1.2.4"
+description: Align reads to reference genome using BWA-MEM algorithm
+keywords:
+  - alignment
+  - mapping
+  - bwa
+  - bam
+  - fastq
+license: MIT
+
+requires:
+  nextflow: ">=24.04.0"
+  plugins:
+    - nf-wave@1.5.0
+  modules:
+    - nf-core/samtools/view@>=1.0.0,<2.0.0
+    - nf-core/samtools/sort@>=2.1.0,<2.2.0
+
+tools:
+  - bwa:
+      description: |
+        BWA is a software package for mapping DNA sequences
+        against a large reference genome.
+      homepage: http://bio-bwa.sourceforge.net/
+      documentation: https://bio-bwa.sourceforge.net/bwa.shtml
+      doi: 10.1093/bioinformatics/btp324
+      license: ["GPL-3.0-or-later"]
+      identifier: biotools:bwa
+
+authors:
+  - "@nf-core"
+maintainers:
+  - "@drpatelh"
+  - "@maxulysse"
+
+input:
+  - - meta:
+        type: map
+        description: Sample metadata map (e.g., [ id:'sample1', single_end:false ])
+    - reads:
+        type: file
+        description: Input FastQ files
+        ontologies:
+          - edam: "http://edamontology.org/format_1930"
+  - - meta2:
+        type: map
+        description: Reference metadata
+    - index:
+        type: directory
+        description: BWA index directory
+        ontologies:
+          - edam: "http://edamontology.org/data_3210"
+
+output:
+  bam:
+    - - meta:
+          type: map
+          description: Sample metadata
+      - "*.bam":
+          type: file
+          description: Aligned BAM file
+          pattern: "*.bam"
+          ontologies:
+            - edam: "http://edamontology.org/format_2572"
+  versions:
+    - versions.yml:
+        type: file
+        description: Software versions
+        pattern: "versions.yml"
+```
+
+#### Subworkflow with Module Dependencies
+
+```yaml
+name: fastq_align_bwa
+description: Align reads with BWA and generate statistics
+keywords:
+  - alignment
+  - bwa
+  - samtools
+  - statistics
+
+requires:
+  modules:
+    - bwa/mem
+    - samtools/sort
+    - samtools/index
+    - samtools/stats
+
+authors:
+  - "@JoseEspinosa"
+maintainers:
+  - "@JoseEspinosa"
+
+input:
+  - ch_reads:
+      description: |
+        Input FastQ files
+        Structure: [ val(meta), [ path(reads) ] ]
+  - ch_index:
+      description: BWA index files
+
+output:
+  - bam:
+      description: Sorted BAM files
+  - bai:
+      description: BAM index files
+  - stats:
+      description: Alignment statistics
+  - versions:
+      description: Software versions
+```
diff --git a/adr/module-spec-schema.json b/adr/module-spec-schema.json
new file mode 100644
index 0000000000..6f54ed6fed
--- /dev/null
+++ b/adr/module-spec-schema.json
@@ -0,0 +1,589 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://registry.nextflow.io/schemas/module-spec/v1.0.0",
+  "title": "Nextflow Module Metadata Schema",
+  "description": "Schema for Nextflow module meta.yaml files, supporting both nf-core community patterns and the Nextflow module system",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Module name. Can be a simple identifier (e.g., 'fastqc', 'bwa_mem') for local/nf-core modules, or a fully qualified scoped name (e.g., 'nf-core/fastqc', 'myorg/custom') for registry modules. Note: The '@' prefix is only used in DSL include statements, not in meta.yaml",
+      "examples": ["fastqc", "bwa_mem", "nf-core/fastqc", "myorg/salmon-quant"],
+      "pattern": "^([a-z0-9][a-z0-9-]*/)?[a-z][a-z0-9_-]*$"
+    },
+    "version": {
+      "type": "string",
+      "description": "Semantic version of the module (MAJOR.MINOR.PATCH). Required for registry publication",
+      "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(-[0-9A-Za-z-]+(\\.[0-9A-Za-z-]+)*)?(\\+[0-9A-Za-z-]+(\\.[0-9A-Za-z-]+)*)?$",
+      "examples": ["1.0.0", "2.1.3", "1.0.0-beta.1"]
+    },
+    "description": {
+      "type": "string",
+      "description": "Brief description of what the module does",
+      "minLength": 10,
+      "maxLength": 500
+    },
+    "keywords": {
+      "type": "array",
+      "description": "Keywords for discovery and categorization",
+      "items": {
+        "type": "string",
+        "minLength": 2
+      },
+      "minItems": 1,
+      "uniqueItems": true
+    },
+    "license": {
+      "type": "string",
+      "description": "SPDX license identifier for the module code itself",
+      "examples": ["MIT", "Apache-2.0", "GPL-3.0-or-later"]
+    },
+    "authors": {
+      "type": "array",
+      "description": "Original authors of the module (GitHub handles preferred)",
+      "items": {
+        "type": "string",
+        "pattern": "^@?[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?$"
+      },
+      "minItems": 1
+    },
+    "maintainers": {
+      "type": "array",
+      "description": "Current maintainers of the module (GitHub handles preferred)",
+      "items": {
+        "type": "string",
+        "pattern": "^@?[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?$"
+      }
+    },
+    "requires": {
+      "type": "object",
+      "description": "All requirements for the module: runtime environment, plugins, and dependencies",
+      "properties": {
+        "nextflow": {
+          "type": "string",
+          "description": "Nextflow version constraint using comparison operators",
+          "examples": [">=24.04.0", ">=24.04.0,<25.0.0"],
+          "pattern": "^[<>=!]+[0-9]+\\.[0-9]+\\.[0-9]+(-[a-zA-Z0-9]+)?(,\\s*[<>=!]+[0-9]+\\.[0-9]+\\.[0-9]+(-[a-zA-Z0-9]+)?)*$"
+        },
+        "plugins": {
+          "type": "array",
+          "description": "Required Nextflow plugins with optional version constraints",
+          "items": {
+            "type": "string",
+            "description": "Plugin reference in format 'plugin-name' or 'plugin-name@constraint'",
+            "pattern": "^[a-z][a-z0-9-]*(@[<>=,0-9.]+)?$",
+            "examples": ["nf-amazon@2.0.0", "nf-wave@>=1.5.0", "nf-azure"]
+          }
+        },
+        "modules": {
+          "type": "array",
+          "description": "Required modules (processes) with optional version constraints",
+          "items": {
+            "type": "string",
+            "description": "Module reference in format '[scope/]name' or '[scope/]name@constraint'",
+            "pattern": "^([a-z0-9][a-z0-9-]*/)?[a-z][a-z0-9_/-]*(@[<>=,0-9.]+)?$",
+            "examples": ["nf-core/fastqc@>=1.0.0", "nf-core/samtools/sort@>=2.1.0,<3.0.0", "bwa/mem"]
+          }
+        },
+        "workflows": {
+          "type": "array",
+          "description": "Required workflows/subworkflows with optional version constraints",
+          "items": {
+            "type": "string",
+            "description": "Workflow reference in format '[scope/]name' or '[scope/]name@constraint'",
+            "pattern": "^([a-z0-9][a-z0-9-]*/)?[a-z][a-z0-9_/-]*(@[<>=,0-9.]+)?$",
+            "examples": ["nf-core/fastq-align-bwa@1.0.0", "my-subworkflow"]
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "tools": {
+      "type": "array",
+      "description": "Software tools wrapped by this module with their metadata",
+      "items": {
+        "type": "object",
+        "minProperties": 1,
+        "maxProperties": 1,
+        "patternProperties": {
+          "^[a-zA-Z][a-zA-Z0-9_-]*$": {
+            "$ref": "#/$defs/toolSpec"
+          }
+        }
+      }
+    },
+    "input": {
+      "description": "Input channel specifications for the module's process(es)",
+      "oneOf": [
+        {
+          "type": "array",
+          "description": "Array-based input specification (nf-core modules pattern)",
+          "items": {
+            "$ref": "#/$defs/inputChannelItem"
+          }
+        },
+        {
+          "type": "object",
+          "description": "Object-based input specification (simplified pattern)",
+          "patternProperties": {
+            "^[a-zA-Z_][a-zA-Z0-9_]*$": {
+              "$ref": "#/$defs/channelElementSpec"
+            }
+          }
+        }
+      ]
+    },
+    "output": {
+      "description": "Output channel specifications for the module's process(es)",
+      "oneOf": [
+        {
+          "type": "object",
+          "description": "Object-based output specification (nf-core modules pattern)",
+          "patternProperties": {
+            "^[a-zA-Z_][a-zA-Z0-9_]*$": {
+              "$ref": "#/$defs/outputChannelDef"
+            }
+          }
+        },
+        {
+          "type": "array",
+          "description": "Array-based output specification (nf-core subworkflows pattern)",
+          "items": {
+            "type": "object",
+            "patternProperties": {
+              "^[a-zA-Z_][a-zA-Z0-9_]*$": {
+                "$ref": "#/$defs/channelElementSpec"
+              }
+            }
+          }
+        }
+      ]
+    }
+  },
+  "required": ["name", "description"],
+  "$defs": {
+    "toolSpec": {
+      "type": "object",
+      "description": "Specification for a software tool used by the module",
+      "properties": {
+        "description": {
+          "type": "string",
+          "description": "Description of the tool and its purpose"
+        },
+        "homepage": {
+          "type": "string",
+          "format": "uri",
+          "description": "Tool's homepage URL",
+          "pattern": "^https?://.*$"
+        },
+        "documentation": {
+          "type": "string",
+          "format": "uri",
+          "description": "Documentation URL",
+          "pattern": "^(https?|ftp)://.*$"
+        },
+        "tool_dev_url": {
+          "type": "string",
+          "format": "uri",
+          "description": "Development/source code URL",
+          "pattern": "^https?://.*$"
+        },
+        "doi": {
+          "description": "Digital Object Identifier for the tool's publication",
+          "oneOf": [
+            {
+              "type": "string",
+              "pattern": "^10\\.\\d{4,9}/[^,]+$"
+            },
+            {
+              "type": "string",
+              "const": "no DOI available"
+            }
+          ]
+        },
+        "arxiv": {
+          "type": "string",
+          "description": "arXiv identifier",
+          "pattern": "^arXiv:\\d{4}\\.\\d{4,5}(v\\d+)?$"
+        },
+        "licence": {
+          "type": "array",
+          "description": "SPDX license identifier(s) for the tool",
+          "items": {
+            "type": "string"
+          },
+          "minItems": 1,
+          "uniqueItems": true
+        },
+        "identifier": {
+          "description": "bio.tools identifier or empty string",
+          "oneOf": [
+            {
+              "type": "string",
+              "pattern": "^biotools:[a-zA-Z0-9_-]+$"
+            },
+            {
+              "type": "string",
+              "maxLength": 0
+            }
+          ]
+        },
+        "manual": {
+          "type": "string",
+          "format": "uri",
+          "description": "Manual/user guide URL"
+        },
+        "args": {
+          "type": "object",
+          "description": "Command-line arguments supported by the tool. Keys are argument names accessible via tool.<toolname>.args.<name>",
+          "patternProperties": {
+            "^[a-zA-Z_][a-zA-Z0-9_]*$": {
+              "$ref": "#/$defs/toolArgSpec"
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "required": ["description"],
+      "anyOf": [
+        { "required": ["homepage"] },
+        { "required": ["documentation"] },
+        { "required": ["tool_dev_url"] },
+        { "required": ["doi"] }
+      ]
+    },
+    "toolArgSpec": {
+      "type": "object",
+      "description": "Specification for a tool command-line argument",
+      "properties": {
+        "flag": {
+          "type": "string",
+          "description": "The CLI flag (e.g., '-n', '--output-fmt')",
+          "pattern": "^--?[a-zA-Z][a-zA-Z0-9_-]*$"
+        },
+        "type": {
+          "type": "string",
+          "description": "Data type of the argument value",
+          "enum": ["boolean", "integer", "float", "string", "file", "path"]
+        },
+        "description": {
+          "type": "string",
+          "description": "Human-readable description of the argument"
+        },
+        "default": {
+          "description": "Default value for the argument"
+        },
+        "enum": {
+          "type": "array",
+          "description": "List of allowed values",
+          "uniqueItems": true
+        },
+        "required": {
+          "type": "boolean",
+          "description": "Whether this argument is required",
+          "default": false
+        }
+      },
+      "required": ["flag", "type", "description"]
+    },
+    "channelElementSpec": {
+      "type": "object",
+      "description": "Specification for a channel element (input or output)",
+      "properties": {
+        "type": {
+          "type": "string",
+          "description": "Data type of the channel element",
+          "enum": ["map", "file", "directory", "string", "integer", "float", "boolean", "list", "val"]
+        },
+        "description": {
+          "type": "string",
+          "description": "Human-readable description of the channel element"
+        },
+        "pattern": {
+          "type": "string",
+          "description": "File pattern in glob syntax or allowed values pattern"
+        },
+        "optional": {
+          "type": "boolean",
+          "description": "Whether this input is optional",
+          "default": false
+        },
+        "default": {
+          "description": "Default value if not provided"
+        },
+        "enum": {
+          "type": "array",
+          "description": "List of allowed values",
+          "uniqueItems": true
+        },
+        "ontologies": {
+          "type": "array",
+          "description": "Ontology annotations (e.g., EDAM)",
+          "items": {
+            "type": "object",
+            "patternProperties": {
+              "^[a-zA-Z]+$": {
+                "type": "string",
+                "format": "uri",
+                "description": "Ontology URI"
+              }
+            }
+          },
+          "uniqueItems": true
+        }
+      },
+      "required": ["description"]
+    },
+    "inputChannelItem": {
+      "description": "Input channel item - can be a tuple (array) or single element (object)",
+      "oneOf": [
+        {
+          "type": "array",
+          "description": "Tuple-style input channel (multiple elements per emission)",
+          "items": {
+            "type": "object",
+            "patternProperties": {
+              "^[a-zA-Z_][a-zA-Z0-9_]*$|^\\*\\..*$": {
+                "$ref": "#/$defs/channelElementSpec"
+              }
+            }
+          }
+        },
+        {
+          "type": "object",
+          "description": "Single-element input channel",
+          "patternProperties": {
+            "^[a-zA-Z_][a-zA-Z0-9_]*$": {
+              "$ref": "#/$defs/channelElementSpec"
+            }
+          }
+        }
+      ]
+    },
+    "outputChannelDef": {
+      "type": "array",
+      "description": "Output channel definition - array of emission patterns",
+      "items": {
+        "oneOf": [
+          {
+            "type": "object",
+            "description": "Single output element",
+            "patternProperties": {
+              "^[a-zA-Z_$][a-zA-Z0-9_{}.$*\"']*$": {
+                "$ref": "#/$defs/channelElementSpec"
+              }
+            }
+          },
+          {
+            "type": "array",
+            "description": "Tuple output (multiple elements per emission)",
+            "items": {
+              "type": "object",
+              "patternProperties": {
+                "^[a-zA-Z_$][a-zA-Z0-9_{}.$*\"']*$|^\\*\\..*$": {
+                  "$ref": "#/$defs/channelElementSpec"
+                }
+              }
+            }
+          }
+        ]
+      }
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "name": {
+            "pattern": "^[a-z0-9][a-z0-9-]*/"
+          }
+        },
+        "required": ["name"]
+      },
+      "then": {
+        "required": ["name", "description", "version"],
+        "properties": {
+          "version": {
+            "description": "Version is required for scoped/registry modules (scope/name format)"
+          }
+        }
+      }
+    }
+  ],
+  "examples": [
+    {
+      "name": "fastqc",
+      "description": "Run FastQC on sequenced reads",
+      "keywords": ["quality control", "qc", "adapters", "fastq"],
+      "tools": [
+        {
+          "fastqc": {
+            "description": "FastQC gives general quality metrics about your reads.",
+            "homepage": "https://www.bioinformatics.babraham.ac.uk/projects/fastqc/",
+            "documentation": "https://www.bioinformatics.babraham.ac.uk/projects/fastqc/Help/",
+            "licence": ["GPL-2.0-only"],
+            "identifier": "biotools:fastqc"
+          }
+        }
+      ],
+      "input": [
+        [
+          {
+            "meta": {
+              "type": "map",
+              "description": "Groovy Map containing sample information"
+            }
+          },
+          {
+            "reads": {
+              "type": "file",
+              "description": "Input FastQ files",
+              "ontologies": []
+            }
+          }
+        ]
+      ],
+      "output": {
+        "html": [
+          [
+            {
+              "meta": {
+                "type": "map",
+                "description": "Sample information"
+              }
+            },
+            {
+              "*.html": {
+                "type": "file",
+                "description": "FastQC report",
+                "pattern": "*_{fastqc.html}",
+                "ontologies": []
+              }
+            }
+          ]
+        ],
+        "versions": [
+          {
+            "versions.yml": {
+              "type": "file",
+              "description": "File containing software versions",
+              "pattern": "versions.yml"
+            }
+          }
+        ]
+      },
+      "authors": ["@drpatelh", "@ewels"],
+      "maintainers": ["@drpatelh", "@ewels"]
+    },
+    {
+      "name": "nf-core/bwa-align",
+      "version": "1.2.4",
+      "description": "Align reads using BWA-MEM algorithm",
+      "keywords": ["alignment", "bwa", "mapping", "fastq", "bam"],
+      "license": "MIT",
+      "authors": ["@nf-core"],
+      "maintainers": ["@nf-core"],
+      "requires": {
+        "nextflow": ">=24.04.0",
+        "plugins": [
+          "nf-amazon@2.0.0"
+        ],
+        "modules": [
+          "nf-core/samtools/view@>=1.0.0,<2.0.0",
+          "nf-core/samtools/sort@>=2.1.0,<2.2.0"
+        ]
+      },
+      "tools": [
+        {
+          "bwa": {
+            "description": "BWA aligner",
+            "homepage": "http://bio-bwa.sourceforge.net/",
+            "licence": ["GPL-3.0-or-later"],
+            "args": {
+              "K": {
+                "flag": "-K",
+                "type": "integer",
+                "description": "Process INT input bases in each batch"
+              },
+              "Y": {
+                "flag": "-Y",
+                "type": "boolean",
+                "description": "Use soft clipping for supplementary alignments"
+              }
+            }
+          }
+        },
+        {
+          "samtools": {
+            "description": "SAMtools",
+            "homepage": "http://www.htslib.org/",
+            "licence": ["MIT"],
+            "args": {
+              "output_fmt": {
+                "flag": "--output-fmt",
+                "type": "string",
+                "description": "Output format",
+                "enum": ["sam", "bam", "cram"]
+              }
+            }
+          }
+        }
+      ],
+      "input": [
+        [
+          {
+            "meta": {
+              "type": "map",
+              "description": "Sample metadata map"
+            }
+          },
+          {
+            "reads": {
+              "type": "file",
+              "description": "Input FastQ files",
+              "ontologies": [
+                { "edam": "http://edamontology.org/format_1930" }
+              ]
+            }
+          }
+        ],
+        {
+          "index": {
+            "type": "directory",
+            "description": "BWA index directory"
+          }
+        }
+      ],
+      "output": {
+        "bam": [
+          [
+            {
+              "meta": {
+                "type": "map",
+                "description": "Sample metadata"
+              }
+            },
+            {
+              "*.bam": {
+                "type": "file",
+                "description": "Aligned BAM file",
+                "pattern": "*.bam",
+                "ontologies": [
+                  { "edam": "http://edamontology.org/format_2572" }
+                ]
+              }
+            }
+          ]
+        ],
+        "versions": [
+          {
+            "versions.yml": {
+              "type": "file",
+              "description": "Software versions"
+            }
+          }
+        ]
+      }
+    }
+  ]
+}
\ No newline at end of file
diff --git a/specs/251117-module-system/checklists/requirements.md b/specs/251117-module-system/checklists/requirements.md
new file mode 100644
index 0000000000..e01762d921
--- /dev/null
+++ b/specs/251117-module-system/checklists/requirements.md
@@ -0,0 +1,39 @@
+# Specification Quality Checklist: Nextflow Module System Client
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-01-15
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- Specification is complete and ready for `/speckit.plan`
+- All 8 user stories have clear acceptance scenarios
+- 32 functional requirements defined across 6 categories
+- 8 success criteria defined with measurable outcomes
+- Edge cases documented for error handling scenarios
+- Registry backend is explicitly out of scope (assumed implemented)
\ No newline at end of file
diff --git a/specs/251117-module-system/spec.md b/specs/251117-module-system/spec.md
new file mode 100644
index 0000000000..4a538a765c
--- /dev/null
+++ b/specs/251117-module-system/spec.md
@@ -0,0 +1,251 @@
+# Feature Specification: Nextflow Module System Client
+
+**Feature Branch**: `251117-module-system`
+**Created**: 2026-01-15
+**Status**: Draft
+**Input**: User description: "Implement Nextflow module system client based on ADR 20251114-module-system.md. Focus on client-side implementation only - CLI commands, DSL parser extensions, dependency resolution, and local storage. Registry backend is assumed to be already implemented."
+
+## Overview
+
+This specification covers the **Nextflow client-side implementation** of the module system, enabling pipeline developers to:
+- Include remote modules from the Nextflow registry using `@scope/name` syntax
+- Manage module versions through `nextflow.config`
+- Use CLI commands to install, search, list, remove, freeze, publish, and run modules
+- Configure tool arguments through structured `meta.yaml` definitions
+
+**Out of Scope**: Registry backend implementation (assumed already available at `registry.nextflow.io`)
+
+## User Scenarios & Testing
+
+### User Story 1 - Install and Use Registry Module (Priority: P1)
+
+A pipeline developer wants to use a pre-built module from the Nextflow registry in their workflow without manually downloading or managing module files.
+
+**Why this priority**: This is the core value proposition - enabling code reuse from the ecosystem. Without this, the module system provides no benefit.
+
+**Independent Test**: Can be fully tested by running `nextflow module install nf-core/fastqc` and then executing a workflow that includes the module. Delivers immediate value by enabling module consumption.
+
+**Acceptance Scenarios**:
+
+1. **Given** a new Nextflow project with no modules installed, **When** user runs `nextflow module install nf-core/fastqc`, **Then** the module is downloaded to `modules/@nf-core/fastqc/`, a `.checksum` file is created, and `nextflow.config` is updated with the version
+2. **Given** a workflow file with `include { FASTQC } from '@nf-core/fastqc'`, **When** user runs `nextflow run main.nf`, **Then** Nextflow resolves the module from local storage and executes the process
+3. **Given** a module version declared in `nextflow.config`, **When** user includes the module, **Then** the declared version is used (not latest)
+
+---
+
+### User Story 2 - Run Module Directly (Priority: P1)
+
+A user wants to run a module directly from the command line without writing a wrapper workflow.
+
+**Why this priority**: Enables immediate productivity - users can test and execute modules without boilerplate code, essential for AI agents and quick experimentation.
+
+**Independent Test**: Can be tested by running `nextflow module run nf-core/fastqc --input 'data/*.fq'` and verifying the process executes.
+
+**Acceptance Scenarios**:
+
+1. **Given** a module is available (locally or in registry), **When** user runs `nextflow module run nf-core/fastqc --input 'data/*.fastq'`, **Then** the module is executed with the provided inputs mapped to process parameters
+2. **Given** a module with tool arguments defined in `meta.yaml`, **When** user runs `nextflow module run nf-core/bwa-align --tools:bwa:K 100000`, **Then** the tool argument is validated and passed to the process
+3. **Given** a module is not installed locally, **When** user runs `nextflow module run nf-core/salmon`, **Then** the module is automatically downloaded before execution
+
+---
+
+### User Story 3 - Structured Tool Arguments (Priority: P1)
+
+A module author wants to define typed, documented tool arguments that replace the legacy `ext.args` pattern.
+
+**Why this priority**: Critical for module usability - provides type-safe, documented arguments that enable IDE autocompletion and validation, replacing the opaque `ext.args` pattern.
+
+**Independent Test**: Can be tested by configuring `tools.bwa.args.K = 100000` in config and verifying the argument is applied in the script.
+
+**Acceptance Scenarios**:
+
+1. **Given** a module with `tools.*.args` defined in `meta.yaml`, **When** user configures `tools.bwa.args.K = 100000` in config, **Then** the argument is accessible in scripts as `tools.bwa.args.K` returning `-K 100000`
+2. **Given** all tool arguments are configured, **When** script uses `${tools.bwa.args}`, **Then** all configured arguments are concatenated in the output
+3. **Given** an argument with enum validation, **When** user provides an invalid value, **Then** a validation error is displayed
+
+---
+
+### User Story 4 - Module Version Management (Priority: P2)
+
+A pipeline developer wants to pin and manage module versions to ensure reproducible workflow executions.
+
+**Why this priority**: Reproducibility is important for scientific workflows - version pinning ensures consistent results.
+
+**Independent Test**: Can be tested by modifying `nextflow.config` module versions and verifying the correct version is used on workflow run.
+
+**Acceptance Scenarios**:
+
+1. **Given** a module is installed at version 1.0.0, **When** user changes `nextflow.config` to specify version 1.1.0 and runs the workflow, **Then** version 1.1.0 is automatically downloaded and replaces the local copy
+2. **Given** modules installed locally, **When** user runs `nextflow module list`, **Then** configured version, installed version, latest available version, and status are displayed for each module
+
+---
+
+### User Story 5 - Module Integrity Protection (Priority: P2)
+
+A pipeline developer who has locally modified a module (for debugging or customization) wants to be protected from accidentally losing those changes.
+
+**Why this priority**: Protects user work - important for developer experience but not blocking core functionality.
+
+**Independent Test**: Can be tested by modifying a module's `main.nf` locally, then attempting to install a different version and verifying the warning appears.
+
+**Acceptance Scenarios**:
+
+1. **Given** a locally modified module (checksum mismatch with `.checksum`), **When** user tries to install a different version, **Then** Nextflow warns about local modifications and does NOT override
+2. **Given** a locally modified module, **When** user runs `nextflow module install -force`, **Then** the local module is replaced with the registry version
+3. **Given** a locally modified module, **When** user runs the workflow, **Then** a warning is displayed about checksum mismatch but execution continues
+
+---
+
+### User Story 6 - Remove Module (Priority: P3)
+
+A pipeline developer wants to remove a module they no longer need.
+
+**Why this priority**: Housekeeping feature - useful but not blocking core workflows.
+
+**Independent Test**: Can be tested by running `nextflow module remove nf-core/fastqc` and verifying files are deleted and config is updated.
+
+**Acceptance Scenarios**:
+
+1. **Given** a module is installed, **When** user runs `nextflow module remove nf-core/fastqc`, **Then** the module directory is deleted and the entry is removed from `nextflow.config`
+2. **Given** a module is referenced in workflow files, **When** user runs `nextflow module remove`, **Then** a warning is displayed about the reference but removal proceeds
+
+---
+
+### User Story 7 - Search and Discover Modules (Priority: P3)
+
+A pipeline developer wants to find available modules in the registry that match their analysis needs.
+
+**Why this priority**: Discovery feature - useful but users can find modules through documentation or registry web UI.
+
+**Independent Test**: Can be tested by running `nextflow module search bwa` and verifying results are displayed with name, version, and description.
+
+**Acceptance Scenarios**:
+
+1. **Given** modules exist in the registry, **When** user runs `nextflow module search alignment`, **Then** matching modules are displayed with name, latest version, description, and download count
+2. **Given** user wants JSON output for scripting, **When** user runs `nextflow module search fastqc -json`, **Then** results are returned in parseable JSON format
+3. **Given** many results exist, **When** user runs `nextflow module search quality -limit 5`, **Then** only 5 results are returned
+
+---
+
+### User Story 8 - Publish Module to Registry (Priority: P3)
+
+A module author wants to publish their module to the Nextflow registry for others to use.
+
+**Why this priority**: Ecosystem contribution feature - important for growth but users can consume modules without publishing capability.
+
+**Independent Test**: Can be tested by creating a valid module structure and running `nextflow module publish -dry-run` to validate.
+
+**Acceptance Scenarios**:
+
+1. **Given** a valid module with `main.nf`, `meta.yaml`, and `README.md`, **When** user runs `nextflow module publish myorg/my-module`, **Then** the module is uploaded to the registry and becomes available for installation
+2. **Given** an invalid module (missing required fields), **When** user runs `nextflow module publish`, **Then** validation errors are displayed listing the missing requirements
+3. **Given** no authentication configured, **When** user runs `nextflow module publish`, **Then** a clear error message indicates authentication is required
+
+---
+
+### Edge Cases
+
+- What happens when the registry is unreachable during module resolution?
+  - Nextflow uses locally cached modules if available, otherwise fails with a clear network error
+- How does the system handle circular module dependencies?
+  - Dependency resolver detects cycles and fails with an error listing the cycle
+- What happens when two modules require incompatible versions of the same dependency?
+  - Version conflict is reported with the conflicting requirements
+- How are modules resolved when multiple registries are configured?
+  - Registries are tried in order; first match wins
+- What happens when `meta.yaml` is missing from a module?
+  - Module is treated as having no dependencies; basic functionality works
+- What happens when local module directory is corrupted or incomplete?
+  - Checksum mismatch triggers warning; `-force` allows re-download
+
+## Requirements
+
+### Functional Requirements
+
+#### DSL Parser Extension
+
+- **FR-001**: System MUST recognize `@scope/name` syntax in `include` statements as registry module references
+- **FR-002**: System MUST distinguish between local file paths (starting with `.` or `/`) and registry modules (starting with `@`)
+- **FR-003**: System MUST resolve module versions from `nextflow.config` `modules {}` block before downloading
+- **FR-004**: System MUST parse and validate `meta.yaml` files for module metadata and dependencies
+
+#### Module Resolution
+
+- **FR-005**: System MUST resolve modules at workflow parse time (after plugin resolution)
+- **FR-006**: System MUST check local `modules/@scope/name/` directory before querying registry
+- **FR-007**: System MUST verify module integrity using `.checksum` file on every run
+- **FR-008**: System MUST download modules from registry when not present locally or when version differs
+- **FR-009**: System MUST NOT override locally modified modules (checksum mismatch) unless `-force` is used
+
+#### Local Storage
+
+- **FR-012**: System MUST store modules in `modules/@scope/name/` directory structure (single version per module)
+- **FR-013**: System MUST create `.checksum` file from registry's X-Checksum header on download
+- **FR-014**: System MUST store module's `main.nf`, `meta.yaml`, and supporting files in the module directory
+
+#### CLI Commands
+
+- **FR-015**: System MUST provide `nextflow module install [scope/name]` command to download modules
+- **FR-016**: System MUST provide `nextflow module search <query>` command to search the registry
+- **FR-017**: System MUST provide `nextflow module list` command to show installed vs configured modules
+- **FR-018**: System MUST provide `nextflow module remove scope/name` command to delete modules
+- **FR-019**: System MUST provide `nextflow module publish scope/name` command to upload modules to registry
+- **FR-020**: System MUST provide `nextflow module run scope/name` command to execute modules directly
+
+#### Configuration
+
+- **FR-022**: System MUST read module versions from `modules {}` block in `nextflow.config`
+- **FR-023**: System MUST support `registry {}` block for configuring registry URL and authentication
+- **FR-024**: System MUST support `NXF_REGISTRY_TOKEN` environment variable for authentication
+- **FR-025**: System MUST support multiple registry URLs with fallback ordering
+
+#### Tool Arguments
+
+- **FR-026**: System MUST provide `tools.<toolname>.args.<argname>` implicit variable in module scripts
+- **FR-027**: System MUST validate tool arguments against `meta.yaml` schema (type, enum)
+- **FR-028**: System MUST support boolean, integer, float, string, file, and path argument types
+- **FR-029**: System MUST concatenate all tool arguments when `tools.<toolname>.args` is accessed
+
+#### Registry Communication
+
+- **FR-030**: System MUST communicate with registry via documented Module API endpoints
+- **FR-031**: System MUST handle authentication using Bearer token in Authorization header
+- **FR-032**: System MUST verify SHA-256 checksum on module download
+
+### Key Entities
+
+- **Module**: A reusable Nextflow process definition with `main.nf` entry point, optional `meta.yaml` manifest, and README documentation
+- **Module Reference**: A scoped identifier (`@scope/name`) pointing to a registry module
+- **Module Manifest (meta.yaml)**: YAML file containing module metadata, version, dependencies, tool arguments schema
+- **Checksum File (.checksum)**: Local cache of registry checksum for integrity verification
+- **Registry Configuration**: Settings for registry URL, authentication, and fallback ordering
+
+## Success Criteria
+
+### Measurable Outcomes
+
+- **SC-001**: Pipeline developers can install and use a registry module within 5 minutes of starting a new project
+- **SC-002**: Module resolution adds less than 2 seconds to workflow startup time when modules are cached locally
+- **SC-003**: Users can successfully search, install, and run any module from the registry without reading documentation
+- **SC-004**: 100% of module version changes in `nextflow.config` result in automatic module updates without manual intervention
+- **SC-005**: Users receive clear, actionable error messages for all failure scenarios (network, validation, authentication)
+- **SC-006**: Module authors can publish a new module version within 3 minutes using the CLI
+- **SC-007**: Locally modified modules are never accidentally overwritten during normal operations
+
+## Assumptions
+
+- Registry backend is fully implemented and available at `registry.nextflow.io` with the Module API as documented in the ADR
+- Existing plugin authentication system can be reused for module registry authentication
+- Module bundle size limit of 1MB (uncompressed) is enforced by the registry
+- Network connectivity is available for initial module downloads; offline operation uses local cache only
+- The `modules/` directory is intended to be committed to the pipeline's git repository
+- Version constraints in `meta.yaml` follow the same syntax as existing Nextflow plugin version constraints
+- SHA-256 is used for all checksum operations
+- Tool arguments CLI syntax uses colon-separated format: `--tools:<tool>:<arg>`
+
+## Dependencies
+
+- Registry backend API (Module API endpoints as specified in ADR)
+- Existing Nextflow plugin system (for authentication reuse)
+- Existing DSL parser infrastructure (for `include` statement extension)
+- Existing config parser (for `modules {}` and `registry {}` blocks)
\ No newline at end of file