The Problem
Out of the box, Claude Code writes fluent academic prose — which is exactly the danger. It will:
- Invent a citation, DOI, author, or page number that looks real but isn't
- State a statistic or measured value it doesn't actually have
- Overclaim — "causes" where the evidence only licenses "is associated with"
- Drift off the thesis and pad sections with plausible filler
- Quote a source it never read, with no locator
In code, a hallucination breaks the build and you find out. In a manuscript, a hallucinated citation looks correct — and survives to peer review, or print.
The Solution
This kit provides a CLAUDE.md instruction set, deterministic hooks, review agents, and skills that enforce one discipline:
Question → Evidence → Draft → Verify → Cite — every time.
The cardinal rule the whole kit exists to enforce: every claim traces to a real source; never invent a citation, DOI, quote, or quantity; never overclaim beyond the evidence.
Quick Start
# clone into your manuscript repo
git clone --depth 1 https://github.com/tansuasici/claude-research-kit.git /tmp/crk
cp /tmp/crk/CLAUDE.md /tmp/crk/MANUSCRIPT_MAP.md /tmp/crk/CLAUDE.project.md .
cp -r /tmp/crk/.claude /tmp/crk/agent_docs /tmp/crk/tasks .
rm -rf /tmp/crk
Then fill in MANUSCRIPT_MAP.md with your thesis, contribution, target venue, and section plan — it is the single most important file, read first every session — and start a Claude Code session.
Or with the CLI:
npx @tansuasici/claude-research-kit init # install into the current dir
npx @tansuasici/claude-research-kit doctor # check installation health
npx @tansuasici/claude-research-kit skills # list the /skills
npx @tansuasici/claude-research-kit convert # export CLAUDE.md → AGENTS.md (+ Cursor/Windsurf/Aider)
Or as a Claude Code plugin, from the shared tansuasici marketplace:
/plugin marketplace add tansuasici/claude-plugins
/plugin install research-kit@tansuasici
Installed earlier as claude-research-kit from the kit's own marketplace? That install keeps updating; to switch, uninstall it and run /plugin install research-kit@tansuasici.
Next to another Claude kit
The Marketing, Design and Code kits use the same CLAUDE.md and the same hook names, so two kits can't share a folder. install.sh and uninstall.sh stop and change nothing when they find one of those kits in the target folder.
Install this kit into a subfolder instead, and open Claude Code in that subfolder:
bash ~/claude-research-kit/install.sh "$PWD/research"
cd research && claude
Hooks only run from the folder the session opened in. A session opened at the repo root doesn't run the subfolder's hooks, so citation-gate won't check a write under research/ from there.
A copy of one of those kits from before this check doesn't stop: its install.sh or uninstall.sh still replaces or deletes this kit's files.
What CLAUDE.md Enforces
| Rule | What it does |
|---|
| Tiered Session Boot | Loads the manuscript map, thesis, venue, and active task first — not the whole corpus |
| Source-Grounded Writing | The cardinal rule: no invented citations, DOIs, quotes, or quantities — ever |
| Claim Discipline | Every sentence is cited, the author's own argument, or common knowledge — nothing else |
| Protected Claims | Stops for approval before changing the thesis, a reported number, methods, or an argument-bearing citation |
| Verification | Citations resolve → quotes match → claims supported → numbers consistent → cross-refs → compiles |
| Calibrated Language | Matches verbs and quantifiers to what the evidence licenses (suggests ≠ proves) |
| Reviewer Memory | Logs recurring reviewer feedback to tasks/reviews/ and reviews the Top Rules each session |
Hooks
Hooks are shell scripts that run automatically — unlike CLAUDE.md rules (advisory), hooks are deterministic. The kit ships 14 hooks, all wired by default.
Guardrails — block on violation (PreToolUse / Stop):
| Hook | Event | What it does |
|---|
block-fabrication | PreToolUse | Blocks writing a fabricated reference — placeholder/fake-shaped DOIs (10.xxxx, example.com) and empty required .bib fields. Honest prose placeholders ([CITE]) are never blocked |
protect-sources | PreToolUse | Blocks edits to sources/ (raw evidence), data/raw/, and frozen submitted/ snapshots |
branch-protect | PreToolUse | Blocks push to main/master and force pushes |
block-dangerous-commands | PreToolUse | Blocks rm -rf /, git reset --hard, etc. |
citation-gate | PostToolUse | After a .tex/.bib edit: every \cite must resolve in references.bib; every \ref must have a \label. Records the verdict |
compile-gate | PostToolUse | Parses the LaTeX .log for undefined citations/references and errors; records a verdict (opt-in CCK_COMPILE_GATE=1 refreshes via latexmk) |
stop-gate | Stop | Blocks completion when the last citation or compile gate failed (bypass: SKIP_QUALITY_GATE=1) |
Context & observability — inject or warn, never block:
This is the beginning of the README. Read the rest at the original. Read the full README ↗
