<project>/.claude/context/
├── HISTORY.md          # Cumulative session log (append-only)
├── DECISIONS.md        # All decisions ever made (append-only)
├── DIRECTIONS.md       # Direction changes and pivots (append-only)
└── archive/            # Old files if manual cleanup needed
    └── HISTORY_pre_YYYY-MM-DD.md

PROJECT=$(basename $(pwd))
CONTEXT_DIR=~/local_workspaces/$PROJECT/.claude/context
TIMESTAMP=$(date +%Y-%m-%d_%H%M)

mkdir -p $CONTEXT_DIR/archive

# Read existing files to understand current state
cat $CONTEXT_DIR/HISTORY.md 2>/dev/null || echo "[No history yet]"
cat $CONTEXT_DIR/DECISIONS.md 2>/dev/null || echo "[No decisions yet]"
cat $CONTEXT_DIR/DIRECTIONS.md 2>/dev/null || echo "[No direction changes yet]"

## Direction Change: YYYY-MM-DD HH:MM

**Original Plan:**
[What was supposed to happen]

**What Actually Happened:**
[What we did instead]

**Why the Pivot:**
[Reason - user request, blocker discovered, better approach found, etc.]

**Impact:**
[What this means for the project going forward]

---

## Session: YYYY-MM-DD HH:MM

### Goal
[What this session aimed to accomplish]

### Accomplished
- [x] Task 1
- [x] Task 2
- [→] Task 3 (in progress)
- [ ] Task 4 (not started)

### Files Changed
- `path/file.ts` - [what changed]
- `path/new.ts` - NEW: [purpose]

### Commands Run
```bash
[key commands only]

### Step 4: Append to DECISIONS.md

**APPEND** any new decisions (check for duplicates first):

```markdown
---

## YYYY-MM-DD: [Decision Title]

**Context:** [Why this decision was needed]

**Options Considered:**
1. [Option A] - [pros/cons]
2. [Option B] - [pros/cons]

**Decision:** [What was chosen]

**Rationale:** [Why]

**Affected Files:** [list]

**Reversible:** [Yes/No - and how if yes]

---

## YYYY-MM-DD HH:MM: [Pivot Description]

**Was Planning To:** [original plan]

**Instead Did:** [what happened]

**Trigger:** [user request / blocker / discovery / better idea]

**Old Direction:**
[brief description of abandoned path]

**New Direction:**
[brief description of new path]

**Carryover:** [what from old direction still applies]

**Abandoned:** [what's being dropped]

cd ~/local_workspaces/$PROJECT

git add .claude/context/

git commit -m "$(cat <<'EOF'
docs(context): Append session context YYYY-MM-DD HH:MM

- Added session to HISTORY.md
- [N] new decisions recorded
- [Direction change noted / No direction change]

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
EOF
)"

git push origin $(git branch --show-current) 2>/dev/null || echo "Push skipped"

Context appended successfully!

HISTORY.md:
  + Session YYYY-MM-DD HH:MM added
  Total sessions: [N]

DECISIONS.md:
  + [N] new decisions added
  Total decisions: [M]

DIRECTIONS.md:
  + Direction change recorded: [title]
  OR
  (no direction change this session)

Git: [commit hash] pushed to origin/main

# Archive old content
mv $CONTEXT_DIR/HISTORY.md $CONTEXT_DIR/archive/HISTORY_pre_$(date +%Y-%m-%d).md

# Start fresh with reference
echo "# Project History (continued)

Previous history archived: archive/HISTORY_pre_$(date +%Y-%m-%d).md

---
" > $CONTEXT_DIR/HISTORY.md

---

## 2026-01-19 22:00: Gemini Migration Instead of Voice Improvements

**Was Planning To:** Improve voice input detection and add wake word support

**Instead Did:** Migrated Council backend from Claude CLI to Gemini API

**Trigger:** User request - provided detailed migration plan

**Old Direction:**
Voice UX improvements - better mic handling, wake word "Hey Claude"

**New Direction:**
Backend modernization - direct Gemini API, streaming, no subprocess

**Carryover:** Voice improvements still on roadmap, now lower priority

**Abandoned:** Nothing permanently - voice work deferred