@tangle-network/starter-foundry 0.7.3 → 0.13.2

package/registry/families/multi-agent-research-lab-ts/files/roles/biology-researcher/methodology/protein-structure-analysis.md

@@ -0,0 +1,185 @@
+---
+capability: protein-structure-analysis
+role: biology-researcher
+status: active
+source: hand-authored
+retrieved: 2026-04-26
+---
+
+# Protein Structure Analysis
+
+## Purpose
+
+Given a protein (by name, UniProt accession, or PDB ID), produce a
+citation-grounded structural narrative the Director can synthesize.
+The deliverable is a `:::contribution` containing a
+`:::artifact template: protein-structure-analysis` with structural
+features, functional implications, and any conformational /
+mechanism context.
+
+This methodology is for **structural analysis from the public
+record** — UniProt + PDB + the deposition / follow-up literature.
+It is not de novo structure prediction (no AlphaFold inference) and
+not clinical interpretation.
+
+## Inputs
+
+- Target protein identifier (UniProt accession preferred, name +
+  organism otherwise).
+- Director's dispatch sub-question (e.g. "what's the structural
+  context for the cleavage-active state of SpCas9").
+- Citation budget from triage.
+- Any `carry-context` from a handoff (especially common from
+  chemistry asking about a substrate-bound complex).
+
+## Step-by-step procedure
+
+### Step 1 — resolve the identifier
+
+Use UniProt to resolve any name/organism pair to a canonical
+accession. Record:
+
+- **UniProt accession** (e.g. Q99ZW2 for SpCas9).
+- **Organism** (TaxID).
+- **Length, MW, isoforms**.
+- **Functional annotations** (EC number, GO terms, Pfam / InterPro
+  domains).
+
+### Step 2 — pull all PDB entries
+
+Query the PDB / RCSB for all structures of the protein:
+
+- Filter by resolution (≤ 3.0 Å for atomic-detail mechanism work;
+  cryo-EM with reported map resolution acceptable).
+- Note ligand-bound vs apo, mutant vs WT, partner-bound vs
+  monomeric.
+- Note crystallisation conditions (pH, ionic, additives) — sometimes
+  the most useful caveat is "this structure is in 0.5 M ammonium
+  sulfate, far from physiological".
+
+For each PDB entry of interest:
+
+- **PDB ID** + retrieval date.
+- **Resolution** (and method: X-ray / cryo-EM / NMR).
+- **Deposition / publication paper** (DOI).
+- **B-factor caveats** — flag any region with B > 40 Ų (i.e. the
+  structure may be ambiguous in the part the question turns on).
+- **Conformational state** (e.g. "open" / "closed" / "active") —
+  source the assignment from the deposition paper, not from the
+  PDB title.
+
+### Step 3 — assemble the structural narrative
+
+For the Director's question, produce:
+
+- **Domain architecture** — which domains, in which order along the
+  sequence, with start-end residue numbers (UniProt numbering).
+- **Active site / functional residues** — UniProt feature table +
+  primary literature citation for the assignment.
+- **Conformational landscape** — what states are observed in the
+  PDB (active, inactive, partner-bound, etc.), with one citation
+  per state.
+- **Disagreement in the literature** — whenever two PDB entries +
+  papers disagree on which state is "physiological", name the
+  disagreement.
+
+### Step 4 — produce the artifact
+
+```
+:::artifact
+template: protein-structure-analysis
+
+Protein:
+  Name: [common name]
+  UniProt: [accession, retrieved <date>]
+  Organism: [organism, TaxID]
+  Length / MW: [residues, kDa]
+
+Domains (UniProt + InterPro):
+  - [Domain 1]: residues N-M [Pfam ID]
+  - [Domain 2]: ...
+
+Active site / key residues:
+  - [residue N, function] [citation: <surname year>]
+
+Structural states observed in the PDB:
+  | State | PDB | Resolution | Method | Ligand / partner | B-factor flag | Source paper |
+  |-------|-----|------------|--------|------------------|---------------|--------------|
+  | active | 8XYZ | 2.4 Å | X-ray | substrate | active-site Bs <30 | [Author year, DOI] |
+  | inactive | 7ABC | 3.1 Å | cryo-EM | apo | hinge B>40 | [Author year, DOI] |
+
+Conformational disagreement (if any):
+  - [name the disagreement and the empirical crux]
+
+Cross-domain context:
+  - Chemistry: [if the active-site mechanism is owned by chemistry —
+    handoff flag]
+  - Physics: [if the conformational dynamics depend on a free-energy
+    landscape / MD simulation — handoff flag]
+
+Citations:
+  [Author, year] First A. et al. (year). Title. Journal vol pp. DOI.
+  PDB: <id>, retrieved <date>
+  UniProt: <accession>, retrieved <date>
+:::
+```
+
+### Step 5 — emit handoffs
+
+- **Active-site mechanism / cleavage chemistry** → handoff to
+  chemistry-researcher.
+- **Conformational dynamics / free-energy landscape** → handoff to
+  physics-researcher.
+- **Drug bound at the active site, drug-design context** → handoff
+  to chemistry-researcher (medicinal chemistry).
+- **B-factor or resolution caveat** that materially affects the
+  Director's answer → name it; ask the Director whether to commission
+  a parallel structure-prediction inquiry if needed.
+
+### Step 6 — wrap in contribution
+
+```
+:::contribution
+from: biology-researcher
+in-response-to: [dispatch or handoff source]
+
+finding: [paragraph narrative — name the canonical state,
+the alternatives, the disagreement (if any), every claim
+[citation: <surname year>]]
+
+handoffs: [list]
+
+corpus-coverage: [high / medium / low]
+
+citations: [full list with database accessions + retrieval dates]
+:::
+```
+
+## Sanity checks
+
+- Every functional claim has a primary-literature citation, not
+  just a UniProt feature-table entry.
+- Every PDB entry has its deposition / follow-up paper cited.
+- B-factor caveats are surfaced where they would change the answer.
+- Cross-domain mechanism / dynamics triggers a handoff.
+- No claim is from training memory.
+
+## Anti-patterns
+
+- **Citing PDB without the paper.** A PDB entry is a deposit; the
+  paper is the interpretation. Both go in citations.
+- **Ignoring B-factor caveats.** A 4.0 Å cryo-EM density and a 2.0 Å
+  X-ray of the same complex are not equivalent evidence.
+- **Treating "active state" labels as authoritative.** PDB titles
+  reflect deposition annotation, not consensus. The deposition paper
+  + follow-ups own the assignment.
+- **Silent dynamics swallow.** Reporting a static structure as "the
+  state of the protein" without flagging dynamics literature.
+  Conformational landscapes are physics's territory; hand off.
+
+## Source
+
+Adapted from UniProt + RCSB PDB documentation, the
+structural-biology critique norms (Read et al. 2011 on the Quality
+of Crystal Structures), and the cross-domain handoff conventions in
+Cell Chemical Biology editorial guidance.

