Recipe: Project planning with project-state
April 28, 2026recipeproject-planningtutorialmilestonesreporting-matrix
# Recipe: Project planning with project-state
This is a step-by-step guide for using project-state to run a project from kickoff to closeout. It assumes you have the 18 skills installed and Claude available in your IDE or via Cursor/Cowork.
## What you'll end up with
- A `.project-state/` directory on your shared drive with a live project manifest
- A seeded reporting matrix encoding who gets what, when, on which surface
- Milestone records with progress tracking
- Phase gates that tell you when you're allowed to move forward
- An agent that can tell you "what do I do this week" and be right
## Step 1: Scaffold the project
```
ask claude: "scaffold a new v2 project"
```
The scaffolder walks you through an interactive setup:
- **Project identity** — name, kind (grant / client / internal / research), start date, end date, one-liner
- **Stakeholders** — organizations, contacts, roles. Be thorough here; the reporting matrix is seeded from this.
- **Pack selection** — choose the compliance pack(s) that match your project type. If you're running an agile software project, `agile-default`. Client engagement: `client-services`. If nothing fits, choose the closest and tune it.
- **Phase preset** — select from grant, agile, waterfall, client-engagement, or open-source. Or describe your phases and the scaffolder will build them.
- **Surface configuration** — which surfaces are wired: Slack channel, Gmail account, Google Calendar, blog, website.
After setup, the scaffolder seeds the reporting matrix from your loaded packs. This is the single most important step in the whole system.
## Step 2: Review the reporting matrix
```
ask claude: "show the reporting matrix"
```
You'll see a YAML structure like:
```yaml
entries:
- stakeholder_group: engineering_team
report_type: weekly_status
cadence: weekly
day: tuesday
format: slack_message
surface: slack
channel: "#project-updates"
generator: project-status-reporter
- stakeholder_group: client
report_type: progress_report
cadence: biweekly
format: email_draft
surface: gmail
template: client-services/progress-report.md
generator: project-funder-reporting
```
Edit this file directly or ask Claude to adjust it. This is the contract between the project and its stakeholders. Every entry becomes an automatic generation task.
## Step 3: Enter your milestones
```
ask claude: "add milestone: [name], due [date], assigned to [person/team], description [what done looks like]"
```
Or in bulk:
```
ask claude: "I need to set up milestones for this project. Here are the deliverables: [paste SOW/grant agreement section]"
```
The milestone manager extracts, structures, and stores them. Each milestone gets:
- Unique ID
- Name and description
- Due date
- Owner
- `percent_complete` (0–100)
- `technical_progress` note (a human-readable description of current state)
- Status: `not-started`, `in-progress`, `at-risk`, `complete`, `blocked`
Update them as work progresses:
```
ask claude: "update milestone [id]: 60% complete, technical progress note: [what's done]"
```
## Step 4: Operate the phase gate
```
ask claude: "what phase are we in?"
```
The phase gate reads the current phase from the manifest and checks whether gate criteria are met. Gate criteria come from your phase preset and pack overrides.
For example, in a waterfall project, gate criteria for moving from Discovery to Design might include:
- Requirements document approved (status: `approved` in document index)
- Kickoff meeting completed (meeting record exists with outcome: `completed`)
- All stakeholders onboarded (onboarding records exist for all stakeholder contacts)
When criteria are met:
```
ask claude: "advance the phase"
```
The phase gate records the transition with timestamp and approver. The new phase's gate criteria become active.
## Step 5: Let the orchestrator drive the week
```
ask claude: "what should I do this week?"
```
The orchestrator reads:
- The reporting matrix (what's due this week?)
- The calendar (what meetings are scheduled?)
- The milestone list (what's overdue? what's approaching?)
- The activity log (what's happened recently that needs follow-up?)
It produces a prioritized weekly brief:
1. Reports due: "Tuesday status update for engineering team (Slack)"
2. Meetings: "Steering Committee on Thursday — agenda not yet generated"
3. Milestones: "M3 due in 5 days, currently at 40% — needs update or risk flag"
4. Follow-ups: "Change request CR-004 has been pending approval for 8 days"
This is the daily driver. Run it every Monday morning.
## Step 6: Document decisions and changes
```
ask claude: "log a decision: we're switching from vendor A to vendor B for the data pipeline, rationale: [reason], decided by: [name]"
```
```
ask claude: "log a change: we're adding a new workstream for [X], classify it"
```
The change register classifies the change as material or non-material using the thresholds your pack defines. Material changes trigger an approval workflow entry. Non-material changes are logged and noted in the next status report.
## Step 7: Generate reports
```
ask claude: "generate the weekly status report"
ask claude: "draft the [stakeholder] progress report"
ask claude: "prepare the agenda for Thursday's Steering Committee"
```
All of these read from `.project-state/` — milestones, decisions, changes, activity log — and produce the right output for the right audience. The status reporter knows what's happened since the last report because the activity log is append-only and timestamped.
## Step 8: Close out
```
ask claude: "start project closeout"
```
The archive skill:
- Confirms all milestones are marked complete or explicitly closed
- Confirms the lessons-learned log has been reviewed
- Produces a closeout summary document
- Archives the `.project-state/` directory into a read-only snapshot
- Runs any pack-specific closeout items (e.g., final funder report, IP disclosure audit)
## Tips for getting the most out of it
**Keep the milestone notes current.** The `technical_progress` field on each milestone is where the real project intelligence lives. Two sentences per milestone per week is enough. Status reports basically write themselves from these notes.
**Log decisions in real time.** Every time a material decision is made in a meeting, log it before closing the conversation. "Ask Claude to log this decision" takes ten seconds and saves hours of reconstruction later.
**Trust the orchestrator.** After the first two or three weeks, the orchestrator's weekly brief becomes the most useful thing in the system. Let it drive what you do, not the other way around.
**Tune the reporting matrix in the first sprint.** The pack seeds reasonable defaults but your actual stakeholders will have opinions. Adjust cadence and format in the first two weeks while it's still cheap to change.