convez.ai
SkillBusca & PesquisaAvançado
HaochenSHI66

Research Orchestrator

HaochenSHI66/research-orchestrator

Orquestrador de pesquisa que mantém conversas longas navegáveis via delegação

Ver no GitHub
InicialPluginScore · de 0 a 100

Uma skill Claude Code que executa projetos de pesquisa mantendo a thread principal limpa através de delegação a subagentes. O orquestrador apenas planeja, despacha, verifica e registra decisões, enquanto todo trabalho de pesquisa é executado por subagentes que persistem resultados em disco e retornam resumos compactos.

Instalação

$npx convez-ai HaochenSHI66/research-orchestrator

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
0

Casos de uso

  • Projetos de pesquisa acadêmica de longa duração
  • Análise competitiva e varredura de inteligência
  • Geração de papers com verificação de citações PDF e padrões de venue

Veredito

Skill maduro e bem-arquitetado para pesquisa de escala acadêmica. Implementa padrões sólidos (evidence-gating, human gates, persistent state) mas exige disciplina do usuário e infraestrutura de Claude Code estabelecida.

README

A tradução para o português deste README ainda está na fila.

research-orchestrator

A Claude Code skill that runs research projects as a lean orchestrator.
The main thread only plans, dispatches, verifies, and records — never does research work itself.
All work is delegated to subagents that write to disk and return compact summaries, so your
conversation stays navigable months into a project.

License: MIT Claude Code ARIS


Contents


The problem

Long research projects break single-conversation LLM sessions: context fills with irrelevant detail, and 30 steps in you've lost the thread.

research-orchestrator fixes this by keeping the main thread plan-only. Every task dispatches to a subagent that writes full output to disk and returns only a ≤200-word summary.


Install

git clone https://github.com/HaochenSHI66/research-orchestrator \
  ~/.claude/skills/research-orchestrator

Then, inside any research project:

/research-orchestrator

The skill reads .research/STATE.md, picks up where you left off, and keeps moving.


How it works

Architecture diagram showing the research-orchestrator loop: Main Thread hexagon with A→B→C→D inner loop, subagent fan-out to ARIS skills, .research/ workspace, and human gates

The orchestrator never does research work itself. It decides what happens next, briefs a subagent, and records the outcome. That's the entire job.

The dispatch contract

Every subagent gets a self-contained brief:

Context: <2–3 sentences — the subagent can't see the main conversation>
Task: <specific, bounded unit of work>
Skill: invoke `aris-xxx` for this
Output path: .research/artifacts/xxx.md
Return ONLY:
  1. ≤200-word summary
  2. Artifact path(s)
  3. Evidence for each load-bearing claim [verified] / [sourced] / [assumption]
  4. Skills/tools actually used
  5. Any decision the orchestrator now needs
  6. Confidence / risk flag

This contract is what keeps the main thread clean. A subagent's full notes, code, logs, and drafts stay on disk. Only the summary comes back.


What it does

Autonomous loopRuns through ordinary work without stopping. Pauses only at genuine human gates: direction choices, missing credentials, interactive logins, irreversible actions.
Persistent workspacePlans, designs, and decisions — including options that lost — are all kept under .research/. Every session reads STATE.md first.
Running TODOTODO.md is updated every loop iteration with status, locked decisions, and open questions — single source of truth for the whole project.
Stage → skill mappingEach research stage auto-maps to the matching ARIS academic skill. Ideation, literature, experiments, writing, review, rebuttal — all covered.
ChatGPT cross-analysisRequired (not optional) for any soundness claim — novel? sound? claim follows from results? Runs via codex MCP at xhigh reasoning, saved to .research/chatgpt/.
Competitive sweepBefore any new direction, fans out parallel subagents to map existing literature and surface direct overlap, competitive risk, and open gaps.

Design principles

Every concern below is enforced at runtime — gates block progress, loops update state, and the workspace records everything. Click the reference link to read the full specification.


Evidence-gating — nothing enters STATE as fact without proof

The most common failure in AI-assisted research: a subagent asserts something, the orchestrator records it, and the error propagates invisibly for 10 more steps. This skill treats every subagent summary as a claim, not proof.

  • All load-bearing claims tagged [verified: file:line], [sourced: url], or [assumption: model-prior]
  • Every claim tracked in verification-ledger.md; status stays unverified until evidence is supplied
  • Hard no-pass gate: no expensive or irreversible action (compute, push, submit) proceeds while any claim it depends on is unverified or refuted
  • An [assumption] may never be silently promoted to fact — it becomes a human gate

→ SKILL.md § The second rule: evidence over assertion · SKILL.md § The verification ledger and the no-pass gate


Citation PDF verification — every reference is downloaded and checked

