The Toolkit: .project-state, Now Yours
#project-state#worksona#building-in-public#release#developer-tools
David Olsson
Yesterday's post was the reflection โ five articles in, the through-line finally clear, the DNA visible end to end. This one is shorter and has a different job. The thing we've been building in public is now a thing you can download.
project-state v2.0 is published. 19 skills, 5 compliance packs, 160KB zip. The docs and the download live here:
That's the whole post, in one link. Everything below is context for why you'd open it.
What's in the box
A typed filesystem (.project-state/) that lives next to your project. Plain YAML, JSON, NDJSON, markdown. No database. No vendor.
19 skills that read and write the substrate โ milestone tracking, status reporting, claim preparation, meeting lifecycle, change register, IP tracking, publication review, lessons learned, closeout. Each one is a single coherent job. Install once, use across every project you run.
A reporting matrix โ one YAML file that says, for each stakeholder, what report at what cadence in what format on which surface. The orchestrator reads it every morning and tells you what's due.
Five compliance packs out of the box: PIC-PCAIS for grant-funded consortia, client-services for consulting engagements, board-investor for VC-backed startups, agile-default for engineering teams, open-source-community for OSS governance. You can run more than one on the same project. You can author your own.
Surfaces it ships to: Slack, Gmail (always as a draft โ never auto-send), Google Calendar, the scsiwyg blog, a static project website. Reports land where your stakeholders already are.
Why the headline says "byproduct"
The frame on the docs site is the thing we landed on after a lot of drafts: routine reporting as a byproduct of normal work.
That's the whole pitch. Not "AI generates your reports." Not "automation eliminates project management." The pitch is narrower and more honest: if you keep your milestones current, log decisions as they happen, flag risks when you see them, classify documents on arrival โ then weekly status, quarterly claims, steering committee packs, board updates, and funder reports write themselves. They have to. The state already contains the answers.
Most multi-stakeholder projects don't fail because the work isn't getting done. They fail because the reporting overhead eats the people doing it. Project Lead writes the same status from scratch every week, pulling from scattered spreadsheets and half-remembered conversations. Hours per week, every week, and the reports are always slightly stale.
project-state doesn't add a tool to that workflow. It dissolves the workflow. The reports are downstream of the state. You maintain one. You get the other for free.
What "v2.0" means
The first internal version was the one we wrote about across the .state series โ built for one specific PIC-funded project, with one specific compliance regime hard-coded into the skills. It worked. But the moment we tried to point it at a second project with a different governance shape, the limits showed up.
v2.0 separates what the skill does from what the project requires. The skill behavior is generic. The pack tells the skill what's specific. Twelve of the original skills carried over unchanged. Six were rewritten to read from profiles. One โ the reporting matrix โ is new and is doing more work than I expected.
The compliance pack model is the part I'm most curious about being wrong about. We've shipped five packs because those are the five we've actually run. The interesting question is what shape your governance has and whether it fits one of the existing packs, fits with modifications, or wants a new pack of its own. The pack-authoring guide is in the docs.
What's not in the box
Honest list, because the docs site won't tell you this part:
The skills are markdown-defined behaviors. They run inside Claude. If you don't have access to Claude (Code, Cowork, or the chat), the substrate still works โ it's just plain files โ but the automation doesn't. This is a Claude-native toolkit. We're not pretending otherwise.
The reporting matrix is a YAML file you fill in. The skills don't guess your stakeholders. You tell the matrix who's on the steering committee, what cadence the board wants, which channel finance prefers, and the orchestrator dispatches accordingly. There's no magic discovery step.
The Gmail integration drafts. It does not send. This is by design. Every email that leaves the project is reviewed by a human first. The skill writes the draft into your Drafts folder; you read it, edit if needed, click send. We chose this constraint deliberately and the docs explain why.
There's no SaaS. There's no dashboard you log into. There's no account to create. The substrate is files in a folder. That's the whole architecture. If you stop using the skills tomorrow, your data stays readable forever, by anything that can read text.
How to start
Three steps, from the docs:
- Download the zip. Unzip it next to your project.
- Symlink the 19 skills into
~/.claude/skills/. - Ask Claude: "scaffold a new v2 project."
That's it. The scaffolder asks you what kind of project this is, which packs apply, who the stakeholders are. It seeds the reporting matrix. It writes the manifest. It tells you what phase you're in.
Then you ask: "what should I do this week?" โ and the orchestrator answers.
What the .state series was actually about
Looking at the full arc โ .blog-state, .app-state, .app-state v2, .project-state, and now this โ the series was never really about any one of those directories. It was about the same observation, sharpened over five iterations: don't make people remember the context. Make the directory remember it instead.
A blog needed it. A product needed it. A consortium-governed project needed it most of all. The shape held every time. The substrate held every time. The agent-prepares-human-decides line held every time. What changed was the scope of what counted as "the work."
This release is where the pattern stops being something we're building and becomes something you can run.
The directory is the thing. The blog is one channel of the system. The system is now downloadable.
โ project-state-docs.vercel.app
160KB. Five-minute install. The substrate outlives the tools.