skills/kora-workflow-builder/SKILL.md

---
name: kora-workflow-builder
description: "Read when creating or changing Kora workflow release source: org-model resources, capabilities, operations, decisions, workflows, service scripts, runtime SDK calls, managed artifacts, validation, release creation, or deployment follow-up. Not for extension package authoring, product UI route lookup, platform inspection, or exact schema lookup."
---

# Kora Workflow Builder

Use this skill when the user wants to create or change workflow release source:
add a role, add a person, introduce a capability, restructure resources, design
a workflow, create an operation, connect service code to an installed extension,
or make a workflow handle runtime inputs, outputs, and managed artifacts.

Describe planned and completed work in product terms -- what the workflow does --
not filenames, paths, YAML kinds, script languages, or runtime SDK wiring, unless
the user asks for implementation detail or you are explaining a failure.

Keep validation and repair loops internal: report the product behavior, the
checks that passed, and only the diagnostics that need user input.

Test results are authoritative. A passed source-validation phase does not
override a failed node execution. Do not infer that an execution-host,
provider, or configuration error is transient; describe it as retryable only
when the structured result explicitly says so. A failed, invalid, or skipped
node test blocks readiness, release creation, and deployment unless the user
explicitly accepts that exact failure after a clear warning.

Do not offer provider-specific destinations such as Slack or email unless the
user named that provider, extension discovery shows the resolved environment
supports it, or the user is explicitly planning missing extension setup. Before
discovery, use generic destinations: run output, a modeled human task, or an
installed extension if available.

This skill is a table of contents. Read the smallest reference that answers the
next question. For exact resource fields, use `kora schema get <resource>
--json`; the CLI schema wins over prose. Schema resource names are lowercase
registry names such as `process`, `operation`, `capability`, and `decision`,
not YAML `kind` values. The user-facing Workflow is authored with the source
schema name `process` and YAML `kind: Process`.

Fresh workflow source has a schema preflight. Before writing a new bundle from
an empty workspace, either start from the complete minimal service workflow in
`references/patterns-and-examples.md` or query the current schemas first:
`manifest`, `organization`, `assignments`, `operation`, and `process`. Query
`role`, `person`, `agent`, `capability`, and `decision` as needed before using
those resources. Use `kora schema get <schema-name> --json` once per schema.
The schema name for `kora.yaml` is `manifest`, not `project`.

## Core Mental Model

The chat source workspace is the source editing area for workflow source files. It may start empty.
The first durable server-side artifact is created with
`kora release create <dir> --json`. Release creation does not create a live
deployment. The target product path is release creation followed by explicit
environment deployment. A deployment is a full release snapshot for that
environment: deploying a release that contains only one new workflow removes any
other workflows from that environment's live set.

Default source resolution:

1. If the workspace already has source files, inspect and edit that workspace
   source.
2. For fresh creation with no existing workspace source, author in the chat
   workspace.
3. For read, add, or modify requests against existing product behavior or
   source, do not guess from an empty workspace. Resolve the intended
   environment from the user request first. If the user names `test`, `staging`,
   `production`, or another environment, use it. Otherwise inspect
   `kora environment list --json`. If exactly one environment exists, use it as
   the default resolved environment; if multiple environments exist, ask which
   environment before materializing release source.
4. For the resolved environment, inspect
   `kora deployment list --environment <environment> --json`.
5. If it has a live deployment, use that live deployment's release as the default
   source and write the frozen source into the workspace with
   `kora release source <release> --out <empty-temp-dir> --json`. Then copy the
   exported files into the chat workspace root before editing.
6. Do not keep edits under temporary folders such as `source/`, `src/`, or
   `project/`; edit workspace-root paths like `org/...`, `processes/...`, and
   `scripts/...` directly.
7. If it has no live deployment, say there is no live release to modify and
   continue only with fresh source or a user-named release.

For read-only inspection of already-created workflow or org-model facts, use
the CLI's release snapshot selectors instead of materializing source:
`--release <release>` for a named immutable release, or
`--environment <environment>` for the selected environment's current live
deployment release.

When adding to an environment that already has a live deployment, start from the
live release source. Before deploying, compare workflow lists; if the new
release drops existing workflows, stop and ask whether removal is intended.

Every workflow source bundle has seven layers you may touch:

1. who does the work: people, agents, roles, assignments
2. what work exists: capabilities and operations
3. how work flows: workflows
4. what external events enter the flow: trigger resources that target workflow messages
5. what external behavior exists: installed extensions, operations, and service scripts
6. what rules apply: decisions
7. what runtime assets support execution: templates, scripts, schemas, docs

