@brainpilot/skills 0.0.6 → 0.0.8

package/skills/06_fMRI_Neuroimaging/rest-mneta-mdd-skill/scripts/validate_rest_mdd.py

@@ -0,0 +1,103 @@
+#!/usr/bin/env python3
+"""Validate REST-meta-MDD BIDS structure and generate compliance report.
+
+Checks directory structure, site identification, and diagnostic group labeling.
+"""
+import argparse
+import csv
+import sys
+from pathlib import Path
+from typing import Dict, List
+
+
+def validate_subject(subject_dir: Path) -> Dict[str, any]:
+    report = {
+        "subject": subject_dir.name,
+        "rs_fMRI_present": False,
+        "anat_present": False,
+        "site_id": "",
+        "n_runs": 0,
+        "missing_files": [],
+        "warnings": [],
+    }
+
+    # Extract site from subject ID if encoded (e.g., sub-Site01_001)
+    parts = subject_dir.name.replace("sub-", "").split("_")
+    if len(parts) > 1:
+        report["site_id"] = parts[0]
+
+    # Check func
+    func_dir = subject_dir / "func"
+    if func_dir.exists():
+        rest_bold = list(func_dir.glob("*_task-rest_bold.nii.gz"))
+        report["rs_fMRI_present"] = len(rest_bold) > 0
+        report["n_runs"] = len(rest_bold)
+        if not rest_bold:
+            report["missing_files"].append("func/*_task-rest_bold.nii.gz")
+    else:
+        report["missing_files"].append("func/")
+
+    # Check anat (optional)
+    anat_dir = subject_dir / "anat"
+    if anat_dir.exists():
+        t1w_files = list(anat_dir.glob("*_T1w.nii.gz"))
+        report["anat_present"] = len(t1w_files) > 0
+    else:
+        report["warnings"].append("No anat directory (optional)")
+
+    return report
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Validate REST-meta-MDD BIDS structure.")
+    parser.add_argument("--input", required=True)
+    parser.add_argument("--output", required=True)
+    args = parser.parse_args()
+
+    input_dir = Path(args.input).resolve()
+    if not input_dir.exists():
+        print(f"Input directory not found: {input_dir}", file=sys.stderr)
+        return 1
+
+    subjects = sorted([d for d in input_dir.glob("sub-*") if d.is_dir()])
+    print(f"Found {len(subjects)} subjects in {input_dir}")
+
+    if not subjects:
+        print("[ERROR] No subjects found.", file=sys.stderr)
+        return 1
+
+    results = []
+    for sub_dir in subjects:
+        report = validate_subject(sub_dir)
+        results.append(report)
+
+    output_path = Path(args.output).resolve()
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    fieldnames = [
+        "subject", "rs_fMRI_present", "anat_present", "site_id",
+        "n_runs", "missing_files", "warnings",
+    ]
+    with open(output_path, "w", newline="", encoding="utf-8") as f:
+        writer = csv.DictWriter(f, fieldnames=fieldnames)
+        writer.writeheader()
+        for r in results:
+            r["missing_files"] = "; ".join(r["missing_files"])
+            r["warnings"] = "; ".join(r["warnings"])
+            writer.writerow(r)
+
+    sites = set(r["site_id"] for r in results if r["site_id"])
+    print(f"\nValidation Summary:")
+    print(f"  Total subjects: {len(results)}")
+    print(f"  With rs-fMRI: {sum(1 for r in results if r['rs_fMRI_present'])}")
+    print(f"  With T1w: {sum(1 for r in results if r['anat_present'])}")
+    print(f"  Sites detected: {len(sites)}")
+    if sites:
+        print(f"  Site IDs: {', '.join(sorted(sites)[:10])}{'...' if len(sites) > 10 else ''}")
+    print(f"  Output: {output_path}")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1,302 @@
+---
+name: smri-skill
+description: "Use this skill whenever the user wants to process structural MRI (sMRI) such as T1w/T2w/FLAIR for brain extraction, bias correction, tissue segmentation (GM/WM/CSF), registration to MNI, cortical/subcortical parcellation, cortical thickness/volumetry (FreeSurfer), HCP-style structural preprocessing, WMH lesion segmentation (FLAIR+T1), ROI-wise feature extraction, or converting results back to DICOM. This is the NeuroClaw modality-layer interface: it plans WHAT to do and delegates execution to tool skills."
+license: MIT License (NeuroClaw custom skill – freely modifiable within the project)
+layer: subagent
+skill_type: modality
+dependencies:
+  - freesurfer-tool
+  - fsl-tool
+  - wmh-segmentation
+  - nii2dcm
+  - claw-shell
+complementary_skills:
+  - fmri-skill
+  - dwi-skill
+---
+# sMRI Skill (Modality Layer)
+
+## Overview
+`smri-skill` is the NeuroClaw **modality-layer** interface skill responsible for **structural MRI** processing (T1w/T2w/FLAIR) and feature extraction.
+
+It strictly follows NeuroClaw hierarchical design principles:
+- This skill describes **WHAT needs to be done** and **which tool skill to delegate to**.
+- It contains **no implementation code** and **no direct shell commands**.
+- All concrete execution is delegated to tool skills and routed through `claw-shell`.
+
+**Core workflow (never bypassed):**
+1. Identify input type (DICOM / NIfTI / BIDS), modalities available (T1w only vs T1w+T2w vs T1w+FLAIR).
+2. Generate a **numbered execution plan** (steps, tools, outputs, runtime, risks).
+3. Present the plan and wait for explicit user confirmation (“YES” / “execute” / “proceed”).
+4. On confirmation, delegate each step via `claw-shell`.
+5. Save outputs into a clean folder structure (`smri_output/`).
+
+## Benchmark-Facing Default Mainline
+
+For benchmark-style structural MRI tasks, start from the narrowest valid anatomical mainline and only add optional branches when the prompt or inputs explicitly require them.
+
+- If the task is full structural MRI processing with no explicit T2w or FLAIR dependency:
+  - Default to `DICOM -> NIfTI if needed -> T1w mainline -> FreeSurfer recon-all -> feature/stat table export`.
+  - Keep T2w, FLAIR, WMH, HCP structural, and DICOM re-export as optional branches, not default branches.
+- If the task is only DICOM conversion:
+  - Delegate to `dcm2nii` and stop there.
+- If the task asks for quick volumetric preprocessing only:
+  - Prefer the `fsl-tool` route rather than mixing FreeSurfer and HCP options in the mainline.
+- If optional modalities or branches are missing:
+  - Mark them as skipped or blocked.
+  - Do not widen the task into unrelated structural subpipelines.
+
+Avoid listing unrelated modality-adjacent tools in the primary plan for T1-only structural benchmarks.
+
+**Research use only.**
+
+---
+
+## Quick Reference (Common sMRI Tasks → Delegation Map)
+
+| Task | What needs to be done (high level) | Delegate to which skill | Expected outputs |
+|---|---|---|---|
+| DICOM → NIfTI | Convert DICOM series to NIfTI (+ JSON) | `dcm2nii` | `*_T1w.nii.gz`, `*_T2w.nii.gz`, `*_FLAIR.nii.gz`, `*.json` |
+| Organize to BIDS | Create valid BIDS layout (anat/) | `bids-organizer` | `bids/sub-*/anat/sub-*_T1w.nii.gz` etc. |
+| Fast structural preprocessing | Brain extraction, bias correction, tissue segmentation, MNI registration | `fsl-tool` (`fsl_anat`, BET/FAST/FLIRT/FNIRT) | brain mask, tissue maps, transforms, QC |
+| FreeSurfer Autorecon1 (volumetric preprocessing) | Image conversion, motion correction, intensity normalization, registration to Talairach, bias correction, skull stripping | `freesurfer-tool` (`recon-all -autorecon1`) | `orig.mgz`, `T1.mgz`, `brainmask.mgz`, `transforms/talairach.xfm` |
+| FreeSurfer Autorecon2 (subcortical segmentation & surface extraction) | Tissue classification, white matter segmentation, surface tessellation, topology repair, white matter & pial surface generation | `freesurfer-tool` (`recon-all -autorecon2`) | `?h.orig`, `?h.white`, `?h.pial`, `aseg.mgz`, `wm.mgz`, surface QC |
+| FreeSurfer Autorecon3 (spherical registration & parcellation) | Spherical surface registration, cortical parcellation (Desikan-Killiany, Destrieux, DKT), anatomical statistics extraction, Brodmann area mapping | `freesurfer-tool` (`recon-all -autorecon3`) | `?h.sphere.reg`, `?h.aparc.annot`, `stats/?h.aparc.stats`, ROI morphology tables |
+| Full FreeSurfer pipeline (all 3 stages) | Complete T1/T2 preprocessing with optional T2-pial refinement | `freesurfer-tool` (`recon-all -all -T2pial`) | Full FreeSurfer subject directory with surfaces, atlases, stats |
+| Surface-based morphometry (quick) | Cortical surfaces, parcellation, thickness, aseg/aparc stats (simplified) | `freesurfer-tool` | FreeSurfer subject dir, stats tables |
+| HCP-grade structural pipeline | PreFreeSurfer → FreeSurfer → PostFreeSurfer | `hcppipeline-tool` | HCP-style derivatives, surfaces, QC |
+| BIDS anatomical derivatives (standardized) | Run BIDS-App anatomical-only workflow | `fmriprep-tool` (`--anat-only`) | BIDS derivatives + QC report |
+| WMH lesion segmentation | Segment WMH from FLAIR+T1 | `wmh-segmentation` (+ `docker-env-manager` if Docker ops needed) | WMH mask NIfTI + run log |
+| ROI-wise feature extraction | Extract ROI stats from derived maps (GM prob, WMH mask, thickness maps in NIfTI, cortical thickness, surface-based stats) | `nilearn-tool` (or `fsl-tool` `fslstats`, FreeSurfer `mris_anatomical_stats`) | `roi_stats_*.csv`, morphology tables |
+| Export results to DICOM | Convert final NIfTI outputs back to DICOM series | `nii2dcm` | DICOM series for PACS/viewers |
+
+---
+
+## Recommended Strategy (Decision Logic)
+- If the goal is **quick brain extraction + tissue segmentation + MNI alignment** (fast baseline, ~6 minutes):
+  - Prefer `fsl-tool` (`fsl_anat`).
+  - Best for: quick QC, preprocessing, multi-subject batches.
+
+- If the goal is **cortical thickness / surface parcellation / aseg-aparc volumetry** (detailed surface morphometry):
+  - Prefer `freesurfer-tool` (`recon-all`) with **3-stage execution** (recommended for flexibility):
+    - **Stage 1: `-autorecon1`** (volumetric preprocessing, ~15-30 min)
+      - Produces: intensity-normalized brain image (`T1.mgz`), Talairach registration (`talairach.xfm`), brain mask (`brainmask.mgz`).
+      - Use when: you need just preprocessing, quality control, or pial surface refinement before running surface extraction.
+    - **Stage 2: `-autorecon2`** (white matter segmentation & surface extraction, ~30-60 min)
+      - Produces: white matter mask (`wm.mgz`), initial surfaces (`?h.orig`, `?h.white`, `?h.pial`), segmentation (`aseg.mgz`).
+      - Use when: you need cortical surfaces for thickness measurement, but haven't registered to standard space yet.
+    - **Stage 3: `-autorecon3`** (spherical registration & parcellation, ~15-30 min)
+      - Produces: registered sphere (`?h.sphere.reg`), cortical parcellations (`?h.aparc.annot`, `?h.aparc.a2009s.annot`, `?h.aparc.DKTatlas.annot`), morphometric statistics (`stats/?h.aparc.stats`).
+      - Use when: you need full atlas-based ROI labels, cortical thickness maps, and anatomical statistics for group-level analysis.
+  - **Quick execution**: Run `recon-all -all -T2pial` (if T2 available, ~2-3 hours total) for immediate full results.
+  - Best for: surface-based group analysis, cortical thickness studies, clinico-anatomical correlation.
+
+- If the goal is **highest-quality, HCP-style surfaces and multimodal alignment**:
+  - Prefer `hcppipeline-tool` (structural stages).
+  - Best for: HCP datasets, publication-grade preprocessing, maximal anatomical detail.
+
+- If the dataset is already **BIDS** and you want **standardized derivatives + QC** (and future fMRI integration):
+  - Prefer `fmriprep-tool --anat-only` (or full fMRIPrep if fMRI exists).
+  - Best for: reproducible BIDS-compliant preprocessing, multi-modal (fMRI-ready), open science.
+
+- If the goal is **WMH lesion segmentation** (vascular burden, aging, MS-like WM lesions):
+  - Use `wmh-segmentation` (Docker-based); ensure Docker readiness via `docker-env-manager` if needed.
+  - Best for: FLAIR+T1 pathological lesion mapping.
+
+- If the goal is **ROI-level tables** from any NIfTI scalar map (thickness, volume, WMH count, etc.):
+  - Use `nilearn-tool` to generate reproducible CSV feature tables.
+  - Best for: downstream statistical analysis, machine learning pipelines.
+
+---
+
+## FreeSurfer Setup & Prerequisites (Ubuntu)
+
+### System Dependencies & Installation
+For Ubuntu 22.04+ systems, `freesurfer-tool` must ensure:
+
+#### 1. System-level Dependencies
+```bash
+sudo apt-get update
+sudo apt-get install -y \
+  tcsh bc perl tar libgomp1 build-essential \
+  wget vim-common libxmu-dev libxi-dev libxt-dev \
+  libx11-dev libglu1-mesa-dev libjpeg62-dev
+```
+
+#### 2. FreeSurfer Installation & License
+- **Download** FreeSurfer 7.4.1 (or newer): Install to `/usr/local/freesurfer/`
+- **License file**: Obtain from https://surfer.nmr.mgh.harvard.edu/fswiki/License → place at `/usr/local/freesurfer/license.txt`
+
+#### 3. Environment Configuration (in shell profile, e.g., `.bashrc`)
+```bash
+export FREESURFER_HOME=/usr/local/freesurfer
+export SUBJECTS_DIR=/path/to/your/freesurfer/subjects
+source $FREESURFER_HOME/SetUpFreeSurfer.sh
+```
+
+### When to Use Each Stage
+
+| Stage | Command | Input | Output | Runtime | Use Case |
+|---|---|---|---|---|---|
+| **Autorecon1** | `recon-all -autorecon1 -i <T1.nii.gz> -subjid <sub>` | T1w NIfTI (mandatory) | `orig.mgz`, `T1.mgz`, `brainmask.mgz`, Talairach xfm | 15–30 min | Preprocessing only, QC checkpoints, T2-pial setup |
+| **Autorecon2** | `recon-all -autorecon2 -subjid <sub>` | (uses autorecon1 outputs) | `wm.mgz`, surfaces (`?h.orig`, `?h.white`, `?h.pial`) | 30–60 min | Cortical surface extraction, thickness measurement |
+| **Autorecon3** | `recon-all -autorecon3 -subjid <sub>` | (uses autorecon2 outputs) | `?h.sphere.reg`, `?h.aparc.annot`, stats tables | 15–30 min | Atlas registration, ROI labels, group analysis ready |
+| **All (1-click)** | `recon-all -all -T2pial -i <T1.nii.gz> -T2 <T2.nii.gz> -subjid <sub>` | T1w (required), T2w (optional but improves pial surface) | Complete subject dir | 2–3 hours | Full pipeline; T2-pial refines pial boundary |
+
+---
+
+## Standard Output Layout (Recommended)
+All outputs must be written under `./smri_output/`:
+- `smri_output/nifti/`        (converted inputs if needed: `*_T1w.nii.gz`, `*_T2w.nii.gz`)
+- `smri_output/bids/`         (optional staging BIDS: `bids/sub-*/anat/`)
+- `smri_output/fsl_anat/`     (FSL structural outputs: brain mask, tissue maps, transforms)
+- `smri_output/freesurfer/`   (FreeSurfer SUBJECTS_DIR structure)
+  - `freesurfer/sub-01/mri/`
+    - `orig.mgz`, `T1.mgz`, `T2.mgz` (if T2 available)
+    - `brainmask.mgz`, `wm.mgz`, `norm.mgz`
+    - `aseg.mgz`, `aparc+aseg.mgz`, `wmparc.mgz` (after autorecon2+3)
+    - `transforms/talairach.xfm`, `cc_up.lta`, etc.
+  - `freesurfer/sub-01/surf/`
+    - `?h.orig`, `?h.white`, `?h.pial` (surfaces)
+    - `?h.sphere.reg` (registered sphere, after autorecon3)
+    - `?h.inflated`, `?h.sphere` (topological surfaces)
+  - `freesurfer/sub-01/label/`
+    - `?h.aparc.annot`, `?h.aparc.a2009s.annot`, `?h.aparc.DKTatlas.annot` (parcellations, after autorecon3)
+    - `?h.cortex.label`, `?h.BA*.label` (Brodmann areas, after autorecon3)
+  - `freesurfer/sub-01/stats/`
+    - `?h.aparc.stats`, `?h.aparc.a2009s.stats`, `?h.aparc.DKTatlas.stats` (cortical morphometry)
+    - `aseg.stats`, `wmparc.stats` (subcortical volumes)
+    - `?h.curv.stats` (curvature statistics)
+- `smri_output/hcp/`          (HCP structural outputs)
+- `smri_output/fmriprep/`     (fMRIPrep derivatives/QC pointers)
+- `smri_output/wmh/`          (WMH masks + logs)
+- `smri_output/roi/`          (ROI feature CSVs extracted from FreeSurfer stats or NIfTI-based ROIs)
+- `smri_output/logs/`         (claw-shell log tags / pointers, FreeSurfer recon-all logs)
+
+---
+
+## Safety / Execution Rules (NeuroClaw)
+- **No execution without explicit user confirmation** of the full numbered plan.
+- All execution must be routed through `claw-shell`.
+- If a required dependency is missing, delegate installation planning to `dependency-planner`.
+- If Docker is required (e.g., WMH segmentation containers), coordinate via `docker-env-manager` (plan → confirm → run).
+
+---
+
+## Important Notes & Limitations
+- **Structural pipelines are long-running** (especially FreeSurfer/HCP). Always provide realistic runtime + disk estimates in the plan:
+  - Autorecon1: 15–30 min, ~2 GB disk
+  - Autorecon2: 30–60 min, ~1 GB additional
+  - Autorecon3: 15–30 min, ~500 MB additional
+  - Full pipeline (`-all`): 2–3 hours total, ~4–5 GB disk per subject
+- **FreeSurfer License**: Required and must be placed at `$FREESURFER_HOME/license.txt`. Obtain from https://surfer.nmr.mgh.harvard.edu/fswiki/License (free registration).
+- **T2-pial optimization**: Include T2w image with `-T2 <file> -T2pial` flags to refine pial surface in cortical regions with ambiguous GM/CSF boundaries. Recommended for HCP and high-resolution clinical datasets.
+- **System dependencies**: Unix/Linux-only (macOS with Rosetta2 for ARM; Windows via WSL2). Requires X11 forwarding for visualization tools.
+- **ROI extraction**: Surface-based ROIs from FreeSurfer `.annot` files can be extracted via `mris_anatomical_stats` (built-in) or converted to NIfTI via `mri_aparc2aseg` for volumetric ROI analysis.
+- **Registration outputs**: FreeSurfer surfaces (`?h.sphere.reg`) are registered to average template space; enables cross-subject statistical inference via QDEC or nilearn.
+- **This skill is for research workflows**; not for clinical decision-making.
+
+---
+
+## When to Call This Skill
+- Any request involving: T1w/T2w/FLAIR preprocessing, brain extraction, tissue segmentation, MNI registration, cortical thickness, FreeSurfer recon-all, HCP structural pipeline, WMH segmentation, or ROI-wise structural features.
+
+## Post-Execution Verification (Harness Integration)
+
+After structural MRI processing completes, this skill **automatically invokes harness-core's VerificationRunner** to validate structural derivatives:
+
+**Integrated verification checks**:
+
+```python
+from skills.harness_core import VerificationRunner, AuditLogger
+import nibabel as nib
+import numpy as np
+
+verifier = VerificationRunner(task_type="structural_mri_processing")
+
+# 1. Structural brain extraction quality
+verifier.add_check("brain_extraction_mask",
+    checker=lambda: verify_brain_mask_exists(output_dir),
+    severity="error"
+)
+
+# 2. Tissue segmentation (GM/WM/CSF) available and reasonable
+verifier.add_check("tissue_segmentation",
+    checker=lambda: verify_tissue_maps_integrity(output_dir),
+    severity="error"
+)
+
+# 3. MNI registration transforms
+verifier.add_check("mni_registration",
+    checker=lambda: verify_mni_transforms(output_dir),
+    severity="warning"
+)
+
+# 4. Cortical surface files (if FreeSurfer)
+verifier.add_check("cortical_surfaces",
+    checker=lambda: verify_freesurfer_surfaces(output_dir),
+    severity="warning"
+)
+
+# 5. No NaN/Inf in structural maps
+verifier.add_check("structural_data_integrity",
+    checker=lambda: verify_structural_no_nan_inf(output_dir),
+    severity="error"
+)
+
+# 6. Cortical thickness reasonable range (if available)
+verifier.add_check("cortical_thickness_bounds",
+    checker=lambda: verify_thickness_range(output_dir, min_mm=1.0, max_mm=4.0),
+    severity="warning"
+)
+
+# 7. Volume statistics plausible
+verifier.add_check("volume_statistics",
+    checker=lambda: verify_tissue_volume_ratios(output_dir),
+    severity="warning"
+)
+
+report = verifier.run(output_dir)
+
+# Log verification results
+logger = AuditLogger(log_file=f"{output_dir}/structural_verification.jsonl")
+logger.log_validation(
+    task_name="structural_mri_processing",
+    checks_passed=len([r for r in report.results if r.passed]),
+    checks_failed=len([r for r in report.results if not r.passed]),
+    warnings=len([r for r in report.results if r.severity == "warning" and not r.passed]),
+    report_summary=report.to_dict()
+)
+
+if report.failed:
+    raise ValueError(f"Structural MRI verification failed: {report.summary}")
+```
+
+**Output files generated**:
+- `{output_dir}/structural_verification.jsonl` — structured audit log
+- `{output_dir}/.structural_verification_timestamp` — completion marker
+
+## Complementary / Related Skills
+
+- `dcm2nii` → DICOM → NIfTI
+- `fsl-tool` → fsl_anat / BET / FAST / FIRST / registration utilities
+- `freesurfer-tool` → cortical & subcortical morphometry + thickness/parcellation
+- `hcppipeline-tool` → HCP-style structural pipeline
+- `fmriprep-tool` → standardized BIDS-App anatomical-only derivatives + QC
+- `wmh-segmentation` → WMH lesion mask from FLAIR+T1 (Docker)
+- `docker-env-manager` → safe Docker operations (when needed)
+- `nilearn-tool` → ROI feature extraction from structural-derived NIfTI maps
+- `nii2dcm` → export final NIfTI results back to DICOM
+- `dependency-planner` + `conda-env-manager` → installation/environment management
+- `claw-shell` → mandatory safe execution layer
+- `harness-core` → automated verification and audit logging
+
+---
+
+## Reference
+Aligned with NeuroClaw modality-skill pattern (see `fmri-skill`, `dwi-skill`, `eeg-skill`).
+Common sMRI toolchain: FSL (fast structural utilities), FreeSurfer (surface morphometry), HCP pipelines (HCP-grade structural processing), fMRIPrep (BIDS anatomical derivatives), Nilearn (ROI features on NIfTI maps), MARS-WMH (WMH segmentation via Docker).
+
+Created At: 2026-03-26 01:09 HKT
+Last Updated At: 2026-04-05 02:01 HKT
+Author: chengwang96

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

