Scaffold a Research Project

Create a new research project from the research-project-template without leaving the chat. Designed for users on Cowork (no terminal) and for Claude Code users who prefer a guided setup.

Announce at start: "Using scaffold-research-project to set up <project_name> at <parent_directory>."

When to use

• User says "start a new research project", "scaffold a project on X", "create a new project", "set up a research project about Y"
• User on Cowork (no shell) or anyone who prefers a guided setup over cp -r and manual frontmatter editing
• First-time users who haven't seen the template structure yet

NOT for: modifying an existing project (edit CLAUDE.md directly), copying parts of the template in isolation (use the relevant skill — e.g. ingest-source will create the wiki structure on demand).

Checklist

Create a task-list item for each. Complete in order; do not write files until all inputs are collected and confirmed.

1. Ask for project name. Require kebab-case (lowercase, hyphens, no spaces). Reject MyProject or my project — request a slug like iron-age-chronology or negev-fortresses-debate. Validate against the regex ^[a-z][a-z0-9-]*$.
2. Ask for parent directory. Offer ~/Documents as default (expand via the Bash tool if available). If Bash is not available, ask the user to paste an absolute path. Verify the directory exists; if not, ask whether to create it.
3. Ask for methodology. Present the three options briefly:
   • hermeneutic — default. Theology, exegesis, source criticism, interpretive archaeology. No frozen hypothesis; the plan documents research question + method sketch + expected sources.
   • quantitative — geostatistics, 14C Bayesian, quantitative DH. Full pre-registration (hypothesis, operationalisation, stop criterion).
   • mixed — per-sub-study; quantitative tasks opt into pre-registration individually. If the user is unsure, recommend hermeneutic and note that they can change it later.
4. Ask for discipline. Free text. Offer examples: "Biblical Archaeology", "Theology / Old Testament", "Ancient History", "Digital Humanities". The string is used in the project's CLAUDE.md frontmatter.
5. Ask for languages. Default [en]. Offer [de, en] for German-speaking research. Other ISO 639-1 codes welcome.
6. Confirm the plan with the user. Present a single block:

   "I'll create <parent_directory>/<project_name>/ with methodology <methodology>, discipline <discipline>, languages <languages>. Proceed?" Wait for explicit confirmation. Do not write any files before confirmation.

