Skip to content

docs: add AGENTS.md for odf and ooxml modules#602

Open
andiwand wants to merge 1 commit into
mainfrom
docs/odf-ooxml-agents
Open

docs: add AGENTS.md for odf and ooxml modules#602
andiwand wants to merge 1 commit into
mainfrom
docs/odf-ooxml-agents

Conversation

@andiwand

Copy link
Copy Markdown
Member

🤖 Generated with Claude Code

Adds design/orientation docs (AGENTS.md) for the ODF and OOXML engines, aligned with the existing oldms/ and pdf/ docs: rationale, load-bearing design decisions, and current status/gaps — not a restatement of code. Feature checklists stay in the per-module README.mds to avoid duplication.

New files

  • src/odr/internal/odf/AGENTS.md — central ODF doc (all four types in one engine)
  • src/odr/internal/ooxml/AGENTS.md — central OOXML doc (shared packaging / encryption / OPC relationships)
  • src/odr/internal/ooxml/text/AGENTS.md — docx
  • src/odr/internal/ooxml/presentation/AGENTS.md — pptx
  • src/odr/internal/ooxml/spreadsheet/AGENTS.md — xlsx
  • top-level AGENTS.md directory map now links the new docs

Framing

  • Front-and-center for both engines: unlike oldms/pdf, ODF and OOXML keep the parsed XML DOM resident and the ElementRegistry is a thin index of pugi::xml_nodes over it — which is why ODF and docx alone can edit and save.
  • Each doc's status section records foundational gaps (things worth planning next), not just missing style checkboxes.

Notable gaps surfaced from reading the code

  • pptx tables are effectively broken (built with the plain builder, so table_first_column throws; table_dimensions still queries ODF table: names — copy-pasted from the ODF adapter). The same ODF-name copy-paste is latent in the docx table/cell adapter.
  • pptx is_text_node copy-paste bug (checks w:t instead of a:t); full but unexposed text-edit machinery.
  • Shared: agile encryption and big-endian are the big cross-format gaps; xlsx never types values or evaluates formulas; named cell-style masters are loaded but unused.

These latent-bug items are flagged as "verify and rewrite" rather than asserted as confirmed runtime failures, since they come from code reading, not execution.

Add design/orientation docs for AI agents covering the ODF and OOXML
engines, aligned with the existing oldms/ and pdf/ AGENTS.md style:
rationale, load-bearing design decisions, and current status/gaps
rather than restating code (feature checklists stay in the READMEs).

- odf/: central doc for all four ODF types (one engine)
- ooxml/: central doc (shared packaging/encryption/OPC relationships)
  plus per-format docs for text (docx), presentation (pptx),
  spreadsheet (xlsx)
- link the new docs from the top-level AGENTS.md directory map

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NDRJJ85vgG6umQvdpNYYU8
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant