An experiment

Agents are writing more and more of our code. Not autocomplete — actual implementation. Reading codebases, understanding intent, building features end to end. This is happening now, and it's accelerating.

Which raises a question nobody has a definitive answer to: what should a framework look like if agents are the primary authors?

Every framework that exists today was designed for human readers. That made perfect sense — humans were the ones writing and reading the code. But as that changes, is there a better foundation? One designed around how agents actually work?

Manifest is our attempt to find out.

Maybe this is the right approach. Maybe it's not. Maybe agent-first is a category that matters, or maybe agents will get good enough that it doesn't. We don't know yet. The only way to find out is to build it and see how far it goes.

When you watch agents work with existing frameworks, patterns emerge. They struggle with the same things humans struggle with — but for different reasons.

Middleware chains. Decorator-based dependency injection. File-system routing conventions. Auto-discovery. Lifecycle hooks. Convention over configuration taken so far that understanding a single request requires knowing the framework by heart.

Humans deal with this through years of experience and intuition. Agents deal with it by burning context tokens on abstractions they can't see, or by guessing at behavior they can't verify.

So we started wondering: what if the framework was just... explicit? What if every behavior was visible in the code? What if an agent — or a human — could read one file and understand one complete thing?

An interesting side effect: optimizing for agent comprehension seems to produce code that's easier for humans to read too. That might be a signal — or just a coincidence. We're still figuring it out.

Manifest is, first and foremost, an idea: what happens when you design a framework around agent comprehension instead of human convention?

The framework itself is one take on that idea. It's a TypeScript framework running on Bun — that part is normal. What's different is the design constraint: every line of code should be readable by an agent with zero framework-specific knowledge.

One feature, one file. A feature declares its route, inputs, authentication, side effects, error cases, and business logic in a single defineFeature() call. The entire framework is ~1,400 lines of source code that ships inside your project — not as an npm package. Small enough that an agent reads it once and understands the whole thing.

No hidden functionality. No middleware. No decorators. No dependency injection. No file-system routing. If something happens, it's because the code says so.

These are our bets. They might be the right ones, or they might be constraints that don't matter as much as we think.

The honest truth: we don't know how complex you can go with this approach. Can you build a simple API? Yes, easily. Can you build something with fifty features, multiple databases, real-time streaming, and background jobs? That's what we're trying to find out.

Every project built with Manifest pushes the boundary a little further. Some things work beautifully. Some things reveal gaps. The framework evolves from what we learn — and because it ships as source code, you evolve it too.

What Manifest does ask is that you try a different way of thinking about software. Not "learn a new framework" — the framework is small, your agent reads it in seconds. The shift is in how you approach the work: writing code that's meant to be read by something other than you, declaring intent explicitly, keeping behavior visible. That's a mindset change, not a tooling change. It might click. It might not. The only way to know is to try.

The experiment doesn't stop at "agents can read the code." The deeper question is: can agents own the entire lifecycle? Not just writing — building, monitoring, fixing, evolving.

The self-healing loop is the most ambitious bet. An error occurs. The agent reads AGENTS.md to orient itself. It reads the feature file — one file, complete behavior. It diagnoses the issue, edits the code, and Bun hot-reloads the module. No deploy. No restart. The next request runs the new code.

Does it work? Sometimes, remarkably well. Sometimes, not at all. The design decisions — one file per feature, declared side effects, source-code framework, no hidden behavior — exist to make it possible. Whether it's practical at scale is something we're actively learning.

That's the nature of this experiment. We're not presenting a finished product. We're exploring a design space and sharing what we find along the way.

Manifest works today. Features, validation, routing, testing, frontend, streaming, rate limiting, database integration, Docker deployment. You can build real things with it. Spark watches your app and fixes what breaks. That part is solid.

But we're not claiming this is the future of software. We're claiming it's an idea worth testing.

Maybe agent-first frameworks become a real category. Maybe existing frameworks adapt and the distinction stops mattering. Maybe the constraints we chose are the wrong ones. We genuinely don't know — and anyone who tells you they do is selling something.

What we do know is that the question is interesting enough to build toward an answer. Every project that uses Manifest teaches us something about where this approach works, where it breaks, and what agents actually need from the code they work with.

This is for people who are curious about the same question.

Not everyone will be. If your team has deep Rails expertise and it serves you well, keep using Rails. If Next.js gives you what you need, use Next.js. We're not here to tell you your tools are wrong. We're exploring a different set of trade-offs and sharing what we learn.

Fork it. Read the code. Try building something. See if the idea resonates — or if it doesn't.