7. Locate the template. Try, in order:
   1. Plugin cache: ~/.claude/plugins/cache/<marketplace>/research-superpowers/templates/research-project-template/. Use Bash ls to confirm if Bash is available; otherwise try common marketplace names (leiverkus-research, claude-plugins-community).
   2. User-supplied path: if the user has the plugin checked out as a development clone, ask for the path.
   3. Fallback: fetch each template file from GitHub raw URLs (https://raw.githubusercontent.com/leiverkus/research-superpowers/main/templates/research-project-template/...) via the WebFetch tool. Slower but works without any local clone.
8. Copy the template tree file-by-file using Read (from the located template path) and Write (to the new project path). Preserve directory structure exactly. Copy these top-level entries:
   • CLAUDE.md
   • README.md
   • .vscode/settings.json and .vscode/tasks.json
   • .gitignore
   • .gitlab-ci.yml
   • schema/knowledge-frontmatter.schema.json
   • scripts/library.py — resolves the shared source library. Without it nothing can find a PDF.
   • scripts/bib-subset.py — writes output/bibtex/references.bib as the cited subset of the library
   • scripts/bib-search.py — page-level full-text search across the library (SQLite FTS5; the index is a local cache, never in the synced folder)
   • scripts/check-pdf-version.py — flags manuscript-vs-published PDFs before ingest
   • scripts/add-to-library.py — adds one PDF directly to the shared master library (the add-to-library skill drives it)
   • scripts/lint-wiki.py
   • scripts/wiki-to-graph.py
   • scripts/graph_mcp.py — stdlib MCP server exposing the graph queries
   • scripts/vendor/cytoscape.min.js (+ scripts/vendor/README.md) — bundled offline lib for the HTML graph viz
   • .mcp.json — registers the wiki-graph MCP server for Claude Code
   • input/ (with its bibliography/, data/, description/, ideas/, notes/ subdirectories — the description/project-description.md template file goes too)
   • knowledge/ (plain Markdown wiki — _meta/, the four _example-*.md files in entities/, concepts/, sources/, synthesis/, plus an empty assets/ and _meta/log.md, _meta/index.md; no _quarto.yml or Makefile — the wiki has no build step)
   • output/ (bibtex/references.bib, bibtex/csl/, article/article.qmd, book/_quarto.yml and chapters, presentation/talk.qmd, plus their Makefiles; and the empty article/outline/ + book/outline/ dirs where drafting-manuscript keeps each manuscript's argument architecture — not rendered, never listed in _quarto.yml)

9. Patch CLAUDE.md frontmatter with the user's answers. Read the new CLAUDE.md, replace the placeholder frontmatter block at the top:

   ---
   methodology: <user-answer>
   discipline: "<user-answer>"
   languages: <user-answer>
   plugin_version: "<version from .claude-plugin/plugin.json>"
   ---

   Use the Edit tool with the original placeholder block as old_string.

   plugin_version is not a user answer — read it from $CLAUDE_PLUGIN_ROOT/.claude-plugin/plugin.json and copy the version string verbatim. It records which plugin version this project's copied schema/ and scripts/ came from, and it is what lets scripts/sync-project.py tell an old copy from a local patch later. Leaving it at 0.0.0 is not fatal — the project is then simply treated as behind — but it costs the user a false "local edit" warning on every file they never touched.

10. Point the project at the shared library. Source PDFs do not live in the project — they live in one shared folder (<library>/pdf/<bibkey>.pdf), so the same paper exists once across every project. Write its path into .research-library (one line, no trailing slash). Without this the project has no sources: ingest-source will hard-stop on the very first ingest.
    • If ~/.config/research-superpowers/library already exists, offer its contents as the default — most users have one library for everything.
    • Otherwise ask: "Where is your shared source library? (e.g. ~/UOLcloud/Bibliothek). Leave blank to set it later."
    • The file is gitignored — the path is machine-local and differs between machines, so committing it would break every other checkout.
11. Optionally init git. If the Bash tool is available, ask: "Initialise a git repository here? (recommended; lets you track changes and roll back.)" If yes, run:

    cd <parent_directory>/<project_name>
    git init -b main
    git add .
    git commit -m "Scaffold research project from research-superpowers template"

    If Bash is not available or the user declines, skip — note that git can be initialised later.
12. Register the project and audit its join keys. Append the new project's absolute path to ~/.config/research-superpowers/projects (one path per line; create the file if missing — the session-start drift check also auto-registers, but only once a session starts in the project). If the registry now lists ≥ 2 projects, run python scripts/wiki-global-graph.py bibkeys <all registry roots> — a new project is exactly when its own doc says to run the audit, because no single project's CI can see a cross-project COLLISION or SPLIT.
13. Confirm completion. Tell the user:

    "Project created at <parent_directory>/<project_name>/. Next steps:

    • Open CLAUDE.md to see the project's conventions
    • Point the project at the shared library (one line in .research-library), then say 'ingest <bibkey>' to populate the wiki
    • For the full walkthrough, see the plugin's docs/tutorial.md"

Process Flow

digraph scaffold {
    "Ask project name" [shape=box];
    "Valid kebab-case?" [shape=diamond];
    "Ask parent directory" [shape=box];
    "Ask methodology" [shape=box];
    "Ask discipline" [shape=box];
    "Ask languages" [shape=box];
    "Confirm plan" [shape=box];
    "User confirms?" [shape=diamond];
    "Locate template" [shape=box];
    "Template found?" [shape=diamond];
    "Fallback to WebFetch" [shape=box];
    "Copy files via Read+Write" [shape=box];
    "Patch CLAUDE.md frontmatter" [shape=box];
    "Bash available?" [shape=diamond];
    "Offer git init" [shape=box];
    "User wants git?" [shape=diamond];
    "git init + commit" [shape=box];
    "Confirm + next steps" [shape=doublecircle];

    "Ask project name" -> "Valid kebab-case?";
    "Valid kebab-case?" -> "Ask project name" [label="no, retry"];
    "Valid kebab-case?" -> "Ask parent directory" [label="yes"];
    "Ask parent directory" -> "Ask methodology";
    "Ask methodology" -> "Ask discipline";
    "Ask discipline" -> "Ask languages";
    "Ask languages" -> "Confirm plan";
    "Confirm plan" -> "User confirms?";
    "User confirms?" -> "Ask project name" [label="no, restart"];
    "User confirms?" -> "Locate template" [label="yes"];
    "Locate template" -> "Template found?";
    "Template found?" -> "Fallback to WebFetch" [label="no"];
    "Fallback to WebFetch" -> "Copy files via Read+Write";
    "Template found?" -> "Copy files via Read+Write" [label="yes"];
    "Copy files via Read+Write" -> "Patch CLAUDE.md frontmatter";
    "Patch CLAUDE.md frontmatter" -> "Bash available?";
    "Bash available?" -> "Offer git init" [label="yes"];
    "Bash available?" -> "Confirm + next steps" [label="no"];
    "Offer git init" -> "User wants git?";
    "User wants git?" -> "git init + commit" [label="yes"];
    "User wants git?" -> "Confirm + next steps" [label="no"];
    "git init + commit" -> "Confirm + next steps";
}

Red Flags

Key Principles

• Ask everything first, then write — atomic-feeling. The user types answers, sees the plan, confirms once, then files appear.
• No bash in the core path — only optional git init uses Bash. The scaffold itself works in any tool environment.
• Template lookup is graceful — plugin cache → user clone → GitHub fetch. Don't fail because the cache path varies.
• Frontmatter is patched, not regenerated — preserves the rest of the template's CLAUDE.md (architecture docs, workflow conventions).
• Git is optional — recommend it, never require it. A research project without git still works.
• One project per invocation — never batch.