phd-agent

End-to-end academic research paper writer that mirrors a real PhD workflow — Foundation → Pilot → Full Experiment → Writing — with a substantive advisor review at every step and the freedom to backtrack when earlier decisions look wrong.

The advisor (main conversation) gives dialectical critique rather than checklist scoring, may route the project back to any earlier phase, and optionally pauses for user confirmation at three named gates. Generators are spawned as subagents; pilot results must show mechanism activation before full experiment runs. Produces a venue-ready paper PDF + conference slide deck, with a live web dashboard you can watch in a browser.

PHASE 1 — FOUNDATION   (literature → hypotheses → design)
PHASE 2 — PILOT        (run → analysis → verdict)      ← mandatory manipulation-check gate
PHASE 3 — FULL EXP     (run → analysis → verdict)
PHASE 4 — WRITING      (discussion → paper → slides)

Venue (CHI / NeurIPS / CSCW / ACL / EMNLP / ...), pilot sample size, and gate-confirmation mode are all configurable per-invocation.

---

Invoke

/phd-agent
Topic:  <research topic>
Venue:  <CHI 2027 / NeurIPS / CSCW / ACL / ...>
Output: <directory name, e.g. paper_v3>
Gates:  auto | manual        # optional, default = auto

---

Required skills

phd-agent is an orchestrator — it dispatches work to other skills. Install the ones below before invoking.

First-party (also by this author)

Skill	Role in phd-agent	Install
experiment-validity-checker	Step 1.3 advisor check — audits experiment design for validity threats before any data is collected	git clone https://github.com/KellyGong0301/experiment-validity-checker ~/.claude/skills/experiment-validity-checker

Third-party (install from their sources — we do not redistribute)

Skill	Role in phd-agent	Source
meta-research	Phases 1.1 / 1.2 / 1.3 — research methodology skeleton (brainstorming → lit review → experiment design)	clawhub install meta-research (author: AmberLJC)
google-scholar-search	Step 1.1 — Semantic Scholar API wrapper for literature search and the advisor's 5-paper spot-check	clawhub install google-scholar-search (author: zhoujc11)
python-dataviz	Steps 2.2 / 3.2 — packaged matplotlib / seaborn / plotly scripts for publication-grade figures	clawhub install python-dataviz
research-paper-writer	Step 4.2 — IEEE / ACM paper structure guide used when drafting paper.tex	clawhub install research-paper-writer (author: veeramanikandanr48)
powerpoint-pptx	Step 4.3 — .pptx layout / template / chart guidance for the conference slide deck	clawhub install powerpoint-pptx

Optional

Skill	Role	Why optional
typetex	Step 4.2 fallback — hosted Typst/LaTeX → PDF API	Only needed if you don't have tectonic / xelatex / pdflatex locally. Relies on a third-party Modal.run endpoint that may go away.

Tip: run clawhub list (or check ~/.claude/skills/) to confirm what you already have.

---

Installation

Option A — ClawHub (recommended once published)

clawhub install phd-agent

Option B — Git clone into Claude skills dir

git clone https://github.com/KellyGong0301/phd-agent ~/.claude/skills/phd-agent

Option C — Manual

Drop SKILL.md into a folder named phd-agent/ under your Claude Code skills directory:

• macOS / Linux: ~/.claude/skills/phd-agent/SKILL.md
• Windows: %USERPROFILE%\.claude\skills\phd-agent\SKILL.md

Restart Claude Code so it picks up the new skill.

---

Architecture in one diagram

PHASE 1 — FOUNDATION
  Step 1.1  Literature survey       (Generator subagent → Advisor critique)
  Step 1.2  Hypotheses              (Generator subagent → Advisor critique)
  Step 1.3  Experiment design       (Generator subagent → Advisor critique)
  ── Phase Gate 1 ─────────────────────────────────────────────────────

PHASE 2 — PILOT                     (mandatory — detects mechanism failures
  Step 2.1  Pilot run                before any full-run compute is spent)
  Step 2.2  Pilot analysis
  Step 2.3  Pilot verdict           (Advisor + Adversarial subagent)
  ── Phase Gate 2 ─────────────────────────────────────────────────────

PHASE 3 — FULL EXPERIMENT
  Step 3.1  Full run
  Step 3.2  Full analysis
  Step 3.3  Significance verdict    (Advisor + Adversarial subagent)
  ── Phase Gate 3 ─────────────────────────────────────────────────────

PHASE 4 — WRITING
  Step 4.1  Discussion / framing
  Step 4.2  Paper (LaTeX → PDF)
  Step 4.3  Slides (PPTX)

CROSS-CUTTING
  state.json            ← single source of truth, rewritten on every step
  advisor_log.jsonl     ← every advisor verdict appended
  backtrack_log.jsonl   ← every backtrack event with reason
  dashboard.html        ← auto-regenerated, self-refreshing

See SKILL.md for the full protocol — advisor critique template, required checks per step, anti-pattern self-test, backtracking rules, and verification commands.

---

Design choices worth calling out

• Pilot phase is mandatory. The manipulation-check verdict gates the full run, so broken mechanisms are caught before they waste compute.
• Advisor is dialectical, not a score-out-of-100. Every review must fill a CHECKS_RUN block and an ANTI_PATTERN_SELF_TEST — no PASS is legal without them.
• Backtracking is first-class. Any verdict can route the project back to an earlier step; the advisor is expected to use this when evidence demands it.
• Adversarial subagent at the two significance gates. A fresh subagent with no exposure to the advisor's draft looks for the strongest reason the result does not justify proceeding.
• Venue is parametric. No venue name is hardcoded. state.target_venue drives template choice and adversarial-reviewer framing.

---

License

MIT © Kelly Gong