Human and agent task nodes depend on this runtime chain:

`role -> capability -> assignment -> workflow task`

If any link is inconsistent, the workflow will not resolve at runtime.
Service nodes are different: they call an `Operation` and do not need roles,
capabilities, agents, or assignments unless the workflow also has human/agent
task nodes. Still create `org/assignments.yaml` for every fresh source bundle; use an
empty `spec.roles: {}` registry when the workflow has no human or agent tasks.

## Runtime Boundary

- The workspace is the proposal surface for authored source -- YAML resources,
  service scripts, templates, and source docs. It is not the live runtime; use
  it for source editing and smoke tests only.
- Extension package source uses the `kora-extension-builder` skill and the
  extension lifecycle, not workflow release source.
- Temporary files, generated outputs, and smoke-test artifacts may exist while
  authoring, but only files accepted by release creation become deployment
  entries.
- Files provided during a conversation are unclassified workspace/input files;
  use them as message context. Copy one into release source only when the user
  explicitly asks; upload it as a managed runtime artifact only when the user
  explicitly asks to use it as workflow/run input.
- `kora` is an authoring and inspection tool, not available inside live
  workflows, operations, scripts, or agent prompts. Do not put `kora` commands
  in workflow YAML, scripts, operations, or agent prompts.
- Service operation scripts run in a separate runtime sandbox with released
  files mounted read-only at `/workspace`. Package installs, node_modules,
  virtualenvs, caches, and build output created while authoring are scratch
  state unless the source bundle has an explicit deterministic packaging
  strategy.

## Environment Discipline

Resolve the intended environment once (see Core Mental Model). Use that same
environment for extension discovery, contract fetches, node tests, release
validation, deployment, and run commands. Do not discover an extension in one
environment and test, release, deploy, or run against another.

For extension-backed service work:

- Verify the selected extension is installed in the resolved environment and
  that `kora extensions get ... --json` reports `state: "ready"`.
- If it is `setup_required`, route the user to Settings setup before publishing
  or running workflow code. If it is `disabled`, tell the user it must be
  enabled. Use the returned `message` as the user-facing explanation.
- If a required provider-backed extension is not installed and ready, stop and
  tell the user exactly which extension/setup is missing. Do not write
  placeholder provider operations, do not substitute unauthenticated direct API
  calls, and do not publish a workflow you expect to fail unless the user
  explicitly asks to continue after that warning.
- To inspect current provider data before authoring, invoke one ready installed
  extension function (`kora extensions invoke <extension-name> <function-name>
  --environment <environment> --input @input.json --yes --json`) after fetching
  its exact schema. Do not create throwaway workflow source just to inspect
  provider data.

## Service Operation Rules

Script-backed service nodes invoke an `Operation`.

- Service scripts import `@kora/runtime-sdk` and use `getInput`,
  `extensions.invoke`, and `emitOutput` for operation input, installed
  extension functions, and stdout JSON. Cloud-backed providers are still
  installed extensions from the script perspective.
- For installed extension calls, normalize the extension response into the
  operation's own stdout shape; do not rely on optional extension fields being
  present or non-null.
- Registered extension function descriptions and schemas are the source of truth
  when authoring operations that call them.
- `paramBindings` shape operation stdin before the script runs.
- Runtime variables and org secrets are declared with `spec.bindings.env` and
  `spec.bindings.secrets`; names and injected env vars must not use the
  reserved `KORA_` prefix.
- Operation scripts can call functions exposed through
  `spec.bindings.extensions`, but they do not read extension storage or
  extension secrets directly.
- When `spec.script.parseStdoutAsJson` is true or omitted, stdout must contain
  exactly one valid JSON value. Log diagnostics to stderr.
- `resultMapping` maps emitted stdout into the service node's declared output.
  Without `resultMapping`, script stdout must be a JSON object that can shallow
  merge into workflow state.
- Optional `resultMapping` fields are skipped only when the source path is
  absent. A present `null` value is mapped and must validate.
- Managed artifact files are separate from stdout. Scripts read artifact inputs
  and write declared artifact outputs through `KORA_ARTIFACT_MANIFEST`
  `localPath` entries; do not persist manifest local paths into workflow state.

## Typical Project Layout

```text
kora.yaml
org/
  org.yaml
  roles/<name>.yaml
  people/<name>.yaml
  agents/<name>.yaml
  assignments.yaml
capabilities/
processes/
operations/
decisions/
triggers/
scripts/
templates/
```

