Oleafly Research Loop

This is the router for a whole research project. It does two jobs. It fixes the file layout that every other Oleafly research skill reads and writes, so a sweep done in one session is still findable three weeks later. And it tells you which skill to load for the stage you are actually in, so you do not improvise a procedure that already exists.

Load this skill when the work spans more than one step. For a single question ("what is the DOI for this paper") answer it directly and skip the loop.

Step 1. Read the ground before planning

Do this once per session, in this order. It is cheap and it stops you from rebuilding state that already exists.

1. list_notes with {}. Earlier turns may have recorded the bibliography path, the venue, the citation style, or a naming convention. Notes beat guessing.
2. list_files with {}. Look for research/, figures/, review/, and any .bib file. This tells you whether the layout below already exists or has to be created.
3. project_map with {} when the tool is offered. It returns files, sections, labels, bibKeys, macros, inputGraph, unresolvedRefs and unresolvedCites. bibKeys and unresolvedCites are the two fields the research skills depend on. The tool is only available when the document engine advertises a document index, so if it is not in your tool list, fall back to step 4.
4. search_project with {"query": "\\addbibresource"} and then {"query": "\\bibliography{"} for LaTeX, or {"query": "bibliography"} for Typst and Markdown. The hit tells you which .bib file the project actually compiles against. Use that file. Do not create references.bib when another one is already wired in.

If list_files shows no research/ directory, create the layout in step 3 before doing any literature work.

Step 2. Plan the loop with update_todos

update_todos takes {"todos": [{"id": "...", "content": "...", "status": "pending"}]} and replaces the whole list every call, so always send the full list. Statuses are pending, in_progress, completed, cancelled. Keep exactly one item in_progress. The list is capped at 30 items and each content at 240 characters.

Write the plan in loop stages, not in tool calls. A good first plan for "help me write this paper" looks like this.

{"todos": [
  {"id": "sweep", "content": "Build the reading list for the research question", "status": "in_progress"},
  {"id": "related", "content": "Draft related work from the reading list", "status": "pending"},
  {"id": "claims", "content": "Audit the claims in the draft against their sources", "status": "pending"},
  {"id": "figures", "content": "Prepare the figures the argument needs", "status": "pending"},
  {"id": "review", "content": "Self review the full manuscript", "status": "pending"},
  {"id": "submit", "content": "Run the pre-submission checks for the target venue", "status": "pending"}
]}

Update the list when the shape of the work changes, not after every tool call.

Step 3. The project layout every research skill honours

Create what is missing with create_file and {"path": "research/notes", "is_dir": true}. The layout is the contract between skills, so do not rename parts of it to suit one session.

<key> is the citation key, formed as <firstauthor><year>-<slug>, all lowercase ASCII. First author surname, four digit year, then two or three words from the title joined by hyphens. vaswani2017-attention-transformer. Use the same key for the .bib entry, the source note, and the PDF, so the three always line up. If the project's existing .bib uses a different key scheme, follow the project. Consistency inside one bibliography matters more than this convention.

Record the deviation with remember_note when you follow a project scheme instead of this one.

Step 4. Load the skill for the stage you are in

Load one skill at a time with load_skill and {"id": "<skill id>"}. It returns the skill's absolute directory, its file tree, its frontmatter, and its instructions. Read a supporting file with read_skill_file and {"id": "<skill id>", "path": "references/handoffs.md"}.

Full trigger phrases are in references/handoffs.md. Read it when the user's request does not map cleanly onto a row above.

Step 5. Record durable conventions with remember_note

remember_note takes {"content": "..."} and the note survives into later sessions. Save a fact only when a future turn would get the work wrong without it.

Worth saving: the path of the bibliography the project compiles against, the citation key scheme when it differs from this skill's, the target venue and deadline, the citation style, a user preference about tone or terminology, and whether Python is available (step 6).

Not worth saving: anything already visible from project_map or list_files, the content of a paper, or a step you are about to do anyway. Notes are read on every turn, so noise there is expensive. Remove a stale one with forget_note and its id from list_notes.

Step 6. Check Python once before any vendored script

Several vendored skills ship Python scripts. Check the interpreter once per session, before the first script, not before each one.

Call run_command with {"command": "python3 --version"}.

• Exit code 0 and a version of 3.11 or newer means the scripts will run. Save it with remember_note and {"content": "python3 <version> is available for vendored skill scripts"}.
• A version older than 3.11 means paper-lookup and scientific-writing scripts will fail. Use the native Oleafly tools instead and tell the user which step was skipped.
• Command not found means no Python. Do the work with literature_search, verify_citation and project_library_search alone. Tell the user plainly that the deeper database coverage needs Python 3.11 or newer on their PATH, and do not try to install it.

run_command runs one shell line from the project root through the login shell, with a 120 second timeout and a 200 KiB output cap. Every call asks the user for approval under the default policy, so batch related work into one command rather than issuing five. When a script produces more than a screenful, redirect it to a file under research/ and read it back with read_file, which is cheaper and does not get truncated at 200 KiB.

Scripts live inside the skill directory, not the project, so always call them by absolute path with the directory load_skill returned.

python3 "<skill dir>/scripts/search_openalex.py" "graph neural network expressivity" --limit 25 -o research/sources/openalex-raw.json

Quote the path. Skill directories can contain spaces.

Step 7. Read papers in parallel with spawn_agent

Reading ten papers in one context is slow and the details blur. Spawn one agent per paper when you have more than three to read.

spawn_agent takes {"task_name": "read_vaswani2017", "prompt": "..."} and returns immediately. The prompt must be self contained. The subagent shares your project tools and approval gates, and it cannot spawn agents of its own.

A prompt that works:

Read research/sources/vaswani2017-attention-transformer.pdf with read_file.
Write research/notes/vaswani2017-attention-transformer.md containing:
the problem the paper attacks, the method in three sentences, the evidence
offered, the stated limitations, and one line on how it relates to
<the project's research question>.
Do not edit any other file. Reply with the three sentence method summary.

Give each agent a distinct output path so two agents never write the same file. Collect with wait_agent and {"timeout_ms": 300000}, which returns whichever finishes first. Then close_agent with {"agent": "<id or task path>"}, because finished agents keep counting toward the concurrency limit until closed.

Do not spawn agents for work that mutates the manuscript. Parallel writes to the same section conflict and the loser is silently discarded.

Failure handling

Done when

• The plan in update_todos reflects the stages actually remaining, with one item in_progress.
• research/, figures/ and any review/ directories the work needs exist.
• The bibliography path in use is the one the document compiles against, confirmed with project_map or search_project.
• Any convention a later session would need is saved with remember_note.
• The right stage skill has been loaded and its procedure followed, not paraphrased.
• compile is green, or the user has been told exactly what is broken and why.

Reference files

• references/handoffs.md maps user phrasing to a skill id.
• references/project-layout.md gives the file formats, key rules, and provenance fields in full.
• references/tooling.md covers approval behaviour, subagent limits, and the vendored script surface.
• assets/reading-list.md, assets/source-note.md and assets/claims.md are the starting templates for the three shared files.

From a terminal

Outside the app (a terminal, or a coding agent with a shell), the oleafly command does the same work. Always pass --json and check ok.