PaperSpine

PaperSpine: A Motivation-Driven Suite for High-Quality Paper and Report Writing

Introduction: A Workflow That Exposes Why, Not Just What PaperSpine is more than a collection of writing utilities. It is a motivation-driven skill suite designed to help coders, researchers, and writers craft journal papers, conference papers, technical reports, and competition submissions with a transparent reason-why behind every manuscript unit. The system emphasizes target formats and audience expectations, encouraging the user to learn the “scene” before drafting, then to rigorously record why each unit is planned or revised. In short, PaperSpine guides you from concept to publication while preserving a clear audit trail of motivation, evidence, and logical connections.

A Quick Orientation: What You Will Find in PaperSpine

• A dual-language, content-equivalent setup: English and Chinese READMEs that stay in lockstep across changes.
• A modular architecture with distinct solid components for Codex and Claude Code, plus shared workflow references and agents.
• A clear path from intake to final manuscript, with a strong emphasis on documentation of reasoning, evidence, and revisions.
• A two-pronged workflow model: rewrite existing manuscripts or build new ones from a pile of materials such as notes, figures, PDFs, data summaries, and partial drafts.
• A robust artifact system that produces more than a final PDF/tex: a transparent writing rationale, evidence banks, inventories, and revision audits.

Repository Overview: What the Structure Really Means PaperSpine is organized to separate installable outputs from development-friendly sources. The main folders you’ll encounter are:

• dist/ — The installable output for each host. This is where the ready-to-use skill bundles live.
• codex/ and claude/ — Host-specific directories carrying distributions and skill specifics for Codex and Claude Code.
• paper-spine/, paper-spine-intake/, paper-spine-research/, paper-spine-rewrite/ — Core skill areas focusing on intake, research, and rewrite activities.
• paper-spine-build/, paper-spine-latex/ — Tools for building documents and LaTeX integration.
• references/ — Shared references used across manuscripts and workflows.
• agents/ — Metadata describing shared agents that drive the workflow.
• .claude-plugin/ — Claude Code plugin metadata.
• scripts/, src/ — Shared deterministic helpers and scripts to support development and operation.
• README.md, README.zh-CN.md — Content-equivalent READMEs in English and Chinese.

A Snapshot of the Installable Output The dist/ directory is what you actually deploy and run. For Codex, you place a single self-contained skill folder such as dist/codex/paper-spine into your Codex skills path, forming the layout:

• SKILL.md
• references/
• scripts/ This keeps the orchestrator, supporting scripts, and references in one cohesive bundle.

