Plugin

research

The record side of research-kit: what a research project keeps in its own repository so that a coding agent works from it instead of from memory. Ideas, questions, tasks and findings are Markdown records the flow command moves through their states; the works the project cites are cards in a library that records how far each was read; a dashboard shows both; three working rules say how the agent reviews, designs and debugs. It needs nothing else, and the formal plugin builds on it for a project with a Lean 4 library.

In Claude Code 2.1.275 or later it installs in one step; Install covers every other agent:

/plugin install research --marketplace lividgreen/research-kit

Seven skills: four over a script each, three with no script behind them; the sections below take them one by one, with the commands each script answers.

Records that hold

Ideas, questions, tasks and findings are Markdown files, one per item, that the flow command creates and moves through their states. You capture an idea, frame it as a question with a kill criterion (what would settle it), split the question into tasks, and close each task with what it produced. A finding names its evidence, such as a proved declaration or a script that asserts the result, and the check confirms that the evidence exists.

flow check fails when a hand-edited state leaves a record inconsistent (an active task with no owner, a closed one outside the archive, an answered question answered by nothing), when a record points to an id that does not exist, when a finding’s evidence does not resolve, when a rank has no reason, or when the index is out of date. It checks that the records hold together, not who wrote them: a hand edit that also writes everything its transition would passes, and shows in the diff. It runs offline as a pre-commit hook, and its last line lists what it did not look at, so a passing check never overstates what it covered. A generated index keeps a ranked list of open work with a reason for each rank, and flow state prints the summary a new session reads first, so the agent continues from the top of the list instead of asking where things stand.

The flow skill and its commands

The flow skill, /research:flow in Claude Code.

Views: flow state (the cold-start summary), flow find, flow show ID, flow graph --from ID, flow directions, flow index, flow check. Every command takes --json; flow init is the write behind the setup.

A reference library that refuses an unread citation

library keeps one card per work the project refers to: a paper, a book, a preprint, a dataset, a piece of software. A card records how far the work was actually read, what may be claimed from it and at which page, and what the project noted about it. The reference list of each bound document is tied to the cards, so citing a work that has no card, or one marked unread without naming the source it is known through, fails the check. Optional online lookups (arXiv, Crossref, OpenAlex and others) fill in the metadata, find open copies and watch for new citing work.

The library skill and its commands

The library skill, /research:library in Claude Code.

What goes online lists the hosts each online command calls; nothing else leaves the machine.

A dashboard

dashboard serves the records and the cards as a read-only page on localhost: the ranked list, each record with its links and back-references, each card with its notes and extracts, and the verdicts of flow check and library check. Every page is the answer of a command with --json, so the page and the command line cannot disagree.

The dashboard skill

The dashboard skill, /research:dashboard in Claude Code. dashboard serves on port 8765; --port, --host, --allow-host NAME (another name it answers to, behind a proxy or a tunnel), --root, --component CMD (a command mounted by hand) and --list (what would be mounted) are its flags.

A setup the agent proposes and you approve

/research:research-init inspects the project and the machine, proposes what is missing, and installs nothing without your confirmation. It writes the bindings files, the records and the cards directories, the paragraphs for the agent’s instructions file and the pre-commit hooks, then runs the checks and reports.

The research-init skill

The research-init skill, /research:research-init in Claude Code; with another agent, ask it to set research-kit up in the project. The probe behind it, the research-init skill’s scripts/setup.py probe, writes nothing; the writes are flow init --log WORKLOG.md and library init.

Working rules for the agent

Three skills with no script behind them, each triggered by the conversation itself. method says how to review, what counts as evidence and how to change a target honestly when a wall is hit. design runs a design pass before anything new is built, whenever you say “let’s add X” or “what about Y”. debug insists on the root cause before a fix, and again before anything is called fixed. They came out of one research project and are optional; the tools work without them.

The method, design and debug skills

method, design and debug, as /research:method, /research:design and /research:debug in Claude Code.

The scripts

The four scripts are single Python 3.11 files in their skills’ scripts/ directories, standard library only; the agent runs them through their skills, and the pre-commit hooks run flow check and library check from a copy of their own. A project binds them in flow.toml and library.toml at its root, which The bindings files shows whole; the skills name no project path themselves. The three working rules are optional: the tools neither read nor need them.