CtrlK
BlogDocsLog inGet started
Tessl Logo

ac-state-tracker

State persistence for autonomous coding. Use when saving progress, loading state, tracking features, managing checkpoints, or persisting data across sessions.

66

Quality

80%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

SecuritybySnyk

Passed

No findings from the security scan

SKILL.md
Quality
Evals
Security

AC State Tracker

Persistent state management for cross-session autonomous coding.

Overview

Maintains all state across sessions:

  • Feature list tracking (passes: false → true)
  • Execution state (iteration, cost, status)
  • Progress logging
  • Handoff packages
  • Checkpoint management

Quick Start

Initialize State Tracker

from scripts.state_tracker import StateTracker

state = StateTracker(project_dir)
await state.initialize()

Save/Load State

# Save current state
await state.save()

# Load state from files
current_state = await state.load()

Update Feature Status

# Mark feature as passing (IMMUTABLE: false → true only!)
await state.update_feature("auth-001", passes=True)

State Files

Primary State Files

project/
├── feature_list.json        # Feature tracking (immutable passes)
├── claude-progress.txt      # Human-readable log
└── .claude/
    ├── master-state.json    # Orchestrator state
    ├── autonomous-state.json # Execution state
    ├── autonomous-log.jsonl  # Activity log
    ├── handoffs/
    │   └── current.json     # Mid-session handoff
    └── checkpoints/
        └── checkpoint-*.json # Rollback points

feature_list.json Schema

{
  "features": [
    {
      "id": "auth-001",
      "description": "User registration endpoint",
      "category": "authentication",
      "status": "completed",
      "passes": true,
      "test_cases": [
        "User can register with email",
        "Validation errors shown"
      ],
      "dependencies": [],
      "estimated_effort": "4h",
      "actual_effort": "2.5h",
      "started_at": "2025-01-15T10:00:00Z",
      "completed_at": "2025-01-15T12:30:00Z"
    }
  ],
  "total": 50,
  "completed": 25,
  "in_progress": 1,
  "blocked": 0
}

CRITICAL RULE: Features can ONLY transition passes: false → true. Never delete or edit features - this prevents the agent from "solving" by removing tasks.

autonomous-state.json Schema

{
  "session_id": "session-20250115-100000",
  "iteration": 12,
  "status": "running",
  "estimated_cost": 4.23,
  "consecutive_failures": 0,
  "current_feature": "auth-002",
  "last_task": "Implement login endpoint",
  "started_at": "2025-01-15T10:00:00Z",
  "context_usage": 0.45
}

master-state.json Schema

{
  "project_id": "my-project",
  "objective": "Build chat application",
  "sessions_used": 5,
  "total_features": 50,
  "features_completed": 25,
  "current_phase": "implementation",
  "last_handoff": "2025-01-15T12:00:00Z"
}

Operations

1. Initialize State

state = StateTracker(project_dir)
await state.initialize()

# Creates default files if not exist
# Loads existing state if present

2. Update Feature

# Mark feature complete
await state.update_feature(
    feature_id="auth-001",
    passes=True,
    actual_effort="2.5h"
)

# Mark feature in progress
await state.update_feature(
    feature_id="auth-002",
    status="in_progress"
)

3. Create Checkpoint

checkpoint = await state.create_checkpoint(
    name="before-refactor",
    git_commit=True
)
# Returns checkpoint ID for rollback

4. Restore Checkpoint

await state.restore_checkpoint("checkpoint-20250115-100000")
# Restores feature_list.json and git state

5. Log Activity

await state.log_activity(
    action="CONTINUE",
    details="Implementing login endpoint",
    iteration=12
)
# Appends to autonomous-log.jsonl

6. Save Handoff

await state.save_handoff({
    "current_feature": "auth-002",
    "context_summary": "Completed auth, starting profile...",
    "next_action": "Implement profile page"
})

7. Get Progress Summary

progress = await state.get_progress()
# Returns:
#   completed: 25
#   total: 50
#   percentage: 50%
#   current_feature: "auth-002"
#   estimated_remaining: "4 hours"

Progress File Format

claude-progress.txt

=== AUTONOMOUS CODING SESSION ===
Project: my-project
Started: 2025-01-15 10:00:00
Sessions: 5

=== PROGRESS ===
[25/50] 50% complete

=== CURRENT FEATURE ===
auth-002: Login with JWT

=== COMPLETED THIS SESSION ===
- auth-001: User registration [PASS]
- auth-002: Login endpoint [IN PROGRESS]

=== BLOCKERS ===
None

=== LAST UPDATED ===
2025-01-15 12:30:00

Integration Points

  • ac-config-manager: Loads paths configuration
  • ac-session-manager: Triggers state save/load
  • ac-autonomous-loop: Updates feature status
  • ac-checkpoint-manager: Creates/restores checkpoints
  • ac-handoff-coordinator: Manages handoff packages

References

  • references/STATE-SCHEMA.md - Complete state schemas
  • references/FEATURE-LIFECYCLE.md - Feature state machine

Scripts

  • scripts/state_tracker.py - Core StateTracker class
  • scripts/feature_manager.py - Feature list operations
  • scripts/checkpoint_store.py - Checkpoint storage
  • scripts/progress_logger.py - Progress file generation
Repository
fernandezbaptiste/Skrillz
Path

skills/ac-state-tracker/SKILL.md

Commit

93ed392

Last updated
First committed

Also appears in

fernandezbaptiste/Skrillz
In sync

since Sep 12, 2026

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.

Claim skill