A Plaintext Creative Workflow

Most creative tools assume you know what you’re building before you start. A game engine wants sprites and a scene tree. A design system generator wants tokens and components. A project management tool wants tasks and deadlines. They all skip the same step: figuring out what the thing actually is before committing to how it gets made.

This is a plaintext creative workflow I built to fix that. It is not software in the traditional sense — it is a set of plain-text files, a workflow discipline, and a small collection of tools that enforce one rule: describe the project as data before writing any implementation code.

The problem it solves

I kept starting projects that collapsed around week three. The pattern was always the same: exciting idea, fast prototype, growing complexity, loss of clarity about what the core thing even was, abandonment. The prototypes were fine. The problem was that I never had a grammar for the project — a structural description of what it contained, what its parts did, and what the core loop was supposed to produce.

A game is not its engine. A design system is not its component library. A research experiment is not its notebook. These are all delivery mechanisms. The actual creative product is the grammar underneath — the state model, the instruments, the actions, the observations. If that grammar is never written down, the project is held together by vibes and memory. Both decay.

How it works

The system has four layers.

Layer 1: The method

Every project follows the same loop:

brief → proposal → smoke → experiment → metrics → decision → archive

A brief is a scoped unit of work with explicit acceptance criteria and a list of files you are allowed to touch. A proposal is how you plan to execute it. A smoke test checks that the preconditions hold. The experiment is the actual work. Metrics are evidence that the experiment produced something measurable. A decision is a recorded judgment — ACCEPTED, REJECTED, or INCONCLUSIVE — that references the metrics and proposes the next step. The archive preserves the completed run.

No work without a brief. No accepted change without evidence. No next step without a decision.

This sounds bureaucratic until you try the alternative, which is three weeks of undocumented exploration ending in a folder full of half-finished prototypes and no clear record of what worked or why anything was abandoned.

Layer 2: The templates

The system provides project templates for different domains:

• Games follow a file-first model: state, then instruments, then actions, then observations, then archive. Every interface element must answer four questions: what state does it read, what state does it change, what action does it perform, and what evidence does it create. No engine work until the core loop is proven in text.

• Visual systems start with token definition, component specification, and render examples before any implementation.

• Research experiments start with hypothesis and method before running anything.

• Software tools start with interface specification before implementation.

The template is not scaffolding in the Rails sense — it is a structural discipline. A game project will have a project.yaml containing the thesis and invariants, a bag.yaml tracking the current phase and next legal step, a briefs/ directory and a decisions/ directory tracking every authorized change and its outcome, and a grammar/ directory containing the actual game grammar defined as YAML and Markdown.

Layer 3: The inspector

A Python CLI reads the YAML and Markdown project files and produces:

• An index — every entity in the project (systems, modules, screens, flows, decisions) catalogued with their relationships
• A validation report — missing fields, broken references, orphan entities, incomplete definitions
• A relationship graph — how everything connects, annotated with health status (complete, incomplete, missing)
• Four export formats — Mermaid, DOT, D2, and Excalidraw diagrams
• A TUI — a five-tab terminal interface for browsing the project model

The inspector treats the project’s YAML files as a schema. A module definition like this:

id: module.receiver
name: Receiver
system: system.observatory
reads:
  - station.target_coordinates
  - sky.signal_map
writes:
  - observation.raw_signal
actions:
  - point_target
  - tune_frequency
  - start_capture
screens:
  - screen.receiver-screen
status: defined

…is not configuration for a game engine. It is the project’s grammar. The receiver reads coordinates and signal maps, writes raw observations, and exposes three actions. The inspector can verify that the referenced screen actually exists, that the parent system is defined, and that no references are dangling.

When you run the full pipeline on a well-structured project you get a graph that shows every entity, every relationship, and every gap — color-coded by health. Green nodes are complete. Yellow nodes have missing fields. Red nodes are referenced but undefined.

Layer 4: The governance layer

A separate registry tracks every repository: its type, migration status, visibility, publication posture, and relationship to the broader thesis. This is the system that answers questions like “which of my repos are safe to link publicly?” and “which repos need metadata standardization before I can reference them in writing?”

The governance layer has its own lifecycle: audit, then docs-only, then metadata-standardized, then ready-for-rename, then renamed, then site-integrated. Repos move through this pipeline one at a time, with validation at each step. The registry is YAML. The validation is a Python script. The principle is the same as everything else in the system: describe the state as data, then inspect it.

The gate system

For games specifically, the system defines six gates:

The rule is absolute: no runtime, no UI, no visual work before Gate F. The game must exist as a proven text-based loop before anyone writes a line of engine code.

This sounds extreme but it filters out the failure mode I kept hitting. Most abandoned game projects die because the designer builds an engine and then discovers the core mechanic does not work. By the time you have a renderer, a physics system, and an input handler, you are debugging infrastructure instead of designing gameplay. The gate system forces the design question first.

What it looks like in practice

The reference implementation is a radio telescope observatory game. Over nine phases following this system, the project progressed from a one-page game grammar to a fully defined model with eight instruments, eight screens, six flows, hidden systems, a time grammar, and visual artifact mappings. The entire model lives in YAML files. No engine has been chosen yet. The core loop has been proven in a text-based CLI prototype that reads the same YAML files the inspector reads.

Phase 7 was particularly interesting: running the inspector against the project model caught three undefined references and two missing fields that would have become bugs in an engine. Catching structural errors in YAML files costs seconds. Catching them in a game engine costs days.

Constraints as a creative tool

The biggest influence on this system is Hundred Rabbits — a creative collective that builds small tools on a sailboat with extreme resource constraints. Their approach: small tools, plain files, durable formats, explicit constraints. A drawing tool that limits you to a grid. A sequencer that limits you to 36 operations. A virtual machine that runs anywhere and fits in 512 bytes.

The insight is that constraints are not limitations on creativity — they are the mechanism by which creativity becomes productive. An unconstrained project expands in every direction and finishes nothing. A constrained project has a grammar, and a grammar has a completion condition.

Visual languages in this system work the same way. They are optional constraint plugins — not tools you must use, but disciplines you can adopt. A pixel language limits resolution. A terminal language limits output to text. A vector grid language limits geometry to a grid. The constraint shapes the output by limiting choices, not by adding ornament.

Why plain text

Everything in this system is Markdown, YAML, or shell. No databases, no web applications, no generated frameworks. If you cannot read it in a text editor, it does not belong.

This is partly philosophical (small tools, durable formats) and partly practical: plain text survives everything. It works with git. It works with grep. It works with AI agents — an agent that can read a brief, produce an artifact, and stop at a decision boundary is actually useful. An agent that needs a running database and a web server to understand the project state is not.

The system must remain small. If it cannot be understood in one sitting, it has grown wrong. That sentence is the last line of the manifesto, and it is also the hardest constraint to maintain. The temptation is always to add one more entity type, one more validation rule, one more export format. The discipline is to stop when the system does what it needs to do and no more.

What it does not do

It does not manage tasks. It does not schedule work. It does not generate code. It does not replace an engine, a design tool, or a research notebook. It is the layer underneath those things — the structural description that tells you what the project is before you decide how to build it.

It also does not enforce anything automatically, at least not yet. The constraints are documented expectations. The validation catches structural errors, not creative ones. The gate system is a convention, not a compiler. The discipline is manual and intentional.

This is a feature, not a missing feature. Automated enforcement is appropriate for mature systems. For a creative workflow, the act of manually following the loop — writing the brief, recording the decision, updating the bag — is itself the creative practice. The process is the product.