OfficeIMO
AGENTS.md713 starsChanged yesterdayMITView on GitHub
.NET document engines without Office installed: Word, Excel, PowerPoint, PDF, Markdown, HTML, Visio, Project, Access, OpenDocument, iWork, email and many more formats, plus readers, converters, the OfficeIMO.Tool CLI/MCP server, OfficeIMO Studio and the PSWriteOffice PowerShell module. - OfficeIMO.<Format>/: one engine or converter per project (OfficeIMO.Word, OfficeIMO.Word.Pdf, OfficeIMO.Reader.*, ...), with <Project>.Tests/, .Benchmarks/, .Verification/ and .AotSmoke/ siblings. OfficeIMO/ is the cross-format converter and batch package (tests in OfficeIMO.Tests/). - OfficeIMO.slnx is the full solution; OfficeIMO.<Area>.slnf filters scope it to one area (Word,…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository5 other files it gives its agents.
The file
We split this AGENTS.md into the rules it gives an agent
10 rules. About 0 are common, 8 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈8
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 77
Document the current contract through measured workloads, not competitor parity or PR progress.
- Distinctive: line 87
Keep hosts thin: Studio, the website, cmdlets, MCP tools and demos call engine APIs.
- Distinctive: line 89
No new external runtime dependencies without an explicit decision.
- Very specific: line 92
Don't copy, port or adapt code from other projects.
- Very specific: line 107
Commit titles are plain sentences describing the change: Keep content file associations when editing attachments in tagged PDFs.
- Distinctive: line 133
Before adding or changing tests, apply the shared test-audit authoring gate and contract-focused proof guidance.
- Distinctive: line 135
Don't write tests that pin human-written prose (README, roadmap, migration).
- Distinctive: line 136
Test Markdown as a format.
- Distinctive: line 139
Add a comparison lane only when every implementation does equivalent, validated work.
- Distinctive: line 147
Keep bulky corpus output, clips and frames outside the repository.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
OfficeIMO
.NET document engines without Office installed: Word, Excel, PowerPoint, PDF, Markdown, HTML, Visio, Project, Access, OpenDocument, iWork, email and many more formats, plus readers, converters, the OfficeIMO.Tool CLI/MCP server, OfficeIMO Studio and the PSWriteOffice PowerShell module.
Layout
OfficeIMO.<Format>/: one engine or converter per project (OfficeIMO.Word,OfficeIMO.Word.Pdf,OfficeIMO.Reader.*, ...), with<Project>.Tests/,.Benchmarks/,.Verification/and.AotSmoke/siblings.OfficeIMO/is the cross-format converter and batch package (tests inOfficeIMO.Tests/).OfficeIMO.slnxis the full solution;OfficeIMO.<Area>.slnffilters scope it to one area (Word, Excel, Pdf, Html, Studio, PowerShell, Benchmarks, ...).PowerShell/PSWriteOffice/: the module (C# cmdlets inSources/, Pester tests,Docs/). It references the engines in this checkout.OfficeIMO.Studio*/: desktop Studio (Avalonia, Windows and Linux).Apple/: the native Mac, iPad and iPhone apps (Swift package).OfficeIMO.Tool/: CLI and MCP server..agents/plugins/officeimo-document-tools/: the agent plugin that ships it.Website/: officeimo.com (PowerForge site pipeline,Website/build.ps1), withWebsite/Apps/for the browser-local WebAssembly tools.Build/: build, release, generators, evidence and verification scripts.Docs/: guides, design docs, support matrices andROADMAP.md.Tools/OfficeIMO.Html.Pdf.Workbench/: Blazor workbench with its ownAGENTS.md.
Build and test
Builds use the SDK pinned in global.json (10.0.100, latest feature roll-forward)
and PSPublishModule 3.0.170 or later. Engines target netstandard2.0, net8.0,
net10.0, plus net472 on Windows; test projects (xUnit) target net8.0 and
net10.0, some also net472 on Windows. The full solution is very large:
build and test the area you changed.
dotnet build OfficeIMO.Word.slnf -c Release
dotnet test OfficeIMO.Word.Tests/OfficeIMO.Word.Tests.csproj -c Release -f net8.0 --filter "Category!=Performance"
dotnet test OfficeIMO.Pdf.Tests/OfficeIMO.Pdf.Tests.csproj -c Release -f net10.0
./Build/Build-Module.ps1 -IncludePackages:$false # unsigned PSWriteOffice build
./Build/Build-Module.ps1 -RunMode Documentation -IncludePackages:$false # regenerate cmdlet docs
cd PowerShell/PSWriteOffice; ./PSWriteOffice.Tests.ps1 # module Pester tests
./Build/Build-Release.ps1 # packages + module, unsigned
./Website/build.ps1 -Serve # website./Build/Build-Release.ps1 -RunMode Publish -SignModule:$true signs and
publishes NuGet, PowerShell Gallery and the GitHub release. Release only.
Build/project.build.json owns package selection and version bindings;
OfficeIMO.Word is the version anchor. Docs/building-and-releasing.md covers
PDF gates, documentation examples and recovery.
Generated files
Edit the source, then regenerate. Never hand-edit the output.
*OpenXmlValueTypes.Generated.cs:Build/Generate-*OpenXmlValueTypes.ps1.- README example blocks in
README.md, the Word, Excel and PDF READMEs andDocs/officeimo.pdf-guide.md: fromBuild/DocumentationExamples, synced withpowerforge docs sync --config Build/docs-sync.json --apply. PowerShell/PSWriteOffice/Docs/*.mdand external help: from cmdlet XML comments via the Documentation run mode above.Website/data/format_map.jsonand format map clips:./Build/Record-FormatMap.ps1(seeDocs/officeimo.format-map-media.md). Don't commit clips or frames.- Agent plugin compatibility manifests: from
plugin.jsonandmcp.jsonwith PowerForgeagent-plugin sync. Theagent-pluginbranch is generated by the release workflow; never edit it.
Documentation
- READMEs (root and per package) are user-facing: what it does, how to install
it (latest NuGet version), its public API.
MIGRATION.mdholds actionable upgrade changes only; release history lives in GitHub Releases. Docs/ROADMAP.mdis the single product backlog, open work only. Don't create other backlogs or gap plans; remove delivered items once their contract is in the owning package or support matrix.- Document the current contract through measured workloads, not competitor parity or PR progress. Keep coverage and limits in the support matrices.
- Studio capability changes update
Website/data/studio_features.json(per platform; available only where it works) and passWebsite/scripts/Test-StudioFeatureMatrix.ps1. MCP tool or skill changes updateWebsite/data/agent_integrations.jsonand passWebsite/scripts/Test-AgentIntegrations.ps1.
Conventions
- Warnings are errors, nullable is on. Follow
.editorconfig. - Keep hosts thin: Studio, the website, cmdlets, MCP tools and demos call engine APIs; reusable behaviour lives in the engine.
- No new external runtime dependencies without an explicit decision. Comparison libraries stay in benchmark projects and opt-in runners, outside the normal solution when their dependencies or licences would affect restore.
- Don't copy, port or adapt code from other projects. Third-party data that ships
in a package goes in
Build/third-party-material.json, with its license texts packed and a section in the package'sTHIRD-PARTY-NOTICES.md;python Build/validate_third_party_notices.pymust pass. See "Third-party material and package licenses" inDocs/building-and-releasing.md. - Studio and OfficeIMO.Workflows convert in process. LibreOffice and Pandoc references in fixtures, benchmarks or verification scripts are independent validation, not runtime requirements; don't carry them into Studio prerequisites, packaging or feature gating.
- Studio interface text is translated into every shipped language in the same
change, for both the desktop
StudioStrings.<language>.resxfiles and the Apple String Catalogs. Use theBuild/Studio/*-StudioTranslations.ps1scripts;Build/Studio/Test-StudioTranslations.ps1must pass. - PSWriteOffice cmdlets stay thin. Engine contract changes include the PowerShell workflows. The module supports Windows PowerShell 5.1 and 7.
- Commit titles are plain sentences describing the change:
Keep content file associations when editing attachments in tagged PDFs.
Product boundaries
- Project (
Docs/ROADMAP.md#microsoft-project-document-library,OfficeIMO.Project/SUPPORT.md): one typed model, thin fluent wrappers, explicit scheduling, separate native-generation codecs, operation-level preservation and conversion reports. - Access (
Docs/officeimo.access-design.md): one typedAccessDocument, generation-specific native codecs, strict loss policy by default, optional DbaClientX execution. Qualify reading, preservation, editing, native creation, conversion and execution separately. Keep VBA, macros and modules inert: never enable trusted locations or execute startup code during validation. - For both: don't replace native writing with XML/text export, template-free creation with seed-file patching, or independent-producer proof with self-round-trip tests. A missing oracle or fixture is an open gap, not a pass.
- HTML engine (
Docs/officeimo.html-engine-design.md): AngleSharp and Jint are the parser and scripting providers; improve them upstream rather than replacing them. Keepnet472while PowerShell 5.1 needs it. Breaking API cleanup is acceptable when consumers are migrated.feature/html-engineholds the parked scripted runtime: don't merge or rebase it intomasteror build new static work on it.
Tests and benchmarks
- Before adding or changing tests, apply the shared test-audit authoring gate and contract-focused proof guidance. Resolve these paths against
CODEX_HOMEwhen configured. - Don't write tests that pin human-written prose (README, roadmap, migration). Test Markdown as a format; check generated docs against their generator.
- Tag measurement-only tests
[Trait("Category", "Performance")]. CI excludes them; timing, allocation and memory budgets run only in opt-in evidence runs. Add a comparison lane only when every implementation does equivalent, validated work. - Live and interop tests are opt-in through environment switches, for example
OFFICEIMO_RUN_GOOGLE_WORKSPACE_LIVE,OFFICEIMO_RUN_LEGACY_DOC_COM_VALIDATION(and the PPT, XLS and Word layout COM variants) andOFFICEIMO_RUN_VBA_SIP_INTEROP. They need Google credentials or installed Microsoft Office. - Many
Build/Test-*.ps1gates need external tools (LibreOffice, Microsoft Office, veraPDF, ffmpeg, Tesseract) or Windows. Run them only when the task needs that evidence. - Keep bulky corpus output, clips and frames outside the repository.
Agent plugin and MCP Registry
- The plugin versions with the OfficeIMO.Tool package; any bundle change, skills
included, needs a patch release. Validate with PowerForge
agent-plugin validate --source .agents/plugins/officeimo-document-tools --project OfficeIMO.Tool/OfficeIMO.Tool.csproj.Build/validate_mcp_registry.pychecksOfficeIMO.Tool/server.json.
Repository skills
Contributor skills in .agents/skills:
officeimo-build-release: building, packaging and releasing OfficeIMO and PSWriteOffice.officeimo-conversion-operator: changing or validating conversion behaviour.officeimo-studio-translations: adding Studio languages and interface text.officeimo-website-wasm: officeimo.com browser tools and the WebAssembly engine.pswritepdf-retirement: moving PSWritePDF behaviour into OfficeIMO and PSWriteOffice.
The plugin's skills under .agents/plugins/ are for users of the tools, not for
working on this repository.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

