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:

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.