context-state-tracker

Save Progress

```python

from scripts.state_tracker import StateTracker

tracker = StateTracker(project_dir)

tracker.save_progress(

accomplishments=["Implemented login form", "Added validation"],

blockers=["Need API endpoint for auth"],

next_steps=["Create auth service", "Add tests"]

)

```

Load Progress

```python

state = tracker.load_progress()

print(f"Last session: {state.accomplishments}")

print(f"Blockers: {state.blockers}")

```

Manage Feature List

```python

from scripts.feature_list import FeatureList

features = FeatureList(project_dir)

features.create([

{"id": "auth-001", "description": "User login", "passes": False},

{"id": "auth-002", "description": "User logout", "passes": False},

])

# Mark feature as passing

features.update_status("auth-001", passes=True)

```

```

project/

├── feature_list.json # Immutable feature tracking (passes: true/false)

├── claude-progress.txt # Human-readable session log

└── .git/ # Git history for detailed rollback

```

feature_list.json

```json

[

{

"id": "feat-001",

"category": "functional",

"description": "User can log in with email",

"steps": ["Navigate to login", "Enter credentials", "Click submit"],

"passes": false

}

]

```

claude-progress.txt

```markdown

# Session Progress

Accomplishments

• Implemented user authentication
• Added password validation
• Created login tests

Blockers

• Need to set up email verification

Next Steps

• Implement email service
• Add password reset flow

```

1. Features are immutable: Can only transition from false → true
2. Never delete features: Removing features is CATASTROPHIC
3. Update progress after each session: Enables quick context restoration
4. Use git for detailed history: Commits provide granular rollback

```

┌─────────────────────────────────────────────────────────────┐

│ STATE TRACKING FLOW │

├─────────────────────────────────────────────────────────────┤

│ │

│ SESSION START │

│ ├─ Read feature_list.json │

│ ├─ Read claude-progress.txt │

│ └─ Get git log (recent commits) │

│ │

│ SESSION WORK │

│ ├─ Select next incomplete feature │

│ ├─ Implement feature │

│ └─ Verify feature passes │

│ │

│ SESSION END │

│ ├─ Update feature_list.json (passes: true) │

│ ├─ Append to claude-progress.txt │

│ └─ Commit with descriptive message │

│ │

└─────────────────────────────────────────────────────────────┘

```

• autonomous-session-manager: Uses state for session detection
• coding-agent: Uses feature list for work selection
• progress-tracker: Uses state for metrics

• references/STATE-ARTIFACTS.md - Artifact specifications
• references/PROGRESS-FORMAT.md - Progress file format

• scripts/state_tracker.py - Core StateTracker class
• scripts/progress_file.py - Progress file management
• scripts/feature_list.py - Feature list management
• scripts/git_state.py - Git history integration