Keep entity names in resource `metadata`, not inferred from filenames.

## Build Order

When creating source from scratch or deliberately restructuring it, prefer
this order so references resolve cleanly. Complete the fresh workflow source
schema preflight before writing the first file.

1. source manifest (`kora.yaml`) and organization (`org/org.yaml`)
2. `org/assignments.yaml` with `spec.roles: {}` for every new source bundle
3. roles, people, agents, and assignment entries only when human/agent tasks need them
4. capabilities
5. installed extensions, operations, and service scripts
6. decisions
7. workflows
8. triggers that bind installed extension events to exactly one workflow message
   start
9. optional templates and supporting docs

## Authoring Discipline

Before editing:

- Inspect the current workspace before assuming files exist.
- Check `kora.yaml` and the target area directly before scaffolding foundational
  files.
- `read` or `ls` the area you plan to change.
- `grep` for references before renaming or deleting anything.

While editing:

- When the user gives a clear intent but omits incidental details, draft a valid
  minimal workflow with reasonable names and a simple message/manual start
  instead of stopping for clarification.
- Keep changes small and scoped.
- Every capability must define at least one of `spec.humanConfig` or
  `spec.agentConfig`. For capability work a person can perform, include at least
  `humanConfig: {}` even when no optional human guidance fields are needed.
- For workflows, author the data contract first. Define `types:` and use only
  the node fields the schema supports.
- Author every workflow as a Process source document under `processes/`, with
  `kind: Process`. `kind: Workflow` and `workflows/` are not source aliases;
  Platform owns internal organization scope injection.
- Treat workflow state as an accumulated top-level object. Each typed node
  output shallow-merges into state.
- Use message starts or `receive` nodes for workflow-level message consumption.
  Use `triggers/*.yaml` only when an installed extension event should start a
  workflow through exactly one message start. Triggers do not resume `receive`
  nodes. A workflow invoked by `call` or
  `call.each` needs a callable manual start marked `internal: true`; call nodes
  name the child with `process`, not `workflow`.
- Use `task.each` or `call.each` for runtime collections.
- For agent output review, put `requiresOutputReview: true` on the producer
  capability and `agentOutputReview` on each ordinary producer `task`. Point it
  directly to an explicit human task; keep approve, reject, revise, apply, and
  escalation behavior in ordinary nodes and gateways. The producer object
  output type must set top-level `additionalProperties: false`. Read
  `references/workflow-flow-nodes.md` before authoring this pattern.
- Use ordinary `next` to a human task when review applies regardless of whether
  the producer is assigned to a person or an agent. Do not use output review as
  tool-call or side-effect authorization; put irreversible actions after an
  explicit human decision.
- Use `call.each` to a child workflow containing producer and review tasks when
  each collection item needs review. A review-required capability is invalid on
  `task.each`.
- For agent tasks that handle file content, use node-level `promptAttachments`
  on `task` / `task.each` for selected top-level file artifact input fields.
  Prefer an earlier extractor service node for PDFs, Office docs, HTML, ZIPs, or
  other binary/rich attachments; attach only the extracted text or image
  artifact to the agent prompt.
- Make operation `resultMapping` and the declared workflow service-node
  `output` type agree.
- Model expected absence explicitly. Optional means absent from the object, not
  `null`, unless the schema deliberately allows `null`.

After meaningful changes:

- There is no validation-only command for uncreated source. Do not invent `kora release
  create --dry-run`, `kora release validate-source`, or similar commands, and
  do not create a release merely to validate a source-only proposal. Inspect
  the touched files and references, run applicable targeted checks, and state
  that full source validation remains deferred until requested release
  creation.
- Run `kora test node <workflow-name> <node-id> --workspace <dir> --input @input.json --environment <environment> --json`
  for touched executable service nodes when you can supply meaningful node
  input.
  Use this before claiming artifact-producing nodes are verified; release
  creation and deployment do not prove artifact capture.
- If a node test ends without an exit code because it was cancelled or timed
  out, do not retry the same node with different workspace or input-path
  variants. Report that targeted check as unverified once.
