create-academic-research 0.1.0

package/template/README.md

@@ -0,0 +1,68 @@
+# Academic Research Project
+
+This repository is an academic research project created with
+`create-academic-research`.
+
+The repository is structured for reproducibility, scholarly evidence tracking,
+and LLM-assisted research work. Notebooks are allowed for exploration and final
+narrative analysis, but repeatable logic belongs in `src/`, `scripts/`, and
+tested project code.
+
+## Discipline Scope
+
+This template is discipline-general. Use it for academic research projects in
+any field, then specialize the methods, evidence standards, and venues for the
+actual discipline. The companion `academic-research-skills` package gives
+first-class support to computer science research while keeping the repository
+structure useful for broader academic work.
+
+The repository is agent-neutral. Capability state uses `agent: auto` unless a
+specific agent target is selected with `--agent`.
+
+## Quickstart
+
+Use Python 3.11 or newer.
+
+```bash
+npm install
+python3.11 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e ".[dev]"
+npx academic-research doctor
+```
+
+## Core Folders
+
+- `sources/`: curated papers, reports, metadata, BibTeX, and conversion ledgers.
+- `sota/`: search strategy, screening, literature matrix, synthesis, and gaps.
+- `wiki/`: LLM-maintained durable research memory.
+- `docs/agent/`: active agent workflows, capability profile, and MCP setup.
+- `docs/methodology/`: research design, evaluation plan, and validity threats.
+- `experiments/`: curated experiment registry and run records.
+- `notebooks/`: optional exploratory and narrative notebooks.
+- `outputs/`: final figures, tables, models, and paper-supporting derived assets.
+- `reports/`: proposal, paper, slides, reviews, and rebuttal material.
+- `artifacts/`: open science and artifact evaluation preparation.
+- `src/`: reusable project code.
+
+## Agent Capabilities
+
+Project-local skills and MCP records are managed with:
+
+```bash
+npx academic-research skills presets
+npx academic-research skills install --preset default
+npx academic-research skills list
+npx academic-research skills status
+npx academic-research mcp enable arxiv semantic-scholar openalex
+npx academic-research mcp list
+npx academic-research mcp commands arxiv
+npx academic-research mcp install arxiv
+```
+
+`skills list` reports installed project-local skills. `skills presets` reports
+available install presets. `mcp enable` changes project records. `mcp commands`
+prints external install commands without running them. `mcp install` runs
+external tool installation commands and should be used only after reviewing the
+selected MCP.

package/template/artifacts/artifact-checklist.md

@@ -0,0 +1,7 @@
+# Artifact Checklist
+
+- Code release scope:
+- Data release scope:
+- Environment instructions:
+- License:
+- Reproduction command:

package/template/configs/agent-stack.yaml

@@ -0,0 +1,5 @@
+version: 1
+description: Written by create-academic-research during project creation.
+presets: {}
+mcp_servers: {}
+skill_bundles: {}

package/template/configs/capabilities.yaml

@@ -0,0 +1,4 @@
+agent: auto
+preset: default
+scope: project-local
+mcp_servers: []

package/template/configs/default.yaml

@@ -0,0 +1,15 @@
+project:
+  slug: academic-research-project
+  title: Academic Research Project
+  profile: academic-general
+  package: project_package
+
+paths:
+  sources: sources
+  sota: sota
+  wiki: wiki
+  experiments: experiments
+  outputs: outputs
+
+run:
+  seed: 42

package/template/docs/agent/capability-profile.md

@@ -0,0 +1,6 @@
+# Agent Capability Profile
+
+- Agent target: `auto`
+- Scope: `project-local`
+
+This file is written during project creation.

package/template/docs/agent/mcp-setup.md

@@ -0,0 +1,4 @@
+# MCP Setup
+
+Record active MCP servers, install commands, auth requirements, smoke tests,
+and known risks here.

package/template/docs/agent/output-contracts.md

