.app-state Is the Next Logical Step for IDE-Native Development
#scsiwyg#devlog#building-in-public#reflection#developer-tools#app-state
David Olsson
Most software projects carry two codebases.
The first is the one everyone can see: the source files, the schema, the tests, the deploy config. Version controlled. Reviewable. The thing CI runs against.
The second lives nowhere. It's distributed across Notion pages, Slack threads, stale READMEs, the PM's brain, the founding engineer's memory. It's the context: why this architecture, what's the market doing, what did we defer and why, what's the next thing.
The gap between these two has always been the gap between what code says and what developers know. In a pre-AI-IDE world, this was manageable โ a human holds the context in their head, translates it into code, commits it. The IDE is just a text editor with autocomplete.
That world is ending.
What's actually changed
When a developer opens Claude Code today, they're not opening a text editor. They're opening a collaborator โ one that reads files, reasons about architecture, proposes refactors, writes tests, explains behavior. It does this well.
But it starts every session cold.
Without context, the AI has to re-derive everything from the code itself. What's the intent? What are the constraints? What's been tried and abandoned? What's the competitive pressure driving this feature? The agent can make educated guesses, but guesses are costly: wrong assumptions produce wrong suggestions, and wrong suggestions produce back-and-forth that slows everything down.
This is the fundamental problem .app-state/ solves.
Not by making the AI smarter. By giving it something to read.
The anatomy of a .app-state/ directory
Every .app-state/ is a structured directory that lives in the repo root. It's checked in alongside the code. It's updated by agents. It's human-readable by design.
The structure is organized into sections, each answering a specific question:
Core answers: what is this app right now? Git head, API surface, schema tables, known issues, shipped vs. planned vs. deferred features. This is the minimum viable context โ every project has it, even solo experiments.
Dev answers: what has changed in the code? A timeline of commits categorized by type (feature, fix, infra, security), velocity metrics per 7 and 30 days, a changelog. When the blog pipeline runs, it reads this first.
Decisions answers: why was it built this way? An append-only decision log. Not every commit deserves an entry โ just the non-obvious choices. The ones future-you, or a new team member, or an AI agent would otherwise have to reverse-engineer.
Market answers: where does it sit in the market? Competitors, positioning statement, ICP, industry context. Not a living market research document โ a snapshot good enough to orient the agent.
Signals answers: what is moving in the world around it? An event log for things you notice: competitor launches, regulatory changes, user complaints, platform shifts. Small signals, dated and categorized, that accumulate into context.
Blog answers: what is the product saying about itself? Queue, ideas, published history, voice config. A complete blog state embedded in the repo, so the agent knows what's been said, what hasn't, and what's ready to write.
Roadmap answers: where is it going? Milestones, OKRs, sprints. Structured enough for agents to compute days remaining and flag at-risk KRs. Simple enough to maintain without a project management tool.
And so on: ops, growth, debt, integrations, users. Twelve sections total. Five presets to match project size.
The design principle throughout: every file in .app-state/ should be something an agent can read in a single pass and act on. No prose narrative. No embedded instructions. Structured data and light markdown, nothing more.
Why this matters now
Three things converged to make this the right moment.
First, AI-assisted development crossed a threshold. Claude Code, Cursor, Windsurf โ these aren't tools anymore, they're active participants in the development loop. They write code, review PRs, explain systems, suggest architecture. The intelligence is here. What's missing is the context layer they can read.
Second, the information problem got worse before anyone noticed. As the AI takes on more execution work, developers spend less time in the code and more time directing. The context that used to live in the code (because you wrote all of it) now gets delegated away. The gap between what the system knows and what the developer knows widens.
Third, we already have the discipline โ we just haven't formalized it. Developers who work with AI assistants have already learned to paste architecture notes, explain constraints, provide history. They're doing .app-state/ manually, in every conversation, and discarding it when the window closes. Writing it down once and putting it in the repo is the obvious move.
The agent usage model
When .app-state/ is in place, the model for working with an AI IDE changes.
Instead of establishing context at the start of every session, you establish it once โ in the files โ and the agent reads it. Instead of the agent guessing at the competitive landscape or the planned feature set, it reads market/competitors.json and features.json. Instead of you explaining what just shipped, the dev timeline has it.
The concrete workflow: run /app-state sync after a batch of commits. The agent reads the git log, categorizes commits, updates the timeline, computes velocity, and surfaces what's publish-worthy for the blog. Takes under a minute. Keeps the state current without manual maintenance.
Run /app-state status when you want a dashboard. Run /app-state weekly to get a digest of the last seven days across all sections โ what shipped, what signals came in, what the blog queue looks like, where the sprint stands.
The agent is doing the maintenance work. You're just directing it.
What's coming next
.app-state/ is a foundation, not a finished product.
The roadmap section was the most recent addition โ milestones, OKRs, sprint tracking. Before that, it was blog only (.blog-state/). Before that, nothing.
What's coming: tighter integration between sections (signals that automatically inform positioning updates), richer query patterns (agents that reason across sections, not just read them individually), and shared state across multiple repos in a portfolio.
We're also thinking about what it means for teams. Right now .app-state/ is a single-developer discipline. A team version has different requirements: merge conflicts on state files, role-appropriate read access, the question of who owns the market section vs. the dev section.
These are solvable problems. But we'll solve them in the same way we built this: start small, make the structure explicit, let the agent do the repetitive maintenance, and keep the files human-readable throughout.
The fundamental insight is simple: if you're working with AI in your IDE, the repo is no longer just code. It's a full context surface. .app-state/ makes that surface explicit, structured, and useful.
This is where IDE-native development is going. We're just writing the files down first.