agentdb-state-manager

The AgentDB State Manager is an advanced utility skill designed to bridge the gap between simple file-based tracking and full-scale database management in automated software development environments. By utilizing DuckDB as an embedded analytics engine, it transforms disparate TODO_*.md source files into a structured, queryable data repository. This allows agents to perform complex operations such as critical path analysis, bottleneck identification, and longitudinal tracking of project state transitions without the performance overhead or token consumption associated with repetitive file parsing. It is specifically built for technical teams leveraging Claude Code who require high-fidelity visibility into their multi-phase workflow states.

• Read-only analytics caching for workflow history, allowing SQL-based queries over task dependencies, phase timing, and project velocity.

• Automated context checkpoint management that captures system state at specific token thresholds, enabling rapid recovery and resumption of complex reasoning tasks.

• Immutable, append-only record keeping that ensures an audit trail of state changes, providing historical metrics for project health reporting.

• Schema-driven organization that integrates seamlessly with existing planning/implementation structures, using standardized workflow states from JSON configuration files.

• High-performance data retrieval for cross-phase inquiries, significantly reducing latency and token costs compared to manual file-parsing methods.

• Primary input involves standard TODO_*.md files representing the current project state, which are synced to the DuckDB instance via the built-in sync utility.

• Outputs provide detailed insights into project bottlenecks, task blocking dependencies, and historical evolution of implementation phases.

• Operates under a cross-phase model (Utilities), meaning it is accessible across planning, implementation, quality assurance, integration, and release workflows.

• Utilizes timestamp-based session IDs to ensure reproducibility and consistency across distinct agent invocations within a 24-hour operational window.

• Constraints include a requirement for an initial schema setup and the necessity of maintaining the TODO_*.md files as the ultimate source of truth, treating AgentDB strictly as an analytics-oriented mirror.