Project State Governance
Project State Governance
Purpose
Give humans and agents a compact way to understand the current project without reading the entire repository.
State Entry Point
Use an existing project-status source when available.
If a meaningful project lacks one, a lightweight PROJECT_STATUS.md or local
equivalent can be introduced.
Suggested fields:
Project:
Status:
Current version:
Current phase:
Active branch/release:
Current objective:
Recent changes:
Known risks:
Open issues:
Next milestone:
Only include fields that are useful.
State Freshness
Update project state after meaningful changes such as:
- milestone completion
- architecture change
- release
- major refactor
- important decision
- material risk discovery
Do not update it for every trivial code edit.
State vs History
Current state answers "where are we now?"
Git history, changelogs, decision records, and archives answer "how did we get here?"
Do not overload the current-state document with full history.
Handoff Test
A healthy state entry point should allow a new agent to answer quickly:
- what is this project?
- what is currently active?
- what is the current version?
- what is the immediate objective?
- what are the main risks?
- where should I start reading?
If it cannot, either the state document or the project structure needs work.