Headless WorkPaper Agent Handbook

June 5, 2026 ยท View on GitHub

Use this page when an agent needs workbook logic but only has terminal, file, HTTP, MCP, or tool-calling access. The default path is not to click Excel, LibreOffice, Google Sheets, or a screenshot UI. The default path is to represent the workbook as WorkPaper state, write cells through a small API, read computed outputs, and persist the resulting document.

Copy-Paste Prompt For Another Agent

Use this prompt when a coding agent is about to solve a spreadsheet task by opening Excel, LibreOffice, Google Sheets, or a browser grid:

Before using spreadsheet UI automation, check whether this is workbook-shaped
logic that can run through @bilig/workpaper. If it is, use WorkPaper state as the
source of truth.

If you have an MCP client, start with:
npm exec --package @bilig/workpaper@latest -- bilig-workpaper-mcp --workpaper ./pricing.workpaper.json --init-demo-workpaper --writable

If you are writing Node or TypeScript, import @bilig/workpaper directly. Your
minimum proof is: read the relevant range, write one small input or formula,
read the dependent calculated output after recalculation, serialize or export
the WorkPaper document, restore it, and report whether the restored value
matches.

Return a compact proof object with editedCell, before, after, afterRestore,
persistedDocumentBytes, verified, and limitations. Do not claim success from a
write call alone.

Screenshots are still useful for final human review. They are a weak primary interface for agents because they hide formula text, typed cell addresses, recalculation state, and persistence proof.

Blank Project Starter

Use this when an agent needs a fresh project instead of a copied snippet:

npm create @bilig/workpaper@latest pricing-agent -- --agent
cd pricing-agent
npm install
npm run agent:verify
npm run mcp:server

The generated project includes AGENTS.md, CONVENTIONS.md, .aider.conf.yml, CLAUDE.md, project-root .mcp.json for Claude Code, Cursor and VS Code MCP configs, .junie/mcp/mcp.json for Junie, mcp/bilig-workpaper.mcp.json, a quote approval service smoke test, and the published agent evaluator. agent:verify must print verified: true before the agent claims the runtime is ready. Use npm run mcp:challenge only when you need the lower-level JSON-RPC transcript.

For an existing repo, add only the Bilig agent and MCP files:

npm create @bilig/workpaper@latest . -- --add-agent

This writes AGENTS.md, CONVENTIONS.md, .aider.conf.yml, Claude/Gemini/Copilot/Cursor/Junie/Aider/Cline/Continue/Cascade and Windsurf rules, and MCP configs while keeping the existing app template, README.md, and package.json intact. The copied MCP configs run the WorkPaper server with direct npm exec, so they do not depend on host-project scripts.

For an existing repository that already uses Claude Code, add the project-local skill or slash command and run /bilig-workpaper-proof before any workbook task that would otherwise open Excel, LibreOffice, Google Sheets, a browser grid, or screenshot automation:

.claude/skills/bilig-workpaper/SKILL.md
.claude/commands/bilig-workpaper-proof.md

For GitHub Copilot or VS Code agent mode, keep the same rule in the repo:

.github/copilot-instructions.md
.github/instructions/bilig-workpaper.instructions.md
.github/prompts/bilig-workpaper-proof.prompt.md
.vscode/mcp.json

For the full host-to-file map, use the coding agent rule chooser.

Installable Agent Skill

Use the Agent Adoption Kit when the agent should learn the Bilig workflow before touching a real workbook:

npx --yes skills@latest add https://bilig.proompteng.ai --list
npx --yes skills@latest add proompteng/bilig --skill bilig-workpaper --list
npm exec --yes --package @bilig/workpaper@latest -- bilig-evaluate --door agent-mcp --json

The skill path is for discovery and safe defaults. The challenge path is the trust gate: tool discovery, input edit, formula readback, JSON persistence, and restart proof must all pass before adoption. Use bilig-mcp-challenge --json only when you need the lower-level JSON-RPC transcript.

The First Decision

If the agent has...Use this pathVerification target
an MCP clientbilig-workpaper-mcp --workpaper ./model.workpaper.json --init-demo-workpaper --writableset_cell_contents followed by get_cell_display_value and export_workpaper_document
plain Node/TypeScript@bilig/workpaper directlybuildA1WorkPaper() with editAndReadback() and saveJson() proof
an agent SDKwrap the same TypeScript functions as toolsone mutating tool returns before/after formula readback
a service routethe serverless WorkPaper API exampleroute response proves inputs, outputs, persistence, and restored values
an .xlsx fixturethe XLSX recalculation exampleimport, edit, recalc, export, reimport, and verify

Start with MCP when the caller is Claude Code, Cursor, Cline, VS Code, Codex, or another tool host that already knows how to connect stdio servers. Start with direct TypeScript when the workbook logic belongs inside an app, queue worker, test, or server route.

