Skip to main content
Use this guide when work is being tracked in a Kiwi run. Kiwi does not require every request to become a workflow or run. For tracked work, follow the pinned run contract and report only actions and results that actually happened. The hosted Kiwi documentation is at docs.kiwiflow.io. Start discovery with its generated llms.txt index, which lists the public pages. Fetch a relevant page as Markdown by appending .md, for example the Agent guide. Use the full documentation export when broader corpus context is needed. Page descriptions help choose what to read. Documentation explains stable concepts, while the exact workflow pinned on the current run and its current graph outputs control a tracked action. A newer workflow publication does not change an existing run.

​
Read the current contract

  1. Connect through the authenticated remote MCP server, or use another authorized client already connected to it.
  2. Call list_projects and select a project available to the authenticated user. A static MCP key is limited to its one project.
  3. If starting a new run is explicitly authorized, call list_workflows for that project and choose an existing published workflow. For an existing run, use its pinned workflow revision; do not substitute a newer revision.
  4. Read the run with get_run before acting. Follow the current graph node’s instructions, requiredOutputs, acceptance, eligibleRoles, and currentAttemptId, together with the actor-specific nextActions.
  5. If a run does not exist and the user authorized starting one, call start_run with a real request and the intended published workflow. Keep the returned run ID and pinned revision.
The current run is the authority for what to do next. Do not infer a missing permission from prose, the user’s request, a prior response, or an MCP tool receipt. If the selected step has pinned skills or a profile, retrieve the assignment and exact version before work begins. Follow Workflow skills and execution records for get_assignment, get_step_skill, and get_skill_file. A returned skill is the pinned instruction source for that step.

​
Start and submit an eligible step

Use camelCase MCP arguments. For a new ready node with currentAttemptId null, generate a new UUID for attemptId. Call start_step with the current runId, exact stepId, new commandId, positive expectedRunVersion, attemptId, and declared harness/session fields. Read its returned run and receipt, then use the current version and attempt from that response when submitting.
The UUIDs and version above are syntax examples, not real Kiwi identities. Replace them with current returned values and a newly generated attempt ID where the current attempt is null. Submit the exact output fields declared by the run’s graph node. Development workflow output examples are in Manual participation; its Plan contract and nested check assignment are in Workflows and gates. MCP submit_result takes the same run, step, command, version, attempt, and harness fields, plus an outputs object. The wrapper uses camelCase; output names are those declared by the workflow and can be snake_case. Do not add undeclared fields. This syntactically valid example shows the full wrapper for the customer help-center task; replace each identifier and reporter with current values.
The UUID values and version are examples only. The named reporter must be an actual eligible user; for checker reporting use the credential’s assigned reporterId and permitted origin instead. Verify is not submitted through submit_result; authorized humans or checker credentials report named checks through the CI check API.

​
Pause for a human decision

An agent may report the Plan proposal, but it cannot accept the Plan. Wait for the designated owner to make the decision in the app, then call get_run again. The designated reviewer makes the Human acceptance decision in the app after the acceptance step has been submitted. An agent may perform Independent review only when the reviewer’s performer and session both differ from the Implement performer and session. Changing only a version label or command ID does not make the session independent. Stop when nextActions does not authorize the operation you intended.

​
Keep session and command identity straight

Keep harnessName, harnessVersion, and nativeSessionRef stable across reconnects and refreshes for the same declared session. They are attribution metadata and do not attest to remote machine activity. For a mutation whose outcome is unknown, retry the same command ID with the exact same input, including the original version and attempt. A repeated command with changed content conflicts. After a definitive stale version or attempt response, read the run again and use a new command ID; do not invent a new attempt if the current node still has an attempt. If the same performer, principal, and session is resuming its own manually reported resumable blocker, use that same attempt ID. An agent cannot claim a queued handoff: the handoff_step action creates an attempt reserved for the responsible human. Failed or blocked check results require authorized rework, not a blocker resume. For state fields, attempt history, and event cursors see Runs and history. For recovery choices see Retries and recovery.