@brainpilot/skills 0.0.6 → 0.0.8

package/skills/06_fMRI_Neuroimaging/aibl-skill/scripts/reorganize_aibl.py

@@ -0,0 +1,394 @@
+#!/usr/bin/env python3
+"""Reorganize AIBL raw data into BIDS-compliant directory structure.
+
+Handles AIBL-style subject IDs, visit names, and multimodal routing
+for T1w MRI and PET (PiB, FDG, tau).
+"""
+import argparse
+import json
+import os
+import re
+import shutil
+import sys
+from collections import defaultdict
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+# AIBL visit name -> BIDS session label mapping
+AIBL_SESSION_MAP = {
+    "screening": "screening",
+    "baseline": "baseline",
+    "18month": "18month",
+    "18_month": "18month",
+    "18-month": "18month",
+    "36month": "36month",
+    "36_month": "36month",
+    "36-month": "36month",
+    "54month": "54month",
+    "54_month": "54month",
+    "54-month": "54month",
+    "72month": "72month",
+    "72_month": "72month",
+    "72-month": "72month",
+}
+
+# Modality keywords -> BIDS modality mapping
+MODALITY_PATTERNS = [
+    (re.compile(r"T1w|T1|mprage|MPRAGE|SPGR", re.IGNORECASE), "T1w", "anat"),
+    (re.compile(r"PET.*PiB|PiB.*PET|pib", re.IGNORECASE), "pet", "pet"),
+    (re.compile(r"PET.*FDG|FDG.*PET|fdg", re.IGNORECASE), "pet", "pet"),
+    (re.compile(r"PET.*tau|tau.*PET|18F.*AV.*1451|flortaucipir", re.IGNORECASE), "pet", "pet"),
+    (re.compile(r"PET|pet", re.IGNORECASE), "pet", "pet"),
+]
+
+SIDECAR_EXTENSIONS = [".json", ".bval", ".bvec", ".tsv"]
+
+
+def normalize_subject_id(raw_id: str) -> str:
+    """Convert AIBL subject ID to BIDS-compatible label.
+
+    002_S_0295 -> sub-002S0295
+    """
+    clean = raw_id.strip()
+    if clean.startswith("sub-"):
+        clean = clean[4:]
+    # Remove underscores and non-alphanumeric characters
+    clean = re.sub(r"[^a-zA-Z0-9]", "", clean)
+    return f"sub-{clean}"
+
+
+def normalize_session(visit_name: str) -> str:
+    """Convert AIBL visit name to BIDS session label."""
+    visit_name = visit_name.strip().lower()
+    if visit_name.startswith("ses-"):
+        visit_name = visit_name[4:]
+
+    # Direct match
+    if visit_name in AIBL_SESSION_MAP:
+        return f"ses-{AIBL_SESSION_MAP[visit_name]}"
+
+    # Fuzzy match
+    for key, val in AIBL_SESSION_MAP.items():
+        if key in visit_name or visit_name in key:
+            return f"ses-{val}"
+
+    # Fallback: sanitize
+    clean = re.sub(r"[^a-zA-Z0-9]", "", visit_name)
+    return f"ses-{clean}"
+
+
+def detect_pet_tracer(filename: str) -> str:
+    """Detect PET tracer from filename."""
+    fname = filename.lower()
+    if "pib" in fname:
+        return "PiB"
+    if "fdg" in fname:
+        return "FDG"
+    if "tau" in fname or "av1451" in fname or "flortaucipir" in fname:
+        return "tau"
+    return "unknown"
+
+
+def detect_modality(filename: str) -> Optional[Tuple[str, str, str]]:
+    """Detect BIDS modality suffix and folder from filename.
+
+    Returns (bids_suffix, bids_folder, tracer) or None.
+    """
+    for pattern, suffix, folder in MODALITY_PATTERNS:
+        if pattern.search(filename):
+            if folder == "pet":
+                tracer = detect_pet_tracer(filename)
+                return (suffix, folder, tracer)
+            return (suffix, folder, "")
+    return None
+
+
+def find_nifti_files(directory: Path) -> List[Path]:
+    """Find all NIfTI files in a directory."""
+    results = []
+    for f in directory.rglob("*"):
+        if f.is_file() and (f.name.endswith(".nii") or f.name.endswith(".nii.gz")):
+            results.append(f)
+    return results
+
+
+def copy_with_sidecars(src_nifti: Path, dst_dir: Path, dst_stem: str) -> List[Path]:
+    """Copy NIfTI file and its sidecar files to destination."""
+    dst_dir.mkdir(parents=True, exist_ok=True)
+    copied = []
+
+    ext = ".nii.gz" if src_nifti.name.endswith(".nii.gz") else ".nii"
+    dst_nifti = dst_dir / f"{dst_stem}{ext}"
+    if not dst_nifti.exists():
+        shutil.copy2(str(src_nifti), str(dst_nifti))
+    copied.append(dst_nifti)
+
+    src_stem = src_nifti.name
+    if src_stem.endswith(".nii.gz"):
+        src_stem = src_stem[:-7]
+    elif src_stem.endswith(".nii"):
+        src_stem = src_stem[:-4]
+
+    for sidecar_ext in SIDECAR_EXTENSIONS:
+        src_sidecar = src_nifti.parent / f"{src_stem}{sidecar_ext}"
+        if src_sidecar.exists():
+            dst_sidecar = dst_dir / f"{dst_stem}{sidecar_ext}"
+            if not dst_sidecar.exists():
+                shutil.copy2(str(src_sidecar), str(dst_sidecar))
+            copied.append(dst_sidecar)
+
+    return copied
+
+
+def write_dataset_description(bids_root: Path) -> None:
+    """Write BIDS dataset_description.json."""
+    desc = {
+        "Name": "AIBL (Australian Imaging, Biomarkers and Lifestyle)",
+        "BIDSVersion": "1.8.0",
+        "DatasetType": "raw",
+        "GeneratedBy": [
+            {
+                "Name": "NeuroClaw aibl-skill",
+                "Description": "AIBL raw data reorganized to BIDS structure",
+                "Version": "1.0.0",
+            }
+        ],
+    }
+    desc_path = bids_root / "dataset_description.json"
+    with open(desc_path, "w", encoding="utf-8") as f:
+        json.dump(desc, f, indent=2, ensure_ascii=False)
+    print(f"[OK] Wrote {desc_path}")
+
+
+def write_participants_tsv(bids_root: Path, subject_ids: List[str]) -> None:
+    """Write BIDS participants.tsv header."""
+    tsv_path = bids_root / "participants.tsv"
+    with open(tsv_path, "w", encoding="utf-8") as f:
+        f.write("participant_id\n")
+        for sid in sorted(set(subject_ids)):
+            f.write(f"{sid}\n")
+    print(f"[OK] Wrote {tsv_path} ({len(set(subject_ids))} participants)")
+
+
+def detect_subject_layout(input_dir: Path) -> str:
+    """Detect whether input follows flat or nested AIBL layout.
+
+    Returns 'flat' if subject dirs are direct children,
+    'nested' if organized as subject/visit/modality.
+    """
+    children = list(input_dir.iterdir())
+    if not children:
+        return "flat"
+
+    first_child = children[0]
+    if first_child.is_dir():
+        sub_children = list(first_child.iterdir())
+        if sub_children:
+            # Check if children look like visit names
+            for sc in sub_children:
+                if sc.is_dir() and any(
+                    k in sc.name.lower() for k in ["screening", "baseline", "month", "visit"]
+                ):
+                    return "nested"
+            # Check if children look like modality folders
+            for sc in sub_children:
+                if sc.is_dir() and detect_modality(sc.name):
+                    return "flat"
+
+    return "flat"
+
+
+def process_flat_layout(
+    input_dir: Path,
+    bids_root: Path,
+    participants: List[str],
+    dry_run: bool = False,
+) -> Tuple[int, int, int]:
+    """Process flat AIBL layout: subject/modality/files."""
+    converted = 0
+    skipped = 0
+    failed = 0
+
+    subject_dirs = sorted(
+        [p for p in input_dir.iterdir() if p.is_dir() and not p.name.startswith(".")]
+    )
+
+    for subject_dir in subject_dirs:
+        sub_label = normalize_subject_id(subject_dir.name)
+        participants.append(sub_label)
+
+        for modality_dir in sorted(subject_dir.iterdir()):
+            if not modality_dir.is_dir():
+                continue
+
+            nifti_files = find_nifti_files(modality_dir)
+            for nifti in nifti_files:
+                result = detect_modality(nifti.name)
+                if result is None:
+                    result = detect_modality(modality_dir.name)
+                if result is None:
+                    print(f"[WARN] {sub_label} | cannot detect modality: {nifti.name}")
+                    failed += 1
+                    continue
+
+                bids_suffix, bids_folder, tracer = result
+
+                ses_label = "ses-baseline"
+
+                if bids_folder == "pet":
+                    dst_stem = f"{sub_label}_{ses_label}_trc-{tracer}_{bids_suffix}"
+                else:
+                    dst_stem = f"{sub_label}_{ses_label}_{bids_suffix}"
+
+                bids_sub_dir = bids_root / sub_label / ses_label / bids_folder
+
+                ext = ".nii.gz" if nifti.name.endswith(".nii.gz") else ".nii"
+                if (bids_sub_dir / f"{dst_stem}{ext}").exists():
+                    skipped += 1
+                    continue
+
+                if dry_run:
+                    print(f"[DRY] {sub_label}/{ses_label}/{bids_folder}/{dst_stem}")
+                    converted += 1
+                else:
+                    copy_with_sidecars(nifti, bids_sub_dir, dst_stem)
+                    print(f"[OK] {sub_label}/{ses_label}/{bids_folder}/{dst_stem}")
+                    converted += 1
+
+    return converted, skipped, failed
+
+
+def process_nested_layout(
+    input_dir: Path,
+    bids_root: Path,
+    participants: List[str],
+    dry_run: bool = False,
+) -> Tuple[int, int, int]:
+    """Process nested AIBL layout: subject/visit/modality/files."""
+    converted = 0
+    skipped = 0
+    failed = 0
+
+    subject_dirs = sorted(
+        [p for p in input_dir.iterdir() if p.is_dir() and not p.name.startswith(".")]
+    )
+
+    for subject_dir in subject_dirs:
+        sub_label = normalize_subject_id(subject_dir.name)
+        participants.append(sub_label)
+
+        for visit_dir in sorted(subject_dir.iterdir()):
+            if not visit_dir.is_dir():
+                continue
+
+            ses_label = normalize_session(visit_dir.name)
+
+            for modality_dir in sorted(visit_dir.iterdir()):
+                if not modality_dir.is_dir():
+                    continue
+
+                nifti_files = find_nifti_files(modality_dir)
+                if not nifti_files:
+                    nifti_files = find_nifti_files(visit_dir)
+                    nifti_files = [f for f in nifti_files if f.parent == modality_dir]
+
+                for nifti in nifti_files:
+                    result = detect_modality(nifti.name)
+                    if result is None:
+                        result = detect_modality(modality_dir.name)
+                    if result is None:
+                        print(
+                            f"[WARN] {sub_label}/{ses_label} | cannot detect modality: {nifti.name}"
+                        )
+                        failed += 1
+                        continue
+
+                    bids_suffix, bids_folder, tracer = result
+
+                    if bids_folder == "pet":
+                        dst_stem = f"{sub_label}_{ses_label}_trc-{tracer}_{bids_suffix}"
+                    else:
+                        dst_stem = f"{sub_label}_{ses_label}_{bids_suffix}"
+
+                    bids_sub_dir = bids_root / sub_label / ses_label / bids_folder
+
+                    ext = ".nii.gz" if nifti.name.endswith(".nii.gz") else ".nii"
+                    if (bids_sub_dir / f"{dst_stem}{ext}").exists():
+                        skipped += 1
+                        continue
+
+                    if dry_run:
+                        print(
+                            f"[DRY] {sub_label}/{ses_label}/{bids_folder}/{dst_stem}"
+                        )
+                        converted += 1
+                    else:
+                        copy_with_sidecars(nifti, bids_sub_dir, dst_stem)
+                        print(
+                            f"[OK] {sub_label}/{ses_label}/{bids_folder}/{dst_stem}"
+                        )
+                        converted += 1
+
+    return converted, skipped, failed
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Reorganize AIBL raw data into BIDS-compliant structure."
+    )
+    parser.add_argument(
+        "--input",
+        required=True,
+        help="Path to AIBL raw data directory",
+    )
+    parser.add_argument(
+        "--output",
+        required=True,
+        help="Path to output BIDS directory",
+    )
+    parser.add_argument(
+        "--participants-file",
+        help="Optional: path to AIBL phenotype file for participant metadata",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Preview without copying files",
+    )
+    args = parser.parse_args()
+
+    input_dir = Path(args.input).resolve()
+    output_dir = Path(args.output).resolve()
+
+    if not input_dir.exists() or not input_dir.is_dir():
+        print(f"Input directory does not exist: {input_dir}", file=sys.stderr)
+        return 1
+
+    output_dir.mkdir(parents=True, exist_ok=True)
+    participants: List[str] = []
+
+    layout = detect_subject_layout(input_dir)
+    print(f"Detected layout: {layout}")
+    print(f"Input:  {input_dir}")
+    print(f"Output: {output_dir}")
+    print(f"{'[DRY RUN] ' if args.dry_run else ''}Starting reorganization...\n")
+
+    if layout == "nested":
+        converted, skipped, failed = process_nested_layout(
+            input_dir, output_dir, participants, args.dry_run
+        )
+    else:
+        converted, skipped, failed = process_flat_layout(
+            input_dir, output_dir, participants, args.dry_run
+        )
+
+    if not args.dry_run and converted > 0:
+        write_dataset_description(output_dir)
+        write_participants_tsv(output_dir, participants)
+
+    print(f"\nDone. Converted={converted}, Skipped={skipped}, Failed={failed}")
+    return 0 if failed == 0 else 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/06_fMRI_Neuroimaging/aomic-skill/SKILL.md