Most tools trust abstracts or metadata. This skill runs a four-gate pipeline on every citation before it can appear in a draft.

  • Resolve via DOI / arXiv / Semantic Scholar to canonical paper
  • Fuzzy-match title, authors, year for metadata integrity
  • Download the actual PDF (via Unpaywall or open-access sources)
  • Extract text and confirm the specific claim the citation is meant to support
  • Five outcomes: VERIFIED, EXISTS-BUT-UNCHECKED, METADATA-MISMATCH, CLAIM-UNSUPPORTED, NOT-FOUND — a draft never ships with anything other than VERIFIED

→ SKILL.md § References: download and verify · references/citation-verification.md


ChatGPT cross-analysis — adversarial second opinion for high-stakes decisions

For decisions where a wrong answer costs weeks (is this novel? is this design sound? does this claim follow from the results?), a second independent model is more valuable than another pass from the same one.

  • Runs via the codex MCP server inside a subagent — exchange never lands in the main thread
  • Model: gpt-5.5, reasoning effort: xhigh — strongest available reviewer, not a quick sanity check
  • Prompted to refute, not praise — disagreement is the signal, not a problem to resolve away
  • Required (not optional) for any soundness claim: design, formula, experimental protocol, novelty assertion
  • Method/design choices need both an independent refutation subagent AND this codex cross-analysis to pass

→ SKILL.md § ChatGPT cross-analysis · SKILL.md § Design / experiments / formulas: both must confirm


Human gates — autonomous loop with hard stops at irreversible decisions

The skill loops without interruption through ordinary work. It stops only when a wrong guess cannot be corrected cheaply.

GateTrigger
Direction choiceMultiple viable directions; choice changes everything downstream
Benchmark protocolNo existing benchmark measures the claimed contribution
Missing credentialAPI key, dataset token, cluster login, codex MCP auth
Interactive authBrowser or terminal login required (OAuth, 2FA, gcloud auth login)
Irreversible actionDelete, push, submit, spend — any action that can't be undone
Unverified claimLedger has an open item a planned step depends on

Multiple visible gates are batched into one question. Session state is written clean before every stop so the next turn or session can resume exactly.

→ SKILL.md § Human gates — the only reasons to stop


Clean main thread — the orchestrator never does the work

The main conversation handles one thing: deciding what happens next. Every execution task is a subagent.

  • Each subagent gets a self-contained brief with context, task, ARIS skill to invoke, and output path
  • Subagent returns ≤200-word summary + artifact paths + evidence; full output stays on disk in artifacts/
  • Independent tasks fan out in a single message (parallel dispatch); dependent tasks run sequentially
  • Research stages map to ARIS skills automatically via stage-skill-map.md — the orchestrator follows the map, not ad-hoc choices

→ SKILL.md § The one rule that makes this work · SKILL.md § Dispatching a subagent — template · references/stage-skill-map.md


Persistent workspace + running TODO — single source of truth across all sessions

Every session starts by reading state, not by asking the user what's going on.

  • STATE.md — reconciled against git log and disk on every session start; disagreements surfaced before any work begins
  • TODO.md — updated every loop iteration with [x] / [~] / [ ] / 🚪 status, locked decisions with rationale, and open questions for the user
  • Superseded decisions are struck through and annotated, never deleted — the history of what was tried and rejected is part of the record
  • Design docs versioned by filename (v1.md, v2.md) and never overwritten in place
  • decisions/ holds one entry per human-gate decision: the options considered, the choice made, and why

→ SKILL.md § Todolist · SKILL.md § Recording designs and decisions · references/workspace-layout.md


Competitive intelligence sweep — no direction chosen blind

Before committing to any research direction (or after a topic pivot), the skill runs a mandatory literature sweep and presents a positioning map.

  • Identifies top 2–3 venues for the area
  • Fans out 3–5 parallel subagents across keyword angles using aris-semantic-scholar, aris-openalex, aris-arxiv; each downloads PDFs
  • One subagent per paper extracts contribution, method, benchmarks, results, limitations
  • Synthesis subagent builds a contribution-space table with an explicit verdict: direct overlap / competitive risk / gap filler / novel axis
  • Direction choice is always a human gate — positioning map presented first, never picked silently
  • Benchmark decision flows from the map: existing benchmarks reused by default; deviation requires documented justification

→ SKILL.md § Competitive intelligence sweep — mandatory before any direction gate


Venue-standard quality + figure discipline — held to NeurIPS/ICML/CVPR/ACL bar

