PhilLit CLAUDE.md

PhilLit is a multi-agent system to (a) author academic literature reviews for philosophy research, and (b) improve these agents. It is packaged as a distributable Claude Code plugin.

This CLAUDE.md is for plugin developers working in this repository. It does not load when PhilLit runs as an installed plugin from a user's own directory — runtime guidance lives in the skills (skills/*/SKILL.md) and agents (agents/*.md).

Mode

Production mode (default): When the user asks for a literature review, invoke the /phillit:literature-review skill to begin the 6-phase workflow. Skills and agents register only when the plugin is loaded — a bare dev clone registers none of them. To run a review against your checkout, launch claude --plugin-dir /path/to/PhilLit from a scratch directory (see CONTRIBUTING.md, Getting Started).

Development mode: Only if user explicitly asks to develop, improve, or test agents/skills. Work on definitions in agents/ and skills/.

Objectives

Priority order for literature reviews (and agent development):

1. Accurate — Only cite verified papers; never fabricate references
2. Comprehensive — Cover all major positions and key debates
3. Rigorous and concise — Analytical depth, tight prose; balanced presentation of positions
4. Reproducible — Structured workflow, standard BibTeX output, Chicago author-date citations

NOT priorities:

• ❌ Speed — Quality over fast completion
• ❌ Context efficiency — Use full context as needed; don't optimize for token savings

File Structure

• reviews/ — All existing and new literature reviews. Each review has its own subdirectory with an informative short name. Gitignored (local only), except the three example reviews linked from the README.
• .claude-plugin/ — Plugin manifest (plugin.json).
• bin/phillit-run — Self-locating wrapper that runs every bundled Python script in the plugin's locked uv project environment (see "Hooks and Python").
• skills/literature-review/ — Main orchestration skill for the 6-phase workflow. scripts/ contains the Phase 3-to-4 evidence barrier (evidence_barrier.py, helpers resolve_context.py, stamp_evidence.py, bib_fields.py — the depth-counting scanner that owns locating field VALUES in raw BibTeX text: every value read (stamp_evidence.parse_entry_fields, enrich_bibliography.parse_bibtex_entries, dedupe's extractors), every edit (add_field_to_entry, the keywords stamp and editors) and every strip (the barrier's derived fields, the context fields) goes through iter_fields / remove_field. Outside it, by design: the barrier's \b<name>\s*= presence COUNTERS in its splice checks, dedupe's line-based duplicate-field warning, and the one textual check in dedupe's field remover, a name = in the untrusted tail past an unclosed value or block — venue_vetting.py — the OpenAlex venue check behind the barrier's venue_status flag — year_suffix.py, the pure Chicago a/b assigner behind its year_suffix field, and web_evidence.py — URL extraction, capture validation and existence checks behind the EVIDENCE-WEB fetch gate, whose urldate/archiveurl the barrier also owns, and which also owns the excluded-host policy (SEP + mirrors, IEP, NDPR, PhilPapers — never earn EVIDENCE-WEB)). The barrier also stamps same_work_group on reprint-shaped entry groups. Since v0.5.0 the barrier also owns EVIDENCE-ABSTRACT attestation: the enrichment ledger is candidacy only, and the tier requires a live per-source re-fetch whose text hash-matches the bib's (enrich_bibliography.corroborate_abstract; budgeted, fail-closed, bucketed in the report). Phase 6 tools: assemble_review.py, normalize_headings.py, dedupe_bib.py, enrich_bibliography.py, generate_bibliography.py, lint_md.py, check_evidence.py, sanitize_bib.py.
• skills/philosophy-research/ — API search scripts for academic sources (Semantic Scholar, OpenAlex, CORE, arXiv, SEP, IEP, PhilPapers, NDPR), abstract resolution, encyclopedia context extraction, and citation verification (CrossRef). Includes Brave web search fallback and caching, and fetch_web.py — the research-time fetch-and-capture tool (HTML and PDF, --stdin fallback) whose capture files the evidence barrier gates EVIDENCE-WEB on, and which refuses the excluded encyclopedia hosts (SEP + mirrors, IEP, NDPR, PhilPapers) before any request. output.dumps() in output.py is the one owner of the ensure_ascii decision for console output, including the Windows stdout guard behind it — never hand-pick ensure_ascii at a call site.
• skills/setup/ — The /phillit:setup skill: scaffolds a workspace (.phillit/ marker, .env) and safely merges permission rules into the workspace's .claude/settings.json.
• agents/ — Specialized subagent definitions invoked by the literature-review skill.
• hooks/ — Hook scripts: fast_gate.sh (shell pre-filter for per-call gates), bib_validator.py, validate_bib_write.py, metadata_cleaner.py, block_background_bash.py (guards Bash-tool background calls inside subagents), block_subagent_background_dispatch.py (guards Agent/Task background dispatch at the orchestrator — the four PhilLit review agents must run foreground), block_ledger_write.py (denies native file-tool writes to the enrichment_ledger-*.json / cleaning_ledger-*.json attestation ledgers — the designated writers write them from inside Python, so the supported pipeline is unaffected; it is not a security boundary, since broadly-allowed Bash bypasses it entirely, and it does deny a developer hand-editing a ledger — use the owning script or git checkout), subagent_stop_bib.sh, and the thin setup-environment.sh SessionStart bootstrap. Also here but not a hook: bib_identity.py, the one owner of bibliography identity, comparison keys, and name folds (normalize_doi, title_key, normalize_pages, normalize_journal, venue_key, year_key, fallback_key, same_work_key, same_work_year, ascii_variants, translit_fold, contract_fold, split_author_list, first_author_name, first_author_surname) — note venue_key is a deliberately looser VERIFICATION key for venue names (it folds conference citation forms onto the series name) and must never be used for dedup identity, which is normalize_journal's job. Author lists are split ONLY through split_author_list (pybtex, brace-aware, no literal fallback) — a literal .split(" and ") keyed a braced corporate author differently from Phase 6; first_author_surname keeps the raw text, while enrich_bibliography.get_author_last_name derives search text from it. It lives in hooks/ because that is the directory other components already import from, and it is deliberately absent from hooks.json. Sites keep their historic names as aliases to the shared objects, so tests assert is identity; never re-add a local copy.
• hooks/hooks.json — Plugin hook definitions (single source of truth): SessionStart bootstrap; marker-gated PreToolUse/PostToolUse/SubagentStop.
• docs/ — Project documentation: ROADMAP.md (the work queue: open items only), shared specs (ARCHITECTURE.md, conventions.md, permissions-guide.md), known-issues/ (measurement scripts and their data — the reproduction path for measured decisions, not issue write-ups), and ideas/ (design ideas and deferred plans).
• tests/ — pytest tests for API scripts and hooks.