Skip to content

AGENTS.md

Latest commit

 

History

History
79 lines (54 loc) · 3.98 KB

AGENTS.md

File metadata and controls

79 lines (54 loc) · 3.98 KB
Raw

BetterOffice

Comments

NO inline comments unless the code is not understandable without them. Docstrings must be extremely concise.

Docs

  • Don't add or edit docs, READMEs, guides or comments to describe a fix or a change's history. The PR body and the changeset carry that.
  • Touch user docs only when public API or user-visible behaviour changes, and then minimally.
  • No process, status, planning or agent-loop documents in the repo: operating guides, running benchmark logs, overnight plans, personal paths or environments.
  • openspec/ is only for major, long-term initiatives. Keep a spec current or delete it.

Titles

PR and commit titles use scoped conventional commits: type(scope): summary. Scope is the affected area — a format (docx, xlsx, pptx, vsdx), a shared crate (opc, text), or an area (ci, deps, web, agents). Keep the summary concise and imperative.

Examples: feat(docx): layout engine, fix(xlsx): formula precedence, ci(deps): bump actions/checkout.

PR style

PR bodies follow this template:

TL;DR:
<human (!) written tl;dr of the pr>

Before/After:
<only for visual changes: before and after screenshots>

Repro file:
<only for engine fixes/improvements: link to the file that reproduces the issue>

Summary:
<concise bullets, gen'd by agent>

Test plan:
<check-boxes the author must fulfill before pinging for review>

Section rules:

  • TL;DR — written by a human, always. Agents must leave it empty and never fill it in.
  • Before/After: include only when the PR makes visual changes. Upload before and after screenshots with GitHub CLI or the browser, following the review artifact instructions below. Omit the section entirely otherwise.
  • Repro file: for engine changes, attach the repro file to the PR or link a fixture used by automated tests. Omit the section otherwise.
  • Summary — concise bullets describing what changed; generated by the agent. What changed, not how.
  • Test plan — GitHub check-boxes (- [ ]). The author must fulfill every box before pinging for review.

Changesets

A changeset body is a tl;dr for the changelog, not a design doc: 1–2 plain, compact sentences on what changed for package users. New or changed public API names (props, options, methods, events) go in backticks; state whether a feature is opt-in or on by default. Leave out internals, rationale, benchmarks and em dashes. CI fails a body over 45 words.

Example: "Adds previewFirstPage, which paints the first pages before the full open finishes. Off by default."

PR review

  • After opening a PR, wait for the automated reviews: Greptile and kyora review (the kyora-review[bot] summary and the kyora review check). Both have the same standing. If both review, address both; if only one is present, iterate on that one's findings.
  • Read every finding, assess whether it is valid, and tell the user what you propose to fix or dismiss. Fix valid findings within the authorized scope and run the relevant checks.
  • Reply to each review thread with the fix and validation, or explain why the finding does not apply. Resolve threads only once addressed.
  • After pushing fixes, request a fresh review from each reviewer present (@greptileai review, @kyora-review review) and wait for it. Repeat until there are no actionable findings.
  • Verify that each reviewer present reviewed the latest commit (kyora's summary names the commit it reviewed); resolving a thread does not replace a fresh review. If a review is unavailable or still pending, report that explicitly and do not present the PR as cleared.

Review artifacts

Put review screenshots, repro files, recordings, and logs in the PR, never in git. Keep actual product assets and automated test fixtures/baselines. Use GitHub CLI v2.101.0+ for image and video attachments:

gh pr comment "$PR_NUMBER" --attach /tmp/before.png --attach /tmp/after.png

Attach repro documents and logs through GitHub's web UI. If uploading fails, report it; do not commit the files as a workaround.