- Use `kora release create <dir> --json` only when the user asks to create a
  release artifact from source. Then:
  1. Treat release-source or release-readiness diagnostics from that command as
     must-fix items before deployment.
  2. When it succeeds, tell the user the release was created, that it is not live
     yet, and route them with a Markdown link such as
     `[release detail](/app/releases/<release>)`.
  3. Inspect `kora environment list --json` before offering deployment follow-up.
     If exactly one environment is available, default to that named environment
     and ask whether to deploy there. If multiple environments are available, ask
     which environment should receive the release.
  4. Use `kora release validate <release> --environment <environment> --json` to
     check one environment's readiness.
  5. Use `kora environment deploy <environment> <release> --json` only when the
     user asks to deploy a release, and name the target environment in your
     confirmation.
  6. If deployment runs a source-defined workflow-node test gate, report the
     pass count, rate, mode, and threshold from the response. A blocked gate
     leaves the previous deployment live; do not retry with an override or
     claim the release is deployed.
- If a workflow-node smoke test fails, do not publish or deploy unless the user
  explicitly says to proceed anyway after you warn that the workflow is likely
  to fail. Classify the failure before responding: source/validation error,
  missing extension/binding/grant, missing connection/credential, extension
  runtime error, or provider/API error.
- For operations that call installed extension functions, use the visible
  installed-extension discovery commands. Use the `kora-extension-builder`
  skill only when a new extension package source is needed. Release creation
  does not publish, install, or grant extensions; extension package and
  install lifecycle actions are admin/product workflows outside workflow source.
- Do not ask the user to test anything you can safely test yourself in the
  current authoring environment.
- If testing requires user authorization, missing business input, or real
  changes in connected systems, say exactly what remains untested and what user
  action is needed.
- Do not claim release readiness until the requested release creation or
  explicit release validation is clean. Release creation is not a substitute
  for workflow-node smoke tests.
- When reporting success to the user, keep checks and user-visible behavior in
  the foreground. Avoid implementation bullets for scripts, YAML files, runtime
  SDK calls, or command mechanics unless the user asks for them.

Cascading/destructive changes:

- Identify dependents first with `grep`.
- Tell the user what will be affected.
- Get explicit confirmation before destructive removals.
- Update references in one pass, then inspect the updated references and run
  applicable targeted checks.

Reminder: real org membership, runtime facts, workflow runs, tasks, releases,
runtime variables, workflow artifacts, and resource schemas are not in the
workspace. Use `kora` for those.

## Which Reference To Read Next

- `references/org-model-resources.md` — modeled people, roles, agents, and
  assignments
- `references/capability-resource.md` — capability resource shape
- `references/workflow-flow-nodes.md` — workflow node types and flow rules
- `references/patterns-and-examples.md` — common workflow patterns and one
  complete current project example
- `references/installed-extension-discovery.md` — find installed extensions,
  search functions/tools/skills, and fetch one exact callable contract
- `references/operation-and-extension-resources.md` — operations, service
  scripts, and runtime SDK bindings for selected extension functions
- `references/service-io.md` — operation stdin, stdout, `emitOutput`, and
  `resultMapping`
- `references/artifacts.md` — managed artifact declarations, manifests, and
  send-template artifact URLs
- `references/credentials.md` — runtime variables, org-secret bindings, and
  extension secret boundaries
- `references/filesystem.md` — live runtime filesystem and dependency
  availability
- `references/testing.md` — workflow-node and artifact smoke-test routing
- `references/decision-resource.md` — decision resource shape
- `references/agent-config.md` — agent-specific modeling
- `references/yaml-resource-schemas.md` — YAML shape companion

## Typical Task Routing

- "Where should this resource live?" -> `references/org-model-resources.md`
- "How should this workflow be structured?" ->
  `references/workflow-flow-nodes.md`, then
  `references/patterns-and-examples.md`
- "How does a workflow call external behavior?" ->
  `references/installed-extension-discovery.md`, then
  `references/operation-and-extension-resources.md`, then `references/service-io.md`
- "What extension function/tool/skill should this workflow use?" ->
  `references/installed-extension-discovery.md`
- "How should this service script read input or emit output?" ->
  `references/service-io.md`
- "How should this workflow use files or folders at runtime?" ->
  `references/artifacts.md`, then `references/filesystem.md`
- "How should this node be tested?" -> `references/testing.md`
- "What exact fields does resource X support?" ->
  `kora schema get <resource> --json`
- "What is already modeled in this source proposal?" -> inspect the workspace
  files directly

## Out Of Scope

- Extension package authoring, publishing, installing, updating, and granting ->
  the `kora-extension-builder` skill.
- Product UI route lookup, menus, tabs, buttons, and user navigation ->
  the `kora-product-ui` skill.
- Platform inspection -> `kora` with the matching family, driven by the
  bootstrap source-of-truth map.
- Exact resource fields -> `kora schema get <resource> --json`, not skill
  prose.