BillyChen123/qdd

Release status: QDD v0.1.0-rc.1 is 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.

Quick Start

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 unlimited

More installation details are in docs/04-installation-guide.md.

What QDD Gives You

Why QDD

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

The Six Human Workflows

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.

1. Start

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.

2. Propose

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.

3. Explore

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.

4. Apply

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.

5. Close

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.

6. Conclude

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

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 unlimited

Auto 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 unlimited

You can also pass the model explicitly:

qdd auto --model deepseek-reasoner --max-turns unlimited

Domain Skill Injection

QDD 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.

Public Data As First-Class Research Context

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.

What QDD Is Not

• 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.