project-status
Maintain machine-readable project status snapshots for instant context at the start of any session, eliminating the need to re-derive project state from package.json, Cargo.toml, or git history. A lig
SKILL.mdskills/project-status/SKILL.md
GitHubProject Status — Instant Context
A lightweight convention for capturing project state in a single PROJECT.md file that an AI can read in one pass, eliminating the need for re-exploration on every session.
Format
Every project should have a PROJECT.md in its root directory. The format uses YAML frontmatter for machine-readability, followed by a brief prose summary.
---
name: [project-name]
status: active # active | paused | archived | completed
phase: mvp # bootstrap | mvp | feature | polish | maintenance
version: 0.1.0 # mirrors package.json/Cargo.toml
last_session: 2026-03-19
tech_stack:
frontend: [React 19, TypeScript, Vite, Tailwind]
backend: [Rust, Tauri 2, tokio, reqwest]
packaging: [Tauri bundler, macOS app]
build: passing # passing | failing | unknown
blockers: [] # empty = clear; list blockers only when present
focus: # current work in progress or next priority
- Feature X
- Feature Y
---
## What This Project Is
One-paragraph description of the project's purpose.
## Current Status
Brief status summary (2-3 sentences).
## Key Architecture
- `src/` — frontend
- `src-tauri/` — backend
## Open Questions
- Question 1
- Question 2
When to Read PROJECT.md
Before exploring any project for the first time in a session, check for and read PROJECT.md in the project root. This is the single source of truth for project state — do not re-derive it from package.json, Cargo.toml, or git history unless the file is missing or stale.
Session Workflow (Session Start)
- Read
medium-term.mdat~/.claude/memory/medium-term.md - Identify the current project and its stacks from the Active Projects table
- Read
{project}/PROJECT.md - Sync lessons for all stacks: run
/lessons-sync(all stacks)
When to Update PROJECT.md
At Session End
- Update
last_activeinmedium-term.mdfor the current project - Sync lessons: for each stack in the project, diff root
~/.claude/memory/lessons/{stack}.mdagainst{project}/memory/lessons/{stack}.md, append new entries from root - Append session log to
{project}/memory/sessions/YYYY-MM-DD.md - Update
last_sessionin{project}/PROJECT.mdto today's date - Update
focusif work shifted from what was listed - Update
statusorphaseonly if a genuine milestone was hit - Update
blockersonly if something genuinely blocked progress
At Session Start
- Read PROJECT.md first
- Use
focusto immediately understand what to work on - If
last_sessionis stale (more than a few days ago), ask if the file needs updating
Never Update For
- Package version bumps (those live in package.json/Cargo.toml)
- Individual commits or minor code changes
- Git history (git log is the source of truth for activity)
Derived vs. Human-Maintained Fields
| Field | Source | Update Frequency |
|---|---|---|
name |
human | only on rename |
status |
human | on phase change |
phase |
human | on milestone |
version |
package.json / Cargo.toml | on release |
last_session |
human (session end) | every session |
tech_stack |
package.json / Cargo.toml | on stack change |
build |
human (after build) | after builds |
blockers |
human | only when present |
focus |
human | at session end |
Adding a New Project
When a new project is created:
- Create
{project}/PROJECT.mdwith the standard format - Run
/skill-importfor the project's stack - Update
medium-term.mdat~/.claude/memory/medium-term.md: add the project to the Active Projects table with its stacks and location - Sync lesson files:
/lessons-sync