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.md

GitHub

Project 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)

  1. Read medium-term.md at ~/.claude/memory/medium-term.md
  2. Identify the current project and its stacks from the Active Projects table
  3. Read {project}/PROJECT.md
  4. Sync lessons for all stacks: run /lessons-sync (all stacks)

When to Update PROJECT.md

At Session End

  1. Update last_active in medium-term.md for the current project
  2. Sync lessons: for each stack in the project, diff root ~/.claude/memory/lessons/{stack}.md against {project}/memory/lessons/{stack}.md, append new entries from root
  3. Append session log to {project}/memory/sessions/YYYY-MM-DD.md
  4. Update last_session in {project}/PROJECT.md to today's date
  5. Update focus if work shifted from what was listed
  6. Update status or phase only if a genuine milestone was hit
  7. Update blockers only if something genuinely blocked progress

At Session Start

  • Read PROJECT.md first
  • Use focus to immediately understand what to work on
  • If last_session is 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:

  1. Create {project}/PROJECT.md with the standard format
  2. Run /skill-import for the project's stack
  3. Update medium-term.md at ~/.claude/memory/medium-term.md: add the project to the Active Projects table with its stacks and location
  4. Sync lesson files: /lessons-sync