In our CLI design discussion there was a dispute.

Should we have a draft state for document edits, or not? This means the CLI is not stateless (but it already wasn't, because of keys). But it would allow the agent to make iterations on a document before publishing.

I thought it would be useful to see what the agent had to say about this topic, so I came up with this prompt which was designed to avoid leading the agent response in one direction or another.

Prompt For Agents

You are being consulted as a technical advisor on CLI design. An open-source project is building a command-line interface for a document collaboration platform. The CLI will be used both by humans and by AI agents (LLMs) performing document editing tasks programmatically.

Here is the relevant context about the system:

Document model: Documents are hierarchical trees of typed blocks (headings, paragraphs, images, etc.). Each block has a defined schema that is strictly validated — malformed or incomplete blocks are rejected. A document may contain dozens or hundreds of blocks in a nested structure.

Publishing model: When a change is published, it becomes visible to other collaborators on the network. Published changes are immutable and form part of the document's permanent history. The system is peer-to-peer, so published changes propagate to other nodes.

Editing scope: A single logical edit (e.g. "add a new section about X" or "restructure the introduction") may require creating, modifying, or deleting multiple blocks, potentially at different levels of the hierarchy. Some edits are trivial (changing one block's text), while others are complex multi-block operations.

The design question: Should the CLI support a local draft workflow, or should every command immediately publish its changes?

Option A — Draft workflow: The CLI provides commands to create a local draft, accumulate changes to it over multiple commands, preview the result, and then publish (or discard) the draft as a single operation. Changes are not visible to collaborators until explicitly published.

Option B — Immediate publish: Every CLI command that modifies a document publishes the change immediately. There is no local staging concept. If a logical edit requires multiple commands, each intermediate state is published as it happens.

These options are not mutually exclusive — the CLI could support both, or some hybrid. But the team needs to decide what to prioritize and build first.

Given that AI agents are a primary consumer of this CLI, what approach would you recommend and why? Consider the tradeoffs from both the agent's perspective and the system's perspective.

Results