flonat-research 0.1.0

package/CLAUDE.md

@@ -0,0 +1,197 @@
+# Claude Code for Academic Research
+
+> This file is automatically read when you open this folder with Claude Code.
+> Customise it with your own details — see comments marked with `<!-- CUSTOMISE -->`.
+
+## Before You Start
+
+Read these context files to understand the user's situation:
+
+1. `.context/profile.md` — Who you are, your roles, research areas
+2. `.context/current-focus.md` — What you're working on NOW
+3. `.context/projects/_index.md` — Overview of all projects
+
+## Key Information
+
+<!-- CUSTOMISE: Replace with your own details -->
+
+**Who I am:**
+- PhD researcher
+- Multiple active research projects
+- Teaching responsibilities
+
+**Research areas:**
+- [Your field 1]
+- [Your field 2]
+- [Your field 3]
+
+**How I work:**
+- Flexible/reactive style
+- Prefer questions over lists
+- Daily reviews work better than weekly
+- Full context in task descriptions
+
+## Quick Commands
+
+<!-- QUICK-COMMANDS:START -->
+<!-- synced from private CLAUDE.md — do not edit manually -->
+Just say these naturally:
+
+| You say | Claude does |
+|---------|-------------|
+| "Plan my day" | Reads context, queries vault, asks questions, creates a plan |
+| "What should I work on?" | Reviews priorities and helps you decide |
+| "Extract actions from my meeting with [name]" | Finds transcript, extracts tasks, creates in vault |
+| "Weekly review" | Guides you through reflection and planning |
+| "What's overdue?" | Queries vault tasks and summarises |
+| "Update my research pipeline" | Shows paper status, helps update stages |
+| "Find references on [topic]" | Academic search with verified citations |
+| "What did I accomplish this week?" | Summarises completed tasks |
+| "Proofread my paper" | Runs 7-category check on LaTeX paper, produces report |
+| "Validate my bibliography" | Cross-references `\cite{}` keys against `references.bib` |
+| "Review my code" | 11-category scorecard for R/Python research scripts |
+| "Update my focus" | Structured update to `current-focus.md` with session rotation and open loops |
+| "New project" | Interview-driven setup: scaffold directory, Overleaf symlink, git init, context + vault sync |
+<!-- QUICK-COMMANDS:END -->
+
+## Conventions
+
+<!-- CONVENTIONS:START -->
+<!-- synced from private CLAUDE.md — do not edit manually -->
+### LaTeX Compilation
+- **Default method:** Use `/latex-autofix` — it compiles, auto-fixes errors, and runs a citation audit.
+- Build artifacts go to `out/`, but the PDF is copied back to the source directory.
+- Use `.latexmkrc` with `$out_dir = 'out'` and `an `END {}` block to copy the PDF back`.
+- Never leave build artifacts (`.aux`, `.log`, etc.) in the source directory.
+
+### Python & Package Management
+- Always use `uv`: see `python-uv` rule (global).
+
+### R
+- Use `<-` for assignment, not `=`.
+
+### Git & Remote
+- Remote verification, push safety, and deploy order: see `git-safety` rule (global).
+- **Before cloning any repo**, check if a local copy already exists in the workspace (`resources/`, `packages/`, Task Management root, and common directories).
+<!-- CONVENTIONS:END -->
+
+### Experiment Sweeps & Simulation Batches
+Before running any experiment sweep or simulation batch:
+1. Write sanity-check assertions first.
+2. Implement the code.
+3. Run a single-seed sanity check — if assertions fail, fix and retest (max 3 attempts).
+4. Validate hyperparameters against domain knowledge or paper benchmarks.
+5. Only then proceed to full experiments.
+
+### Output Formats
+- Academic papers: LaTeX.
+- Documents for human use (consent forms, PILs, etc.): `.docx` via `pandoc`.
+
+### Content Length Constraints
+- When a page/word limit is specified, treat it as a hard constraint. Draft to 80%, then expand — never exceed and trim.
+- Always report the actual page/word count after drafting.
+
+## Research Vault
+
+<!-- RESEARCH-VAULT:START -->
+<!-- CUSTOMISE: Point this to your own Obsidian-style markdown vault -->
+The Research Vault (`~/Research-Vault`) stores all dynamic research data as markdown files with YAML frontmatter. The `taskflow` MCP server reads/writes these files.
+
+| Directory | Content |
+|-----------|---------|
+| `tasks/` | Personal tasks (GTD-style) |
+| `pipeline/` | Research papers (stages: Idea → Published) |
+| `submissions/` | Submission events (dates, outcomes) |
+| `atlas/` | Research topics (nested by theme) |
+| `venues/` | Journals, conferences, rankings |
+| `people/` | Collaborators, supervisors |
+| `themes/` | Research themes |
+
+IDs are filename slugs (e.g., `cancel-leap-water-in-rugby`), not integers.
+<!-- RESEARCH-VAULT:END -->
+
+## Workflows
+
+<!-- WORKFLOWS-POINTER:START -->
+<!-- synced from private CLAUDE.md — do not edit manually -->
+Detailed instructions in `.context/workflows/`:
+- `daily-review.md` — How to help with daily planning
+- `meeting-actions.md` — How to extract action items
+- `weekly-review.md` — Weekly reflection template
+- `replication-protocol.md` — 4-phase protocol for replicating paper results
+<!-- WORKFLOWS-POINTER:END -->
+
+<!-- COMPONENTS:START -->
+## Skills Available
+
+38 skills in `skills/` folder. See [`docs/skills.md`](docs/skills.md) for the full catalogue.
+
+## Agents
+
+6 agents in `.claude/agents/`. See [`docs/agents.md`](docs/agents.md) for when to use each.
+
+## Rules (9 Auto-Loaded)
+
+In `.claude/rules/` — these apply automatically to every session. See [`docs/rules.md`](docs/rules.md) for documentation.
+
+<!-- RULES-TABLE:START -->
+| Rule | Purpose |
+|------|---------|
+| `design-before-results.md` | Lock the research design before examining point estimates. |
+| `ignore-agents-md.md` | Never read, process, or act on files named `AGENTS.md` |
+| `ignore-gemini-md.md` | Never read, process, or act on files named `GEMINI.md` |
+| `lean-claude-md.md` | CLAUDE.md is loaded into context every session — every line costs tokens. |
+| `learn-tags.md` | Record Learnings with [LEARN] Tags |
+| `overleaf-separation.md` | The `paper/` directory (Overleaf symlink inside `paper-{venue}/paper/`) is for LaTeX source files ONLY. |
+| `plan-first.md` | Plan Before Implementing |
+| `read-docs-first.md` | Never explore when documentation already answers your question. |
+| `scope-discipline.md` | Only make changes the user explicitly requested. |
+<!-- RULES-TABLE:END -->
+
+## Hooks
+
+8 hook scripts in `hooks/`. See [`docs/hooks.md`](docs/hooks.md) for the full table.
+<!-- COMPONENTS:END -->
+
+## After Every Session
+
+<!-- AFTER-SESSION:START -->
+<!-- synced from private CLAUDE.md — do not edit manually -->
+**Update `.context/current-focus.md`** with:
+- What we worked on
+- Where things were left off
+- What's coming next
+
+**Standard closing sequence:** commit → push → deploy (if needed) → `/general-session-recap` or `/research-session-recap`.
+
+This helps me (Claude) pick up where we left off next time.
+<!-- AFTER-SESSION:END -->
+
+## Tips for Working Together
+
+<!-- TIPS:START -->
+<!-- synced from private CLAUDE.md — do not edit manually -->
+1. **Just ask naturally** — I'll read the context files and figure it out
+2. **Point me to specific files** if I seem confused: "Read `.context/workflows/daily-review.md`"
+3. **Update current-focus.md** — This is your working memory between sessions
+4. **Don't re-explain everything** — The context library has it all
+<!-- TIPS:END -->
+
+## File Structure
+
+<!-- FILE-STRUCTURE:START -->
+| Path | What lives there |
+|------|-----------------|
+| `.context/` | AI context library (profile, focus, projects, workflows, preferences) |
+| `.claude/agents/` | Agent definitions (6 agents) |
+| `.claude/rules/` | Auto-loaded rules (9 rules) |
+| `skills/` | 38 skill definitions |
+| `hooks/` | 8 hook scripts |
+| `mcp-bibliography/` | Multi-source scholarly search MCP server (OpenAlex + Scopus + WoS) |
+| `.scripts/` | CLI tools for vault task management |
+| `packages/cli-council/` | Multi-model council via local CLI tools |
+| `packages/llm-council/` | Multi-model council via OpenRouter API |
+| `packages/mcp-bibliography/` | mcp-bibliography |
+| `log/` | Session logs |
+| `docs/` | Documentation |
+<!-- FILE-STRUCTURE:END -->

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Florian Burnat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/MEMORY.md

