# Set up your agent
Source: https://docs.kiwiflow.io/ai-quickstart

Start setup, connect an agent to a hosted Kiwi project, and prepare its existing developer workspace.

Use the agent environment you already have to connect to a hosted Kiwi project. Kiwi stays hosted; this guide does not install a local Kiwi client or server.

## Connection-only prompt brief

This short brief is for the existing connection-only helpers on `/app` and `/app/mcp`. The `/app/get-started` prompt also prepares the current developer workspace after the hosted connection is verified.

Paste this into your agent:

```text wrap theme={null}
Help me connect my existing agent environment to a hosted Kiwi project through its supported MCP connection. Ask me one question at a time and follow:
https://docs.kiwiflow.io/ai-quickstart.md
https://docs.kiwiflow.io/remote-mcp.md
```

## Start with Get started

From the public Kiwi landing page, choose **Get started**. Signed-out visitors continue through Clerk's hosted signup and return to `/app/get-started`; signed-in visitors go straight to the choice. Choose **Set up with an agent** to reveal a prompt for the current developer workspace, or **Continue manually** to open the existing project setup at `/app`. You can return to the choice through **Get started** later.

First-time setup initializes an organization and **My first project** through the hosted app. It does not publish a workflow. Choosing agent setup only reveals the prompt; it does not connect the agent. After you paste and run the prompt and complete OAuth sign-in in the agent client, it asks the agent to verify the current organization, exact project, role, and published workflows through actual MCP responses, then update appropriate existing workspace guidance. It preserves unrelated instructions and reports when workspace files are unavailable. This purpose can prepare a workflow proposal when a successful `list_workflows` response contains no published workflows; an eligible Admin reviews and publishes it in the Kiwi app. It does not create a workflow, run, credential, invitation, membership, or billing change.

The helpers already available from [Projects home](https://www.kiwiflow.io/app) and [MCP & access](https://www.kiwiflow.io/app/mcp) stay connection-only: they connect and verify access without asking to edit developer workspace guidance.

## Choose your organization and project

* **New to Kiwi:** choose [Get started](https://www.kiwiflow.io/get-started), create an account through hosted Clerk signup, then choose agent or manual setup.
* **Joining a team:** accept the organization invitation, then open the project you were invited to use. Organization membership does not grant access to every project. If it is missing, ask a project Admin for access.
* **Already use Kiwi:** select an organization in the app, then choose a project you can access inside the setup helper.

See [Organizations and accounts](/organizations) for membership and role details. Complete sign-in, invitation acceptance, and any permission changes in Kiwi.

## Copy the project's setup prompt

In the signed-in app, select the intended organization. Open **Set up your agent → Copy setup prompt** from [Projects home](https://www.kiwiflow.io/app) or the global [MCP & access page](https://www.kiwiflow.io/app/mcp). Choose the project inside the helper. If only one project is available, it is selected for you; otherwise, choose the intended project.

The prompt revealed by **Set up with an agent** at `/app/get-started` uses the same current connection details and selection rules, with the developer-workspace purpose described above. The `/app` and `/app/mcp` prompts remain connection-only.

Paste the copied prompt into your agent. It contains the canonical MCP endpoint and the selected organization's and project's names and IDs as JSON data. Those values identify the connection; they are not credentials. The prompt contains no access token, key, password, or secret.

Ask your agent to add the connection through the MCP settings supported by that agent environment. Use the endpoint and selected project details from the copied prompt. Preserve other configured servers and ask before replacing a conflicting Kiwi entry. If your client stores MCP settings in a file, follow that client's instructions. This connection uses Kiwi's hosted service through OAuth. Complete sign-in in the client and select the organization that contains the project. No API key is required for OAuth.

Verify the connection with actual MCP responses: call list\_projects, match the exact project ID from the setup prompt, then call list\_workflows for that project. Report what those calls returned. If the exact project is absent, either read fails, access is denied, or the calls are unavailable, explain the specific blocker and stop; a failed read is not an empty workflow list. Copying the prompt or seeing documentation does not prove an authenticated connection.

Neither prompt purpose creates or publishes a workflow or starts a run. MCP cannot publish a workflow, look up members, identify the current user with whoami, report a CI check, or make a human decision. Any suitable existing published workflow, including a custom workflow, is valid for general developer-workspace setup; do not require one named Development. Only when list\_workflows succeeds and returns no published workflow does the developer-workspace prompt prepare a proposal and give an eligible Admin the project workflow page at `/app/projects/{encodedProjectId}?view=workflows`. The prompt builds the absolute browser link from the canonical MCP service origin; keep the MCP endpoint and OAuth audience unchanged. For the optional Development task below, use a published Development workflow. The [manual quickstart](/quickstart) and [workflow guide](/workflows) explain that path.

## Optional: track a Development task

After connection is verified, use this only when you want a specific task tracked in Kiwi. Describe the task in plain language. Starting a run is a separate choice from setup.

```text wrap theme={null}
Before any run mutation, read and follow:
https://docs.kiwiflow.io/for-agents.md
https://docs.kiwiflow.io/workflows.md
https://docs.kiwiflow.io/ci-reporting.md

I want Kiwi to track this development task: [describe the goal in plain language].

Before starting a run, verify the selected project's exact ID in list_projects and inspect its published workflows with list_workflows. Use only the project's existing published Development workflow. If access or Development is unavailable, stop and tell me the next step. A project Admin must publish a missing Development workflow in the Kiwi app; do not create or change one. If a human QA assignment is required, explain it when relevant and help me confirm an eligible person through the project Members area or an Admin. Do not invent people, IDs, checks, or results.

If Development is published and the available actions permit it, start one run for this task using the returned project and workflow data. Prepare the Plan and use only actions the current run allows. Stop for the designated owner to decide the Plan in the app before implementation. Follow the actual candidate, check, reviewer, and Handoff requirements, and pause for each human decision. Do not bypass a gate.
```

An agent may submit a Plan when the run allows it, but the designated owner accepts it in the app. The reviewer makes Human acceptance in the app. An MCP tool receipt does not mean either decision passed. If a task needs a human-attested check and the agent cannot confirm a real eligible reporter, ask a project Admin to resolve the assignment; MCP has no member-lookup tool.

## Optional: prepare team or CI setup

For team access, ask the agent to prepare steps from [Organizations and accounts](/organizations):

```text wrap theme={null}
Help me prepare team access for this Kiwi project. Read
https://docs.kiwiflow.io/organizations.md and explain the difference between
organization invitations and project roles. Give me a read-only checklist. I
will make any membership or role changes in Kiwi myself. Do not send invitations
or change roles or billing.
```

For CI, use [Connections](/connections) and [CI reporting](/ci-reporting):

```text wrap theme={null}
Help me prepare CI check reporting for this project's existing pipeline. Read
https://docs.kiwiflow.io/connections.md and
https://docs.kiwiflow.io/ci-reporting.md. Explain the required inputs and steps.
Prepare guidance only; do not issue credentials, change CI settings, or create,
request, or store secrets. I will complete Admin and secret-store actions.
```

For a manual first run in the hosted app, see the [quickstart](/quickstart). For exact agent actions in an existing run, use the [Agent guide](/for-agents). For check results, see [CI reporting](/ci-reporting).


# Integration API reference
Source: https://docs.kiwiflow.io/api-reference

Supported remote MCP and checker HTTP contracts for connecting customer agents and CI to hosted Kiwi.

This reference covers the external integration interfaces supported by Kiwi. Use the endpoint shown by the signed-in app's setup helper; the hosted service origin is not something to guess. Use the Kiwi app to manage accounts, invitations, project members, workflow publication, run decisions, and credentials.

## Remote MCP

Connect an existing agent environment to the hosted Streamable HTTP MCP endpoint at /mcp. OAuth protected-resource metadata is available at /.well-known/oauth-protected-resource/mcp on the same host. The setup helper provides the full endpoint and selected project context.

For OAuth setup, the client targets the exact /mcp resource and requests the user:org:read scope. A project-bound MCP key can be used by clients that support static Bearer authentication. See [Remote MCP](/remote-mcp) for authentication boundaries and the supported tool list.

## Checker HTTP API

A project-bound checker credential can read the current verification context and report a named result for a run. It cannot manage project settings, submit ordinary workflow outputs, or make human decisions.

The checker API uses the origin of the exact MCP URL copied from the signed-in Kiwi setup helper. Keep its scheme, host, and any port; remove only the `/mcp` path and append `/v1/runs/{runId}/checks`. For example, if the copied MCP URL is `https://<host>:<port>/mcp`, the checker request URL is `https://<host>:<port>/v1/runs/{runId}/checks`. Do not guess a host or use Kiwi's website or documentation origin. This route is part of hosted Kiwi; customers do not deploy a separate service. MCP requests continue to use the full URL ending in `/mcp`.

### Read the current context

Send a Bearer token:

```http theme={null}
GET /v1/runs/{runId}/checks
Authorization: Bearer YOUR_CHECKER_KEY
```

The response contains the current runVersion, acceptedPlanRevision, candidateRef, candidateRevision, implementationAttemptId, verificationAttemptId, verificationState, and the checks assigned to the credential under the accepted Plan. Read this context immediately before reporting; do not use a cached candidate or version.

### Report a check

`POST /v1/runs/{runId}/checks` accepts these fields:

| Field | Type | Meaning |
| - | - | - |
| command\_id | UUID | Idempotency key for this report. |
| expected\_run\_version | positive integer | Current runVersion from the context read. |
| attempt\_id | UUID | Current verificationAttemptId, or a new UUID when Verify is ready and none exists. |
| check\_id | string | Exact assigned ID from checks\[].checkId. |
| status | pass, fail, blocked, not-applicable | Observed result; only pass satisfies the required-check gate. |
| candidate\_ref | string | Current candidateRef from the context read. |
| plan\_revision | positive integer | Current acceptedPlanRevision. |
| implementation\_attempt\_id | UUID | Current implementationAttemptId. |
| evidence | object, optional | A summary and optional URL that support the observed result. |

Example body for the customer task used across this guide:

```json theme={null}
{
  "command_id": "00000000-0000-4000-8000-000000000010",
  "expected_run_version": 2,
  "attempt_id": "00000000-0000-4000-8000-000000000011",
  "check_id": "help-search-results",
  "status": "pass",
  "candidate_ref": "commit:REPLACE_WITH_CURRENT_CANDIDATE",
  "plan_revision": 1,
  "implementation_attempt_id": "00000000-0000-4000-8000-000000000012",
  "evidence": {
    "summary": "The no-results message and revise-search action appear, and matching articles remain visible.",
    "url": "https://ci.example.org/runs/REPLACE_WITH_ACTUAL_RUN"
  }
}
```

Use only the current values from GET. If verificationAttemptId is null and Verify is ready, create one UUID for the first check report and use the returned attempt on later reports. Allowed statuses are pass, fail, blocked, and not-applicable. Only pass satisfies the gate.

A successful POST returns a receipt and refreshed context. The receipt uses camelCase fields; the HTTP request uses snake\_case. The response has this shape:

```json theme={null}
{
  "receipt": {
    "commandId": "00000000-0000-4000-8000-000000000010",
    "recorded": true,
    "replayed": false,
    "runVersion": 3,
    "eventCursor": 3,
    "eventId": "event_example",
    "eventType": "check_reported"
  },
  "checks": {
    "runId": "00000000-0000-4000-8000-000000000000",
    "projectId": "00000000-0000-4000-8000-000000000001",
    "runVersion": 3,
    "verificationState": "in_progress",
    "acceptedPlanRevision": 1,
    "candidateRef": "commit:EXAMPLE_CANDIDATE",
    "candidateRevision": 1,
    "implementationAttemptId": "00000000-0000-4000-8000-000000000012",
    "verificationAttemptId": "00000000-0000-4000-8000-000000000011",
    "checks": [
      {
        "checkId": "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.",
        "status": "pass",
        "evidence": { "summary": "The no-results message and revise-search action appear, and matching articles remain visible." },
        "resultVersion": 3,
        "evidenceOrigin": "checker_reported",
        "reportedBy": "checker:EXAMPLE_KEY_ID"
      }
    ]
  }
}
```

These values are synthetic examples, not a real run or credential. See [CI reporting](/ci-reporting) for the full report sequence and [Connections](/connections) for credential handling.

## Errors and retries

Integration errors return a JSON object with error and message. Common responses include 400 for invalid input, 401 for a missing or invalid credential, 403 for insufficient project or check authority, 404 for a missing run, 409 for stale state or a conflicting command replay, and 503 when an integration dependency is unavailable. MCP clients receive isError: true with an error and message in the text content.

If a check POST may have reached Kiwi but its response is missing, retry the same command\_id with the identical body. After a definitive stale response, read the context again and create a new command\_id using the current version and attempt. See [Retries and recovery](/retries-and-recovery).


# CI check reporting
Source: https://docs.kiwiflow.io/ci-reporting

Assign a project-bound checker credential and submit observed results for the exact current candidate and Verify attempt.

Kiwi accepts named results from an existing CI pipeline over HTTP. It does not start a pipeline or inspect its logs. A project Admin issues a checker credential restricted to selected check IDs and an expiry. Store the one-time secret in the CI secret manager used by your team.

The checker API uses the origin of the exact MCP URL copied from the signed-in Kiwi setup helper. Keep its scheme, host, and any port; remove only the `/mcp` path and append `/v1/runs/{runId}/checks`. For example, if the copied MCP URL is `https://<host>:<port>/mcp`, the checker request URL is `https://<host>:<port>/v1/runs/{runId}/checks`. Do not guess a host or use Kiwi's website or documentation origin. This route is part of hosted Kiwi; customers do not deploy a separate service. MCP requests continue to use the full URL ending in `/mcp`.

## Assign the checker

The accepted Plan check must name the check ID, allow checker\_reported in permittedOrigins, and list the credential's nonsecret reporterId in authorizedReporterIds. The credential's allowed\_check\_ids must also contain that exact check ID.

Issue the credential in the project's **Connections** area. Its record id is not its reporterId. Store secret once in CI; the response reports secretAvailable as true only at initial issuance. A replay returns secret as null and does not create a replacement.

## Read current check context

Send the key as a Bearer token and read `GET /v1/runs/{runId}/checks` before each report. The response shows the current runVersion, acceptedPlanRevision, candidateRef, implementationAttemptId, verificationState, verificationAttemptId, and checks authorized for this key and accepted Plan.

| GET context field | POST body field |
| - | - |
| runVersion | expected\_run\_version |
| acceptedPlanRevision | plan\_revision |
| candidateRef | candidate\_ref |
| implementationAttemptId | implementation\_attempt\_id |
| verificationAttemptId | attempt\_id; when null and Verify is ready, generate the first verification attempt UUID. |
| checks\[].checkId | check\_id |

Generate a fresh UUID for command\_id for each new report. Read runVersion immediately before POST and use that positive value as expected\_run\_version.

Do not report if candidateRef or implementationAttemptId is null, or the verification state is not ready for a result. Use the current values from that response; never use a version or candidate cached from an earlier pipeline run.

## Submit an observed result

`POST /v1/runs/{runId}/checks` uses snake\_case HTTP fields. Replace placeholders with values from the context response. The numeric values below are examples, not current state. If verificationAttemptId is null while Verify is ready, create one UUID for attempt\_id; on subsequent reports, use the attempt ID returned by the next context read.

```json theme={null}
{
  "command_id": "00000000-0000-4000-8000-000000000003",
  "expected_run_version": 2,
  "attempt_id": "00000000-0000-4000-8000-000000000004",
  "check_id": "help-search-results",
  "status": "pass",
  "candidate_ref": "commit:REPLACE_WITH_CURRENT_CANDIDATE",
  "plan_revision": 1,
  "implementation_attempt_id": "00000000-0000-4000-8000-000000000005",
  "evidence": {
    "summary": "The no-results message and revise-search action appear, and matching articles remain visible.",
    "url": "https://ci.example.org/runs/REPLACE_WITH_ACTUAL_RUN"
  }
}
```

Allowed statuses are pass, fail, blocked, and not-applicable. Only pass can satisfy the required-check gate. fail fails Verify; blocked and not-applicable block it. A required result cannot be cleared by reporting not-applicable.

The checker POST response includes a command receipt and refreshed check context. A receipt confirms recording, not acceptance of the Verify gate. Every required check must report pass for the current Plan revision, implementation attempt, candidate, and verification attempt before Verify advances.

## Resolve a lost response

If a check POST may have reached Kiwi but its response is unknown, retry the exact body with the same command\_id. After a definitive stale version or attempt response, read the current context and submit a new command ID with the current version and attempt. Do not reuse an ID with changed content.

If a credential issuance has an unresolved status, check the credential record in Kiwi before issuing another. An issuance replay does not reveal a lost secret or create a replacement. See [Retries and recovery](/retries-and-recovery) and the [Integration API reference](/api-reference).


# Kiwi concepts
Source: https://docs.kiwiflow.io/concepts

Understand organizations, projects, workflows, runs, attempts, actors, and the Development workflow contract.

## Account and project structure

An **organization** is a team and billing boundary in Kiwi. It contains one or more **projects**. Project membership is separate from organization membership, so an organization member does not automatically see every project. Each project has its own Admin, Contributor, and Reviewer roles. Use the organization selector and project areas in the hosted app.

## Workflow and run

A **workflow definition** declares an ordered set of steps, the actors and project roles that may perform them, the outputs each step must submit, and its acceptance rule. Publishing creates an immutable revision.

A **run** is one request tracked against one published workflow revision. It pins that revision and records its responsible person, designated decision makers, current state, candidate, plan revision, step graph, check results, and event history. Publishing another workflow revision does not change a run already in progress.

An **attempt** is one try at one step. A run keeps previous attempts when work is resumed or sent for rework. Each attempt records its state, performer and session when applicable, submitted outputs, and whether its evidence has been superseded.

## Actors and authority

Kiwi records a report as human-attested, agent-reported, or checker-reported. It checks the signed-in identity, project membership, role, step assignment, current attempt, and gate for each action. Declared harness and session values help identify an agent session; they are not proof of remote execution.

The default Development workflow has six ordered steps:

1. **Plan** — the designated owner decides whether to accept the submitted scope, criteria, and required checks in the app.
2. **Implement** — an eligible person or agent reports a candidate reference, summary, and handoff notes.
3. **Verify** — authorized humans or checker credentials report each planned check against the current candidate.
4. **Independent review** — a different performer and a different session review that candidate and submit a verdict and findings.
5. **Human acceptance** — the designated reviewer makes the decision in the app.
6. **Handoff** — an eligible performer records the delivery reference, summary, and remaining limitations.

A report can make the next step ready, but Kiwi does not start that work automatically. Failed checks and failed or blocked review prevent completion. See [Workflows and gates](/workflows) for the accepted schema and [Retries and recovery](/retries-and-recovery) for blockers, handoffs, rework, and cancellation.

## Check definitions and results

The accepted Plan defines each required check with an id, name, expectedResult, permittedOrigins, and authorizedReporterIds. The id is the stable name used by CI and the check API. A checker must be allowed that ID in its credential and its reporterId must be assigned in the accepted Plan. A human check reporter must be an eligible project Admin or Reviewer and be listed as an authorized reporter.

Each recorded check binds to the current Verify attempt, accepted plan revision, implementation attempt, and candidate reference. Verify's check\_results output is synthesized from those reports; an agent cannot submit a made-up list of check results.

For first-run steps and exact output fields, continue to the [hosted quickstart](/quickstart). For human, MCP, and checker authority boundaries, see [Manual participation](/participation), [Remote MCP](/remote-mcp), and [CI reporting](/ci-reporting).


# Connections and project logs
Source: https://docs.kiwiflow.io/connections

Manage nonsecret external references, checker credentials for CI, and recorded project events.

The project **Connections** area contains nonsecret references to external resources and restricted checker credentials for named CI reports. A connection is a reference for people and tools; Kiwi does not call the referenced URL.

## External references

A project Admin can add a name, HTTPS endpoint URL, notes, and bindings to exact published workflow revisions and step IDs. The endpoint must be a public HTTPS URL. Kiwi rejects URL credentials, query strings, fragments, local or private addresses, and non-HTTPS schemes. Do not put a token, password, or signed query parameter in the reference.

Connections and bindings are metadata for people and agent environments. Kiwi does not fetch or call the URL, test its health, store its remote secret, or treat the presence of a reference as workflow evidence. The list omits secrets. Archived references remain part of the configuration history.

To change a reference, open the project's Connections area and edit its fields and bindings. Archive it by setting its status to archived; archived references remain configuration history. Bindings identify a workflow\_id, positive workflow\_revision, and step\_id, and do not rewrite a run's pinned definition.

## Checker credentials

Use a checker credential when a CI pipeline needs to submit a named required check. A project Admin creates a credential with selected check IDs and an expiry. The check must also be defined in the accepted Plan, permit checker\_reported, and list the credential's nonsecret reporterId in authorizedReporterIds.

Save the key secret directly in the CI secret store when it is shown. Later inventory and issuance replay return metadata only. The credential metadata id identifies the Kiwi record; reporterId identifies the reporter used in a Plan assignment. Do not substitute one for the other, and never place the secret in a workflow definition, repository, log, or issue.

Checker credentials authorize only check reporting for the bound project and allowed check IDs. They cannot read runs through MCP, make human decisions, or submit ordinary step outputs. Revoke credentials when no longer needed. If Kiwi shows that revocation is pending, use the available retry action in the app and check its status there.

For a copyable context-read and report sequence, see [CI reporting](/ci-reporting).

## Project logs

Use **Logs** to inspect committed workflow events across the project's runs. Filter by run or event type, inspect the actor and event, and open the associated run. The log records workflow transitions and submitted evidence; it is not a complete error log and does not include unreported agent or CI activity.


# Agent guide
Source: https://docs.kiwiflow.io/for-agents

Follow the current workflow and report real work when a task is already tracked in a Kiwi run.

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](https://docs.kiwiflow.io). Start discovery with its generated [llms.txt index](https://docs.kiwiflow.io/llms.txt), which lists the public pages. Fetch a relevant page as Markdown by appending .md, for example the [Agent guide](https://docs.kiwiflow.io/for-agents.md). Use the [full documentation export](https://docs.kiwiflow.io/llms-full.txt) 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](/remote-mcp), 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](/workflow-skills) 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.

```json theme={null}
{
  "runId": "00000000-0000-4000-8000-000000000000",
  "stepId": "implement",
  "commandId": "00000000-0000-4000-8000-000000000001",
  "expectedRunVersion": 4,
  "attemptId": "00000000-0000-4000-8000-000000000002",
  "harnessName": "YOUR_ACTUAL_HARNESS",
  "harnessVersion": "YOUR_ACTUAL_VERSION",
  "nativeSessionRef": "YOUR_ACTUAL_STABLE_SESSION_REFERENCE"
}
```

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](/participation); its Plan contract and nested check assignment are in [Workflows and gates](/workflows).

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.

```json theme={null}
{
  "runId": "00000000-0000-4000-8000-000000000000",
  "stepId": "plan",
  "commandId": "00000000-0000-4000-8000-000000000006",
  "expectedRunVersion": 2,
  "attemptId": "00000000-0000-4000-8000-000000000007",
  "harnessName": "YOUR_ACTUAL_HARNESS",
  "harnessVersion": "YOUR_ACTUAL_VERSION",
  "nativeSessionRef": "YOUR_ACTUAL_STABLE_SESSION_REFERENCE",
  "outputs": {
    "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"]
      }
    ]
  }
}
```

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](/ci-reporting).

## 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](/runs-and-history). For recovery choices see [Retries and recovery](/retries-and-recovery).


# Kiwi documentation
Source: https://docs.kiwiflow.io/index

Connect an existing agent to hosted Kiwi, or follow the guide for tracking work in the app.

Kiwi is a hosted service for teams that want a shared record of selected work across people, agent environments, and CI. Choose how you want to get started.

## Choose your starting point

> **[Create an account](https://www.kiwiflow.io/sign-up)**
>
> Sign in to Kiwi. First-time setup creates an organization and **My first project**.

> **[Join a team](/organizations)**
>
> Accept your organization invitation, then ask a project Admin for access if the project is not visible.

> **[Connect an agent](/ai-quickstart)**
>
> Use the setup helper to connect an agent environment you already use to a hosted Kiwi project.

## Start with your existing agent

Paste this into the agent environment you already use. The setup guide will walk you through sign-in, project selection, OAuth, and a read-only connection check to hosted Kiwi.

```text wrap theme={null}
Help me connect my existing agent environment to the selected hosted Kiwi project through its supported MCP connection.

Read:
https://docs.kiwiflow.io/ai-quickstart.md
https://docs.kiwiflow.io/remote-mcp.md

Ask me one question at a time whether I need a new account, a team invitation, or access to an existing project. I will complete account, invitation, and access actions in Kiwi myself.

After I sign in, have me select the intended organization and open the agent setup helper from https://www.kiwiflow.io/app or https://www.kiwiflow.io/app/mcp. I will choose the project and paste the copied setup prompt here. Use that exact context to configure this agent environment's supported MCP settings, preserve other configured servers, and ask before replacing a conflicting Kiwi entry. Use OAuth and let me complete sign-in.

Then call list_projects, match the exact project ID from the setup context, and call list_workflows for that project. Report the actual results. If access or the project is missing, explain the next step and stop.

This request is for connection setup only. Do not create a workflow or run, send an invitation, issue a key, change billing, or start task work.
```

The setup helper is available from [Projects home](https://www.kiwiflow.io/app) or the global [MCP & access page](https://www.kiwiflow.io/app/mcp). Select the organization, choose a project inside the helper, then copy its prompt. The prompt contains the selected project's endpoint and nonsecret organization and project details; it contains no access token, key, password, or secret. See [Set up your agent](/ai-quickstart) for the full steps.

## What Kiwi records

When you choose to track a task, Kiwi records its ordered workflow steps, submitted reports, named check results, human decisions, and run history. The work itself stays in the tools you already use. Kiwi does not launch agents, run CI, observe unreported work, or make human gate decisions.

* [Set up your agent](/ai-quickstart) connects an existing agent environment and explains how to start a tracked task later.
* [Hosted quickstart](/quickstart) walks through a first run in the app.
* [Concepts](/concepts) explains organizations, projects, workflows, runs, attempts, actors, and checks.
* [Workflows and gates](/workflows) documents the definition and output contract.
* [Manual participation](/participation) covers people, decisions, blockers, rework, and handoff.
* [Agent guide](/for-agents) gives an agent the safe path for work already tracked in a run.
* [Remote MCP](/remote-mcp) and [CI reporting](/ci-reporting) document supported integrations.
* [Organizations and accounts](/organizations) covers membership, project access, billing, and referral attribution.


# Organizations and accounts
Source: https://docs.kiwiflow.io/organizations

Manage account access, project roles, organization billing, and referral attribution in hosted Kiwi.

An organization is the team and billing boundary. Each organization can contain multiple Kiwi projects, each with its own membership and roles.

## First use

Sign in at [Kiwi](https://www.kiwiflow.io/sign-up). On first use, Kiwi creates an organization from your profile name or email and initializes a project named **My first project**. If you already belong to an organization, use the membership and project access already granted to you. An organization member does not automatically receive access to every project.

## Membership and roles

Use **Members** in Kiwi to manage organization invitations and membership. Accepting an invitation makes the person an organization member; it does not grant access to every project.

In a project's **Members** area, a project Admin can assign current organization members one of these project roles:

| Role | Scope |
| - | - |
| Admin | Manage the project, workflow configuration, members, and project credentials. |
| Contributor | Perform eligible workflow steps. |
| Reviewer | Perform eligible review and verification actions. |

Project access and organization authority are separate. An organization Admin does not automatically gain access to a private project. A project Admin does not become an organization Admin or gain billing authority.

## Billing

Use **Billing** to view the organization's plan, status, and billing actions shown to you. An organization Admin manages billing access and makes changes through the available controls.

## Remote access and checker keys

Use **MCP & access** to see the hosted MCP connection details and manage project-bound MCP credentials. OAuth is the normal path for an existing agent environment. A project Admin can also issue an expiring read-only or workflow-write MCP key for one project. The secret is shown once; the key inventory contains nonsecret metadata only.

Checker keys are separate credentials for named CI check reports. A project Admin creates them in **Connections**, restricts their check IDs and expiry, then stores the one-time secret in the customer's CI secret manager. See [Remote MCP](/remote-mcp), [Connections](/connections), and [CI reporting](/ci-reporting) for their permissions.

## Referrals

An organization Admin can create a stable referral link and view aggregate attribution counts. A valid code is recorded during the first eligible Kiwi organization Admin onboarding, before the organization has already been initialized or used to create projects. The first valid referral cookie lasts thirty days; opening another link does not replace a still-valid referral.

Existing organizations are not attributed later. A same-organization referral and a claimant using a code they created are ineligible. Counts report onboarding attribution only; Kiwi does not calculate payment or rewards from them, and the aggregate view does not expose another customer's identity.

For project membership and run permissions, see [Concepts](/concepts). For a customer-facing overview of connecting an agent, see [Set up your agent](/ai-quickstart).


# Manual participation and rework
Source: https://docs.kiwiflow.io/participation

Perform human workflow steps, submit required outputs, make assigned decisions, and return work safely.

People work in the hosted Kiwi app alongside agents and CI. Open the run to see the current step, required outputs, attempt owner, and actions available to your identity. Kiwi checks project membership, role, current attempt, and workflow prerequisites for each action.

## Human and agent responsibilities

* Contributors and agents perform only steps allowed by the pinned workflow and their project role.
* The designated owner accepts or sends the submitted Plan back for rework in the app.
* The designated reviewer makes the Human acceptance decision in the app.
* Eligible project Admins or Reviewers may report human-attested QA when the accepted Plan lists them as authorized reporters.
* A checker key can report only its assigned check IDs and checker-origin results; it cannot submit step outputs or make decisions.
* Only the responsible human can resume a handed-off attempt. An Admin or the responsible human may cancel a run.

Request bodies cannot choose their own user, actor kind, role, performer, or session identity. An agent's declared harness metadata helps keep reports attached to the same session; it is not remote-machine attestation.

## Structured step outputs

Every report must match the pinned workflow's required output names and types. The default Development workflow uses these objects. Replace the candidate placeholder with the exact same candidate reference where applicable, and report only work actually done.

**Implement** reports a candidate and a concise summary:

```json theme={null}
{
  "candidate_ref": "commit:REPLACE_WITH_EXACT_CANDIDATE",
  "summary": "Describe the implemented change.",
  "handoff_notes": "Describe verification context and any remaining work."
}
```

**Independent review** must be performed by a different performer and different session from Implement:

```json theme={null}
{
  "candidate_ref": "commit:REPLACE_WITH_EXACT_CANDIDATE",
  "verdict": "pass",
  "findings": []
}
```

Use pass only when the actual review passes. Use fail or blocked to record the real outcome; neither advances the workflow.

**Human acceptance** requires a submitted step report before the designated reviewer decides in the app:

```json theme={null}
{
  "candidate_ref": "commit:REPLACE_WITH_EXACT_CANDIDATE",
  "qa_notes": "Describe the actual candidate inspection and QA notes."
}
```

Submitting qa\_notes is not acceptance. Only the designated reviewer can accept or request rework for this step.

**Handoff** records actual delivery and remaining limitations:

```json theme={null}
{
  "candidate_ref": "commit:REPLACE_WITH_EXACT_CANDIDATE",
  "delivery_ref": "REPLACE_WITH_ACTUAL_DELIVERY_REFERENCE",
  "summary": "Describe the delivery and remaining limitations."
}
```

This final Handoff step is different from the MCP handoff\_step action, which returns an in-progress agent attempt to the run's responsible human. See [CI reporting](/ci-reporting) for Verify; Kiwi synthesizes the Verify output from actual check reports.

## Blockers and rework

When work cannot proceed, the current performer can record a blocker on its active attempt. A manually reported resumable blocker can be resumed only by the same performer, principal, and session. Keep that session identity stable; use a responsible-human handoff if the work should move to another person. A failed or blocked verification result is not a resumable work attempt and requires authorized rework.

Authorized people can request rework on the run. Rework can retain the accepted Plan or explicitly revise it. It creates affected attempts and invalidates candidate-dependent verification and review evidence; old reports stay visible but cannot satisfy the new gate. After a changed candidate, rerun the affected checks and review.

The responsible human or a project Admin can cancel in the app. Cancellation stops Kiwi from accepting further run transitions; it does not stop an agent, CI job, or other process outside Kiwi. For recovery actions, see [Retries and recovery](/retries-and-recovery).


# Hosted quickstart
Source: https://docs.kiwiflow.io/quickstart

Publish the Development workflow, prepare a run, and follow its real human decisions and check reports.

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](/ai-quickstart).

**1. Get started and choose a setup path**

From the public Kiwi site, choose **Get started**. Signed-out visitors continue through Clerk's hosted signup and return to `/app/get-started`; signed-in visitors go straight to that choice. Choose **Set up with an agent** to reveal a prompt for connecting your existing developer workspace, or **Continue manually** to open the project setup at `/app`. The public **Sign in** link continues to open the existing app path for returning users.

On first use, Kiwi initializes an organization using your profile name or email and a project named **My first project**. It does not publish a workflow automatically. After you paste and run the prompt and complete OAuth sign-in in the agent client, it asks the agent to verify the current organization, exact project, role, and published workflows through actual MCP responses, then update relevant existing workspace guidance. Any suitable published workflow, including a custom workflow, is valid. If a successful `list_workflows` response contains no published workflow, the prompt proposes one and gives an eligible Admin the project Workflows page to review and publish it; a failed read is a blocker, not an empty list. Organization invitations alone do not grant access to every project.

**2. Publish a workflow**

Open **Workflows** in the project. Publish the bundled [Development workflow definition](/examples/development.v1.json) or import a valid definition. Kiwi validates the ordered chain and assigns a new immutable published revision. See [Workflows and gates](/workflows) 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.

```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"]
    }
  ]
}
```

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](/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](/runs-and-history) and [Retries and recovery](/retries-and-recovery).


# Remote MCP
Source: https://docs.kiwiflow.io/remote-mcp

Connect an existing agent environment to hosted Kiwi through OAuth or a project-bound MCP key.

Kiwi provides a hosted Streamable HTTP MCP connection at the path /mcp. The signed-in app's setup helper gives you the complete canonical endpoint for your project. OAuth protected-resource metadata is available at /.well-known/oauth-protected-resource/mcp on the same host. Use the endpoint from the helper; do not guess or type a host.

For the default setup path, select the intended organization in Kiwi, then open **Set up your agent → Copy setup prompt** from [Projects home](https://www.kiwiflow.io/app) or the global [MCP & access page](https://www.kiwiflow.io/app/mcp). Choose the project inside the helper. See [Set up your agent](/ai-quickstart) for account, invitation, and client-connection steps.

## Connect with OAuth

OAuth is the usual setup for an existing agent client. In that client's MCP settings, add a remote server with the URL copied from Kiwi's setup helper and use OAuth sign-in. The access token must target the exact /mcp resource and include the user:org:read scope. Select the organization that contains the intended project in the sign-in flow.

Use the configuration controls supported by your agent client. If the client stores MCP settings in a file, follow that client's own instructions and keep credentials in its credential store. The agent client connects directly to the hosted endpoint.

## Project-bound MCP keys

For a client that supports a static Authorization header, a project Admin can open **MCP & access**, select one project, choose read-only or workflow-write access, and issue an expiring key. Send its one-time secret as a Bearer token:

```http theme={null}
Authorization: Bearer YOUR_MCP_KEY
```

Read-only keys can call read tools. Workflow-write keys can also start runs and report ordinary agent step progress. Both are restricted to one project and the issuer's current project grant. They cannot make human decisions, manage organization settings, or submit checker-origin results. A checker key cannot authenticate to MCP.

The key secret is returned only once. Issuance replay does not reveal it again or create a replacement. If the one-time secret is lost, revoke that key in Kiwi and issue a new one.

## Available tools

Discover the current tool list in your MCP client after connecting. The hosted service supports these tools; argument names are camelCase.

| Tool | Purpose and inputs |
| - | - |
| list\_projects | No arguments. Lists projects available to the authenticated user. A static key sees only its bound project. |
| list\_workflows | projectId, optional offset and limit. Lists published definitions, revisions, digests, and pagination totals. Defaults to offset 0 and limit 50; maximum limit 100. |
| list\_connections | projectId. Lists active nonsecret references and exact workflow-step bindings. |
| start\_run | projectId, commandId, workflowId, optional workflowRevision, requestText or requestReference, optional responsibleUserId, designatedOwnerId, and designatedReviewerId, plus declared harness/session fields. Creates a pinned run and initial graph. |
| get\_run | runId and declared harness/session fields. Reads the current actor-specific run projection and event cursor. |
| start\_step | runId, stepId, commandId, positive expectedRunVersion, attemptId, and declared harness/session fields. Starts an eligible attempt. |
| submit\_result | The start\_step fields plus outputs. Submits ordinary step outputs; it cannot submit human decisions or Verify results. |
| report\_blocker | The start\_step fields plus reason. Records a resumable blocker for that owned attempt. |
| handoff\_step | The start\_step fields plus a new nextAttemptId and notes. Queues the same step for the run's responsible human. |
| list\_skills | projectId. Lists the authorized skill library. |
| get\_profile | projectId, profileId, version. Reads exact published safe profile settings. |
| get\_assignment | Explicit run/step/optional child assignment and harness/session. Reads its pinned work contract and current context. |
| get\_step\_skill | Explicit run/step or child, exact skill/version, and harness/session. Delivers bound instructions and their file/dependency manifest. |
| get\_skill\_file | The same assignment and exact skill/version plus path. Delivers a referenced text file. |
| create\_assignment | Current parent attempt, run version, command ID, designated project member, scope, and pinned skill. Records bounded delegated work. |
| start\_assignment | Child assignment, current run version, command ID, and harness/session. Claims the assigned task. |
| submit\_assignment | Child assignment, current run version, command ID, outputs, and harness/session. Records evidence without accepting the parent. |
| report\_configuration | Current owned attempt or child, run version, command ID, and safe exposed settings. Appends an attributed report. |
| report\_skill\_use | Current owned attempt or child, run version, command ID, and declared skill/version use. Keeps claims separate from pins. |
| create\_skill\_check | projectId, exact draft/release target, command ID, and optional workflow context. Creates a persisted remote checker job. |
| run\_skill\_check | projectId, job ID, and command ID. Runs a bounded remote review; pending retries retain the same job. |
| get\_skill\_check | projectId and job ID. Reads status and the retained report history. |

For workflow-skill versions, assignment instructions, and remote checks, see [Workflow skills and execution records](/workflow-skills). For the step order, output shape, human pauses, and retry rules, follow the [Agent guide](/for-agents). For CI check reports, use a checker credential and [CI reporting](/ci-reporting).

## MCP responses and errors

Successful tool calls return structuredContent as well as a text content item containing the same JSON. A run mutation returns an updated run projection and receipt. get\_run returns a run projection and eventCursor; it does not return a full event list. The receipt identifies the command, whether it was recorded or replayed, the new run version and cursor, and the recorded event.

A simplified get\_run response has this shape:

```json theme={null}
{
  "run": {
    "runId": "00000000-0000-4000-8000-000000000000",
    "projectId": "00000000-0000-4000-8000-000000000001",
    "status": "active",
    "version": 1,
    "candidate": null,
    "candidateRevision": 0,
    "planRevision": 0,
    "graph": [
      {
        "stepId": "plan",
        "name": "Plan",
        "status": "ready",
        "allowedActorKinds": ["human", "agent"],
        "eligibleRoles": ["admin", "contributor", "reviewer"],
        "requiredOutputs": [
          { "name": "scope", "type": "text" },
          { "name": "acceptance_criteria", "type": "text-list" },
          { "name": "required_checks", "type": "check-definition-list", "minimum_items": 1 }
        ],
        "acceptance": { "mode": "human_decision", "assignee": "designated_owner" },
        "currentAttemptId": null,
        "attempts": []
      }
    ],
    "checkResults": [],
    "nextActions": ["start_step"]
  },
  "eventCursor": 1
}
```

Identifiers and versions above are illustrative. MCP errors return isError: true and a JSON text content item with error and message. If a mutation may have reached Kiwi but its response is missing, retry the identical command with the same payload. A successful MCP tool call does not establish acceptance of a workflow step or run.


# Retries and recovery
Source: https://docs.kiwiflow.io/retries-and-recovery

Recover from unknown responses, stale attempts, blockers, handoffs, failed checks, rework, and cancellation.

Choose recovery based on what Kiwi confirmed. A known validation, authority, missing-resource, or stale-command rejection means Kiwi rejected that request. A lost response or server error can occur after a run commit, so do not treat every HTTP error as proof that nothing happened.

## Unknown outcome or definitive rejection

| What you observed | What to do |
| - | - |
| Connection closed, timeout, or client ended before the response; no definitive service error | Retry the identical command with the same command\_id (or MCP commandId), same payload, expected version, attempt, and declared harness/session. Kiwi returns the stored receipt if it recorded the command. |
| 400 validation error, 401 or 403 authority error, or 404 resource error | The request was rejected. Fix the input or access, read current state, then use a new command ID for the next valid command. |
| 409 stale version, stale attempt, invalid transition, or changed replay content | Read the current run and attempt. Preserve the current attempt ID when it remains active; create a new command ID for the updated request. Do not reuse the old command ID with changed content. |
| 500 or another 5xx, including a timeout returned by a proxy | Unless the response identifies a known application rejection, treat the outcome as uncertain. For a run command or checker report, retry the identical command ID and body. |
| 503 integration dependency unavailable | Do not assume the operation completed. Check its current status in Kiwi before trying again. |

Every run state mutation requires a positive current expected\_run\_version. Do not reuse a version from before another action. See the [Integration API reference](/api-reference) for the supported external request shapes.

## Attempt IDs

When a ready node has no currentAttemptId, generate a new UUID for the first attempt. Use the currentAttemptId returned by the server for subsequent mutations to that attempt. Do not invent an attempt ID from a null field.

For a manually reported resumable blocker, only the same principal, performer, and session may resume the blocked attempt; call start\_step with that same attempt ID. A new agent session must not impersonate the old session to resume it.

A handoff\_step call ends the current performer attempt and queues the step under a new ID reserved for the run's responsible human. The responsible human starts that queued attempt. An unrelated agent cannot claim it.

## Checks and candidate changes

Before reporting CI evidence, read `GET /v1/runs/{runId}/checks`. Use its current runVersion, accepted plan revision, candidate reference, implementation attempt, and verification attempt. If Verify is ready and verificationAttemptId is null, generate one UUID for the first checker report; then use the returned current attempt on later reports.

Each check binds to the current accepted Plan, candidate, Implement attempt, and Verify attempt. A pass is the only status that can satisfy the gate. fail fails Verify; blocked and not-applicable do not satisfy it. Failed or blocked check outcomes require authorized rework; they cannot be resumed as a manually reported blocker.

Rework preserves attempt history. It can keep the current accepted Plan or explicitly revise it. Revising Plan increments the Plan revision and returns to Plan. Rework at Implement invalidates the current candidate and all dependent verification and review evidence. Reports for the previous candidate remain visible but cannot pass the new gate. Rerun checks and review against the new candidate.

## Credential outcomes

If MCP or checker credential issuance has an unresolved result, inspect its nonsecret status in the Kiwi app before creating another credential. An issuance replay does not reveal an already-issued secret. If the secret is confirmed lost, use the app to revoke that credential and issue a replacement.

If Kiwi shows that revocation is pending, use the available retry action in the app and check its status there.

## Rework, handoff, and cancellation

An authorized human can request rework through the app. The request needs a reason and may set revise\_plan. The designated owner decides rework on a submitted Plan; other rework follows the workflow's authorized role. A responsible human or project Admin can cancel with a reason. Cancellation prevents future Kiwi run transitions but does not stop external agents, jobs, or systems.

Use [Manual participation](/participation) for human roles and structured step outputs, and [Runs and history](/runs-and-history) to inspect current attempts and prior events.


# Runs and history
Source: https://docs.kiwiflow.io/runs-and-history

Read the current run graph, attempts, evidence, version, available actions, and event history.

A run is a record of one request against one immutable published workflow revision. Open the project **Runs** area to inspect active and past work. A run preserves earlier attempts and committed workflow events so people can see what changed and who reported it.

## Read a run

The current run projection includes the pinned workflow ID and revision, run status and version, current candidate and plan revision, step graph, current and previous attempts, recorded check results, and actor-specific nextActions.

Run status is active, blocked, completed, or cancelled. Each graph node shows its status, predecessor, instructions, eligible actor kinds and roles, required outputs, acceptance rule, current attempt ID, and attempt history. An attempt records its state, performer if assigned, outputs or blocker, handoff notes, and whether earlier evidence has been superseded.

The candidate is the exact reference submitted by Implement. Verification and independent review attach to that candidate, Plan revision, implementation attempt, and their own current attempts. A new candidate or Plan revision means older candidate-dependent results remain visible as history but no longer satisfy the gate.

## Available actions

The nextActions list is calculated for the authenticated actor and current run state. It may include start\_step, submit\_step, decide\_step, report\_blocker, handoff\_step, report\_check, request\_rework, and cancel\_run. Treat this list and the node's currentAttemptId as current state; do not infer permission from a role label or an earlier response.

An MCP run mutation returns the updated run projection and a receipt identifying its command and recorded event. MCP get\_run returns a run projection and eventCursor; it does not return an unfiltered event array. The cursor marks the event position represented by that projection.

## Event history

Use **Logs** to inspect recorded project events and follow an event to its run. Project event filters include run ID and event type. The MCP get\_run eventCursor refers to the events represented in that projection; use the hosted Logs area for browsing project history.

Events are committed workflow reports and transitions. They are not a full server log or a passive record of editor activity, prompts, transcripts, or external CI output that was never submitted. For current permissions and execution order, see the [Agent guide](/for-agents).


# Troubleshooting
Source: https://docs.kiwiflow.io/troubleshooting

Diagnose account access, agent connection, workflow reporting, CI check, and public documentation issues.

## The project or run is missing

1. Confirm you are signed in to the intended organization.
2. Ask an organization Admin or project Admin to confirm you have access to the project. Organization membership alone does not grant access to every project.
3. For OAuth MCP, reconnect with the correct organization selected. For a static MCP key, confirm in Kiwi that it is active and belongs to the requested project.

## The agent cannot connect to MCP

* **401:** complete OAuth sign-in in the agent client and select the organization that contains the project. Confirm the client uses the exact endpoint copied from the signed-in app.
* **421 invalid\_host:** copy the canonical endpoint again from the Kiwi setup helper. Do not guess a hostname or change the URL path.
* **403 invalid\_origin:** confirm the agent client is using the copied endpoint and a supported connection method. If the error remains, ask your workspace Admin for help.
* **Missing tool or disabled action:** refresh tool discovery and check that client's installed-version approval settings. Kiwi still checks project role and workflow gates.

## A workflow report is rejected

* For invalid output, read the run graph for exact required outputs and field names. Root output names may be snake\_case while nested check-definition fields are camelCase.
* For stale state, read the current run version and currentAttemptId; submit with a new command ID and the current identifiers.
* For a blocked predecessor, inspect the graph and complete its gate before starting the next step.
* For independent-review rejection, verify that the actual review performer and actual session both differ from Implement.
* A receipt means a command was recorded. Inspect the returned run and nextActions to see whether the gate accepted it.

## CI cannot report a check

Read `GET /v1/runs/{runId}/checks` with the checker credential and compare its check list to the current Plan. The key must be active in Kiwi, bound to the project, and allowed to report that check ID. The accepted Plan must allow checker\_reported and list the key's nonsecret reporterId; the credential record id is not interchangeable.

Also verify that POST fields match the latest context: expected\_run\_version, plan\_revision, candidate\_ref, implementation\_attempt\_id, and attempt\_id. A stale candidate or Plan requires refreshing context. Only pass can satisfy a check; not-applicable blocks Verify.

If the credential appears unresolved, inspect its nonsecret record in Kiwi before issuing another. A replay does not reveal a lost secret or create a replacement. See [CI reporting](/ci-reporting) and [Retries and recovery](/retries-and-recovery).

## Public Markdown or page discovery

The [public documentation index](https://docs.kiwiflow.io/llms.txt) lists the published customer pages. Each page is also available as Markdown by adding .md to its page URL; the [full Markdown export](https://docs.kiwiflow.io/llms-full.txt) contains the complete public documentation set.


# Workflow skills and execution records
Source: https://docs.kiwiflow.io/workflow-skills

Bind published instructions and agent profiles to workflow steps, then inspect their use in a run.

A workflow step can bind published skill versions and an optional agent profile. Kiwi keeps those bindings with the workflow revision and run. Publishing another release does not change work already in progress.

## Publish instructions

Open a project's **Skills** area. Create a draft with its instructions, referenced text files, exact skill dependencies, and required tools. To revise a release, start from that exact version and describe the change. Use a higher release number; the selected predecessor remains explicit. For feedback-driven changes, preserve the real failure example, affected consumers, and intended behavior change. Maintenance revisions can leave feedback absent.

Create a remote check for the current draft, inspect its findings, and publish a numbered release as a project Admin. Publication links the exact checked content and the Admin's decision. An incomplete semantic review requires explicit acknowledgement and remains recorded as incomplete. A completed review can contain findings; it does not make a workflow acceptance decision.

Published instructions and profile settings are immutable. Archive a version to prevent new workflow bindings and runs from selecting it. Existing runs keep their pinned versions and authorized access.

## Bind a workflow

Include exact references in the workflow JSON you publish:

```json theme={null}
{
  "skills": [{ "skillId": "implementation", "version": 4 }],
  "agent_profile": { "profileId": "developer", "version": 2 }
}
```

These are optional fields on a step; retain its other required fields. The optional workflow-level delegated\_skills array declares released skills available for bounded child assignments. The service resolves dependencies and validates the complete manifest. Importing a supplied digest cannot replace that validation.

Create a new workflow revision and run to adopt updated skills or profiles. A run keeps its original versions through retries, rework, and handoff. Earlier runs without version records show that tracking was not recorded.

## Fetch an assignment through MCP

Give a worker explicit run, step, and, when delegated, assignment references. A concise project entry instruction can be:

```text wrap theme={null}
For assigned Kiwi work, fetch get_assignment for the explicit run and step.
Load its selected skill with get_step_skill. Retrieve supporting resources
through get_skill_file or the dependency skill at the returned pinned version
when the selected instructions require them. Follow the returned scope and
report outputs against that assignment.
```

The entry instruction routes work; the full procedure stays in Kiwi. Agents fetch instructions before starting an eligible step. Delegated workers retrieve their own bounded contract, while parent output requirements are identified separately.

After starting work, use report\_configuration and report\_skill\_use to record exposed runtime settings and declared skill use. Unknown values remain unknown. Append a report when settings change. Configuration uses a safe allowlist; credentials, raw prompts, and environment dumps are excluded.

get\_step\_skill returns the exact instruction body, dependency references, required tools, and reference-file manifest. get\_skill\_file returns a specific file from that release. Reading content records delivery, not proof that the agent followed it. File digests are SHA-256 of the exact content string encoded as canonical JSON, including its quotes and escaped characters. They differ from a raw file-byte hash. Preserve the returned text exactly when verifying its digest.

## Inspect a run

The run view shows readable skill and profile versions. Select a step to inspect its bindings, parent and child performers, harness versions, configuration history, reported skill use, and instruction deliveries. Version links open the exact release and its related authorized runs.

Server-pinned versions and agent-reported settings have distinct provenance. A model identifier can be a requested alias; Kiwi does not infer an unavailable provider revision or hidden setting. Older attempts retain their evidence and participant records after replacement.

Compare releases or run attempts to see meaningful changes first. Expand unchanged fields when needed. Skill comparisons cover instructions, files, dependencies, and tools; execution comparisons include versions, participants, profiles, reported settings, and unknowns.

## Use remote checks

The hosted checker exposes create\_skill\_check, run\_skill\_check, and get\_skill\_check through MCP. Use them for a specific draft or release. Kiwi retains structural observations, semantic findings, exact input and context digests, checker and ruleset versions, and reviewer settings. Jobs can be pending or complete; after an unknown result, read the same job before starting another check.

A semantic review that is unavailable or incomplete remains blocked or incomplete in the result, while any completed structural observations remain readable. The page and MCP response show the actual state. A blocked result is not a completed semantic review.

A product defect is a failed result. An unusable capture, tool, or criterion produces blocked evidence and a decision request to its owner. The checker helps identify instruction defects and propose repairs; publishing changes and accepting workflow work retain their designated authority.


# Workflows and gates
Source: https://docs.kiwiflow.io/workflows

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](/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](/runs-and-history) and [Retries and recovery](/retries-and-recovery).