ObneyAI/orc / .claude/skills/grain-command-handler
grain-command-handler
VerifiedImplement command handlers that validate state and emit events using the Grain framework
Grain Command Handler Pattern
Required Imports
(ns my.service.core.commands
(:require [ai.obney.grain.event-store-v3.interface :refer [->event]]
[ai.obney.grain.command-processor-v2.interface :refer [defcommand]]
[ai.obney.grain.command-processor-v2.interface :as cp]
[ai.obney.grain.time.interface :as time]
[my.service.core.read-models :as rm]
[cognitect.anomalies :as anom]))
Command Template
(defcommand :service command-name
"Docstring describing what the command does."
[{{:keys [entity-id field1 field2]} :command
:as ctx}]
;; 1. Read current state from read models (pass ctx, NOT bare event-store)
(let [entity (rm/get-entity ctx entity-id)]
(cond
;; Return anomaly for validation failures
(not entity)
{::anom/category ::anom/not-found
::anom/message "Entity not found"}
(not (:active entity))
{::anom/category ::anom/conflict
::anom/message "Cannot modify inactive entity"}
;; Success: return events
:else
{:command-result/events
[(->event
{:type :service/entity-updated
:tags #{[:entity entity-id]}
:body {:entity-id entity-id
:field1 field1
:field2 field2
:modified-at (str (time/now))}})]})))
Key Variations
Success with Events Only
{:command-result/events
[(->event {:type :service/thing-created
:tags #{[:thing thing-id]}
:body {:thing-id thing-id :name name}})]}
Anomaly Return (Error)
{::anom/category ::anom/conflict
::anom/message "Name already taken."}
CAS (Optimistic Concurrency)
Prevents races by checking state hasn't changed between read and write:
{:command-result/events [...]
:command-result/cas {:types thing-event-types
:predicate-fn (fn [_events]
(= :active (:status (rm/get-thing ctx id))))}}
Calling Other Commands
(let [result (cp/process-command
(assoc ctx :command {:command/id (random-uuid)
:command/timestamp (time/now)
:command/name :other/command-name
:field1 value1}))]
;; result is either anomaly or {:command-result/events [...]}
result)
Common Anomaly Categories
::anom/not-found-- resource does not exist::anom/conflict-- business rule violation (duplicate, invalid state)::anom/incorrect-- bad input data::anom/forbidden-- not authorized for this action
Conventions
- Commands modify state by emitting events; never write to a database directly
- Always validate via read models before emitting events
- Read model helpers take
ctx(the full context), not bareevent-store - Tag events with
#{[:entity entity-id]}for efficient filtered reads - Return anomalies for all error cases
- Include
modified-atin event bodies when relevant
Reference Files
components/orc-service/src/ai/obney/orc/orc_service/core/commands.clj-- ORC sheet commandscomponents/colbert/src/ai/obney/orc/colbert/core/commands.clj-- ColBERT commandscomponents/ontology/src/ai/obney/orc/ontology/core/commands.clj-- Ontology commands
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |