An open source toolkit for conducting structured, rigorous research with AI agents. Move beyond ad-hoc queries to systematic investigation with quality standards and reproducible methodologies.
Research Kit is a fork of Spec Kit by GitHub, originally built as a personal project to adapt the Specification-Driven Development (SDD) workflow for systematic research.
The deeper motivation behind this project is to demonstrate a simple but powerful idea: AI agents perform significantly better when guided by multiple structured phases and template constraints. Instead of asking an AI to "do research" in a single open-ended prompt, Research Kit breaks the process into 10 distinct phases, each with its own template, quality standards, and output expectations. This structured approach:
- Reduces hallucination by constraining AI output to specific, well-defined templates at each phase
- Improves consistency by enforcing the same methodology across different research topics
- Enables quality control by making each phase reviewable before proceeding to the next
- Produces better results by giving the AI clear context boundaries instead of unbounded instructions
If you've ever noticed that AI gives better answers when you break a complex question into smaller parts, Research Kit applies that principle systematically to the entire research workflow.
For details on what changed from the upstream Spec Kit, see The Fork.
- Origin & Motivation
- What is Research Kit?
- The Problem
- Who It's For
- Key Features
- Quick Start
- Research Workflow
- Research Types
- Supported AI Agents
- Installation
- Research CLI Reference
- Example Output
- Documentation
- Prerequisites
- Troubleshooting
- Contributing
- License
Research Kit is a structured research framework designed for AI agents. It transforms ad-hoc prompting into systematic investigation by providing:
- Multi-phase research workflow - From defining research questions to executing comprehensive studies
- Quality standards enforcement - Built-in principles for source evaluation, methodology rigor, and bias mitigation
- Research type specialization - Tailored approaches for academic, market, technical, and general research
- Reproducible methodologies - Documented approaches that can be validated and replicated
- Citation management - Integrated BibTeX support for proper source attribution
- AI agent integration - Works with Claude Code and Codex CLI
Traditional AI interactions treat research as a single-shot query: you ask a question, get an answer, and hope it's accurate. This approach struggles with:
- Lack of source transparency - Where did this information come from?
- No methodology documentation - How was this answer derived?
- Inconsistent quality - Results vary wildly between queries
- No bias mitigation - Unexamined assumptions baked into responses
- Poor reproducibility - Can't validate or build on previous research
Research Kit solves this by making research a structured, auditable process rather than a black-box interaction.
Research Kit is designed for anyone who needs rigorous, documented research:
- Researchers & Academics - Literature reviews, hypothesis exploration, methodology design
- Business Analysts - Market research, competitive analysis, trend investigation
- Technical Writers - Technology evaluations, framework comparisons, best practices documentation
- Consultants - Client research, industry analysis, strategic recommendations
- Students - Term papers, thesis research, learning new domains
- Product Managers - User research synthesis, feature validation, market positioning
If you need defensible conclusions backed by documented sources and transparent methodology, Research Kit is for you.
Research Kit guides you through a systematic 10-phase process:
- Principles - Establish research quality standards and ethical guidelines
- Define - Articulate research questions, objectives, and scope
- Refine - Clarify ambiguities and sharpen focus (optional)
- Methodology - Design research approach and data collection strategy
- Validate - Review feasibility and identify potential issues (optional)
- Tasks - Break down research into executable activities
- Execute - Conduct research and collect data
- Analyze - Process data and generate statistical insights
- Synthesize - Draw conclusions and answer research questions
- Publish - Create publication-ready outputs (reports, papers, presentations)
Specialized templates and guidance for different research domains:
- Academic Research - Literature reviews, peer-reviewed sources, scholarly rigor
- Market/Business Research - Industry analysis, competitive intelligence, market trends
- Technical Research - Technology evaluations, architecture decisions, implementation strategies
- General Investigation - Open-ended exploration, cross-domain synthesis, curiosity-driven inquiry
Built-in enforcement of research best practices:
- Source Quality - Distinction between primary/secondary sources, peer review status, recency
- Methodology Rigor - Explicit research design, assumption documentation, limitation acknowledgment
- Ethics & Bias - Conflict of interest disclosure, bias mitigation, diverse perspective inclusion
- Citation Standards - Proper attribution with BibTeX format, source accessibility
- Analysis Quality - Transparent frameworks, data interpretation rationale, alternative explanations
- Report Completeness - Executive summaries, methodology sections, supported findings, justified conclusions
Works seamlessly with popular AI coding agents through slash commands and structured prompts.
In addition to slash commands, Research Kit provides custom agents for autonomous multi-step workflows:
| Agent | Purpose | When to Use |
|---|---|---|
| agent-research-assistant | Full SRD workflow orchestrator | Starting new research, guided workflow |
| agent-research-reviewer | Quality assurance specialist | Validating research, checking rigor |
| agent-literature-specialist | Literature review expert | Conducting systematic literature reviews, source evaluation |
| agent-analysis-expert | Data analysis specialist | Statistical analysis, visualization, pattern discovery |
| agent-data-collector | Data collection specialist | Web scraping, API integration, systematic data gathering |
| agent-academic-writer | Academic writing specialist | Creating publication-ready research outputs |
Agent Invocation:
- Use
@agent-namesyntax to invoke a specific agent (e.g.,@agent-research-reviewer) - Agents have specialized knowledge and tools for their domain
- Slash commands suggest relevant agents at completion (e.g., "ask
@agent-research-reviewerto validate the definition")
Agents vs Slash Commands:
- Agents have isolated context and handle complex multi-step workflows autonomously
- Slash commands are lightweight utilities for single-step tasks within your main conversation
Agents are deployed to agent-specific locations (e.g., .claude/agents/) and can be invoked using @agent-name mentions.
Choose your preferred installation method:
Install once and use everywhere:
uv tool install research-cli --force --from git+https://github.com/nguyenvanduocit/research-kit.gitThen use the tool directly:
research init my-research-project
research checkTo upgrade:
uv tool install research-cli --force --from git+https://github.com/nguyenvanduocit/research-kit.gitRun directly without installing:
uvx --from git+https://github.com/nguyenvanduocit/research-kit.git research init my-research-projectLaunch your AI assistant in the project directory. The /research.* commands are available.
Use the /research.principles command to establish your research quality standards:
/research.principles Create principles focused on academic rigor, peer-reviewed sources, bias mitigation, and transparent methodology. Include ethical guidelines for data handling and citation standards.Use the /research.define command to articulate what you want to investigate:
/research.define I need to understand the current state of AI agent frameworks for software development. What are the leading approaches, their strengths/weaknesses, adoption trends, and future directions? Target audience is engineering leadership making tooling decisions.Use the /research.methodology command to plan your research approach:
/research.methodology Conduct academic research focused on peer-reviewed papers, industry reports, and framework documentation. Include quantitative analysis of GitHub stars/activity and qualitative assessment of architectural patterns. Timeline: 2 weeks.Use /research.tasks to create an actionable research plan:
/research.tasksUse the following commands to conduct and complete your research:
/research.execute # Collect data and conduct research
/research.analyze # Analyze collected data
/research.synthesize # Draw conclusions from findings
/research.publish # Create final research outputsResearch Kit implements a structured 10-phase workflow designed to ensure quality, reproducibility, and defensibility:
Define the quality standards that will govern your research:
- Source evaluation criteria (peer review, primary vs secondary, recency)
- Methodology requirements (rigor, documentation, limitations)
- Ethical guidelines (bias mitigation, conflicts of interest, diverse perspectives)
- Citation standards (format, attribution, accessibility)
- Analysis frameworks (interpretation rules, confidence levels, alternative explanations)
- Report requirements (structure, completeness, justification standards)
Output: /principles/research-principles.md
Clearly state what you're investigating and why:
- Primary research question and sub-questions
- Research objectives and success criteria
- Scope and boundaries (what's included/excluded)
- Target audience and intended use
- Background context and motivation
- Key terms and definitions
Output: /research/<research-id>/definition.md
Interactive clarification to address ambiguities:
- Structured questioning to identify underspecified areas
- Scope refinement and boundary clarification
- Assumption surfacing and validation
- Stakeholder alignment on research direction
Output: Updates to definition.md with Clarifications section
Plan how you'll conduct the research:
- Research type selection (academic, market, technical, general)
- Data collection strategy (sources, search terms, inclusion/exclusion criteria)
- Analysis framework (how you'll synthesize findings)
- Timeline and milestones
- Resource requirements
- Quality assurance approach
Output: /research/<research-id>/methodology.md
Check for potential issues before investing effort:
- Source availability and accessibility
- Timeline realism
- Resource constraint validation
- Methodology soundness review
- Bias and blind spot identification
Output: Updates to methodology.md with Validation section
Convert methodology into executable steps:
- Literature search tasks (by domain, source type, time period)
- Data collection activities (interviews, surveys, experiments)
- Analysis tasks (coding, synthesis, pattern identification)
- Writing tasks (sections, drafts, reviews)
- Dependency mapping and parallel work identification
Output: /research/<research-id>/tasks.md
Execute the research methodology to gather data:
- Implement data collection protocols
- Conduct experiments or surveys as designed
- Gather literature and documentary evidence
- Record observations systematically
- Track execution progress and deviations
- Maintain data quality and integrity
Output: /research/<research-id>/execution.md, /research/<research-id>/data/, /research/<research-id>/logs/
Analyze collected data using appropriate methods:
- Clean and prepare data for analysis
- Apply statistical tests and models
- Generate visualizations and figures
- Identify patterns and relationships
- Compare findings with literature
- Document all analysis decisions
Output: /research/<research-id>/analysis.md, /research/<research-id>/figures/, /research/<research-id>/tables/
Integrate findings to answer research questions:
- Connect findings to research questions
- Identify emergent themes and patterns
- Build theoretical contributions
- Develop practical implications
- Assess confidence in conclusions
- Acknowledge limitations honestly
Output: /research/<research-id>/synthesis.md, /research/<research-id>/models/
Transform research into publication-ready formats:
- Generate comprehensive research reports
- Create academic papers for journals
- Develop presentations for stakeholders
- Write executive briefs for decision-makers
- Format citations and bibliographies
- Prepare submission packages
Output: /research/<research-id>/publications/, /research/<research-id>/bibliography.bib
Research Kit supports four specialized research approaches:
Focus: Scholarly rigor, peer-reviewed sources, theoretical frameworks
Best For:
- Literature reviews
- Theory development
- Hypothesis testing
- Academic paper preparation
- Systematic reviews
Standards:
- Prioritize peer-reviewed journals and academic presses
- Document search strategies (databases, terms, filters)
- Use established analytical frameworks (PRISMA, etc.)
- Comprehensive citation with DOIs
- Acknowledge limitations and future research directions
Focus: Industry trends, competitive analysis, business intelligence
Best For:
- Market opportunity assessment
- Competitive landscape mapping
- Customer research synthesis
- Strategic decision support
- Investment due diligence
Standards:
- Balance authoritative sources (industry reports, financial data) with emerging signals (news, social media)
- Triangulate findings across multiple source types
- Distinguish fact from opinion/projection
- Consider source incentives and potential bias
- Include both quantitative metrics and qualitative insights
Focus: Technology evaluation, implementation strategies, architecture decisions
Best For:
- Framework/library comparisons
- Architecture pattern evaluation
- Tool selection decisions
- Best practices documentation
- Technology trend analysis
Standards:
- Prioritize official documentation and maintainer guidance
- Include hands-on testing or proof-of-concept validation
- Document version specificity and compatibility
- Assess community health and long-term viability
- Consider maintenance burden and total cost of ownership
Focus: Open-ended exploration, cross-domain synthesis, curiosity-driven inquiry
Best For:
- Learning new domains
- Exploratory research without fixed hypothesis
- Connecting disparate topics
- Building mental models
- Answering complex "why" or "how" questions
Standards:
- Start broad, narrow based on findings
- Document reasoning for source selection and synthesis
- Acknowledge uncertainty and confidence levels
- Seek diverse perspectives explicitly
- Build clear narrative from evidence to conclusions
Research Kit is optimized for CLI-based AI agents:
| Agent | Support | Notes |
|---|---|---|
| Claude Code | β | Full support with agents and commands |
| Codex CLI | β | Full research workflow support |
- Linux/macOS/Windows
- uv for package management
- Python 3.11+
- Supported AI agent
- Git (optional, for version control)
# Persistent installation
uv tool install research-cli --force --from git+https://github.com/nguyenvanduocit/research-kit.git
# Verify installation
research checkpip install git+https://github.com/nguyenvanduocit/research-kit.git# With uv
uv tool install research-cli --force --from git+https://github.com/nguyenvanduocit/research-kit.git
# With pip
pip install --upgrade git+https://github.com/nguyenvanduocit/research-kit.gitThe research command supports the following options:
| Command | Description |
|---|---|
init |
Initialize a new Research Kit project from the latest template |
check |
Check for installed tools and AI agents |
| Argument/Option | Type | Description |
|---|---|---|
<project-name> |
Argument | Name for your new research project directory (optional if using --here, or use . for current directory) |
--ai |
Option | AI assistant to use: claude or codex |
--ignore-agent-tools |
Flag | Skip checks for AI agent tools |
--no-git |
Flag | Skip git repository initialization |
--here |
Flag | Initialize project in the current directory instead of creating a new one |
--force |
Flag | Force merge/overwrite when initializing in current directory (skip confirmation) |
--skip-tls |
Flag | Skip SSL/TLS verification (not recommended) |
--debug |
Flag | Enable detailed debug output for troubleshooting |
--github-token |
Option | GitHub token for API requests (or set GH_TOKEN/GITHUB_TOKEN env variable) |
# Basic project initialization
research init literature-review
# Initialize with Claude Code
research init market-analysis --ai claude
# Initialize with Codex CLI
research init tech-evaluation --ai codex
# Initialize in current directory
research init . --ai claude
# or use the --here flag
research init --here --ai codex
# Force merge into current (non-empty) directory
research init . --force --ai claude
# Skip git initialization
research init my-research --ai codex --no-git
# Enable debug output
research init my-research --ai claude --debug
# Use GitHub token for API requests
research init my-research --ai claude --github-token ghp_your_token_here
# Check system requirements
research checkAfter running research init, your AI agent will have access to these research commands:
Essential commands for the Research Kit workflow:
| Command | Description |
|---|---|
/research.principles |
Create or update research quality standards and ethical guidelines |
/research.define |
Define research question, objectives, and scope |
/research.methodology |
Design research approach and data collection strategy |
/research.tasks |
Generate actionable research task breakdown |
/research.execute |
Conduct research and collect data systematically |
/research.analyze |
Analyze collected data and generate insights |
/research.synthesize |
Synthesize findings and draw conclusions |
/research.publish |
Create publication-ready outputs (reports, papers, presentations) |
Additional commands for enhanced research quality:
| Command | Description |
|---|---|
/research.refine |
Clarify underspecified areas (recommended before /research.methodology) |
/research.validate |
Review methodology feasibility and identify potential issues (run after /research.methodology, before /research.tasks) |
/research.quality |
Generate custom quality checklists for research validation |
| Variable | Description |
|---|---|
RESEARCH_ID |
Override research ID detection for non-Git repositories. Set to the research directory name (e.g., 001-ai-agent-frameworks) to work on a specific research project when not using Git branches. |
A completed research project generates the following structure:
my-research-project/
βββ principles/
β βββ research-principles.md # Quality standards and ethical guidelines
βββ research/
β βββ 001-ai-agent-frameworks/ # Research project directory
β βββ definition.md # Research question and scope
β βββ methodology.md # Research approach and strategy
β βββ tasks.md # Actionable research breakdown
β βββ execution.md # Research execution log
β βββ analysis.md # Data analysis and insights
β βββ synthesis.md # Conclusions and findings
β βββ publications/ # Publication-ready outputs
β β βββ report.md # Comprehensive research report
β β βββ paper.md # Academic paper (if applicable)
β β βββ presentation.md # Executive presentation
β βββ data/ # Collected research data
β βββ figures/ # Charts and visualizations
β βββ tables/ # Data tables
β βββ bibliography.bib # BibTeX citation database
βββ templates/
βββ definition-template.md # Template for new research questions
βββ methodology-template.md # Template for research approaches
βββ tasks-template.md # Template for task breakdowns
βββ report-template.md # Template for research reports
Research reports follow a standardized structure for clarity and reproducibility:
# Research Report: AI Agent Frameworks for Software Development
## Executive Summary
High-level findings, key conclusions, actionable recommendations (2-3 paragraphs)
## Research Question & Objectives
- Primary question: What are the leading AI agent frameworks for software development?
- Sub-questions: Strengths/weaknesses, adoption trends, future directions
- Success criteria: Comprehensive landscape mapping with actionable recommendations
## Methodology
- Research type: Technical Research
- Sources: Academic papers (10), industry reports (5), framework docs (15), GitHub metrics
- Search strategy: Google Scholar, arXiv, GitHub trending, Stack Overflow surveys
- Analysis framework: Comparative evaluation matrix (features, adoption, maturity, ecosystem)
- Timeline: 2 weeks (Jan 15 - Jan 29, 2025)
## Findings
### Theme 1: Framework Architecture Patterns
- Evidence from sources [1], [3], [7]
- Key insight: Three dominant patterns (agentic, workflow-based, hybrid)
- Supporting data: GitHub star trends, adoption curves
### Theme 2: Adoption Drivers
- Evidence from sources [2], [5], [9]
- Key insight: Developer experience beats raw capability in adoption
[Additional themes...]
## Analysis
- Cross-theme patterns and tensions
- Alternative interpretations considered
- Confidence levels and uncertainty acknowledgment
- Implications for engineering leadership
## Conclusions
- Direct answers to research questions
- Actionable recommendations
- Limitations and caveats
- Future research directions
## References
[1] Smith, J. et al. (2024). "Agentic AI Frameworks: A Survey." Journal of Software Engineering...
[2] Chen, L. (2024). "State of AI Development Tools 2024." Industry Report...
[Full BibTeX in bibliography.bib]- Complete Research-Driven Investigation Methodology - Deep dive into the research process
- Agent Integration Guide - Integration instructions and agent development guide
- Contributing Guide - How to contribute to Research Kit
- Support Resources - Getting help and reporting issues
Before using Research Kit, ensure you have:
- Operating System: Linux, macOS, or Windows
- Python: Version 3.11 or higher (download)
- Package Manager: uv (recommended) or pip
- AI Agent: One of the supported AI coding agents
- Git (optional): For version control and branch-based research organization
Most users will have Python and pip already installed. To install uv:
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"If you're having issues with Git authentication on Linux, install Git Credential Manager:
#!/usr/bin/env bash
set -e
echo "Downloading Git Credential Manager v2.6.1..."
wget https://github.com/git-ecosystem/git-credential-manager/releases/download/v2.6.1/gcm-linux_amd64.2.6.1.deb
echo "Installing Git Credential Manager..."
sudo dpkg -i gcm-linux_amd64.2.6.1.deb
echo "Configuring Git to use GCM..."
git config --global credential.helper manager
echo "Cleaning up..."
rm gcm-linux_amd64.2.6.1.debIf you encounter SSL certificate errors (common in corporate environments):
# Temporary workaround (not recommended for production)
research init my-project --skip-tls
# Better solution: Install certificates
# macOS
pip install certifi
# Linux
sudo apt-get install ca-certificatesIf research command is not found after installation:
# Check uv tool installation
uv tool list
# Reinstall with explicit path
uv tool install research-cli --force --from git+https://github.com/nguyenvanduocit/research-kit.git
# Verify PATH includes uv tools directory
echo $PATH | grep -q ".local/bin" || echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrcIf the CLI doesn't detect your AI agent:
# Check if agent is in PATH
which claude # or codex
# Skip agent check and install anyway
research init my-project --ignore-agent-tools --ai claude- Open an issue on GitHub
- Check the SUPPORT.md guide
- Review agent-specific documentation
We welcome contributions to Research Kit! Here's how you can help:
- Report bugs - Found something broken? Open an issue
- Suggest features - Have ideas for new research types or workflow improvements? We'd love to hear them
- Improve documentation - Help make Research Kit easier to use
- Add agent support - Integrate new AI coding agents
- Enhance templates - Improve research templates and quality standards
- Share research examples - Contribute example research projects
- Read the Contributing Guide
- Check the Code of Conduct
- Look for "good first issue" labels
- Fork the repository and make your changes
- Submit a pull request
# Clone the repository
git clone https://github.com/nguyenvanduocit/research-kit.git
cd research-kit
# Install dependencies with uv
uv sync
# Run the CLI locally
uv run research --help
# Test your changes
uv run research init test-project --ai claudeFor detailed development instructions, see CONTRIBUTING.md.
This project is licensed under the terms of the MIT open source license. Please refer to the LICENSE file for the full terms.
Research Kit is a fork of Spec Kit by GitHub. The original project focuses on Specification-Driven Development (SDD) for software engineering. Research Kit adapts the same multi-phase, template-constrained approach for systematic research workflows.
Special thanks to the GitHub team for creating Spec Kit and demonstrating that structured constraints make AI agents dramatically more effective.
Start conducting rigorous, reproducible research with AI agents today.
uv tool install research-cli --force --from git+https://github.com/nguyenvanduocit/research-kit.git