@@ -0,0 +1,292 @@
+---
+name: aomic-skill
+description: "Use this skill whenever the user wants an end-to-end workflow for the AOMIC (Amsterdam Open MRI Collection) dataset, including data access, BIDS organization, and multimodal processing of sMRI, rs-fMRI, and task-fMRI. Triggers include: 'AOMIC', 'AOMIC data', 'process AOMIC', 'AOMIC fMRI', 'AOMIC resting state', or any request to run the AOMIC multimodal pipeline. This is the NeuroClaw dataset-orchestration layer for AOMIC."
+license: MIT License (NeuroClaw custom skill - freely modifiable within the project)
+layer: subagent
+skill_type: dataset
+dependencies:
+  - smri-skill
+  - fmri-skill
+  - bids-organizer
+  - claw-shell
+---
+# AOMIC Skill (Dataset-Orchestration Layer)
+
+## Overview
+`aomic-skill` is the NeuroClaw orchestration skill for the **AOMIC (Amsterdam Open MRI Collection)** dataset.
+
+It coordinates a fixed three-phase workflow:
+1. Guide AOMIC data access and download from OpenNeuro / the AOMIC repository.
+2. Prepare and validate BIDS-style data organization for downstream processing.
+3. Delegate modality pipelines to `smri-skill` and `fmri-skill`.
+
+It also provides **phenotype extraction** and **QC integration** paths:
+- Extract and merge AOMIC phenotype tables (Big Five personality traits, fluid intelligence, demographics).
+- Generate per-subject QC summaries with exclusion lists.
+
+This skill follows NeuroClaw hierarchy:
+- Defines **WHAT to do**, not low-level implementation details.
+- Does **not** execute direct shell commands itself.
+- Delegates all execution via `claw-shell` to base/tool skills.
+
+**Research use only.**
+
+---
+
+## Download Stage (Mandatory First Step)
+
+### Source
+AOMIC data is publicly available:
+- Website: https://nilab-uva.github.io/AOMIC.github.io/
+- OpenNeuro derivatives: https://openneuro.org/
+- Data access: direct download, no authentication required for most components
+
+### Supported AOMIC Sub-datasets
+- **AOMIC-ID1000**: ~1,000 participants with T1w, rs-fMRI, task-fMRI (emotion, gambling, motor, language tasks), Big Five personality, Raven's progressive matrices
+- **AOMIC-PIOP1**: T1w, rs-fMRI, task-fMRI (emotion, working memory), personality and cognitive data
+- **AOMIC-PIOP2**: T1w, rs-fMRI, task-fMRI (emotion, working memory), personality and cognitive data
+
+### Delegation Rules for Download
+- Environment/setup checks: `dependency-planner` + `conda-env-manager`
+- Download tool installation and execution: `claw-shell`
+- Optional raw-data organization to BIDS-style staging: `bids-organizer`
+
+### Download Inputs to Confirm in Plan
+- Target sub-dataset (ID1000, PIOP1, PIOP2, or all)
+- Subject list scope (full cohort or custom subset)
+- Destination directory with sufficient disk space
+
+---
+
+## Narrow Path: AOMIC Raw Data -> BIDS Staging
+
+Use this path when the task only asks to reorganize raw AOMIC files into a BIDS-style dataset and does not require preprocessing, ROI extraction, phenotype merging, or downstream analysis.
+
+### When this narrow path should dominate
+- The task objective is limited to AOMIC data staging, BIDS renaming, sidecar handling, and dataset-level metadata.
+- Inputs are already local AOMIC files or AOMIC-style subject folders.
+- The required deliverable is a direct staging script or command sequence, not a plan for preprocessing or downstream analysis.
+
+### Narrow-path contract
+- Do not widen the solution to preprocessing, ROI extraction, phenotype merging, or downstream analysis unless the task explicitly requires them.
+- Treat this as a direct file-organization problem: scan AOMIC subject layout, normalize subject labels, map modalities to BIDS names, copy or symlink files plus matching sidecars, and write dataset-level metadata plus staging logs.
+- If the task is benchmark-style, prefer a single direct end-to-end staging script over a confirmation-first orchestration plan.
+
+### Expected narrow-path behavior
+1. Detect AOMIC subject IDs (e.g., `sub-0001`) and validate BIDS compliance.
+2. Detect session/task information from directory structure and filenames.
+3. Route modalities:
+   - T1w -> `anat/*_T1w`
+   - rs-fMRI -> `func/*_task-rest_bold`
+   - task-fMRI -> `func/*_task-<taskname>_bold` (emotion, gambling, motor, language, workingmemory)
+4. Preserve or rename matching JSON sidecars and physiological recordings when available.
+5. Emit dataset-level outputs such as `dataset_description.json`, `participants.tsv`, `README`, and a manifest or skipped-file report.
+
+---
+
+## Core Workflow (Never Bypassed)
+1. Identify user target: full AOMIC processing, specific sub-dataset, phenotype extraction, or BIDS staging only.
+2. Generate a numbered plan with tools, outputs, runtime, storage, and risks.
+3. Wait for explicit confirmation (`YES` / `execute` / `proceed`).
+4. On confirmation, run download stage first (if needed).
+5. After download success, run BIDS preparation using `scripts/reorganize_aomic.py`.
+6. Delegate sequentially or in parallel to:
+   - `smri-skill` for structural MRI (T1w)
+   - `fmri-skill` for functional MRI (rs-fMRI, task-fMRI)
+7. If phenotype extraction is requested, run `scripts/extract_aomic_phenotype.py`.
+8. If QC summary is requested, run `scripts/aomic_qc_summary.py`.
+9. Save outputs into an AOMIC-centered structure under `aomic_output/`.
+
+---
+
+## Input Layout (Example)
+
+Subject `sub-0001` (T1w + rs-fMRI + task-fMRI):
+
+```
+aomic_raw/
+  sub-0001/
+    anat/
+      sub-0001_T1w.nii.gz
+      sub-0001_T1w.json
+    func/
+      sub-0001_task-rest_bold.nii.gz
+      sub-0001_task-rest_bold.json
+      sub-0001_task-emotion_bold.nii.gz
+      sub-0001_task-emotion_bold.json
+      sub-0001_task-gambling_bold.nii.gz
+      sub-0001_task-gambling_bold.json
+      sub-0001_task-motor_bold.nii.gz
+      sub-0001_task-motor_bold.json
+      sub-0001_task-language_bold.nii.gz
+      sub-0001_task-language_bold.json
+  phenotype/
+    big_five.csv
+    ravens.csv
+    demographics.csv
+```
+
+---
+
+## BIDS Preparation
+
+### Script: `scripts/reorganize_aomic.py`
+
+Validates and reorganizes AOMIC data into BIDS-compliant layout.
+
+```bash
+python skills/aomic-skill/scripts/reorganize_aomic.py \
+  --input /path/to/aomic_raw \
+  --output /path/to/aomic_bids \
+  --participants-file /path/to/aomic_raw/phenotype/demographics.csv
+```
+
+Features:
+- Subject ID validation (BIDS-compliant `sub-XXXX` format)
+- Session/task detection from directory structure and filenames
+- Modality routing: T1w, rs-fMRI, task-fMRI (emotion, gambling, motor, language, workingmemory)
+- Sidecar JSON preservation and validation
+- Physiological recording file handling
+- `dataset_description.json` and `participants.tsv` generation
+- Dry-run mode: `--dry-run` to preview without copying
+
+---
+
+## Modality Processing Delegation
+
+After BIDS staging completes, `aomic-skill` delegates by modality:
+
+| Modality | Delegated skill | Typical tasks | Main outputs |
+|---|---|---|---|
+| sMRI (T1w) | `smri-skill` | brain extraction, tissue segmentation, cortical reconstruction, ROI morphometry | `smri_output/` derivatives and stats |
+| fMRI (rs-fMRI/task-fMRI) | `fmri-skill` | preprocessing, denoising, ROI time series, connectivity, task GLM | `fmri_output/` derivatives, timeseries, connectivity |
+
+### Delegation Strategy
+- If user asks for full multimodal AOMIC analysis: run sMRI -> fMRI in ordered phases.
+- If user asks for one modality only: call only the corresponding modality skill.
+- Task-fMRI analysis should use task-specific event files (emotion, gambling, motor, language, workingmemory).
+
+---
+
+## Phenotype Extraction
+
+### Script: `scripts/extract_aomic_phenotype.py`
+
+Extracts and merges AOMIC phenotype tables for downstream analysis.
+
+```bash
+python skills/aomic-skill/scripts/extract_aomic_phenotype.py \
+  --phenotype-dir /path/to/aomic_raw/phenotype \
+  --output /path/to/aomic_output/phenotype/merged_phenotype.csv \
+  --columns subject_id,age,sex,openness,conscientiousness,extraversion,agreeableness,neuroticism,ravens_score \
+  --imaging-ids /path/to/aomic_output/bids/participants.tsv
+```
+
+Features:
+- Reads AOMIC phenotype CSV/TSV files (Big Five, Raven's, demographics)
+- Column selection and renaming
+- Missing value handling (filter or impute)
+- Cross-reference with imaging subject list to keep only subjects with both imaging and phenotype data
+- Outputs merged CSV ready for statistical analysis or model training
+
+---
+
+## QC Integration
+
+### Script: `scripts/aomic_qc_summary.py`
+
+Generates per-subject QC summaries and exclusion lists.
+
+```bash
+python skills/aomic-skill/scripts/aomic_qc_summary.py \
+  --fmriprep-dir /path/to/aomic_output/fmriprep \
+  --freesurfer-dir /path/to/aomic_output/smri/freesurfer \
+  --output /path/to/aomic_output/qc/qc_summary.csv \
+  --exclude-output /path/to/aomic_output/qc/exclude_list.csv \
+  --fd-threshold 0.3
+```
+
+Features:
+- Reads fMRIPrep confounds (framewise displacement, DVARS)
+- Reads FreeSurfer recon-all QC metrics
+- Structural quality assessment
+- Applies exclusion criteria: motion threshold (FD), structural quality
+- Outputs per-subject QC summary CSV and exclusion list CSV
+
+---
+
+## Recommended Output Layout
+All assets should be organized under `./aomic_output/`:
+- `aomic_output/raw/` (downloaded original AOMIC files)
+- `aomic_output/bids/` (staged BIDS data)
+- `aomic_output/smri/` (links or copies from `smri_output/`)
+- `aomic_output/fmri/` (links or copies from `fmri_output/`)
+- `aomic_output/phenotype/` (merged phenotype tables)
+- `aomic_output/qc/` (QC summaries and exclusion lists)
+- `aomic_output/logs/` (download + orchestration logs)
+
+---
+
+## Benchmark Adapter Guidance
+
+For benchmark-style prompts, do not force the full `download -> staging -> multimodal processing` orchestration when the task is only asking for local AOMIC data staging or organization.
+
+- If the task starts from raw AOMIC data already present on disk and only asks for BIDS-style staging / organization:
+  - skip the mandatory download stage
+  - do not automatically delegate to `smri-skill` or `fmri-skill`
+  - default to the narrow path `local raw AOMIC discovery -> BIDS-style staging -> minimal metadata -> validation/report`
+- In benchmark mode, do not require explicit confirmation before presenting the direct staging solution.
+- Preserve the AOMIC-centered output contract under `aomic_output/bids/` when the task is specifically a staging benchmark.
+- Only use the full multimodal orchestration and confirmation-heavy workflow when the prompt explicitly asks for download, end-to-end multimodal AOMIC processing, or post-staging structural / functional analysis.
+
+---
+
+## Safety and Execution Policy
+- No execution before explicit plan confirmation.
+- All execution must be routed via `claw-shell`.
+- Missing dependencies must be resolved by `dependency-planner` before running.
+- If download fails for partial subjects, continue batch with clear failure report and retry list.
+
+---
+
+## Important Notes and Limitations
+- AOMIC data is already in BIDS format for many components; the reorganize script primarily validates and handles edge cases.
+- AOMIC has multiple sub-datasets (ID1000, PIOP1, PIOP2) with slightly different task paradigms and phenotype measures.
+- Task-fMRI event files (.tsv) must be preserved alongside BOLD data for proper task analysis.
+- Some AOMIC components include physiological recordings (cardiac, respiration) that can be used for advanced denoising.
+- `aomic-skill` is orchestration-only; detailed preprocessing logic remains in `smri-skill` and `fmri-skill`.
+
+---
+
+## When to Call This Skill
+- User asks for end-to-end AOMIC workflow.
+- User asks to process AOMIC MRI data (sMRI, rs-fMRI, task-fMRI).
+- User needs BIDS staging for raw AOMIC files.
+- User asks to extract and merge AOMIC phenotype tables (personality, cognition, demographics).
+- User asks for AOMIC-specific QC summaries and exclusion lists.
+- User needs a single entry point for AOMIC multimodal orchestration.
+
+---
+
+## Complementary / Related Skills
+- `smri-skill`
+- `fmri-skill`
+- `bids-organizer`
+- `fmriprep-tool`
+- `freesurfer-tool`
+- `nilearn-tool`
+- `brain-visualization`
+- `dependency-planner`
+- `conda-env-manager`
+- `claw-shell`
+
+---
+
+## Reference
+- AOMIC: https://nilab-uva.github.io/AOMIC.github.io/
+- OpenNeuro: https://openneuro.org/
+- BIDS spec: https://bids.neuroimaging.io/
+
+Created At: 2026-05-06 11:24 HKT
+Last Updated At: 2026-05-06 11:24 HKT
+Author: chengwang96