agentleFS
Xuzhen-LiXuzhen-Li/literature-review-skills/skills/review-orchestrator/SKILL.md

review-orchestrator

Skill2 starsChanged 35 days agoMITView on GitHub

Reports the current literature-review stage from project.yaml and LOG.md, routes to exactly one next skill, and blocks advancement past an unpassed human gate. Trigger on "continue the review", "what is the next step", "where are we in the review", or "start the review workflow". Do not use it to draft prose, invent references, build a search string, or screen records.

4 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

9 rules. 0 are common, 4 are distinctive, and 5 are very specific to this project.

  • 0

    Common

    Most of the 4 edited versions we read keep these.

  • 4

    Distinctive

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Use this skill at the start of a session and whenever the user asks what to do next.

    line 22
  2. Very specific:

    Read project.yaml. A gate is passed only when its line is the YAML boolean true (topic_lock: true).

    line 38
  3. Very specific:

    Read LOG.md from the bottom.

    line 39
  4. Very specific:

    After final_submit: true with no decision letter, the report is: waiting for the journal.

    line 83
  5. Distinctive:

    No DOI, count, or journal metric was added to the report from memory.

    line 114
  6. Distinctive:

    Do not fabricate records, hit counts, or reviewer comments.

    line 118
  7. Distinctive:

    Do not mark a gate true because the draft "looks ready".

    line 119
  8. Very specific:

    Do not delete LOG.md lines or other keys in project.yaml.

    line 120
  9. Distinctive:

    Do not ask the user to log in to a database or Zotero as a prerequisite.

    line 121

“Common” is measured: kept by at least 6 in 10 of the 4 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Review orchestrator

Opening

On first use in a project, say this verbatim:

I am the review orchestrator. I read the project file and the decision log, name the single next skill, and I do not pass a gate for you.

When to use

Use this skill at the start of a session and whenever the user asks what to do next. It does not perform the next skill's work in the same breath as the status report. After the report, follow only the routed skill's SKILL.md.

Inputs (paths) / Preconditions

  • <project>/project.yaml and <project>/LOG.md when they exist.
  • Gate names and pass rules in the suite file shared/gates.md (suite root is two levels above this file after symlinks are resolved). The gate keys are listed below so this skill still runs if shared/ is not installed beside it.
  • Output paths named in the routing table. Do not create those files here.

<project> is the review folder. If the user gives a path, use it. Else if ./project.yaml exists, use .. Else route to review-project-setup and ask where to create the folder. Do not guess a path.

Entry without a project

If there is no project.yaml, ask what the user already has before routing to setup (table in docs/START_HERE.md at the suite root): a draft goes to review-writing, a near-final manuscript to journal-selection, a decision letter to reviewer-response. Only a topic, or their own paper set, goes to review-project-setup.

Procedure (numbered steps)

  1. Read project.yaml. A gate is passed only when its line is the YAML boolean true (topic_lock: true). Missing, false, "true", or yes means not passed.
  2. Read LOG.md from the bottom. Do not treat an agent line as a user confirmation. Gate lines end with | human.
  3. Walk routing rows 1 through 17 in order. Row 0 is this skill and is never the destination. The first row whose condition is true is the next skill. Later files do not cancel an earlier failed gate: if 09-draft/ has prose but topic_lock is not true, route back to review-scoping-and-gaps. review-writing is not a routing row. Name it as the next skill only when the user asks to rewrite or restructure an existing draft, fix paper-by-paper listing or template prose, or revise a Word file with live citations; it still respects every earlier gate in a project.
  4. Print the status report (template below) and stop. Name the skill and the first action from that skill. Do not start a second skill in this turn.
  5. If the user then confirms a gate in this chat, record it only when every file named for that gate in shared/gates.md already exists and scripts/check_gate_phrase.py prints OK gate phrase for that reply. The reply must be the exact sentence, as the whole message or as its only line. Set the boolean, append one log line, and route again. Otherwise leave the boolean false. institutional_access is optional and has no required file.

Status report:

Project: <title or path>
Review type: <narrative|systematic|scoping|umbrella|unknown>
Passed gates: <list or none>
Current stage: <skill name>
Next skill: <skill name>
Why: <one sentence naming the missing file or the unpassed gate>
Also due: <figure-permissions if the ledger has adapted/reused rows still needed, else none>
Do not skip to: <the skill after next>

Routing

