itervox

Use when a human or agent needs to do exploratory QA on existing Itervox UI before/after a UI change. Drives both the route-mocked Playwright lane and the real-daemon lane, then captures qualitative issues (visual hierarchy, copy, accessibility) automated tests cannot. Produces a structured report under `docs/qa-reports/`.

Use when editing go.mod, Makefile, bumping the Go toolchain version, addressing govulncheck stdlib vulnerabilities, or when `make verify` fails with `go: go.mod requires go >= X.Y.Z (running go X.Y.Z; GOTOOLCHAIN=goX.Y.Z)`. Keeps the two Go version pins (`go.mod` and `Makefile`) in lockstep.

Use when editing any file in internal/orchestrator/, when adding or modifying fields on structs in internal/config/config.go, or when discussing concurrency, state mutations, locking, goroutines, or race conditions in the itervox Go codebase. Enforces the single-goroutine state machine rule and the exact cfgMu guard list.

Use before claiming any change is complete, before creating a commit or PR, or when the user asks "is this ready" / "are we done" / "can I merge". Also use when the user mentions test failures, coverage drops, or CI red. Enforces running `make verify` and related gates with evidence before asserting success.

Use when editing any file in web/src/ that performs HTTP requests or opens SSE streams — any .ts/.tsx file outside web/src/auth/ that uses fetch, EventSource, or adds a new query/mutation under web/src/queries/. Enforces bearer-token transport rules so frontend network I/O stays compatible with ITERVOX_API_TOKEN auth and the AuthGate login flow.

Use when `change-impact-review` surfaces a breaking change, OR when you're about to remove/rename an exported Go symbol, remove/rename a Zod schema field, change an HTTP route's shape, rename a WORKFLOW.md config field, or alter the semantics of a field without changing its name. This skill is a HARD STOP — no code changes until the user explicitly confirms.

Use BEFORE editing any exported Go symbol (type, function, interface, struct field), any HTTP route in `internal/server/`, any SSE event shape, any Zod schema in `web/src/types/schemas.ts`, any WORKFLOW.md config field, or any public API surface. Produces a structured impact analysis listing affected call sites, schema parity risks, and regression surface before code changes begin.

Use when adding or renaming fields in any config struct in internal/config/config.go (ServerConfig, TrackerConfig, AgentConfig, WorkspaceConfig, PollingConfig, HooksConfig), or when the user says "add a config option", "new WORKFLOW.md field", or mentions evolving the WORKFLOW.md schema.

Use when adding a new `.go` file to any `internal/` package, when an existing file grows past ~400 lines, when introducing a helper function, or when considering a new package. Enforces itervox's package dependency order, file-size discipline, reuse of stdlib builtins, and the no-premature-utils-package rule.

Use when creating or editing any `.tsx` file under `web/src/components/` or `web/src/pages/`, when adding a new React hook under `web/src/hooks/`, or when the user asks for a new UI component. Enforces component size, state-layer boundaries (Zustand vs TanStack Query vs SSE snapshot), and reuse of existing itervox UI primitives.