@@ -0,0 +1,8 @@
+# Output Contracts
+
+- `repro_outputs/`: trusted reproduction evidence.
+- `train_outputs/`: training run evidence.
+- `explore_outputs/`: exploratory variants.
+- `analysis_outputs/`: analysis reports and claim audits.
+- `debug_outputs/`: diagnosis artifacts.
+- `outputs/`: curated paper-facing figures, tables, models, and exportable derived assets.

package/template/docs/agent/research-program.md

@@ -0,0 +1,3 @@
+# Research Program
+
+State the project aim, scope, contribution targets, and current evidence plan.

package/template/docs/data_dictionary/README.md

@@ -0,0 +1,3 @@
+# Data Dictionary
+
+Document dataset fields, provenance, licenses, and known limitations.

package/template/docs/ethics/data-governance.md

@@ -0,0 +1,3 @@
+# Data Governance
+
+Record privacy, consent, platform terms, license, retention, and sharing rules.

package/template/docs/methodology/evaluation-plan.md

@@ -0,0 +1,3 @@
+# Evaluation Plan
+
+Define datasets, baselines, metrics, ablations, and success criteria.

package/template/docs/methodology/research-design.md

@@ -0,0 +1,4 @@
+# Research Design
+
+| rq_id | question | scope | evidence_needed | method | risk | status |
+|---|---|---|---|---|---|---|

package/template/docs/methodology/threats-to-validity.md

@@ -0,0 +1,3 @@
+# Threats To Validity
+
+Track internal, external, construct, conclusion, and reproducibility threats.

package/template/docs/reproducibility/README.md

@@ -0,0 +1,3 @@
+# Reproducibility
+
+Record environments, commands, seeds, data versions, and artifact policies.

package/template/docs/venue/venue-strategy.md

@@ -0,0 +1,3 @@
+# Venue Strategy
+
+Track target venues, fit, review criteria, deadlines, and positioning risks.

package/template/experiments/registry.csv

@@ -0,0 +1 @@
+run_id,date,git_commit,question,hypothesis,command,config,seed,dataset,metric,result,runtime,status,record_path,notes

package/template/experiments/templates/experiment-record.md

@@ -0,0 +1,23 @@
+# Experiment: <run_id>
+
+## Question
+
+<fill: experiment question>
+
+## Hypothesis
+
+<fill: expected result or pattern>
+
+## Command
+
+```bash
+# <fill: exact command>
+```
+
+## Result
+
+<fill: measured result, output path, or failure>
+
+## Interpretation
+
+<fill: claim status, limitations, and next action>

package/template/notebooks/README.md

@@ -0,0 +1,5 @@
+# Notebooks
+
+Use notebooks for exploration, annotation, and narrative analysis. Move reusable
+logic that supports claims into `src/`, and keep notebook outputs synchronized
+with `outputs/`, `analysis_outputs/`, or `experiments/` when they matter.

package/template/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "academic-research-project",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "doctor": "academic-research doctor",
+    "skills:install": "academic-research skills install --preset default",
+    "skills:list": "academic-research skills list",
+    "skills:presets": "academic-research skills presets",
+    "mcp:list": "academic-research mcp list",
+    "mcp:commands": "academic-research mcp commands",
+    "mcp:doctor": "academic-research mcp doctor"
+  },
+  "devDependencies": {
+    "create-academic-research": "^0.1.0"
+  }
+}

package/template/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "academic-research-project"
+version = "0.1.0"
+description = "Academic research project."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "ruff>=0.4"
+]
+analysis = [
+  "numpy>=1.26",
+  "pandas>=2.0",
+  "matplotlib>=3.8",
+  "seaborn>=0.13"
+]
+notebooks = [
+  "ipykernel>=6.0",
+  "jupyterlab>=4.0"
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]

package/template/reports/rebuttal/README.md

@@ -0,0 +1,3 @@
+# Rebuttal
+
+Store reviewer concern maps, rebuttal drafts, and revision plans here.

package/template/reports/reviews/README.md

@@ -0,0 +1,3 @@
+# Reviews
+
+Store internal and external review analysis here.