package/registry/families/multi-agent-research-lab-ts/files/roles/chemistry-researcher/AGENTS.md

@@ -0,0 +1,127 @@
+---
+name: chemistry-researcher
+role: Chemistry Researcher — reaction mechanism analysis, Crossref literature search, cross-domain handoffs
+domain: chemistry-research
+allowedDomains:
+  - api.tangle.tools
+  - api.crossref.org
+  - api.openalex.org
+  - api.semanticscholar.org
+  - pubchem.ncbi.nlm.nih.gov
+  - www.chemspider.com
+  - pubs.rsc.org
+  - pubs.acs.org
+allowedEnv:
+  - TANGLE_API_KEY
+advisoryOnly: true
+escalationRequired: true
+version: 0.1.0
+---
+
+## Role
+
+You are the Chemistry Researcher in a four-role cross-domain
+research lab. The Lab Director dispatches chemistry-primary questions
+to you. Your corpus is **Crossref + OpenAlex** for peer-reviewed
+chemistry literature, **PubChem / ChemSpider** for compound data, and
+**RSC / ACS** journal access for primary mechanism papers.
+
+You do **two** kinds of work:
+
+1. **Primary work** — the Director dispatches a chemistry question
+   (mechanism, retrosynthesis, compound property, spectroscopy
+   interpretation) and you reply with a `:::contribution`.
+2. **Cross-domain support** — physics or biology emit a
+   `:::handoff` when their literature crosses into chemistry
+   (reaction step, compound property, spectroscopic assignment). You
+   pull, you contribute, you tag the contribution as
+   `from: chemistry-researcher`.
+
+## What you do NOT do
+
+- Give **lab safety advice** — chemical handling, PPE, fume hood,
+  storage, disposal. Escalate to the operator's lab safety officer.
+- Make **clinical / toxicological judgements** — toxicity, dosing,
+  pharmacokinetics. Escalate.
+- Answer **physics or biology questions directly**. Hand off.
+- Synthesize the final answer — that is the Director's job.
+- Recommend **experimental procedures involving controlled or hazardous
+  substances** without escalation.
+- Fabricate citations, melting points, yields, or spectral data.
+
+## Authoritative methodology
+
+When the Director's dispatch maps to one of these capabilities, load
+the corresponding methodology file *before* responding:
+
+- `reaction-mechanism-analysis` →
+  `methodology/reaction-mechanism-analysis.md`
+- `crossref-literature-search` →
+  `methodology/crossref-literature-search.md`
+
+The full coordination protocol is at `coordination-protocol.md`. Read
+it on every conversation; it owns the handoff trigger conditions.
+
+## Output blocks
+
+- `:::contribution` — your reply to a dispatch or handoff. Required:
+  `from`, `in-response-to`, `finding(s)`, `citations`. Tag every
+  claim with `[citation: <surname year>]`.
+- `:::handoff` — emitted when your retrieved literature crosses into
+  physics or biology.
+- `:::survey` — citation-grounded retrieval used inside contribution.
+- `:::escalation` — when the question crosses into safety, clinical,
+  regulatory, IP, or legal territory.
+
+## Cross-domain handoff trigger conditions
+
+Emit `:::handoff` when ANY of these conditions hold:
+
+- The mechanism depends on a **DFT / TDDFT / ab initio** calculation
+  (computational chemistry → physics-researcher for methods
+  provenance, even though the calculation is "chemistry").
+- The mechanism happens **in vivo** or in a biological system (the
+  biology-researcher owns the physiological context).
+- The compound is a **drug, drug candidate, biologic, or natural
+  product whose biology** is the operator's actual interest.
+- A free-energy / kinetic / thermodynamic primitive is borrowed from
+  statistical mechanics → handoff to physics-researcher.
+- Author affiliations include a primary biology / physics department.
+
+## Mandatory escalation
+
+Stop and emit `:::escalation` for:
+
+1. **Lab safety** — handling, storage, disposal, PPE, fume hood,
+   reactivity, runaway, hazard codes interpretation. → lab safety
+   officer / institutional EHS.
+2. **Controlled substances** — Schedule I-V, precursors (DEA list 1
+   / list 2). → institutional regulatory affairs / DEA registrant.
+3. **Explosives / energetic materials / select agents** → institutional
+   biosafety + EHS.
+4. **Clinical / toxicological** — interpret toxicity, dosing,
+   exposure limits beyond citing the source. → clinical
+   pharmacologist / toxicologist / physician.
+5. **Patent / regulatory** — patentability, REACH / TSCA / GHS
+   classification, FDA / EMA filings. → patent counsel / regulatory
+   affairs.
+
+## Citation discipline
+
+Every claim takes a `[citation: <surname year>]`. Compound properties
+take a database citation (PubChem CID + retrieval date, ChemSpider
+ID + retrieval date). **Fabricated citations or fabricated data are
+an immediate halt condition** — stop and report the gap to the
+Director.
+
+## What you WILL do
+
+- Pull from Crossref / OpenAlex / PubChem / ChemSpider / RSC / ACS
+  using the research-corpus tools — never from training memory.
+- Tag every claim with a citation.
+- Hand off the moment a finding crosses into physics (computational
+  methods) or biology (in vivo / structural biology).
+- Disagree with another role's contribution by name, with the
+  empirical crux that would resolve the disagreement.
+- Refuse to advise on safety, controlled substances, or clinical
+  interpretation — escalate instead.

package/registry/families/multi-agent-research-lab-ts/files/roles/chemistry-researcher/methodology/crossref-literature-search.md

@@ -0,0 +1,167 @@
+---
+capability: crossref-literature-search
+role: chemistry-researcher
+status: active
+source: hand-authored
+retrieved: 2026-04-26
+---
+
+# Crossref Literature Search
+
+## Purpose
+
+Run a citation-grounded chemistry literature search using **Crossref
+(primary)** for DOI-linked metadata, **OpenAlex** for citation graph
++ corroboration, and **PubChem / ChemSpider** for compound data.
+Used when the Lab Director dispatches a chemistry question and when
+physics or biology hand off into chemistry territory.
+
+The Crossref API is the workhorse for chemistry because most
+chemistry primary literature lives behind ACS / RSC / Wiley / Elsevier
+paywalls — the Crossref DOI metadata is the universal handle.
+
+## Inputs
+
+- The dispatched / handed-off sub-question.
+- Citation budget from the Director's triage.
+- `carry-context` from any handoff.
+
+## Step-by-step procedure
+
+### Step 1 — pick the corpus order
+
+| Question | Corpus order |
+|---|---|
+| Compound property (mp, bp, logP, pKa, spectra) | PubChem → ChemSpider → Crossref (for the underlying primary) |
+| Reaction / mechanism | Crossref (JACS, Angew, Chem Sci, Nat Chem) → OpenAlex citation graph |
+| Catalysis / new methodology | Crossref → OpenAlex (recent + highly cited) |
+| Spectroscopic assignment | PubChem (spectra) → Crossref (primary report) |
+| Drug / biologically-active compound | PubChem (incl. biological assay data) → Crossref → flag for handoff to biology |
+
+### Step 2 — query construction
+
+For Crossref, use the works endpoint with:
+
+- `query.title` — title-restricted search.
+- `query.bibliographic` — title + abstract.
+- `query.author` — when the operator named an author / group.
+- Filters: `from-pub-date`, `until-pub-date`, `container-title`
+  (specific journal), `type:journal-article`.
+
+Example: mechanism of photoredox single-electron transfer in
+organic halide reduction:
+
+```
+Crossref:
+  query.bibliographic: "photoredox single electron transfer organic halide"
+  filter: container-title=J. Am. Chem. Soc. OR Nat. Chem. OR Chem. Sci.,
+          from-pub-date=2018-01-01, type=journal-article
+  rows: [from triage budget]
+  sort: relevance
+```
+
+### Step 3 — corroborate via OpenAlex citation graph
+
+Take each Crossref hit by DOI; query OpenAlex for:
+
+- Citation count + per-year trend.
+- Cited-by works (papers citing this one — useful for identifying
+  the corroborating + dissenting literature).
+- References (the paper's own bibliography — useful for tracing the
+  mechanism back to its origin).
+- Author affiliations (signals chemistry-only vs cross-domain).
+
+### Step 4 — for compound data, hit PubChem / ChemSpider
+
+If the question is property-driven:
+
+- **PubChem** by CID (preferred), or by name / SMILES / InChI.
+- Extract: molecular formula, MW, logP (XLogP3), pKa, mp, bp,
+  density, solubility, spectral data (NMR / IR / MS where reported),
+  hazard / GHS classifications, biological assay data (and **flag
+  for biology handoff** if the assay data is the operator's actual
+  interest).
+- **ChemSpider** for cross-validation; flag any disagreement > 5%
+  on a numeric property between sources.
+
+### Step 5 — assemble the survey
+
+```
+:::survey
+template: crossref-literature-search
+query: [the search you ran, in human-readable form]
+corpora-hit: [list]
+budget-used: [n papers, n compound records]
+
+| # | Title / Compound | Authors | Year | Source | Citations | Cross-domain signal |
+|---|------------------|---------|------|--------|-----------|---------------------|
+| 1 | ... | ... | 2024 | JACS | 47 | none |
+| 2 | ... | ... | 2023 | Cell Chem Biol | 12 | bio co-authors — flag |
+
+**Synthesis (chemistry view)**: 2-3 sentences naming the consensus,
+the dissent if any, and the gap.
+
+**Compound data (if applicable)**:
+| Property | Value | Source | Retrieved |
+|---|---|---|---|
+| MW | ... | PubChem CID 1234 | 2026-04-26 |
+| logP | ... | PubChem (XLogP3) | 2026-04-26 |
+
+**Full citations**:
+- [Surname, year] Author A. et al. (year). Title. Journal vol pp. DOI.
+:::
+```
+
+### Step 6 — emit handoffs if triggered
+
+For each row tagged "cross-domain signal — flag", emit a `:::handoff`
+inside the contribution:
+
+- DFT or computational methods → physics-researcher.
+- Protein structure / in vivo / drug pharmacology → biology-
+  researcher.
+
+### Step 7 — wrap in contribution + return
+
+```
+:::contribution
+from: chemistry-researcher
+in-response-to: [dispatch or handoff source]
+
+finding: [paragraph narrative; every claim tagged
+[citation: <surname year>]; PubChem / ChemSpider citations include
+CID + retrieval date]
+
+handoffs: [list]
+
+corpus-coverage: [high / medium / low]
+
+citations: [full list]
+:::
+```
+
+## Sanity checks
+
+- Every numeric compound property has a database citation with
+  retrieval date.
+- Every mechanism claim has a primary-literature DOI citation, not
+  a textbook attribution.
+- Every cross-domain signal in the survey has a matching `:::handoff`.
+- No claim is from training memory.
+
+## Anti-patterns
+
+- **PubChem-only on a mechanism question.** PubChem has compound
+  data; mechanism lives in primary literature. Use Crossref.
+- **Citing the review.** A review's citation is the original; trace
+  it. Use the review for breadth, not for the load-bearing claim.
+- **Silent disagreement between PubChem and ChemSpider.** Numeric
+  disagreements are signal — flag them, do not pick the prettier
+  number.
+
+## Source
+
+Adapted from Crossref API docs (api.crossref.org), OpenAlex API
+ranking heuristics, and the cheminformatics community's PubChem
+citation conventions (Kim et al., Nucleic Acids Res. — PubChem
+papers, plus PubChem's own data citation guidance).

package/registry/families/multi-agent-research-lab-ts/files/roles/chemistry-researcher/methodology/reaction-mechanism-analysis.md

@@ -0,0 +1,180 @@
+---
+capability: reaction-mechanism-analysis
+role: chemistry-researcher
+status: active
+source: hand-authored
+retrieved: 2026-04-26
+---
+
+# Reaction Mechanism Analysis
+
+## Purpose
+
+Given a target reaction (or transformation), produce a citation-
+grounded mechanistic narrative the Director can synthesize. The
+deliverable is a `:::contribution` containing a `:::artifact
+template: reaction-mechanism-analysis` with the proposed mechanism,
+its evidence, and any contradictions in the literature.
+
+This methodology is for **mechanism analysis from published
+literature** — not de novo proposal of a route the literature does
+not support, and **never** experimental safety guidance.
+
+## Inputs
+
+- Target reaction or transformation (substrates, conditions if
+  known, expected product if known).
+- Director's dispatch sub-question (e.g. "what mechanism is proposed
+  for X cleavage in conditions Y").
+- Citation budget from triage.
+- Any `carry-context` from a handoff (especially common from biology
+  asking about an enzyme or drug-action mechanism).
+
+## Step-by-step procedure
+
+### Step 1 — frame the mechanistic question precisely
+
+Distinguish:
+
+- **Elementary step** (single bond making / breaking) vs **overall
+  mechanism** (multi-step pathway).
+- **Stoichiometric** vs **catalytic** (different evidence shapes).
+- **Concerted** vs **stepwise** (look for kinetic isotope effect,
+  Hammett, intermediates).
+- **In vitro** (organic flask) vs **in vivo / enzyme-catalysed** (if
+  the latter, you are likely going to hand off to biology-researcher
+  for the structural context).
+
+### Step 2 — pull the primary mechanism literature
+
+Use `crossref-literature-search` (sister methodology) with:
+
+- The IUPAC / common name of substrate + product.
+- Mechanism keywords: "mechanism", "kinetics", "isotope effect",
+  "intermediate", "transition state", "DFT" (signal for handoff to
+  physics).
+- Restrict to peer-reviewed primary literature (not reviews) for the
+  mechanism claim itself; pull one or two recent reviews for
+  context.
+
+For published, well-studied reactions, hit:
+
+- **JACS** (J. Am. Chem. Soc.) — primary mechanism papers.
+- **Nature Chemistry**, **Science** — high-impact mechanism /
+  catalysis.
+- **Chem. Sci.**, **Angew. Chem.** — corroborating primary.
+- **Chem. Rev.**, **Chem. Soc. Rev.** — review for breadth, never as
+  the citation for a specific claim.
+
+### Step 3 — extract the mechanistic evidence
+
+For each primary paper, extract:
+
+- **Proposed mechanism** (in arrow-pushing or step list form).
+- **Evidence supporting it**:
+  - Kinetic data (rate law, KIE).
+  - Isotope labeling.
+  - Trapped or detected intermediates (UV-Vis, NMR, MS, EPR, IR).
+  - Computational (DFT, ab initio) — **flag for handoff to
+    physics-researcher** for methods provenance.
+  - Crystallography (substrate-bound or transition-state analog) —
+    **flag for handoff to biology-researcher** if the crystal is of
+    a protein-substrate complex.
+- **Caveats / known disagreements** — the field-internal
+  disagreement is the single most useful signal for the Director's
+  contradiction-resolution step.
+
+### Step 4 — produce the artifact
+
+```
+:::artifact
+template: reaction-mechanism-analysis
+
+Reaction:
+  Substrate(s): [structure / SMILES / common name]
+  Product(s): [...]
+  Conditions cited: [solvent, T, catalyst, additives]
+
+Proposed mechanism (consensus / dominant view):
+  Step 1: [arrow-pushing or word description]
+    Evidence: [KIE = X, intermediate Y observed by NMR — Z et al. year]
+  Step 2: [...]
+    Evidence: [...]
+  ...
+
+Alternative mechanism(s) (if the literature is split):
+  - [name the alternative]
+    Evidence cited: [...]
+    Disagreement crux: [what experiment would distinguish]
+
+Computational evidence (if any):
+  Method: [DFT functional / basis or ab initio level]
+  Source: [arxiv / J Chem Phys / J Chem Theory Comput]
+  Flag: handoff to physics-researcher for methods-provenance check.
+
+Structural / biological evidence (if any):
+  Source: [PDB ID / Nature / Cell paper]
+  Flag: handoff to biology-researcher for structural context.
+
+Confidence in the consensus mechanism:
+  high / medium / low — [why]
+
+Citations:
+  [Surname, year] Author A. et al. (year). Title. Journal vol pp. DOI.
+:::
+```
+
+### Step 5 — emit handoffs
+
+- **DFT / ab initio in evidence** → handoff to physics-researcher to
+  validate the methods (functional choice, basis set, known
+  systematic biases for the bond / state in question).
+- **Crystal structure of protein-substrate** → handoff to biology-
+  researcher for the structural-biology context (alternative
+  conformations, B-factor caveats, the structural era's known
+  caveats).
+- **Mechanism in vivo** → handoff to biology-researcher for
+  cellular context (compartmentalisation, cofactors, off-target).
+
+### Step 6 — wrap in contribution
+
+```
+:::contribution
+from: chemistry-researcher
+in-response-to: [dispatch or handoff source]
+
+finding: [paragraph narrative — name the consensus, name the
+dissent, explicitly tag every claim [citation: <surname year>]]
+
+handoffs: [list]
+
+citations: [full list, primary literature first, reviews flagged]
+:::
+```
+
+## Sanity checks
+
+- Every mechanism claim has a primary-literature citation (not a
+  review) where possible.
+- Every alternative mechanism is named with its empirical crux.
+- DFT / computational evidence triggered a physics handoff.
+- Protein-substrate evidence triggered a biology handoff.
+- No claim is from training memory.
+
+## Anti-patterns
+
+- **Textbook mechanism without primary citation.** "SN2 with
+  inversion" might be true but needs the specific paper.
+- **Smoothing field disagreements.** If the literature is split
+  between concerted and stepwise, the contribution must show the
+  split — that is exactly what the Director's synthesis needs.
+- **Absorbing computational evidence silently.** DFT calculations
+  carry method-dependent error; physics-researcher's handoff
+  catches functional-choice bias.
+
+## Source
+
+Adapted from Anslyn & Dougherty *Modern Physical Organic Chemistry*
+(mechanism analysis frameworks), Lowry & Richardson *Mechanism and
+Theory in Organic Chemistry*, and the IUPAC recommendations for
+reporting mechanistic evidence (Pure Appl. Chem. 2014).