agentleFS
EvotecITEvotecIT/OfficeIMO/AGENTS.md

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,…

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
  1. Distinctive:

    Document the current contract through measured workloads, not competitor parity or PR progress.

    line 77
  2. Distinctive:

    Keep hosts thin: Studio, the website, cmdlets, MCP tools and demos call engine APIs.

    line 87
  3. Distinctive:

    No new external runtime dependencies without an explicit decision.

    line 89
  4. Very specific:

    Don't copy, port or adapt code from other projects.

    line 92
  5. Very specific:

    Commit titles are plain sentences describing the change: Keep content file associations when editing attachments in tagged PDFs.

    line 107
  6. Distinctive:

    Before adding or changing tests, apply the shared test-audit authoring gate and contract-focused proof guidance.

    line 133
  7. Distinctive:

    Don't write tests that pin human-written prose (README, roadmap, migration).

    line 135
  8. Distinctive:

    Test Markdown as a format.

    line 136
  9. Distinctive:

    Add a comparison lane only when every implementation does equivalent, validated work.

    line 139
  10. Distinctive:

    Keep bulky corpus output, clips and frames outside the repository.

    line 147

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

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 in OfficeIMO.Tests/).
  • OfficeIMO.slnx is the full solution; OfficeIMO.<Area>.slnf filters scope it to one area (Word, Excel, Pdf, Html, Studio, PowerShell, Benchmarks, ...).
  • PowerShell/PSWriteOffice/: the module (C# cmdlets in Sources/, 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), with Website/Apps/ for the browser-local WebAssembly tools.
  • Build/: build, release, generators, evidence and verification scripts.
  • Docs/: guides, design docs, support matrices and ROADMAP.md.
  • Tools/OfficeIMO.Html.Pdf.Workbench/: Blazor workbench with its own AGENTS.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 and Docs/officeimo.pdf-guide.md: from Build/DocumentationExamples, synced with powerforge docs sync --config Build/docs-sync.json --apply.
  • PowerShell/PSWriteOffice/Docs/*.md and external help: from cmdlet XML comments via the Documentation run mode above.
  • Website/data/format_map.json and format map clips: ./Build/Record-FormatMap.ps1 (see Docs/officeimo.format-map-media.md). Don't commit clips or frames.
  • Agent plugin compatibility manifests: from plugin.json and mcp.json with PowerForge agent-plugin sync. The agent-plugin branch 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.md holds actionable upgrade changes only; release history lives in GitHub Releases.
  • Docs/ROADMAP.md is 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 pass Website/scripts/Test-StudioFeatureMatrix.ps1. MCP tool or skill changes update Website/data/agent_integrations.json and pass Website/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's THIRD-PARTY-NOTICES.md; python Build/validate_third_party_notices.py must pass. See "Third-party material and package licenses" in Docs/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>.resx files and the Apple String Catalogs. Use the Build/Studio/*-StudioTranslations.ps1 scripts; Build/Studio/Test-StudioTranslations.ps1 must 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 typed AccessDocument, 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. Keep net472 while PowerShell 5.1 needs it. Breaking API cleanup is acceptable when consumers are migrated. feature/html-engine holds the parked scripted runtime: don't merge or rebase it into master or 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_HOME when 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) and OFFICEIMO_RUN_VBA_SIP_INTEROP. They need Google credentials or installed Microsoft Office.
  • Many Build/Test-*.ps1 gates 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.py checks OfficeIMO.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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.