acture

Load context on acture's schema bridge — Zod → JSON Schema projection, MCP tool emission, AI SDK tool definitions, Standard Schema compatibility, and the JSON-Schema-representable subset rule. Use when working on toJsonSchema, the MCP adapter, the Vercel AI adapter, the Anthropic adapter, schema validation at registration, or compare-schemas. Triggers on "JSON Schema", "Zod schema", "z.toJSONSchema", "MCP tool", "AI tool definition", "schema bridge", "Standard Schema", "Valibot", "param schema validation". Do NOT use for general CommandRecord questions (load `acture-command-record-shape`) or for the tier/versioning system (load `acture-tier-system`).

Build an embedded AI assistant that OPERATES a command-dispatch app — not just a chatbot that answers, but an assistant that reads current app state and takes actions on the user's behalf. Composes acture's write-side (command→tool/MCP, via acture-ai / acture-mcp) with the missing read side (a ViewRegistry projected to MCP resources + a getState tool), a dispatch-boundary human-in-the-loop confirmation gate, and dispatch-chain capture (undo/replay). Bridges to the general ai-assistant-* skill family for the runtime, chat UI, and prompts (which stay the app's choice). Use when adding an "operate my app" assistant/copilot to a command-dispatch app, exposing app state to an LLM, wiring MCP resources, or gating destructive AI actions. Triggers on "AI assistant", "operate my app", "copilot", "agent that takes actions", "expose state to the AI", "MCP resources", "getState tool", "human in the loop", "confirmation gate", "CopilotKit", "assistant-ui", "AG-UI", "the assistant should see what's selected".

Build a keyboard-shortcut consumer surface in a target project — bind `keybinding` off every CommandRecord and dispatch through the registry on key match, AND (new) let end users remap shortcuts. Covers the tool-library choice (tinykeys / react-hotkeys-hook / custom), the agent-written vs `acture-hotkeys` package paths, first-registered-wins conflict resolution, fire-time when-clause evaluation, the input-aware default, and end-user customization (persisted user keymap over the record default, press-to-record capture, conflict detection, physical-vs-logical keys, WCAG 2.1.4). Use when adding keyboard shortcuts to a command-dispatch app, when adding user-remappable shortcuts, or when working ON the `acture-hotkeys` package. Triggers on "hotkeys", "keyboard shortcuts", "keybindings", "bind keys", "tinykeys", "Ctrl+K shortcut", "shortcut conflict", "modal-scoped shortcuts", "customize keybindings", "remap shortcut", "rebind keys", "user keymap", "keybinding editor", "keymap preset".

Build an MCP-server consumer surface in a target project — project the command registry as Model Context Protocol tools (`{name, description, inputSchema}`), tier-filtered, errors-as-data, AND (new) project app state as MCP resources (the read side — views → `resources/list`/`resources/read`/`resources/subscribe`). Covers the two-layer split (pure projection vs transport glue), the agent-written vs `acture-mcp-server` package paths, tier semantics, function-when-clause exclusion, the prompt-injection guardrails, and the read-side resources projection. Use when exposing a command-dispatch app to MCP clients, exposing app state as MCP resources, or when working ON the `acture-mcp-server` package. Triggers on "MCP", "MCP server", "Model Context Protocol", "tools/list", "tools/call", "MCP resources", "resources/list", "expose state to an assistant", "expose to Claude", "stdio server", "@modelcontextprotocol/sdk".

Load the conceptual model of acture's command-dispatch architecture. Use this skill at the start of ANY non-trivial task in the acture repository — it covers the three primitives (state model, command registry, schema bridge), the eight consumer surfaces, and acture's dev-tool-first positioning with its two flexibility dimensions. Triggers on phrases like "what is acture", "how does the architecture work", "the three primitives", "the consumer surfaces", or when starting a new phase. Do NOT use this for narrow API/typing questions — load `acture-command-record-shape` or another targeted skill instead.

The foundational pattern for building a command-dispatch CONSUMER in a target project — a command palette, keyboard shortcuts, AI tool calling, an MCP endpoint, e2e testing, macros, telemetry, undo. Load this whenever you are adding a consumer surface to a user's app, OR whenever you are working on a consumer-specific acture-* package (acture-palette-react, acture-hotkeys, acture-mcp-server, acture-ai-vercel, acture-e2e-playwright, …). It encodes acture's dev-tool-first positioning: the agent-written path is always viable, acture packages are an optional opt-in accelerator, and tool-library choices belong to the user. Triggers on "add a command palette", "add hotkeys", "wire up MCP", "expose commands to an AI", "set up e2e testing", "build a consumer", "which acture package should I use", "do I need to install acture".

Build an extension / plugin consumer surface in a target project — let code you did not author contribute new commands to the registry via a typed, inert manifest, invoked through `dispatch`. Covers the trust-tier fork (trusted in-process host/loader vs untrusted-author isolation), the contribution-manifest shape, the ~15-line hand-written host (there is NO package for the trusted path — it ships as a pattern), the deferred isolation-only `acture-sandbox` package and the single trigger that unlocks it, and the prompt-injection / supply-chain guardrails. Use when a host needs to load command-contributing code from a partner, customer plugin, or Labs bundle, or when working ON the deferred `acture-sandbox` package. Triggers on "extension", "plugin", "plugin system", "contribution points", "third-party commands", "extension API", "sandbox", "isolate untrusted code", "iframe sandbox", "QuickJS", "load external commands".

Concrete, file-by-file walk-through for standing up a command-dispatch layer in a NEW PHP project. Covers the state model (cuyz/valinor DTOs + backed enums), the `#[Command]` attribute, a ~120-line attribute-scanning CommandRegistry on top of symfony/messenger, JSON Schema generation via spiral/json-schema-generator, the first CLI surface (Symfony Console 7.3 invokable commands), and Pest architecture tests that enforce the contract. Use after `acture-php` once the project has chosen the greenfield path. Triggers on "new PHP project with commands", "set up command registry in PHP from scratch", "PHP greenfield acture", "Symfony Messenger registry from scratch", "Laravel command registry from scratch", "first PHP command".

Foundational skill for adding a command-dispatch architecture to a PHP project — greenfield or strangler-fig. Maps acture's three primitives (state model, command registry, schema bridge) to the modern PHP stack (cuyz/valinor + symfony/messenger +

Concrete walk-through for adopting a command-dispatch layer in an EXISTING PHP codebase incrementally — the strangler-fig pattern applied to PHP services, controllers, and Artisan/Console commands. Covers the three phases (Wrap → Enrich → Extract), the additive `#[Command]` + `#[AsMessageHandler]` overlay on existing service methods, feature-flagged surface activation, the per-batch tempo (3–5 candidates at a time), and the deletion conditions that retire the legacy code path. Use after `acture-php` once the project has chosen the strangler-fig path against an existing PHP codebase. Triggers on "migrate PHP to command dispatch", "strangler-fig PHP", "wrap controller as command", "wrap service method as command", "incremental PHP refactor", "retire Tactician", "replace Prooph", "feature-flag command dispatch", "introduce command palette to existing PHP app".

Concrete, file-by-file walk-through for standing up a command-dispatch layer in a NEW C# / .NET project. Covers the state model (`record` + `required` + nullable refs), the `[Command]` attribute, a project-owned `CommandRegistry` registered through `IServiceCollection`, the schema bridge built on `System.Text.Json.Schema.JsonSchemaExporter` with a `TransformSchemaNode` delegate that lifts `[Description]` into the JSON Schema, the first CLI surface (`System.CommandLine` 2.0), the projection helpers that expose the same registry as `Microsoft.Extensions.AI` tools AND `ModelContextProtocol` server tools, and xUnit + `CsCheck` architecture tests. Use after `acture-dotnet` once the project has chosen the greenfield path. Triggers on "new C# project with commands", "set up .NET command registry from scratch", "C# greenfield acture", "first .NET command", "wire MEAI tools from scratch", "wire MCP server from scratch", "JsonSchemaExporter description transform", "AIFunction registry", "source-generated command regist

Foundational skill for adding a command-dispatch architecture to a C# / .NET project — greenfield or strangler-fig. Maps acture's three primitives (state model, command registry, schema bridge) to the modern .NET stack (`record` + `required` + nullable refs; a hand-rolled `IServiceCollection`-backed registry or `martinothamar/Mediator`; `System.Text.Json.Schema.JsonSchemaExporter`), names the AIFunction convergence (`Microsoft.Extensions.AI.AIFunction` IS the `CommandRecord` shape and the MCP SDK's `McpClientTool` inherits from it), surfaces the AOT-vs-reflection axis, and routes to the right deeper skill (`acture-dotnet-greenfield`). Triggers on ".NET command dispatch", "C# command bus", "MediatR alternative", "MediatR replaced what", "MCP server C#", "Microsoft.Extensions.AI tool calling", "expose .NET service to MCP", "WPF command palette acture", "ASP.NET command registry", "Blazor command palette", "Wolverine vs Brighter vs MediatR", "JsonSchemaExporter for AI tools", "acture in C#", "acture in .NET", "R

Concrete walk-through for adopting a command-dispatch layer in an EXISTING C# / .NET codebase incrementally — the strangler-fig pattern applied to .NET services, ASP.NET controllers, MediatR handlers, and Worker services. Covers the three phases (Wrap → Enrich → Extract), the additive `[Command]` overlay on existing service methods, feature-flagged surface activation via `Microsoft.FeatureManagement`, the per-batch tempo (3–5 candidates at a time), the YARP + `Microsoft.AspNetCore.SystemWebAdapters` HTTP-level migration for ASP.NET Framework → ASP.NET Core, the MediatR escape path (when an existing project's licence status forces the move), and the deletion conditions that retire the legacy code path. Use after `acture-dotnet` once the project has chosen the strangler-fig path. Triggers on "migrate .NET to command dispatch", "strangler-fig C#", "wrap controller as command", "wrap service method as command", "escape MediatR", "MediatR licence change response", "ASP.NET Framework to ASP.NET Core acture", "YARP

Load the canonical CommandRecord shape and the closed-metadata-surface principle. Use when defining, modifying, reviewing, or extending the CommandRecord interface, when adding a new field, when removing/renaming a field, or when asked about command identity, schema, when-clauses, kind (atomic/handoff), tier, keybindings, or the Result<R> shape. Triggers on "CommandRecord", "defineCommand", "command metadata", "what fields does a command have", "add a field to commands", "the dispatch signature". Do NOT use for palette/UI behavior (load `acture-palette-design`) or migration helpers (load `acture-migration-package`).

The state-model design walkthrough for a greenfield command-dispatch project — deciding what application state EXISTS before authoring any command. Expands Step 1 of the acture-greenfield foundation. Covers the four hard constraints on the state shape (JSON-serializable, typed slices, normalized, stored-vs-derived), the deterministic id-generation pattern, the StateAdapter seam, and what does NOT belong in state. Use when designing or reviewing the state shape of a new acture project. Triggers on "design the state model", "state shape", "what state should the app have", "normalize state", "state slices", "JSON-serializable state", "id generation", "greenfield state".

Build a Python consumer for an acture-mcp-server — a dict-like facade over the Model Context Protocol so Python code can dispatch commands the same way an LLM agent would. Covers the SDK choice (mcp / FastMCP / hand-rolled JSON-RPC), the agent-written vs `acture` (PyPI) package paths, the dict-like Mapping[str, Command] idiom, errors-as-data preservation across the language boundary, the stdio vs streamable-HTTP transport choice, and why a Pydantic-codegen layer is deliberately post-v1. Use when a Python program needs to call commands hosted by an acture-mcp-server, or when working ON the `acture` Python package. Triggers on "Python client", "call acture from Python", "MCP client", "Python facade", "py2mcp", "Python companion".

Build a property-testing consumer surface in a target project — fast-check arbitraries over the command registry, random `CommandSequence`s replayed end-to-end, invariants asserted at the end of each sequence. Covers the property-runner choice (fast-check / hand-rolled), the agent-written vs `acture-test-property` package paths, the Zod-to-arbitrary subset, the end-of-sequence invariant rule, and the counter-example reproducibility contract (shrunk sequence attached to the thrown error). Use when adding property tests / fuzzing over commands, or when working ON the `acture-test-property` package. Triggers on "property testing", "fast-check", "fuzz the registry", "invariant testing", "random command sequences", "shrinking", "counter-example".

Load context on acture's StateAdapter<S> interface (per research-3), the PatchCapableAdapter sub-interface that `acture-undo` consumes, and the strategy of being state-library-agnostic with documented happy-path adapters. Two reference adapters ship: `acture-state-zustand` and `acture-state-redux`. Use when building or modifying a state adapter, when designing the StateAdapter interface, when working on the reference adapters, when integrating acture with a host app's existing store, or when reviewing the get/set/subscribe contract. Triggers on "StateAdapter", "state library", "zustand", "Redux Toolkit", "RTK", "Jotai", "Valtio", "MobX", "Effector", "XState", "state substrate", "patches", "Immer", "produceWithPatches". For the undo subsystem itself, load `acture-undo`.

Build a telemetry consumer surface in a target project — observe every `dispatch` and forward a structured record to a configurable sink. Errors-as-data preserved end-to-end. Covers the sink-library choice (structured logger / OpenTelemetry / network beacon / custom), the agent-written vs `acture-telemetry` package paths, the sampler → redact → sink order, defensive try/catch, and the "telemetry must never break dispatch" rule. Use when adding production observability over commands, or when working ON the `acture-telemetry` package. Triggers on "telemetry", "observability", "log every dispatch", "structured logging", "OpenTelemetry", "network beacon", "audit log", "dispatch tracing".

Build an undo/redo consumer surface in a target project — patch-based, observing the state adapter's `setStateWithPatches` calls and grouping by dispatch boundary. Covers the state-library choice (any `PatchCapableAdapter` — zustand-with-immer, RTK, MST), the agent-written vs `acture-undo` package paths, the transaction model with partial-failure semantics, and the host-callback effect lifecycle (`onEffect(effect, { isUndo, isRedo })`). Use when adding undo/redo to a command-dispatch app, or when working ON the `acture-undo` package. Triggers on "undo", "redo", "patches", "immer", "history", "rollback", "rewind", "time-travel", "transaction", "effects", "PatchCapableAdapter".

Build an AI-tool-calling consumer surface in a target project — project the command registry as LLM function-calling tool definitions so a model can invoke commands. Covers the SDK choice (Vercel AI SDK / Anthropic SDK / OpenAI SDK / LangChain), the schema-projection fork (pass Zod through vs project to JSON Schema), the agent-written vs `acture-ai-vercel` package paths, errors-as-data, and the prompt-injection guardrails. Use when exposing a command-dispatch app to an LLM, or when working ON the `acture-ai-vercel` package. Triggers on "AI tool calling", "LLM function calling", "tool use", "expose commands to an AI", "Vercel AI SDK", "streamText tools", "let the model call commands", "AI agent loop".

Build an end-to-end / integration testing consumer surface in a target project, testing through the command registry. An e2e test is a macro with assertions — a command sequence replayed with state checks. Covers the test-pyramid compilation strategy (one intent, adapters per level), the agent-written path, the optional acture-e2e-playwright package, and that Cypress / Vitest browser mode / other runners are equally valid choices. Use when adding e2e or integration tests that dispatch commands, when wiring a Playwright/Cypress suite to an acture registry, or when working ON the acture-e2e-playwright package. Triggers on "e2e", "end-to-end test", "integration test", "Playwright", "Cypress", "test through commands", "data-command", "test the registry", "command-centric testing".

The foundational pattern for standing up command dispatch in a NEW or greenfield target project — designing the state model, then writing or installing the command registry + dispatcher primitive. Load this when an agent is adding a command-dispatch architecture to a project from scratch (not migrating an existing codebase — that's the migration-* track). It encodes acture's dev-tool-first positioning for the CORE primitive itself: the registry can be ~80 lines the project owns outright (agent-written, zero acture dependency) or `acture` core installed as an optional accelerator — a deliberate per-project choice. Triggers on "build a command-dispatch app", "set up a command registry", "greenfield acture", "command dispatch from scratch", "start a new project with acture", "do I need to install acture core", "hand-write the registry".

The acture pre-merge anti-pattern checklist. Load this before merging any non-trivial change to the acture codebase, before reviewing a PR, or whenever you're about to add a feature, a field, or a package. Catches inner-platform creep, god-packaging, business logic in adapters, React coupling in core, eval of LLM strings, and the other named hard "don'ts" from redesign_takeaways.md §3. Triggers on "review this change", "pre-merge check", "is this an anti-pattern", "should I add this field", "should I create this package", "hard don'ts", "checklist", "merge checklist", "anti-pattern".

Build a macros (record / compose / replay) consumer surface in a target project. A macro is a serializable list of `{commandId, params}` pairs replayed through the registry. Use when a project wants to record user/agent command sequences and replay them — workflows, pipelines, saved actions, AI-composed sequences. There is NO acture-macros package: macros ship as a pattern + skill, hand-written from docs/hand-written-command-sequence.md. Triggers on "macros", "record/replay", "command sequence", "workflow", "pipeline", "saved actions", "replay a sequence", "macro recorder". For e2e testing (a macro with assertions) load acture-e2e instead.

The worked, end-to-end bootstrap for a greenfield command-dispatch project — the concrete file-by-file walk-through of the acture-greenfield foundation's four-step sequence, grounded in the graph-editor worked example. Covers the three core-primitive files (state, registry, commands), the "every mutation flows through dispatch" acceptance criterion and its `rg` audit, the state→registry→commands→consumer ordering discipline, and the recurring hand-write-vs-install decision points. Use when actually standing up a new acture project from scratch. Triggers on "bootstrap acture", "set up a new acture project", "scaffold command dispatch", "greenfield walkthrough", "wire up the registry and commands", "first acture app".

Install acture into an existing app and wire the registry + state adapter without touching legacy code. Use after `migration-plan` and before `migration-wrap`. Triggers on "scaffold acture", "set up the registry", "install acture into this app", "add the migration package". Creates a single `acture/` directory with a registry instance and wraps the existing store as a `StateAdapter`.

Load context on `acture-migration` (Phase 3) — its four-function API per research-4 §A.6 (wrapMutation, actureMiddleware, chooseImplementation, shadowCompare), why divertHandler was dropped, the codemod scope deferred to v1.1, and the migration-track skills (migration-diagnose, migration-plan, migration-scaffold, migration-wrap, migration-graduate). Use when working on the migration package, when writing or rewriting migration skills, when designing the strangler-fig adoption workflow, or when an existing-codebase agent is using acture for the first time. Triggers on "migration", "strangler fig", "wrapMutation", "divertHandler", "chooseImplementation", "shadowCompare", "actureMiddleware", "graduate", "codemods", "ast-grep", "jscodeshift", "ts-morph", "event interception", "legacy mimic".

Load context on acture's command palette design, including the parameterized-command UX (atomic vs. handoff), the auto-derived `kind` heuristic, the per-parameter-count defaults, and the don't-do list. Use when building or modifying `acture-palette-react`, when implementing parameter collection, when reviewing palette UX choices, or when working on form adapters (`acture-forms-autoform`, `acture-forms-rjsf`). Triggers on "command palette", "parameter collection", "atomic vs handoff", "param collector", "cmdk", "kbar", "form adapter", "picker chain", "Ctrl+K". Do NOT use for keybinding-only work (focus on `acture-command-record-shape` for the `keybinding` field).

Load context on acture's API tier system (per research-5) — @stable / @experimental / @internal / @deprecated JSDoc tags, the build-step mirror to the `tier` metadata field, per-tier (not per-feature) runtime opt-in, and the `acture compare-schemas` CLI with description-changes-as-MAJOR-by-default. Use when working on the tier-enforcement build step, the runtime gating in registry.toMCPServer/toAITools, the deprecation banner prefixing, the @internal symbol-token enforcement, the schema diff CLI, or when reviewing API stability commitments. Triggers on "tier system", "stable", "experimental", "internal", "deprecated", "compare-schemas", "schema versioning", "breaking change", "JSDoc tag", "API stability", "@stable", "MCP tool versioning", "SEP-1575".

Retire `wrapMutation` calls once the legacy handler is no longer needed — collapse the wrapper into the command's execute, or delete the wrapper and let the command be authored directly with `defineCommand`. The final step in the strangler-fig metaphor — "let the host die." Use after `migration-wrap` when the wrapped commands have been in use for a while and the legacy call sites have been deleted or rerouted. Triggers on "graduate", "retire wrapMutation", "remove the wrapper", "promote to defineCommand", "strangler-fig endgame".

Turn a diagnosis report into a phased adoption backlog with effort estimates and explicit configuration decisions. Use after `migration-diagnose` and before `migration-scaffold`. Triggers on "plan the migration", "prioritize candidates", "phase the migration", "adoption backlog". Surfaces decisions for the user (id prefix, categories, scope) instead of guessing.

Wrap one or more existing handlers / store actions as acture commands using acture-migration's `wrapMutation`. Use after `migration-scaffold`. Triggers on "wrap this handler", "register as a command", "wrap onClick", "convert this action to a command", "use wrapMutation". The fourth skill in the migration track. Wraps incrementally without touching the legacy call site.

Scan an existing codebase for acture command candidates — event handlers, store actions, async thunks, API calls. Use when a Claude Code agent is starting to adopt acture in an app that already has its own state library and UI. Triggers on "diagnose", "find command candidates", "what should I wrap", "audit handlers", "scan for migration". First skill in the migration track (diagnose → plan → scaffold → wrap → graduate). Does NOT modify any files.