Question-driven orchestration for AI-assisted biomedical discovery.
Turn long-horizon research into an auditable loop of questions, evidence, artifacts, and next-study decisions.
Language
简体中文 · English
Quick Links
Release status: QDD
v0.1.0-rc.1is the public submission-candidate line. This repository accepts reproducibility fixes, bug fixes, documentation improvements, and changes required by manuscript review. New research architectures are developed separately so this line remains a stable reference for the paper.
Requirements:
- Node
>=20.19.0 - An Anthropic-compatible model configuration for Auto Mode
Install locally:
npm install
npm run build
npm install -g .Initialize a research project:
mkdir my-qdd-project
cd my-qdd-project
qdd init .Then either run the six human workflows through your agent, or start Auto Mode for the core research loop:
qdd auto --max-turns unlimitedMore installation details are in docs/04-installation-guide.md.
| Question governance Every study records how the research question changed: refinement, confirmation, pivot, or dissolution. |
Agent-ready memory Contracts, study files, task records, artifacts, and evolution history stay readable to both humans and agents. |
| Domain skill injection 34 local skills are routed by role and task instead of being dumped into every prompt. |
Public-data grounding CELLxGENE, GEO, PubMed, CellMarker, and ligand-receptor references become auditable local artifacts. |
Modern AI agents can write code, search public databases, and run analyses. The hard part is no longer only execution. The hard part is keeping a multi-step scientific project coherent after every partial result, failed hypothesis, dataset limitation, or promising signal.
QDD is built for that gap:
| Without QDD | With QDD |
|---|---|
| Scattered chats, scripts, notebooks, and folders | One readable research state shared by humans and agents |
| Agents optimize the next task only | Agents optimize the next question |
| Negative results become dead ends | Negative results become pivots, validations, or robustness studies |
| Public-data searches are hard to audit | Dataset and reference choices are recorded as reusable evidence |
| Domain knowledge must be re-explained every turn | Domain skills are injected into the right role at the right time |
QDD is intentionally small. The human-facing model is five research-loop workflows plus a project-level conclude workflow. Auto Mode covers the research loop only.
Establish the project contract: research theme, scope, data assumptions, runtime environment, durable resources, and mode. This is the stable "why are we doing this?" layer.
Turn the current frontier into one bounded study. A good study has a judgeable question, a falsifiable expectation, a small task graph, and explicit resource fit.
Stress-test a proposed study before execution. This is where the agent and user refine boundaries, decide whether public data is needed, and avoid over-broad or under-powered plans.
Execute the study tasks. QDD injects task-local domain skills, runs code inside the project, preserves scripts and outputs, and keeps final artifacts under a canonical study output surface.
Synthesize evidence and update the research frontier. A close event can refine, confirm, pivot, or dissolve a question. QDD records what changed, what remains open, which artifacts are reusable, and what next candidates are worth pursuing.
Use $qdd-conclude in Codex or the corresponding qdd-conclude entry in Claude Code when the project is synthesis-ready. The general-purpose agent writes a cross-study research synthesis, aligns the manuscript narrative with the user, writes and revises the complete story.md, and renders TeX only after the user accepts that story. Conclude is human-only and is not an Auto Mode phase.
Auto Mode runs the whole loop through an Anthropic-compatible SDK session:
Start -> Propose -> Apply -> Close -> Propose -> ...
It is designed for long-running research automation, not a single prompt. The runtime decides the next phase from persisted QDD state, while the thesis-manager role decides whether the project should continue, stop, validate, pivot, or search for better data.
Minimal launch:
qdd auto --max-turns unlimitedAuto Mode currently speaks the Anthropic protocol. Install dependencies and configure an Anthropic-compatible model before running it. If you use DeepSeek as the default backend, route it through an Anthropic-compatible gateway or internal proxy:
export ANTHROPIC_AUTH_TOKEN="your-api-key"
export ANTHROPIC_BASE_URL="https://<your-anthropic-compatible-deepseek-gateway>"
export ANTHROPIC_MODEL="deepseek-reasoner"
qdd auto --max-turns unlimitedYou can also pass the model explicitly:
qdd auto --model deepseek-reasoner --max-turns unlimitedQDD ships with 34 local skills that are routed by role and task instead of dumped into every prompt.
| Skill layer | Current coverage |
|---|---|
| Thesis planning | project-frontier planning and continue/stop/pivot decisions |
| Study brain | single-cell, spatial, and public-data planning |
| scRNA-seq | QC, integration, clustering, annotation, DE, group stats, module scoring, enrichment, communication, trajectory |
| scATAC-seq | LSI preprocessing, latent integration, gene-activity annotation, DAR |
| Spatial transcriptomics | QC, integration, clustering, annotation, group stats, DE, neighborhood, niche composition, structure quantification |
| Public data and reference | CELLxGENE, GEO, PubMed, CellMarker, ligand-receptor resources |
The point is not just more tools. The point is role-aware injection:
- thesis-manager gets frontier-planning skills
- study-brain gets planning skills
- executor gets only the task-local domain skills it needs
- public-data skills are separated from downstream analysis skills
This keeps prompts smaller, analysis more reproducible, and agent behavior easier to audit.
QDD treats external data and references as evidence, not hidden prompt memory.
Supported public-data/reference surfaces currently include:
- CELLxGENE dataset discovery
- GEO candidate capture
- PubMed evidence capture
- CellMarker marker reference capture
- ligand-receptor database capture
Dataset acquisition and downstream analysis are deliberately decoupled:
external source -> fetch/capture skill -> local artifact -> domain executor -> study output
That means an agent can first find or validate a dataset, then hand a normalized local artifact to a single-cell or spatial workflow without mixing search logic into analysis code.
- It is not a clinical decision system.
- It is not a black-box cloud notebook.
- It is not a replacement for domain judgment.
- It is not a rigid workflow engine where every branch is pre-scripted.
QDD is a protocol layer for human-agent research: local files, explicit evidence, reusable artifacts, and question evolution.