PaperSpine

English | 中文

The English and Chinese READMEs are maintained as content-equivalent versions. If one document changes, update the other in the same commit.

PaperSpine is a motivation-driven paper and report writing skill suite for Codex, Claude Code, and OpenClaw.

It is designed for writing tasks where the target format matters: journal papers, conference papers, course or technical reports, reviews, and competition papers. The workflow asks the agent to learn the target scene and strong examples before writing, then records why each manuscript unit is planned or changed.

Repository Layout

PaperSpine/
  dist/
    codex/
      skills/                   # Codex flat skill suite
      paper-spine/              # legacy Codex bundled fallback
    claude/
      skills/                   # Claude Code flat skill suite
        paper-spine/
        paper-spine-ui/
        paper-spine-intake/
        paper-spine-research/
        paper-spine-citation/
        paper-spine-rewrite/
        paper-spine-build/
        paper-spine-latex/
        paper-spine-audit/
        paper-spine-translate/
        paper-spine-update/
      commands/                 # Claude Code slash-command helpers
        paperspine.md
        paper-spine.md
        paperspine-legacy.md
    openclaw/
      skills/                   # OpenClaw flat skill suite
  src/
    scripts/                    # shared deterministic helpers
    references/                 # shared workflow references
    agents/                     # shared agent metadata source
  .claude-plugin/               # Claude Code plugin metadata
  install.ps1                   # Windows installer
  install.sh                    # macOS / Linux installer
  README.md
  README.zh-CN.md

The dist/ directory is the installable output. The src/ directory keeps shared scripts and references readable for development.

Quick Install

On Windows PowerShell:

git clone https://github.com/WUBING2023/PaperSpine.git
cd PaperSpine
.\install.ps1 -Target all

Use a narrower target when needed:

.\install.ps1 -Target codex
.\install.ps1 -Target claude
.\install.ps1 -Target openclaw
.\install.ps1 -Target all -CleanLegacy

-CleanLegacy removes common old PaperSpine folders that caused duplicate discovery, such as nested PaperSpine, PaperSpineV2, and old paper-spine-* copies.

After installing for Codex: Restart Codex. Then call the full workflow with $paper-spine, or call a branch such as $paper-spine-research, $paper-spine-citation, or $paper-spine-latex.

After installing for Claude Code: restart or reload Claude Code, then use /paperspine.

After installing for OpenClaw: restart or reload OpenClaw, then invoke paper-spine for the full workflow or any paper-spine-* branch skill for a single stage.

The installer writes the installed version to ~/.paperspine/install_state.json and preserves ~/.paperspine/config.json, including UI language preferences.

Manual Install

Codex now uses the same flat suite idea so each branch can be called directly:

