Imported from ms609/TreeDist (AGENTS.md). Install upstream with npx skills add ms609/TreeDist. Copyright stays with the author.

TreeDist — Agent Instructions

Project Overview

TreeDist is an R package (GPL ≥ 3) providing a suite of topological distance metrics between phylogenetic trees. The mathematical core is implemented in C++17 and exposed to R via Rcpp. The primary optimization goal is speed: many real analyses compute pairwise distances over hundreds or thousands of trees, so inner loops must be tight.

Current version: 2.12.0.9000 (development).
CRAN package page: https://cran.r-project.org/package=TreeDist

Repository Layout

TreeDist/
├── .AGENTS/              # Protocols for specific activities. Records of work done.
├── src/                  # C++17 source (main optimization target)
├── R/                    # R wrapper layer and pure-R helpers
├── benchmark/            # Microbenchmark scripts (bench package)
├── tests/testthat/       # Unit tests
├── data-raw/             # Scripts that regenerate lookup tables / data
├── vignettes/            # User-facing tutorials
└── inst/                 # Installed extras

Sibling repository — ../TreeTools is a companion package that TreeDist links against at the C++ level (LinkingTo: TreeTools). Edits to TreeTools headers (especially SplitList.h) can affect TreeDist performance and can be pushed to CRAN independently when ready.

C++ Source Files

C++ compilation flags are controlled by src/Makevars.win (Windows) / src/Makevars. The package requires C++17 (CXX_STD = CXX17).

Benchmark Infrastructure

When benchmarking, profiling or optimizing, you MUST first read .AGENTS/protocol/Optimization.md.

TreeTools Dependency

../TreeTools is available locally and editable. It is linked at the C++ level via LinkingTo; the key header consumed by TreeDist is <TreeTools/SplitList.h>.

Important constants defined there that affect TreeDist:

• SL_MAX_TIPS — maximum number of leaf taxa per tree.
• SL_MAX_SPLITS — maximum number of splits.
• splitbit — the unsigned integer type used for bitset representation of splits.

If a bottleneck traces back to a TreeTools header (e.g. SplitList layout, bit-width of splitbit), changes can be made in ../TreeTools, tested locally by re-installing, and pushed to CRAN when stable.

Prefer TreeTools over ape

When a function exists in both ape and TreeTools, always use the TreeTools version. TreeTools wrappers validate input and return consistently-classed objects.

Use ape:: only for functions with no TreeTools equivalent (e.g. ape::read.nexus(), ape::read.tree()).

Development Workflow

A task is complete only when R CMD check passes.

Validation on GitHub actions is preferred. Where there is a strong case to do so, you may test locally:

# Build and reload (from R)
devtools::load_all()          # fast incremental rebuild
devtools::test()              # run testthat suite

# Or from the shell
R CMD build .
R CMD check TreeDist_*.tar.gz

# Run a single benchmark interactively
source("benchmark/_init.R")
source("benchmark/bench-tree-distances.R")

Remote compute dispatch (GHA)

Agents can offload full test suites, R CMD check, and benchmarks to GitHub Actions instead of running them locally. This frees local CPU for fast iteration (targeted tests only).

Helper scripts (in GitHub/ root)

Available workflows

Typical usage

# Push feature branch and dispatch checks
cd TS-<task-name>
git push -u origin feature/<task-name>
cd ..
bash gha-dispatch.sh agent-check.yml feature/<task-name>
# → prints run ID, e.g. 23496860826

Immediately after dispatch, write a pending-file (see "GHA pending-file protocol" below). This ensures any agent can pick up the result later:

RUN_ID=23496860826
cat > .gha-pending/TreeSearch-${RUN_ID}.md << 'EOF'
# GHA Run 23496860826

- **Package:** TreeSearch
- **Branch:** feature/<task-name>
- **Workflow:** agent-check.yml
- **Dispatched by:** Agent <Letter>
- **Dispatched at:** <ISO-8601>
- **Task:** <Letter>-nnn — <description>
- **Worktree:** TS-<task-name>
## Context

<1-3 sentences: what changes are being validated>

## On PASS

<What to do: e.g. "Create PR to cpp-search" or "Report pass on existing PR #N">

## On FAIL

<What to check: e.g. "Timeout logic in ts_driven.cpp line ~443.
Check if elapsed() fires before first replicate completes.">

## Key files changed

- <list of files relevant to diagnosing failures>
EOF

GHA pending-file protocol

Directory: .gha-pending/ (in the GitHub/ root).

When an agent dispatches a GHA workflow, it writes a context file to .gha-pending/<Package>-<run_id>.md. This file serves two purposes:

1. Discovery: Any agent can scan the directory to find completed runs.
2. Context handoff: The file contains enough information for a different agent to interpret the results and continue the work.

CPU limits

Max 2 cores per agent. Use nThreads = 2L in tests and benchmarks. Never use nThreads = 0L (auto-detect). Use -j2 for make.

Documentation and spelling checks

After any work that adds or modifies roxygen comments, Rd files, NEWS.md, or vignettes, run:

devtools::check_man()                # regenerates Rd files and checks for issues
spelling::spell_check_package()      # flags potential misspellings

Legitimate technical terms, proper nouns, and code identifiers flagged by the spell checker should be added to inst/WORDLIST (one word per line, alphabetically sorted). Only fix actual typos in the source.

Code coverage

Check that existing tests cover all new code. The GHA test suite uses codecov. To check locally:

cov <- covr::package_coverage()
covr::report(cov)                        # interactive HTML report
covr::file_coverage(cov, "src/pairwise_distances.cpp")  # per-file summary

Aim for full line coverage of new C++ and R code. If a new code path is not exercised by the existing test suite, add targeted tests in tests/testthat/.

You are done when:

A completed task:

• Passes checks
• Has suitable test coverage
• Follows