{"id":36645958,"url":"https://github.com/data-wise/scholar","last_synced_at":"2026-06-14T03:05:04.723Z","repository":{"id":332054005,"uuid":"1130887597","full_name":"Data-Wise/scholar","owner":"Data-Wise","description":"Academic workflows for research and teaching - 21 commands for literature management, manuscript writing, simulation studies, and course material generation. Claude Code plugin.","archived":false,"fork":false,"pushed_at":"2026-02-06T03:42:17.000Z","size":64864,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-06T05:24:47.764Z","etag":null,"topics":["academic","arxiv","bibtex","claude-code","claude-plugin","education","literature-search","manuscript-writing","research","teaching"],"latest_commit_sha":null,"homepage":"https://data-wise.github.io/scholar/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Data-Wise.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"docs/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/SECURITY-TESTING-GUIDE.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-09T06:47:06.000Z","updated_at":"2026-02-06T03:37:04.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Data-Wise/scholar","commit_stats":null,"previous_names":["data-wise/scholar"],"tags_count":30,"template":false,"template_full_name":null,"purl":"pkg:github/Data-Wise/scholar","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Data-Wise%2Fscholar","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Data-Wise%2Fscholar/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Data-Wise%2Fscholar/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Data-Wise%2Fscholar/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Data-Wise","download_url":"https://codeload.github.com/Data-Wise/scholar/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Data-Wise%2Fscholar/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29290991,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-10T03:42:42.660Z","status":"ssl_error","status_checked_at":"2026-02-10T03:42:41.897Z","response_time":65,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["academic","arxiv","bibtex","claude-code","claude-plugin","education","literature-search","manuscript-writing","research","teaching"],"created_at":"2026-01-12T10:00:20.420Z","updated_at":"2026-06-14T03:05:04.716Z","avatar_url":"https://github.com/Data-Wise.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Scholar Plugin\n\n\u003e **Academic workflows for research and teaching** - Literature management, manuscript writing, simulation studies, course material generation, and 17 A-grade research skills\n\nA comprehensive Claude Code plugin for academic workflows combining research and teaching. Features unified Plugin + MCP architecture with 33 slash commands and research skills.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Version](https://img.shields.io/badge/version-2.20.0-blue.svg)](https://github.com/Data-Wise/scholar/releases/tag/v2.20.0)\n[![Tests](https://img.shields.io/badge/tests-3,412%20passing-brightgreen.svg)](https://github.com/Data-Wise/scholar)\n[![Scholar CI](https://github.com/Data-Wise/scholar/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Data-Wise/scholar/actions/workflows/ci.yml?query=branch%3Amain)\n[![Docs Deploy](https://github.com/Data-Wise/scholar/actions/workflows/docs.yml/badge.svg?branch=main)](https://github.com/Data-Wise/scholar/actions/workflows/docs.yml?query=branch%3Amain)\n\n---\n\n## Features\n\n### 📚 33 Slash Commands\n\n**Literature Management (4 commands)**\n- `/arxiv \u003cquery\u003e` - Search arXiv for papers (top-level command)\n- `/doi \u003cdoi\u003e` - Look up paper metadata by DOI (top-level command)\n- `/bib:search \u003cquery\u003e` - Search BibTeX files for entries\n- `/bib:add \u003cfile\u003e` - Add BibTeX entries to bibliography\n\n**Manuscript Writing (4 commands)**\n- `/manuscript:methods` - Write methods sections\n- `/manuscript:results` - Write results sections\n- `/manuscript:reviewer` - Generate reviewer responses\n- `/manuscript:proof` - Review mathematical proofs\n\n**Simulation Studies (2 commands)**\n- `/simulation:design` - Design Monte Carlo studies\n- `/simulation:analysis` - Analyze simulation results\n\n**Research Planning (4 commands)**\n- `/scholar:lit-gap \u003ctopic\u003e` - Identify literature gaps\n- `/scholar:hypothesis \u003ctopic\u003e` - Generate research hypotheses\n- `/scholar:analysis-plan` - Create statistical analysis plans\n- `/scholar:method-scout \u003cproblem\u003e` - Scout statistical methods for research problems\n\n**Teaching (18 commands)**\n- `/teaching:quiz \u003ctopic\u003e` - Generate quiz questions with answer keys ✅\n- `/teaching:exam \u003ctype\u003e` - Create comprehensive exams with rubrics. NEW in v2.18.0: `--format exam-rich-latex` for evidence-based statistics exams ✅\n- `/teaching:assignment \u003ctopic\u003e` - Create homework assignments with solutions ✅\n- `/teaching:solution \u003cfile\u003e` - Generate standalone solution keys from assignment files ✅\n- `/teaching:syllabus \u003ccourse\u003e` - Generate comprehensive course syllabus ✅\n- `/teaching:slides \u003ctopic\u003e` - Create lecture slides with examples ✅\n- `/teaching:rubric \u003ctype\u003e` - Generate detailed grading rubrics ✅\n- `/teaching:feedback \u003cassignment\u003e` - Generate constructive student feedback ✅\n- `/teaching:demo [path]` - Create demo course environment with sample materials ✅\n- `/teaching:lecture \u003ctopic\u003e` - Generate comprehensive lecture notes ✅\n- `/teaching:validate \u003cfile\u003e` - Validate YAML configuration files (multi-level) ✅\n- `/teaching:validate-r \u003cfile\u003e` - Validate R code chunks in `.qmd` files ✅\n- `/teaching:diff \u003cfile\u003e` - Compare YAML and JSON sync status ✅\n- `/teaching:sync [options]` - Synchronize YAML to JSON ✅\n- `/teaching:migrate` - Batch migrate YAML configs from v1 to v2 schema ✅\n- `/teaching:config \u003csubcommand\u003e` - Manage prompts, config, and provenance ✅\n- `/teaching:preflight` - Pre-release health checks for Scholar projects ✅\n- `/teaching:canvas \u003cfile\u003e` - Convert exam files to Canvas QTI format ✅\n\n**Command Discovery (1 command)**\n- `/scholar:hub [argument]` - Browse all commands, drill into categories, get usage details ✅ NEW\n\n### 🎯 17 A-Grade Skills\n\nSkills automatically activate when relevant to your work:\n\n**Mathematical (4 skills)**\n- `proof-architect` - Rigorous proof construction and validation\n- `mathematical-foundations` - Statistical theory foundations\n- `identification-theory` - Parameter identifiability analysis\n- `asymptotic-theory` - Large-sample theory\n\n**Implementation (5 skills)**\n- `simulation-architect` - Monte Carlo study design\n- `algorithm-designer` - Statistical algorithm development\n- `numerical-methods` - Numerical optimization and computation\n- `computational-inference` - Computational statistical inference\n- `statistical-software-qa` - Statistical software quality assurance\n\n**Writing (3 skills)**\n- `methods-paper-writer` - Statistical methods manuscripts\n- `publication-strategist` - Journal selection and positioning\n- `methods-communicator` - Clear statistical communication\n\n**Research (5 skills)**\n- `literature-gap-finder` - Research gap identification\n- `cross-disciplinary-ideation` - Cross-field method transfer\n- `method-transfer-engine` - Adapting methods across domains\n- `mediation-meta-analyst` - Mediation analysis meta-analysis\n- `sensitivity-analyst` - Sensitivity analysis design\n\n### 🔧 Shell API Wrappers\n\nLightweight shell-based APIs for research tools:\n- `arxiv-api.sh` - arXiv paper search and PDF download\n- `crossref-api.sh` - DOI lookup and BibTeX retrieval\n- `bibtex-utils.sh` - BibTeX file search, add, format\n\n### 🏗️ Architecture\n\n**Unified Plugin + MCP Pattern:**\n- `src/core/` - Framework-agnostic business logic\n- `src/plugin-api/` - Claude Plugin commands and skills\n- `src/mcp-server/` - MCP Protocol tools\n- `lib/` - External API wrappers (arXiv, Crossref, BibTeX)\n\nThis architecture eliminates IPC overhead by sharing core logic directly between both APIs.\n\n**Phase 0 Foundation + Teaching Commands:**\n- `src/teaching/templates/` - Template system (exam, quiz, assignment, syllabus, lecture)\n- `src/teaching/generators/` - AI-powered content generation\n- `src/teaching/config/` - Configuration management\n- `src/teaching/validators/` - Multi-layer validation (Schema + LaTeX + Completeness)\n- `src/teaching/ai/` - AI content generation with retry logic\n- `tests/teaching/` - 3,411 unit tests (100% passing)\n\nSee [Phase 0 Architecture](docs/architecture/PHASE-0-FOUNDATION.md) for detailed documentation.\n\n---\n\n## Installation\n\nScholar is a **pure plugin** with no MCP server dependencies. It works immediately after installation in both Claude Code CLI and Claude Desktop app.\n\n### Option 1: Homebrew (Recommended - macOS)\n\n```bash\n# Add the Data-Wise tap\nbrew tap data-wise/tap\n\n# Install scholar plugin\nbrew install scholar\n\n# Or upgrade existing installation\nbrew upgrade scholar\n```\n\nThe Homebrew formula automatically:\n- Installs the plugin to `~/.claude/plugins/scholar`\n- Syncs Claude Code's plugin cache (new features available immediately)\n- Makes it available in Claude Code CLI and Claude Desktop\n- No additional configuration needed\n\n**Latest version:** v2.20.0 (released 2026-06-13)\n- 33 commands (18 teaching + 14 research + 1 hub)\n- 3,411 tests with 100% pass rate\n- Comprehensive documentation (95% coverage)\n\n### Option 2: Manual Installation (Local Development)\n\n**For Claude Code CLI and Claude Desktop:**\n\n```bash\n# Clone the repository\ngit clone https://github.com/Data-Wise/scholar.git\ncd scholar\n\n# Install in development mode (symlink - changes reflected immediately)\n./scripts/install.sh --dev\n\n# Or install in production mode (copy - stable)\n./scripts/install.sh\n```\n\n**Installation locations:**\n- Plugin directory: `~/.claude/plugins/scholar`\n- Commands: `~/.claude/plugins/scholar/src/plugin-api/commands/`\n- Skills: `~/.claude/plugins/scholar/src/plugin-api/skills/`\n- Shell APIs: `~/.claude/plugins/scholar/lib/`\n\n### Option 3: npm (Future - Not yet published)\n\n```bash\n# When published to npm (future release):\nnpm install -g @data-wise/scholar\nscholar-install  # Installs plugin to ~/.claude/plugins/\n```\n\n### Verify Installation\n\n```bash\n# Check plugin directory exists\nls -la ~/.claude/plugins/scholar\n\n# Verify plugin.json\ncat ~/.claude/plugins/scholar/.claude-plugin/plugin.json\n\n# Run test suite (if installed from source)\ncd ~/projects/dev-tools/scholar\n./tests/test-plugin-structure.sh\n```\n\n**Expected output:**\n```\n✅ All tests passed (10/10)\n- Plugin structure valid\n- 33 commands present (18 teaching + 14 research + 1 hub)\n- 17 skills present\n- No hardcoded paths\n- v2.20.0 verified\n```\n\n### Using in Claude Code CLI\n\nAfter installation, commands are immediately available:\n\n```bash\n# Start Claude Code in any directory\nclaude\n\n# Use scholar commands\n/arxiv \"bootstrap mediation\"\n/teaching:syllabus \"Statistics 101\"\n/doi \"10.1037/met0000165\"\n```\n\n### Using in Claude Desktop App\n\nScholar automatically loads when you open Claude Desktop. Commands work the same way:\n\n1. Open Claude Desktop app\n2. Start a new conversation\n3. Use slash commands: `/arxiv`, `/teaching:syllabus`, etc.\n\n### MCP Server Setup\n\n**Scholar does NOT require any MCP server configuration.**\n\nUnlike plugins like rforge that depend on MCP servers, Scholar uses shell-based API wrappers (`lib/arxiv-api.sh`, `lib/crossref-api.sh`, `lib/bibtex-utils.sh`) for external services.\n\n**Benefits of pure plugin approach:**\n- ✅ Faster startup (no IPC overhead)\n- ✅ Simpler installation (no server configuration)\n- ✅ More portable (works anywhere Claude Code/Desktop runs)\n- ✅ Self-contained (all dependencies included)\n\n**Future MCP integration (Phase 2):**\nIn a future release, Scholar may optionally integrate with an MCP server for advanced features like:\n- R execution for statistical analysis\n- Zotero library integration\n- LaTeX compilation\n\nThis will be **optional** - all current commands will continue to work without MCP.\n\nThis is planned for a future release.\n\n---\n\n## Quick Start\n\n### Literature Search\n\n```bash\n# Search arXiv\n/arxiv \"bootstrap mediation analysis\"\n\n# Look up specific paper\n/doi \"10.1080/00273171.2014.962683\"\n\n# Search your BibTeX files\n/bib:search \"mediation\"\n```\n\n### Manuscript Writing\n\n```bash\n# Generate methods section\n/manuscript:methods\n\n# Write results section with statistical details\n/manuscript:results\n\n# Respond to reviewer comments\n/manuscript:reviewer\n```\n\n### Teaching\n\n```bash\n# Create course syllabus\n/teaching:syllabus \"Introduction to Statistics\"\n\n# Generate homework assignment\n/teaching:assignment \"Linear Regression\"\n\n# Create grading rubric\n/teaching:rubric \"data analysis project\"\n```\n\n### Research Planning\n\n```bash\n# Identify literature gaps\n/scholar:lit-gap \"causal mediation analysis\"\n\n# Generate hypotheses\n/scholar:hypothesis \"mediation moderation\"\n\n# Create analysis plan\n/scholar:analysis-plan\n```\n\n---\n\n## Command Reference\n\n### Literature Management\n\n#### `/arxiv \u003cquery\u003e [limit]`\nSearch arXiv for papers matching your query.\n\n**Examples:**\n```bash\n/arxiv \"bootstrap mediation\"\n/arxiv \"causal inference\" 20\n```\n\n**Output:** Title, authors, arXiv ID, publication date, abstract preview\n\n**Follow-up Actions:** Get full details, download PDF, add BibTeX entry\n\n---\n\n#### `/doi \u003cdoi\u003e`\nLook up paper metadata by DOI using Crossref API.\n\n**Examples:**\n```bash\n/doi \"10.1037/met0000165\"\n/doi 10.1080/00273171.2014.962683\n```\n\n**Output:** Full citation, BibTeX entry, journal information\n\n---\n\n#### `/bib:search \u003cquery\u003e`\nSearch BibTeX files in your project for entries matching keywords.\n\n**Examples:**\n```bash\n/bib:search \"mediation\"\n/bib:search \"Baron Kenny\"\n```\n\n**Output:** Matching BibTeX entries with citation keys\n\n---\n\n#### `/bib:add \u003cfile\u003e`\nAdd BibTeX entries to your bibliography file.\n\n**Examples:**\n```bash\n/bib:add references.bib\n```\n\n---\n\n### Manuscript Writing\n\n#### `/manuscript:methods`\nGenerate a methods section for statistical manuscript.\n\n**Includes:**\n- Study design description\n- Statistical methods with mathematical notation\n- Software and implementation details\n- Assumptions and diagnostics\n\n---\n\n#### `/manuscript:results`\nWrite a results section with statistical findings.\n\n**Includes:**\n- Descriptive statistics\n- Model fit and diagnostics\n- Parameter estimates with uncertainty\n- Interpretation in context\n\n---\n\n#### `/manuscript:reviewer`\nGenerate responses to reviewer comments.\n\n**Features:**\n- Point-by-point responses\n- Additional analyses if requested\n- Clarifications and revisions\n- Professional academic tone\n\n---\n\n#### `/manuscript:proof`\nReview mathematical proofs in manuscript for correctness and clarity.\n\n---\n\n### Simulation Studies\n\n#### `/simulation:design`\nDesign a Monte Carlo simulation study.\n\n**Includes:**\n- Data generation mechanisms\n- Estimator implementations\n- Performance metrics\n- Parallelization strategy\n\n---\n\n#### `/simulation:analysis`\nAnalyze simulation results and create summary tables.\n\n**Output:**\n- Bias, variance, MSE, coverage\n- Publication-quality tables\n- Convergence diagnostics\n\n---\n\n### Research Planning\n\n#### `/scholar:lit-gap \u003ctopic\u003e`\nIdentify gaps in literature for a research area.\n\n**Output:**\n- Current state of literature\n- Identified gaps and opportunities\n- Potential research questions\n\n---\n\n#### `/scholar:hypothesis \u003ctopic\u003e`\nGenerate testable research hypotheses.\n\n**Output:**\n- Theoretical hypotheses\n- Statistical hypotheses\n- Expected findings\n\n---\n\n#### `/scholar:analysis-plan`\nCreate a comprehensive statistical analysis plan.\n\n**Includes:**\n- Research questions\n- Statistical methods\n- Sample size justification\n- Analysis workflow\n\n---\n\n### Teaching Commands\n\n#### Universal Options (All Teaching Commands)\n\nAll teaching commands support the `--config` flag to explicitly specify a configuration file path:\n\n```bash\n/teaching:quiz \"Linear Regression\" --config /path/to/config.yml\n/teaching:exam midterm --config .flow/teach-config.yml\n```\n\n**When to use `--config`:**\n- Integration with automation tools (e.g., flow-cli)\n- Using non-standard config locations\n- Testing with different configurations\n- CI/CD pipelines\n\n**Behavior:**\n- **With `--config`:** Loads the specified YAML file directly (skips parent directory search)\n- **Without `--config`:** Searches parent directories for `.flow/teach-config.yml` (default)\n- **Validation:** Lenient mode (warnings only) to avoid blocking workflow automation\n- **Debug:** Use `[scholar:config]` prefix in logs to track config source\n\n**Example workflow integration:**\n```bash\n# flow-cli passes explicit config path\nclaude --print \"/teaching:exam Midterm --config $(pwd)/.flow/teach-config.yml\"\n```\n\n---\n\n#### `/teaching:quiz \u003ctopic\u003e [options]`\nGenerate quiz questions with answer keys.\n\n**Examples:**\n```bash\n/teaching:quiz \"Linear Regression\"\n/teaching:quiz \"Hypothesis Testing\" --questions 10 --type practice\n```\n\n**Options:**\n- `--questions N` - Number of questions (default: 5)\n- `--type TYPE` - Quiz type: reading, practice, checkpoint, pop, review\n- `--duration N` - Duration in minutes (default: 15)\n- `--difficulty LEVEL` - beginner, intermediate, advanced\n\n**Output Formats:** markdown, json, canvas (QTI)\n\n---\n\n#### `/teaching:exam \u003ctype\u003e [options]`\nCreate comprehensive exams with rubrics.\n\n**Examples:**\n```bash\n/teaching:exam midterm --questions 20 --duration 90\n/teaching:exam final --topics \"regression,ANOVA,hypothesis testing\"\n/teaching:exam stat-545-final --format exam-rich-latex --topics \"two-way ANOVA\"\n```\n\n**Options:**\n- `--type TYPE` - midterm, final, practice, comprehensive\n- `--questions N` - Number of questions\n- `--duration N` - Duration in minutes\n- `--topics \"t1,t2\"` - Specific topics to cover\n- `--format FORMAT` - md (default), tex, qmd, canvas, json, exam-rich-latex *(v2.18.0)*\n\n**Output:** JSON with questions, answer key, grading rubric. `exam-rich-latex` emits a Quarto `.qmd` using the LaTeX `exam` class with an evidence-based reporting policy, F-critical bracket table, and $s$-value calibration — see the [Rich Exam LaTeX tutorial](docs/tutorials/teaching/rich-exam-format.md).\n\n---\n\n#### `/teaching:assignment \u003ctopic\u003e [options]`\nCreate homework assignments and problem sets.\n\n**Examples:**\n```bash\n/teaching:assignment \"Linear Regression\"\n/teaching:assignment homework --problems 5 --difficulty intermediate\n/teaching:assignment lab --topic \"Bootstrap Methods\" --include-code\n```\n\n**Options:**\n- `--type TYPE` - homework, problem-set, lab, project, worksheet\n- `--problems N` - Number of problems (default: 5)\n- `--points N` - Total points (default: 100)\n- `--include-code` - Include programming problems\n- `--language R|Python` - Programming language\n\n**Output:** JSON with problems, solutions, grading rubric\n\n---\n\n#### `/teaching:syllabus \u003ccourse\u003e [semester]`\nGenerate a comprehensive course syllabus.\n\n**Examples:**\n```bash\n/teaching:syllabus \"Introduction to Statistics\"\n/teaching:syllabus \"Regression Analysis\" \"Fall 2026\"\n```\n\n**Options:**\n- `--weeks N` - Number of weeks (default: 16)\n- `--level LEVEL` - undergraduate, graduate, doctoral\n- `--format FORMAT` - in-person, online, hybrid\n\n**Output Formats:** markdown, json, latex, html\n\n**Includes:**\n- Course and instructor information\n- Learning objectives (measurable, action verbs)\n- Grading policy with scale\n- Week-by-week schedule\n- Standard policies (academic integrity, accessibility, etc.)\n\n---\n\n#### `/teaching:slides \u003ctopic\u003e [duration]`\nCreate lecture slides with examples.\n\n**Examples:**\n```bash\n/teaching:slides \"Multiple Regression\"\n/teaching:slides \"Hypothesis Testing\" 75\n/teaching:slides \"ANOVA\" --format reveal\n```\n\n**Options:**\n- `--duration N` - Duration in minutes (default: 50)\n- `--format FORMAT` - markdown, reveal, beamer, quarto\n- `--include-code` - Include code examples\n- `--subtopics \"t1,t2\"` - Specific subtopics\n\n**Slide Count by Duration:**\n- 50 min → ~20 slides\n- 75 min → ~30 slides\n- 90 min → ~36 slides\n\n**Output:** Slides with speaker notes, organized by type (title, objectives, content, example, practice, summary)\n\n---\n\n#### `/teaching:rubric \u003cassignment-type\u003e [points]`\nGenerate detailed grading rubrics.\n\n**Examples:**\n```bash\n/teaching:rubric \"data analysis project\"\n/teaching:rubric \"research paper\" 100\n```\n\n**Includes:**\n- Clear criteria for each performance level\n- Point allocations\n- Observable, measurable descriptors\n\n---\n\n#### `/teaching:validate \u003cfile\u003e [options]`\nValidate YAML configuration files against schema.\n\n**Examples:**\n```bash\n/teaching:validate .flow/teach-config.yml\n/teaching:validate content/lesson-plans/week03.yml\n/teaching:validate --all  # Validate all YAML files in project\n```\n\n**Options:**\n- `--all` - Validate all YAML configs in project\n- `--strict` - Strict validation mode (errors on warnings)\n- `--quiet` - Suppress warnings, errors only\n\n**Validation Levels:**\n1. **YAML Syntax** - Valid YAML structure (indentation, colons, quotes)\n2. **JSON Schema** - Conforms to teach-config or lesson-plan schema\n3. **LaTeX Validation** - Math notation compiles (`$...$`, `$$...$$`)\n4. **Completeness** - Required fields present (course_info, defaults, style)\n\n**Output Format:**\n```\nIDE-style error messages:\n  file:line:col: error message\n  file:line:col: warning message\n\nSummary:\n  ✅ Validation passed (0 errors, 2 warnings)\n  ❌ Validation failed (3 errors, 1 warning)\n```\n\n**Use Cases:**\n- Pre-commit validation (ensure configs are valid before commit)\n- CI/CD pipelines (block deploys with invalid configs)\n- Development debugging (find syntax errors quickly)\n- Migration testing (validate after schema upgrades)\n\n**Exit Codes:**\n- `0` - Validation passed\n- `1` - Validation failed (errors found)\n- `2` - File not found or YAML parse error\n\n---\n\n#### `/teaching:diff \u003cfile\u003e [options]`\nCompare YAML and JSON sync status.\n\n**Examples:**\n```bash\n/teaching:diff teach-config.yml\n/teaching:diff content/lesson-plans/week03.yml\n/teaching:diff --all  # Check sync status for all configs\n```\n\n**Options:**\n- `--all` - Check sync status for all YAML/JSON pairs\n- `--verbose` - Show detailed diff output\n- `--json` - Output sync status as JSON\n\n**Output:**\n```json\n{\n  \"file\": \"teach-config.yml\",\n  \"inSync\": true,\n  \"yamlHash\": \"a3b2c1d4...\",\n  \"jsonHash\": \"a3b2c1d4...\",\n  \"lastSync\": \"2026-01-15T10:30:00Z\",\n  \"cacheAge\": \"5m 30s\"\n}\n```\n\n**Sync States:**\n- ✅ **In Sync** - YAML and JSON match (identical hashes)\n- ⚠️ **Out of Sync** - YAML changed, JSON needs update\n- ❌ **Missing JSON** - JSON file doesn't exist (run `/teaching:sync`)\n- ❌ **Invalid YAML** - YAML has syntax/schema errors\n\n**Use Cases:**\n- Verify sync before command execution\n- Debug sync issues (stale cache, missing JSON)\n- CI/CD validation (ensure configs are synced)\n- Pre-deployment checks\n\n**Performance:**\n- Hash comparison: ~5ms per file\n- Cache lookup: ~2ms per file\n- No file parsing (hash-based only)\n\n---\n\n#### `/teaching:sync [file] [options]`\nSynchronize YAML to JSON (manual trigger).\n\n**Examples:**\n```bash\n/teaching:sync                        # Sync all YAML files in project\n/teaching:sync teach-config.yml      # Sync specific file\n/teaching:sync --force                # Force re-sync (ignore cache)\n```\n\n**Options:**\n- `--force` - Force re-sync (bypass hash check, rewrite all JSON)\n- `--dry-run` - Preview sync without writing files\n- `--verbose` - Show detailed sync progress\n\n**Sync Process:**\n1. **Find YAML** - Locate all `*.yml` files in `.flow/` and `content/`\n2. **Hash Check** - Compare SHA-256 hash with cache (skip if unchanged)\n3. **Validate** - 4-level validation (YAML, schema, LaTeX, completeness)\n4. **Parse** - Parse YAML to JSON\n5. **Write** - Write JSON to same directory as YAML\n6. **Cache** - Update `.scholar-cache/sync-status.json` with new hash\n\n**Performance:**\n- Unchanged files: ~5ms (hash check only)\n- Changed files: ~80ms (parse + validate + write)\n- Typical project (10 files): ~150ms total\n\n**Output:**\n```\nSyncing 10 YAML files...\n\n✅ teach-config.yml → teach-config.json (80ms)\n⏭️ week01.yml (unchanged, skipped)\n⏭️ week02.yml (unchanged, skipped)\n✅ week03.yml → week03.json (75ms)\n❌ week04.yml (validation failed, see errors below)\n\nSummary:\n  2 synced, 2 skipped, 1 failed\n  Total time: 155ms\n```\n\n**Automatic Sync Triggers:**\n- Pre-command hook (before Scholar commands run)\n- Pre-commit hook (before git commits)\n- GitHub Actions (on CI/CD push)\n\n**Manual Sync When:**\n- Testing config changes before committing\n- Debugging sync issues (stale cache, corrupt JSON)\n- Forcing full re-sync after cache corruption\n\n**Cache Location:**\n```\n.scholar-cache/\n  sync-status.json    # Hash tracking, sync timestamps\n```\n\n**Error Handling:**\n- Validation errors block sync (prevents broken JSON)\n- Missing YAML files are skipped (warnings only)\n- Corrupt cache is auto-rebuilt on next sync\n\n---\n\n#### `/teaching:migrate [options]`\nMigrate YAML configuration files from v1 to v2 schema with atomic batch migration.\n\n**Examples:**\n```bash\n/teaching:migrate --detect              # Find v1 files with complexity\n/teaching:migrate --dry-run             # Preview migration changes\n/teaching:migrate                       # Apply migration with git commit\n/teaching:migrate --file week-01.yml    # Migrate single file\n/teaching:migrate --no-git              # Apply without git commit\n```\n\n**Modes:**\n- `--detect` - Find v1 schema files and show complexity scoring (0-10)\n- `--dry-run` - Preview colored diffs without modifying files\n- Default mode - Apply migration with git commit automation\n- `--file \u003cpath\u003e` - Migrate specific file only\n\n**Options:**\n- `--no-git` - Skip git commit (still applies migration)\n- `--no-git-check` - Skip git safety check (dangerous - may lose uncommitted work)\n- `--patterns \u003cglob\u003e` - Custom glob patterns (comma-separated)\n- `--debug` - Enable debug logging\n\n**Features:**\n- **Atomic semantics** - All-or-nothing migration with rollback\n- **Git integration** - Automated commits with descriptive messages\n- **Git safety** - Checks for uncommitted changes before migration\n- **Complexity scoring** - Helps prioritize migration effort\n- **Security hardened** - Uses `execFileNoThrow` (prevents command injection)\n\n**Complexity Categories:**\n- Simple (0-3): Few field renames\n- Medium (4-6): Multiple renames + type conversions\n- Complex (7-10): Many changes + nested structures\n\n**Rollback Guarantee:**\n- In-memory backups of all files\n- Automatic rollback on any failure\n- Restores exact original content\n\n**Output:**\n```\nFound 12 v1 schema files\n\nStep 1: Detecting v1 schema files...\nStep 2: Checking git status...\nStep 3: Migrating files...\n\n[1/12] week-01.yml... ✅\n[2/12] week-02.yml... ✅\n...\n\n✓ Migration complete!\nProcessed: 12 files\nCommit: abc123\n\nNext steps:\n  1. Review changes: git show abc123\n  2. Validate configs: /teaching:validate\n  3. Push to remote: git push\n```\n\n---\n\n## Skills Reference\n\nSkills automatically activate based on context. See `src/plugin-api/skills/README.md` for detailed documentation of all 17 A-grade skills.\n\n**When do skills activate?**\n- Writing methods → `methods-paper-writer`, `methods-communicator`\n- Designing simulations → `simulation-architect`, `numerical-methods`\n- Mathematical proofs → `proof-architect`, `mathematical-foundations`\n- Literature review → `literature-gap-finder`, `cross-disciplinary-ideation`\n\n---\n\n## Architecture Details\n\n### Unified Plugin + MCP Pattern\n\n```\nscholar/\n├── src/\n│   ├── core/              # Business logic (framework-agnostic)\n│   │   ├── literature/    # Literature search, metadata\n│   │   ├── manuscript/    # Writing assistance\n│   │   └── teaching/      # Course material generation ⭐ NEW\n│   │       ├── ai/        # AI provider with retry logic\n│   │       ├── config/    # Configuration loader\n│   │       ├── templates/ # Template system\n│   │       └── validators/# Validation engine\n│   ├── plugin-api/        # Claude Plugin commands/skills\n│   │   ├── commands/\n│   │   │   ├── literature/\n│   │   │   ├── manuscript/\n│   │   │   └── teaching/  # Teaching commands (Phase 2+)\n│   │   └── skills/\n│   └── mcp-server/        # MCP Protocol tools (future)\n├── lib/                   # External API wrappers\n│   ├── arxiv-api.sh\n│   ├── crossref-api.sh\n│   └── bibtex-utils.sh\n├── tests/                 # Test suite\n│   └── teaching/          # 2,252 tests ⭐\n└── scripts/               # Installation scripts\n```\n\n**Benefits:**\n- No IPC overhead (shared core library)\n- Single source of truth for business logic\n- Both APIs consume the same tested code\n- Easy to maintain and extend\n- Teaching foundation ready for command implementation\n\n**Phase 0 Components (Complete):**\n- **Template System** - Base schemas with inheritance and auto-field injection\n- **Config Loader** - Parent directory search for `.flow/teach-config.yml`\n- **Validator Engine** - Multi-layer validation (JSON Schema + LaTeX + Completeness)\n- **AI Provider** - Content generation with retry logic and rate limiting\n\nSee [Phase 0 Architecture Documentation](docs/architecture/PHASE-0-FOUNDATION.md) for details.\n\n---\n\n## Configuration \u0026 Sync Management\n\n### YAML ↔ JSON Workflow (v2.2.0)\n\nScholar v2.2.0 introduces a **dual-config system** where you write YAML configs (human-friendly) and Scholar automatically maintains JSON files (machine-optimized) with sub-100ms sync latency.\n\n#### How It Works\n\n```\n┌─────────────────┐         ┌──────────────────┐\n│  YAML (source)  │ ────→   │  JSON (auto)     │\n│  You edit this  │  sync   │  Never edit this │\n└─────────────────┘         └──────────────────┘\n     teach-config.yml            teach-config.json\n```\n\n**Key Principles:**\n- **YAML = Source of Truth** - Edit only YAML files\n- **JSON = Generated** - Auto-synced from YAML (gitignored)\n- **Fast Sync** - Hash-based change detection (\u003c 100ms)\n- **Safe** - Validation errors prevent broken configs\n\n#### Automatic Sync Triggers\n\nSync happens automatically in these scenarios:\n\n1. **Before Command Execution** - Pre-command hook ensures configs are synced\n2. **Pre-Commit Hook** - Git hook validates and syncs before commits\n3. **CI/CD Pipeline** - GitHub Actions workflow validates schemas\n\n#### Manual Sync Commands\n\n```bash\n# Sync YAML to JSON\n/teaching:sync\n\n# Check sync status\n/teaching:diff teach-config.yml\n\n# Validate YAML schema\n/teaching:validate teach-config.yml\n```\n\n#### Hash-Based Change Detection\n\nScholar uses SHA-256 hashing to skip unchanged files:\n\n```\n.scholar-cache/\n  sync-status.json    # Tracks file hashes and sync timestamps\n```\n\n**Performance:**\n- Changed files: Parse + Validate + Write JSON (~80ms)\n- Unchanged files: Hash check only (~5ms)\n- Cache invalidation: Automatic on YAML modification\n\n#### Directory Structure\n\n```\ncourse-repo/\n├── .flow/\n│   ├── teach-config.yml        # YAML config (source)\n│   └── teach-config.json       # JSON config (auto-generated)\n├── .scholar-cache/\n│   └── sync-status.json        # Hash tracking\n├── content/\n│   └── lesson-plans/\n│       ├── week01.yml          # YAML lesson plan (source)\n│       └── week01.json         # JSON lesson plan (auto-generated)\n└── .gitignore                  # Excludes *.json and .scholar-cache/\n```\n\n#### Validation Levels\n\nScholar performs 4-level validation during sync:\n\n1. **YAML Syntax** - Valid YAML structure\n2. **JSON Schema** - Conforms to teach-config schema\n3. **LaTeX Validation** - Math notation compiles\n4. **Completeness** - Required fields present\n\n**Error Handling:**\n- Validation errors block sync (prevents broken configs)\n- IDE-style error output: `file:line:col: message`\n- Lenient mode with `--config` flag (warnings only)\n\n#### GitHub Actions Integration\n\nAutomate validation in CI/CD:\n\n```yaml\n# .github/workflows/validate.yml\n- name: Validate Configs\n  run: |\n    npm install -g @data-wise/scholar\n    scholar validate .flow/teach-config.yml\n```\n\nSee `docs/github-actions-setup.md` for complete workflow examples.\n\n#### Migration from v2.1.0\n\n**Before v2.2.0:**\n```bash\n# Edit YAML, manually convert to JSON\nvim .flow/teach-config.yml\n# (manual conversion required)\n```\n\n**With v2.2.0:**\n```bash\n# Edit YAML, sync happens automatically\nvim .flow/teach-config.yml\ngit add .flow/teach-config.yml   # Sync in pre-commit hook\n```\n\nSee [MIGRATION-v2.2.0.md](docs/MIGRATION-v2.2.0.md) for detailed upgrade guide.\n\n---\n\n## Development\n\n### Running Tests\n\n```bash\ncd scholar\n./tests/test-plugin-structure.sh\n```\n\n**Test Coverage:**\n- ✅ Required files present\n- ✅ Valid JSON in plugin.json\n- ✅ Directory structure\n- ✅ 17+ commands exist\n- ✅ Teaching commands present\n- ✅ 15+ skills exist\n- ✅ API wrappers present\n- ✅ No hardcoded paths\n- ✅ Valid command frontmatter\n\n### Modifying Commands\n\nCommands are in `src/plugin-api/commands/`. Each command is a markdown file with:\n\n1. **YAML frontmatter** (name, description)\n2. **User-facing documentation**\n3. **`\u003csystem\u003e` block** with implementation details\n\n**Example:**\n```markdown\n---\nname: arxiv\ndescription: Search arXiv for papers\n---\n\n# Search arXiv\n\nUser-facing instructions here...\n\n\u003csystem\u003e\nImplementation details for Claude...\n\u003c/system\u003e\n```\n\n### Adding New Commands\n\n1. Create `.md` file in appropriate category directory\n2. Add frontmatter with `name:` and `description:`\n3. Write user-facing documentation\n4. Add `\u003csystem\u003e` block with implementation\n5. Test: `/namespace:command \"test input\"`\n\n---\n\n## Roadmap\n\n### Phase 0: Foundation (Complete ✅ 2026-01-11)\n**Teaching Infrastructure Layer**\n- ✅ Template system with inheritance and auto-fields\n- ✅ Configuration loader with parent directory search\n- ✅ Multi-layer validation (JSON Schema + LaTeX + Completeness)\n- ✅ AI provider with retry logic and rate limiting\n\n**Components:**\n- `src/teaching/templates/` - Template system\n- `src/teaching/config/` - Configuration management\n- `src/teaching/validators/` - Validation engine\n- `src/teaching/ai/` - AI content generation\n\n**Documentation:**\n- [Phase 0 Architecture](docs/architecture/PHASE-0-FOUNDATION.md)\n- [Test Documentation](tests/README.md)\n\n### Phase 1: MVP (Complete)\n- ✅ 14 research commands from statistical-research\n- ✅ 3 teaching commands (syllabus, assignment, rubric)\n- ✅ 17 A-grade skills\n- ✅ Shell API wrappers\n- ✅ Unified directory structure\n- ✅ Installation scripts\n- ✅ Test suite\n\n### Phase 2: Teaching Commands (Complete ✅ 2026-01-13)\n**Core Teaching Commands - 2,252 tests, 100% passing**\n\n- ✅ `/teaching:quiz` (33 tests)\n  - Multiple question types (MC, true-false, short-answer, numerical)\n  - Quiz types: reading, practice, checkpoint, pop, review\n  - Canvas QTI export support\n  - Conversational generation for Claude Max users\n\n- ✅ `/teaching:exam` (existing)\n  - Question bank generation\n  - Answer key creation\n  - LaTeX math support\n\n- ✅ `/teaching:assignment` (41 tests)\n  - Problem types: homework, problem-set, lab, project, worksheet\n  - Multi-part problems with solutions\n  - Grading rubrics with partial credit\n  - Code problems support (R, Python)\n\n- ✅ `/teaching:syllabus` (48 tests)\n  - Course information and instructor details\n  - Learning objectives (measurable, action verbs)\n  - Grading policy with scale\n  - Week-by-week schedule\n  - Standard policies (academic integrity, accessibility)\n  - Export: markdown, JSON, LaTeX, HTML\n\n- ✅ `/teaching:slides` (50 tests)\n  - Slide types: title, objectives, content, example, practice, summary\n  - Duration-based slide count calculation\n  - Speaker notes support\n  - Export: markdown, reveal.js, beamer, quarto\n\n**Pending Commands:**\n- [ ] `/teaching:feedback` - Constructive student feedback\n- [ ] `/teaching:rubric` - Enhanced with AI generation\n\n### Phase 3: MCP Server Integration (Future)\n- [ ] Implement MCP protocol tools in `src/mcp-server/`\n- [ ] Add TypeScript/Zod schemas\n- [ ] Test MCP server independently\n- [ ] Integrate with Claude Desktop app\n\n### Phase 4: Advanced Features (Future)\n- [ ] LMS integration (Canvas, Blackboard)\n- [ ] Export to PDF/Word formats\n- [ ] Calendar integration\n- [ ] Student roster management\n- [ ] Real-time collaboration\n\n---\n\n## Contributing\n\nContributions are welcome! This is a standalone project focused on academic workflows.\n\n**Development workflow:**\n1. Fork the repository: https://github.com/Data-Wise/scholar\n2. Create a feature branch: `git checkout -b feature/your-feature`\n3. Make your changes\n4. Run tests: `./tests/test-plugin-structure.sh`\n5. Commit with clear messages\n6. Push and submit a pull request\n\n**See also:**\n- [claude-plugins monorepo](https://github.com/Data-Wise/claude-plugins) for shared tooling and standards\n- [craft](https://github.com/Data-Wise/craft) and [rforge](https://github.com/Data-Wise/claude-plugins/tree/main/rforge) - Related projects\n\n---\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n---\n\n## Support\n\n- **Issues:** https://github.com/Data-Wise/scholar/issues\n- **Repository:** https://github.com/Data-Wise/scholar\n- **Documentation:** See `docs/` directory for comprehensive guides\n\n---\n\n## Related Projects\n\n- **[craft](https://github.com/Data-Wise/craft)** - Full-stack developer toolkit (86 commands, 8 agents, 21 skills)\n- **[rforge](https://github.com/Data-Wise/claude-plugins/tree/main/rforge)** - R package ecosystem orchestrator with mode system\n- **[claude-plugins](https://github.com/Data-Wise/claude-plugins)** - Shared tooling and plugin development standards\n\n**Migration from older plugins:**\n- `workflow` → Merged into craft (v1.17.0)\n- `statistical-research` → Superseded by scholar (v1.0.0)\n\n---\n\n**Ready to use!** Try: `/arxiv \"your research topic\"`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdata-wise%2Fscholar","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdata-wise%2Fscholar","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdata-wise%2Fscholar/lists"}