> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kiwiflow.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflows and gates

> Import and publish an ordered workflow with typed outputs, actor eligibility, human decisions, and required checks.

Kiwi workflows are validated ordered definitions. They describe what each step requires and how Kiwi accepts its report; they do not launch workers, call a referenced skill, or route work automatically.

## Default Development workflow

The bundled [Development definition](https://docs.kiwiflow.io/examples/development.v1.json) defines this sequence:

1. Plan
2. Implement
3. Verify
4. Independent review
5. Human acceptance
6. Handoff

Use the file as the starting point for a project. A published revision is immutable. A run pins the chosen workflow ID and revision; later publications do not alter its contract.

## Definition contract

The root object uses schema\_version 1, a nonempty workflow\_id and name, a positive input revision, topology "ordered", an inputs list drawn from request\_text and request\_reference, input\_rule "at-least-one-request-input", steps, rework, and terminal\_outcome.

Each step declares a unique id, name, depends\_on, allowed\_actor\_kinds, eligible\_roles, instructions, skill\_ref, required\_outputs, acceptance, and candidate\_bound. skill\_ref is required and must be either null or a nonempty string. It is a reference in the workflow; Kiwi does not invoke the skill. depends\_on must list exactly the preceding step, so branching and cycles are rejected.

| Output type | Submitted value |
| - | - |
| text | Nonempty text. |
| text-list | A list of nonempty strings. |
| candidate-reference | Nonempty text identifying the exact candidate. |
| verification-verdict | pass, fail, or blocked. |
| check-definition-list | Check definitions; each needs a unique id, name, expectedResult, nonempty permittedOrigins, and nonempty authorizedReporterIds. |
| check-result-list | Synthesized Verify results. Agents cannot submit this output. |

An output may set a nonnegative integer minimum\_items. The submitted list must meet that minimum. Required outputs must be present and nonempty where applicable; undeclared output fields are rejected.

## Supported acceptance modes

| Mode | Meaning |
| - | - |
| required\_outputs | Accept when an eligible performer submits all declared outputs. |
| human\_decision | Hold the submitted attempt until its designated owner or reviewer makes a decision in the app. Plan is assigned to designated\_owner. |
| all\_required\_checks\_pass | Accept the single Verify step when every check from the accepted Plan passes. Verify must follow a candidate-producing Implement step. |
| independent\_review\_pass | Require a pass verdict from a reviewer whose performer and session both differ from Implement. |

The Development contract requires a Plan step with scope, acceptance\_criteria, and at least one required check; a preceding accepted Plan; a candidate-producing Implement with candidate\_ref, summary, and handoff\_notes; and exactly one candidate-bound required-check gate. Independent review requires candidate\_ref, verdict, and findings. Human acceptance requires candidate\_ref and qa\_notes. Final Handoff requires candidate\_ref, delivery\_ref, and summary. Check the bundled definition for exact actor, role, and output declarations.

## Plan check assignment

Plan output names are snake\_case. Fields inside each check definition are camelCase:

```json theme={null}
{
  "scope": "Improve the help center's search results when a query has no matches.",
  "acceptance_criteria": [
    "A query with no matching help articles explains that no results were found and offers a way to revise the search.",
    "Queries with matching articles continue to show the matching results."
  ],
  "required_checks": [
    {
      "id": "help-search-results",
      "name": "Help search results QA",
      "expectedResult": "When a query has no matches, the help center explains that no results were found and offers a way to revise the search; matching results continue to display.",
      "permittedOrigins": ["human_attested"],
      "authorizedReporterIds": ["user_REPLACE_WITH_CURRENT_ELIGIBLE_PROJECT_USER_ID"]
    }
  ]
}
```

For a checker report, set permittedOrigins to checker\_reported, use the credential's actual nonsecret reporterId in authorizedReporterIds, and include this check ID in allowed\_check\_ids when the Admin issues the credential. The credential record id is a different value. A human QA reporter needs an eligible project Admin or Reviewer role and must also be listed in authorizedReporterIds. This schema has no separate QA-assignee field.

## Publish and version

Use the project's **Workflows** area to import or edit a definition and publish it. Kiwi validates the definition and stores a new immutable server-assigned revision. The revision number in the imported JSON does not choose or overwrite the next published revision.

Plan approval establishes the active check definitions. Check results bind to the accepted Plan revision, current implementation attempt, Verify attempt, and candidate. Rework preserves prior attempts as history while invalidating affected candidate-dependent evidence. See [Runs and history](https://docs.kiwiflow.io/runs-and-history.md) and [Retries and recovery](https://docs.kiwiflow.io/retries-and-recovery.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.