# Research Amp Toolkit

A Claude Code toolkit for dissertation-grade academic research workflows. The toolkit's design commitment: every empirical value cites a file on disk, every claim survives a grep against the cited source, and the planning, construction, and verification of a research deliverable are three separately auditable steps rather than one conflated prompt.

Author: Jake Benhart (NC State University, Operations Research). Contact: jebenhar@ncsu.edu. The bundled /pcv skill (Plan-Construct-Verify) is the work of Dr. Michael G. Kay.

License: MIT.

Status: v2.2.0 (2026-10-20). Every push runs the test suite in CI on Linux and macOS.

## Who this is for

PhD students, early-career researchers, faculty advisors, and instructors producing dissertation work, journal submissions, conference papers, and grant proposals where citation accuracy and methodological reproducibility are load-bearing. Optimized for Claude Code on the local machine. Not optimized for general-purpose software engineering, persistent agent memory, or production deployment.

## What is in the toolkit

Twenty-four Claude Code slash commands, organized by workflow phase:

- Setup: /setup (asks about your workspace and writes ~/.claude/toolkit-config.md, which the other commands read)
- Planning: /pcv (structured plan-construct-verify), /quick-ten (the few questions that change a build, asked before it), /coa (multi-perspective adversarial review), /pace (paired-agent verified deliverables)
- Reading and ingestion: /readable (PDF text extraction with grep-citable output), /acquire (download a paper, refuse the wrong document, extract it and grep-check the claimed figures)
- Verification: /audit (citation and numerical accuracy audit), /review (artifact review), /simplify (working-code cleanup), /bulletproof (tests proven able to fail), /guard-hook (hook guards proven able to fail)
- Production: /quarto (slide deck and document generation), /improve (infrastructure-gap scan), /automate (a finished task turned into a skill with a tested script)
- Shipping: /commit (workstream-scoped commit workflow with terminal-scope enforcement)
- Meetings and work lists: /meeting-breakdown (a transcript broken into a per-domain plan), /list-maker (a numbered work list whose numbers never change), /step-by-step (one item at a time, nothing skipped)
- Observation: /run-log (longitudinal command performance), /daily-summary (per-day capture), /weekly-summary (aggregated review)
- Bootstrap: /startup (multi-workstream state briefing), /help

Also included: four optional hooks, copied by install.sh --hooks and never registered (python3 scripts/register_hooks.py prints the settings entries): a usage counter (scripts/usage_counts.py reports its counts), a token-budget warning, a summary-folder note, and a guard against writes to the files your config names (it holds no list of its own). Companion tool, released separately: captioner (alt text for PowerPoint images), https://github.com/jbenhart44/captioner.

## Key documents

- README.md — install, command catalog, contribution guidelines
- POSITIONING.md — who this toolkit is for, who it is not for, what makes it distinct
- DESIGN.md — architectural rationale, command-level design notes, changelog
- EVIDENCE.md — what each claim rests on: reproducible gates, measured usage counts, observed notes
- QUICKSTART.md — minimal install walkthrough
- USAGE_GUIDE.md — command-by-command usage notes
- CITATION.md, CITATION.cff — how to cite the toolkit
- references/preventable_errors.md — twelve error classes the toolkit is built to prevent in academic deliverables
- references/iron_rules.md — consolidated index of every iron rule across the command files

## Key design commitments

- Citation pipeline as the primary gate: deliverables refuse to incorporate unverified numbers or citations
- Planning, construction, and verification are three separately auditable steps
- Multi-perspective adversarial review is a first-class step, not a single-agent self-check
- Text-first architecture: every artifact is plain text (Markdown, YAML, bash); binary formats appear only at the end of the production pipeline
- Forkable per user: every command's prompt lives in a file the user is expected to read and may modify
- No live network on the default execution path; cross-model verification is opt-in
- No co-author attribution to AI assistants on commits; doctorate-holders referred to as "Dr. Surname" in reader-facing artifacts

## How to install

Clone the repository, run `bash install.sh`, then run `/setup` inside Claude Code. It asks about your workspace and writes `~/.claude/toolkit-config.md`. Then run `/startup`.

## How to cite

See CITATION.md or CITATION.cff for citation metadata.

## Repository

https://github.com/jbenhart44/Research-Toolkit
