Pathology Research Kit for AI Assistants

This kit gives you a practical starting structure for AI-assisted computational pathology, causal inference, Bayesian/statistical workflow, and reproducible data analysis.

It began as a Codex-focused kit. The repository template now supports multiple assistants in the same research repository, especially Codex, GitHub Copilot Chat, and Claude, without maintaining separate repositories per model.

What it contains

• GLOBAL_AGENTS.md: optional personal/global Codex instructions to copy to ~/.codex/AGENTS.md.
• skills/: reusable Codex skills for pathology causal analysis, QuPath/napari bioimage analysis, and spatial pathology course resources.
• repo_template/ASSISTANT_GUIDANCE.md: shared model-agnostic scientific, reproducibility, privacy, and validation rules.
• repo_template/AGENTS.md: lightweight Codex adapter that points to the shared guidance and names Codex skills.
• repo_template/.github/copilot-instructions.md: lightweight GitHub Copilot Chat adapter.
• repo_template/CLAUDE.md: lightweight Claude adapter.
• repo_template/: files to copy into each research repository, including resource-registry, research-trace, local-library, modular manuscript, and lecture scaffolding.
• prompts/: Codex-oriented prompts that can also be adapted for other assistants.
• docs/codex_intake.md: audit note for curation changes to this kit.
• EXPLANATION.md: plain-language explanations of assistant guidance, MCP, skills, hooks, tests, and Makefile.

Current Codex-specific parts

The Codex-specific layer is intentionally preserved where it is useful:

• GLOBAL_AGENTS.md and install_global.sh configure a personal Codex setup.
• skills/ contains Codex skills.
• repo_template/AGENTS.md is the Codex project adapter.
• repo_template/.codex/ contains optional Codex hook/config examples.
• Several prompt files are still phrased for Codex.
• docs/codex_intake.md and scripts/check_codex_research_preflight.py keep their legacy names for compatibility, but are documented as assistant/research workflow artifacts.

The portable layer is repo_template/ASSISTANT_GUIDANCE.md. Update that file when the scientific or reproducibility rules change; update adapter files only when an assistant needs different startup or tool conventions.

Recommended Codex installation

From the unzipped kit directory:

bash install_global.sh

This will:

1. Create ~/.codex/ if needed.
2. Copy GLOBAL_AGENTS.md to ~/.codex/AGENTS.md after backing up any existing file.
3. Copy the reusable skills under skills/ to ~/.agents/skills/.

GitHub Copilot Chat and Claude do not use this installer. They use the adapter files copied into each project.

Add the repository template to a project

Open a terminal in the unzipped kit directory and run:

bash copy_repo_template.sh /path/to/your/project

Then customize docs/research_brief.md, docs/resources.md, docs/resource_registry.yml, and the data dictionary.

Assistant startup

For any assistant, start with:

Read ASSISTANT_GUIDANCE.md, the adapter file for your assistant, docs/resources.md,
docs/resource_registry.yml, docs/research_brief.md, docs/research_trace/index.md,
docs/research_trace/claim_registry.yml, docs/data_dictionary.*,
docs/analysis_plan.md, docs/assumptions.md, and docs/causal_model.md if present.
Create or update docs/codex_intake.md as the assistant intake note.
Do not write analysis code until the research question, unit of analysis,
measurement process, assumptions, and validation plan are clear.

For Codex, add:

Use $pathology-causal-analysis.

For spatial phenotyping, spatial cell-cell interaction, QuPath, napari, WSI, segmentation, or measurement-export work, also use the relevant Codex skills or follow the equivalent workflow described in ASSISTANT_GUIDANCE.md when using Copilot Chat or Claude.

Resource registry and local library

The repository template includes a grouped resource registry derived from slrenne/Resources, plus computational pathology defaults, QuPath/napari/Bioimage resources, and local integrated-course resources. It helps assistants select and log resources for Bayesian workflow, Stan modeling, causal inference, scientific writing, discussion framing, productivity planning, Beamer lectures, QuPath and napari image-analysis workflows, spatial cell phenotyping, and spatial cell-cell interaction analysis.

Two local course repositories are registered when available:

• C:/Users/srenne/GitHubRepo/spatial_cell_phenotyping/: a 5-chapter module on multiplex imaging phenotyping, marker quantification, cell type calling, functional states, embeddings, QC, benchmarking, and exercise scripts.
• C:/Users/srenne/GitHubRepo/spatial_cell_interaction/: a 10-lecture textbook and review materials on spatial statistics, point processes, neighborhood analysis, graphs, ligand-receptor models, Bayesian spatial models, machine learning, deep learning, and future directions.

Actual PDFs, books, slides, transcripts, and course downloads should usually live outside git under external/library/. Keep only docs/local_library_manifest.md in version control unless the repository governance explicitly allows committing the source files.

When using these course repositories, an assistant should verify that the local paths exist, summarize rather than copy long passages, and log any consulted file in docs/resource_use_log.md.

For QuPath, napari, WSI, segmentation, annotation, measurement export, or image-analysis teaching, use bioimage_analysis_qupath_napari in the template registry. QuPath and napari official documentation are the behavior references, Bioimage Book is the conceptual reference, and image.sc forum material is secondary troubleshooting that must be logged when it influences decisions.

Research trace and manuscript source

The repository template includes a durable docs/research_trace/ layer for decisions, assumptions, experiments, outputs, interpretations, failed paths, human/pathologist review, and manuscript claim-to-evidence links. Its Markdown, YAML, and CSV files are the source of truth; HTML rendered with Quarto, MkDocs, Sphinx, or another tool should be treated as generated output.

The LaTeX article template is modular: latex/article/main.tex inputs preamble.tex, macros.tex, and section files under latex/article/sections/. Major manuscript claims should be checked against docs/research_trace/claim_registry.yml before finalizing.

Suggested first command in each project

After copying the template into a repository, customize the docs/ files. Then run:

make validate

The validation checks are intentionally lightweight. They do not prove the science is correct; they help ensure that the analysis plan, causal assumptions, data dictionary, and required documentation are present before an AI assistant or human analyst proceeds.

Privacy and research-data safety

For projects containing human data, do not give an assistant network access unless you have checked privacy, consent, and institutional rules. Keep raw patient-level data out of Git unless your governance process explicitly permits it. Use data/raw/ and large derived data folders as ignored paths by default.

Folder map

codex_pathology_research_kit/
  README.md
  EXPLANATION.md
  install_global.sh
  copy_repo_template.sh
  GLOBAL_AGENTS.md
  docs/
  prompts/
  skills/
    pathology-causal-analysis/
    qupath-napari-bioimage-analysis/
    spatial-pathology-course-resources/
  repo_template/
    ASSISTANT_GUIDANCE.md
    AGENTS.md
    CLAUDE.md
    .github/
      copilot-instructions.md
    AGENTS_RESOURCE_ADDENDUM.md
    AGENTS_RESOURCES.md
    Makefile
    .codex/
    docs/
    latex/
    prompts/
    scripts/
    skills/
    tests/