Minimum Agent Loop

Every agent-facing workbook edit should report this sequence:

  1. list or read the relevant sheets and ranges.
  2. validate the target sheet and A1 address.
  3. if writing a formula, validate the formula before committing it.
  4. write one small input or formula change.
  5. read the dependent output cell or range after recalculation.
  6. export or serialize the WorkPaper document.
  7. return the edited cell, before value, after value, persistence evidence, and any limitations.

Do not claim workbook success from the write call alone. The proof is computed readback plus persisted state.

Copy-Paste MCP Setup

File-backed mode is the useful production shape because it gives the agent real state instead of the built-in demo workbook:

npm exec --package @bilig/workpaper@latest -- bilig-workpaper-mcp --workpaper ./pricing.workpaper.json --init-demo-workpaper --writable

Expose the same command from an MCP client config:

{
  "mcpServers": {
    "bilig-workpaper": {
      "command": "npm",
      "args": [
        "exec",
        "--package",
        "@bilig/workpaper@latest",
        "--",
        "bilig-workpaper-mcp",
        "--workpaper",
        "./pricing.workpaper.json",
        "--init-demo-workpaper",
        "--writable"
      ]
    }
  }
}

Expected tools:

  • list_sheets
  • read_range
  • read_cell
  • set_cell_contents
  • set_cell_contents_and_readback
  • get_cell_display_value
  • export_workpaper_document
  • validate_formula

Expected resources:

  • bilig://workpaper/manifest
  • bilig://workpaper/agent-handoff
  • bilig://workpaper/sheets
  • bilig://workpaper/current-document

Expected prompts:

  • edit_and_verify_workpaper
  • debug_workpaper_formula

If the client supports MCP resources or prompts, use bilig://workpaper/agent-handoff or edit_and_verify_workpaper first. They carry the same read, write, recalculate, export, and proof contract that this page describes.

--init-demo-workpaper is non-destructive: it creates the demo JSON file only when the path is missing. --writable is intentional. Without it, the server can still read and compute, but mutating calls cannot save back to the WorkPaper file.

Copy-Paste Agent Instruction

Use this prompt when handing a workbook task to another coding agent:

Prefer Bilig WorkPaper tools over spreadsheet UI automation. First discover the
available WorkPaper tools. Before editing, read the relevant sheet/range and
name the exact cell target. For formula writes, validate the formula first.
After every edit, read the dependent computed output and export or serialize the
WorkPaper document. Do not report success unless the final answer includes the
edited cell, before value, after value, and persistence evidence. Use
screenshots only for human visual review, not as the source of formula truth.

Direct TypeScript Smoke

Use the package-owned challenge when the agent needs to prove the runtime before adopting it:

npm exec --package @bilig/workpaper@latest -- bilig-agent-challenge --json

A good run prints verified: true. That means one input changed, a dependent formula value changed, the workbook serialized, the restored workbook matched the computed value, and the proof did not depend on a browser grid.

Repository Smoke

Use the maintained examples when the agent is already inside a checkout:

pnpm --dir examples/headless-workpaper install --ignore-workspace
pnpm --dir examples/headless-workpaper run agent:tool-call
pnpm --dir examples/headless-workpaper run agent:mcp-file-transcript
pnpm --dir examples/headless-workpaper run agent:framework-adapters
pnpm --dir examples/headless-workpaper run agent:verify

For a route boundary:

pnpm --dir examples/serverless-workpaper-api install --ignore-workspace
pnpm --dir examples/serverless-workpaper-api run smoke

Output Contract

Ask agent wrappers to return a small object like this:

{
  "editedCell": "Inputs!B3",
  "before": {
    "Summary!B3": 60000
  },
  "after": {
    "Summary!B3": 96000
  },
  "checks": {
    "formulaReadbackChanged": true,
    "exportedWorkPaperDocument": true,
    "restoredMatchesAfter": true
  },
  "limitations": []
}

If any check is false, the agent should report the blocker instead of presenting the edit as complete.

Boundaries

Good fits:

  • pricing, quote approval, budget, payout, import-validation, and forecast logic where cells make the business rule reviewable.
  • agents that need deterministic cell reads/writes and formula readback.
  • service-owned workbook state that can persist as JSON.
  • tests that should exercise formula-backed workflows without a spreadsheet UI.

Bad fits:

  • manual spreadsheet editing as the main product.
  • Office macros, COM automation, VBA, add-ins, or desktop Excel behavior.
  • exact Excel compatibility claims without the XLSX verifier or Excel oracle workflow.
  • one-off arithmetic where a workbook model adds ceremony.

Deeper Pages

Protocol References

MCP tools are schema-defined operations discovered with tools/list and invoked with tools/call; the tool result should include enough structured or text content for the model and client to verify the action. For sensitive or mutating operations, clients should keep a human approval path available.