OfficeCLI Three-Layer Architecture (L1/L2/L3): Progressive Complexity for Office Automation

OfficeCLI implements a three-layer architecture that enables AI agents to start with high-level semantic views (L1), escalate to DOM-like property editing (L2), and only fall back to raw XML manipulation (L3) when necessary, optimizing token efficiency while maintaining full OpenXML capabilities.

The iOfficeAI/OfficeCLI repository provides a command-line interface for automating Microsoft Office documents through a unique three-layer architecture that organizes all file operations into progressive levels of abstraction. This design allows automated agents to interact with Word, Excel, and PowerPoint files using the simplest possible command set, descending to lower-level controls only when higher-level abstractions prove insufficient. By separating read-only inspection from structured editing and raw XML access, the OfficeCLI three-layer architecture ensures agents consume the fewest possible tokens while retaining the ability to handle complex edge cases.

Understanding the Three Layers (L1, L2, L3)

The three-layer architecture divides every Office file operation into distinct tiers based on complexity and abstraction level. According to the README.md and SKILL.md files in the repository, each layer serves a specific purpose in the automation workflow.

Layer L1 – High-Level Semantic Views

L1 provides read-only, semantic views of documents without touching the underlying XML. This layer focuses on inspection and understanding, offering concise representations that keep token usage minimal.

• Purpose: Inspect document structure and content before making changes
• Commands: officecli view <file> text, officecli view <file> html, officecli view <file> outline
• Key characteristic: No XML manipulation; purely extractive operations

When an agent needs to understand a document's structure, locate elements, or verify content, it begins here. This layer returns structured representations like outlines or HTML previews rather than raw OpenXML.

Layer L2 – Dotted-Attribute Editing

L2 exposes DOM-like properties using dotted attribute syntax (--prop font.size=12pt), allowing fine-grained control while maintaining schema integrity. The CLI translates these high-level properties into valid OpenXML automatically.

• Purpose: Modify document properties without writing raw XML
• Commands: officecli set <file> /path --prop <attribute>
• Key characteristic: Guaranteed schema correctness through abstraction

This layer handles most editing tasks, from changing font sizes to setting number formats. Because the CLI manages the underlying XML translation, agents avoid syntax errors while maintaining precise control.

Layer L3 – Raw XML Fallback

L3 provides direct XPath access to the underlying OpenXML for edge cases that L1 and L2 cannot express. This layer performs no schema validation, placing responsibility for correctness on the user.

• Purpose: Handle custom elements, non-standard attributes, or niche features
• Commands: officecli raw-set <file> /path --xpath "<expression>" --xml "<fragment>"
• Key characteristic: Full OpenXML access with no abstraction safety net

Agents drop to L3 only when dealing with custom list items, specialized PPTX transitions, or other non-standard OpenXML elements that lack corresponding L2 properties.

The Progressive Complexity Workflow

The progressive complexity model follows a strict escalation path designed to minimize complexity and token consumption:

1. Start at L1 – Use view commands to inspect the document structure, locate target elements, and verify current state. This prevents unnecessary edits and keeps initial context token counts low.

2. Escalate to L2 – When the required change maps to a known property (font size, bold formatting, cell number formats), issue set commands with --prop flags. This preserves schema integrity while avoiding raw XML verbosity.

3. Drop to L3 only when necessary – For requirements that lack corresponding properties (custom dropdown values differing from display text, VML fallback shapes, or morph transition parameters), use raw-set with explicit XPath and XML fragments.

Because each layer adds only the complexity absolutely required, agents maintain simple code paths and minimal token usage while retaining access to the full OpenXML specification when needed.

Implementation in the Source Code

The three-layer architecture is implemented across several key files in the iOfficeAI/OfficeCLI repository:

• README.md – Defines the top-level "Progressive complexity (L1 → L2 → L3)" concept and outlines the purpose of each abstraction layer.
• SKILL.md – Details the concrete command mappings (view, set, raw-set) and provides the "raw-set escape hatch" documentation for L3 operations.
• src/officecli/Handlers/Word/WordHandler.cs – Implements the L2 property parsing (--prop flag handling) and L3 raw-XML processing (raw-set command execution) for Word documents.
• src/officecli/Handlers/Excel/ExcelHandler.cs – Contains the L2 dotted-attribute logic for spreadsheet elements and L3 raw XML handling for Excel-specific edge cases.
• plugins/plugin-protocol.md – Lists the supported verbs (add, set, raw-set) that constitute the three-layer command structure.

Code Examples by Layer

L1: Read-Only Inspection

# Generate a structural outline of a Word document

officecli view my-report.docx outline

# Create an HTML preview for visual verification

officecli view my-report.docx html

L2: Property-Based Editing

# Modify font size and weight in a specific paragraph

officecli set my-report.docx /body/p[2] \
    --prop font.size=14pt \
    --prop bold=true

# Set currency formatting in an Excel cell

officecli set sales.xlsx /Sheet1/B5 \
    --prop numFmt='$#,##0' \
    --prop bold=true

L3: Raw XML Manipulation

# Append custom list items where stored values differ from display text

officecli raw-set my-form.docx /document \
    --xpath "//w:sdt[w:sdtPr/w:tag/@w:val='dept']/w:sdtPr/w:dropDownList" \
    --action append \
    --xml '<w:listItem w:displayText="Engineering" w:value="ENG"/>
           <w:listItem w:displayText="Finance" w:value="FIN"/>'

# Modify a PPTX morph transition speed not covered by L2 properties

officecli raw-set deck.pptx /slide[3] \
    --xpath "//p:transition" \
    --action setattr \
    --xml 'spd=slow'

Summary

• The OfficeCLI three-layer architecture separates file operations into L1 (read-only views), L2 (property editing), and L3 (raw XML access).
• Progressive complexity requires starting at L1, escalating to L2 when possible, and only using L3 for edge cases.
• L2 commands guarantee OpenXML schema validity by translating dotted attributes (--prop font.size=12pt) into proper XML structures.
• L3 commands provide XPath-based access for custom elements but require manual XML correctness.
• The architecture is implemented in WordHandler.cs and ExcelHandler.cs, with specifications documented in README.md and SKILL.md.

Frequently Asked Questions

What distinguishes L2 from L3 in the OfficeCLI architecture?

L2 uses high-level property syntax (--prop font.size=12pt) that the CLI translates into schema-valid OpenXML, protecting against malformed documents. L3 provides direct XPath access to the XML tree without validation, necessary for custom elements or non-standard attributes that lack L2 mappings, but requires the user to ensure XML correctness.

When should I use L1 view commands instead of immediately editing?

Use L1 commands whenever you need to inspect document structure, locate specific elements, or verify content before modification. Starting with officecli view minimizes token consumption by returning concise semantic representations (outlines, text extractions) rather than loading full document XML into context, and prevents unnecessary edits by confirming the current state.

How does OfficeCLI maintain schema validity across the three layers?

Schema validity is enforced only at L2, where the set command translates dotted properties into guaranteed-valid OpenXML through the handlers in WordHandler.cs and ExcelHandler.cs. L1 is read-only and therefore cannot invalidate schemas. L3 bypasses validation entirely, allowing raw XML insertion via raw-set, which places the responsibility for schema correctness on the agent or user.

Can I combine L2 and L3 operations in the same workflow?

Yes, agents typically mix layers within a single workflow: use L1 to locate a target element, L2 to apply standard formatting changes, and L3 only for specific attributes that lack L2 properties (such as custom dropdown values or specialized transition effects). This hybrid approach maintains token efficiency and schema safety while handling edge cases that require raw XML.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}