File-based contracts and state-machine orchestration.

Why file-based contracts instead of in-memory state

Skills communicate through files on disk: resolved_manifest.json, slides.json, design-profile.json, qa.json. Each skill invocation is a fresh CLI call. No shared memory, no session state, no persistent connection between skills.

In-memory state would be faster. But files on disk buy you things that matter more.

Debugging, for one. When a deck comes out wrong, you can inspect the resolved manifest to see if the template extraction was correct, read slides.json to see if the plan was reasonable, check qa.json to see what the lint engine found.

Resumability, for another. If the agent's session is interrupted after the build step, the artifacts are still on disk. The next session picks up where the previous one stopped.

And composability. Any tool that can read and write JSON can participate in the pipeline. You could replace the build skill with a different agent, or the critique skill with a human reviewer who edits qa.json by hand.

It's the Unix pipes idea applied to structured data. Instead of piping text between processes, skills pass JSON files between invocations. Small tools, well-defined interfaces.

Why a state machine instead of a linear pipeline

The first design was a linear pipeline: extract, build, audit, critique, polish. Run each step once, in order, done.

It didn't work because deck generation is iterative. The audit step finds font size violations. The critique step finds weak action titles. These need fixing, but fixes can introduce new problems. A text edit that fixes a title might overflow the text box, triggering a layout violation. A linear pipeline has no mechanism for this.

The orchestrator uses a state machine with two quality gates (content and visual) and a fix-and-recheck loop. Any failed gate routes to the fix state, then back to the gate for rechecking. The agent keeps fixing and rechecking until both gates pass.

I tried the alternative: make the build step so good that post-build fixes aren't needed. Unrealistic. Even a well-prompted agent makes visual mistakes. A chart 0.1 inches too wide, a font color that doesn't contrast against a dark background, a missing source line. The state machine accepts this reality and builds error correction into the workflow.

Why two separate quality gates

The content gate (critique) checks storytelling: are the action titles assertive? Is the structure MECE? Does the visual match the text? The visual gate (audit + lint) checks technical quality: font sizes within range, no overlapping shapes, contrast ratios accessible.

These are separate because they require different fix strategies. A content fix (rewriting a title) is a semantic operation that requires understanding the deck's argument. A visual fix (adjusting a font size) is mechanical. When I tried combining them in one pass, the agent confused content feedback with visual feedback and applied the wrong type of fix.

Content and visual quality are also partially independent. A deck can have great storytelling with terrible typography, or perfect visual consistency with a muddled narrative. Checking them separately gives each dimension full attention instead of having one crowd out the other.

Consulting firms do this too, for whatever that's worth. Content review happens in a storyline session with the engagement manager. Visual review happens in a formatting check with the design team. Different people, different criteria, different passes.