For Claude Code, the approach is a flat skill suite rather than a single bundle. You copy the contents of dist/claude/skills/* and dist/claude/commands/* into:

• ~/.claude/skills/
• ~/.claude/commands/ The Claude Code layout then includes:
• paper-spine/SKILL.md
• paper-spine-intake/SKILL.md
• paper-spine-research/SKILL.md
• paperspine.md (a slash-command to kick things off)

This division reflects how Claude Code discovers and uses skills as flat folders and how it supports slash-command helpers.

A Quick Install Guide: Getting PaperSpine Running Two main installation tracks are provided to accommodate different toolchains:

• Windows (PowerShell, Codex or Claude Code)

• Full install:

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

• Narrower targets when you need them:

  • .\install.ps1 -Target codex
  • .\install.ps1 -Target claude
  • .\install.ps1 -Target all -CleanLegacy (this option clears old PaperSpine folders that caused duplicate discovery)

• After Codex installation: restart Codex, then call the skill with $paper-spine or select paper-spine from the skill list.

• After Claude Code installation: restart or reload Claude Code, then use /paperspine.

• Manual Install (Codex and Claude Code)

• Codex expects a self-contained skill folder at dist/codex/paper-spine for placement in your Codex skills directory:

  • Copy to ~/.codex/skills/paper-spine
  • Expected final structure:
  • SKILL.md
  • references/
  • scripts/

• Claude Code expects flat folders in dist/claude/skills/ and dist/claude/commands/.md:

  • Copy to ~/.claude/skills/ and ~/.claude/commands/

• Claude Code final layout should include:

  • ~/.claude/skills/paper-spine/SKILL.md
  • ~/.claude/skills/paper-spine-intake/SKILL.md
  • ~/.claude/skills/paper-spine-research/SKILL.md
  • ~/.claude/commands/paperspine.md

Claude Code Plugin Install: Extending Capabilities Claude Code can leverage additional plugin metadata via the .claude-plugin manifest. To enable the plugin:

• Run: /plugin marketplace add https://github.com/WUBING2023/PaperSpine
• Then: /plugin install paper-spine
• Finally: /reload-plugins The plugin manifest in this flow points to the flat suite under dist/claude/skills, not to the Codex distribution, making it easy to adapt to Claude Code’s discovery model.

Codex vs Claude Code: Tailoring to Your Host

• Codex
• Host: Codex
• Installable unit: dist/codex/paper-spine
• Typical entry: $paper-spine
• Rationale: Codex works best with one bundled skill that includes the orchestrator, scripts, and references in a single package.
• Claude Code
• Host: Claude Code
• Installable unit: dist/claude/skills/* plus dist/claude/commands/*
• Typical entry: /paperspine
• Rationale: Claude Code discovers skills as flat folders and supports slash-command helpers.

A Note on Packaging: Do Not Flatten the Repository Do not copy the entire repository into a single skills folder. Duplication or missing skills are common when the repository is flattened wholesale. The intended approach preserves modularity and ensures each host can locate and load the appropriate components correctly.

Main Workflows: Two Equal, First-Class Paths PaperSpine is built around two core workflows, both designed to produce publishable material while maintaining a transparent trail of decisions and supporting evidence.

1) Rewrite Existing

• Objective: Improve an existing manuscript by making substantial logical and structural changes, not merely polishing sentences.
• How it works: You analyze the current manuscript, identify gaps, and rewrite manuscript units with a rationale for every change.
• Outcome: A document that demonstrates improved alignment with target scene requirements and strengthened motivation-to-evidence linkage.

2) Build From Materials

• Objective: Construct a manuscript or report from a folder containing notes, figures, PDFs, data summaries, partial drafts, and experiments.
• How it works: PaperSpine assembles a manuscript by weaving together inputs that reflect the task’s objectives, then justifies each unit with a writing rationale and evidence map.
• Outcome: A fully formed manuscript that adheres to the target format and shows explicit tracing from source materials to final text.

Supported Target Scenes

• journAL: Journal papers with formal structures and rigorous standards.
• conference: Conference papers with concise emphasis and clear novelty.
• report/review: Course reports, technical reports, or literature reviews.
• competition: Competition papers or competition reports demanding specific criteria.

Research Tiers

• flash: A lighter load with 3 target-scene examples, 3 recent/high-quality same-field papers, and official requirements.
• pro: A more demanding tier with 6 target-scene examples, 6 recent/high-quality same-field papers, and official requirements.

Output Languages

• English
• Chinese
• Translation options: PaperSpine can generate a translation_package containing Chinese translations of intermediate artifacts and final Markdown outputs when English is selected as the primary output language.

Intake UI: Starting the PaperSpine Flow

• Primary command: /paperspine launches the intake flow from Claude Code.
• Automatic UI: The intake UI should open automatically if the host terminal allows it.
• Fallback: If automatic UI isn’t available, you can invoke the Python wizard:
• python src/scripts/intake_wizard.py
• Output from intake:
• paperrewritingoutput/paperspineconfig.json
• paperrewritingoutput/paperspineconfig.md
• Preview of the TUI:
• python src/scripts/tuipreviewserver.py --port 8765

Required Artifacts: Transparency Across the Process A complete PaperSpine run produces an auditable trail, not only a final manuscript. The artifacts include:

• paperrewritingoutput/
• paperspineconfig.json
• paperspineconfig.md
• downloaded_references/
• research_dossier.md
• motivation_candidates.md
• confirmed_motivation.md
• source_inventory.md
• evidence_bank.md
• figureassetmap.md
• claim_register.md
• section_blueprint.md
• writingrationalematrix.md
• rewrite_matrix.md
• revision_audit.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)

Central to this artifact set is the writingrationalematrix.md

• Purpose: It explains the writing plan unit by unit.
• Contents: For each unit, it describes what the unit does, how it serves the confirmed motivation, what was learned from state-of-the-art or target-scene examples, which evidence supports it, and the final text checks that must pass.
• Why it matters: This matrix anchors the manuscript in motivation, evidential backing, and verifiable criteria for success.

Quality Checks: Ensuring Rigor and Reproducibility PaperSpine includes tooling to verify and validate artifacts, aiming to prevent common writing pitfalls. The artifact checker suite runs as follows:

• Check artifacts: python src/scripts/artifactcheck.py paperrewriting_output --markdown --write
• Compatibility note: The same checker can appear in skill instructions as:
• python scripts/artifactcheck.py paperrewriting_output --markdown --write
• Verify LaTeX and Word outputs:
• LaTeX guard: python src/scripts/latexguard.py paperrewritingoutput/finalpaper/main.tex --markdown
• Word guard: python src/scripts/wordguard.py paperrewritingoutput/finalpaper/paper.docx --markdown
• Repository tests: python -m unittest discover -s tests

What PaperSpine Tries To Prevent

• Direct sentence-by-sentence polishing without changing underlying logic or motivation.
• Treating disparate target genres (journals, conferences, technical reports, reviews) as a single, uniform writing task.
• Writing before confirming the motivation and without a robust audit trail.
• Adding claims unsupported by evidence.
• Producing only a main.tex or final text without explaining the rationale behind design choices.
• Generating partial translation packages when translated artifacts are actually requested.

The Language, The License, and The Ethos

• PaperSpine is released under the MIT License. See the LICENSE file for details.

Why PaperSpine Is Valuable to Researchers and Writers

• Motivation-first design. Every unit’s purpose, evidence, and checks are explicit, reducing drift between intent and output.
• Structured workflows for both rewriting and building from materials, which helps accommodate a wide range of project types and disciplines.
• Clear separation of host-specific deployment details (Codex vs Claude Code) reduces friction and prevents skill duplication or loss of needed components.
• A comprehensive artifact system that makes it possible to audit the writing process, learn from strong examples, and demonstrate compliance with target-scene requirements.
• Strong support for multi-language output, including translation packages, making it feasible to produce bilingual manuscripts or abstracts.
• Built-in quality controls that help catch omissions, misalignments, or unsupported claims before publication.

A Final Word on the Editorial Journey PaperSpine invites you to reimagine how writing is done in technical and research contexts. Rather than a distant tool that merely refines text, PaperSpine acts as a partner in shaping the narrative by revealing the thread of motivation that binds every paragraph, figure, and claim. The emphasis on auditability, evidence curation, and explicit reasoning makes the manuscript process more transparent, more persuasive, and more defensible in the face of scrutiny from reviewers, editors, and peers.

If you are preparing for a journal submission, a conference paper, a technical report, or a competition entry, PaperSpine offers a disciplined framework to ensure that every decision is justified, every claim is supported, and every revision is traceable. Whether you choose to rewrite an existing manuscript or to assemble a new one from a curated set of materials, PaperSpine’s two-pronged workflows, artifact-centered approach, and cross-host compatibility deliver a robust path from concept to publication.