project-state User Guide
#documentation#user-guide#getting-started#v3.2
What is project-state?
project-state is an operational substrate that turns routine project reporting into a byproduct of normal work. Instead of assembling weekly reports, meeting packs, and funder claims by hand, you maintain state once — milestones, risks, decisions, documents — and the system generates everything else from it.
It runs as a Claude Code plugin with 30 skills, 7 compliance packs, and a local dashboard. The "database" is a directory of plain YAML, JSON, and markdown files on your shared drive. No infrastructure to deploy. No accounts to create.
The core principle: State is the source of truth. Reports are generated from state. When a report is wrong, you fix the state — not the report.
Part 1: Getting Started
Install
/plugin marketplace add github:atomic47/project-state
/plugin install project-state@atomic47
Or from a local zip:
/plugin install --local project-state-v3.zip
Once installed, all 30 /project-* slash commands are available in Claude Code.
Your first project
There are two ways to start:
| Path | When to use | Command |
|---|---|---|
| Quick scaffold | You know your pack, phase, and want to move fast | /project-scaffolder |
| Guided onboarding | First time, or you have documents to ingest | /project-onboarding |
We recommend guided onboarding for your first project. It takes 10–15 minutes and produces a far better-oriented substrate.
The onboarding experience
Onboarding runs nine chapters. Each builds on the last. You can go deep or stay shallow — the system tells you where gaps remain.
Onboarding Flow
┌─────────────────────────────────────────────────────────────┐
│ │
│ ── Chapter 0 of 9: Welcome ───────────────────────────── │
│ │
│ ████░░░░░░░░░░░░░░ 1/9 │
│ │
│ Welcome to project-state setup. This process will orient │
│ the system around your specific project so that every │
│ report, claim draft, and milestone update it produces is │
│ grounded in your actual context. │
│ │
│ The single most valuable thing you can do right now is │
│ share documents. If you have a proposal, an MPA, a SOW, │
│ a milestone schedule, or anything that describes what │
│ this project is — share it before we begin. │
│ │
│ > Do you have any documents to share now? │
│ │
└─────────────────────────────────────────────────────────────┘
The nine chapters:
| # | Chapter | What it collects | Time |
|---|---|---|---|
| 0 | Welcome | Documents — proposals, MPAs, SOWs, schedules | 2 min |
| 1 | Pack Selection | Which compliance packs to load (grant, client, board, agile, etc.) | 2 min |
| 2 | Project Identity | Name, funder, dates, budget, one-liner description | 2 min |
| 3 | Document Drop | Second invitation to share documents before deeper questions | 1 min |
| 4 | Stakeholder Mapping | Who receives outputs, their roles, communication preferences | 3 min |
| 5 | Milestone Capture | Deliverables, owners, dates, completion criteria | 5 min |
| 6 | Goals & Examples | What success looks like, example outputs to model, anti-patterns to avoid | 3 min |
| 7 | Gaps & Synthesis | Review what's captured, decide what to fill, leave, or synthesize | 2 min |
| 8 | Initialize | Pre-flight review and substrate creation | 1 min |
| 9 | Orientation Check | Quality assessment and suggested first actions | 1 min |
Pro tip: Drop documents first. If you share your governing document (MPA, SOW, grant agreement) in Chapter 0, the system extracts project identity, milestones, and stakeholders automatically. Chapters 2, 4, and 5 become confirmation passes — you verify what was found instead of typing it from scratch.
┌─────────────────────────────────────────────────────────────┐
│ │
│ ── Chapter 2 of 9: Project Identity ───────────────────── │
│ │
│ ██████████░░░░░░░░ 3/9 │
│ │
│ ┌─ Pre-filled from documents ────────────────────────────┐ │
│ │ │ │
│ │ Project name Volta Consortium [from MPA] │ │
│ │ Funder PIC / PCAIS Program [from MPA] │ │
│ │ Start date 2026-04-01 [from MPA] │ │
│ │ End date 2031-03-31 [from MPA] │ │
│ │ Budget $4,200,000 CAD [from MPA] │ │
│ │ │ │
│ │ Confirm or correct? │ │
│ └────────────────────────────────────────────────────────┘ │
│ │
│ One-liner (in your own words): │
│ > What is this project, in one or two sentences? │
│ │
└─────────────────────────────────────────────────────────────┘
What onboarding creates
After Chapter 8 confirms, the system writes:
project-state/
├── manifest.yaml project identity, consortium, surfaces
├── state.json current phase, health, counters
├── reporting-matrix.yaml who gets what report, when
├── milestones/
│ ├── M01-design-phase.yaml
│ ├── M02-prototype.yaml
│ └── ...
├── references/
│ ├── goals.md your words, unedited
│ ├── examples/
│ │ ├── good/ outputs to model
│ │ └── avoid/ anti-patterns
│ └── onboarding-intake.yaml audit trail
├── documents/
│ ├── inbox/ drop zone for new docs
│ ├── source-of-truth/ governing documents
│ └── index.yaml classification registry
├── logs/
│ └── activity.ndjson append-only audit log
└── kanban/ local dashboard (Next.js)
Orientation quality
At the end of onboarding, the system rates your setup honestly:
Orientation quality
───────────────────
Grounding: ██░ 2/3 governing document seen; proposal not provided
Goals: ███ 3/3 goals, positive examples, and anti-patterns captured
Stakeholders: █░░ 1/3 names captured; preferences not yet known
Overall: Good starting point. Outputs will improve as grounding increases.
Suggested next steps:
1. Add your proposal document to improve milestone extraction
2. Update M03 with percent_complete — it's currently at 0%
3. Run /project-orchestrator to see what's due this week
You can always improve orientation later with /project-onboarding re-orient.
Part 2: The Cowork Model
project-state is designed for cowork — humans and AI collaborating through a shared substrate. The system drafts; humans decide and send. This section describes the interaction patterns that make that work.
The review-not-author discipline
Every external artifact passes through human review before it leaves the system. This is an architectural constraint, not a setting you can disable.
The Review-Not-Author Flow
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ Update │ │ Generate │ │ Review │ │ Send │
│ state │────▶│ report │────▶│ draft │────▶│ (human) │
└──────────┘ └──────────┘ └──────────┘ └──────────┘
│ │ │ │
You update a System reads Draft appears You review,
milestone or state and in Gmail or adjust if
log a decision assembles it Slack queue needed, send
| Surface | Behavior | Why |
|---|---|---|
| Slack (team channels) | Auto-post allowed | Internal team; low risk |
| Gmail | Always draft. Never auto-sent. | External comms require human judgment |
| Google Calendar | Proposed holds | Recipient accepts or declines |
| Blog / Website | Draft with review window | Publication review may be required |
There is no auto-send for email. Ever. This is a compliance constraint for funder-governed projects. The system creates the draft; you press Send.
State wins, always
When a report disagrees with reality, the correct action is:
✗ Edit the report
✓ Fix the state, then regenerate the report
This keeps everything downstream consistent. Update a milestone from 40% to 60%, and that change automatically propagates to:
- The next weekly report
- The next steering committee pack
- The next quarterly claim
- The project website milestone tracker
- The kanban dashboard burndown chart
- The activity log
No parallel maintenance. One write, many surfaces.
The reporting matrix
The reporting matrix is the single data structure that converts normal project updates into scheduled stakeholder artifacts. It answers: who gets what report, at what cadence, in what format, on which surface, produced by which skill?
# reporting-matrix.yaml (excerpt)
entries:
- id: weekly-team-status
stakeholder_group: internal.team
cadence: { kind: weekly, day: monday }
format: md
surface: slack
generator: project-status-reporter
- id: quarterly-claim
stakeholder_group: funder.pic
cadence: { kind: quarterly, months: [4, 7, 10, 1], day: 20 }
format: xlsx
surface: gmail.draft
generator: project-funder-reporting
To add a new stakeholder, you edit the matrix — not the skills. The orchestrator reads this matrix on every tick and dispatches the right generator at the right time.
Part 3: Daily Workflows
The daily rhythm
Start your day with:
/project-orchestrator
The orchestrator checks everything and returns a prioritized action list:
┌─────────────────────────────────────────────────────────────┐
│ Daily Brief — 2026-05-28 │
│─────────────────────────────────────────────────────────────│
│ │
│ URGENT │
│ ● M05 is 3 days past planned_end — update status or │
│ extend date │
│ ● Q2 claim due in 12 days — run /project-funder-reporting │
│ │
│ THIS WEEK │
│ ○ Weekly report due Monday — /project-status-reporter │
│ ○ 4 documents in inbox/ awaiting classification │
│ │
│ ON DECK │
│ · SC meeting in 18 days — agenda generation in 4 days │
│ · M07 at 85% — check if deliverable is ready │
│ │
│ QUIET │
│ · No phase gate transitions pending │
│ · No uncommitted changes │
│ │
└─────────────────────────────────────────────────────────────┘
The orchestrator runs three named routines:
| Routine | When | What it does |
|---|---|---|
tick | Any time | Reads the reporting matrix; dispatches whatever is due today |
daily | Start of day | Harvests signals + classifies inbox + checks milestones + flags risks |
end-of-session | End of day | Proposes a git checkpoint, flags approaching deadlines, reminds to push |
Updating milestones
The most common daily action is updating milestone progress:
/project-milestone-manager update M03 percent_complete=60
Or conversationally: "Update M03 — we completed the prototype integration tests. Move to 60%."
The skill updates milestones/M03-slug.yaml:
# milestones/M03-prototype-integration.yaml
title: Prototype Integration
owner_org: Atomic 47
planned_end: 2026-09-30
percent_complete: 60 # ← updated
status: in_progress
technical_progress: |
Completed integration test suite for the core API.
All 47 endpoint contracts verified. Performance
benchmarks within 15% of target.
This write is logged to activity.ndjson and immediately visible in the kanban, the next weekly report, and every downstream surface.
Logging decisions and risks
/project-state decision "Chose PostgreSQL over MongoDB for the audit trail"
/project-state risk "Vendor API rate limits may block the data migration"
Decisions become decisions/YYYY-MM-DD-slug.yaml. Risks become risks/R-NN-slug.yaml. Both feed into weekly reports and steering committee packs automatically.
End-of-session checkpoint
At the end of your work session:
/project-orchestrator end-of-session
┌─────────────────────────────────────────────────────────────┐
│ End of Session — 2026-05-28 17:45 │
│─────────────────────────────────────────────────────────────│
│ │
│ Activity since last checkpoint: │
│ • M03 updated: 45% → 60% │
│ • Decision logged: PostgreSQL for audit trail │
│ • 2 documents classified │
│ │
│ Suggested commit message: │
│ "Update M03 to 60%; log PostgreSQL decision; classify │
│ 2 inbox docs" │
│ │
│ Approaching deadlines: │
│ • Q2 claim due in 12 days │
│ • Weekly report due Monday │
│ │
│ > Run /project-git checkpoint to commit? │
│ │
└─────────────────────────────────────────────────────────────┘
The system never auto-commits. It suggests; you confirm.
Part 4: Weekly Reporting
Generating the weekly report
/project-status-reporter weekly
The skill reads the current state — milestones, risks, decisions, activity log — and assembles a report. You don't write it; you review it.
Weekly Report Flow
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Milestones │ │ Risks │ │ Decisions │
│ M01–M13 │ │ R-01–R-05 │ │ this week │
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘
│ │ │
└───────────┬───────┘───────────────────┘
▼
┌─────────────────┐
│ status-reporter │ reads state,
│ generates │ assembles report
└────────┬────────┘
│
┌─────────┴─────────┐
▼ ▼
┌──────────────┐ ┌──────────────┐
│ Slack post │ │ Gmail draft │
│ (auto-post) │ │ (you send) │
└──────────────┘ └──────────────┘
What the report contains
The weekly report is generated from state, not written from memory. It includes:
- Milestone progress — percent_complete changes since last report, at-risk flags
- Key decisions — any decisions logged this week
- Risks — new or escalated risks
- Activity summary — tail of the activity log since last report
- Upcoming deadlines — next claim, next SC meeting, milestone due dates
- Blockers — anything flagged as blocked
Reviewing and sending
The report lands as:
- A Slack message in your team channel (auto-posted for internal channels)
- A Gmail draft for any external recipients (you open Gmail, review, press Send)
- An outbox card in the kanban queue view for tracking
Part 5: Document Lifecycle
The document flow
Documents move through a clear pipeline:
Document Lifecycle
┌─────────┐ ┌────────────┐ ┌───────────┐ ┌───────────┐
│ inbox/ │──▶│ classify │──▶│ working/ │──▶│ published/ │
│ │ │ & index │ │ │ │ │
└─────────┘ └────────────┘ └───────────┘ └───────────┘
▲ │
│ ▼
Drop files source-of-truth/
here or (governing docs)
/project-harvester
Dropping documents
Put any file in documents/inbox/:
- Proposals, SOWs, MPAs
- Meeting minutes, correspondence
- Technical reports, deliverables
- Anything the project needs to know about
Then classify:
/project-document-curator
The curator asks five questions per document:
- What kind? — proposal, milestone-schedule, approval-letter, meeting-minutes, etc.
- What phase? — which lifecycle phase does it belong to?
- Source of truth? — is this the governing version of this document?
- Supersedes? — does it replace an older document?
- State impact? — does it change anything the substrate should know?
Harvesting external signals
The harvester pulls project-relevant content from your connected surfaces:
/project-harvester
It scans:
- Slack — messages in configured project channels
- Gmail — threads involving configured contacts
- Google Docs — shared documents mentioning the project
- scsiwyg — blog posts tagged with the project
Harvested items land in documents/inbox/ as classified markdown files. The harvester tracks per-surface cursors, so it never fetches the same item twice.
Part 6: The Kanban Dashboard
Starting the dashboard
/project-kanban
This launches a local Next.js app at http://localhost:3355. It reads the substrate directly on every page load — no sync step needed.
Five views
┌─────────────────────────────────────────────────────────────┐
│ project-state │
│ ┌────────┬───────────┬───────────┬─────────┬─────────────┐ │
│ │ Kanban │ Dashboard │ Inventory │ Reports │ Milestone ▾ │ │
│ └────────┴───────────┴───────────┴─────────┴─────────────┘ │
└─────────────────────────────────────────────────────────────┘
Kanban — Milestones as cards in status columns.
Planned In Progress At Risk Complete
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ M06 │ │ M03 60% │ │ M05 40% │ │ M01 100% │
│ Data │ │ Proto │ │ Testing │ │ Design │
│ Pipeline │ │ Integr. │ │ Suite │ │ Phase │
│ │ │ [SL][GM] │ │ ⚠ 3d late│ │ ✓ │
└──────────┘ ├──────────┤ └──────────┘ ├──────────┤
│ M04 25% │ │ M02 100% │
│ API │ │ Arch. │
│ Design │ │ Review │
└──────────┘ └──────────┘
Dashboard — Activity timeline, milestone burndown, risk heatmap. See momentum at a glance.
Inventory — Searchable tables of all milestones, risks, decisions, and documents. Inline markdown previewer.
Reports — View generated reports in-browser. Download baseline bundles (xlsx, docx) for offline distribution.
Milestone detail — Full card per milestone: deliverables, technical progress narrative, owner, planned vs. actual dates, at-risk reason, harvested signals, activity tail.
Part 7: Stakeholder Reporting
How reporting works
You don't write reports. You maintain state. The reporting matrix schedules generation. The orchestrator dispatches skills. Artifacts land for your review.
Reporting Pipeline
┌──────────────────┐
│ reporting-matrix │ "weekly report due Monday"
│ .yaml │ "quarterly claim due Jul 20"
└────────┬─────────┘ "SC pack due in 14 days"
│
▼
┌──────────────────┐
│ orchestrator │ reads matrix, dispatches
└────────┬─────────┘ the right generator
│
┌─────┼──────┐
▼ ▼ ▼
┌──────┐┌────┐┌──────┐
│weekly││SC ││claim │ generators read state,
│report││pack││draft │ produce artifacts
└──┬───┘└──┬─┘└──┬───┘
│ │ │
▼ ▼ ▼
┌──────────────────┐
│ notifier │ routes to surfaces
└────────┬─────────┘
│
┌─────┼──────┐
▼ ▼ ▼
Slack Gmail Calendar
post draft hold
Steering committee meetings
/project-review-meeting sc
The review meeting skill manages the full lifecycle:
- 14 days before — generate agenda from current state
- 7 days before — assemble pre-read pack (milestone summary, risks, financials)
- Day of — capture minutes and action items
- After — distribute minutes, track action items to completion
Quarterly claims
/project-funder-reporting claim Q2
The skill assembles:
- Milestone percent_complete at quarter-end
- Technical progress narratives from each milestone
- Financial summary (from Finance Rep input)
- Cover email (as Gmail draft)
You review the claim package, verify the numbers, then send.
Part 8: Compliance & Governance
Phase gates
Projects move through lifecycle phases. Each transition is gated:
Lifecycle Phases
LOI ──▶ Approval ──▶ Planning ──▶ Execution ──▶ Closeout ──▶ Archive
│ │
▼ ▼
Gate check: Gate check:
• MPA signed? • All M01–M13
• Budget approved? at 100%?
• Team confirmed? • Final report
submitted?
/project-phase-gate transition execution
The system checks all gate criteria before allowing the transition. If items are missing, it tells you what's needed.
Change management
/project-change-register "Extend M05 deadline by 30 days"
The system classifies changes as material (requires funder approval) or non-material (log and proceed). Material changes trigger a change order draft for submission.
IP tracking
/project-ip-tracker disclose "Novel data fusion algorithm"
IP disclosures are routed to the recipients configured by your compliance pack — your tech transfer office, funder, or legal team.
Lessons learned
/project-lessons capture "Vendor onboarding took 3x longer than planned"
Lessons accumulate throughout the project and are synthesized into a closeout summary at project end.
Part 9: Compliance Packs
Packs configure behavior — they don't change code. Choose the packs that match your project's stakeholder relationships.
Available packs
| Pack | For | What it configures |
|---|---|---|
| pic-pcais | Canadian consortium grants (PIC program) | SC meeting agenda, claim format, IP recipients, phase gates |
| grant-canada | Canadian grant submissions (19 programs) | Compliance gates, narrative templates, playbooks |
| sred-canada | SR&ED tax credits | TU/EX/ADV evidence, T661 narrative, CRA-aligned gates |
| client-services | Paying customers | QBR cadence, invoice templates, client comms review |
| board-investor | Board governance / VC-backed | Board meeting cadence, investor updates, board packs |
| agile-default | Scrum / Kanban teams | Sprint cadence, retros, backlog linking |
| open-source-community | Community projects | RFC review, community calls, contributor onboarding |
Packs are additive
A government-funded project with a client and SR&ED obligations loads three packs simultaneously:
packs_loaded:
- pic-pcais # funder reporting
- client-services # client QBRs
- sred-canada # SR&ED evidence capture
Each pack configures its own slice of behavior. They don't conflict.
Authoring a custom pack
If your funder or compliance context isn't covered, author a new pack in about an hour. No code — just YAML profiles:
packs/my-new-pack/
├── manifest.yaml pack identity and metadata
├── profiles/
│ ├── phase-gate.yaml gate criteria per phase
│ ├── review-meeting.yaml meeting agenda templates
│ ├── funder-reporting.yaml report format and cadence
│ ├── external-comms.yaml publication review windows
│ ├── ip-tracker.yaml disclosure recipients
│ └── archive.yaml closeout checklist
├── templates/ optional document templates
└── reporting-matrix-defaults.yaml default matrix entries
See the Pack Authoring Guide for the full specification.
Part 10: Collaboration & Concurrency
Multiple people, one substrate
project-state is designed for teams sharing a drive or git repo. Three mechanisms prevent conflicts:
File-per-entity — Each milestone, decision, and risk is its own YAML file. Two people editing different milestones touch different files. No conflicts.
Person A edits: Person B edits:
milestones/M03-proto.yaml milestones/M07-deploy.yaml
│ │
└──────── no conflict ─────────┘
Advisory lockfiles — Monolithic files (manifest.yaml, state.json) use .lock files with a 300-second TTL. Short-lived, automatic, no deadlocks.
Append-only logs — activity.ndjson is never rewritten. Two people logging events on the same day? Git merges them with merge=union — no conflict, ever.
Git workflow
/project-git checkpoint # commit with auto-generated message
/project-git push # share with team
/project-git sync # pull + rebase
/project-git status # see what's changed
The .gitattributes file is set up during scaffolding with merge=union on log files, so append-only logs merge automatically.
Shared drive workflow
If your team uses a shared drive (Google Drive, OneDrive, Dropbox) instead of git, everything still works. The file-per-entity design and advisory locks handle concurrency. You just skip the git commands.
Part 11: Grant Submissions
The two-facility model
Grant submissions use a parallel facility — grant-state/ — that operates independently from the execution project-state/:
your-project/
├── grant-state/ pre-award: submission work
│ ├── manifest.yaml
│ ├── sections/ narrative drafts
│ ├── gates/ compliance gates
│ └── budget/ budget scaffold
│
└── project-state/ post-award: execution work
├── manifest.yaml
├── milestones/
└── ...
Submission workflow
/grant-scaffolder
The scaffolder matches your target program against 19 Canadian playbooks and seeds the facility with program-specific templates.
/grant-ingestor triage # classify program documents
/grant-ingestor strategy # program fit, section coverage, gate map
/grant-ingestor verdict # eligibility assessment with confidence
Award handoff
When you receive the award, the scaffolder runs a three-step wizard:
- Freeze
grant-state/— submission becomes a provenance record - Spawn
project-state/— with consortium, IP rationale, and milestones carried forward - Ready — execution project starts with six weeks of submission context already grounded
No rework. The proposal milestones become the execution milestones. The people you mapped during submission are already in the consortium.
Part 12: Surface Modes
project-state adapts its presentation to where you're working.
Claude Code (CLI)
In the terminal, you see markdown with progress lines, tables, and numbered prompts.
Claude Coworker (claude.ai)
On claude.ai, the same content renders as interactive HTML artifacts with styled cards, progress bars, and action buttons — all within the chat window.
Same substrate, different surface
Both modes produce identical substrate output. The difference is only visual. You can start onboarding in Coworker and continue daily operations in Claude Code — or vice versa.
Quick Reference
Essential commands
| Command | What it does |
|---|---|
/project-orchestrator | "What should I do today?" — prioritized action list |
/project-milestone-manager update M03 percent_complete=60 | Update a milestone |
/project-status-reporter weekly | Generate the weekly report |
/project-document-curator | Classify inbox documents |
/project-harvester | Pull signals from Slack, Gmail, GDocs |
/project-kanban | Open the local dashboard at localhost |
/project-git checkpoint | Commit with auto-generated message |
/project-funder-reporting claim Q2 | Generate a quarterly claim |
/project-review-meeting sc | Steering committee lifecycle |
/project-phase-gate transition <phase> | Advance lifecycle phase |
/project-onboarding | Full guided onboarding (first time) |
/project-onboarding re-orient | Update orientation (any time) |
/project-lessons capture "..." | Log a lesson learned |
The daily loop
Morning During the day End of day
─────── ────────────── ──────────
/project-orchestrator Update milestones /project-orchestrator
│ Log decisions end-of-session
▼ Classify docs │
Review action list Respond to flags ▼
Handle urgent items Review checkpoint
Delegate or defer /project-git checkpoint
Where things live
| What | Path |
|---|---|
| Project identity | project-state/manifest.yaml |
| Current phase & health | project-state/state.json |
| Reporting schedule | project-state/reporting-matrix.yaml |
| Milestones | project-state/milestones/M<NN>-<slug>.yaml |
| Decisions | project-state/decisions/YYYY-MM-DD-<slug>.yaml |
| Risks | project-state/risks/R-<NN>-<slug>.yaml |
| Documents | project-state/documents/ (inbox → working → published) |
| Activity log | project-state/logs/activity.ndjson (append-only) |
| Generated reports | project-state/reports/ |
| Your goals & examples | project-state/references/ |
Principles to remember
- State is the source of truth. Don't edit reports — update state, regenerate.
- Review, don't author. The system drafts; you decide and send.
- Documents accelerate everything. Drop them early, drop them often.
- Gmail is always a draft. No exceptions. You press Send.
- Packs configure, code doesn't. New funder? Author a pack, not a fork.
- Logs are append-only. Corrections are new entries, never rewrites.
- Orientation improves over time. Add documents and examples whenever you have them.
project-state v3.2 — Built by Atomic 47 Questions? david@atomic47.co