Context State Tracker

Persists and restores state across autonomous coding sessions using structured artifacts.

Quick Start

Save Progress

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

state = tracker.load_progress()
print(f"Last session: {state.accomplishments}")
print(f"Blockers: {state.blockers}")

Manage Feature List

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)

State Artifacts

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

[
  {
    "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

# Session Progress

## Session 5 - 2025-01-15 14:30

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

Key Rules

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

Workflow

┌─────────────────────────────────────────────────────────────┐
│                    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                         │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Integration Points

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

References

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

Scripts

• 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