Events

Key Ideas

• Activity Selects Work: Events connect system activity or an explicit user request to reusable Skills.
• One Shared Capability: workflow, CLI, browser, API, and MCP use the same definitions, parameter resolution, execution, and evidence.
• Explicit Scope: project definitions apply across nodes; node definitions and binding overrides identify their node explicitly.
• Durable Occurrences: a workflow transition or manual request identifies one occurrence. Restart and transport retries reuse its evidence.
• Bounded Execution: managed process admission, cancellation, timeouts, and checkout serialization apply to Event agents.

Purpose

Events are internal system occurrences; Skills are the configuration surface for choosing when work happens. They replace separate Governance, Quality, and Guidance configuration with a common way to connect instructions to workflow and lifecycle activity. There are no user-created Event entities in the UI or CLI. The shared Custom trigger allows users to run one selected Skill.

Expected Role

The initial system catalog contains Enter and Exit for Backlog, Todo, Plan, Implement, Quality, Governance, Review, Done, Failed, and Cancelled, plus node.startup.ready. Startup means the node daemon has become ready. State synchronization is deliberately absent from the trigger catalog.

An Event contains ordered Skill bindings. Blocking results gate normal progression, background results provide nonblocking evidence, and context attachments supply Skill instructions without launching another agent. Each agent receives the same pinned occurrence context, its parameters, and applicable attachments. A prior binding’s response is not injected into the next binding. A gate requires a valid successful result for every applicable pinned blocking binding. Execution state remains separate: a background failure or error stays visible without vetoing satisfied blocking requirements. Pending missing evidence waits; cancellation, terminal missing evidence, and invalid result contracts are faults. Missing results identify the invocation and binding as an actionable error; an empty or partial result collection cannot authorize progression. A failed blocking finding fails the collective gate; provider and contract faults remain execution errors.

Normal transitions wait for applicable gates. A user-requested transition retains its intent and source state while Exit gates run. Cancel and failure transitions proceed immediately and cannot be vetoed by a hook. Entry generations distinguish a later retry from a transport retry. A supported success action may explicitly request Start, Accept, Retry, or Reopen; the default is no additional lifecycle action. Actions retain receipts, reuse the existing transition capability, and stop automatic action chains after sixteen steps until a new manual trigger.

Skills declare text, number, boolean, or choice parameters, optional requirements, and defaults. Skill inputs can refer to goal.*, system.*, or event.* fields. The trigger determines the expected result: Plan, Implement, Quality, and Governance entry supply their workflow contracts; manual and other occurrences supply Task results. The browser collects manual input before opening an agent tab; interactive CLI calls collect missing required values before a supervised run. Manual Skill launches carry no Goal or Goal action. Automatic missing input records a visible execution error rather than waiting for user input. Unknown inputs, invalid types, and inconsistent definitions fail before agent launch.

Configuration lives in the project state as one revision-fenced Events/Skills document and synchronizes through refine-state. Node overrides replace a named project binding; disabling an override suppresses that binding on that node without hiding unrelated bindings. Disjoint configuration edits merge structurally with a new revision; contested edits and broken references stay conflicted. Invocation snapshots retain the configuration and inputs that actually launched work. Editing a definition affects future invocations. Manual transitions retain the Entry occurrence and requested Exit configuration separately, including when a Skill moves to a different trigger.

Goal phase agents use the admitted implementation or exact-candidate worktree. Executable Backlog and Todo Enter/Exit Skills use an invocation-owned managed linked checkout, including before an implementation branch exists. Refine pins repository, Goal, current Round and authored request, node, event source, transition (including a claimed Todo-to-Plan transition) or durable occurrence, configured target ref and resolved source commit before materialization. The source comes from that target, independently of the primary checkout’s HEAD. Physical registration is persisted before launch; cwd, System workspace and workspace-derived parameters identify the same checkout, with any agent subpath canonically contained inside it. Work without a Goal retains its explicit selected checkout. Managed checkout access is serialized. Background means its verdict does not gate progression; it does not grant concurrent mutation of a shared checkout. The existing worker admits queued work against runtime capacity and pause policy. Invocation evidence retains results, invalid attempts, process references, and cancellation. Process registration uses the same cancellation fence as managed operations, and callbacks revalidate Goal, Round, candidate, and node authority.

Failed and Cancelled Enter/Exit Skills also use invocation-owned lifecycle workspaces when a Goal stops before any implementation workspace is recorded. Existing implementation evidence continues to require its recorded managed checkout. Forced cancellation or failure settles immediately, before its terminal Entry Skills execute.

Lifecycle checkout creation never sets Goal implementation branch, base or candidate fields. Disabled and context-only bindings need no checkout. Ordered bindings, diagnostic repairs and recovered invocations reuse the pinned registration and retain dirty work; an interrupted creation without registration proof fails visibly when its branch or path already exists. Launch, result acceptance, cached-success reuse and transition settlement recheck the current authority and original registration. Scheduler and manual settlement retain required invocation and binding identities and their original workspace commitments independently of results, then reread completion after later Skills finish. Failed and cancelled records remain terminal evidence and are neither rewritten nor relaunched to satisfy the gate. Cancellation remains immediate, and only applicable blocking bindings delay settlement. No Goal lock is held while an agent runs.

The capability routes are /event-definitions, /skills, and /event-invocations. /events retains its existing streaming meaning. The public CLI exposes only skills, including trigger discovery, configuration, cloning, manual launch, history, and cancellation. Controls and the command palette discover Custom Skills dynamically. Web manual runs reuse managed terminal sessions and their transcript and process evidence; automatic and CLI runs retain invocation evidence. Internal Event routes remain available for compatibility and evidence inspection.

Future Direction

Add system sources only when they represent a useful, bounded semantic occurrence. Future delivery policies and richer parameter sources should compose with the existing worker, ownership, and evidence contracts rather than introduce another scheduler.