@@ -0,0 +1,204 @@
+---
+name: tcp-skill
+description: "Use this skill whenever the user wants an end-to-end workflow for the Transdiagnostic Connectome Project (TCP) dataset, including BIDS validation, multimodal processing of sMRI, rs-fMRI, and dMRI, phenotype extraction, and QC integration. Triggers include: 'TCP', 'Transdiagnostic Connectome', 'process TCP data', 'TCP fMRI', or any request to run the TCP multimodal pipeline."
+license: MIT License (NeuroClaw custom skill - freely modifiable within the project)
+layer: subagent
+skill_type: dataset
+dependencies:
+  - smri-skill
+  - fmri-skill
+  - dwi-skill
+  - bids-organizer
+  - claw-shell
+complementary_skills:
+  - brain-visualization
+---
+# TCP Skill (Dataset-Orchestration Layer)
+
+## Overview
+
+`tcp-skill` is the NeuroClaw orchestration skill for the **Transdiagnostic Connectome Project (TCP)** dataset, collected at Washington University in St. Louis.
+
+It strictly follows the NeuroClaw hierarchical design principles:
+- This skill **only describes WHAT needs to be done** and **which tool skill to delegate to**.
+- It contains **no implementation code or concrete commands**.
+- All concrete execution is delegated to existing base/tool skills via `claw-shell`.
+- Companion scripts in `scripts/` provide reference implementations for BIDS validation, phenotype extraction, and QC.
+
+**Core workflow (never bypassed):**
+1. Identify input TCP data and target modalities.
+2. Generate a **numbered execution plan** clearly stating WHAT needs to be done and which tool skill will handle each step.
+3. Present the full plan, estimated runtime, resource requirements, and risks to the user and wait for explicit confirmation ("YES" / "execute" / "proceed").
+4. On confirmation, delegate every step to the appropriate skill via `claw-shell`.
+5. After execution, save all outputs in a clean directory structure (`tcp_output/`).
+
+**Research use only.**
+
+---
+
+## Quick Reference
+
+| Task | What needs to be done | Delegate to | Expected output |
+|---|---|---|---|
+| BIDS validation | Validate TCP BIDS structure | `scripts/validate_tcp.py` | Validation report |
+| sMRI processing | Brain extraction, tissue segmentation | `smri-skill` | `smri_output/` derivatives |
+| rs-fMRI processing | Preprocessing, denoising, connectivity | `fmri-skill` | `fmri_output/` connectivity |
+| dMRI processing | Diffusion preprocessing, tractography | `dwi-skill` | `dwi_output/` metrics |
+| Phenotype extraction | Psychiatric diagnosis, dimensional measures | `scripts/extract_tcp_phenotype.py` | Merged phenotype CSV |
+| QC summary | Per-subject quality control | `scripts/tcp_qc_summary.py` | QC summary + exclusion list |
+
+---
+
+## Dataset Characteristics
+
+- **Cohort**: ~600+ participants
+  - Transdiagnostic approach: participants span multiple diagnostic categories
+  - **Healthy controls**: Age-matched
+  - **Psychiatric groups**: Depression, anxiety, psychosis spectrum, etc.
+- **Scanner**: 3T Siemens (WashU)
+- **Modalities**: T1w sMRI, rs-fMRI, dMRI/DTI
+- **Clinical**: RDoC-informed dimensional measures, diagnostic assessments
+- **Access**: NIMH Data Archive (NDA), OpenNeuro
+- **Format**: BIDS-compliant
+- **Reference**: Barch, Gordon et al., WashU
+
+---
+
+## Supported Modalities
+
+| Modality | Description | Details |
+|---|---|---|
+| T1w | High-resolution structural MRI | 1mm isotropic, cortical thickness |
+| rs-fMRI | Resting-state functional MRI | Eyes open, functional connectivity |
+| dMRI | Diffusion-weighted imaging | DTI, white matter tractography |
+
+---
+
+## TCP Clinical Dimensions
+
+| Domain | Measures | RDoC Construct |
+|---|---|---|
+| Negative valence | Anhedonia, anxiety | Negative valence systems |
+| Positive valence | Reward processing | Positive valence systems |
+| Cognitive | Working memory, executive function | Cognitive systems |
+| Social | Social cognition | Social processes |
+| Arousal | Arousal/regulatory systems | Arousal/regulatory systems |
+
+---
+
+## BIDS Preparation
+
+### Script: `scripts/validate_tcp.py`
+
+Validates TCP BIDS structure and generates a compliance report.
+
+```bash
+python skills/tcp-skill/scripts/validate_tcp.py \
+  --input /path/to/TCP/bids \
+  --output /path/to/tcp_output/qc/bids_validation.csv
+```
+
+Features:
+- BIDS directory structure validation
+- Modality completeness check (T1w, rs-fMRI, dMRI)
+- Diagnostic group labeling
+- Missing data identification
+
+---
+
+## Core Workflow (Never Bypassed)
+
+1. Identify user target: full TCP processing, imaging subset, phenotype extraction, or BIDS validation 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 BIDS validation using `scripts/validate_tcp.py`.
+5. Delegate to `smri-skill` for structural MRI processing.
+6. Delegate to `fmri-skill` for rs-fMRI processing.
+7. Delegate to `dwi-skill` for dMRI processing.
+8. If phenotype extraction is requested, run `scripts/extract_tcp_phenotype.py`.
+9. If QC summary is requested, run `scripts/tcp_qc_summary.py`.
+10. Save outputs into `tcp_output/`.
+
+---
+
+## Modality Processing Delegation
+
+| Modality | Delegated skill | Typical tasks | Main outputs |
+|---|---|---|---|
+| sMRI (T1w) | `smri-skill` | brain extraction, tissue segmentation, cortical thickness | `smri_output/` derivatives |
+| rs-fMRI | `fmri-skill` | preprocessing, denoising, connectivity | `fmri_output/` connectivity |
+| dMRI | `dwi-skill` | diffusion preprocessing, tensor metrics | `dwi_output/` metrics |
+
+---
+
+## Standard Output Layout
+
+```
+tcp_output/
+├── bids/                   # BIDS-staged data (or validation report)
+├── smri/                   # Structural MRI derivatives
+├── fmri/                   # Functional MRI derivatives (rs-fMRI connectivity)
+├── dwi/                    # Diffusion MRI derivatives
+├── phenotype/              # Merged phenotype tables (diagnosis, dimensional)
+├── qc/                     # QC summaries and exclusion lists
+└── logs/                   # Processing logs
+```
+
+---
+
+## Benchmark Adapter Guidance
+
+For benchmark-style prompts, do not force the full orchestration when the task only asks for local TCP data validation.
+
+- If the task starts from TCP data already present on disk and only asks for BIDS validation:
+  - Skip the download stage
+  - Default to the narrow path `local TCP discovery -> BIDS validation -> report`
+- In benchmark mode, do not require explicit confirmation before presenting the validation solution.
+
+---
+
+## 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.
+
+---
+
+## Important Notes and Limitations
+- TCP uses a transdiagnostic approach; analyses should consider dimensional rather than categorical models.
+- RDoC-informed phenotyping enables cross-diagnostic connectivity analyses.
+- Connectome-based predictive modeling (CPM) is a commonly used analysis approach.
+- Multi-diagnostic design requires careful handling of group comparisons.
+- `tcp-skill` is orchestration-only; detailed preprocessing logic remains in modality skills.
+
+---
+
+## When to Call This Skill
+- User asks for end-to-end TCP workflow.
+- User asks to process TCP neuroimaging data.
+- User needs BIDS validation for TCP data.
+- User asks to extract TCP phenotype data (diagnostic, dimensional).
+- User asks for transdiagnostic connectivity analysis.
+
+---
+
+## Complementary / Related Skills
+- `smri-skill` → structural MRI preprocessing
+- `fmri-skill` → functional MRI preprocessing and analysis
+- `dwi-skill` → diffusion MRI preprocessing
+- `bids-organizer` → BIDS validation and organization
+- `brain-visualization` → visualization of derivatives
+- `dependency-planner` → dependency resolution
+- `conda-env-manager` → environment management
+- `claw-shell` → command execution
+
+---
+
+## Reference
+- TCP: Washington University in St. Louis
+- Barch, Gordon et al.: Transdiagnostic Connectome Project
+- NIMH Data Archive: https://nda.nih.gov/
+
+Created At: 2026-05-06 14:21 HKT
+Last Updated At: 2026-05-06 14:21 HKT
+Author: chengwang96