claude-code-my-workflow
A ready-to-fork Claude Code template for academics using LaTeX/Beamer + R. Multi-agent review, quality gates, adversarial QA, and replication protocols.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/pedrohcgs--claude-code-my-workflow)HTML
<a href="/listings/pedrohcgs--claude-code-my-workflow"><img src="/api/listings/pedrohcgs--claude-code-my-workflow/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
> **Before you start:** Claude Code, git and Python 3 are the minimum. Python 3 runs the hooks, the gate suite (`./scripts/backtest.sh` — 10 checkers) and the quality scorer, and is pre-installed on macOS/Linux. To run the included `HelloWorld` demos end-to-end you also need XeLaTeX (Beamer sample) and Quarto (Quarto sample). R and the GitHub CLI are recommended. Full list in [Prerequisites](#prerequisites) below. Fastest path: clone first, then run `./scripts/validate-setup.sh` — it reports exactly what's missing with install links. > > **Only need Python/R/markdown?** You don't need XeLaTeX or Quarto. The agents, rules, skills, and orchestration patterns work for any text/code artifact. Skip the `HelloWorld` demos and head straight to `/data-analysis`, `/review-paper`, `/lit-review`, or `/review-r`. > > **Session 2 onwards:** [MEMORY.md](MEMORY.md) (committed) collects generic `[LEARN]` entries that help all forkers; machine-specific notes accumulate in Claude Code's native auto memory (`~/.claude/projects/<project>/memory/`, machine-local, never committed). See [`.claude/rules/meta-governance.md`](.claude/rules/meta-governance.md) for the distinction.
1. Fork & Clone
# Fork this repo on GitHub (click "Fork" on the repo page), then: git clone https://github.com/YOUR_USERNAME/claude-code-my-workflow.git my-project cd my-project ./scripts/validate-setup.sh # reports missing tools with install links
Replace `YOUR_USERNAME` with your GitHub username.
2. Start Claude Code and Paste This Prompt
claude
**Using VS Code?** Open the Claude Code panel instead. Everything works the same — see the [full guide](https://psantanna.com/claude-code-my-workflow/workflow-guide.html#sec-setup) for details.
> **Avoid prompt fatigue.** On Claude Code ≥ 2.1.283, new interactive sessions start in **auto mode** by default (classifier-gated — most actions run, risky ones prompt; on earlier versions this applied to Pro/Max/Team); where auto is unavailable, Manual mode prompts per risky tool call. If you still see too many prompts, toggle **Auto-accept edits** mode (a keybinding; see the [permission modes section](https://psantanna.com/claude-code-my-workflow/workflow-guide.html#settings---permissions-and-hooks) of the guide) or run `claude --permission-mode acceptEdits`. **Bypass** mode skips permission prompts and safety checks (deny rules still apply), and Anthropic scopes it to isolated containers and VMs; it takes effect from the CLI flag, `--settings`, or user/managed settings (`~/.claude/settings.json`) — a bypass default in a project's `.claude/settings.json` is not honoured (the session starts in Manual). The template's `.claude/settings.json` sets no default mode (terminal sessions get the platform's auto mode); its `.vscode/settings.json` carries two bypass keys, but the current VS Code extension ignores them (it reads `claudeCode.initialPermissionMode` and `claudeCode.allowDangerouslySkipPermissions` only from your VS Code *user* settings, and never reads the unprefixed `allowDangerouslySkipPermissions` key), so VS Code sessions also start in auto unless your user settings say otherwise — set both `claudeCode.` keys there if you want bypass in VS Code — and the `.claude/settings.json` ships broad catch-all allows (`Bash(*)`, `Edit(**)`, `Write(**)` — 7 wildcard rules, not a curated list), so in Manual mode almost nothing prompts; auto mode drops the blanket `Bash(*)` and routes shell commands through its classifier. Working with restricted data? Add deny rules — see [TROUBLESHOOTING](TROUBLESHOOTING.md#keep-restricted-data-off-the-model).
Then paste the [starter prompt](https://psantanna.com/claude-code-my-workflow/workflow-guide.html#sec-first-session) from the guide, filling in your project details:
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 465 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- # My Claude Code Setup
- [](LICENSE)
- [](CHANGELOG.md)
- [](.github/CONTRIBUTING.md)
- > **Actively maintained.** A summary of how I use Claude Code for academic work — slides, papers, data analysis, and more — packaged so you can fork it for your own research. See [CHANGELOG.md](CHANGELOG.md) for the latest changes.
- **Live site:** [psantanna.com/claude-code-my-workflow](https://psantanna.com/claude-code-my-workflow/)
- A ready-to-fork foundation for AI-assisted academic work. You describe what you want — lecture slides, a research paper, a data analysis, a replication package — and Claude plans the approach, runs specialized agents, fixes issues, verifies quality, and presents results. Like a contractor who handles the entire job. Extracted from a production PhD course and extended by a growing [community](#community--extensions).
- ---
- ## Quick Start (5–10 minutes, plus ~30 min for first-time installs)
- > **Before you start:** Claude Code, git and Python 3 are the minimum. Python 3 runs the hooks, the gate suite (`./scripts/backtest.sh` — 11 checkers) and the quality scorer, and is pre-installed on macOS/Linux. To run the included `HelloWorld` demos end-to-end you also need XeLaTeX (Beamer sample) and Quarto (Quarto sample). R and the GitHub CLI are recommended. Full list in [Prerequisites](#prerequisites) below. Fastest path: clone first, then run `./scripts/validate-setup.sh` — it reports exactly what's missing with install links.
- >
- > **Only need Python/R/markdown?** You don't need XeLaTeX or Quarto. The agents, rules, skills, and orchestration patterns work for any text/code artifact. Skip the `HelloWorld` demos and head straight to `/data-analysis`, `/review-paper`, `/lit-review`, or `/review-r`.
- >
- > **Session 2 onwards:** [MEMORY.md](MEMORY.md) (committed) collects generic `[LEARN]` entries that help all forkers; machine-specific notes accumulate in Claude Code's native auto memory (`~/.claude/projects/<project>/memory/`, machine-local, never committed). See [`.claude/rules/meta-governance.md`](.claude/rules/meta-governance.md) for the distinction.
- ### 1. Fork & Clone
- **Unpublished work? Choose before you copy.** GitHub keeps a fork of a public repository public, and its visibility cannot be changed. For a paper, data or anything not yet public, click **Use this template** on the repository page instead, set the new repository to **Private**, and clone that one: `git clone https://github.com/YOUR_USERNAME/YOUR_REPO.git my-project`. Fork only for work that can be public.
- ```bash
- # Fork this repo on GitHub (click "Fork" on the repo page), then:
- git clone https://github.com/YOUR_USERNAME/claude-code-my-workflow.git my-project
- cd my-project
- ./scripts/validate-setup.sh # reports missing tools with install links
- ```
- Replace `YOUR_USERNAME` with your GitHub username.
- ### 2. Start Claude Code and Paste This Prompt
- ```bash
- claude
- ```
- **Using VS Code?** Open the Claude Code panel instead. Everything works the same — see the [full guide](https://psantanna.com/claude-code-my-workflow/workflow-guide.html#sec-setup) for details.
- **Using Codex (now also a tab in the ChatGPT desktop app) or Antigravity?** Start with [`AGENTS.md`](AGENTS.md). Those agents read the skills in [`.agents/skills/`](.agents/skills/): generated wrappers that point to the real instructions in `.claude/skills/`, for every skill one agent can run end to end. Claude Code's deny rules and guard hooks do not apply to them, so `AGENTS.md` lists what they must do by hand; the pre-commit gate and CI still apply. Skills built on several independent reviewers (`/review-paper --peer`, `/seven-pass-review`, `/verify-claims`) and the ones that manage Claude Code itself stay Claude-only — the list and the reasons are in [`scripts/sync-agent-skills.py`](scripts/sync-agent-skills.py).
- > **Avoid prompt fatigue.** On Claude Code ≥ 2.1.283, new interactive terminal and VS Code sessions start in **auto mode** by default (a classifier approves routine actions and prompts on risky ones). Where auto mode is unavailable, this template's `.claude/settings.json` ships broad allow rules (`Edit(**)`, `Write(**)`, `Bash(*)`), so routine work inside the repo runs unprompted. It does not set `permissions.blockWritesOutsideWorkingDirectories` (removed in v2.9.1), so Claude can change `.claude/settings*.json` itself. To turn that block on, add `"blockWritesOutsideWorkingDirectories": true` under `permissions` (Claude Code ≥ 2.1.314): Claude's file tools then refuse writes outside the working directories and every write to a Claude Code settings file, even inside the repository, and the worktree tools (`EnterWorktree`, `ExitWorktree`) leave the session. A `true` in any settings file applies, and lifting it takes a restart. If you still see prompts, press `Shift+Tab` to switch to **Auto-accept edits** (`claude --permission-mode acceptEdits`). For container/VM **Bypass** mode or restricted-data `deny` rules, see [TROUBLESHOOTING.md](TROUBLESHOOTING.md#claude-keeps-asking-permission-for-every-tool).
- Then paste the [starter prompt](https://psantanna.com/claude-code-my-workflow/workflow-guide.html#sec-first-session) from the guide, filling in your project details:
- > I am starting to work on **[PROJECT NAME]** in this repo. **[Describe your project in 2–3 sentences.]** I've set up the Claude Code academic workflow... Please read the configuration files and adapt them for my project. Enter plan mode and start.
- The [full guide](https://psantanna.com/claude-code-my-workflow/workflow-guide.html#sec-first-session) has the complete starter prompt with all the details.
- **What this does:** Claude reads all the configuration files, fills in your project name, institution, and preferences, then enters contractor mode — planning, implementing, and (within the skill you invoke) running the review + verify loop. You approve the plan, invoke a skill, and the skill handles the rest within its scope.
- > **Heavily adapting CLAUDE.md for a non-academic project?** Anthropic's built-in `/init` command will re-derive a `CLAUDE.md` from your codebase as a starting point. The pre-shipped CLAUDE.md in this template already covers the academic setup — you only need `/init` if your fork diverges substantially (e.g., a Python/ML project that doesn't use LaTeX or Quarto).
- ### 3. Verify Your Setup
- Before building real lectures, confirm your environment works:
- ```bash
- ./scripts/validate-setup.sh # Checks XeLaTeX, Quarto, Python, git, etc.
- ```
- Then inside Claude:
- ```text
- /compile-latex HelloWorld # Compiles Slides/HelloWorld.tex to PDF
- /deploy HelloWorld # Renders Quarto/HelloWorld.qmd to HTML
- ```
- If both succeed, delete `Slides/HelloWorld.tex` and `Quarto/HelloWorld.qmd` and start on your real work.
- ---
- ## How It Works
- ### Goal-first, gate-enforced (the v2.0 shift)
- You don't craft a perfect prompt — you **state a goal and let the work loop toward it under gates**. Specialist agents do the labor; enforcing gates decide when it's good enough; you adjudicate the disagreements they surface. Three things make that trustworthy:
- - **Real gates, not reminders.** One command — `./scripts/backtest.sh` — runs **eleven gates**: surface-sync, skill integrity, model currency against the SSoT, link and anchor resolution, Agent Skills spec conformance, staleness (including source-vs-published divergence), repo hygiene, derived counts (enumerable claims re-counted from disk), ledger coverage (the qualification ledger and the checks that actually run must agree in both directions, and every hook declared in settings must exist and be invocable), a seeded hook battery (every active guard hook is re-fired against the failure it targets, alongside clean controls, on every run), and a cross-platform portability suite (path, encoding, line-ending and git-output cases). A version-controlled pre-commit hook (`./scripts/install-hooks.sh`) runs it plus the quality check (≥80) on *every* commit. In the session, destructive git commands are refused by permission `deny` rules in `.claude/settings.json`, which Claude Code checks itself, with no hook process. Two `PreToolUse` hooks remain, and Claude Code starts each only for the commands it checks: `dirty-tree-guard` for `git merge`, `pull` and `rebase`, and `issue-guard` for `gh`. Only `issue-guard` is registered with `"onFailure": "block"` (Claude Code ≥ 2.1.295), so a machine without `python3` no longer has Bash, Edit and Write blocked; its `gh` commands are refused until `python3` works. The review runtime also re-checks any reviewer-introduced "fatal" finding before it counts.
- <details><summary><em>What the in-session guards catch, and what they miss (click to expand)</em></summary>
- The deny rules refuse `git reset --hard`, every `git clean` (dry runs included), `git push --force` and `-f` (`--force-with-lease` still runs), `git add -A`, `--all` and `.` wherever they appear among the arguments, and a checkout or restore of the whole tree (`git checkout .`, `git checkout -- .`, `git checkout HEAD -- .`, `git restore .`, `git restore -- .`; also `git restore --staged .`, which only unstages). They also refuse reads and edits of `.env` files and reads of `*.pem`, `*.key` and `credentials*` files. Claude Code applies a deny rule to every part of a compound command, including a subshell or a `$(…)` substitution, strips wrappers such as `timeout` and `nohup`, and keeps it in every permission mode. It does not match a rewritten spelling (`git -C . push --force`, `git -c x=y push`, `/usr/bin/git`, `bash -c '…'`), and Anthropic's permissions docs call Bash deny rules a guard on the invocation Claude usually produces, not a security boundary. `dirty-tree-guard` refuses a merge, pull or rebase while tracked files have uncommitted changes; untracked files do not count, `--abort` and `--continue` pass, and `ALLOW_DIRTY_MERGE=1` overrides it. It reads the session's directory, so it misses a repository reached by `cd elsewhere &&` or `git -C`, and it fails open. No hook refuses shell writes into `.claude/settings*.json`, `.claude/hooks/` or `.githooks/` any more; `blockWritesOutsideWorkingDirectories` still refuses file-tool writes to the settings files. Nothing here recovers anything either: the transcript and `git reflog` are an audit trail and a commit-history aid, and neither holds the bytes of an uncommitted edit or an untracked file.
- </details>
- - **Every gate is qualified, and the ledger is itself a gate.** Each one has been shown a planted defect and confirmed to go red, with recall and false-alarm rate recorded in [`quality_reports/qualification/LEDGER.md`](quality_reports/qualification/LEDGER.md) — and that ledger is now load-bearing rather than aspirational: a registered check with no row there fails the build, and a row naming a checker that no longer exists fails too. Checks that have *not* been qualified are listed there by name as visible debt — because an unqualified check is not weak evidence, it is none. Run [`/vaccinate`](.claude/skills/vaccinate/SKILL.md) to qualify one.
- - **A real orchestration runtime.** Reviews fan out to forked specialist agents, reduce over a shared finding schema, judge with a hallucination gate, and loop until dry — see [`orchestrator-protocol.md`](.claude/rules/orchestrator-protocol.md).
- - **Ground truth as a process.** A mismatch isn't always a failure: a defensible, *named* alternative is recorded as `EXPLAINED` and carried into your response-to-referees, while genuine errors stay fail-closed.
- This is **not** an autonomous daemon — the loop is always you- or skill-initiated, and you stay the auditor. Scheduled automation handles recurring chores and notifies only on findings — cloud [Routines](.claude/references/scheduled-routines.md) for committed-repo checks (weekly lit-delta), Desktop scheduled tasks for anything touching local data (inbox triage, and the nightly reproducibility check).
- ### Contractor Mode
- You describe a task. For complex or ambiguous requests, Claude first creates a requirements specification with MUST/SHOULD/MAY priorities and clarity status (CLEAR/ASSUMED/BLOCKED). You approve the spec, then Claude plans the approach and runs the right skill — or, for user-invoked skills such as `/create-lecture`, tells you which one to run (e.g. `/create-lecture`, `/qa-quarto`, `/review-paper --adversarial`). That skill implements the orchestrator runtime internally — implement, verify, review, fix, re-verify, score — and returns a summary when the work meets quality standards. Say "just do it" and it runs the full loop; commits still require an explicit `/commit` (which the pre-commit hook then gates).
- ### Specialized Agents
- Instead of one general-purpose reviewer, 18 focused agents each check one dimension. A representative sample:
- - **proofreader** — grammar/typos
- - **slide-auditor** — visual layout
- - **pedagogy-reviewer** — teaching quality
- - **r-reviewer** — R code quality
- - **domain-reviewer** — field-specific correctness, slides (template — customize for your field)
- - **domain-referee** / **methods-referee** / **editor** — manuscript peer-review pipeline (`/review-paper --peer`)
- Each is better at its narrow task than a generalist would be. The `/slide-excellence` skill runs the slide-review agents in parallel; `/review-paper --peer` runs the paper-review pipeline. The same pattern extends to any academic artifact — manuscripts, data pipelines, proposals.
- ### Adversarial QA
- Two agents work in opposition: the **critic** reads both Beamer and Quarto and produces harsh findings. The **fixer** implements exactly what the critic found. They **loop until dry** — converging after two consecutive rounds surface no new issue (a 5-round cap is the fallback, not the primary stop). This catches errors that single-pass review misses.
- ### Quality Review
- Every artifact gets a score (0–100). Scores below threshold halt the workflow and surface the findings — the user decides whether to fix or explicitly override:
- - **80** — commit threshold
- - **90** — PR threshold
- - **95** — excellence (aspirational)
- > **Framing honesty:** Thresholds are advisory at the harness level — the `/commit` skill runs quality checks and halts on failure. **And** as of v2.0, running `./scripts/install-hooks.sh` once installs a real pre-commit hook (`.githooks/pre-commit`) that runs the backtest gate suite (the hook battery only when a hook, its settings or the battery itself is staged; CI always runs everything) plus the quality (≥80) gate on *every* commit, so bypassing the skill no longer bypasses the review. Opt out per-commit with `SKIP_QUALITY_GATE=1` or `git commit --no-verify`.
- ### Context Survival
- Plans, specifications, and session logs survive auto-compression and session boundaries. The PreCompact hook saves a context snapshot before Claude's auto-compression triggers, ensuring critical decisions are never lost. MEMORY.md accumulates learning across sessions, so patterns discovered in one session inform future work.
- For *forced* compression (long pipelines, mid-plan handoffs), `/compress-session` (v1.9.0) distils the conversation into a structured note — decisions, next actions, and **discarded-as-noise** — instead of letting auto-compaction truncate. `/promote-memory` (v1.9.0) periodically harvests generic learnings from native auto memory to committed MEMORY.md via a five-critic council.
- ### Verification Discipline (v1.7.0+)
- Multiple complementary verification layers run before submission:
- - **`/verify-claims`** (v1.7.0) — Chain-of-Verification with a fresh-context verifier that cannot self-confirm because it has never seen the draft. v1.9.0 adds HIGH/MED/LOW-WARN severity tiers; HIGH-WARN findings (fabricated citation, numerical contradiction) fail the verification closed — the draft is never reported as verified; `/commit` does not read these verdicts, so resolving them before committing is on you.
- - **`/audit-reproducibility`** (v1.4.0; Stata coverage v1.9.0) — every numeric claim in the manuscript is cross-checked against the script output that produced it. v1.9.0 adds `passport.yaml` — a per-paper YAML state file with PASS/FAIL/STALE/UNVERIFIED status per claim.
- - **`/humanize`** (v1.9.0) — detect AI-voice tells (boilerplate transitions, hedging stacking, sycophancy) before submission. Read-only by design; auto-rewriting degrades quality.
- - **`/review-paper --peer <journal> --variance N`** (v1.9.0) — runs N referees with sampled dispositions and reports a **decision distribution**, not a point estimate. Motivated by AgentReview (EMNLP 2024) finding 37% of decisions vary purely from disposition sampling.
- ---
- ## The Guide
- For a comprehensive walkthrough, read the **[full guide](https://psantanna.com/claude-code-my-workflow/workflow-guide.html)** (or see the [source](guide/workflow-guide.qmd)).
- It covers:
- 1. **Why This Workflow Exists** — the problem and the vision
- 2. **Getting Started** — fork, paste one prompt, and Claude sets up the rest
- 3. **The System in Action** — specialized agents, adversarial QA, quality scoring
- 4. **The Building Blocks** — CLAUDE.md, rules, skills, agents, hooks, memory
- 5. **Workflow Patterns** — slides, research, reproducibility, presentation rhetoric, sequential adversarial audits, and more
- 6. **The Ecosystem** — extensions by clo-author, claudeblattman, MixtapeTools, autoresearch, ClaudeCodeTools, and a growing community
- 7. **Customizing for Your Domain** — creating your own reviewers and knowledge bases
- ### 2026 Features
- The guide covers Claude Code's latest capabilities:
- - **Model lineup** — the **Fable tier** (opt-in via `/model fable` or the `best` alias) is the top tier for long-horizon work; the **Opus tier** is the Claude Code default and the template's high-judgment tier. Current point versions, prices, effort defaults, and the **provider-dependent alias table** live in the single source of truth, [`model-versions.md`](.claude/references/model-versions.md) — surfaces here stay tier-abstract so they cannot go stale, and the staleness gate fails the build when the SSoT's own expiry passes.
- - **Effort levels** — `/effort` sets cost vs. thoroughness (`low` / `medium` / `high` / `xhigh` / `max`). **Default effort differs by tier** (per the [model SSoT](.claude/references/model-versions.md)): the current Opus and Haiku tiers default to `medium` — and Opus's `medium` matches the prior Opus generation's `high` — while the Fable and Sonnet tiers default to `high`. Set effort explicitly (`CLAUDE_CODE_SUBAGENT_EFFORT` sets the subagent default), lower it before prompting for brevity, reserve `xhigh` for extended exploration and the `ultracode` toggle (dynamic workflows; since Claude Code 2.1.284 it no longer forces `xhigh`) for the largest autonomous runs, with `workflowSizeGuideline` to cap how many agents a workflow plans; `maxEffortLevel` caps effort on every surface.
- - **`/goal <verifiable condition>`** (v1.9.0; Anthropic May 2026) — keep working across turns until a fast model confirms the condition holds. Pairs with `/commit` quality gates for verified-end-state runs.
- - **`claude agents` dashboard** (v1.9.0; Anthropic May 2026) — single screen for parallel review work (`/review-paper --peer`, `/slide-excellence`).
- - **Cost-Conscious Composition** — prompt-cache TTL (5-min default on API keys; on Claude subscriptions **1 hour for the main conversation but 5 minutes for subagents**, unless you set `subagentPromptCacheTtl`), 70/20/10 model routing (Haiku/Sonnet/Opus), `/usage` monitoring (it absorbed `/cost`), Agent SDK credit-pool split (2026-06-15).
- - **Skill frontmatter** — `effort`, `context: fork`, `agent`, `hooks`, `disable-model-invocation` (v1.8.0+), `disallowed-tools` (the *actual* tool restriction — `allowed-tools` only pre-approves), `paths` (glob-scoped auto-activation), and dynamic content (`$ARGUMENTS`, `!command` syntax)
- - **Permission modes** — Manual (config value `default`), Accept edits, Plan, **Auto** (classifier-gated; the built-in starting mode for new interactive terminal and VS Code sessions on Claude Code ≥ 2.1.283 — on earlier versions, on Pro, Max, and Team since 2026-08-14 — and available on Bedrock / Google Cloud / Foundry without an opt-in flag), Bypass
- - **Hook handler types** — five (command, HTTP, MCP tool, prompt, agent) across 33 hook events (Claude Code 2.1.318); hooks see `effort.level` and `$CLAUDE_EFFORT` (Apr 2026 Week 19)
- - **Advanced agent configuration** — model, maxTurns, isolation, tool restrictions; `model-routing.md` rule codifies per-agent tier (v1.9.0)
- - **Worktree base ref** (v1.9.0; Anthropic Apr 2026) — `worktree.baseRef` setting controls `fresh` (default; remote default-branch) vs `head` (local HEAD) for new worktrees
- - **Built-in skills** — `/fewer-permission-prompts`, `/team-onboarding`, `/autofix-pr`, `/powerup`, Ultraplan, `/loop` (self-pacing)
- - **Plugins** — `/plugin` (its **Discover** tab) for third-party extensions. Since 2.1.287 a plugin can also ship a *mod*, code inside Claude Code that on a personal account can override deny rules and hooks (see [TROUBLESHOOTING](TROUBLESHOOTING.md#keep-restricted-data-off-the-model))
- - **Mid-2026 additions** (Jun–Sep 2026) — `/skill-doctor` (what each skill costs in context and how often it fires), `claude plugin eval` (score a plugin against test cases vs a no-plugin baseline), `maxEffortLevel` (cap effort on every surface — a hard ceiling for a fixed grant budget), built-in output styles (**Concise** for everyday work; **Learning**, which leaves parts for you to write — pairs with `/scaffold-exercises`; **Explanatory**; and **Proactive**, which skips plan mode unless you ask, so it works against plan-first), subagents running in the background and fork mode on by default, `/fork` (continue a copy of the conversation in a background session), `/doctor` (setup checkup), and `autoUpdatesChannel: "stable"` for deadline weeks
- ---
- ## Use Cases
- | Academic Task | How This Workflow Helps |
- |---------------|----------------------|
- | Lecture slides (Beamer/Quarto) | Full creation, translation, multi-agent review, deployment |
- | Research papers | Literature review, manuscript review, simulated peer review (`/review-paper --peer [journal]`), reviewer-disposition variance reporting (`--variance N`) |
- | Data analysis | End-to-end R pipelines (`/data-analysis`) or Stata pipelines via `stata-mcp` (`/stata-replication`, v1.9.0), replication verification, publication-ready output |
- | Monte Carlo simulations | Reproducible simulation studies (`/simulation-study`, v1.10.0) — parameterized DGP, estimator grid, bias/RMSE/coverage/size/power with Monte Carlo SEs, dedicated `sim-reviewer` review pass |
- | Package development | R package release gate (`/r-package-check`, v1.10.0) — `devtools::document()` + tests + `R CMD check --as-cran` + CRAN-policy triage + `r-package-reviewer` (Stata / Python checks on the roadmap) |
- | Replication packages | AEA-compliant packaging, reproducibility audit trails, `passport.yaml` claims provenance (v1.9.0) |
- | Presentations | Rhetoric of decks principles, visual audit, cognitive load review |
- | Research proposals | Structured drafting with adversarial critique |
- | Preregistration | OSF / AsPredicted / AEA RCT Registry-ready document (`/preregister --style`) — full workflow in Pattern 16 |
- | Manuscript submission discipline | `/humanize` (detect AI voice), `/verify-claims` HIGH-WARN fail-closed reporting (a fabricated citation is never reported as verified), reviewer-disposition variance |
- **Disciplines preloaded:** Economics (top-5 journal profiles, R conventions) and Political Science (APSR / AJPS / JOP profiles, formal-theory + survey-experiment paper types, conjoint/`cjoint` conventions). Forkers extend for psych / sociology / public-health via journal profiles + paper types + discipline cards.
- ### One repo, many project types
- This workflow is designed as a **single hub for an entire research program** — not one paper at a time. The same `CLAUDE.md`, rules, agents, and quality gates serve courses and lectures, papers and referee reports, data analysis and replication packages, **Monte Carlo simulation studies** (`/simulation-study` + `sim-reviewer`), and the **R package release gate** (`/r-package-check` + `r-package-reviewer`) — all new in v1.10.0. *On the roadmap:* Stata / Python package checks (SSC / PyPI) and personal-productivity workflows. See [`.claude/references/v2.0-backlog.md`](.claude/references/v2.0-backlog.md) for what's next.
- ---
- ## What's Included
- <details>
- <summary><strong>18 agents, 62 skills, 37 rules, 9 hooks</strong> (click to expand)</summary>
- ### Agents (`.claude/agents/`)
- <!-- surface-sync-table: agents -->
- | Agent | What It Does |
- |-------|-------------|
- | `proofreader` | Grammar, typos, overflow, consistency review |
- | `slide-auditor` | Visual layout audit (overflow, font consistency, spacing) |
- | `pedagogy-reviewer` | 13-pattern pedagogical review (narrative arc, notation density, pacing) |
- | `r-reviewer` | R code quality, reproducibility, and domain correctness |
- | `tikz-reviewer` | Merciless TikZ diagram visual critique |
- | `beamer-translator` | Beamer-to-Quarto translation specialist |
- | `quarto-critic` | Adversarial QA comparing Quarto against Beamer benchmark |
- | `quarto-fixer` | Implements fixes from the critic agent |
- | `verifier` | End-to-end task completion verification |
- | `domain-reviewer` | **Template** for your field-specific substance reviewer |
- | `claim-verifier` (v1.7.0) | Chain-of-Verification fact-checker in a fresh context (never a conversation fork) |
- | `editor` (v1.5.0) | Journal editor for `/review-paper --peer` (desk review + referee selection + synthesis) |
- | `domain-referee` (v1.5.0) | Disposition-primed substance referee for `--peer` mode |
- | `methods-referee` (v1.5.0+) | Paper-type-aware methodology referee (6 paper types) |
- | `humanize-auditor` (v1.9.0) | Read-only AI-voice auditor invoked by `/humanize` |
- | `promote-memory-council` (v1.9.0) | Five-critic council for `[LEARN]` promotion to MEMORY.md |
- | `sim-reviewer` (v1.10.0) | Monte Carlo simulation reviewer — DGP/estimand match, Monte Carlo SE, coverage-vs-truth, claims↔tables parity |
- | `r-package-reviewer` (v1.10.0) | R package-source reviewer — DESCRIPTION/NAMESPACE hygiene, roxygen completeness, testthat coverage, CRAN-policy red flags |
- ### Skills (`.claude/skills/`)
- > **Start here on Day 1 — a short list to try first:**
- > - **Explore & frame:** `/interview-me` (formalize a fuzzy idea) · `/lit-review` (literature synthesis + gap check)
- > - **Run & audit data:** `/data-analysis` (end-to-end R pipeline; or `/stata-replication` for Stata) · `/audit-reproducibility` (verify manuscript numbers ↔ code outputs)
- > - **Review & ship:** `/review-paper --peer <journal>` (simulated editor + 2 referees, plus `/verify-claims` fact-check) · `/commit` (run gates and commit cleanly)
- > - **Teach:** `/create-lecture` (draft a lecture deck) · `/compile-latex` (build the Beamer PDF)
- <!-- surface-sync-table: skills -->
- | Skill | What It Does |
- |-------|-------------|
- | `/compile-latex` | 3-pass XeLaTeX compilation with bibtex |
- | `/deploy` | Render Quarto + sync to GitHub Pages |
- | `/extract-tikz` | TikZ diagrams to PDF to SVG pipeline |
- | `/proofread` | Launch proofreader on a file |
- | `/visual-audit` | Visual layout audit of a deck (the `slide-auditor` checks, run inline) |
- | `/pedagogy-review` | Launch pedagogy-reviewer on a file |
- | `/review-r` | Launch R code reviewer |
- | `/qa-quarto` | Adversarial critic-fixer loop (loops until dry; 5-round cap is a fallback) |
- | `/slide-excellence` | Combined multi-agent review |
- | `/translate-to-quarto` | Full Beamer-to-Quarto translation — Phase 0 pre-flight plus 12 translation phases (1–11 and a 6.5 pedagogy review) |
- | `/vaccinate` | Measure whether a check, gate, or AI reviewer actually detects the failure it targets — seeds defects + a clean control, reports recall and false-positive rate into a qualification ledger |
- | `/adjudicate-review` | Turn incoming findings — AI review, referee report, linter, second model — into verified fixes. Every finding is a CANDIDATE until checked against the source |
- | `/blast-radius` | Before and after changing anything shared (return value, schema, default, units), enumerate every consumer and actually run them |
- | `/credible-claims` | Research brief before delegating, claim record after. Keeps faster execution from being mistaken for credible evidence |
- | `/differential-audit` | Compare two implementations — a port, a replication, a refactor, a version upgrade — so that agreement means something |
- | `/oracle-review` | Run an external frontier-model referee (Claude Code → another vendor's frontier model via the Oracle CLI) and adjudicate what comes back |
- | `/verify-artifact` | Prove the file you are about to send IS the thing you mean — rebuild, verify integrity, diff against source |
- | `/voice-profile` | Extract a written voice profile from your own prior papers, then audit drafts against it — the positive counterpart to `/humanize`, which only detects AI tells |
- | `/validate-bib` | Cross-reference citations against bibliography |
- | `/verify` | Run the backtest and the quality score on what is about to be committed; Claude Code tells Claude to run it before committing (2.1.286+), a reminder next to the enforcing pre-commit hook |
- | `/devils-advocate` | Challenge design decisions before committing |
- | `/create-lecture` | Full lecture creation workflow |
- | `/commit` | Run the gates, then commit on a branch; `--pr` also pushes and opens a pull request. Never merges — that waits for your say-so |
- | `/lit-review` | Literature search, synthesis, and gap identification |
- | `/research-ideation` | Generate research questions and empirical strategies |
- | `/interview-me` | Interactive interview to formalize a research idea |
- | `/review-paper` | Manuscript review: structure, econometrics, referee objections |
- | `/data-analysis` | End-to-end R analysis with publication-ready output |
- | `/learn` | Extract non-obvious discoveries into persistent skills |
- | `/context-status` | Show session health and context usage |
- | `/deep-audit` | Adversarial audit of a theory, proof, paper, codebase or set of claims — decompose, independent skeptics, a separate judge per finding, fix, re-verify; repo-wide consistency is one application |
- | `/permission-check` | Diagnose permission layers when prompts fire unexpectedly |
- | `/audit-reproducibility` | Enforce tolerance thresholds on paper ↔ code numeric claims |
- | `/new-diagram` | Scaffold a TikZ diagram from the snippet gallery with prevention + review |
- | `/respond-to-referees` | R&R response-letter generator (maps referee comments to revisions) |
- | `/seven-pass-review` | Seven-pass adversarial manuscript review (parallel forked subagents) |
- | `/checkpoint` | Structured session-handoff snapshot (state + plan pointers + next actions). Companion to narrative session logs. |
- | `/preregister` | Generate a preregistration document (OSF / AsPredicted / AEA RCT Registry style) from a research spec |
- | `/verify-claims` (v1.7.0) | Chain-of-Verification fact-check (fresh-context verifier). HIGH/MED/LOW-WARN severity tiers (v1.9.0); HIGH-WARN fails closed in the report (the draft is never presented as verified). |
- | `/humanize` (v1.9.0) | Detect AI-voice tells in academic prose (10 detection categories; read-only, no rewrite) |
- | `/compress-session` (v1.9.0) | Distil current session into structured notes (decisions, next actions, *discarded-as-noise*) before auto-compaction |
- | `/promote-memory` (v1.9.0) | Five-critic council that votes on which `[LEARN]` entries graduate from native auto memory to MEMORY.md |
- | `/stata-replication` (v1.9.0) | End-to-end Stata pipeline via the `stata-mcp` MCP server (mirrors `/data-analysis` for R-first projects) |
- | `/simulation-study` (v1.10.0) | Scaffold + run a reproducible Monte Carlo study — parameterized DGP, estimator grid, seeded replications, bias/RMSE/coverage/size/power with Monte Carlo SEs |
- | `/r-package-check` (v1.10.0) | R package release gate — `devtools::document()` + tests + `R CMD check --as-cran`, triage ERROR/WARNING/NOTE vs CRAN policy, `r-package-reviewer` pass |
- | `/replication-package` (v2.0) | Assemble a submission-ready DCAS / openICPSR replication package — standard README, dataset manifest, computational-requirements capture, Table/Figure → script:line map, confidential-data deposit note (blocks on `/audit-reproducibility` FAIL) |
- | `/challenge` | Stress-test a finding against the choices you didn't make — specification curve over the discrete forks, then named sensitivity statistics (E-value, Cinelli–Hazlett RV, Oster δ) against the identifying assumption |
- | `/capture-environment` (v2.0) | Snapshot the computational environment for a replication package — renv.lock + sessionInfo.txt (R), requirements.txt / environment.yml / uv.lock (Python), Stata version + ado list, seeds/RNG, optional pinning Dockerfile |
- | `/power-analysis` (v2.0) | Power / required-N / minimum-detectable-effect for study design — two-arm RCT (clustering/ICC, unequal allocation), multi-arm corrections, simulation-based power for non-standard designs; feeds `/preregister` |
- | `/disclosure-check` (v2.0) | Statistical-disclosure-limitation pre-screen for restricted/confidential-data outputs (small cells, complementary-suppression gaps, dominance, PII); CRITICAL/WARNING/OK + gate |
- | `/grant-proposal` (v2.0) | Scaffold an NSF/NIH/ERC/foundation grant proposal by composing primitives (spec → aims/methods, delegated DMP + facilities, coherence pass + requirements checklist) |
- | `/data-management-plan` (v2.0) | Funder-compliant Data Management Plan (NSF / NIH DMS 2023 / ERC / Horizon Europe) — folds in disclosure-avoidance + IRB constraints and a replication-package/environment plan; outputs a draft + funder checklist |
- | `/coauthor-brief` (v2.0) | Collaborator handoff brief — what changed since last brief, per-artifact state, open questions, reproduce-locally + restricted-data access steps |
- | `/triage-inbox` (v2.0) | Schedulable academic inbox + calendar triage via Gmail/Calendar MCP — classifies referee requests, R&R/editor, co-author threads, seminar/conference invites, grant/admin deadlines; proposes one human-gated action each (draft reply, calendar hold, scaffold a referee project, `/coauthor-brief`, snooze); emits a digest + referee-obligations tracker; degrades gracefully when MCP is absent; never auto-sends |
- | `/diagnose` (v2.0) | Root-cause a wrong/failing empirical result — disciplined reproduce → minimise → hypothesise → instrument → fix loop; tuned for research-code bugs (type coercion, NA/merge blow-ups, clustering/SE choice, seed/package-version drift); `--no-fix` localizes without editing |
- | `/submission-disclosures` (v2.1) | The submission-time disclosure block: AI-use disclosure matched to the target journal's verified-current policy, CRediT contributor roles, conflict-of-interest, and data-availability statements (NOT statistical disclosure — that's `/disclosure-check`) |
- | `/syllabus` (v2.0) | Build/restructure a course syllabus from a topic or reading list — course description + prerequisites, week-by-week schedule (topic→readings→deliverables), measurable learning objectives, assessment scheme + rubric, standard policies (late work / AI use / integrity / accessibility), and a per-week work-list mapping weeks to `/create-lecture` decks; economics-aware (PhD metrics/micro/macro sequences, undergrad) |
- | `/teach-from-paper` (v2.0) | Reads a paper end-to-end and pitches it to a stated audience level — lecture outline (motivation → setup → key result → method → takeaways), the 3-5 results worth presenting with intuition, a slide skeleton for `/create-lecture`, discussion questions, and a problem-set brief for `/scaffold-exercises` |
- | `/respond-to-eval` (v2.0) | Teaching analogue of `/respond-to-referees` — clusters course-eval comments into themes, weights by frequency (signal vs noise), classifies Keep / Change / Investigate / Out-of-scope, and drafts concrete changes mapped to the syllabus + slide decks; saves the plan to `quality_reports/teaching/` |
- | `/scaffold-exercises` (v2.0) | Scaffold a graded problem set across analytical/empirical/coding types, with worked solutions and "why this matters" explainers emitted to a separate solution key |
- | `/new-skill` (v2.0) | Scaffold a new skill that follows this repo's conventions — interviews for purpose, triggers, and tools, writes `.claude/skills/<name>/SKILL.md` from the template with frontmatter/body that pass `check-skill-integrity.py` first try, then reminds to add the surface-table rows |
- | `/issues` (v2.6) | GitHub issues as the project's to-do list and memory — files each confirmed finding as its own issue after checking open and closed issues for a duplicate, lists what is open for the work at hand, and closes an issue with a comment recording what was wrong, what was tried, and how it was fixed; shows every draft and posts nothing without a yes; warns before posting to a public repository |
- ### Research Workflow
- | Feature | What It Does |
- |---------|-------------|
- | Exploration folder | Structured `explorations/` sandbox with graduate/archive lifecycle |
- | Fast-track workflow | 60/100 quality threshold for rapid prototyping |
- | Simplified orchestrator | implement → verify → score → done (no multi-round reviews) |
- | Enhanced session logging | Structured tables for changes, decisions, verification |
- | Merge-only reporting | Quality reports at merge time only |
- | Math line-length exception | Long lines acceptable for documented formulas |
- | Workflow quick reference | One-page cheat sheet at `.claude/WORKFLOW_QUICK_REF.md` |
- ### Rules (`.claude/rules/`)
- Rules use path-scoped loading: **always-on** rules load every session; **path-scoped** rules load only when Claude works on matching files. Adherence degrades as instruction files grow (official guidance: keep `CLAUDE.md` under ~200 lines), so less is more.
- **Always-on** (no `paths:` frontmatter — load every session):
- | Rule | What It Enforces |
- |------|-----------------|
- | `plan-first-workflow` | Plan mode for non-trivial tasks + context preservation |
- | `session-logging` | Three logging triggers: post-plan, incremental, end-of-session |
- | `progress-reports` | GitHub as memory — issues as defect memory, `quality_reports/` as work memory, `MEMORY.md` as lesson memory |
- | `repo-hygiene` | Scratch must not become main — enforced by `check-repo-hygiene.py` on every commit |
- | `prompt-shaping` (v2.0) | Ambient habit — shape informal/ambiguous requests before acting (replaces the retired `/prompt` + `/prompt-only` skills) |
- **Path-scoped** (load only when working on matching files):
- | Rule | Triggers On | What It Enforces |
- |------|------------|-----------------|
- | `orchestrator-protocol` | `.claude/skills/`, `.claude/agents/`, orchestration refs | Goal-first review runtime: fan-out → reduce → judge (+ hallucination gate) → loop-until-dry — loads while fan-out skills and reviewer agents are written; the skills link it directly |
- | `meta-governance` | top-level docs, `guide/`, `docs/`, `templates/`, `.claude/`, gate scripts | Template vs. working project distinctions — maintainer work only |
- | `verification-protocol` | `.tex`, `.qmd`, `docs/` | Task completion checklist |
- | `single-source-of-truth` | `Figures/`, `.tex`, `.qmd` | No content duplication; Beamer is authoritative |
- | `quality-gates` | `.tex`, `.qmd`, `*.R` | 80/90/95 scoring + tolerance thresholds |
- | `r-code-conventions` | `*.R` | R coding standards + math line-length exception |
- | `tikz-visual-quality` | `.tex` | TikZ diagram visual standards |
- | `beamer-quarto-sync` | `.tex`, `.qmd` | Auto-sync Beamer edits to Quarto |
- | `pdf-processing` | `master_supporting_docs/` | Safe large PDF handling |
- | `proofreading-protocol` | `.tex`, `.qmd`, `quality_reports/` | Propose-first, then apply with approval |
- | `no-pause-beamer` | `.tex` | No overlay commands in Beamer |
- | `replication-protocol` | `*.R` | Replicate original results before extending |
- | `knowledge-base-template` | `.tex`, `.qmd`, `*.R` | Notation/application registry template |
- | `orchestrator-research` | `*.R`, `explorations/` | Simple orchestrator for research (no multi-round reviews) |
- | `exploration-folder-protocol` | `explorations/` | Structured sandbox for experimental work |
- | `exploration-fast-track` | `explorations/` | Lightweight exploration workflow (60/100 threshold) |
- | `tikz-prevention` (v1.3.0) | `Slides/**`, `Figures/**`, `Preambles/**` | TikZ pre-flight grep checks (P3/P4 collision avoidance) |
- | `agent-authored-code` (v2.5) | `**/*.sh`, `**/*.py`, `**/*.R`, `**/*.do` | The bugs are usually ours: dry-run before any bulk edit, resolve paths before `cd`, monitor by PID file not `pgrep`, cover every terminal state |
- | `writing-with-ai` (v2.5) | `**/*.tex`, `**/*.qmd`, `**/*.md`, `**/*.Rmd` | Internal vs external-facing documents; why a model cannot make its own output stop reading as model output; the human-readable standard |
- | `issue-ledger` (v2.5) | `.github/**` | Which work gets a GitHub issue (shipped bugs, deferred improvements, blocking owner decisions, one summary issue per review round; never restricted data), the evidence standard — denominator, positive/negative control, explicit non-scope — and the closing comment |
- | `tikz-measurement` (v1.3.0) | `Slides/**`, `Figures/**`, `Preambles/**`, `scripts/**` | Bézier curve depth math + 6-pass collision protocol (from MixtapeTools) |
- | `content-invariants` (v1.6.x) | `.tex`, `.qmd`, `Preambles/`, `scripts/R/**` | Numbered invariants INV-1–INV-12 (palette sync, Beamer↔Quarto notation parity, no overlays, at most two boxes per slide, `set.seed` once, relative paths, …) that critics cite by number |
- | `cross-artifact-review` (v1.4.0) | `master_supporting_docs/`, `.tex`, `.qmd` | Paper ↔ code dependency graph; auto-invokes `/review-r` + `/audit-reproducibility` |
- | `post-flight-verification` (v1.7.0) | Skills generating factual claims | Chain-of-Verification protocol with a fresh-context verifier |
- | `summary-parity` (v1.7.0) | `CHANGELOG.md`, `README.md`, `.qmd`, skill/rule/agent `.md` | Anti-whack-a-mole: re-verify summaries against their bodies |
- | `model-routing` (v1.9.0) | `.claude/agents/**/*.md`, `.claude/skills/**/SKILL.md` | 70/20/10 architect/editor split (Haiku/Sonnet/Opus) |
- | `review-fencing` (v2.5.1) | `.tex`/`.qmd`, `master_supporting_docs/`, `quality_reports/` audit dirs, `claim-verifier.md` | Reviewer independence is a property of the environment — neutral copy outside the checkout, prior verdicts excluded, own reading first, positive controls fenced from committed answer keys |
- | `stata-code-conventions` (v1.9.0) | `**/*.do`, `scripts/stata/**` | Stata header scaffold, numbered pipeline, esttab, clustering discipline, AEA compliance |
- | `simulation-conventions` (v1.10.0) | `**/*simulation*.R`, `**/*_sim.R`, `explorations/**` | Monte Carlo discipline: DGP/estimand, L'Ecuyer seeding, Monte Carlo SE, coverage-vs-truth, raw-result storage |
- | `r-package-conventions` (v1.10.0) | `R/**`, `tests/**`, `DESCRIPTION`, `NAMESPACE`, `man/**` | R package-source standards: no `library()` in `R/`, roxygen NAMESPACE, Imports/Suggests, testthat 3e, CRAN policy |
- | `confidential-data` (v2.0) | `data/**`, `**/*.dta`, `**/restricted/**`, `**/confidential/**` | Restricted/IRB-data protocol: never commit raw data, disclosure clearance before release, restricted-data-safe multi-author git topology |
- | `inference-robustness` (v2.0) | `scripts/**/*.R`, `scripts/**/*.do`, `scripts/**/*.py` | Multiple-testing (FWER/Romano-Wolf vs FDR/Anderson sharpened-q, pre-register the family) + specification-curve / leave-one-out / wild-cluster-bootstrap robustness |
- ### Templates (`templates/`)
- | Template | What It Does |
- |----------|-------------|
- | `session-log.md` | Structured session logging format |
- | `quality-report.md` | Merge-time quality report format |
- | `exploration-readme.md` | Exploration project README template |
- | `archive-readme.md` | Archive documentation template |
- | `requirements-spec.md` | MUST/SHOULD/MAY requirements framework with clarity status |
- | `constitutional-governance.md` | Template for defining non-negotiable principles vs. preferences |
- | `skill-template.md` | Academic skill creation template with domain-specific examples |
- | `decision-record.md` | Architectural decision record (ADR) template |
- | `journal-profile-template.md` | Journal profile for `/review-paper --peer` editor calibration |
- | `preregistration-template.md` (v1.8.0) | Preregistration document scaffold (OSF / AsPredicted / AEA RCT) |
- | `passport-template.yaml` (v1.9.0) | Per-paper YAML passport for numeric-claim provenance (used by `/audit-reproducibility`) |
- | `response-to-referees.md` | R&R response document scaffold |
- | `executor-contract.md` (v2.5.1) | Dispatchable goal contract for a delegated task — goal, acceptance bar, exact paths, gates it must pass, output contract, and the mechanisms the executor may refuse |
- | `triangulation-ledger.md` | What each robustness check will mean, fixed and committed before it runs; joins `spec-ledger.md` on date and `Script:line` |
- | `screening-rubric.md` (v2.5.1) | Screening rubric — written before the screen runs, with per-candidate evidence, an adjudication table, and a dispatcher spot-check |
- </details>
- ---
- ## Prerequisites
- | Tool | Required For | Install |
- |------|-------------|---------|
- | [Claude Code](https://code.claude.com/docs/en/overview) **2.1.314+** | Everything. The shipped settings need 2.1.295 (`onFailure`) and 2.1.314 (the write boundary); an older version skips them without a warning | [claude.ai/install](https://claude.ai/install) |
- | git | Clone + version control | [git-scm.com](https://git-scm.com/downloads) |
- | Python 3 (3.9+), runnable as `python3` | The hooks and the gate scripts. Without a working `python3` the hooks do not run, and `gh` commands are refused, because `issue-guard` is registered to fail closed ([#179](https://github.com/pedrohcgs/claude-code-my-workflow/issues/179) for Windows) | Preinstalled on macOS/Linux; [python.org](https://www.python.org/) for Windows |
- | XeLaTeX | LaTeX compilation (Beamer `HelloWorld`, real lectures) | [TeX Live](https://tug.org/texlive/) or [MacTeX](https://tug.org/mactex/) |
- | [Quarto](https://quarto.org) | Web slides (Quarto `HelloWorld`, real lectures) | [quarto.org/docs/get-started](https://quarto.org/docs/get-started/) |
- | R | Figures and analysis (`/data-analysis`, `scripts/R/` template) | [r-project.org](https://www.r-project.org/) |
- | pdf2svg | TikZ → SVG for Quarto (`/extract-tikz`) | `brew install pdf2svg` (macOS), `apt install pdf2svg` (Debian) |
- | [gh CLI](https://cli.github.com/) | PR / issue workflow | `brew install gh` (macOS), `apt install gh` (Debian) |
- | poppler (optional) | Beamer page screenshots, page-to-frame map and log digest (`scripts/beamer-qa.py`, run by `/visual-audit`) | `brew install poppler` (macOS), `apt install poppler-utils` (Debian) |
- | Playwright for Python (optional) | Browser-measured slide QA (`scripts/slide-qa.py`, run by `/visual-audit`, `/qa-quarto`, `/slide-excellence`); drives your installed Chrome | `python3 -m venv ~/.venvs/slide-qa && ~/.venvs/slide-qa/bin/pip install playwright`, then `export SLIDE_QA_PYTHON=~/.venvs/slide-qa/bin/python` |
- **Minimum to fork this template:** Claude Code + git + Python 3 (Python is already installed on macOS/Linux).
- **Minimum to run the included HelloWorld demos end-to-end:** add XeLaTeX (for `/compile-latex HelloWorld`) and Quarto (for `/deploy HelloWorld`).
- **Your real lectures may need more** — R for `scripts/R/` analyses, pdf2svg if you use TikZ extraction, gh CLI if you use the PR-based commit workflow, Playwright if you want slide overflow measured in a browser. `./scripts/validate-setup.sh` reports whether R, the gh CLI and Playwright are installed; it does not check pdf2svg (`command -v pdf2svg` does).
- ---
- ## Adapting for Your Field
- 1. **Fill in the knowledge base** (`.claude/rules/knowledge-base-template.md`) with your notation, applications, and design principles
- 2. **Customize the domain reviewer** (`.claude/agents/domain-reviewer.md`) with review lenses specific to your field
- 3. **Update the color palette** — this is a **two-surface contract**: change the HEX values at the top of **both** [`Preambles/header.tex`](Preambles/header.tex) (Beamer/TikZ) **and** [`Quarto/theme-template.scss`](Quarto/theme-template.scss) (Quarto slides) so they agree. Then run `./scripts/check-palette-sync.sh` to verify. Forgetting one surface silently produces mismatched Beamer vs. Quarto renderings. See [`Preambles/README.md`](Preambles/README.md) for the full contract and the TikZ style library.
- 4. **Add field-specific R pitfalls** to `.claude/rules/r-code-conventions.md`
- 5. **Fill in the lecture mapping** in `.claude/rules/beamer-quarto-sync.md`
- 6. **Customize the workflow quick reference** (`.claude/WORKFLOW_QUICK_REF.md`) with your non-negotiables and preferences
- 7. **Set up the exploration folder** (`explorations/`) for experimental work
- ---
- ## Additional Resources
- - [Claude Code Documentation](https://code.claude.com/docs/en/overview)
- - [Writing a Good CLAUDE.md](https://code.claude.com/docs/en/memory) — official guidance on project memory
- ---
- ## Origin
- This infrastructure was extracted from **Econ 730: Causal Panel Data** at Emory University, developed by Pedro Sant'Anna using Claude Code over 6+ sessions. The course produced 6 complete PhD lecture decks with 800+ slides, interactive Quarto versions with plotly charts, and full R replication packages — all managed through this multi-agent workflow. The patterns are domain-agnostic: the same agents, rules, and orchestrator work for any academic project.
- ---
- ## Community & Extensions
- Research groups across economics, energy, political science, and engineering have forked and adapted this workflow — **15+ research groups at the March 2026 survey**; the repository has since passed **3,145 forks** and 1,680 stars (GitHub, 2026-11-04 — a fork is not a research group, so read the survey figure and the fork count as different things). The infrastructure (orchestrator, hooks, quality gates) transfers without modification.
- **Extended workflows:**
- - **[clo-author](https://github.com/hugosantanna/clo-author)** by Hugo Sant'Anna (UAB) — Paper-centric research workflows (release 26.09) with 25 specialized agents and 18 skills (adversarial worker-critic pairs plus referees, data-engineer, verifier), script-enforced submission gates, `/coherence` internal-consistency audit, `/explain` author comprehension gate, simulated blind peer review, and AEA replication compliance. **The `/review-paper --peer <journal>` pipeline in this template is adapted from clo-author with Hugo's permission** (pipeline shape, 6-way disposition taxonomy, journal-calibration schema, paper-type branching). Thanks, Hugo.
- - **[claudeblattman](https://github.com/chrisblattman/claudeblattman)** by Chris Blattman (U Chicago) — Comprehensive guide for non-technical academics: executive assistant workflows, proposal writing, parallel critics with a separate synthesis, and self-improving configuration
- - **[MixtapeTools](https://github.com/scunning1975/MixtapeTools)** by Scott Cunningham (Baylor) — The Rhetoric of Decks, Referee 2 (a five-audit replication protocol whose audits include an R ↔ Stata ↔ Python cross-language replication), and Blindspot (a "peripheral vision" audit of empirical output)
- - **[Paul Goldsmith-Pinkham's research tools](https://github.com/paulgp)** (Yale) — [`claude-container`](https://github.com/paulgp/claude-container) (sandboxed Docker execution), [`exhibit-review`](https://github.com/paulgp/exhibit-review) (spatial table/figure review), and [`margin`](https://github.com/paulgp/margin) (source-first writing review)
- - **[posit-dev/skills](https://github.com/posit-dev/skills)** by Posit (MIT) — Skills for R packages, Quarto and accessibility, including `alt-text` for figure alt text in Quarto documents
- - **[awesome-ai-for-economists](https://github.com/hanlulong/awesome-ai-for-economists)** by Lu Han (Bank of Canada) — Curated directory of AI workflows, MCP servers (`mcp-for-stata`, FRED, World Bank, Census), and replication tools for economists
- - **[autoresearch](https://github.com/karpathy/autoresearch)** by Andrej Karpathy — Constraint-based autonomous research with `program.md` as constitutional document
- - **[Claude-Code-Presentation](https://github.com/aspi6246/Claude-Code-Presentation)** (formerly `ClaudeCodeTools`) by Alessandro Spina (UTS) — "The Editor" persona: seven-audit sequential paper review protocol
- See the [guide's ecosystem section](https://psantanna.com/claude-code-my-workflow/workflow-guide.html#sec-ecosystem) for detailed descriptions, design principles, and more resources.
- ---
- ## Versioning & Contributing
- - **What's new:** see [CHANGELOG.md](CHANGELOG.md). We follow loose semver — breaking changes get major bumps so you can decide when to pull updates.
- - **How to contribute:** see [.github/CONTRIBUTING.md](.github/CONTRIBUTING.md). Pull requests are open to collaborators only — propose a generalizable improvement in an issue; fork-specific work stays in your fork.
- - **Pin to a version:** `git checkout $(git describe --tags --abbrev=0)` pins the newest release tag; [CHANGELOG.md](CHANGELOG.md) says what each one contains.
- ---
- ## License
- MIT License. See [LICENSE](LICENSE).
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.