From .blog-state to .app-state: How a Blogging Idea Became a Product Intelligence System

It started with a simple problem: we kept writing blog posts about scsiwyg but losing track of what we'd already written.

Not the posts themselves — those live in the platform. But the context. Which features had we shipped and not written about? What was sitting in the queue? Were we repeating ourselves? Was there something genuinely worth publishing this week, or were we forcing it?

So we built .blog-state/ — a small directory of JSON and markdown files that lived inside the repo and tracked exactly that. What we'd published. What was queued. What topics we'd covered and which ones were open. A simple state file that an agent could read before deciding what to write.

The repo-publisher skill came out of that: a Claude Code skill that reads .blog-state/, looks at recent commits, and produces draft posts that are actually grounded in real changes. No hallucinated features, no vague positioning. Just: here's what changed, here's why it matters, here's a draft.

It worked. We've published 12 posts from it without manually writing a single one.

---

But then something started bothering us.

The agent kept asking questions we should have been able to answer from the repo itself. What's the current schema? How many REST endpoints does the API expose? What's the competitive positioning? Are we tracking user feedback anywhere?

Every time we started a new conversation with Claude Code, we'd spend the first few minutes re-establishing context. Pasting in architecture notes. Explaining the plan. Reminding it which ORM we use and why we chose Neon over PlanetScale.

This wasn't a Claude problem. It was a state problem. The repo had no structured, agent-readable intelligence layer.

.blog-state/ was a narrow solution to a narrow problem. We needed something wider.

---

The expansion was obvious once we framed it that way.

If we can track blog state in a directory, we can track anything. Dev velocity. Deployment history. Growth metrics. Competitor movements. Tech debt. Market positioning. Active signals from the industry.

The structure already existed in our heads — we were just carrying it around there instead of writing it down somewhere the agent could read it.

.app-state/ is that somewhere. It's a directory of structured files: JSON for machine-readable data, markdown for human-readable context. Every section answers one question:

• state.json — what is this app right now?
• dev/timeline.jsonl — what changed in the code?
• market/competitors.json — who else is in the space?
• signals/log.jsonl — what's moving in the world around it?
• blog/ — what is the product saying about itself?
• decisions/log.md — why was it built this way?

Twelve sections in total. Five presets so you can start small (solo: just core and decisions) and grow into it.

The blog pipeline moved in too. .blog-state/ still exists as a standalone skill — but for scsiwyg, the blogging facility lives inside .app-state/blog/, where it can draw on all the other signals: dev commits, incident logs, growth metrics, market movements. The agent has more to work with. The posts get better.

---

The .blog-state/ idea was right. We just hadn't pushed it far enough.

When your development environment is already an AI-assisted one — when your IDE is actively helping you write code — structured repo state is the natural next step. Not documentation, not wikis. Live, structured, agent-readable files that give the system context it can act on.

That's what .app-state/ is. And we're already planning what comes next.