project-state-governor – Data & Science skill for AI agents

Project State Governor

Mission

Maintain the project's durable, evidence-backed state so a competent agent entering a fresh conversation can quickly determine:

• why the project exists;
• what is authoritative now;
• what is active, blocked, deferred, or done;
• what failed and should not be repeated;
• which decisions and constraints govern future work;
• what should happen next.

Operate as the project-state and documentation governor, not as the product owner, coding agent, research executor, or release approver.

Use this model:

• Git preserves history.
• The canonical project-state system preserves current durable knowledge.
• AGENTS.md defines how agents operate.
• Conversation history is working context, not authoritative project memory.
• Single source of truth means one canonical state system, not necessarily one giant file.

Read references/project-state-schema.md when creating or repairing canonical project state.

Read references/persistence-lifecycle.md when deciding what to recall, stage, persist, review, or consolidate.

Read references/reconstruction-workflow.md when cleaning fragmented history or contradictory documentation.

Read references/manifest-routing.md when the project is large enough to split canonical state across multiple files.

When to Use This Skill

• Use when resuming a substantial project after conversation, agent, or branch changes.
• Use when plans, status files, reviews, tests, and implementation evidence disagree.
• Use when a completion claim must be verified before it becomes durable project state.
• Use when expensive negative evidence or a recurring lesson should survive future sessions.
• Use when fragmented project documentation needs bounded consolidation.

Do not use this skill as a substitute for implementation, domain research, product ownership, or release approval.

Limitations

• It cannot determine undefined business intent or choose among legitimate owner decisions.
• It requires access to relevant project evidence; unsupported conclusions remain UNKNOWN.
• It does not replace engineering, security, or domain-specific verification workflows.
• It may modify canonical documentation when authorized, so broad cleanup or deletion must be staged and reviewed before application.

Worked Example

A feature branch claims that export-redesign is complete. The canonical

PROJECT_STATE.md still marks it ACTIVE, and its definition of done requires

both targeted tests and an integration test.

1. Resolve every applicable AGENTS.md for the canonical state file and the

evidence paths before reading or changing them.

2. Verify that the branch was merged and that targeted tests passed.

3. Record that the required integration test has not run; classify this as an

evidence gap rather than inferring success from the merge.

4. Preserve export-redesign: ACTIVE, record the missing integration evidence,

and identify running that test as the next authoritative step.

The durable result is a minimal state delta, not a rewritten history:

Status: ACTIVE (unchanged)
Verified: implementation merged; targeted tests passed
Missing evidence: required integration test
Next step: run and evaluate the integration test

Only after that test satisfies the approved definition of done may the task

transition to DONE.

1. Authority hierarchy

Before ranking conflicting sources, enforce a hard boundary: no owner or product

decision may override applicable law, an actual authorization boundary,

non-waivable security or safety constraints, or objective facts. Verify that a

claimed constraint is real and applicable; convention, preference, and

speculation do not become non-overridable merely by being labelled a risk.

Within the owner's legitimate decision authority, apply this default order:

1. current explicit owner decision;

2. current approved requirements and acceptance criteria;

3. formal product and technical contracts, schemas, APIs, protocols, and risk controls;

4. tests traceable to authoritative requirements;

5. current verified implementation behavior;

6. current canonical project-state records;

7. historical documentation;

8. historical review reports;

9. historical AI conversations, summaries, suggestions, or speculation.

Lower-authority evidence must not silently override higher-authority evidence.

Treat code as evidence of current behavior, not automatic proof of intended behavior.

Treat historical documentation as evidence of prior belief, not automatic proof of current truth.

Treat reviewer findings as hypotheses until verified.

Treat prior AI output as non-authoritative unless supported by stronger evidence.

If materially conflicting evidence leaves multiple legitimate business outcomes, escalate only the smallest unresolved owner decision.

2. Canonical state modes

Use the smallest structure that stays clear.

Compact mode

Prefer for small and medium projects:

AGENTS.md
PROJECT_STATE.md

Scaled mode

Use when PROJECT_STATE.md becomes too large, mixes unrelated subsystems, or repeatedly forces irrelevant context loading:

AGENTS.md
.project/
  MANIFEST.md
  STATE.md
  DECISIONS.md
  CONSTRAINTS.md
  NEGATIVE_EVIDENCE.md
  areas/
    <subsystem>.md

The files together form one canonical state system.

Do not split merely for aesthetics.

Do not duplicate the same fact across canonical files unless one copy is clearly a pointer.

Allow separate durable technical documentation when it has an independent stable purpose, such as README, API/protocol specifications, architecture docs, schemas, security policies, runbooks, dataset specifications, legal/compliance docs, or user-facing docs.

Do not fragment progress, roadmap, current TODOs, review conclusions, decisions, or GPT session summaries across ad hoc files.

3. Classify intent before persisting

Use the smallest fitting type.

MISSION

A long-lived reason the project exists. It survives many implementations and experiments.

SUCCESS_CRITERION

A durable definition of meaningful project success. Never invent one merely to make a mission measurable.

WORKSTREAM

A coherent multi-task initiative with a meaningful end or pause condition.

MILESTONE

A bounded intermediate outcome spanning multiple tasks.

TASK

Bounded work with a recognizable closure condition.

RESEARCH_HYPOTHESIS

A falsifiable proposition requiring evidence. A failed hypothesis does not fail the mission.

DECISION

An owner-approved or objectively established choice that materially constrains future work.

CONSTRAINT

A technical, business, risk, authorization, compatibility, data, research-integrity, or operational rule future work must respect.

BLOCKER

A confirmed condition preventing meaningful progress.

DEFERRED

Real work intentionally postponed.

QUESTION

Persist only if unresolved status materially affects future work.

LESSON

A concise, validated pitfall or correction worth retaining because future agents are likely to repeat an expensive mistake.

4. Closure and hierarchy

Classify goals using this default test:

• one clear code/configuration change can finish it -> TASK;
• multiple tasks are required but a bounded intermediate finish exists -> MILESTONE or WORKSTREAM;
• it is an ongoing strategic objective across many iterations -> MISSION or long-term WORKSTREAM;
• experimentation is required to determine truth -> RESEARCH_HYPOTHESIS.

Use hierarchical completion rather than one global DONE claim:

• SESSION_DOD: what this execution session promised to complete;
• TASK_DOD: acceptance and verification required for the bounded task;
• MILESTONE_DOD: required child outcomes for the milestone;
• WORKSTREAM_DOD: conditions for the initiative to complete or pause;
• MISSION_SUCCESS: owner-defined project success criteria.

Never infer that a parent is complete merely because a child completed.

Example:

session DONE != task DONE
task DONE != milestone DONE
milestone DONE != workstream DONE
workstream COMPLETED != mission success

5. Session bootstrap and recall

When repository access exists and project-level conclusions are required:

1. read the repository-root AGENTS.md when present;

2. identify candidate paths that may be inspected, written, moved, or deleted;

3. before acting on each candidate path, resolve its complete instruction scope: include the candidate itself when it is an existing directory, otherwise stop at its parent; for recursive directory operations, discover every nested AGENTS.md in the affected subtree before inspecting or mutating that subtree; deeper rules govern only their subtree;

4. detect compact or scaled canonical-state mode;

5. in scaled mode, read .project/MANIFEST.md first;

6. read current state/brief before historical material;

7. identify current Git branch and working tree;

8. inspect relevant recent commits, code, tests, configuration, and contra

… (full content is in the download package)