project-state is built to be live
April 28, 2026orchestratorautomationreporting-matrixbackground-agentsproactive
# project-state is built to be live
Most project management systems are built for capture. You go to them to record what happened. You query them when you need to know something. They're inert until you poke them.
project-state is built differently. It's built to be **live** — to watch the calendar, read the state, and surface what needs to happen *before you ask*. The system knows what's due, what's approaching, what's overdue, and who needs to know. It acts on this continuously, not when prompted.
Here's how that works.
## The reporting matrix is the heartbeat
Every entry in `.project-state/reporting-matrix.yaml` is a scheduled commitment:
```yaml
entries:
- stakeholder_group: engineering_team
cadence: weekly
day: tuesday
format: slack_message
surface: slack
generator: project-status-reporter
- stakeholder_group: client
cadence: biweekly
format: email_draft
surface: gmail
generator: project-funder-reporting
- stakeholder_group: board
cadence: monthly
day: first-monday
format: email_draft
surface: gmail
generator: project-funder-reporting
```
These aren't reminders. They're dispatch instructions. When the orchestrator runs, it reads the matrix, checks the calendar, and determines what needs to be generated *today*. The status reporter gets called. The email draft gets created. The Slack message goes out. All without you typing anything.
This is what separates a project operating on project-state from one that isn't: **reporting becomes a byproduct of the system's existence, not a task you have to do.**
## The orchestrator: calendar-aware and context-loaded
```
ask claude: "what should I do this week?"
```
This is the invocation, but the orchestrator does the work. It pulls:
- **Calendar events** — what meetings are scheduled this week? Which of those are project-review meetings that need agendas generated?
- **Reporting matrix** — what reports are due this week? Any that were due last week and weren't generated?
- **Milestone status** — what's overdue? What's within 7 days of due with less than 80% completion? What's newly blocked?
- **Activity log recency** — what's the last logged activity on each workstream? Any workstreams that haven't had an update in over 10 days?
- **Open change requests** — any pending approvals that are aging?
- **Open action items** — from the last meeting notes, what was assigned and what's not yet closed?
It synthesizes these into a prioritized brief. Not a list of everything — a prioritized read of what actually needs attention today and this week.
## Background agents: the system checks on itself
The scheduling subsystem allows project-state to run headless — without you needing to be present to invoke it. Background agents are scheduled tasks that run at configured intervals:
```yaml
schedule:
- agent: weekly-orchestration
cron: "0 8 * * MON" # Every Monday at 8am
task: "run the weekly orchestrator brief and post to Slack"
- agent: milestone-watchdog
cron: "0 9 * * *" # Every morning at 9am
task: "check for milestones overdue or within 3 days, alert if status hasn't been updated"
- agent: report-generator
cron: "0 7 * * TUE" # Every Tuesday at 7am
task: "generate weekly status report and create Gmail draft for review"
```
With background agents configured, the system doesn't wait for you. It checks. It generates. It alerts. You review and approve — but you're not the one driving the cadence.
This is a qualitative shift in how projects run. Instead of the Project Lead manually assembling status reports every Tuesday morning and checking milestone spreadsheets every Friday, the system does the assembly and surfaces only the exceptions that need human judgment.
## What gets surfaced automatically
**Status reports** — generated on cadence from the reporting matrix. The status reporter reads the activity log, milestone progress, and recent decisions. It knows what happened since the last report because the logs are timestamped. The draft is created and waiting for your review before 8am on Tuesday.
**Meeting agendas** — generated 24–48 hours before a scheduled review meeting. The review-meeting skill reads the last meeting's follow-up actions, the current milestone status, and any change requests awaiting discussion. It produces an agenda, not a blank template.
**Milestone alerts** — when a milestone is within three days of due and hasn't been updated recently, or when a milestone flips to `at-risk`, the notifier sends an alert. You're not surprised by a deadline you missed — you're warned with enough lead time to act.
**Overdue change requests** — when a change request has been pending approval for more than [n] days (configurable per pack), the system surfaces it in the weekly brief and sends a reminder.
**Lessons learned prompts** — at configured intervals (typically every two weeks), the system prompts for a lessons-learned entry. Not at closeout when everything is a blur — continuously, while the experience is fresh.
## The activity log is the source of truth for everything
The system's ability to be proactive depends on the activity log being current. The activity log at `.project-state/activity-log.jsonl` is an append-only timestamped record of everything that happens on the project:
- Milestone updates
- Decision records
- Meeting outcomes
- Change register entries
- Document promotions
- IP disclosures
- Phase transitions
Whenever you update a milestone, log a decision, or record a meeting outcome, an entry goes into the activity log automatically. The status reporter reads back from the last report date. The orchestrator reads it to assess workstream health. The archive skill reads it to produce the closeout summary.
This is why the system knows what happened since the last report without you summarizing it. It was watching the whole time.
## The discipline: review, not author
The operating principle for project-state is **review, not author**. You don't write status reports. You review and approve the ones the system generates. You don't build meeting agendas. You review and adjust the ones the system assembled. You don't track down what's overdue. The system tells you.
This is a meaningful shift in how a Project Lead spends their time. Instead of 40% of the week on reporting overhead, you spend 40% of the week on the things that require human judgment: stakeholder relationships, difficult decisions, unblocking the team, managing risk.
The system handles the rest.
## Surfaces: where it shows up
project-state routes to where the stakeholders already are:
- **Slack** — team status updates, milestone alerts, weekly brief summaries
- **Gmail** — formal stakeholder reports as drafts (you review before sending)
- **Google Calendar** — meeting records, upcoming review meetings flagged for agenda generation
- **scsiwyg** — project blog posts for public-facing progress
- **Static website** — via `project-website-publisher`, a stable URL for reference documents
Nothing goes out unreviewed. Drafts are created; humans approve. But the creation happens automatically, at the right time, with the right content, for the right audience.
## Getting there
A project running on project-state at full automation takes about two weeks to dial in:
**Week 1:** Scaffold, configure the reporting matrix, enter milestones, wire surfaces. The orchestrator runs manually while you're verifying the outputs are right.
**Week 2:** Enable background agents for report generation. Start getting Tuesday morning drafts waiting for your review before you've had coffee.
**Week 3+:** The system is live. Your Monday brief is waiting. Your status reports are waiting. Your milestone alerts come in before the deadline, not after. You spend your time on the project, not the management of the project.
That's the goal. project-state is built to get you there.