version: "1.0.0" name: state-management description: "Client state management standards: local-vs-global decisions, store structure, selectors, and re-render performance. TRIGGER when: creating a store, managing global state, or deciding local vs global state. SKIP: component/hook structure (use react-patterns); visual styling (use mui-styling). (Examples use Zustand.)"

State Management Skill

Client state management standards and best practices. The universal guidance (local-vs-global decisions, store structure, selectors, performance) applies to any store library; the concrete code examples use Zustand.

When to Apply

• Creating new state stores
• Sharing state between components
• State architecture decisions
• Performance optimization for state

State Category Guidelines

Zustand Store Standards

Store Structure

Store Design Principles

Selector Best Practices

Selection Rules

Selector Patterns

Middleware Usage

Store Organization

File Structure

src/stores/
├── index.ts           # Re-exports all stores
├── projectStore.ts    # Domain-specific store
├── uiStore.ts         # UI state (modals, panels)
└── settingsStore.ts   # User preferences

Store Separation Guidelines

Performance Guidelines

DO

• Select only needed state slices
• Use shallow equality for object selections
• Define actions inside store (stable references)
• Split large stores by domain
• Use subscribeWithSelector for side effects

DON'T

• Select entire store object
• Create new objects in selectors without shallow
• Put derived/computed state in store
• Call actions during render phase
• Create deeply nested store structure

Anti-Patterns

Decision Matrix

Example: Zustand Store Patterns (illustrative)

Illustrative — these are one team's concrete Zustand conventions shown as an

example. Substitute your store library's equivalents (Redux Toolkit, Jotai,

Pinia, signals, etc.). The decision matrix and selector/performance guidance

above are the reusable, library-agnostic part.

Store Files (<your-stores-module>/)

Type Pattern: Separate State & Actions

Every store defines type XxxState and type XxxActions, then exports the combined type:

type WorkspaceState = {
  workspaces: Workspace[];
  activeWorkspace: Workspace | null;
};
type WorkspaceActions = {
  addWorkspace: (pathOrWorkspace: string | Workspace) => void;
  removeWorkspace: (path: string) => Promise<void>;
  setActiveWorkspace: (path: string) => void;
  loadFromApi: () => Promise<void>;
};
export type WorkspaceStore = WorkspaceState & WorkspaceActions;

Persist Middleware with partialize

Persisted stores use partialize to exclude actions and transient state from storage:

export const useWorkspaceStore = create<WorkspaceStore>()(
  persist(
    (set, get) => ({ /* state + actions */ }),
    {
      name: 'scaffolding-workspaces',
      partialize: (state) => ({
        workspaces: state.workspaces,
        activeWorkspace: state.activeWorkspace,
      }),
    }
  )
);

Hook Wrappers with useShallow (<your-hooks-module>/)

Stores are consumed through hook wrappers that use useShallow to prevent re-renders:

import { useWorkspaceStore } from '../stores/workspaceStore';
import { useShallow } from 'zustand/shallow';
export function useWorkspace() {
  return useWorkspaceStore(
    useShallow((state) => ({
      workspaces: state.workspaces,
      activeWorkspace: state.activeWorkspace,
      addWorkspace: state.addWorkspace,
      // ... selected fields only
    }))
  );
}

API Sync Pattern (loadFromApi)

Stores hydrate from localStorage first, then enrich from API:

1. persist middleware loads cached state from localStorage on mount
2. loadFromApi() fetches from backend, merges fields (id, github_url, role) into existing entries
3. Failures are silently caught - localStorage data still works offline

SSE Update Pattern (taskStore)

Non-persisted stores receive real-time updates from Server-Sent Events:

• addTask(task) - deduplicates before prepending to list
• updateTask(task) - replaces full task object in list and currentTask
• updateTaskPartial(id, updates) - merges partial fields from SSE completion events
• updateAgentStatus(taskId, status) - tracks per-agent progress within a task

Error Handling in Stores

Stores use extractErrorMessage(err, fallbackMsg) utility and store errors in state:

catch (err) {
  const message = extractErrorMessage(err, 'Failed to fetch tasks');
  set({ error: message, isLoading: false });
}

For expected errors (e.g., 409 conflict on cancel), check AxiosError status before setting error state.