package/template/sota/gaps.md

@@ -0,0 +1,9 @@
+# Research Gaps
+
+## Open Gaps
+
+<fill: concrete gaps with source IDs or evidence notes>
+
+## Candidate Contributions
+
+<fill: possible contribution claims and failure conditions>

package/template/sota/literature-matrix.csv

@@ -0,0 +1 @@
+source_id,title,authors,year,venue,method,dataset_or_sample,task_or_problem,key_claim,metric_or_result,limitations,relevance,citation_count_or_signal,identifiers,notes

package/template/sota/prisma-flow.md

@@ -0,0 +1,4 @@
+# Review Flow
+
+Use this file for PRISMA-style counts when the project uses a systematic or
+scoping review process.

package/template/sota/screening-decisions.csv

@@ -0,0 +1 @@
+stage,source_id,title,decision,reason,screened_by,date,notes

package/template/sota/search-strategy.md

@@ -0,0 +1,14 @@
+# Search Strategy
+
+## Research Question
+
+<fill: research question or review objective>
+
+## Sources Queried
+
+| Source | Query | Date | Filters | Results | Notes |
+|---|---|---:|---|---:|---|
+
+## Screening Notes
+
+<fill: screening workflow, ambiguity, or reviewer notes>

package/template/sota/synthesis.md

@@ -0,0 +1,9 @@
+# SOTA Synthesis
+
+## Current View
+
+<fill: concise synthesis with source IDs>
+
+## Contradictions
+
+<fill: competing claims or unresolved conflicts>

package/template/sources/bib/citation-audit.csv

@@ -0,0 +1 @@
+citation_key,status,issue,source_id,claim_or_location,expected_fix,checked_on,notes

package/template/sources/bib/references.bib

@@ -0,0 +1 @@
+

package/template/sources/conversion-ledger.csv

@@ -0,0 +1 @@
+source_id,input_path,output_path,tool,command_or_config,conversion_date,quality,checked_pages,known_issues,notes

package/template/sources/source-ledger.csv

@@ -0,0 +1 @@
+source_id,type,title,authors,year,venue,identifiers,raw_path,derived_path,bib_path,status,relevance,evidence_level,quality_notes,added_on,last_checked,notes

package/template/src/project_package/__init__.py

@@ -0,0 +1 @@
+"""Project package."""

package/template/tests/test_project_structure.py

@@ -0,0 +1,25 @@
+from pathlib import Path
+
+
+def test_core_research_structure_exists() -> None:
+    root = Path(__file__).resolve().parents[1]
+    for relative in (
+        "AGENTS.md",
+        "configs/default.yaml",
+        "configs/capabilities.yaml",
+        "docs/agent/capability-profile.md",
+        "notebooks/README.md",
+        "outputs/figures",
+        "outputs/tables",
+        "data/raw",
+        "analysis_outputs",
+        "artifacts/cache",
+        "artifacts/data",
+        "artifacts/models",
+        "artifacts/releases",
+        "sources/source-ledger.csv",
+        "sota/literature-matrix.csv",
+        "wiki/index.md",
+        "wiki/log.md",
+    ):
+        assert (root / relative).exists()

package/template/wiki/contradictions.md

@@ -0,0 +1,3 @@
+# Contradictions
+
+Record conflicts across sources, data, experiments, or interpretations.

package/template/wiki/index.md

@@ -0,0 +1,9 @@
+# Wiki Index
+
+This is the content index for the LLM-maintained project wiki.
+
+## Core Pages
+
+- [[synthesis]]
+- [[open_questions]]
+- [[contradictions]]

package/template/wiki/log.md

@@ -0,0 +1 @@
+# Wiki Log

package/template/wiki/open_questions.md

@@ -0,0 +1,3 @@
+# Open Questions
+
+- What must be resolved before claims can be made?

package/template/wiki/synthesis.md

@@ -0,0 +1,3 @@
+# Project Synthesis
+
+No project-level synthesis has been established yet.