ecr_grpo_agent

Imported from Hjhnb-star/ecr_grpo_agent (AGENTS.md). Install upstream with npx skills add Hjhnb-star/ecr_grpo_agent. Copyright stays with the author.

AGENTS.md

OVERVIEW

CoPaper: structured academic paper writing

This is a CoPaper paper-writing project. CoPaper uses a six-phase workflow, 22 agent skills, and a CLI (copaper) to guide you from research storyline to submission-ready LaTeX. The core philosophy is structure-first, human-led, AI-assisted: AI polishes your expression and checks your logic, but never invents research content. Your insight is the soul of the paper; the system helps you express it clearly and defend it rigorously.

STRUCTURE

Project files and their roles

• storyline.md: Research storyline — problem, importance, insight, design, and evaluation plan. The highest-level narrative guiding all downstream writing.
• paper.md: The formal paper framework. Level 1-5 headings define structure; Level 6 (######) headings hold paragraph content (topic sentence + supporting text).
• writingrules.md: Definitive writing constraints — heading rules, character limits, metadata format, image handling.
• relatedwork/: Literature assets directory.
  • literature.json: Canonical metadata catalog for all tracked papers (title, authors, venue, BibTeX, PDF URL, download status, summary path).
  • paper_list.bib: BibTeX reference file, kept in sync with literature.json.
  • pdfs/: Downloaded paper PDFs.
  • papers/: Per-paper markdown summaries generated by multimodal agents.
  • summary.md: Categorized literature overview.
• fig/: Paper figures and charts (JPG/PNG/GIF, max 5MB each).
• templates/: LaTeX conference/journal templates for final export.
• .agents/state.json: Workflow state — phase statuses, checker results, literature counters, writing progress.
• .agents/events.jsonl: Append-only operation log for all CLI and skill actions.
• .agents/cross_index.json: Cross-reference index mapping technical concepts to literature summaries.
• .agents/skills/: The 22 agent skills that power each workflow phase.
• AGENTS.md: This file — the project-level guide for agents.

SIX-PHASE WORKFLOW

From storyline to submission

CoPaper organizes work into six phases. The recommended forward order is:

Flexibility rules:

• Any phase can be skipped via copaper skip <phase> --reason "...".
• Any phase can be re-entered and repeated.
• Reverse paths are supported: paper.md can backfill storyline.md; LaTeX can be imported into paper.md.
• The CLI tracks current_phase automatically based on actual phase statuses.

ARTIFACT MODEL

How data flows between files and skills

The system revolves around a few key artifacts rather than the phases themselves:

Primary artifacts and their producers/consumers:

Supported data flow paths:

1. Forward: storyline.md → relatedwork/ → discussion → experiments → paper.md → LaTeX
2. Reverse: paper.md → storyline.md (via storyline-helper reverse extraction)
3. Reverse: LaTeX → paper.md (via latex2markdown)
4. Fallback: paper.md → relatedwork-finder (when storyline.md is sparse)
5. Loop: paper.md → 7 checkers → review-revise → paper.md (iterative improvement)

SKILL CATALOG

22 skills organized by workflow purpose

Phase 1 — Storyline

Phase 2 — Literature

Phase 3 — Discussion

Phase 4 — Experiments

Phase 5 — Writing

Phase 5 — Quality Assurance (7 Checkers)

Phase 5 — Review & Revision

Phase 6 — LaTeX & Submission

Workflow Management

RECOMMENDED WORKFLOW

Step-by-step guide for writing a paper

Standard Forward Path

1. Initialize: copaper init --name "Paper Title" --domain "research area"
2. Storyline (trigger: "help me write storyline"): Fill in storyline.md section by section. Define problem, importance, insight, design, evaluation plan.
3. Literature (trigger: "find related work"): Search, download, summarize related papers. Build cross-index.
4. Discussion (trigger: "discuss my research"): Socratic questioning to sharpen arguments before writing.
5. Experiments (trigger: "analyze experiments" or copaper skip experiments --reason "..."): Run experiments or skip if theoretical.
6. Writing (trigger: "write the paper"): Use orchestrator to draft paper.md section by section. Each section gets 7-checker review.
7. Review-Revise (trigger: "review and revise"): Multi-round checker-driven revision until quality is satisfactory.
8. Pre-submission (trigger: "submission precheck"): Final quality gate before export.
9. LaTeX (trigger: "convert to latex"): Export to conference-ready LaTeX.

Alternative Entry Points

• Already have a paper draft: Use latex2markdown to import, then storyline-helper reverse extraction to backfill storyline.md.
• Already have storyline but no literature: Start at Phase 2 directly.
• Want to iterate on a specific section: Use markdown-helper directly on that section, then run markdown-review.

WHERE TO LOOK

Key files for common tasks

• Starting a new paper → storyline.md (fill this first)
• Writing paper content → paper.md (the main document)
• Understanding writing rules → writingrules.md
• Checking project progress → copaper status or .agents/state.json
• Finding related work metadata → relatedwork/literature.json
• Reading paper summaries → relatedwork/papers/*.md
• Checking quality issues → .agents/state.json → checkers field
• Finding technical concept coverage → .agents/cross_index.json
• Reviewing operation history → copaper log or .agents/events.jsonl
• CLI automation guidance → .agents/skills/copaper-manage/SKILL.md

CONVENTIONS

Writing and CLI rules

Writing Rules (from writingrules.md)

• Level 1-5 headings (# to #####) are structural only — never write body text under them.
• Level 6 (######) is the only level for paragraph content.
• Level 6 title = topic sentence, max 50 characters.
• Paragraph body = supporting sentences, max 500 characters.
• Metadata uses HTML comments: <!-- description: ... -->.
• Inline math: $...$. Block math: $$...$$.
• Images: JPG/PNG/GIF in fig/, max 5MB.
• Nodes ending in numbers (e.g., "Challenge 1") can be duplicated by incrementing the number.

CLI Rules

• --root is a global option and must appear before the subcommand: copaper --root <dir> status, not copaper status --root <dir>.
• Use full phase names: storyline, literature, discussion, experiments, writing, latex_review.
• Prefer the CLI over hand-editing .agents/state.json or .agents/events.jsonl.

Content Rules

• AI polishes expression and checks logic; it does not invent research content.
• Every claim in paper.md should trace back to storyline.md or experimental evidence.
• Literature summaries must be generated by multimodal subagents reading the actual PDF, not fabricated.
• Paper summaries in relatedwork-finder must be processed one at a time, never in parallel.

ANTI-PATTERNS

Common mistakes to avoid

• Do not modify Level 2-5 headings in paper.md — they define the structural framework.
• Do not write body text directly under Level 1-5 headings — use Level 6 for all content.
• Do not rely on AI to generate meaningful research content — use it for optimization and checking only.
• Do not skip the 7-checker review after completing a section — it is mandatory.
• Do not auto-apply revisions without user confirmation — every change needs explicit approval.
• Do not fabricate checker results — always read from .agents/state.json.
• Do not fabricate literature summaries — always use multimodal subagents reading actual PDFs.
• Do not parallelize paper summaries — process one paper at a time to avoid errors.
• Do not use .github/skills/ (incorrect legacy path) — the correct path is .agents/skills/.
• Do not place --root after subcommands — it must come before.
• Do not use stage letters (A, B, D) — use full phase names (storyline, experiments).
• Do not assume commit, rollback, or diff work outside a Git repository.

COMMANDS

CLI commands for paper workflow management

• copaper init --name "<project>" --domain "<domain>": Initialize project, scaffold skills and starter files.
• copaper status [--json]: View phase statuses and current phase.
• copaper set-phase <phase> --status <status> [--reason <reason>]: Explicitly set a phase status (not_started, in_progress, complete, skipped).
• copaper skip <phase> --reason "<reason>": Skip a phase.
• copaper log [--phase ...] [--operator ...] [--last N] [--since YYYY-MM-DD]: Query operation history.
• copaper report [--since YYYY-MM-DD] [--output file]: Generate progress report.
• copaper commit -m "<message>" [--phase <phase>]: Create a phase-aware Git commit.
• copaper rollback <phase> [-y]: Rollback to the latest commit of a phase.
• copaper diff <phase-a> <phase-b>: Compare two phase snapshots.
• copaper relatedwork status [--json]: View literature metadata catalog status.
• copaper relatedwork import --input <json>: Import search results into canonical catalog.
• copaper relatedwork sync-bib: Synchronize literature.json and paper_list.bib bidirectionally.
• copaper relatedwork download [--paper-id ...] [--retry-failed]: Download PDFs with validation.
• copaper relatedwork register-summary --paper-id <id> --summary-path <path>: Register a completed paper summary.
• copaper relatedwork build-index: Rebuild .agents/cross_index.json from paper summaries.

NOTES

Additional information

• copaper init is non-destructive: it will not overwrite existing storyline.md, paper.md, writingrules.md, AGENTS.md, or already-present skill directories.
• current_phase is automatically derived from actual phase statuses — it is not a static value.
• relatedwork/literature.json is the canonical metadata store; .agents/state.json only keeps aggregate counters (papers_found, papers_downloaded, download_failures, summaries_done).
• report works without Git but will note the missing repository. commit, rollback, and diff require Git.
• The 7 checkers are: problem-checker, novelty-checker, technical-depth-checker, logic-checker, clarity-checker, evaluation-protocol-checker, data-checker.
• Writing modes: Fine mode (markdown-helper) for precision, Fast mode (mad-writer) for throughput. The writing-orchestrator helps choose.
• Socratic discussion covers 57 dimensions across the 7 checker families, with 5 question types: Clarification, Assumption, Evidence, Alternative, Implication.
• Review-Revise has a 5-round safety cap and processes issues by severity: Critical → Major → Minor.