Sportstime/PROJECT_STATE.md

Claude Code State & Control System

This document contains everything you need to keep Claude Code from losing context, looping, or rewriting history:

1. A canonical PROJECT_STATE.md file template
2. A full set of copy‑paste prompts for working with Claude Code
3. Claude Code hooks / scripts to automate checkpoints and recovery

---

1️⃣ PROJECT_STATE.md (CANONICAL FILE)

Create this file at the root of your repo.

# PROJECT STATE — CANONICAL

⚠️ This file is the single source of truth.
⚠️ Sections marked LOCKED may not be modified unless the user explicitly says "unlock".
⚠️ Claude must read this file before doing any work.

---

## Goal (LOCKED)
<!-- 1–3 sentences. Immutable unless explicitly changed by the user. -->


## Non‑Negotiable Constraints (LOCKED)
- No re‑evaluation of prior decisions
- No alternative architectures unless explicitly requested
- No refactors outside the active task
- No scope expansion


## Architecture Decisions (LOCKED)
-
-


## Current Phase
<!-- Short name + description -->


## Active Tasks
<!-- Only tasks Claude is allowed to work on -->
- [ ]
- [ ]


## Completed Tasks
- [x]


## Open Questions (User‑Owned)
<!-- Claude may not answer these unless asked -->
-


## Checkpoints (APPEND‑ONLY)

### Checkpoint YYYY‑MM‑DD HH:MM
- What exists:
- What is missing:
- Known issues:
- Next step:

---

2️⃣ CLAUDE CODE PROMPTS (COPY / PASTE)

Save this section as CLAUDE_PROMPTS.md if you want it separate.

---

🔹 Initialize Project State

Create or update PROJECT_STATE.md.
Write the goal, non‑negotiable constraints, architecture decisions, and an initial task list.
Do NOT write code.
Do NOT speculate.
This file is canonical.

---

🔹 Start Any Work Session

Before doing anything, read PROJECT_STATE.md in full.
Summarize:
- Goal
- Current Phase
- Active Tasks
Then proceed with the first unfinished task only.
Do not modify PROJECT_STATE.md unless explicitly told to.

---

🔹 Execute a Task (No Drift)

Work only on the selected Active Task.
Do not introduce new abstractions.
Do not refactor unrelated code.
Do not re‑analyze architecture.
Produce the minimum change required.

---

🔹 Write a Checkpoint

Write a new checkpoint to PROJECT_STATE.md.
Append only under the Checkpoints section.
Do not modify earlier content.
Summarize truthfully:
- What exists
- What is missing
- Known issues
- Next step

---

🔹 Context Reset / Recovery

Clear context.
Read PROJECT_STATE.md completely.
Summarize:
- Goal
- Current Phase
- Active Tasks
Then continue from the next unfinished task.

---

🔹 Scope Guard (When Claude Starts Drifting)

Stop.
This is out of scope.
Re‑read PROJECT_STATE.md.
Return to the current Active Task.

---

🔹 Lock or Unlock Sections

Unlock the following section(s):
- <section name>
No other sections may be modified.

---

3️⃣ CLAUDE CODE HOOKS / SCRIPTS

These assume Claude Code can run shell commands or that you trigger them manually.

---

🧠 Auto‑Checkpoint Script

Create checkpoint.sh

#!/usr/bin/env bash

echo "\n### Checkpoint $(date '+%Y-%m-%d %H:%M')" >> PROJECT_STATE.md
echo "- What exists:" >> PROJECT_STATE.md
echo "- What is missing:" >> PROJECT_STATE.md
echo "- Known issues:" >> PROJECT_STATE.md
echo "- Next step:" >> PROJECT_STATE.md
echo "" >> PROJECT_STATE.md

Use prompt:

Run checkpoint.sh and then fill in the new checkpoint accurately.

---

🔁 Session Start Hook

Create session_start.md

Read PROJECT_STATE.md.
You may not write code until you summarize:
- Goal
- Current Phase
- Active Tasks

Paste this at the top of every new Claude Code session.

---

🧯 Emergency Reset Hook

Create RESET.md

STOP ALL WORK.
Discard assumptions from previous context.
Read PROJECT_STATE.md in full.
State what the next correct action is.
Do not code until confirmed.

---

Final Rule (Read This Once)

Claude Code is a stateless executor, not a planner.

This system turns it into:

• A reliable implementer
• A resumable worker
• A non‑looping assistant

If Claude starts looping, drifting, or "thinking creatively" — it means the rails weren’t explicit enough.

Tighten the rails.