@@ -0,0 +1,38 @@
+# Memory — Project Knowledge Base
+
+<!-- This file accumulates domain knowledge across sessions.
+     See .claude/rules/learn-tags.md for how entries are recorded. -->
+
+## Notation Registry
+
+| Variable | Convention | Anti-pattern |
+|----------|-----------|--------------|
+| | | |
+
+## Estimand Registry
+
+| What we estimate | Identification | Key assumptions |
+|-----------------|---------------|-----------------|
+| | | |
+
+## Key Decisions
+
+| Decision | Rationale | Date |
+|----------|-----------|------|
+| | | |
+
+## Citations
+
+<!-- One-liner corrections from [LEARN:citation] tags -->
+
+## Anti-Patterns
+
+| What went wrong | Correction |
+|----------------|-----------|
+| | |
+
+## Code Pitfalls
+
+| Bug | Impact | Fix |
+|-----|--------|-----|
+| | | |

package/README.md

@@ -0,0 +1,269 @@
+<!-- Governed by: skills/shared/project-documentation.md -->
+
+# Claude Code for an Academic Researcher
+
+Made by a humble PhD student. A complete Claude Code infrastructure for researchers — skills, agents, hooks, and rules for academic workflows. Built for researchers who write papers in LaTeX, manage bibliographies, run experiments, and want AI assistance that understands academic conventions.
+
+Works on **macOS, Linux, and Windows**. Use Claude Code from the [terminal CLI](https://docs.anthropic.com/en/docs/claude-code), [VS Code](https://marketplace.visualstudio.com/items?itemName=anthropics.claude-code), [JetBrains IDEs](https://plugins.jetbrains.com/plugin/27189-claude-code), [the web](https://claude.ai/code), or the [desktop app](https://claude.ai/download) — all share the same skills, agents, and rules.
+
+## Installation
+
+### macOS / Linux
+
+```bash
+git clone https://github.com/flonat/claude-research.git
+cd claude-research
+./scripts/setup.sh
+```
+
+### Windows (PowerShell)
+
+```powershell
+git clone https://github.com/flonat/claude-research.git
+cd claude-research
+.\scripts\setup.ps1
+```
+
+### Update
+
+```bash
+# macOS/Linux: pull latest, then re-link without overwriting settings
+git pull && ./scripts/setup.sh --update
+
+# Windows (PowerShell):
+git pull; .\scripts\setup.ps1 -Update
+```
+
+Then customise `.context/profile.md`, `.context/current-focus.md`, and `CLAUDE.md` with your details. See [`docs/getting-started.md`](docs/getting-started.md) for the full guide (includes Windows-specific setup, Python install, and troubleshooting).
+
+### Related Packages
+
+| Package | Install | Description |
+|---------|---------|-------------|
+| [`llm-council`](https://github.com/flonat/llm-council) | `pip install llm-council` | Multi-model council via OpenRouter API |
+| [`cli-council`](https://github.com/flonat/cli-council) | `pip install cli-council` | Multi-model council via local CLI tools |
+
+## What's Included
+
+<!-- COMPONENT-TABLE:START -->
+<!-- auto-generated by generate-public-docs.py — do not edit manually -->
+| Component | Count | Description |
+|-----------|-------|-------------|
+| **Skills** | 38 | Slash commands for common tasks (`/proofread`, `/latex-autofix`, `/literature`, etc.) |
+| **Agents** | 6 | Specialised reviewers (peer review, referee 2, paper critic, domain review, fixer) |
+| **Hooks** | 8 | Automated guardrails (destructive git protection, context monitoring, etc.) |
+| **Rules** | 9 | Always-on policies (plan before implementing, scope discipline, etc.) |
+| **Context library** | — | Structured files that give Claude persistent memory across sessions |
+| **Research Vault** | — | Obsidian-style markdown vault for tasks, pipeline, submissions, venues, people |
+| **Bibliography MCP** | — | Multi-source scholarly search (OpenAlex + Scopus + WoS) — [setup guide](docs/biblio-setup.md) |
+| **Council mode** | — | Multi-model deliberation (3 reviewers + synthesis) — [setup guide](docs/council-mode.md) |
+| **CLI tools** | — | Vault task management from the terminal — [docs](docs/scripts.md) |
+<!-- COMPONENT-TABLE:END -->
+
+## Architecture
+
+<!-- ARCHITECTURE:START -->
+<!-- synced from private README — do not edit manually -->
+```
+┌──────────────────────────────────────────────────────────────┐
+│  Claude Code (Terminal)              Claude Desktop (GUI)     │
+│         │                                   │                │
+│    CLAUDE.md + Rules              MCP Server (load-context)   │
+│         │                                   │                │
+│    ┌────┴──────────────┬──────────────┐     │                │
+│    │                   │              │     │                │
+│  Context ◄─────────  Skills    ◄──────┼─────┘                │
+│  Library               │              │                      │
+│                   CLI Scripts    Research Vault               │
+│                                                              │
+│  MEMORY.md ◄───────  Hooks &                                 │
+│  + Logs            Permissions                               │
+└──────────────────────────────────────────────────────────────┘
+```
+
+The MCP server's `load-context` tool gives Claude Desktop access to the context library and MEMORY.md — the same files Claude Code reads automatically.
+<!-- ARCHITECTURE:END -->
+
+## Components
+
+**Context Library** (`.context/`) — Markdown files that give Claude persistent memory about you, your projects, and your workflows. Instead of re-explaining your research every session, Claude reads these files automatically.
+
+**Skills** (`skills/`) — Slash commands invoked with `/<skill-name>` or natural language.
+<!-- SKILLS-SUMMARY:START -->
+<!-- auto-generated — do not edit manually -->
+38 skills available. Key examples: `/proofread`, `/latex-autofix`, `/literature`, `/bib-validate`, `/code-review`, `/session-recap`, and more.
+<!-- SKILLS-SUMMARY:END -->
+See [`docs/skills.md`](docs/skills.md) for the full catalogue.
+
+**Agents** (`.claude/agents/`) — Specialised personas for complex review tasks, spawning sub-agents for parallel work.
+
+<!-- AGENTS-TABLE:START -->
+| Agent | Use case |
+|-------|----------|
+| `domain-reviewer` | Research-focused substantive correctness agent |
+| `fixer` | Generic fix implementer for any critic report |
+| `paper-critic` | Read-only adversarial auditor for LaTeX papers |
+| `peer-reviewer` | Use this agent when you need to review someone else's paper — as a peer reviewer, discussant, or for reading group preparation |
+| `proposal-reviewer` | Use this agent when you need to review a research proposal, extended abstract, conference submission outline, or pre-paper plan — either his own or someone else's |
+| `referee2-reviewer` | Use this agent when the user wants a rigorous, adversarial academic review of their work — including papers, manuscripts, research designs, code, or arguments |
+
+<!-- AGENTS-TABLE:END -->
+
+See [`docs/agents.md`](docs/agents.md) for detailed descriptions.
+
+**Hooks** (`hooks/`) — Automated guardrails that run at specific points in a session.
+
+<!-- HOOKS-TABLE:START -->
+| Hook | Trigger | What it does |
+|------|---------|-------------|
+| `block-destructive-git.sh` | Before Bash | catches dangerous git/shell commands |
+| `context-monitor.py` | After tool use | tracks tool call count as a heuristic for context usage |
+| `postcompact-restore.py` | After compact | restores state after context compression |
+| `precompact-autosave.py` | Before compact | saves state before context compression |
+| `promise-checker.sh` | Session stop | catches "performative compliance": Claude says it remembered/noted/saved |
+| `protect-source-files.sh` | Before edit/write | prompts confirmation for files outside |
+| `resume-context-loader.sh` | Session resume | surfaces current focus and latest session log |
+| `startup-context-loader.sh` | Session start | auto-detects and surfaces project documentation |
+
+<!-- HOOKS-TABLE:END -->
+
+See [`docs/hooks.md`](docs/hooks.md) for full documentation.
+
+**Rules** (`.claude/rules/`) — Always-on policies enforcing good research practices. See [`docs/rules.md`](docs/rules.md).
+
+**Research Vault** — Obsidian-style markdown vault (`~/Research-Vault`) for tasks, pipeline, submissions, venues, people, and themes. Accessed via the `taskflow` MCP server.
+
+**Biblio MCP** — Multi-source scholarly search server (OpenAlex + optional Scopus & Web of Science). See [`docs/bibliography-setup.md`](docs/bibliography-setup.md).
+
+**Flonat-Papers MCP** — Zotero library management server (search, PDF extraction, semantic retrieval, BibTeX export). Lives in `packages/flonat-papers/` with bundled `bib-validate` and `bib-parse` skills.
+
+**Council Mode** — Multi-model deliberation with 3 LLM providers, anonymised cross-review, and chairman synthesis. See [`docs/council-mode.md`](docs/council-mode.md).
+
+## Workflows
+
+<!-- WORKFLOWS:START -->
+<!-- synced from private README — do not edit manually -->
+| Command | What happens |
+|---------|-------------|
+| "Plan my day" | Reads context, queries vault, asks questions, creates Must Do / Should Do / Could Do plan |
+| "Extract actions from my meeting with [name]" | Finds transcript, extracts tasks with full context, creates in vault |
+| "Weekly review" | 4-part reflection: clear the decks, review, plan, project check |
+| "What's overdue?" | Queries vault and summarises |
+| "Proofread my paper" | 7-category academic check (report only) |
+| "Validate my bibliography" | Cross-references `\cite{}` keys against `.bib` |
+<!-- WORKFLOWS:END -->
+
+## Session Continuity
+
+<!-- SESSION-CONTINUITY:START -->
+<!-- synced from private README — do not edit manually -->
+Each session builds on previous ones:
+
+- `current-focus.md` — updated at session end with progress and next steps
+- `log/` — timestamped session logs
+- `log/plans/` — saved implementation plans
+- `MEMORY.md` — accumulated `[LEARN]` tags (notation, citation, code, method, domain corrections)
+
+The recovery protocol reads the latest plan, session log, and current focus to resume seamlessly.
+<!-- SESSION-CONTINUITY:END -->
+
+## Project Structure
+
+<!-- FILE-TREE:START -->
+```
+claude-research/
+├── CLAUDE.md                    # Main instruction file (customise this)
+├── README.md                    # This file
+├── MEMORY.md                    # Accumulated knowledge (auto-populated)
+├── .claude/
+│   ├── agents/                  # 6 specialised review agents
+│   ├── rules/                   # 9 auto-loaded policy rules
+│   └── settings.json            # Permissions, hooks, model config
+├── skills/                      # 38 slash commands
+│   ├── shared/                  # Shared utilities (palettes, scoring, rhetoric)
+│   ├── proofread/               # Academic proofreading
+│   ├── latex-autofix/           # LaTeX compilation + auto-fix
+│   ├── literature/              # Literature search + synthesis
+│   └── ...                      # See docs/skills.md for full list
+├── hooks/                       # 8 automated guardrails
+├── .context/                    # AI context library
+│   ├── profile.md               # Your identity and background
+│   ├── current-focus.md         # What you're working on NOW
+│   ├── projects/                # Project metadata
+│   ├── preferences/             # Workflow preferences
+│   ├── workflows/               # Process guides (daily review, etc.)
+│   └── resources/               # Reference data (journal rankings, etc.)
+├── .scripts/                    # CLI tools for vault task management
+├── mcp-bibliography/            # Multi-source scholarly search (OpenAlex + Scopus + WoS)
+├── packages/
+│   ├── cli-council/             # Multi-model council via local CLI tools
+│   ├── llm-council/             # Multi-model council via OpenRouter API
+│   └── mcp-bibliography/             # mcp-bibliography
+├── docs/                        # Component documentation
+├── log/                         # Session logs (auto-created)
+└── scripts/
+    └── setup.sh                 # Initial setup script
+```
+<!-- FILE-TREE:END -->
+
+## Design Principles
+
+<!-- DESIGN-PRINCIPLES:START -->
+<!-- synced from private README — do not edit manually -->
+1. **Lazy prompting** — Context files eliminate repetitive explanations
+2. **Hybrid local + cloud** — Markdown (versioned) + Research Vault (dynamic)
+3. **Question-driven** — AI asks questions before dumping lists
+4. **Read-only audits** — Proofread, validate, review — never auto-edit source
+5. **Session continuity** — Every session makes the next one better
+6. **Permission governance** — Global settings propagate automatically
+<!-- DESIGN-PRINCIPLES:END -->
+
+## Requirements
+
+| Tool | Why you need it | macOS | Linux | Windows |
+|------|----------------|-------|-------|---------|
+| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | The AI engine — runs skills, agents, hooks | `curl -fsSL https://claude.ai/install.sh \| bash` | same | `winget install Anthropic.ClaudeCode` |
+| [Python 3.11+](https://www.python.org/) | Hooks and MCP servers | `brew install python@3.12` | `apt install python3.12` | `winget install Python.Python.3.12` |
+| [uv](https://docs.astral.sh/uv/) | Fast Python package manager — isolates dependencies, replaces `pip` | `brew install uv` | `curl -LsSf https://astral.sh/uv/install.sh \| sh` | `winget install astral-sh.uv` |
+| [Git](https://git-scm.com/) | Version control | Included | `apt install git` | `winget install Git.Git` |
+| [TeX Live](https://tug.org/texlive/) | LaTeX compilation (`/proofread`, `/latex-autofix`) | `brew install --cask mactex` | `apt install texlive-full` | [install guide](https://tug.org/texlive/windows.html) |
+
+Also available as a [VS Code extension](https://marketplace.visualstudio.com/items?itemName=anthropics.claude-code), [JetBrains plugin](https://plugins.jetbrains.com/plugin/27189-claude-code), [web app](https://claude.ai/code), or [desktop app](https://claude.ai/download).
+
+See [`docs/getting-started.md`](docs/getting-started.md) for Fedora/Arch commands, Windows-specific setup, Python version guidance, and troubleshooting.
+
+## Credits
+
+<!-- CREDITS:START -->
+<!-- synced from private README — do not edit manually -->
+This infrastructure draws on design patterns from several open-source workflows.
+
+### Academic Researchers
+
+- **[Scott Cunningham](https://github.com/scunning1975/MixtapeTools)** (MixtapeTools) — session logs, rhetoric-driven presentations, "health inspector" model for code audits, cross-language replication, author/reviewer separation
+- **[Pedro Sant'Anna](https://github.com/pedrohcgs/claude-code-my-workflow)** — specialist agents, plan-first protocol, quality gates, critic-fixer loops, [LEARN] tags
+- **[Jared Black](https://github.com/Black-JL/Research-Project-Flow)** — "break the glass" protocol for infrastructure changes, data sensitivity rules, reproducible project templates
+- **[Antonio Mele](https://github.com/meleantonio/awesome-econ-ai-stuff)** — curated AI-for-economists resources, programmatic Claude Code controller, scientific skills reference
+- **[Hugo Sant'Anna](https://github.com/hsantanna88/clo-author)** (CLO-Author) — open-source Claude Code workflow for applied econometrics, agents, 29 slash commands
+- **[Chris Blattman](https://github.com/chrisblattman/claudeblattman)** — academic AI workflows guide, non-developer-friendly skill and agent patterns
+
+### General Resources
+
+- **[Andrej Karpathy](https://github.com/karpathy/llm-council)** — multi-model council with peer review and synthesis (our fork: [llm-council](https://github.com/user/llm-council), [cli-council](https://github.com/user/cli-council))
+- **[rtk-ai](https://github.com/rtk-ai/rtk)** — RTK rewrite hook for 60–90% token savings on CLI output
+- **[NPC Worldwide](https://github.com/npc-worldwide/npcsh)** (npcsh) — knowledge graph sleep/dream cycles, inspiring the memory consolidation skill
+- **[Boris Cherny](https://github.com/AugmendTech/ChernyCode)** (ChernyCode) — AI coding assistant configuration patterns
+- **[Jim Christian](https://github.com/aplaceforallmystuff)** (aplaceforallmystuff) — creation-guard pre-flight checks, lessons-learned retrospective, ecosystem health diagnostics
+- **[blader](https://github.com/blader/Claudeception)** (Claudeception) — skill description optimization, post-match action table, solution pattern for skill creation, learning nudge hook
+- **[Anthropic](https://github.com/anthropics/claude-code)** — Claude Code platform, 8 adopted skill patterns (docx, xlsx, pptx, pdf, frontend-design, mcp-builder, webapp-testing, skill-creator)
+
+System created January 2026.
+<!-- CREDITS:END -->
+
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=flonat/claude-research&type=Date)](https://star-history.com/#flonat/claude-research&Date)
+
+## License
+
+MIT

package/docs/agents.md

@@ -0,0 +1,44 @@
+# Agents
+
+> 6 specialised review agents with separate context and persistent memory.
+
+Agents are autonomous sub-processes that run in a separate context via Claude Code's Task tool.
+Unlike skills, agents solve the "grading your own homework" problem — they review work
+without access to the author's reasoning.
+
+## Available Agents
+
+| Agent | Description |
+|-------|-------------|
+| `domain-reviewer` | Research-focused substantive correctness agent |
+| `fixer` | Generic fix implementer for any critic report |
+| `paper-critic` | Read-only adversarial auditor for LaTeX papers |
+| `peer-reviewer` | Use this agent when you need to review someone else's paper — as a peer reviewer, discussant, or for reading group preparation |
+| `proposal-reviewer` | Use this agent when you need to review a research proposal, extended abstract, conference submission outline, or pre-paper plan — either his own or someone else's |
+| `referee2-reviewer` | Use this agent when the user wants a rigorous, adversarial academic review of their work — including papers, manuscripts, research designs, code, or arguments |
+
+## How Agents Work
+
+1. The main session spawns an agent via the Task tool
+2. The agent runs in a separate context with its own instructions
+3. The agent produces a report (never modifies source files)
+4. The report is returned to the main session for review
+
+## The Read-Only Principle
+
+Review agents never modify the author's files. They produce reports and recommendations.
+The `fixer` agent is the only exception — it reads a critic report and applies fixes,
+but only when explicitly invoked.
+
+## Creating a New Agent
+
+Create a `.md` file in `.claude/agents/` with YAML frontmatter:
+
+```yaml
+---
+name: my-agent
+description: "What this agent does"
+---
+```
+
+Agents are available globally via symlink: `~/.claude/agents/` points to this repo's `.claude/agents/`.

package/docs/bibliography-setup.md

@@ -0,0 +1,55 @@
+<!-- Governed by: skills/shared/project-documentation.md -->
+
+# Biblio MCP Server Setup
+
+The Biblio MCP server (`.mcp-server-biblio/`) provides scholarly search across up to 3 sources. OpenAlex is always available (free, no key required). Scopus and Web of Science are optional — add API keys to unlock them.
+
+## 1. Update the Email Address
+
+In `.mcp-server-biblio/server.py`:
+
+```python
+client = OpenAlexClient(email="your.email@university.edu")
+```
+
+OpenAlex uses this for its [polite pool](https://docs.openalex.org/how-to-use-the-api/rate-limits-and-authentication#the-polite-pool) — faster rate limits, no registration needed.
+
+## 2. Add the Server to Your Claude Code MCP Config
+
+In `.mcp.json` (project root) or `~/.claude.json` (global access):
+
+```json
+{
+  "mcpServers": {
+    "biblio": {
+      "command": "/opt/homebrew/bin/uv",
+      "args": ["run", "--frozen", "--directory", "/path/to/claude-research/.mcp-server-biblio", "python", "server.py"],
+      "env": {}
+    }
+  }
+}
+```
+
+## 3. (Optional) Add API Keys for Additional Sources
+
+| Source | Env var | How to get it |
+|--------|---------|---------------|
+| OpenAlex | None needed | Free — just set your email in step 1 |
+| Scopus | `SCOPUS_API_KEY` | [Elsevier Developer Portal](https://dev.elsevier.com/) — free for academic institutions |
+| Web of Science | `WOS_API_KEY` | [Clarivate Developer Portal](https://developer.clarivate.com/) — requires institutional subscription |
+
+Add keys to the `env` block:
+
+```json
+"env": {
+  "SCOPUS_API_KEY": "your-scopus-key",
+  "WOS_API_KEY": "your-wos-key",
+  "WOS_API_TIER": "expanded"
+}
+```
+
+The server auto-detects available keys at startup. With all 3 sources enabled, the `scholarly_*` tools deduplicate across sources and the `scholarly_verify_dois` tool cross-validates references.
+
+## 4. Use `/literature`
+
+Search for papers — the skill uses the biblio server automatically.

package/docs/council-mode.md

@@ -0,0 +1,36 @@
+<!-- Governed by: skills/shared/project-documentation.md -->
+
+# Council Mode
+
+Claude Code can invoke other LLM providers' CLI tools as subprocess reviewers — a different model reviews work that Claude produced, providing genuine architectural diversity (different training data, reasoning patterns, and blind spots). The system is extensible: any CLI tool that accepts a prompt and returns text can be wrapped as a backend (~20 lines of Python).
+
+Council mode coordinates this into a structured 3-stage protocol: independent assessments from multiple LLM providers, anonymised cross-review, then chairman synthesis. Used by the `paper-critic` agent and optionally by `/proofread`, `/devils-advocate`, `/code-review`, and `/multi-perspective`.
+
+See `skills/shared/council-protocol.md` for the full orchestration protocol.
+
+## CLI Council (`packages/cli-council/`) — Free
+
+Uses local CLI tools with existing subscriptions (no per-token cost). Backends are pluggable — adding a new provider follows the `BackendSpec` pattern:
+
+```bash
+cd packages/cli-council
+pip install -e .
+python -m cli_council --check  # verify which CLI backends are available
+```
+
+Currently available backends:
+- [Gemini CLI](https://github.com/google-gemini/gemini-cli) — `npm install -g @google/gemini-cli`
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) — useful for fresh context (same model, different session)
+- Additional backends can be added by implementing a `BackendSpec` in `config.py` and a thin async wrapper in `backends/`
+
+## LLM Council (`packages/llm-council/`) — API
+
+Uses OpenRouter for structured JSON output and programmatic integration:
+
+```bash
+cd packages/llm-council
+pip install -e .
+export OPENROUTER_API_KEY="sk-or-..."  # get one at https://openrouter.ai/keys
+```
+
+Requires an [OpenRouter](https://openrouter.ai/) account. One API key accesses Anthropic, OpenAI, and Google models. A council run (3 models) costs ~7 API calls. See the package's `README.md` for the full Python API reference.