Working with agents

You clone Manifest. You build your app — features, schemas, services. Weeks pass. You add authentication, wire up a database, build an API that your frontend talks to. The framework source lives right there in manifest/, and you've read it. Maybe you've even tweaked a few things.

Meanwhile, upstream evolves. Better validation. Improved error handling. New extensions. The framework keeps getting better — and your project has diverged from it in ways that matter.

This is usually where things get messy. Here's how Manifest tries to handle it.

Because the framework is source code — not an npm package — updating looks different. The agent reads every upstream commit, groups them by area, and recommends what to cherry-pick and what to skip. You decide what enters your app.

The two-branch model keeps this clean. The manifest branch tracks upstream. Your main branch is your app. Updates flow one direction: upstream → manifest → cherry-pick onto main. When there's a conflict, the agent categorizes the file — framework or application code — and tries to make the right call. It usually gets it right. When it doesn't, you're there.

Here's an idea Manifest leans into: the commit history is how agents orient themselves when they arrive at your codebase. If commit messages explain what changed and why — not just "fix stuff" — the next agent can read git log and understand the project's progression without looking at a single diff.

Think of each commit as a knowledge transfer. What changed. Why it changed. The approach taken. What was deliberately left out. This also helps the update skill know what to accept, skip, or adapt when upstream evolves.

You added three features, installed an extension, and modified a service. The code works. But does the rest of the codebase know? Does AGENTS.md still reflect reality? Do the skills still make sense? Are there test files for everything?

The learn skill checks whether the surrounding context needs to catch up after changes — documentation, skills, types, tests, commit quality. The idea: the next agent that arrives shouldn't follow stale instructions because someone forgot to update the map after moving the furniture.

Conflicts during cherry-picks aren't just code conflicts — they're intent conflicts. The upstream repo evolves the framework. Your project evolves the application. When they collide, the agent tries to categorize every file: framework code, application code, shared documentation, or your vision.

The heuristic: framework improvements get accepted, your features stay untouched, shared files get merged thoughtfully. And VISION.md — what your application is supposed to be — is always yours. That boundary seems to work well, though edge cases still come up. It's part of what we're learning.