dist/codex/skills/*

Copy the folders to:

~/.codex/skills/

The final Codex layout should be:

~/.codex/skills/paper-spine/SKILL.md
~/.codex/skills/paper-spine-research/SKILL.md
~/.codex/skills/paper-spine-citation/SKILL.md
~/.codex/skills/paper-spine-latex/SKILL.md
~/.codex/skills/paper-spine-update/SKILL.md

dist/codex/paper-spine remains as a legacy bundled fallback for old installs, but the recommended Codex install is dist/codex/skills/*.

Claude Code expects flat skill folders plus optional slash commands:

dist/claude/skills/*
dist/claude/commands/*.md

Copy them to:

~/.claude/skills/
~/.claude/commands/

The final Claude Code layout should include:

~/.claude/skills/paper-spine/SKILL.md
~/.claude/skills/paper-spine-ui/SKILL.md
~/.claude/skills/paper-spine-intake/SKILL.md
~/.claude/skills/paper-spine-research/SKILL.md
~/.claude/skills/paper-spine-citation/SKILL.md
~/.claude/skills/paper-spine-update/SKILL.md
~/.claude/commands/paperspine.md

OpenClaw expects skill folders with SKILL.md:

dist/openclaw/skills/*

Copy them to:

~/.openclaw/skills/

The final OpenClaw layout should include:

~/.openclaw/skills/paper-spine/SKILL.md
~/.openclaw/skills/paper-spine-research/SKILL.md
~/.openclaw/skills/paper-spine-citation/SKILL.md
~/.openclaw/skills/paper-spine-update/SKILL.md

Claude Code Plugin Install

Claude Code can also use the plugin metadata in .claude-plugin.

/plugin marketplace add https://github.com/WUBING2023/PaperSpine
/plugin install paper-spine
/reload-plugins

The plugin manifest points to the flat suite under dist/claude/skills, not to the Codex distribution.

Codex vs Claude Code vs OpenClaw

Host	Installable unit	Typical entry	Reason
Codex	`dist/codex/skills/*`	`$paper-spine` or `$paper-spine-*`	Codex can discover flat skill folders, so the full workflow and branch skills are both callable.
Claude Code	`dist/claude/skills/` plus `dist/claude/commands/`	`/paperspine`	Claude Code discovers skills as flat folders and supports slash-command helpers.
OpenClaw	`dist/openclaw/skills/*`	`paper-spine` or `paper-spine-*`	OpenClaw skills are directories containing `SKILL.md`, so the same flat suite is used.

Do not copy the whole repository into a skills folder. That is the main cause of duplicated or missing skills.

Main Workflow

PaperSpine has two equal first-class workflows:

Rewrite Existing: improve an existing manuscript without treating the task as simple polishing.
Build From Materials: build a manuscript or report from a folder containing notes, figures, PDFs, data summaries, partial drafts, and experiment descriptions.

Supported target scenes:

journal: journal paper
conference: conference paper
report/review: course report, technical report, or review
competition: competition paper or competition report

Research tiers:

flash: 3 target-scene examples, 3 recent/high-quality same-field papers, and official requirements.
pro: 6 target-scene examples, 6 recent/high-quality same-field papers, and official requirements.

Output languages:

English
Chinese

When English output is selected, PaperSpine can also generate a translation_package containing Chinese translations of intermediate artifacts and final Markdown outputs.

Orchestrator And Branch Skills

PaperSpine is organized as one main orchestrator plus branch skills. The main paper-spine skill routes the work stage by stage instead of directly patching prose:

paper-spine-ui: opens the external terminal configuration UI.
paper-spine-intake: validates paper_spine_config.json.
paper-spine-research: learns the target scene, local/reference materials, and strong examples.
paper-spine-citation: builds a claim-level citation support bank.
paper-spine-rewrite or paper-spine-build: rewrites an existing manuscript or builds from materials.
paper-spine-latex: produces and checks LaTeX, PDF when possible, and optional Word output.
paper-spine-audit: checks completeness, rationale depth, citation bank quality, translation coverage, and artifact health.
paper-spine-translate: produces the complete translation_zh/ package with row-by-row translation.
paper-spine-update: checks GitHub main for the latest PaperSpine version and updates local installs while preserving global config.

The same research, citation, rationale-matrix, LaTeX, translation, and audit logic is shared by both rewrite_existing and build_from_materials.

Users can run the full workflow through paper-spine, or call only one branch:

paper-spine-ui: configure a run.
paper-spine-intake: validate or repair config.
paper-spine-research: research target requirements and exemplar structure.
paper-spine-citation: build the citation support bank only.
paper-spine-rewrite: rewrite an existing manuscript using existing upstream artifacts.
paper-spine-build: build from materials using existing upstream artifacts.
paper-spine-latex: assemble/check LaTeX, PDF, and optional Word output.
paper-spine-translate: produce the translation_zh/ package.
paper-spine-audit: audit artifacts, translation coverage, and rationale depth.
paper-spine-update: check or update the local PaperSpine installation.

Updating PaperSpine

After the first install, use the update branch skill when you want to check for new versions:

$paper-spine-update

The update skill runs:

python scripts/paperspine_update.py --yes

It compares the local version recorded in ~/.paperspine/install_state.json with the GitHub main manifest at dist/paperspine_version.json. If the local copy is already current, it reports that no update is needed. If an update is available, it downloads the GitHub archive, validates the PaperSpine layout, updates Codex, Claude Code, and OpenClaw skill folders, and keeps ~/.paperspine/config.json intact.

For a non-mutating check:

python scripts/paperspine_update.py --check-only

Local Reference Reading

Reference collection is no longer network-only. The config field reference_mode controls how PaperSpine starts literature and example reading:

local_first: default. Index reference materials from the current working folder first, then supplement from the web when needed.
specified_paths: index only the folders/files listed in reference_paths, then supplement according to the task.
web: use web collection when the user has no local reference materials.

Local reference paths are written into:

paper_rewriting_output/reference_materials/source_index.md

The helper script is:

python src/scripts/reference_inventory.py . --output-dir paper_rewriting_output --mode local_first

PaperSpine may read user-provided PDFs, downloaded papers, BibTeX/RIS files, templates, notes, and school or competition documents. It must not bypass paywalls or private database access.

Citation Support Bank

paper-spine-citation creates:

paper_rewriting_output/citation_support_bank.md

This is separate from exemplar learning. Exemplar papers teach structure and rhetoric; the citation support bank supplies candidate papers for Introduction, Related Work, Discussion, limitations, applications, and background claims.

Default behavior:

citation_target_count: 20
candidate pool: citation_target_count * 3, so the default is 60
recent-paper target: about 80% of candidates should be from the last three years; in 2026 the simple threshold is 2023 or later
each candidate row must include a reference/BibTeX-style entry, year, source, and one or two support sentences that can justify a manuscript statement

Check the bank with:

python src/scripts/citation_bank_check.py paper_rewriting_output/citation_support_bank.md --target-count 20 --markdown

Intake UI

Claude Code can launch the PaperSpine intake flow through:

/paperspine

The command should launch the PaperSpine intake UI automatically when the host terminal allows it. The fallback is the Python wizard:

python src/scripts/intake_wizard.py

The intake writes:

paper_rewriting_output/paper_spine_config.json
paper_rewriting_output/paper_spine_config.md

Required Artifacts

A complete PaperSpine run should produce a transparent audit trail, not just a final manuscript:

paper_rewriting_output/
  paper_spine_config.json
  paper_spine_config.md
  reference_materials/
    source_index.md
  research_dossier.md
  exemplar_learning_dossier.md
  style_profile.md
  sota_gap_map.md
  motivation_options_after_research.md
  citation_support_bank.md
  confirmed_motivation.md
  source_inventory.md
  evidence_bank.md
  figure_asset_map.md
  claim_register.md
  section_blueprints.md
  writing_rationale_matrix.md
  rewrite_matrix.md
  logic_transfer_audit.md
  latex_report.md
  final_artifact_manifest.md
  final_paper/
    main.tex
    references.bib
    figures/
    paper.docx              # optional Word output
    paper.pdf               # generated when a LaTeX compiler is available
  translation_package/       # optional for English output

The central artifact is writing_rationale_matrix.md. It must explain the writing plan unit by unit: what the unit does, how it serves the confirmed motivation, what was learned from SOTA or target-scene examples, which evidence supports it, and what final text check should pass.

citation_support_bank.md is the second major reasoning artifact. It makes every optional citation traceable to a concrete sentence-level claim before the agent selects final references for the manuscript.

Quality Checks

Run the artifact checker:

python src/scripts/artifact_check.py paper_rewriting_output --markdown --write

For compatibility with copied skill scripts, the same command may appear in skill instructions as:

python scripts/artifact_check.py paper_rewriting_output --markdown --write

Check LaTeX:

python src/scripts/latex_guard.py paper_rewriting_output/final_paper/main.tex --markdown

Check Word output:

python src/scripts/word_guard.py paper_rewriting_output/final_paper/paper.docx --markdown

Check local reference indexing:

python src/scripts/reference_inventory.py . --output-dir paper_rewriting_output --mode local_first

Check citation candidate coverage:

python src/scripts/citation_bank_check.py paper_rewriting_output/citation_support_bank.md --target-count 20 --markdown

Run repository tests:

python -m unittest discover -s tests

What PaperSpine Tries To Prevent

Direct sentence-by-sentence polishing with no logic change.
Treating target journals, competitions, reports, and reviews as the same genre.
Writing before confirming the motivation.
Adding claims that are not supported by evidence.
Producing only main.tex without explaining why the paper was written that way.
Partial translation packages when the user requested translated intermediate and final artifacts.

License

MIT License. See LICENSE.