flonat-research 0.1.0

package/scripts/setup.sh

@@ -0,0 +1,143 @@
+#!/usr/bin/env bash
+# setup.sh — Set up Claude Code for Academic Research
+#
+# Creates symlinks so Claude Code can find skills, agents, hooks, and rules
+# from any project directory.
+#
+# Usage:
+#   ./scripts/setup.sh            # first-time setup
+#   ./scripts/setup.sh --update   # re-link without overwriting settings
+
+set -euo pipefail
+
+REPO_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+CLAUDE_DIR="$HOME/.claude"
+VERSION="$(grep '"version"' "$REPO_DIR/package.json" 2>/dev/null | head -1 | sed 's/.*: *"\(.*\)".*/\1/' || echo "unknown")"
+UPDATE_MODE=false
+
+[[ "${1:-}" == "--update" ]] && UPDATE_MODE=true
+
+RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[0;33m'; CYAN='\033[0;36m'; NC='\033[0m'
+info()  { echo -e "${CYAN}[setup]${NC} $*"; }
+ok()    { echo -e "${GREEN}[setup]${NC} $*"; }
+warn()  { echo -e "${YELLOW}[setup]${NC} $*"; }
+err()   { echo -e "${RED}[setup]${NC} $*" >&2; }
+
+echo ""
+echo "========================================="
+echo "  Claude Code for Academic Research"
+if $UPDATE_MODE; then
+  echo "  Update (v$VERSION)"
+else
+  echo "  Initial Setup (v$VERSION)"
+fi
+echo "========================================="
+echo ""
+
+# ---------- helper: create or verify symlink ----------
+link_component() {
+  local name="$1"
+  local source="$2"
+  local target="$3"
+
+  if [[ -L "$target" ]]; then
+    existing="$(readlink "$target")"
+    if [[ "$existing" == "$source" ]]; then
+      ok "$name symlink already correct"
+    else
+      if $UPDATE_MODE; then
+        rm "$target"
+        ln -s "$source" "$target"
+        ok "$name symlink updated → $source"
+      else
+        warn "$name symlink exists but points to: $existing"
+        warn "Remove it manually if you want to update: rm $target"
+      fi
+    fi
+  elif [[ -e "$target" ]]; then
+    warn "$target is a real directory/file (not a symlink)"
+    warn "Back it up and remove it if you want to use this repo's $name"
+  else
+    ln -s "$source" "$target"
+    ok "Linked $name → $source"
+  fi
+}
+
+# ---------- 1. Create ~/.claude if needed ----------
+if [[ ! -d "$CLAUDE_DIR" ]]; then
+  info "Creating $CLAUDE_DIR..."
+  mkdir -p "$CLAUDE_DIR"
+  ok "Created $CLAUDE_DIR"
+fi
+
+# ---------- 2. Symlink components ----------
+link_component "skills" "$REPO_DIR/skills" "$CLAUDE_DIR/skills"
+link_component "agents" "$REPO_DIR/.claude/agents" "$CLAUDE_DIR/agents"
+link_component "rules"  "$REPO_DIR/.claude/rules"  "$CLAUDE_DIR/rules"
+link_component "hooks"  "$REPO_DIR/hooks"  "$CLAUDE_DIR/hooks"
+
+# ---------- 3. Copy settings (skip in update mode) ----------
+if $UPDATE_MODE; then
+  info "Update mode — skipping settings.json (preserving your config)"
+elif [[ -f "$CLAUDE_DIR/settings.json" ]]; then
+  warn "~/.claude/settings.json already exists — not overwriting"
+  warn "Compare with $REPO_DIR/.claude/settings.json and merge manually"
+else
+  cp "$REPO_DIR/.claude/settings.json" "$CLAUDE_DIR/settings.json"
+  ok "Copied settings.json → $CLAUDE_DIR/settings.json"
+fi
+
+# ---------- 4. Create log directory ----------
+mkdir -p "$REPO_DIR/log/plans"
+ok "Ensured log/ and log/plans/ directories exist"
+
+# ---------- 5. Check Python dependencies ----------
+info "Checking Python dependencies..."
+
+if command -v uv &>/dev/null; then
+  ok "uv found: $(uv --version)"
+else
+  warn "uv not found — required for Python hooks and MCP server"
+  warn "Install: curl -LsSf https://astral.sh/uv/install.sh | sh"
+fi
+
+if command -v python3 &>/dev/null; then
+  ok "python3 found: $(python3 --version 2>&1)"
+else
+  warn "python3 not found — some hooks require Python 3.11+"
+fi
+
+if command -v latexmk &>/dev/null; then
+  ok "latexmk found (LaTeX compilation available)"
+else
+  info "latexmk not found — install a TeX distribution for LaTeX skills"
+fi
+
+# ---------- 6. MCP bibliography server ----------
+if [[ -d "$REPO_DIR/.mcp-server-biblio" ]]; then
+  info "Bibliography MCP server found at .mcp-server-biblio/"
+  info "To configure it, see docs/bibliography-setup.md"
+else
+  info "No .mcp-server-biblio/ directory — bibliography search not available"
+fi
+
+# ---------- Done ----------
+echo ""
+echo "========================================="
+echo "  Setup complete! (v$VERSION)"
+echo "========================================="
+echo ""
+if ! $UPDATE_MODE; then
+  echo "Next steps:"
+  echo "  1. Edit .context/profile.md with your details"
+  echo "  2. Edit .context/current-focus.md with your current work"
+  echo "  3. Edit .context/projects/_index.md with your projects"
+  echo "  4. Edit CLAUDE.md to customise conventions"
+  echo "  5. Review ~/.claude/settings.json for permissions and hooks"
+  echo ""
+  echo "Then open any project directory and run 'claude' to start!"
+else
+  echo "Symlinks updated. Your settings.json was preserved."
+  echo ""
+  echo "Check docs/getting-started.md if you need to merge new settings."
+fi

package/skills/beamer-deck/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: beamer-deck
+description: "Use when you need to create an academic Beamer presentation with original theme and multi-agent review."
+allowed-tools: Bash(latexmk*), Bash(xelatex*), Bash(pdflatex*), Bash(biber*), Bash(bibtex*), Bash(mkdir*), Bash(ls*), Bash(R*), Bash(Rscript*), Bash(python*), Read, Write, Edit, Task
+argument-hint: [topic, content-path, or project-name]
+---
+
+# Beamer Deck Skill
+
+> Generate academic Beamer presentations with original themes, rhetoric-driven structure, and multi-agent review. Internalises Scott Cunningham's rhetoric framework and implements an adversarial review workflow.
+
+## Purpose
+
+Create polished, zero-warning Beamer decks for academic contexts: seminars, conference talks, teaching lectures, and working decks for coauthors. Every deck gets a custom theme, assertion-driven titles, and parallel review by rhetoric and graphics sub-agents.
+
+**NOT for project status updates** — use `/project-deck` for those.
+
+## When to Use
+
+- Academic seminar presentations
+- Conference talks (15–45 min)
+- Teaching lectures (undergraduate or PhD)
+- Working decks for coauthors or supervisors
+- Any presentation that needs rhetoric discipline and visual quality
+
+---
+
+## Critical Rules
+
+1. **Build artifacts go to `out/`, PDF stays in the source directory.** Create `.latexmkrc` with `$out_dir = 'out'` and an `END {}` block to copy the PDF back if missing. Use `/latex-autofix` for compilation — it handles error resolution automatically. See `/latex` for manual config details.
+2. **Python:** Always use `uv run python`. Never bare `python`, `python3`, `pip`, or `pip3`.
+2. **Fix ALL warnings.** Overfull hbox, underfull hbox, overfull vbox, underfull vbox — no matter how small. Parse the `.log` file. Recompile until clean.
+3. **Titles are assertions, not labels.** "Distance increases abortion rates" — not "Results". Every frame title states a claim.
+4. **One idea per slide.** Not a guideline. A law. If a slide has two ideas, split it.
+5. **Original themes only.** Never use default Beamer themes (Warsaw, Madrid, etc.) as-is. Define colours and templates inline in the `.tex` file — no separate `.sty` files.
+6. **Code-first figures.** Generate figures via R or Python scripts before inserting. Never use placeholder images. **Always save the script alongside the figures** — never generate a figure without preserving the code that created it.
+7. **If a `.bib` file is used, validate it.** Cross-reference all `\cite{}` keys against the bibliography file. See `/bib-validate` for the full protocol.
+
+---
+
+## Rhetoric Principles
+
+Full framework (Three Laws, MB/MC, Aristotelian Triad, Narrative Arc, Pyramid Principle, Devil's Advocate): [`../shared/rhetoric-principles.md`](../shared/rhetoric-principles.md)
+
+Scott's original essay: `resources/academics/scott-cunningham/MixtapeTools/presentations/rhetoric_of_decks.md`
+
+---
+
+## Quality Scoring
+
+Apply numeric quality scoring using the shared framework and skill-specific rubric:
+
+- **Framework:** [`../shared/quality-scoring.md`](../shared/quality-scoring.md) — severity tiers, thresholds, verdict rules
+- **Rubric:** [`references/quality-rubric.md`](references/quality-rubric.md) — issue-to-deduction mappings for this skill
+
+Start at 100, deduct per issue found, apply verdict. Compute the score in Phase 7 and report it in the final output.
+
+## Context-Specific Guidance
+
+See [`../shared/rhetoric-principles.md`](../shared/rhetoric-principles.md) for the full Aristotelian Triad framework. Context-specific Ethos/Pathos/Logos balance and adjustments are applied in Phase 2 based on audience type (academic seminar, conference talk, teaching lecture, working deck).
+
+---
+
+## Workflow: 7 Phases
+
+```
+You (orchestrator)
+├── Phase 1: Gather context        (direct)
+├── Phase 2: Design structure       (direct)
+├── Phase 3: Build deck             (direct)
+├── Phase 4: Fix all warnings       (direct)
+├── Phase 5: Rhetoric review        (sub-agent — Explore)
+├── Phase 6: Graphics review        (sub-agent — Explore)  ← parallel with Phase 5
+└── Phase 7: Apply & finalise       (direct)
+```
+
+### Phase 1: Gather Context (Direct)
+
+Read project files, content sources, and audience brief. Ask the user clarifying questions:
+
+- **Audience**: Who is this for? (seminar, conference, teaching, coauthors)
+- **Duration**: How long is the talk?
+- **Content source**: Paper draft? Notes? Existing slides? Code output?
+- **Special requirements**: Specific figures, institutional branding, language?
+
+Check for existing `.bib` files in the project. If citations are needed, note this for Phase 3.
+
+### Phase 2: Design Structure (Direct)
+
+1. **Choose rhetoric balance** based on audience (see table above)
+2. **Outline slide sequence** with assertion titles — write each title as a claim
+3. **Plan narrative arc** — identify Act I/II/III transitions
+4. **Choose colour palette** — original, appropriate to audience tone (see Reference Palettes below for starting points)
+5. **Identify figures needed** — which need to be generated via code?
+
+Present the outline to the user for approval before building.
+
+### Phase 3: Build Deck (Direct)
+
+1. **Generate figures first** — run R/Python scripts, save to `figures/`
+2. **Write `.tex` file** with inline theme (colours, templates, fonts — all in one file, no `.sty`)
+3. **Use 16:9 aspect ratio** (`\documentclass[aspectratio=169,11pt]{beamer}`)
+4. **Create `.latexmkrc`** if not present (`$out_dir = 'out'` + `END {}` block to copy PDF back)
+5. **Compile using `/latex-autofix`** — this handles missing packages, font conflicts, citation key mismatches, and stale cache automatically
+6. **If using citations**: add `\addbibresource{references.bib}` or `\bibliography{}` as appropriate
+
+### Phase 4: Fix All Warnings (Direct)
+
+After `/latex-autofix` resolves errors, address remaining **warnings** (which autofix does not fix):
+
+1. Parse `out/*.log` for overfull/underfull hbox/vbox warnings
+2. Fix every single one — adjust text, resize figures, tweak `\parbox`, etc.
+3. Recompile
+4. Repeat until the log is clean
+
+**"Compilation success does not mean visual success."** Also check for silent visual errors:
+- TikZ: shape constraints forcing label misplacement, coordinate misalignment. **If the deck contains TikZ diagrams**, run the 6-pass verification from [`../shared/tikz-rules.md`](../shared/tikz-rules.md) — compute Bezier depths, check gaps, verify label fit, check shape boundary clearance.
+- matplotlib/ggplot: axis labels cut off, legend obscuring data, text sizing. **If figures use curved arrows (`arc3`)**, compute Bézier positions using the helper functions in `../shared/tikz-rules.md` § Matplotlib Extension — never guess where curves pass. Check label-to-shape clearance (Boundary Rule) and use anchor-based centering for text pairs.
+- **PDF visual inspection**: Run `uv run python scripts/pdf-to-images.py <deck>.pdf` to convert pages to images, then inspect each image for text overflow, element overlap, font readability, and alignment issues that are invisible in the log
+
+### Phase 5: Rhetoric Review (Sub-Agent — Explore)
+
+Launch a sub-agent to review the `.tex` file against 7 criteria: narrative arc, MB/MC balance, title quality, one-idea-per-slide, transitions, Aristotelian balance, and pyramid principle.
+
+Full prompt template: [`references/review-prompts.md`](references/review-prompts.md) § Rhetoric Review
+
+### Phase 6: Graphics Review (Sub-Agent — Explore)
+
+Launch **in parallel with Phase 5**. Reviews TikZ diagrams, figure sizing, table formatting, colour consistency, typography, and numerical accuracy.
+
+Full prompt template: [`references/review-prompts.md`](references/review-prompts.md) § Graphics Review
+
+### Phase 7: Apply and Finalise (Direct)
+
+1. Read both reviewer reports
+2. Incorporate feedback — prioritise Critical and Needs Work items
+3. Recompile
+4. Verify zero warnings in the log
+5. **If using a `.bib` file**: validate all `\cite{}` keys resolve correctly (check log for `Citation .* undefined`). See `/bib-validate` for the full cross-referencing protocol.
+6. If significant changes were made, loop back to Phase 5 for another review round
+7. **Compute quality score** — read `references/quality-rubric.md`, log all issues from Phases 4-6, compute score and verdict
+8. Confirm final PDF is in the source directory (copied from `out/` by `.latexmkrc`)
+
+---
+
+## Reference Palettes
+
+Three starting palettes (Professional, Energetic, Academic) in both LaTeX and CSS formats: [`../shared/palettes.md`](../shared/palettes.md)
+
+Use as inspiration — always create an original palette for each deck.
+
+---
+
+## Output Checklist
+
+A completed deck directory should contain:
+
+```
+project/
+├── deck.tex              # Main Beamer file (inline theme)
+├── deck.pdf              # Compiled PDF (copied from out/ by .latexmkrc)
+├── .latexmkrc            # Output directory config
+├── out/                  # Build artifacts only
+├── figures/              # Generated figures (if any)
+│   ├── figure_1.png
+│   └── ...
+├── scripts/              # R/Python scripts that generated figures (if any)
+│   ├── figure_1.R
+│   └── ...
+└── references.bib        # Bibliography (if citations used)
+```
+
+- [ ] PDF compiles with zero warnings
+- [ ] All frame titles are assertions
+- [ ] One idea per slide
+- [ ] Narrative arc: Problem → Investigation → Resolution
+- [ ] Rhetoric review completed (Phase 5)
+- [ ] Graphics review completed (Phase 6)
+- [ ] If `.bib` used: all `\cite{}` keys validated (see `/bib-validate`)
+- [ ] Quality score computed and reported
+
+---
+
+## Cross-References
+
+| Skill | When to use instead/alongside |
+|-------|-------------------------------|
+| `/project-deck` | For project status updates (supervisor meetings, coauthor handoffs) |
+| `/latex-autofix` | **Default compiler** — used in Phase 3 for error resolution and citation audit |
+| `/latex` | For manual compilation config details, `.latexmkrc` setup, engine selection |
+| `/proofread` | For post-hoc review of text quality in the deck |
+| `/bib-validate` | For thorough bibliography cross-referencing when citations are used |
+| `/literature` | For finding and verifying citations to include |
+| `/quarto-deck` | For HTML presentations (teaching, informal talks) instead of PDF |
+| `/quarto-course` | For full course websites with multiple lectures, exercises, and navigation |
+
+**Scott's full rhetoric essay:** `resources/academics/scott-cunningham/MixtapeTools/presentations/rhetoric_of_decks.md`
+**Scott's deck generation prompt:** `resources/academics/scott-cunningham/MixtapeTools/presentations/create_deck_prompt.md`
+**Scott's example decks:** `resources/academics/scott-cunningham/MixtapeTools/presentations/examples/`

package/skills/beamer-deck/references/quality-rubric.md

@@ -0,0 +1,54 @@
+# Quality Rubric: Beamer Deck
+
+> Scoring rubric for `/beamer-deck`. Uses the shared framework in [`../../shared/quality-scoring.md`](../../shared/quality-scoring.md).
+
+## Deduction Table
+
+### Blocker (-100)
+
+| Issue | Deduction | Notes |
+|-------|-----------|-------|
+| Compilation fails — no PDF produced | -100 | Deck is broken |
+| Default Beamer theme used (Warsaw, Madrid, etc.) | -100 | Violates Critical Rule 5 |
+
+### Critical (-15 to -25)
+
+| Issue | Deduction | Notes |
+|-------|-----------|-------|
+| No narrative arc (no Problem → Investigation → Resolution structure) | -20 | Fundamental rhetoric failure |
+| Label title instead of assertion (e.g., "Results" not a claim) | -15 | Per frame — violates Critical Rule 3 |
+| Multiple ideas on a single slide | -15 | Per slide — violates Critical Rule 4 |
+| Unresolved `\cite{}` — `??` or `[?]` in output | -15 | Per broken citation |
+| Unresolved `\ref{}` — `??` in output | -15 | Per broken reference |
+
+### Major (-5 to -14)
+
+| Issue | Deduction | Notes |
+|-------|-----------|-------|
+| Overfull hbox/vbox warning remaining | -5 | Per instance — violates Critical Rule 2 |
+| Missing transitions between sections (audience loses thread) | -8 | Per missing transition |
+| Aristotelian balance off (e.g., 0% pathos in teaching) | -5 | Once for the deck |
+| Placeholder image instead of code-generated figure | -10 | Per figure — violates Critical Rule 6 |
+| Figure axes unlabelled or legend missing | -5 | Per figure |
+| Colour palette not accessible (low contrast, red-green reliance) | -5 | Once for the deck |
+| `.bib` used but not validated | -8 | Once — violates Critical Rule 7 |
+
+### Minor (-1 to -4)
+
+| Issue | Deduction | Notes |
+|-------|-----------|-------|
+| Conclusion-last instead of conclusion-first on a slide (Pyramid Principle) | -3 | Per slide |
+| Speaker notes missing on key slides | -2 | Per key slide |
+| Slide overloaded visually (too much text, cramped layout) | -3 | Per slide |
+| Inconsistent font sizing across slides | -2 | Once for the deck |
+| Minor TikZ alignment issue | -2 | Per diagram |
+| Cognitive load spike (too much new information at once) | -3 | Per instance |
+
+## Category Mapping
+
+| Rubric category | Phase |
+|----------------|-------|
+| Compilation & warnings | Phase 3-4 |
+| Rhetoric (arc, titles, one-idea) | Phase 5 |
+| Graphics (figures, TikZ, colour) | Phase 6 |
+| Final polish | Phase 7 |

package/skills/beamer-deck/references/review-prompts.md

@@ -0,0 +1,106 @@
+# Beamer Deck Review Prompts
+
+> Sub-agent prompts for Phases 5 and 6 of `/beamer-deck`. Also usable by `/quarto-deck` (Phase 5).
+
+## Rhetoric Review (Phase 5)
+
+Launch with `subagent_type: Explore`:
+
+```
+You are a rhetoric reviewer for an academic Beamer presentation.
+
+Read the file at: [PATH TO .tex FILE]
+
+Evaluate the deck against these criteria and return a structured report:
+
+## 1. Narrative Arc
+- Does the deck follow a three-act structure (Problem → Investigation → Resolution)?
+- Is the opening a provocative question, statistic, or bold claim (not "Today I'll talk about...")?
+- Does the closing deliver a single memorable takeaway (not "Questions?" or "Thank you")?
+
+## 2. MB/MC Balance
+- Is cognitive load distributed smoothly across slides?
+- Are there overloaded slides (too many ideas, text to footer)?
+- Are there underloaded slides (wasted opportunity)?
+- Is there deliberate rhythm between dense and light slides?
+
+## 3. Title Quality
+- Is every frame title an assertion (a claim), not a label?
+- Bad: "Results", "Data", "Background"
+- Good: "Distance increases abortion rates", "Standard methods fail with staggered treatment"
+
+## 4. One Idea Per Slide
+- Does any slide try to convey multiple ideas?
+- Flag any slide that should be split.
+
+## 5. Transitions
+- Are transitions between slides explicit?
+- Does the audience know where they are in the argument at all times?
+
+## 6. Aristotelian Balance
+- For the intended audience ([AUDIENCE TYPE]), is the ethos/pathos/logos balance appropriate?
+- Is there a Devil's Advocate moment (acknowledging the strongest objection)?
+
+## 7. Pyramid Principle
+- Does each section lead with conclusions, then support?
+- Or does the deck bury findings after too much background?
+
+Return your report as a structured markdown document with:
+- A rating for each criterion (Strong / Adequate / Needs Work)
+- Specific slide numbers and suggested improvements
+- An overall assessment
+```
+
+## Graphics Review (Phase 6)
+
+Launch with `subagent_type: Explore` **in parallel with Phase 5**:
+
+```
+You are a graphics specialist reviewing an academic Beamer presentation.
+
+Read the file at: [PATH TO .tex FILE]
+
+Check for visual and technical issues:
+
+## 1. TikZ Diagrams
+- Do coordinate values match intended placement?
+- Are node positions consistent with the visual layout described?
+- Are labels positioned correctly (not overlapping nodes or edges)?
+- Do shape constraints force any misplacement?
+- Do labels near circles/rectangles clear the computed shape boundary by at least 0.4cm?
+
+## 2. Matplotlib/Python Figures
+- For curved arrows (`arc3`): were Bézier positions computed or guessed?
+- Do labels near patches (FancyBboxPatch, Circle) clear their boundaries?
+- For text pairs in containers: is anchor-based centering used (not symmetric `va='center'`)?
+- Are figure-generation scripts saved alongside the output figures?
+
+## 3. Figure Sizing and Placement
+- Are included figures sized appropriately for the slide?
+- Is there sufficient whitespace around figures?
+- Are captions/labels readable at presentation size (minimum 18pt)?
+
+## 4. Table Formatting
+- Are tables clean (booktabs style, no vertical rules)?
+- Is text in tables large enough to read?
+- Are column widths balanced?
+
+## 5. Colour Consistency
+- Is the colour palette used consistently throughout?
+- Are accent colours used for emphasis, not decoration?
+- Do data visualisation colours match the deck palette?
+
+## 6. Typography
+- Is body text at least 24pt (18pt floor)?
+- Maximum two font families?
+- Is text ragged right (not justified)?
+
+## 7. Numerical Accuracy
+- If the deck references specific numbers, do the figures/tables match?
+- Are axis scales appropriate and labeled?
+
+Return your report as structured markdown with:
+- Specific slide numbers for each issue found
+- Severity (Critical / Minor / Suggestion)
+- Recommended fix for each issue
+```