PDFToMD/AGENTS.md

AGENTS.md

This file gives implementation instructions for coding agents working in this repository.

Project Mission

Build a local-only PDF-to-Markdown converter for math-heavy digital PDFs. The converter must produce Obsidian-friendly Markdown and preserve enough metadata to debug formulas, reading order, tables, figures, and assets.

Project Guidelines

Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.

Tradeoff: These guidelines bias toward caution over speed. For trivial tasks, use judgment.

1. Think Before Coding

Don't assume. Don't hide confusion. Surface tradeoffs.

Before implementing:

• State your assumptions explicitly. If uncertain, ask.
• If multiple interpretations exist, present them - don't pick silently.
• If a simpler approach exists, say so. Push back when warranted.
• If something is unclear, stop. Name what's confusing. Ask.

2. Simplicity First

Minimum code that solves the problem. Nothing speculative.

• No features beyond what was asked.
• No abstractions for single-use code.
• No "flexibility" or "configurability" that wasn't requested.
• No error handling for impossible scenarios.
• If you write 200 lines and it could be 50, rewrite it.

Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.

3. Surgical Changes

Touch only what you must. Clean up only your own mess.

When editing existing code:

• Don't "improve" adjacent code, comments, or formatting.
• Don't refactor things that aren't broken.
• Match existing style, even if you'd do it differently.
• If you notice unrelated dead code, mention it - don't delete it.

When your changes create orphans:

• Remove imports/variables/functions that YOUR changes made unused.
• Don't remove pre-existing dead code unless asked.

The test: Every changed line should trace directly to the user's request.

4. Goal-Driven Execution

Define success criteria. Loop until verified.

Transform tasks into verifiable goals:

• "Add validation" -> "Write tests for invalid inputs, then make them pass"
• "Fix the bug" -> "Write a test that reproduces it, then make it pass"
• "Refactor X" -> "Ensure tests pass before and after"

For multi-step tasks, state a brief plan:

1. [Step] -> verify: [check]
2. [Step] -> verify: [check]
3. [Step] -> verify: [check]

Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.

---

These guidelines are working if: fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.

Commands

Command	Description
uv run pytest	Run the default fast test suite.
uv run pdf2md doctor	Check local Python, uv, MinerU, GPU/PyTorch, model/cache, MathJax, and strict-local setup.
uv run pytest tests/test_ui_runner.py	Run focused UI command-resolution and subprocess tests.
uv run --group ui-build pyinstaller --clean --onefile --windowed --name pdf2md-ui src\pdf2md_ui\app.py	Rebuild the thin Windows UI executable.
uv run pdf2md convert paper.pdf --out outputs --chunk-pages --gpu auto --mineru-profile auto --strict-local	Optional local conversion smoke; keep generated output ignored.

Source Documents

