Research Agent Starter Kit

Build a local research agent that thinks before writing, checks sources before claiming, and blocks weak formal outputs before delivery.

中文说明

Use it with Codex, Claude Code, Cursor, or any coding agent that can read local files and follow SKILL.md instructions. The kit itself is file-based and local-first; the agent tool you choose may have its own login, subscription, or API-key requirements.

This starter kit is for dissertations, theses, articles, reports, proposals, and structured research projects where AI assistance must stay evidence-aware, auditable, and honest about its limits.

It does not replace source review, ethics/compliance approval, supervisor judgement, peer review, or institutional credentials. Those limits are visible by design.

How It Works

flowchart LR
    A["User task"] --> B["Route skills"]
    B --> C["Source-first check"]
    C --> D["Cognitive map"]
    D --> E["Draft or revise"]
    E --> F["Two-pass self-review"]
    F --> G["Academic integrity preflight"]
    G --> H["Delivery gate"]
    H --> I["Knowledge update"]

    C -. blocks unsupported facts .-> X["Revise evidence"]
    X -. back to source check .-> C
    G -. catches placeholders / fake refs .-> Y["Fix artifact"]
    Y -. back to draft .-> E
    H -. blocks weak formal output .-> Z["Complete required gates"]
    Z -. back to review .-> F

The dashed paths are revision loops. They show where the agent should stop, fix the weak point, and rerun the relevant gate.

The workflow is strict where it matters:

1. Plan before writing — the agent maps the claim, gap, evidence status, warrant, and section role.
2. Write with source boundaries — formal claims require local source evidence or a visible NEEDS VERIFICATION boundary.
3. Review before delivery — drafts go through self-review, integrity checks, and delivery gates before they are treated as usable formal outputs.

What's New

v1.2.0 adds a self-growing knowledge base, local retrieval tools, optional neural vector search, and an academic-integrity preflight gate.

That means the starter kit now covers not only writing and review, but also controlled knowledge-base growth: raw inbox -> growth queue -> compiled wiki -> source-aware retrieval.

Quick Start

If you use Obsidian: Open knowledge-base/ as your Obsidian vault. Do not open the repository root. See Obsidian Setup.

git clone https://github.com/JonasLee12/research-agent-starter-kit.git
cd research-agent-starter-kit

python3 -m venv .venv
source .venv/bin/activate

pip install -r requirements.txt

# AGENTS.md is where you tell the agent what your project is about and which rules it must follow.
cp templates/AGENTS.example.md AGENTS.md
# Edit AGENTS.md with your project topic, sources, rules, and delivery needs.

python scripts/run_skill_evals.py
python scripts/validate_agent_schemas.py
python -m unittest discover -s tests

Optional neural vector retrieval:

pip install -r requirements-vector.txt
bash scripts/run_vector_index.sh

What Problems It Solves

Core Pieces

Scope And Limits

This kit is deliberately strict about what it cannot prove.

• It cannot prove that a source supports a claim without source-section review.
• It cannot turn retrieval results into evidence.
• It cannot access subscription databases such as Scopus, Web of Science, or EBSCO without valid institutional credentials.
• It cannot complete ethics approval, compliance approval, peer review, or supervisor approval.
• It cannot guarantee marks, publication, funding, acceptance, or official approval.
• It cannot stop someone from manually bypassing the workflow outside the agent pipeline.

These limits are part of the design. The system should make weak evidence visible instead of hiding it behind fluent prose.

Validation

The public template currently reports 21/21 skill evaluations passing.
The badge reflects the published template state; rerun the checks after customising the kit.

python scripts/run_skill_evals.py
python scripts/validate_agent_schemas.py
python -m unittest discover -s tests
python scripts/run_behavioral_evidence_checks.py
bash scripts/privacy_check.sh

Optional vector smoke test:

bash scripts/run_vector_index.sh

More Setup

Add project requirements

Place marking criteria, client requirements, ethics/compliance notes, or formal guidance in university-guidance/, compliance/, or your own project-specific folder. See university-guidance/EXAMPLE_RUBRIC_GUIDE.md for the expected style.

Add your own skills

Create a new directory in .agents/skills/your-skill-name/ with a SKILL.md file. Register eval test cases in research-wiki/SKILL_EVAL_REGISTRY.md. See CONTRIBUTING.md for requirements.

Configure Zotero

See research-wiki/ZOTERO_AND_CITATION_WORKFLOW_SPEC.md.

Set up the self-growing knowledge base

Start with knowledge-base/self-growing/README.md, then run:

python scripts/kb_health_check.py
python scripts/build_agent_index.py --rebuild --summary
python scripts/local_retrieval_search.py --rebuild --query "source readiness"

Set up Obsidian safely

Open knowledge-base/ as your Obsidian vault. Do not open the repository root.

For a cleaner personal notebook, copy templates/obsidian-vault/ to a location outside this repository and open the copied folder in Obsidian.

See Obsidian Setup.

Adapt cognitive frameworks

Edit .agents/skills/cognitive-frameworks/SKILL.md to adjust gap classifications, warrant quality tests, or rhetorical moves for your discipline.

Documentation

• Architecture — Full system diagram
• Dual Window Guide — Production and Maintenance window workflow
• Skill Development Guide — How to create and test new skills
• Weekly Literature Gap-Watch Automation — Candidate-only weekly literature monitoring
• Obsidian Setup — Open the clean knowledge layer, not the repository root
• Self-Growing Knowledge Base — Controlled knowledge-base growth workflow
• Retrieval Protocol — How the local retrieval layers work together
• Document Pipeline — Staged checkpoint delivery process
• Software and Plugin Requirements — Required and optional tools

Acknowledgements

See ACKNOWLEDGEMENTS.md for open-source projects and workflows that inspired this system.

License

MIT