SpecTree: Composable Instructions

Intro

In the early days of web programming, I'd build little web apps in a single JavaScript file, using libraries like jQuery or MooTools. That worked for a while, but as browsers grew more powerful, the kinds of apps I wanted to build grew more complex.

React was a big step forward for me, changing how I thought about building apps.

Instead of separating concerns into HTML, CSS, and JS, I could instead decompose an app into a tree of composable (and sometimes reusable) "components". It was a simple/elegant idea, and I still use it today in everything I build (including this blog).

LLMs are limited by context

For the last two years, I've been programming a lot with LLMs -- using them to write and debug code, and also using LLM APIs in the apps I build.

At first, my prompts were relatively simple, but as models grew more powerful (especially with reasoning and tool use), my prompts have gotten much longer and more complex.

Models are so good now they can execute on multi-page specs until completion. So the bottleneck for working with them productively is 100% about giving them enough high quality context. So it feels like we need new tools or primitives to help manage more complex context engineering workflows -- instructions, specs, entire design systems, etc.

SpecTree

SpecTree is a simple little experiment I built for myself that I've found useful. It's a small Python (and soon JS/TS) library for writing complex specs or prompts.

It's inspired by two things:

• John Gruber's original Markdown spec
• React's component model, where an app is rendered as a composable tree

Concretely, SpecTree is just Markdown with one addition: the @ operator for transclusion. It lets you build up quite complex LLM prompts as a tree of Markdown files (instructions, context, output formats, etc).

How it works

Just write a Markdown file, and use the @ operator (at the start of a line) to transclude other Markdown files via relative paths:

# Build a Todo App

@code/stack.md
@design/system.md
@design/colors.md
@product/features.md

You can decompose long prompts however you like. For example, I might specify my preferred tech stack in one file, and various design system decisions in another.

# stack.md

- **Language**: TypeScript
- **Framework**: Next.js 15 (App Router)
- **Styling**: Tailwind CSS v4
- **Components**: shadcn/ui
- **Package Manager**: pnpm
  ...

SpecTree provides a single render function to resolve these references into a final Markdown output that can be pasted into any AI tool like Claude Code, Codex, Jules, etc.

Implementation

Like Markdown, I think SpecTree is an idea more than a specific library.

But I've published a simple Python implementation you can try out if you like: https://github.com/fuzzycomputer/spectree.

One interesting thing about it is it's my first attempt at purely spec-driven programming. I didn't write a single line of code here. Instead, I iterated (with Claude Opus) to write several READMEs, specs, and test plans in plain English, describing various details about how it should work.

Then Claude Code wrote a test suite from those specs, followed by all the code needed for tests to pass. In the process of writing the code, it realized there were a few minor ambiguities in the spec, so we looped back to the specs/tests and refined them.

I wouldn't call this "vibe coding". It's still very useful to think like a programmer about various edge cases (you can see an example here).

But I still found it interesting to be discussing these details in English (similar to how a PM and Tech Lead might discuss how a system should work) upstream of writing the actual code.

What's next?

I've recently been building some more complex patterns (like fuzzy compilers, README generators, and LLM design systems), but I needed something like SpecTree as the lowest layer of abstraction in my "fuzzy" computing stack.

I think of it as the "filesystem" layer for this little "fuzzy OS" I'm building up. It lets me create much more complex prompts and context trees that get LLMs to do more useful things.

I'll write about some of these other patterns in future posts.