ObneyAI/orc / orc-skills/orc-grain-application
orc-grain-application
VerifiedModel and implement the Grain application around an ORC tree: domain commands, events, processors, periodic triggers, projections, queries, tenant scoping, authorization, and Event Model topology. Use when ORC actions must persist domain facts or serve production reads.
Build the application around the tree
ORC already emits its own execution events. Use Grain for domain facts and application workflows around ORC: a code action may issue a command, a processor may start a tree after an event, and a query may combine domain projections with ORC execution projections. Keep domain policy in commands and Allium rules; a blackboard value alone is not a committed domain fact.
Check the application’s instructions if provided, the current ORC/Grain revisions, and contracts.md before implementing. This skill is about the Grain substrate; use orc-design-tree for tree design and orc-runtime-bootstrap for boot wiring. ORC also tracks the schema, command, read-model, query, processor and periodic-task skills. For deeper Grain guidance, use the public Grain skill collection, including the Grain engineering entry point and Event Model skill. That collection also covers Event Model elicitation, distillation, propagation, tending and reconciliation. To read those skills locally, give the agent access to a Grain checkout alongside ORC. Adding Grain as a library dependency does not automatically configure discovery of its agent skills. These public companion skills add depth; the bundled contracts reference remains usable without a personal skill installation.
Shape the write and read sides
- Name an actor intent, the invariant it must uphold, immutable resulting event(s), and the exact read projection that can prove the outcome. Put acceptance behavior in Allium; keep Event Model as topology and link it to the relevant rule/surface.
- Register Malli command/query schemas and event-body schemas.
defcommandchecks current state through a read model and returns:command-result/eventsbuilt with v3->event; the v3 append assigns event IDs and timestamps. No direct/bare append from an ORC code node or processor for a domain command. defreadmodelis a pure reducer over named event types.defqueryreads projections and returns:query/result. Exposed commands and queries need an explicit:authorized?predicate evaluated by the request adapter, or an explicit guard at the host/handler boundary. Direct command/query processors do not execute that metadata. Bind identity and tenant from trusted host context, then actually check their authority; claims alone are data, not enforcement.defprocessorreacts to a durable event and issues a command or performs a declared effect. Choose checkpoint-before or checkpoint-after according to the actual duplicate/loss tradeoff; make at-least-once external effects idempotent. Avoid read-state → decide → write races during concurrent events; use the event-store CAS or a domain idempotency key where required.defperiodicemits trigger events; use an explicit:result/casguard when a schedule tick must be deduplicated. Its processor does the work.- Prove from the public path: command → event → projection → query, plus processor/schedule when present. Read the projection back under the same tenant and test a second tenant's isolation. Test duplicate triggers, restart/replay, and authorization denial where those are real risks. A successful command return is not enough.
Keep generated handler vars distinct within a namespace. Several declaration macros generate <service>-<name>: defreadmodel :app results and defquery :app results both define app-results; defperiodic :app refresh and defprocessor :app refresh both define app-refresh with different arities. A later declaration can overwrite the function behind an already registered Var. Use distinct names or namespaces, such as tool-results/results and refresh/process-refresh, and exercise every registered path. Direct processor calls need full command/query envelopes with UUID IDs and offset-date-time timestamps. Tool capabilities using direct calls must enforce authority before effects and reads. Verify denial through the path actually used by the action. ORC query authorization metadata examines :auth-claims when an enforcing boundary evaluates it; supplying those claims to a direct processor does not perform the check.
Use contracts.md for current macro shapes, Event Model edges, and a concrete verification scenario. When observable behavior changes in ORC, follow its Allium loop, diagnostic baseline, and spec-integrated inspection gate; do not treat a clean test process exit as proof that specifications and projections agree.
Keep file/network effects out of a command handler's decision body: constructing its returned events must not itself write a file or call an external service. For durable work, record intent and execute through an owned processor/capability with appropriate idempotency and reconciliation. A deliberately synchronous experiment may call a guarded host capability and then record its actual observation through a command, but the external effect and event append are not atomic. Preserve that limit; a receipt projection alone does not prove crash-safe exactly-once execution.
Skill check
Try: “A successful recommendation-tree run should record a proposal for tenant A, then expose proposals through a query. A daily process may request refreshes, but duplicate triggers must not create duplicate proposals.” A satisfactory design names commands/events, validates the durable proposal state, routes ORC code through a command, projects and queries per tenant, makes the scheduler a trigger, handles idempotency, links topology to Allium, and tests output plus read-back. The skill must not invent the app's business eligibility rules.
Durable quality reporting
Read orc-judges for immutable assessment manifests and banded result reporting. Use commands to record expected assessments and typed scored/failed/ungradable outcomes, then project tenant-scoped coverage, bands and available feedback by actual scope/model/rubric filters. Validate concurrent replay against the exact persisted payload. Rebuild from events in a fresh process. An application reporting sample does not supply a native durable judge worker scheduler or holistic tree grade.
Current decisions and tools
At ORC 1851212396cced2fc4533fda30b824bd4b691390, use decision models for one-answer boolean/Choice nodes and registered native providers, and tools for authored tool leaves and enforced code/tool/researcher contracts. Delegate context, family budgets/usage and execution leases are integrated. Native Score still needs a custom client; these updates do not repair judge jobs, attachment, evidence scopes or score identity. Contracts do not replace authorized domain commands or callee idempotency.
Terminal execution reporting
For a durable application outcome when a root exhausts its execution paths, read terminal execution outcomes. Keep retained work, failed execution and semantic goal assessment distinct; use canonical ownership and an idempotent Grain processor/command path.
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: 196k | 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: 193k | 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: 193k | 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: 193k | Updated | Claude CodeCodex | Verified | Install |