Imported from hyruuk/analysis_agent (mini/AGENTS.md). Install upstream with npx skills add hyruuk/analysis_agent --skill mini. Copyright stays with the author.

Analysis Project Guidelines

Standardization, reproducibility, documentation.

Data

• BIDS layout for everything: raw, derivatives, processed outputs.
• Raw data is immutable. Never overwrite.
• Processed outputs go in data/processed/{script_name}/ and follow BIDS naming.

Provenance

Every generated file (derivative, figure, table, stats) gets a JSON sidecar with:

{
  "script": "code/glm/compute_glm.py",
  "git_commit": "a7f3e9c",
  "date": "2026-05-06T14:30:22",
  "parameters": { "...": "..." },
  "inputs": ["..."],
  "random_seed": 42
}

No file lands on disk without its sidecar. All stochastic code sets and records a seed.

User-facing API (invoke)

• All operations run through invoke tasks. Users do not call scripts directly.
• Every task accepts a --slurm flag to dispatch to HPC; default runs locally.
• Tasks accept --subject, --session, --run (and similar) selectors. With none specified, the task runs over the full dataset.
• Idempotent: skip work when the output and its sidecar already exist with matching parameters. Provide --force to override.
• Validate early: check inputs (files exist, BIDS entities parse, required config keys present) before dispatching jobs — never submit a SLURM array that will fail in the first second.
• SLURM defaults per task: each task declares default --mem, --time, --cpus; users can override via flags.
• Document each task in TASKS.md (purpose, args, resource defaults, examples).

Configuration

• All parameters and paths live in config.yaml.
• Ship config.yaml.template with <PLACEHOLDER> values; gitignore the real config.yaml.
• No hardcoded paths or magic numbers in code.

Setup

• Provide setup.sh that bootstraps the repo: creates the venv with uv, installs the package, and interactively prompts for key config values (data path, SLURM username, etc.) to generate config.yaml from the template.
• Running setup.sh on a fresh clone should be the only step needed before invoke tasks work.

Documentation

• README.md — install, configure, run.
• TASKS.md — every invoke task documented.
• CHANGELOG.md — significant changes, paired with commit hashes recorded in sidecars.
• Update all three whenever tasks or behavior change.

Code

• Small, single-purpose functions. Utilities in utils.py, orchestration in scripts, user entry points in tasks.py.
• Type hints and Google-style docstrings on every public function.
• Manage the environment with uv. Pin every dependency to an exact version in pyproject.toml and commit uv.lock.
• ruff + pytest.
• Use the logging module, not print. Logs to logs/ (gitignored).

QC

• Each pipeline step emits a diagnostic alongside its main output: a small figure, a summary JSON, or both.
• Stored next to the output, named per BIDS conventions (e.g. ..._desc-qc.png).

Git

• Never commit data, outputs, logs, secrets, venvs, or config.yaml.
• Agent does not commit; it summarizes changes and lets the user commit.