# Agent State Architect

> Design and audit the runtime state layer for AI agent interfaces. Use when a request involves streaming state, unnecessary re-renders, useSyncExternalStore, external stores, React and non-React state sharing, side-effect centralization, command queues, file watchers, or tiering state by frequency and lifecycle. Not for CLI entry architecture or terminal renderer internals.

- Skill: `ceilf6/agent-state-architect` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add ceilf6/agent-state-architect`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ceilf6/agent-state-architect/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: ceilf6 (https://skillmd.com/u/ceilf6)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ceilf6/agent-state-architect

---


# Agent State Architect

Own the truth model of the running app: what state exists, who owns it, how often it changes, and how updates cross the React boundary without dragging the whole UI with them.

## When To Use

- Diagnosing unnecessary re-renders during token streaming or tool progress updates.
- Designing state tiers for a new agent UI or refactoring an overloaded global store.
- Bridging React components with command queues, watchers, sockets, or other non-React producers.
- Centralizing persistence, notifications, cache invalidation, or other side effects now scattered across mutation sites.

## Use Another Skill Instead

- Use `agent-cli-architect` when the issue is how the app starts, how commands are registered, or how multiple entry modes converge.
- Use `tui-render-optimizer` when state boundaries are already sane and the remaining cost sits in commit, layout, screen diff, or terminal writes.
- Use both this skill and `tui-render-optimizer` when you must distinguish "too many updates" from "each update is too expensive."

## Read First

- Read [references/three-tier-patterns.md](./references/three-tier-patterns.md) when designing or explaining the tier split.
- Read [references/side-effect-centralization.md](./references/side-effect-centralization.md) when mutations trigger persistence, notifications, or cache work.

## Workflow

### 1. Classify State Before Refactoring

For each state domain, record:

- update frequency
- lifecycle scope
- who reads it
- who writes it
- whether non-React code needs synchronous access

Collect evidence from:

- top-level providers and stores
- hot components such as REPL or chat views
- watcher, queue, socket, or bridge modules
- side-effect handlers, persistence hooks, and notification paths

### 2. Split By Tier

Use this default mapping unless the repo proves otherwise:

- Tier 1: low-frequency shared session state in a store plus selectors
- Tier 2: high-frequency REPL or component-local state with `useState` plus `useRef`
- Tier 3: external store state for React and non-React consumers

### 3. Move Side Effects Out Of Mutation Sites

Prefer one store-level `onChange` or equivalent diff handler over scattered persistence and notification code. Mutation sites should change state, not remember every downstream concern.

### 4. Protect Read Semantics

Check these failure modes explicitly:

- selectors creating fresh objects
- `useContext` carrying hot state instead of a stable store reference
- streaming callbacks reading stale closure state
- external stores exposing mutable snapshots to React
- side effects firing from some mutation paths but not others

### 5. Validate The New Boundaries

Confirm that:

- streaming updates only re-render the hot subtree
- non-React code can read and write shared process state safely
- side effects still fire after every relevant mutation path
- unrelated settings changes do not disturb streaming surfaces
- the chosen store API makes ownership obvious rather than convenient-but-ambiguous

## Output Shape

When using this skill, prefer producing:

- a tiered state inventory
- a current-vs-target state map
- concrete store or signal patterns for the chosen tiers
- a centralized side-effect plan
- a note on which symptoms belong to state design versus renderer cost
- a verification checklist tied to re-render and consistency risks

## Guardrails

- Do not put millisecond-level streaming state in the global shared store.
- Do not pass hot state values through Context when a stable store reference will do.
- Do not create fresh objects in `useSyncExternalStore` selectors.
- Do not read hot state from stale closures inside streaming callbacks.
- Do not scatter side effects across mutation callsites.
- Do not expose mutable snapshots as React store outputs.
- Do not use renderer-level hacks to hide a state-layer ownership problem.

## Decision Rules

- If every token touches too much UI, split the hot path into component-local state first.
- If React and non-React code both need the same truth source, build an external store instead of forcing everything through React state.
- If some mutation paths miss persistence or notifications, centralize side effects immediately.
- If the user wants explanation rather than code, keep the answer tier-based and failure-mode-driven.
- If re-render frequency looks correct but each frame is still expensive, hand off to `tui-render-optimizer` instead of overfitting the state model.