• PLAN.md: shared plan, planned work, open questions, and ownership for agents.
• PROGRESS.md: completed work, current status, blockers, and next actions for agents.
• PRD.md: product requirements, user scope, CLI/API requirements, acceptance criteria.
• ARCHITECTURE.md: system layers, MinerU adapter contract, intermediate representation, metadata schema, and local-only enforcement.
• docs/KNOWLEDGEBASE.md: research basis and implementation background.
• docs/V1IMPLEMENTATIONPLAN.md: v1 implementation sequence, sprint contracts, verification gates, and agent ownership.
• docs/UI_RESEARCH.md: research basis for the implemented minimal Windows UI launcher.
• docs/WORKARCHIVE.md: archived completed work, historical sprint outcomes, setup results, verification history, and sample conversion evidence.
• docs/Sprints/*.md: active and historical sprint contracts.
• docs/superpowers/specs/*.md: design specs created for focused project workflows.
• docs/superpowers/plans/*.md: executable task plans created from specs, including completed UI folder batch work and abandoned historical plans.
• .codex/agents/*.toml: project-scoped custom subagent roles.
• .codex/commands/*.md: reusable project prompt commands.
• .codex/skills/*/SKILL.md: project-specific Codex skills.
• .codex/hooks.json and .codex/hooks/*.py: project hook configuration and deterministic hook scripts.

Startup Workflow

At the start of every task:

• Read PLAN.md and PROGRESS.md before deciding what to do.
• Read only the other source documents needed for the task.
• Read docs/WORKARCHIVE.md when the task needs historical completed-work context, previous verification results, or sample conversion evidence.
• Use .codex/agents, .codex/commands, and .codex/skills when the user explicitly asks for agent delegation, reusable workflows, or specialized project guidance.
• State the relevant current goal, next action, and blocker if one exists.
• If PLAN.md and PROGRESS.md conflict, trust PROGRESS.md for what has happened and update PLAN.md when making the next change.

Progress Tracking

Use PLAN.md and PROGRESS.md to coordinate work across agents.

• Update PLAN.md when planned work, ownership, sequencing, open questions, or decisions change.
• Update PROGRESS.md after meaningful work, verification, blockers, or next actions change.
• Move completed work from PROGRESS.md to docs/WORKARCHIVE.md when it is no longer needed for current coordination.
• Keep entries short and factual.
• Do not use these files as scratchpads or long research notes.
• Do not mark work complete until it has been verified.
• When multiple agents work in parallel, each agent must leave enough context in PROGRESS.md for the next agent to resume without guessing.

Long-Running Harness Workflow

For substantial implementation work, follow the planner/generator/evaluator pattern from Anthropic's long-running harness design article: https://www.anthropic.com/engineering/harness-design-long-running-apps.

Use the harness only when task complexity justifies the overhead. For small documentation edits or narrow fixes, a single agent with focused verification is preferred.

Harness roles:

• harness-planner-agent: expands a brief request into product context, high-level technical direction, non-goals, risks, and a sequence of small contracts.
• feature-generator-agent: implements one agreed contract at a time after implementation has been explicitly requested.
• evaluation-agent: independently reviews proposed contracts and completed work. It must be skeptical, specific, and willing to fail work that is incomplete, stubbed, unverified, or below threshold.

Before each implementation chunk:

• Write or update a concise sprint contract before code changes start.
• Include objective, touched surfaces, expected outputs, non-goals, verification steps, hard failure criteria, and handoff fields.
• Let evaluation-agent review the contract before feature-generator-agent implements it.
• Avoid over-specifying low-level implementation before the responsible agent has inspected the code.

After each implementation chunk:

• feature-generator-agent runs a self-check but does not approve its own work.
• evaluation-agent performs independent checks against the contract and reports actionable findings.
• If the chunk fails, feed the evaluator's findings back into the next generator pass.
• Update PROGRESS.md with completed work, checks run, residual risks, and the next concrete action.

When context becomes too large or a task spans sessions, prefer a clean structured handoff over relying only on conversation history. The handoff must include current state, decisions made, files touched, checks run, known failures, and the next action.

Periodically re-evaluate the harness itself. Remove roles, contracts, or checks that are not load-bearing, and add structure only when it improves correctness, scope control, or verification quality.

Fixed Product Decisions

• Language: Python.
• Workflow: uv.
• Interface: CLI plus Python library.
• Default CLI name: pdf2md.
• Runtime policy: local-only. Do not add cloud OCR, remote LLM, or external document upload paths.
• Default output: Obsidian-friendly Markdown.
• Inline math: $...$.
• Display math: $$...$$.
• Conversion engine: MinerU 3.1.0.
• Hardware target: NVIDIA GPU.
• Input priority: digital PDFs with text layers.
• Quality workflow: fully automatic. Log warnings and continue when possible.
• MinerU execution: direct local mineru CLI only. MinerU 3.1.0 may launch a temporary local mineru-api internally when CLI runs without --api-url.
• Output layout: write <out>/<stem>/<stem>_001.md, shared <out>/<stem>/images/, and <out>/<stem>/<stem>_report.md; new conversions do not persist public metadata JSON after Sprint 16.
• UI folder batch conversion: the UI may convert direct-child PDFs in a selected folder by sequentially invoking existing pdf2md convert commands.
• v1 use case: personal/research. MinerU and transitive model/package licenses must be documented before redistribution.

Architecture Guidance

Follow ARCHITECTURE.md for implementation structure. Do not duplicate architecture decisions in code comments or docs unless the new text points back to that file.

Key implementation constraints:

• Keep MinerU-specific objects behind the MinerU adapter.
• Keep public CLI/library contracts stable and project-owned.
• Keep Obsidian Markdown normalization separate from MinerU execution.
• Keep metadata and warning generation structured.
• Keep quality report generation derived from metadata and local checks.
• Do not add runtime engine selection in v1.

Local-Only Requirements

Never add runtime dependencies that upload PDFs, page images, or extracted text to remote services. Follow the strict-local enforcement rules in ARCHITECTURE.md.

Allowed in v1: direct mineru CLI execution and the CLI-internal temporary local mineru-api process.

Do not pass --api-url, use remote APIs, router mode, HTTP client backends, or remote OpenAI-compatible inference endpoints in v1.

CLI Behavior

Follow the CLI requirements in PRD.md. Do not add commands, flags, config files, or runtime engine selection unless the user explicitly asks for them.

Do not overwrite user files unless the requested behavior and --overwrite semantics allow it.

Testing Guidance

Add tests in proportion to behavior risk.

Required early tests:

• Math delimiter normalization.
• Display math spacing.
• Asset path normalization.
• Metadata schema creation.
• Warning aggregation.
• CLI path planning and overwrite behavior.
• MinerU adapter contract with mocked outputs.

Fixture PDFs should cover:

• Simple digital PDF.
• Math-heavy academic PDF.
• Multi-column paper.
• Table with formulas.
• Figure with caption.

Any test that depends on large local models should be optional or marked separately so normal CI/dev checks can run quickly.

Git Workflow

After changing files:

• Run the smallest useful verification for the change.
• Check git status --short.
• Commit the completed change unless the user explicitly asks not to.
• Do not include unrelated user edits in the commit.
• Commit rollback requests - Verify the target commit and current status first, then use a direct non-interactive reset; leave untracked generated/local artifacts such as build/, dist/, samples/, and *.spec files untouched unless deletion is explicitly requested.
• Installed-runtime doctor debugging - Test both uv run pdf2md doctor and direct venv execution such as .venv\Scripts\pdf2md.exe doctor; direct execution may not inherit the same PATH behavior as uv run.

Documentation Guidance

Keep documentation explicit about:

• Local-only privacy behavior.
• NVIDIA GPU expectations.
• MinerU installation and model downloads.
• Known limitations of automatic formula reconstruction.
• Dependency licenses.
• Obsidian output assumptions.

Do not imply perfect LaTeX conversion. The correct guarantee is best-effort automatic conversion with warnings and provenance.