#SkillEnter when
0review-orchestratorNever selected. It only runs this table.
1review-project-setupproject.yaml is missing, or has no review_type, or project_confirmed is not in LOG.md. institutional_access is optional and never blocks.
2review-scoping-and-gapstopic_lock is not true.
3search-strategy-buildertopic_lock is true and search_lock is not true.
4search-export-and-dedupsearch_lock is true and 02-records/library.csv or 02-records/prisma_counts.json is missing.
5literature-screeningThe library exists and (inclusion_lock is not true, or 03-screening/screening.csv, 03-screening/prisma_flow.md, or 03-screening/included.tsv is missing). When review_type is narrative, also enter while 03-screening/core_decision.tsv, 03-screening/not_read.tsv, or 03-screening/cap_overflow.tsv is missing.
6zotero-library-syncinclusion_lock is true, included.tsv exists, and (04-library/pdf_status.csv is missing or lacks a row for any included record_id, or 04-library/oa_check.csv has a paper without a PDF and 04-library/oa_after_retry.csv is missing or a row listed in 04-library/agent_retry.tsv has an empty agent_retry in 04-library/oa_after_retry.csv (meaning the agent has not retried it with its own tools yet; rows not in agent_retry.tsv never block), or 04-library/fulltext_need.tsv or 04-library/please_fetch.md is missing, or use_zotero is true and 04-library/collection_checklist.tsv is missing or has a user_confirmed cell that is not yes). Papers still on the please-fetch list do not block: reading continues using the abstract.
7paper-deep-readingSome included record_id has no 05-reading/*.md file containing that id, and either LOG.md has no no-PDF skip line for it or a PDF has since arrived (04-library/uploads/<record_id>.pdf exists, or its local_path in pdf_status.csv is now filled). A skip only stands while the paper still has no PDF.
8exemplar-review-analysisEvery included record has a note and 06-exemplars/style_brief.md is missing.
9review-outline-builderThe style brief exists and (outline_lock is not true, including when 07-outline/outline.md is still Status: draft, or review_type is systematic and 07-outline/systematic_methods_checklist.md is missing).
10review-figures-and-tablesoutline_lock is true and (08-figures/figure_plan.md or 08-figures/figure_ledger.csv is missing, or an original ledger row has no SVG and PDF). Fig. 1 uses 08-figures/fig-1.svg and fig-1.pdf. Table 1 uses table-1. Box 1 uses box-1. A panel letter stays on the slug (Fig. 2a is fig-2a).
11review-section-drafterThe figure files exist and any non-structural ## S<n> section in the outline lacks 09-draft/S<nn>-*.md containing Status: checked. Structural titles start with Acknowledgements, Acknowledgments, Funding, or Author contributions. Limitations and Next questions are required sections, not structural.
12journal-selectionEvery required section file is checked and journal_lock is not true.
13exemplar-review-analysisjournal_lock is true and 06-exemplars/style_brief.md does not contain both Refreshed after journal lock: yes and the recommended journal name.
14manuscript-polishingjournal_lock is true, the style brief has that refresh line for the recommended journal, and 10-polish/manuscript_polished.docx is missing.
15figure-permissions10-polish/manuscript_polished.docx exists and figure_ledger.csv has an adapted or reused row whose permission_status is not granted or not_required. Before that file exists, keep walking and list this skill under "Also due".
16submission-packageThe polished manuscript exists, open permission rows are cleared or the ledger has no adapted/reused rows, and 13-submission/ is empty or final_submit is not true.
17reviewer-responseThe user supplies a decision letter, or 14-revision/decision_letter.md, .txt, or .pdf exists, and 14-revision/response_to_reviewers.docx is missing or the user says a new letter arrived.

An optional post-export cluster pass is not a row. After 02-records/library.csv exists, the user may ask review-scoping-and-gaps to write 00-scope/export_clusters.md. That pass may ask to reopen topic_lock. It does not run unless the user asks, and it does not replace the question-first scope report. Note export into the user's library is also not a row. It runs only after the user asks zotero-library-sync.

After final_submit: true with no decision letter, the report is: waiting for the journal. Do not invent a decision. The user submits the package. This skill never uploads it.

Human gate(s)

Enforce these six, plus the optional institutional_access when the user asked for it. Do not add others. Questions and required files are in shared/gates.md.

KeyOwner
institutional_access (optional)review-project-setup
topic_lockreview-scoping-and-gaps
search_locksearch-strategy-builder
inclusion_lockliterature-screening
outline_lockreview-outline-builder
journal_lockjournal-selection
final_submitsubmission-package

check_gate_phrase.py printing OK means the sentence matches. It does not pass the gate by itself. Only that user sentence, written to project.yaml and LOG.md, passes a gate.

Outputs (exact paths + formats)

The status report is the reply to the user. Do not write a second status file. The only edits this skill may make are a gate boolean the user just accepted and one appended LOG.md line:

YYYY-MM-DD | review-orchestrator | <gate key> passed: <the exact sentence> | human

Quality checklist

  • The next skill is the first matching row from row 1 downward, not the skill the user finds most interesting.
  • An unpassed earlier gate beats a later file that already exists.
  • The report names a path that is missing or a gate that is false.
  • No DOI, count, or journal metric was added to the report from memory.

Guardrails

  • Do not fabricate records, hit counts, or reviewer comments.
  • Do not mark a gate true because the draft "looks ready".
  • Do not delete LOG.md lines or other keys in project.yaml.
  • Do not ask the user to log in to a database or Zotero as a prerequisite. Do not run database logins, payments, copyright transfer, or the journal Submit button.

Next step

The single skill named in the status report.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.