Skip to main content
Use this guide to create and follow a run in the hosted Kiwi app. Keep implementation in the tools you already use: Kiwi records work that people, agents, and CI explicitly report. To connect an agent environment using details from the signed-in app, start with Set up your agent.
1

Sign in and open a project

Sign in to Kiwi. On first use, Kiwi creates an organization using your profile name or email and a project named My first project. If you already belong to an organization, use the organization and project access already granted to you. An organization invitation alone does not grant access to every project.
2

Publish a workflow

Open Workflows in the project. Publish the bundled Development workflow definition or import a valid definition. Kiwi validates the ordered chain and assigns a new immutable published revision. See Workflows and gates before changing the template.
3

Prepare a run and its people

In Runs, start a run with a request description or reference and choose the published workflow. Set the responsible person, designated owner, and designated reviewer. The responsible person receives reserved human handoffs; the owner decides Plan; the reviewer decides Human acceptance.
4

Submit the Plan outputs

For a bounded example, track a change in your own application that improves help-center search when a query has no matches. The Plan performer reports scope, acceptance_criteria, and at least one required_checks entry. Root output names are snake_case; fields inside a check definition are camelCase. Replace the reporter placeholder with an actual eligible project user ID; a placeholder never grants authority.
The designated owner must accept the submitted Plan in the app. A submitted output or tool receipt is not the decision. If a checker will report this check, use checker_reported, the actual nonsecret checker reporterId, and allow the same check ID on that credential. See CI reporting.
5

Report implementation and verification

Implement in your existing tools and report the exact candidate reference, summary, and handoff notes. A human QA reporter or assigned checker then reports each required check against that candidate. A check must pass; fail, blocked, or not-applicable does not satisfy the gate.
6

Complete review, acceptance, and handoff

A distinct reviewer performer and session reviews the same candidate. The designated reviewer submits a Human acceptance decision in the app. Complete Handoff by recording the actual delivery reference, summary, and remaining limitations. The run completes only when the workflow records all required accepted steps.

​
Confirm the current state

Open the run to see its current step, attempts, check evidence, actor provenance, and available actions. The run’s nextActions are permission- and state-specific. A receipt confirms one command was recorded; it does not mean the whole run or current gate passed. If a mutation’s response is lost and its outcome is unknown, retry the same command with the same command ID and identical body. For a definitive stale-version or stale-attempt response, refresh the run and create a new command ID. See Runs and history and Retries and recovery.