cs-paper-harness

Language: English | 中文

cs-paper-harness is an evidence-bound, agent-first harness for Computer Science graduate paper workflows in Codex and Claude Code.

The project is not a paper-writing bot, a LaTeX formatter, or a prompt collection. It gives the agent a protocol for preserving context, evidence boundaries, direct-edit recovery, and handoff state while the student works toward a credible paper.md draft.

Install

Install the runtime:

pipx install cs-paper-harness==1.0.0
cph --help

Configure a paper workspace, global agent surfaces, or both:

cph-install --scope project --agent codex --project /path/to/paper-workspace
cph-install --scope global --agent all
cph-install --scope both --agent all --project /path/to/paper-workspace

project scope writes only workspace-local guidance and .cs-paper/ private state setup. global scope installs Codex and Claude Code skill surfaces into normal user discovery paths. both performs both actions explicitly.

Student Path

Start here if you want to use CPH for a paper:

• Install CPH
• First Paper From Zero
• Continue An Existing Paper
• Bring Experiment Artifacts
• Direct Paper Edit Recovery
• Privacy And Local State
• Use CPH In Codex
• Use CPH In Claude Code
• Troubleshooting

AI-readable project assets are available at llms.txt, llms-full.txt, and docs/project-knowledge.md.

Core Idea

Models should think, discuss, analyze, and write. The harness should preserve state, evidence, gates, and handoff.

In plain terms:

• The model is the runner.
• The agent is the running interface and tool surface.
• CPH is the guardrail, checkpoint, and relay protocol.

CPH does not replace the agent interface. A student still works inside Claude Code or Codex. CPH constrains the process so the agent does not skip evidence, forget decisions after context compaction, or write claims stronger than the available artifacts.

V1 Outcome

V1 starts when a student says something like:

• I want to do research about X.
• I want to write a CS paper, but I am not sure about the direction.
• I already have an idea, experiment folder, or partial draft.

V1 ends with:

• paper.md
• references.bib
• references.md

V1 does not include formatting, LaTeX, Word, submission packaging, automatic experiment execution, or a full venue database.

Workflow

1. Initialization
2. Direction confirmation
3. Idea planning
4. Experiment artifact analysis
5. Evidence-core writing
6. Storyline planning
7. Introduction draft and framing audit
8. Discussion and limitations
9. Related Work and citation pass
10. Conclusion
11. Assembly, polish, and final audit

The writing order is evidence-first. For most empirical CS papers, method/system and experiments/findings should be written before Introduction, because Introduction is where unsupported over-framing is most likely to appear.

Runtime Boundary

The cph runtime exposes only deterministic protocol operations:

• cph init
• cph doctor
• cph manifest
• cph assemble
• cph handoff

The runtime does not judge research novelty, paper quality, evidence support, final audit quality, or whether to keep, discard, or defer direct paper.md edits. Those decisions stay with the student and the agent workflow.

Local Verification

From the repository root:

env UV_CACHE_DIR=/tmp/uv-cache uv lock --offline
env UV_CACHE_DIR=/tmp/uv-cache uv run cph --help
env UV_CACHE_DIR=/tmp/uv-cache uv run cph doctor
jq empty schemas/*.schema.json
env UV_CACHE_DIR=/tmp/uv-cache uv run pytest

The committed synthetic demo workspace has its own deterministic gate:

cd examples/self-referential-demo
env UV_CACHE_DIR=/tmp/uv-cache uv run cph doctor
env UV_CACHE_DIR=/tmp/uv-cache uv run cph manifest list
env UV_CACHE_DIR=/tmp/uv-cache uv run cph manifest check
env UV_CACHE_DIR=/tmp/uv-cache uv run cph assemble
env UV_CACHE_DIR=/tmp/uv-cache uv run cph handoff

For a copyable toy workspace flow, see docs/getting-started-walkthrough.md.

Privacy

Real paper workspaces should keep these files private and ignored by git:

.cs-paper/
AGENTS.md
CLAUDE.md

Only examples/self-referential-demo may commit synthetic .cs-paper/ state.

Maintainer References

• Documentation Index
• Protocol Overview
• Command Boundary
• Stage Contracts
• Evidence And Claims
• Manifest Contract
• Handoff State
• Paper Sync Reconciliation
• Maintainer Architecture
• Release Operations
• Release Evidence Ledger
• Manual Acceptance
• Release Contract
• Development Roadmap
• Changelog
• Security Policy
• Support

The project is licensed under the MIT License.