From 6373617d937c66cf925d4cde6a083b046e2984c2 Mon Sep 17 00:00:00 2001 From: Daniel Falster Date: Sun, 28 Jun 2026 06:07:14 +1000 Subject: [PATCH 1/2] docs: add .claude/CLAUDE.md pointer to austraits-meta Adds a minimal agent guide that points to the family-wide austraits-meta repo for cross-package context (pipeline, dependency direction, artifacts, governance). Package-local content left as a TODO stub. Co-Authored-By: Claude Opus 4.8 (1M context) --- .claude/CLAUDE.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 .claude/CLAUDE.md diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md new file mode 100644 index 0000000..1ce1778 --- /dev/null +++ b/.claude/CLAUDE.md @@ -0,0 +1,25 @@ +# APD — agent guide + +> ⚠️ **Package-local guidance is TODO.** This stub currently only points to family-wide +> context. Add APD-specific architecture, build/test commands, and gotchas below. + +## Cross-package context + +`APD` is part of the **AusTraits family**. Cross-package concerns are documented +centrally in the **[austraits-meta](https://github.com/traitecoevo/austraits-meta)** repo — +don't restate them here, read them there: + +- **Start with [`AGENTS.md`](https://github.com/traitecoevo/austraits-meta/blob/main/AGENTS.md)** — + pipeline order, who owns what, dependency direction (incl. the reversed + `traits.build` → `austraits` edge), source-of-truth rules, cross-boundary artifacts, gotchas. +- **[`dependencies.yml`](https://github.com/traitecoevo/austraits-meta/blob/main/dependencies.yml)** — + machine-readable package graph + artifacts. +- **[`governance/`](https://github.com/traitecoevo/austraits-meta/tree/main/governance)** — + label taxonomy, board #9 conventions, release playbooks, triage. + +> austraits-meta is hand-maintained prose — a map, not ground truth. Verify specifics against +> the actual repos. + +## Package-local guidance (TODO) + +_To be written: APD-specific architecture, key entry points, build & test, known gotchas._ From 4ca8ffdacb42547381dc4b4cefb2626c531538ea Mon Sep 17 00:00:00 2001 From: Daniel Falster Date: Sun, 28 Jun 2026 14:49:15 +1000 Subject: [PATCH 2/2] docs: restructure family pointer into AGENTS.md (+ README section) Adopt the austraits-meta convention: CLAUDE.md is a stub that defers to AGENTS.md, which holds repo-local guidance plus the AusTraits-family cross-package pointer. Add a README "AusTraits family" section. Co-Authored-By: Claude Opus 4.8 (1M context) --- .claude/CLAUDE.md | 28 +++++------------------- AGENTS.md | 56 +++++++++++++++++++++++++++++++++++++++++++++++ README.md | 12 ++++++++++ 3 files changed, 74 insertions(+), 22 deletions(-) create mode 100644 AGENTS.md diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 1ce1778..c2c3f2a 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -1,25 +1,9 @@ -# APD — agent guide +# CLAUDE.md -> ⚠️ **Package-local guidance is TODO.** This stub currently only points to family-wide -> context. Add APD-specific architecture, build/test commands, and gotchas below. +This repo keeps its agent & contributor guidance in **[`AGENTS.md`](../AGENTS.md)** so the same +content is tool-agnostic and shared across every agent. -## Cross-package context +**👉 Read [`AGENTS.md`](../AGENTS.md)** for repo-local orientation (architecture, build & test, +gotchas) and the AusTraits-family cross-package pointer. -`APD` is part of the **AusTraits family**. Cross-package concerns are documented -centrally in the **[austraits-meta](https://github.com/traitecoevo/austraits-meta)** repo — -don't restate them here, read them there: - -- **Start with [`AGENTS.md`](https://github.com/traitecoevo/austraits-meta/blob/main/AGENTS.md)** — - pipeline order, who owns what, dependency direction (incl. the reversed - `traits.build` → `austraits` edge), source-of-truth rules, cross-boundary artifacts, gotchas. -- **[`dependencies.yml`](https://github.com/traitecoevo/austraits-meta/blob/main/dependencies.yml)** — - machine-readable package graph + artifacts. -- **[`governance/`](https://github.com/traitecoevo/austraits-meta/tree/main/governance)** — - label taxonomy, board #9 conventions, release playbooks, triage. - -> austraits-meta is hand-maintained prose — a map, not ground truth. Verify specifics against -> the actual repos. - -## Package-local guidance (TODO) - -_To be written: APD-specific architecture, key entry points, build & test, known gotchas._ +Don't duplicate that content here — edit `AGENTS.md` and this file stays correct by reference. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..a120346 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,56 @@ +# APD — agent & contributor guide + +`APD` is a Quarto compendium that builds the **AusTraits Plant Dictionary** — a formal vocabulary of +500+ plant traits, released simultaneously in human-readable and machine-readable formats (Wenk et +al. 2024, doi:10.1038/s41597-024-03368-z). + +## Repo-local guidance + +- **Source data:** `data/` holds the ~11 input CSVs that define the dictionary — trait definitions + (`APD_traits_input.csv`), allowable categorical values (`APD_categorical_values_input.csv`), the + trait hierarchy, glossary, units, references, reviewers, namespaces, and annotation properties. + These are the source of truth. +- **Build:** `build.qmd` builds the APD from `data/`, emitting the machine-readable representations + at the repo root — RDF Turtle (`APD.ttl`), N-Quad (`APD.nq`), N-Triple (`APD.nt`), JSON-LD + (`APD.json`) — plus the derived `APD_traits.csv` and `APD_categorical_values.csv`. +- **Website:** a Quarto website (`_quarto.yml`, `index.qmd`, `using_the_APD.qmd`, `news.md`) rendered + to `docs/` and published via GitHub Pages at . The dictionary + is also resolvable via . +- **R helpers:** `R/` holds supporting functions; the compendium `Depends` on dplyr, tidyr, readr, + stringr, rdflib, purrr, gt, knitr. + +Build by executing `build.qmd` (e.g. `quarto render build.qmd`); render/preview the site with +`quarto render` / `quarto preview`. This is a **Compendium/Bundle**, not an R package — there is no +`devtools::check()` workflow. Default branch is `prepare-for-release`. + +> Heads-up: the root `APD.ttl`/`.nq`/`.nt`/`.json` and the two root CSVs are **generated** by +> `build.qmd` — edit the inputs in `data/`, then rebuild; don't hand-edit the generated files. The +> `docs/` site is likewise built output, not hand-maintained. + +--- + +## AusTraits family — cross-package context + +`APD` is part of the **AusTraits family** (a subset of the +[`traitecoevo`](https://github.com/traitecoevo) org) — here, the AusTraits Plant Dictionary — the +trait vocabulary/contract (definitions, allowed categorical values, units). Family-wide concerns are +documented centrally in +**[austraits-meta](https://github.com/traitecoevo/austraits-meta)** — don't restate them here, read +them there: + +- **Start with [`AGENTS.md`](https://github.com/traitecoevo/austraits-meta/blob/main/AGENTS.md)** — + pipeline order, who owns what, dependency direction, source-of-truth rules, cross-boundary + artifacts, gotchas. +- **[`dependencies.yml`](https://github.com/traitecoevo/austraits-meta/blob/main/dependencies.yml)** — + machine-readable package graph + cross-boundary artifacts. +- **[`governance/`](https://github.com/traitecoevo/austraits-meta/tree/main/governance)** — + label taxonomy, board #9 conventions, release playbooks, triage. + +**Filing issues:** the whole family is tracked on one board, +[AusTraits #9](https://github.com/orgs/traitecoevo/projects/9) (new issues auto-add to it). Follow +the [issue & labelling guide](https://github.com/traitecoevo/austraits-meta/blob/main/governance/issue-guide.md): +pick one work-type label (`bug` / `task` / `epic`); Status and Priority are set on the board, not as +labels. + +> austraits-meta is hand-maintained prose — a map, not ground truth. Verify specifics against the +> actual repos. diff --git a/README.md b/README.md index ce46eb6..c10af5a 100644 --- a/README.md +++ b/README.md @@ -91,6 +91,18 @@ curl -sH "Accept: text/html" -L https://w3id.org/APD/traits > temp2.html curl -sH "Accept: text/html" -L https://w3id.org/APD/traits\#trait_0001 > temp3.html ``` +## AusTraits family + +`APD` is part of the **AusTraits family** of packages maintained by the +[AusTraits](https://austraits.org) team. See **[austraits.org](https://austraits.org)** for the +project, the data, and the people behind it. + +Contributing? Issues across the family are tracked on one board, +[AusTraits #9](https://github.com/orgs/traitecoevo/projects/9), and new issues are auto-added. Please +read the [issue & labelling guide](https://github.com/traitecoevo/austraits-meta/blob/main/governance/issue-guide.md) +in [`austraits-meta`](https://github.com/traitecoevo/austraits-meta) — the family's cross-package +knowledge and governance hub — before filing. + ## Acknowledgements We are grateful to S Cox, J Smillie, K Levett, M Barlow, and C Brady for useful conversations. The AusTraits project received investment (, ) from the Australian Research Data Commons (ARDC). The ARDC is funded by the National Collaborative Research Infrastructure Strategy (NCRIS).