project-state
A generic operational substrate for multi-stakeholder projects — 18 skills that turn reporting into a byproduct of normal work.
project-state
David OlssonIntelligence, not insights: the eight things organizations never track
Every organization runs a second ledger it never reads — how long decisions sat unmade, who was the only person who understood a system, how often a stakeholder learned something too late. Those things go untracked not because they're unimportant but because they were never stored in a form you could query. project-state changes that, and the difference between insight and intelligence is the whole point.
project-state User Guide
The complete guide to project-state v3.2 — from first install through daily workflows, stakeholder reporting, compliance packs, and grant submissions. 30 skills, 7 packs, one substrate.
Publishing and external comms — Slack, Gmail, blog, website
Five surfaces, one principle: the system generates the artifact, a human decides to send it. Gmail is always draft. Slack auto-posts. Blog and website have configurable review gates.
Customization — packs, matrix, and custom phases
Packs configure, code doesn't. Six skills load their behavior from YAML profiles shipped by compliance packs. The reporting matrix, phase presets, and gate criteria are all editable.
Phase transitions and gates
Five phase presets define the lifecycle. Gates enforce what must be true before you can move forward. The skill refuses transitions when artifacts are missing — and tells you exactly what's blocking.
Onboarding — turning documents into project context
Drop your project documents into the inbox, run the triage, and watch project-state extract milestones, stakeholders, risks, and context from what you already have.
Install project-state in five minutes
From zero to 30 slash commands in two terminal commands. Three install paths, one verification checklist.
Your first scaffold — from empty directory to working substrate
The 6-step scaffolding wizard creates a typed project-state/ directory with manifest, reporting matrix, phase presets, and activity log — ready for the other 29 skills to operate on.
The daily routine — orchestrator, status, and the reporting matrix
The orchestrator reads your state and calendar, produces a prioritized brief, and delegates to the right skill. The reporting matrix encodes what reports exist, for whom, and when.
Milestones, risks, and decisions — the working state
Everything in project-state is a YAML file. One file per milestone, one per risk, one per decision. The files are the source of truth — reports are generated from them, not the other way around.
The kanban dashboard — your local project UI
A local Next.js app on port 3355 that reads the substrate directly on every page load. Five views, no sync step, no database.
Harvesting intelligence — pulling signals from Slack, Gmail, Docs, and blog
The harvester reads four external surfaces, filters for project relevance using the manifest, and deposits classified intel docs into the inbox. Cursors track where each surface left off.
Why a typed substrate beats a wiki for AI agents
Obsidian and wikis are built for humans writing prose. project-state is built for AI agents doing work. The difference isn't the content — it's whether the agent has to interpret what it reads or can act on it directly.
project-state v3.2 — dual-surface scaffolding, grant-canada pack, and 30 skills
v3.2 ships dual-surface interactive wizards (HTML artifact + markdown), the grant-canada compliance pack covering 19 Canadian programs and 12 compliance gates, bringing the total to 30 skills, and a local Next.js kanban dashboard with milestone detail view.
work-state: From Events to Intelligence — Building the Reporting Layer
The harvesters ran. Events accumulated. But flat files on disk are not intelligence — they are raw material. David built a trio of reporting screens that turn the corpus into something you can actually read: a kanban, a dashboard, and an inventory. This is what it took, what each screen answers, and what the data revealed once it became visible.
work-state: The Pattern Turns Inward
project-state runs a project. dot Emporium runs a storefront. work-state runs a person. Same substrate, same skill suite shape — but the unit being measured is one human's contribution across an entire portfolio of projects.
dot Emporium: The Pattern Takes a Left Turn
The state pattern behind project-state has been converted into a full ecommerce workflow — intake, grading, pricing research, listing, and publishing to scsiwyg. dot Emporium is what happens when the pattern meets a vintage goods storefront.
The Toolkit: .project-state, Now Yours
project-state v2.0 is published. 19 skills, 5 compliance packs, 160KB zip. The thing we've been building in public is now a thing you can download.
Baseline Reports — project-state v2.0
Five baseline snapshots establishing the starting position for project-state v2.0: milestones, risk register, roadmap timeline, reporting matrix, and project identity.
New: Styled .docx + .xlsx Baseline Report Bundles
project-state v2.0.1 adds a 19th skill — project-doc-suite-generator — that renders professional Office documents from your project substrate. Tracker workbooks, risk registers, milestone specs, and more.
project-state is built to be live
project-state isn't built for capture — it's built to be live. The orchestrator reads the calendar, checks milestones, and generates reports automatically. Reporting becomes a byproduct, not a task.
Recipe: Financial modelling and calculator construction with project-state
How to use project-state to manage a financial modelling or calculator construction engagement — assumption decision logs, version milestones, scope change management, and IP tracking.
Recipe: Data analysis with project-state
How to adapt project-state for a data analysis engagement — phase presets, analytical milestones, decision traceability, scope change management, and stakeholder-appropriate reporting.
Recipe: Project planning with project-state
A step-by-step recipe for running a project from kickoff to closeout using project-state — scaffolding, milestones, phase gates, the reporting matrix, and the weekly orchestrator brief.
Why project-state: extensive, extensible, and built for any kind of work
project-state ships with 18 skills, 5 compliance packs, and a reporting matrix that generalizes to any type of multi-stakeholder work — from software delivery to research, consulting, and beyond.
How project-state came to be
project-state didn't start as a project management system. It started as a blog platform — and the state pattern that emerged from building scsiwyg kept generalizing until it became something much bigger.