{"slug": "surface-kdl-specification-format-experimental", "title": "Surface – KDL Specification Format – Experimental", "summary": "Surface, an experimental KDL-based specification format for describing applications without prescribing implementation, has been released as version 0.1 by developer etoxin. The format allows humans and LLMs to share a checked product specification, and the CLI tool 'surf' currently supports macOS only, with installation via source build. The project aims to enable LLMs to generate applications from specifications, with support for Codex and Claude Code integrations.", "body_md": "Surface is a small [KDL](https://kdl.dev/) format for describing an application without prescribing its\nimplementation. It gives humans and LLMs a shared, checked product specification: data,\ncapabilities, interfaces, screens, technology choices, context, and ordered logic.\n\nIt adds just enough syntax to describe an application with the ability to add LLM context to kdl nodes.\n\n**Status:** experimental · **Format:** Surface 0.1 · **Syntax:** KDL 2 · **Extension:**\n`.kdl`\n\n```\n/- kdl-version 2\n\nsurface \"0.1\"\n\napplication \"todo\" {\n    purpose \"Keep a small list of tasks.\"\n\n    stack \"web\" {\n        target \"browser\"\n        technology \"markup\" \"html\"\n        technology \"styling\" \"css\"\n    }\n}\n\ncollection \"todo\" {\n    (string)\"text\"\n    (boolean)\"completed\"\n}\n\n(array)value \"todos\" variable {\n    context (collection)\"todo\" \"Contain the current todos.\"\n}\n\nfunction \"createTodo\" {\n    collection \"todoInput\" {\n        (string)\"text\"\n    }\n\n    input (collection)\"todoInput\"\n    output (collection)\"todo\"\n\n    logic {\n        (collection)\"todoInput\" \"Trim the text and output null if it is empty.\"\n        (collection)\"todo\" \"Otherwise, output a todo with that text and completed set to false.\"\n    }\n}\n\ninterface \"todoList\" {\n    context (value)\"todos\" (function)\"createTodo\" \"Render a text input, an Add button, and the current todos.\"\n\n    logic {\n        (value)\"todos\" \"Start with this value empty.\"\n        (function)\"createTodo\" \"When Add is activated, call this function and append its output when it is not null.\"\n        (collection)\"todo\" \"Let the user toggle each todo between complete and incomplete.\"\n    }\n}\n\nscreen \"home\" {\n    use (interface)\"todoList\"\n}\n```\n\nSurface currently builds locally from source. Install [mise](https://mise.jdx.dev/), then\nbuild and install the CLI for your user:\n\n```\ngit clone https://github.com/etoxin/surface.git\ncd surface\nmise install\nmise run build\ninstall -d \"$HOME/.local/bin\"\ninstall -m 755 build/surf \"$HOME/.local/bin/surf\"\n```\n\nMake sure your `~/.zshrc`\n\ncontains:\n\n```\nexport PATH=\"$HOME/.local/bin:$PATH\"\n```\n\nOpen a new terminal and confirm the installation:\n\n```\nsurf --help\n```\n\nThis installation path currently supports macOS only.\n\nEnter a directory containing a `surface.kdl`\n\nfile, then run:\n\n```\nsurf init\n```\n\nSelect Codex, Claude Code, or both. The command installs their project-local Surface\nskills and adds `/build/`\n\nto `.gitignore`\n\n. Use `surf init --codex`\n\n, `surf init --claude`\n\n,\nor both flags for a non-interactive setup.\n\nTo have an LLM create the specification as well as the application, follow\n[Create a Specification with an LLM](/etoxin/surface/blob/main/examples/llm-authoring/README.md).\n\nStart with [Getting started](/etoxin/surface/blob/main/docs/getting_started.md) to write and implement your own\nspecification. Surface is experimental, so keep the `.kdl`\n\nsource in version control and\nreview generated applications before using them.\n\n| Guide | Purpose |\n|---|---|\n|\n\n[Getting started](/etoxin/surface/blob/main/docs/getting_started.md)[Generating applications](/etoxin/surface/blob/main/docs/generating_applications.md)[Testing and reporting](/etoxin/surface/blob/main/docs/testing.md)[Surface 0.1 grammar](/etoxin/surface/blob/main/docs/grammar.md)[Starting a Surface file](/etoxin/surface/blob/main/docs/node_surface.md)[Application](/etoxin/surface/blob/main/docs/node_application.md)[Technology stacks](/etoxin/surface/blob/main/docs/node_stack.md)[Portable types](/etoxin/surface/blob/main/docs/primitives.md)[Values and enums](/etoxin/surface/blob/main/docs/node_value.md)[Collections](/etoxin/surface/blob/main/docs/node_collection.md)[Functions](/etoxin/surface/blob/main/docs/node_function.md)[Interfaces](/etoxin/surface/blob/main/docs/node_interface.md)[Screens](/etoxin/surface/blob/main/docs/node_screen.md)[Context](/etoxin/surface/blob/main/docs/node_context.md)[Logic](/etoxin/surface/blob/main/docs/node_logic.md)Five examples cover the workflow from first use through platform-scale tests:\n\n[Hello World](/etoxin/surface/blob/main/examples/hello-world/README.md)[Create a Specification with an LLM](/etoxin/surface/blob/main/examples/llm-authoring/README.md)[Todo List](/etoxin/surface/blob/main/examples/todo-list/README.md)[Online Checkout](/etoxin/surface/blob/main/examples/online-checkout/README.md)[Multi-tenant Project Tracker](/etoxin/surface/blob/main/examples/multi-tenant-project-tracker/README.md)\n\nOnline Checkout and Multi-tenant Project Tracker pin Pico CSS 2.1.1 in their application stacks and test the frozen grammar at platform scale.\n\nEach example is its own agent workspace. Enter one and initialize it with the installed CLI:\n\n```\ncd examples/todo-list\nsurf init\n```\n\nSelect Codex, Claude Code, or both, then open that agent in the example directory. Run\n`$surf-build`\n\nin Codex or `/surf:build`\n\nin Claude Code. Both build `surface.kdl`\n\ninto\n`build/`\n\n; generated build directories are ignored by Git.\n\n```\nsurf init [--codex] [--claude]\nsurf parse <file.kdl>\nsurf check <file.kdl>\nsurf format <file.kdl>\nsurf reference <file.kdl> <selector|--list>\n```\n\n`reference --list`\n\ndiscovers selectors and typed reference literals. Passing a selector\nprints its complete KDL declaration for focused human or LLM context.\n\nFor repository development, run `mise tasks`\n\nto see the available tasks. The complete\nrepository check is `mise run verify`\n\n.\n\nSurface 0.1 is frozen. Bug fixes, diagnostics, formatting, documentation, and tooling may improve, but new valid syntax belongs to a later format version.", "url": "https://wpnews.pro/news/surface-kdl-specification-format-experimental", "canonical_source": "https://github.com/etoxin/surface", "published_at": "2026-08-01 23:38:53+00:00", "updated_at": "2026-08-01 23:52:40.229183+00:00", "lang": "en", "topics": ["developer-tools", "artificial-intelligence"], "entities": ["Surface", "KDL", "etoxin", "Codex", "Claude Code", "mise"], "alternates": {"html": "https://wpnews.pro/news/surface-kdl-specification-format-experimental", "markdown": "https://wpnews.pro/news/surface-kdl-specification-format-experimental.md", "text": "https://wpnews.pro/news/surface-kdl-specification-format-experimental.txt", "jsonld": "https://wpnews.pro/news/surface-kdl-specification-format-experimental.jsonld"}}