Personal
create-academic-research
An npm scaffolder for research repositories built around four entities – digested papers, one survey, self-contained contributions, and per-venue submissions – after a rewrite that deleted most of the first version.
A creator command that turns an empty directory into a research project with a structure a human and an agent can both navigate. It is one half of a pair: this owns the structure and the formats, and academic-research-skills owns the procedures that operate on them.
- Shape
- npm creator, scaffold only, no other commands
- Model
- Four entities: SOTA, survey, contributions, papers
- Companion
- academic-research-skills
- Repository
- VincenzoImp/create-academic-research
The problem
The first version of this had roughly thirty top-level template directories, about fifteen CSV ledgers, a command-line tool of some eight and a half thousand lines with more than thirty-five subcommands, and thirty-two partly overlapping skills. The design note that opens the rewrite states the failure in one sentence: users and agents get lost, and the structure does not make the research pipeline obvious.
That is a specific kind of failure. Nothing was broken: there was simply more scaffolding than research, and the shape of the work had stopped being visible in the shape of the repository.
What I built
The rewrite is organised around exactly four things, and nothing may live outside them.
SOTA is the set of digested papers: each one a PDF, a synthesis written to a standard form, an authoritative bibliography entry, and its position in a citation graph. Survey is a single LaTeX document that digests every one of those syntheses, groups them by theme and method, and carries the gaps-and-directions section. Contributions are self-contained folders – an analysis, an experiment, a piece of software – each with a report detailed enough to be folded into a paper later. Papers are per-venue submission folders: framing, manuscript on the venue’s template, artifacts packaged to that venue’s badge requirements, correspondence, and the archived rounds.
One bibliography file at the root serves all of them.
Hard parts
A citation exists only if a lookup produced it. Scholarly lookup servers are mandatory rather than optional, digestion cross-checks every configured source, and each digested paper records where its metadata came from. In a workflow where an agent writes prose next to references, this is the property that matters most: a plausible-looking citation with no provenance is the failure mode of the entire category, and the scaffold is built so it cannot occur silently.
Deleting the command surface. The creator now scaffolds and does nothing else: no doctor, no update, no rename, none of the tooling command families. The discipline that those commands used to enforce moves into template READMEs, a single check script, and the skills. The cost is that a project cannot be upgraded in place; the gain is that there is no second implementation of the rules to keep in sync with the first.
Committing the built PDFs. Every LaTeX source keeps its generated PDF beside it, with only auxiliary files ignored. That is deliberate repository bloat, bought so anyone – a co-author, a reviewer, an agent – can read the current state without a working TeX installation.