Every project is held to the submission standards of a top CS venue. These are gates, not aspirations.

  • Every design constant needs a derivation, or a sensitivity sweep + ablation; if neither exists, that's a finding, not a detail
  • Gains attributed to tuning or compute (not the idea) are flagged and separated
  • Single-run results, weak baselines, data leakage, missing closest prior work, and overclaiming are all caught by the reviewer-attack checklist before the writing stage
  • All figures produced via the paper-plot-from-data skill for consistent style and palette across the paper
  • Every paper targets a diverse set of figure types: schematic, quantitative, ablation, qualitative/failure, convergence — not repetitive
  • Tables follow the LaTeX template in figure-discipline.md: booktabs, no vertical rules, \rowcolor for proposed method, captions above

→ SKILL.md § Held to top CS-venue standards · references/reviewer-attack-checklist.md · references/figure-discipline.md


Workspace

Bootstrapped on first run:

.research/
├── STATE.md               ← current-state snapshot; first thing every session reads
├── TODO.md                ← running task board + locked decisions + open questions
├── plan.md                ← living master plan (high-level milestones)
├── verification-ledger.md ← status of every load-bearing claim
├── designs/               ← design docs, versioned, never overwritten
├── decisions/             ← one entry per human-gate decision (options, choice, rationale)
├── competitive-sweep/     ← positioning map + per-paper analyses
├── artifacts/             ← subagent working outputs
└── chatgpt/               ← ChatGPT cross-analysis exchanges

TODO.md is the project's single source of truth — it tracks tasks, records locked decisions with rationale, and lists open questions for the user. It's updated every loop iteration so it always reflects reality.

designs/ is versioned by filename (exp-design-v1.md, v2.md) and never overwritten. Old versions stay — the history of what was tried and rejected is part of the project record.


Academic skills

The stage → skill map targets the ARIS family (aris-*). Falls back to scholar-* / arl-* / phd-* if ARIS isn't installed — orchestration still works either way.

StageSkills
Ideationaris-idea-discovery, aris-idea-creator, aris-novelty-check
Literaturearis-research-lit, aris-openalex, aris-semantic-scholar, aris-arxiv
Experiment designaris-experiment-plan, aris-ablation-planner
Running & monitoringaris-monitor-experiment
Analysisaris-analyze-results, aris-result-to-claim
Writingaris-paper-write, aris-paper-plan, aris-paper-figure
Review & auditaris-citation-audit, aris-paper-claim-audit, aris-auto-review-loop
Rebuttalaris-rebuttal, aris-resubmit-pipeline

The orchestrator never invokes these itself — it tells each dispatched subagent which skill to run. The subagent runs it in its own context. See references/stage-skill-map.md for the full mapping.


Requirements

  • Claude Code with the Agent tool — required; without subagent support the skill is non-functional
  • ARIS skills — recommended; without them falls back to scholar-* / arl-* / phd-* or generic subagents; literature depth and review quality degrade
  • codex MCP server — required for autonomous soundness decisions; without it every novelty/design-validity check becomes a human gate the loop cannot pass autonomously
  • Network + PDF access — required for citation verification, arXiv/Semantic Scholar sweeps, and Unpaywall downloads; air-gapped environments will trigger gate pauses

Repo layout

research-orchestrator/
├── SKILL.md                         ← the skill (orchestrator logic)
├── references/
│   ├── stage-skill-map.md           ← research stage → ARIS skill mapping
│   ├── workspace-layout.md          ← .research/ structure + file templates
│   ├── reviewer-attack-checklist.md ← what top-venue reviewers attack
│   ├── figure-discipline.md         ← figure/table standards
│   └── citation-verification.md     ← citation verification protocol
└── README.md

Limitations

  • Token cost: the competitive sweep fans out 3–5 parallel subagents each downloading and parsing PDFs; a full direction sweep can cost $5–20 in API tokens. Complex stages (review loop, ablation planning) with many concurrent subagents can push a full session past $50.
  • codex MCP is a hard dependency for soundness: without it, any soundness-critical decision (novelty, design validity, claim follows from results) becomes a human gate — the loop cannot proceed autonomously past it.
  • Subagent summaries are not guaranteed accurate: if a subagent hallucinates or misreads a paper, the error propagates unless evidence-gating catches it. The ledger and provenance tags reduce this risk but do not eliminate it.
  • Network and PDF access required: citation verification, literature sweeps, and Unpaywall downloads all require outbound internet; paywalled papers fall back to EXISTS-BUT-UNCHECKED status.
  • Long projects accumulate state: after many sessions, .research/ can grow large; periodic manual archiving of artifacts/ and completed decisions is recommended.
  • No automatic rollback: the workspace records everything but does not version-control it automatically; corrupted STATE.md or design docs require manual recovery.

License

MIT — see LICENSE.

Ver o original no GitHub

Bom para

Relacionados