Update to Kora

{
  "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.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 320
    },
    {
      "relative_path": "assets/kora-mark.png",
      "size_in_bytes": 24826
    },
    {
      "relative_path": "references/agent-config.md",
      "size_in_bytes": 5084
    },
    {
      "relative_path": "references/artifacts.md",
      "size_in_bytes": 7037
    },
    {
      "relative_path": "references/capability-resource.md",
      "size_in_bytes": 2459
    },
    {
      "relative_path": "references/credentials.md",
      "size_in_bytes": 2185
    },
    {
      "relative_path": "references/decision-resource.md",
      "size_in_bytes": 643
    },
    {
      "relative_path": "references/filesystem.md",
      "size_in_bytes": 2641
    },
    {
      "relative_path": "references/installed-extension-discovery.md",
      "size_in_bytes": 6128
    },
    {
      "relative_path": "references/operation-and-extension-resources.md",
      "size_in_bytes": 3254
    },
    {
      "relative_path": "references/org-model-resources.md",
      "size_in_bytes": 1308
    },
    {
      "relative_path": "references/patterns-and-examples.md",
      "size_in_bytes": 4462
    },
    {
      "relative_path": "references/service-io.md",
      "size_in_bytes": 4801
    },
    {
      "relative_path": "references/testing.md",
      "size_in_bytes": 4124
    },
    {
      "relative_path": "references/workflow-flow-nodes.md",
      "size_in_bytes": 7455
    },
    {
      "relative_path": "references/yaml-resource-schemas.md",
      "size_in_bytes": 8587
    }
  ],
  "name": "kora-workflow-builder",
  "skill_md_contents": "---\nname: kora-workflow-builder\ndescription: \"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.\"\n---\n\n# Kora Workflow Builder\n\nUse this skill when the user wants to create or change workflow release source:\nadd a role, add a person, introduce a capability, restructure resources, design\na workflow, create an operation, connect service code to an installed extension,\nor make a workflow handle runtime inputs, outputs, and managed artifacts.\n\nDescribe planned and completed work in product terms -- what the workflow does --\nnot filenames, paths, YAML kinds, script languages, or runtime SDK wiring, unless\nthe user asks for implementation detail or you are explaining a failure.\n\nKeep validation and repair loops internal: report the product behavior, the\nchecks that passed, and only the diagnostics that need user input.\n\nTest results are authoritative. A passed source-validation phase does not\noverride a failed node execution. Do not infer that an execution-host,\nprovider, or configuration error is transient; describe it as retryable only\nwhen the structured result explicitly says so. A failed, invalid, or skipped\nnode test blocks readiness, release creation, and deployment unless the user\nexplicitly accepts that exact failure after a clear warning.\n\nDo not offer provider-specific destinations such as Slack or email unless the\nuser named that provider, extension discovery shows the resolved environment\nsupports it, or the user is explicitly planning missing extension setup. Before\ndiscovery, use generic destinations: run output, a modeled human task, or an\ninstalled extension if available.\n\nThis skill is a table of contents. Read the smallest reference that answers the\nnext question. For exact resource fields, use `kora schema get <resource>\n--json`; the CLI schema wins over prose. Schema resource names are lowercase\nregistry names such as `process`, `operation`, `capability`, and `decision`,\nnot YAML `kind` values. The user-facing Workflow is authored with the source\nschema name `process` and YAML `kind: Process`.\n\nFresh workflow source has a schema preflight. Before writing a new bundle from\nan empty workspace, either start from the complete minimal service workflow in\n`references/patterns-and-examples.md` or query the current schemas first:\n`manifest`, `organization`, `assignments`, `operation`, and `process`. Query\n`role`, `person`, `agent`, `capability`, and `decision` as needed before using\nthose resources. Use `kora schema get <schema-name> --json` once per schema.\nThe schema name for `kora.yaml` is `manifest`, not `project`.\n\n## Core Mental Model\n\nThe chat source workspace is the source editing area for workflow source files. It may start empty.\nThe first durable server-side artifact is created with\n`kora release create <dir> --json`. Release creation does not create a live\ndeployment. The target product path is release creation followed by explicit\nenvironment deployment. A deployment is a full release snapshot for that\nenvironment: deploying a release that contains only one new workflow removes any\nother workflows from that environment's live set.\n\nDefault source resolution:\n\n1. If the workspace already has source files, inspect and edit that workspace\n   source.\n2. For fresh creation with no existing workspace source, author in the chat\n   workspace.\n3. For read, add, or modify requests against existing product behavior or\n   source, do not guess from an empty workspace. Resolve the intended\n   environment from the user request first. If the user names `test`, `staging`,\n   `production`, or another environment, use it. Otherwise inspect\n   `kora environment list --json`. If exactly one environment exists, use it as\n   the default resolved environment; if multiple environments exist, ask which\n   environment before materializing release source.\n4. For the resolved environment, inspect\n   `kora deployment list --environment <environment> --json`.\n5. If it has a live deployment, use that live deployment's release as the default\n   source and write the frozen source into the workspace with\n   `kora release source <release> --out <empty-temp-dir> --json`. Then copy the\n   exported files into the chat workspace root before editing.\n6. Do not keep edits under temporary folders such as `source/`, `src/`, or\n   `project/`; edit workspace-root paths like `org/...`, `processes/...`, and\n   `scripts/...` directly.\n7. If it has no live deployment, say there is no live release to modify and\n   continue only with fresh source or a user-named release.\n\nFor read-only inspection of already-created workflow or org-model facts, use\nthe CLI's release snapshot selectors instead of materializing source:\n`--release <release>` for a named immutable release, or\n`--environment <environment>` for the selected environment's current live\ndeployment release.\n\nWhen adding to an environment that already has a live deployment, start from the\nlive release source. Before deploying, compare workflow lists; if the new\nrelease drops existing workflows, stop and ask whether removal is intended.\n\nEvery workflow source bundle has seven layers you may touch:\n\n1. who does the work: people, agents, roles, assignments\n2. what work exists: capabilities and operations\n3. how work flows: workflows\n4. what external events enter the flow: trigger resources that target workflow messages\n5. what external behavior exists: installed extensions, operations, and service scripts\n6. what rules apply: decisions\n7. what runtime assets support execution: templates, scripts, schemas, docs\n\nHuman and agent task nodes depend on this runtime chain:\n\n`role -> capability -> assignment -> workflow task`\n\nIf any link is inconsistent, the workflow will not resolve at runtime.\nService nodes are different: they call an `Operation` and do not need roles,\ncapabilities, agents, or assignments unless the workflow also has human/agent\ntask nodes. Still create `org/assignments.yaml` for every fresh source bundle; use an\nempty `spec.roles: {}` registry when the workflow has no human or agent tasks.\n\n## Runtime Boundary\n\n- The workspace is the proposal surface for authored source -- YAML resources,\n  service scripts, templates, and source docs. It is not the live runtime; use\n  it for source editing and smoke tests only.\n- Extension package source uses the `kora-extension-builder` skill and the\n  extension lifecycle, not workflow release source.\n- Temporary files, generated outputs, and smoke-test artifacts may exist while\n  authoring, but only files accepted by release creation become deployment\n  entries.\n- Files provided during a conversation are unclassified workspace/input files;\n  use them as message context. Copy one into release source only when the user\n  explicitly asks; upload it as a managed runtime artifact only when the user\n  explicitly asks to use it as workflow/run input.\n- `kora` is an authoring and inspection tool, not available inside live\n  workflows, operations, scripts, or agent prompts. Do not put `kora` commands\n  in workflow YAML, scripts, operations, or agent prompts.\n- Service operation scripts run in a separate runtime sandbox with released\n  files mounted read-only at `/workspace`. Package installs, node_modules,\n  virtualenvs, caches, and build output created while authoring are scratch\n  state unless the source bundle has an explicit deterministic packaging\n  strategy.\n\n## Environment Discipline\n\nResolve the intended environment once (see Core Mental Model). Use that same\nenvironment for extension discovery, contract fetches, node tests, release\nvalidation, deployment, and run commands. Do not discover an extension in one\nenvironment and test, release, deploy, or run against another.\n\nFor extension-backed service work:\n\n- Verify the selected extension is installed in the resolved environment and\n  that `kora extensions get ... --json` reports `state: \"ready\"`.\n- If it is `setup_required`, route the user to Settings setup before publishing\n  or running workflow code. If it is `disabled`, tell the user it must be\n  enabled. Use the returned `message` as the user-facing explanation.\n- If a required provider-backed extension is not installed and ready, stop and\n  tell the user exactly which extension/setup is missing. Do not write\n  placeholder provider operations, do not substitute unauthenticated direct API\n  calls, and do not publish a workflow you expect to fail unless the user\n  explicitly asks to continue after that warning.\n- To inspect current provider data before authoring, invoke one ready installed\n  extension function (`kora extensions invoke <extension-name> <function-name>\n  --environment <environment> --input @input.json --yes --json`) after fetching\n  its exact schema. Do not create throwaway workflow source just to inspect\n  provider data.\n\n## Service Operation Rules\n\nScript-backed service nodes invoke an `Operation`.\n\n- Service scripts import `@kora/runtime-sdk` and use `getInput`,\n  `extensions.invoke`, and `emitOutput` for operation input, installed\n  extension functions, and stdout JSON. Cloud-backed providers are still\n  installed extensions from the script perspective.\n- For installed extension calls, normalize the extension response into the\n  operation's own stdout shape; do not rely on optional extension fields being\n  present or non-null.\n- Registered extension function descriptions and schemas are the source of truth\n  when authoring operations that call them.\n- `paramBindings` shape operation stdin before the script runs.\n- Runtime variables and org secrets are declared with `spec.bindings.env` and\n  `spec.bindings.secrets`; names and injected env vars must not use the\n  reserved `KORA_` prefix.\n- Operation scripts can call functions exposed through\n  `spec.bindings.extensions`, but they do not read extension storage or\n  extension secrets directly.\n- When `spec.script.parseStdoutAsJson` is true or omitted, stdout must contain\n  exactly one valid JSON value. Log diagnostics to stderr.\n- `resultMapping` maps emitted stdout into the service node's declared output.\n  Without `resultMapping`, script stdout must be a JSON object that can shallow\n  merge into workflow state.\n- Optional `resultMapping` fields are skipped only when the source path is\n  absent. A present `null` value is mapped and must validate.\n- Managed artifact files are separate from stdout. Scripts read artifact inputs\n  and write declared artifact outputs through `KORA_ARTIFACT_MANIFEST`\n  `localPath` entries; do not persist manifest local paths into workflow state.\n\n## Typical Project Layout\n\n```text\nkora.yaml\norg/\n  org.yaml\n  roles/<name>.yaml\n  people/<name>.yaml\n  agents/<name>.yaml\n  assignments.yaml\ncapabilities/\nprocesses/\noperations/\ndecisions/\ntriggers/\nscripts/\ntemplates/\n```\n\nKeep entity names in resource `metadata`, not inferred from filenames.\n\n## Build Order\n\nWhen creating source from scratch or deliberately restructuring it, prefer\nthis order so references resolve cleanly. Complete the fresh workflow source\nschema preflight before writing the first file.\n\n1. source manifest (`kora.yaml`) and organization (`org/org.yaml`)\n2. `org/assignments.yaml` with `spec.roles: {}` for every new source bundle\n3. roles, people, agents, and assignment entries only when human/agent tasks need them\n4. capabilities\n5. installed extensions, operations, and service scripts\n6. decisions\n7. workflows\n8. triggers that bind installed extension events to exactly one workflow message\n   start\n9. optional templates and supporting docs\n\n## Authoring Discipline\n\nBefore editing:\n\n- Inspect the current workspace before assuming files exist.\n- Check `kora.yaml` and the target area directly before scaffolding foundational\n  files.\n- `read` or `ls` the area you plan to change.\n- `grep` for references before renaming or deleting anything.\n\nWhile editing:\n\n- When the user gives a clear intent but omits incidental details, draft a valid\n  minimal workflow with reasonable names and a simple message/manual start\n  instead of stopping for clarification.\n- Keep changes small and scoped.\n- Every capability must define at least one of `spec.humanConfig` or\n  `spec.agentConfig`. For capability work a person can perform, include at least\n  `humanConfig: {}` even when no optional human guidance fields are needed.\n- For workflows, author the data contract first. Define `types:` and use only\n  the node fields the schema supports.\n- Author every workflow as a Process source document under `processes/`, with\n  `kind: Process`. `kind: Workflow` and `workflows/` are not source aliases;\n  Platform owns internal organization scope injection.\n- Treat workflow state as an accumulated top-level object. Each typed node\n  output shallow-merges into state.\n- Use message starts or `receive` nodes for workflow-level message consumption.\n  Use `triggers/*.yaml` only when an installed extension event should start a\n  workflow through exactly one message start. Triggers do not resume `receive`\n  nodes. A workflow invoked by `call` or\n  `call.each` needs a callable manual start marked `internal: true`; call nodes\n  name the child with `process`, not `workflow`.\n- Use `task.each` or `call.each` for runtime collections.\n- For agent output review, put `requiresOutputReview: true` on the producer\n  capability and `agentOutputReview` on each ordinary producer `task`. Point it\n  directly to an explicit human task; keep approve, reject, revise, apply, and\n  escalation behavior in ordinary nodes and gateways. The producer object\n  output type must set top-level `additionalProperties: false`. Read\n  `references/workflow-flow-nodes.md` before authoring this pattern.\n- Use ordinary `next` to a human task when review applies regardless of whether\n  the producer is assigned to a person or an agent. Do not use output review as\n  tool-call or side-effect authorization; put irreversible actions after an\n  explicit human decision.\n- Use `call.each` to a child workflow containing producer and review tasks when\n  each collection item needs review. A review-required capability is invalid on\n  `task.each`.\n- For agent tasks that handle file content, use node-level `promptAttachments`\n  on `task` / `task.each` for selected top-level file artifact input fields.\n  Prefer an earlier extractor service node for PDFs, Office docs, HTML, ZIPs, or\n  other binary/rich attachments; attach only the extracted text or image\n  artifact to the agent prompt.\n- Make operation `resultMapping` and the declared workflow service-node\n  `output` type agree.\n- Model expected absence explicitly. Optional means absent from the object, not\n  `null`, unless the schema deliberately allows `null`.\n\nAfter meaningful changes:\n\n- There is no validation-only command for uncreated source. Do not invent `kora release\n  create --dry-run`, `kora release validate-source`, or similar commands, and\n  do not create a release merely to validate a source-only proposal. Inspect\n  the touched files and references, run applicable targeted checks, and state\n  that full source validation remains deferred until requested release\n  creation.\n- Run `kora test node <workflow-name> <node-id> --workspace <dir> --input @input.json --environment <environment> --json`\n  for touched executable service nodes when you can supply meaningful node\n  input.\n  Use this before claiming artifact-producing nodes are verified; release\n  creation and deployment do not prove artifact capture.\n- If a node test ends without an exit code because it was cancelled or timed\n  out, do not retry the same node with different workspace or input-path\n  variants. Report that targeted check as unverified once.\n- Use `kora release create <dir> --json` only when the user asks to create a\n  release artifact from source. Then:\n  1. Treat release-source or release-readiness diagnostics from that command as\n     must-fix items before deployment.\n  2. When it succeeds, tell the user the release was created, that it is not live\n     yet, and route them with a Markdown link such as\n     `[release detail](/app/releases/<release>)`.\n  3. Inspect `kora environment list --json` before offering deployment follow-up.\n     If exactly one environment is available, default to that named environment\n     and ask whether to deploy there. If multiple environments are available, ask\n     which environment should receive the release.\n  4. Use `kora release validate <release> --environment <environment> --json` to\n     check one environment's readiness.\n  5. Use `kora environment deploy <environment> <release> --json` only when the\n     user asks to deploy a release, and name the target environment in your\n     confirmation.\n  6. If deployment runs a source-defined workflow-node test gate, report the\n     pass count, rate, mode, and threshold from the response. A blocked gate\n     leaves the previous deployment live; do not retry with an override or\n     claim the release is deployed.\n- If a workflow-node smoke test fails, do not publish or deploy unless the user\n  explicitly says to proceed anyway after you warn that the workflow is likely\n  to fail. Classify the failure before responding: source/validation error,\n  missing extension/binding/grant, missing connection/credential, extension\n  runtime error, or provider/API error.\n- For operations that call installed extension functions, use the visible\n  installed-extension discovery commands. Use the `kora-extension-builder`\n  skill only when a new extension package source is needed. Release creation\n  does not publish, install, or grant extensions; extension package and\n  install lifecycle actions are admin/product workflows outside workflow source.\n- Do not ask the user to test anything you can safely test yourself in the\n  current authoring environment.\n- If testing requires user authorization, missing business input, or real\n  changes in connected systems, say exactly what remains untested and what user\n  action is needed.\n- Do not claim release readiness until the requested release creation or\n  explicit release validation is clean. Release creation is not a substitute\n  for workflow-node smoke tests.\n- When reporting success to the user, keep checks and user-visible behavior in\n  the foreground. Avoid implementation bullets for scripts, YAML files, runtime\n  SDK calls, or command mechanics unless the user asks for them.\n\nCascading/destructive changes:\n\n- Identify dependents first with `grep`.\n- Tell the user what will be affected.\n- Get explicit confirmation before destructive removals.\n- Update references in one pass, then inspect the updated references and run\n  applicable targeted checks.\n\nReminder: real org membership, runtime facts, workflow runs, tasks, releases,\nruntime variables, workflow artifacts, and resource schemas are not in the\nworkspace. Use `kora` for those.\n\n## Which Reference To Read Next\n\n- `references/org-model-resources.md` — modeled people, roles, agents, and\n  assignments\n- `references/capability-resource.md` — capability resource shape\n- `references/workflow-flow-nodes.md` — workflow node types and flow rules\n- `references/patterns-and-examples.md` — common workflow patterns and one\n  complete current project example\n- `references/installed-extension-discovery.md` — find installed extensions,\n  search functions/tools/skills, and fetch one exact callable contract\n- `references/operation-and-extension-resources.md` — operations, service\n  scripts, and runtime SDK bindings for selected extension functions\n- `references/service-io.md` — operation stdin, stdout, `emitOutput`, and\n  `resultMapping`\n- `references/artifacts.md` — managed artifact declarations, manifests, and\n  send-template artifact URLs\n- `references/credentials.md` — runtime variables, org-secret bindings, and\n  extension secret boundaries\n- `references/filesystem.md` — live runtime filesystem and dependency\n  availability\n- `references/testing.md` — workflow-node and artifact smoke-test routing\n- `references/decision-resource.md` — decision resource shape\n- `references/agent-config.md` — agent-specific modeling\n- `references/yaml-resource-schemas.md` — YAML shape companion\n\n## Typical Task Routing\n\n- \"Where should this resource live?\" -> `references/org-model-resources.md`\n- \"How should this workflow be structured?\" ->\n  `references/workflow-flow-nodes.md`, then\n  `references/patterns-and-examples.md`\n- \"How does a workflow call external behavior?\" ->\n  `references/installed-extension-discovery.md`, then\n  `references/operation-and-extension-resources.md`, then `references/service-io.md`\n- \"What extension function/tool/skill should this workflow use?\" ->\n  `references/installed-extension-discovery.md`\n- \"How should this service script read input or emit output?\" ->\n  `references/service-io.md`\n- \"How should this workflow use files or folders at runtime?\" ->\n  `references/artifacts.md`, then `references/filesystem.md`\n- \"How should this node be tested?\" -> `references/testing.md`\n- \"What exact fields does resource X support?\" ->\n  `kora schema get <resource> --json`\n- \"What is already modeled in this source proposal?\" -> inspect the workspace\n  files directly\n\n## Out Of Scope\n\n- Extension package authoring, publishing, installing, updating, and granting ->\n  the `kora-extension-builder` skill.\n- Product UI route lookup, menus, tabs, buttons, and user navigation ->\n  the `kora-product-ui` skill.\n- Platform inspection -> `kora` with the matching family, driven by the\n  bootstrap source-of-truth map.\n- Exact resource fields -> `kora schema get <resource> --json`, not skill\n  prose.\n"
}