307 lines
6.3 KiB
Markdown
307 lines
6.3 KiB
Markdown
# scholarly-writing-workbench
|
|
|
|
This directory is intended to be a reusable workbench for paper writing and literature review workflows.
|
|
|
|
The goal is not to store every raw reference asset in Git. The goal is to version:
|
|
|
|
- reusable prompt templates
|
|
- Codex multi-agent setup notes
|
|
- the working Word draft
|
|
- small workflow documents, checklists, and mapping tables
|
|
|
|
Large local reference corpora should stay outside normal Git tracking by default, including:
|
|
|
|
- `paper/`
|
|
- the localized reference folder
|
|
- `root/`
|
|
|
|
Those directories are already ignored in [`.gitignore`](./.gitignore). If you later decide to version part of them, prefer a small curated subset or Git LFS instead of pushing a full local corpus.
|
|
|
|
---
|
|
|
|
## 1. What this repository should contain
|
|
|
|
Recommended for version control:
|
|
|
|
- `README.md`
|
|
- `multi-agent-review-workflow-template.md`
|
|
- `codex-multi-agent-setup-notes.md`
|
|
- `review-outline.md`
|
|
- `pending-calibration-tasks.md`
|
|
- `macrolide-review-draft.docx`
|
|
- small task lists, mapping tables, and workflow notes
|
|
|
|
Not recommended for normal Git tracking:
|
|
|
|
- full PDF corpora
|
|
- full Zotero `storage/`
|
|
- large GitHub source snapshots
|
|
- large Docling parse outputs
|
|
- large QMD index databases
|
|
|
|
---
|
|
|
|
## 2. Required skills
|
|
|
|
This workflow depends on these `Deep-Research-skills` skills:
|
|
|
|
- `research`
|
|
- `research-add-fields`
|
|
- `research-add-items`
|
|
- `research-deep`
|
|
- `research-report`
|
|
|
|
Useful supporting skills:
|
|
|
|
- `skill-installer`
|
|
- `skill-creator`
|
|
|
|
On a fresh machine, confirm they are installed under:
|
|
|
|
- Windows:
|
|
- `C:\Users\<user>\.codex\skills`
|
|
- macOS:
|
|
- `/Users/<user>/.codex/skills`
|
|
- Linux:
|
|
- `/home/<user>/.codex/skills`
|
|
|
|
---
|
|
|
|
## 3. Required MCP servers
|
|
|
|
Core MCP servers:
|
|
|
|
- `word-mcp`
|
|
- edits `.docx`
|
|
- `zotero`
|
|
- manages items, PDFs, and citations
|
|
- `docling`
|
|
- parses PDFs
|
|
- `qmd`
|
|
- performs local hybrid retrieval
|
|
|
|
Strongly recommended:
|
|
|
|
- `chrome-devtools`
|
|
- opens paper pages and GitHub pages for manual downloading
|
|
|
|
---
|
|
|
|
## 4. MCP installation notes
|
|
|
|
### 4.1 `word-mcp`
|
|
|
|
Recommended approach: clone locally and run with `pixi`.
|
|
|
|
Example:
|
|
|
|
```powershell
|
|
codex mcp add word-mcp -- pixi run --manifest-path C:/path/to/word-mcp start
|
|
```
|
|
|
|
### 4.2 `zotero`
|
|
|
|
Recommended approach: clone locally, run with `pixi`, and configure:
|
|
|
|
- `ZOTERO_API_KEY`
|
|
- `ZOTERO_USER_ID`
|
|
- `UNPAYWALL_EMAIL`
|
|
|
|
Example:
|
|
|
|
```powershell
|
|
codex mcp add zotero `
|
|
--env ZOTERO_API_KEY=YOUR_KEY `
|
|
--env ZOTERO_USER_ID=YOUR_USER_ID `
|
|
--env UNPAYWALL_EMAIL=YOUR_EMAIL `
|
|
-- pixi run --manifest-path C:/path/to/mcp-zotero start
|
|
```
|
|
|
|
### 4.3 `docling`
|
|
|
|
Recommended approach: clone locally and run with `uv`.
|
|
|
|
Example:
|
|
|
|
```powershell
|
|
codex mcp add docling -- uv run --directory C:/path/to/docling-mcp docling-mcp-server --transport stdio
|
|
```
|
|
|
|
### 4.4 `qmd`
|
|
|
|
Recommended requirements:
|
|
|
|
- Node.js >= 22
|
|
- either a stable local build or a verified global installation
|
|
|
|
Example:
|
|
|
|
```powershell
|
|
codex mcp add qmd -- node C:/path/to/qmd/dist/qmd.js mcp
|
|
```
|
|
|
|
### 4.5 `chrome-devtools`
|
|
|
|
Windows example:
|
|
|
|
```powershell
|
|
codex mcp add chrome-devtools -- npx chrome-devtools-mcp@latest
|
|
```
|
|
|
|
On Windows 11, you may also need `SystemRoot`, `PROGRAMFILES`, and a larger `startup_timeout_ms` in `~/.codex/config.toml`.
|
|
|
|
macOS and Linux usually do not need the Windows-specific environment block.
|
|
|
|
---
|
|
|
|
## 5. Codex multi-agent requirements
|
|
|
|
At minimum, `~/.codex/config.toml` should contain:
|
|
|
|
```toml
|
|
[features]
|
|
multi_agent = true
|
|
```
|
|
|
|
Recommended additions:
|
|
|
|
```toml
|
|
[agents]
|
|
max_threads = 6
|
|
max_depth = 1
|
|
```
|
|
|
|
Recommended agents for this workflow:
|
|
|
|
- `deep_researcher`
|
|
- `zotero_locator`
|
|
- `qmd_retriever`
|
|
- `github_mapper`
|
|
- `writer`
|
|
- `citation_checker`
|
|
- `citation_archivist`
|
|
- `web_researcher`
|
|
|
|
See:
|
|
|
|
- [`codex-multi-agent-setup-notes.md`](./codex-multi-agent-setup-notes.md)
|
|
|
|
---
|
|
|
|
## 6. Recommended dynamic variables
|
|
|
|
To keep this workflow portable across Windows, macOS, and Linux, maintain key paths as variables instead of hard-coding them everywhere.
|
|
|
|
Recommended variables:
|
|
|
|
- `REVIEW_TITLE`
|
|
- `WORK_ROOT`
|
|
- `WORD_TARGET_DOC`
|
|
- `REVIEW_OUTLINE_FILE`
|
|
- `ANALYSIS_DIR`
|
|
- `ZOTERO_ROOT`
|
|
- `ZOTERO_STORAGE_DIR`
|
|
- `PAPER_GITHUB_MAP_CSV`
|
|
- `RAG_ROOT`
|
|
- `RAG_PARSED_MD_DIR`
|
|
- `GITHUB_SOURCE_DIR`
|
|
- `GITHUB_MD_DIR`
|
|
- `CITATION_EVIDENCE_DIR`
|
|
|
|
See:
|
|
|
|
- [`multi-agent-review-workflow-template.md`](./multi-agent-review-workflow-template.md)
|
|
|
|
---
|
|
|
|
## 7. Core workflow
|
|
|
|
Recommended execution order:
|
|
|
|
1. `Deep-Research-skills`
|
|
- identify missing papers, missing GitHub projects, and missing evidence
|
|
2. `zotero`
|
|
- check whether items and PDFs already exist
|
|
3. `chrome-devtools`
|
|
- open download pages so the user can manually download PDFs, supplements, or GitHub assets
|
|
4. `docling`
|
|
- convert PDFs into structured text
|
|
5. `qmd`
|
|
- perform hybrid retrieval over parsed papers, GitHub docs, and notes
|
|
6. `word-mcp`
|
|
- revise the Word draft only after evidence is ready
|
|
7. `zotero`
|
|
- support citation insertion and citation review
|
|
|
|
---
|
|
|
|
## 8. Paper-to-GitHub mapping
|
|
|
|
Maintain both:
|
|
|
|
- Zotero source traces
|
|
- a local structured mapping table
|
|
|
|
Recommended mapping table:
|
|
|
|
- `paper_github_repo_map.csv`
|
|
|
|
Rules:
|
|
|
|
- one paper to multiple repositories: one row per mapping
|
|
- one repository to multiple papers: one row per mapping
|
|
- QMD is the primary retrieval layer
|
|
- Zotero is the source-trace layer
|
|
|
|
---
|
|
|
|
## 9. Minimal checklist for a fresh machine
|
|
|
|
1. Install Codex CLI
|
|
2. Install and verify `Deep-Research-skills`
|
|
3. Install and verify:
|
|
- `word-mcp`
|
|
- `zotero`
|
|
- `docling`
|
|
- `qmd`
|
|
- `chrome-devtools`
|
|
4. Confirm `~/.codex/config.toml` enables:
|
|
- `multi_agent = true`
|
|
5. Confirm `~/.codex/agents/` contains the required agent configs
|
|
6. Confirm Zotero local data or Zotero Web API access is available
|
|
7. Confirm QMD collections, Docling output directories, and mapping files are configured
|
|
8. Confirm the Word draft and outline file paths are updated
|
|
|
|
---
|
|
|
|
## 10. Git initialization and push
|
|
|
|
Initialize locally:
|
|
|
|
```powershell
|
|
git init -b main
|
|
git add README.md .gitignore *.md *.docx
|
|
git commit -m "Initialize scholarly writing workbench"
|
|
```
|
|
|
|
After creating the remote repository in Gitea:
|
|
|
|
```powershell
|
|
git remote add origin <YOUR_GITEA_REPO_URL>
|
|
git push -u origin main
|
|
```
|
|
|
|
---
|
|
|
|
## 11. Recommended repository name
|
|
|
|
Preferred:
|
|
|
|
- `scholarly-writing-workbench`
|
|
|
|
Alternatives:
|
|
|
|
- `paper-review-agent-workbench`
|
|
- `scholarly-writing-agent-kit`
|
|
- `literature-review-agent-kit`
|