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

```md
# 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`

```bash
#!/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`

```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`

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