Skip to content

CLAUDE.md

Latest commit

 

History

History
61 lines (43 loc) · 5.02 KB

CLAUDE.md

File metadata and controls

61 lines (43 loc) · 5.02 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

sci-brain is a skill-based plugin for AI coding assistants (Claude Code, Codex, OpenCode) that provides a structured scientific research brainstorming workflow. It is not a traditional code project — it consists of skill definition files (SKILL.md) that define agent interaction protocols.

Skills

Eight skills in skills/, each defined by a SKILL.md with YAML frontmatter + instructions:

  • ideas — The main entry point. Socratic research mentor that understands user background, finds attackable problems, and encourages deeper thinking. When an advisor is selected, /ideas launches that advisor as a subagent, builds an advisor-specific literature cache, and loads representative papers into the advisor context. Auto-calls researchstyle (Phase 0, if user chooses Zotero/Scholar) and writer (Phase 3, if user wants a report).
  • survey — Parallel literature search via 7 strategies, builds a registry (summary.md + references.bib) with verified BibTeX. Run before /ideas for deeper literature grounding.
  • writer — Produces a structured ideas report (Typst/LaTeX/Markdown) with full reasoning trail. Auto-called from /ideas at wrap-up, or run standalone on a past session's log.
  • researchstyle — Indexes a personal paper collection (Zotero/PDF folder/Google Scholar) into registry format. Auto-called from /ideas during background setup, or run standalone.
  • quicknote — Captures the last substantive Q&A exchange, saves to docs/discussion/notes/, copies to clipboard. General-purpose, works in any conversation.
  • conversation-dump — Extracts dialog from Claude Code or Codex CLI session logs, classifies user messages across 6 academic dimensions (Bloom's, Graesser, Paul & Elder, Walton, Long & Sato), organizes by topic, outputs tagged dialog reports to docs/dialog/. Extraction script: python skills/conversation-dump/extract_dialog.py list|extract.
  • soul-extraction — Reads /conversation-dump output, clusters trigger→reaction pairs into thinking-pattern.md, detects logic jumps (with user confirmation) for master-thinking.md. The master-thinking file serves as a self-interview for the creator to reconstruct their chain of thought. Output feeds into incarnate for advisor profile generation (incarnate drives the flow, not soul-extraction).
  • incarnate — Onboards a third-party contributor as a named advisor. Guides them through providing background (Zotero/Scholar/self-intro), runs conversation-dump and soul-extraction on their history, then synthesizes a thinking portrait into the advisor library (advisors/<name>/profile.md). The ideas skill lets users select an advisor at session start.

Architecture

Entry point: /ideas — most users only need this. Other skills are auto-called when needed or can run independently.

Ideas skill uses a primary Socratic mentor plus an optional advisor subagent:

  • Understands user background (self-intro, Zotero, or Google Scholar)
  • Builds/loads advisors/<slug>/survey/ for a selected advisor, including a survey index, verified BibTeX, and markdown paper cards for representative publications
  • Six principles: clarify motivation, encourage thinking (humbly), flag uncertainty, surface related facts, empower based on skills, inspire with deep theory
  • Phases: Get to Know You → Find Good Problems → Dive Into the Topic → Wrap Up

Survey registry format (reused across survey, ideas, researchstyle, writer):

<registry-root>/<topic>/
  summary.md       # Papers by sub-theme, open problems, bottlenecks
  references.bib   # BibTeX with abstract + doi/url required per entry

Advisor library (advisors/): Named advisor profiles generated by incarnate. Each profile contains a contributor's background and thinking style (cognitive patterns, attention patterns, reasoning strengths, conversation dynamics), and may include publication-source links and edge-tts voice hints. The ideas skill launches a selected advisor as a subagent and loads that advisor's literature cache during brainstorming.

BibTeX lookup chain (never from memory): CrossRef API → Semantic Scholar API → MCP servers → WebFetch fallback

Regenerating the Flowchart

typst compile images/flowchart.typ images/flowchart.svg
typst compile images/flowchart.typ images/flowchart.png

Installation

  • Claude Code: /plugin marketplace add QuantumBFS/sci-brain
  • Codex: Clone → symlink to ~/.agents/skills/sci-brain (see .codex/INSTALL.md)
  • OpenCode: Clone → symlink to ~/.config/opencode/skills/sci-brain (see .opencode/INSTALL.md)

Key Files

  • plugin.json / marketplace.json — Plugin metadata for Claude Code marketplace
  • .claude/settings.local.json — Allowed permissions (WebSearch, academic domain WebFetch, curl, git, typst)
  • docs/plans/ — Design documents for interaction protocols
  • images/flowchart.typ — Workflow diagram source (Typst + Fletcher package)