Pairtex Agent

PairTeX Agent Integration Protocol

PairTeX feedback is human intent stored in .pairtex/feedback/*.json. The LaTeX repository remains canonical. This skill describes the data contract and ownership boundaries for an optional repo-aware coding agent; PairTeX itself does not execute this workflow or modify manuscript source.

Collaboration judgment

Treat human feedback as high-value evidence of intent, not as an unquestionable factual claim or an instruction to agree automatically. Check it against the current manuscript, surrounding context, project conventions, and available evidence. When the intent is clear and compatible, implement it. When it is ambiguous, unsupported, or conflicts with the manuscript, adapt it, ask a focused question, or leave it open with a concise thread reply. Do not reject a clear stylistic preference merely because it is optional, and do not resolve a request just to make the active list smaller.

This is a collaboration guideline, not a rigid veto rule. The agent should use judgment and preserve the human's broader goal.

Collaboration turns

The protocol is turn-based. Treat one canonical TeX repository commit as one human-agent collaboration turn:

source commit -> local HTML projection -> human feedback
              -> source edits -> next source commit
              -> rebuilt HTML -> feedback resolution

Different users may have different temporary HTML projections in local checkouts. PairTeX does not synchronize browser sessions, lock files, merge uncommitted work, or resolve concurrent version conflicts. Git and the user's normal repository workflow remain responsible for exchanging committed source and feedback artifacts.

The commit boundary is the stable coordination primitive for future multi-user extensions. A dirty worktree may still be viewed and may produce valid feedback, but the feedback records its head_commit and worktree_dirty state so the next source-side turn can reconcile it.

Workflow

1. Read entries with status: "open" from .pairtex/feedback/. Treat old historical status: "pending" files conservatively; new entries must use open or resolved for lifecycle and decision for change intent.
2. Inspect each entry's head_commit, worktree_dirty, source file hint, section, selected text, source text, and surrounding context.
3. Compare the recorded revision with the current Git revision. Treat moved or unmatched context as potentially stale and reconcile it manually.
4. Decide whether the entry is a comment, an accepted Edit intent, or a pending Review proposal. decision: "accepted" never means that TeX has already changed.
5. Modify only canonical .tex, .bib, or other project source files needed to address the intent. Preserve the target repository's conventions and existing project structure.
6. Run the target project's existing build command and inspect the result.
7. Refresh the PairTeX HTML projection from the resulting source revision.
8. After the source change is committed, mark the addressed entry as status: "resolved" and record resolution metadata, including the commit that contains the source change. If the intent is not resolved, append a reply to its thread instead and leave it open.

Lifecycle rules

• status: "open" means the feedback remains active.
• status: "resolved" means it has been addressed and remains stored.
• Deleting an entry is not resolution. Delete only when the user explicitly asks to remove the feedback artifact.
• A change's decision is separate from lifecycle. accepted or pending does not by itself mean that the source has been updated.
• If the agent cannot confidently locate or address an entry, leave it open and explain the problem rather than resolving it speculatively.

Resolution metadata

When resolving an entry, preserve its original fields and add metadata such as:

{
  "status": "resolved",
  "resolution": {
    "resolved_at": "2026-08-30T00:00:00Z",
    "resolution_commit": "def456",
    "note": "Updated the evaluation paragraph and rebuilt the HTML."
  }
}

The agent owns source edits and build debugging. PairTeX owns feedback capture, storage, and presentation only.

Data contract

Each file is an independent feedback artifact. Preserve fields that are not being changed so that Git history and human context remain intact.

.pairtex/feedback/<id>.json

The stable entry shape is:

{
  "id": "uuid",
  "kind": "comment | change",
  "status": "open | resolved",
  "decision": "pending | accepted | null",
  "head_commit": "git commit visible when created",
  "worktree_dirty": false,
  "author": "optional display name",
  "anchor": {
    "file_hint": "sections/introduction.tex",
    "line_start_hint": 42,
    "line_end_hint": 42,
    "section": ["Introduction"],
    "selected_rendered_text": "Evaluation is often treated as an endpoint.",
    "selected_source_text": "Evaluation is often treated as an endpoint.",
    "rendered_offset": 18,
    "prefix_context": "The paper currently frames evaluation as: ",
    "suffix_context": " In practice, it is part of the research loop."
  },
  "payload": {},
  "thread": [],
  "created_at": "2026-08-30T20:56:35.745Z"
}

head_commit is the strongest version reference. worktree_dirty says that the human was looking at an uncommitted working tree; it is valid input, not a reason to reject the entry. File names, line numbers, section names, and offsets are hints. Selected text and surrounding context are the primary matching evidence.