Why project-state: extensive, extensible, and built for any kind of work

Most project management tools make a bet on a project shape. Jira bets you run sprints and ship software. Asana bets you have tasks and assignees. Notion bets you want flexible pages. They work well until your project doesn't fit the assumed shape.

project-state makes a different bet: the thing that generalizes across all project types is the reporting problem, not the work itself. Every project, regardless of what it's doing, has stakeholders who need to know things, at regular intervals, in specific formats, on specific surfaces. Solve that generically and you have something that works for any kind of work.

Here's how it's designed to do that.

The three-layer architecture

┌─────────────────────────────────────────────────────────────┐
│  SURFACES — Slack · Gmail · Calendar · Blog · Web           │
├─────────────────────────────────────────────────────────────┤
│  SKILLS — 18 project-* skills                               │
│           ┌──── reads behavior from ────┐                   │
│           ▼                              ▼                   │
│  PACKS — compliance profiles per project type               │
│           ┌──── seeds entries into ────┐                    │
│           ▼                             ▼                    │
│  REPORTING MATRIX — who gets what, when, where              │
├─────────────────────────────────────────────────────────────┤
│  SUBSTRATE — .project-state/ on shared drive                │
└─────────────────────────────────────────────────────────────┘

The substrate is dumb files. YAML documents, append-only logs, Markdown status reports. Anything can read them: agents, scripts, humans with a text editor. There is no database. There is no server. There is no lock-in.

The skills are the operations layer. Eighteen project-* skills cover the full lifecycle: scaffold, phase-gate, milestone tracking, status reporting, meeting management, funder reporting, change control, IP tracking, onboarding, closeout. Each skill reads and writes the substrate. Each skill is a Markdown file — a plain text instruction set the agent follows.

The packs are where project-type-specific knowledge lives. A pack defines: what your stakeholders look like, what reports they need, what cadence, what surface. Load the agile-default pack and the reporting matrix gets seeded with sprint reviews and weekly standups. Load board-investor and it gets seeded with board decks and investor updates. Load both if you're a startup that also runs sprints.

The reporting matrix is the key. It's a YAML file at .project-state/reporting-matrix.yaml that answers: for each stakeholder group, what do they need to know, how often, in what format, on which surface? The orchestrator reads this and dispatches accordingly. You configure it once; the system executes it repeatedly.

The 18 skills in plain language

Rather than a table of names, here's what the system actually does for you:

It remembers where you are. project-state (the memory skill) reads and writes every entity. Milestones, documents, decisions, activity logs, change records, IP disclosures — all persisted across sessions so the agent can orient in any conversation without you re-explaining.

It runs the project lifecycle. project-scaffolder initializes a new project in one shot. project-phase-gate tracks phases — you define what your phases are called and what gates them. project-milestone-manager handles CRUD on milestones with completion percentages and technical progress notes.

It generates the deliverables. project-status-reporter produces status updates in the right format for the right audience. project-funder-reporting generates the formal stakeholder-bound recurring reports your compliance pack defines. project-review-meeting handles meeting lifecycle: agenda generation, notes, follow-up actions.

It routes to surfaces. project-notifier sends to Slack, Gmail (as drafts), or Calendar. project-blog-publisher pushes to scsiwyg. project-website-publisher maintains a static project website with stable URLs. The reporting matrix tells the orchestrator which surface gets which report.

It handles the edge cases. project-change-register classifies material vs non-material changes. project-ip-tracker files IP disclosures. project-external-comms runs the review pipeline before anything goes public. project-lessons captures lessons learned continuously and writes the closeout summary.

Why compliance packs change everything

The generic core would be useful but friction-heavy if you had to configure everything by hand for every project. Packs remove that friction by encoding the conventions for a project type.

The pic-pcais pack (production) encodes the exact reporting requirements for a PIC-funded Canadian innovation consortium: Steering Committee cadence, quarterly claim packages, IP disclosure recipients, change approval thresholds, all of it. Load the pack and the reporting matrix is seeded correctly before you write a single line of custom YAML.

The four starter packs do the same for client services, board-backed startups, agile engineering teams, and open-source communities. They're starters, not finished products — the expectation is you'll tune them for your specific instance.

Authoring a new pack is covered in docs/PACK-AUTHORING.md. The format is straightforward. If you run projects in a specific regulatory environment — healthcare, aviation, oil and gas, government contracting — you encode those requirements once in a pack and every project inherits them.

From software delivery to knowledge work

Software teams using the agile-default pack get sprint tracking, velocity, retrospective structure, and engineering-appropriate milestone granularity.

Consulting engagements using client-services get SOW-aligned deliverable tracking, client-specific reporting cadence, and an external comms review pipeline before anything goes to the client.

Research projects get phase presets built around discovery, experimentation, and dissemination. Knowledge workers get document classification, a change register for scope shifts, and lessons-learned capture built into the workflow rather than bolted on at the end.

The substrate is the same in every case. The skills are the same. What changes is the pack — and the pack is just a YAML profile plus a few templates.

What it doesn't try to do

project-state doesn't manage tasks. It doesn't replace your issue tracker. It doesn't give you Gantt charts or dependency graphs.

It manages the one thing every other tool punts on: the structured intelligence layer that lets an AI agent understand where the project stands and produce accurate, timely outputs without asking you to re-explain everything in every session.

That's the gap it fills. That's why it's built the way it is.