How project-state came to be

April 28, 2026originapp-stateblog-statescsiwygdesign

# How project-state came to be project-state didn't start as a project management system. It started as a blog platform. Understanding that lineage explains a lot about why project-state is built the way it is — and why it works for so many different kinds of work. ## Step one: scsiwyg [scsiwyg](https://www.scsiwyg.com) is a headless, API-first blogging platform. No web editor. Content is written in Markdown and published via MCP tool calls from inside an AI IDE. It was built because the existing publishing workflow — write in Notion, copy to Ghost, format twice, lose version history — was too much friction for the pace of building. scsiwyg solved the publishing problem. But it immediately created a new one: **how does the agent know what to write about?** If you're publishing from inside a software repo, the agent needs context. What has already been published? What changed in the code since the last post? What's the narrative arc of the project? What's worth saying, and when? None of that lives in the code itself. So a small state directory appeared in the repo: `.blog-state/`. A JSON file tracking what was published, what was queued, what the last analysis found. Enough context for the agent to orient and act. The `repo-publisher` skill formalized it. It reads `.blog-state/`, decides what's worth writing about, produces drafts, and publishes via scsiwyg. It works because the state file gives the agent persistent memory that survives across sessions. ## Step two: app-state Once `.blog-state/` was working, the pattern was obvious. If you can give the agent persistent memory about a repo's publishing history, why not give it persistent memory about *everything*? `.app-state/` was born — a file-based, agent-readable intelligence layer covering the full product lifecycle: - **Technical health** — code audit scores, security posture, test coverage - **Dev velocity** — sprint history, velocity trends, what shipped vs slipped - **Business signals** — user feedback, competitor moves, growth metrics - **Roadmap** — milestones, OKRs, planned features, decisions in-flight - **Editorial** — blog ideas, draft queue, publication history The `app-state` skill reads and writes that directory. Any agent in any session can pick it up and know where the product stands. No re-reading the codebase. No asking "what were we working on?" every Monday morning. The key insight from `app-state`: **structured files on disk are a better long-term memory for AI agents than conversation history**. Conversation history is ephemeral. Files persist. Files are versionable. Files can be read by teammates, by scripts, and by different AI models on different days. ## Step three: project-state app-state is built around a software product — a codebase with git history, a CI pipeline, a user base. But a lot of work doesn't look like that. Consider a funded research consortium. Six organizations. An external funder who needs quarterly reports in a specific format. A Steering Committee that meets every six weeks. IP disclosures to file. Change requests to approve. Partners who need different information than funders do. app-state wasn't the right fit. The milestones weren't code releases, they were deliverables. The stakeholders weren't users, they were funders with contract requirements. The reporting surface wasn't a blog, it was a formal PDF submitted through a government portal. But the *pattern* was identical: **give the agent persistent, structured state so it can act across sessions without losing context.** The first version of what became project-state was built for a real PIC-funded consortium — it worked. But it had the consortium baked in. Specific stakeholder shapes. Specific report formats. Specific cadences. v2.0 separated the generic pattern from the specific instantiation. The generic core became 18 `project-*` skills. The consortium-specific behavior moved into a compliance pack. And four more pack starters shipped for different project types: client engagements, board-backed startups, agile engineering teams, open-source communities. ## The pattern, abstracted Looking back, every step in this lineage followed the same move: 1. **Identify what the agent needs to know** to act helpfully across sessions 2. **Store it in structured files** on a shared drive, not in conversation history 3. **Build skills that read and write those files** rather than asking the human to re-explain 4. **Generalize the structure** so it works for any instance of the problem, not just the one you first solved scsiwyg → `.blog-state/` → `.app-state/` → `.project-state/` is that pattern applied three times. The next question is what domain it gets applied to next. Financial state? Research state? Legal matter state? The pattern is general enough that the answer is probably all of the above. For now: project-state is built, documented, and open. If you're running a multi-stakeholder project and the reporting is eating your week, this is the thing.