beads-statelisted
Install: claude install-skill Tibsfox/gsd-skill-creator
# Beads State Persistence
Filesystem-backed state management for multi-agent orchestration. All state is stored as individual JSON files using atomic write operations. No database dependencies.
## State Entities
### Agent Identity
**Path:** `.chipset/state/agents/{id}.json`
Persistent record of an agent in the topology. Contains role, rig assignment, hook pointer, lifecycle status, and optional ephemeral session ID.
```typescript
interface AgentIdentity {
id: string; // Unique identifier (e.g., 'polecat-alpha')
role: AgentRole; // mayor | witness | refinery | polecat | crew
rig: string; // Parent rig name
hookId: string; // Pointer to hook bead in state/hooks/
status: AgentStatus; // idle | active | stalled | terminated
sessionId?: string; // Present only while agent is active
}
```
### Work Item
**Path:** `.chipset/state/work/{bead-id}.json`
A unit of work flowing through the dispatch pipeline. Created by the mayor, assigned via hooks, tracked through lifecycle.
```typescript
interface WorkItem {
beadId: string; // Bead-style ID (prefix-xxxxx)
title: string;
description: string;
status: WorkStatus; // open | hooked | in_progress | done | merged
assignee?: string; // Agent ID (undefined if unassigned)
hookStatus: HookStatus; // empty | pending | active | completed
priority: 'P1' | 'P2' | 'P3';
}
```
### Hook
**Path:** `.chipset/state/hooks/{agent-id}.json`
Current work assignment for