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

# How Kanaeru works

> The model behind visions, roadmaps, outcomes, tasks, journeys, blueprints, and pipelines.

Kanaeru organizes work as a loop. Each link narrows the one before it, you review at the points where a misunderstanding would be expensive, and each outcome's retrospective saves [learnings](/concepts/learning-loop) that Kana carries into the next one. Refinement keeps the roadmap in shape the whole time.

```mermaid theme={null}
%%{init: {"theme":"base","themeVariables":{"fontFamily":"Inter, ui-sans-serif, system-ui, sans-serif","fontSize":"16px","primaryColor":"#FFF1E0","primaryBorderColor":"#A94604","primaryTextColor":"#3B1A02","secondaryColor":"#FFE4C2","tertiaryColor":"#FFF8F0","lineColor":"#A94604","clusterBkg":"#FFF8F0","clusterBorder":"#E8B98A","edgeLabelBackground":"#FFFFFF","git0":"#A94604","git1":"#FF9F0A","git2":"#D97706","git3":"#B45309","gitBranchLabel0":"#FFFFFF","gitBranchLabel1":"#3B1A02","gitBranchLabel2":"#FFFFFF","commitLabelColor":"#3B1A02","commitLabelBackground":"#FFF1E0"}}}%%
flowchart TD
  V[Vision] --> R[Roadmap]
  RF[Refinement] -.-> R
  R --> O[Outcome]
  O --> T[Tasks, journeys, blueprints]
  T --> RV[Review]
  RV --> TP[Task planning]
  TP --> P[Pipelines]
  P --> PR[Task pull requests]
  PR --> D[Delivery]
  D --> RT[Retrospective]
  RT -. learnings .-> O
```

## Vision

The **vision** is the long-term result you're aiming for. One vision usually takes several outcomes to reach, and you can refine it as you learn. Each vision lives in its own **workspace**: creating a workspace means describing a vision.

## Roadmap and backlog

The **roadmap** holds every item needed to reach the vision. Items come from you, from Kana's suggestions, and from your connected tools. Proposed items stay proposed until you accept them.

Items that aren't part of an outcome yet sit in the **backlog**. They wait there until they're scoped into an outcome. Kana's **auto-suggested** items wait there too, for you to review.

A **refinement** session is where you shape the roadmap with Kana. Start one with **New Refinement**. In it, Kana can:

* reorder, merge, split, and clarify items
* check whether an item already exists before adding a new one
* pull in detail from your connected tools and the code
* group backlog items into new or existing outcomes

You can open a refinement session at any point, before or alongside the rest of the work.

## Outcome

An **outcome** is one cycle of work toward your vision that ends in something you can actually use. It groups roadmap items into a deliverable and moves through a fixed lifecycle: planning, review, execution, delivery, and a retrospective. See [Outcomes](/concepts/outcomes).

## Tasks, journeys, and blueprints

In the outcome's **planning** session, Kana breaks it into **tasks**. Each task covers one or more **user journeys**, the paths a user takes through what you're building. Each journey carries:

* **Acceptance criteria**: scenarios written as Given / When / Then. A task isn't done until its acceptance tests pass.
* **Blueprints**: the designs that journey needs, generated before any code is written so you can check what Kana understood.

Blueprints come in many types, and each journey uses the ones its surfaces need:

| Blueprint | Shows |
| - | - |
| **UX Mockup** | The screens, built as a live, clickable prototype of the real route. Screens not yet prototyped show as planned |
| **User Journey** | The steps a user takes, with their scenarios |
| **Sequence Diagram** | How components talk to each other over time |
| **API Contract** | Endpoints, requests, and responses |
| **Data Model** and **Domain Model** | Entities, relationships, business concepts, and their rules |
| **Architecture** | Components, deployment, integrations, and data flow |
| **State Machine** | States and the transitions between them |
| **Intent Spec**, **Quality Profile**, **Tech Stack** | The intent behind the outcome, the quality it must meet, and the technology choices with their reasons |

See [Blueprints](/concepts/blueprints) for every type and how to review them.

Tasks without a declared dependency run in parallel.

## Understanding gaps

An **understanding gap** is a place where what Kana understood may not match what you meant. She raises it at the narrowest level it affects: one journey, one task, the task list, or the whole outcome.

Some gaps are routine: missing information, an ambiguity, an assumption to confirm, or a recorded decision. Others are **blocking**: a risk, an escalation, a spec gap, intent drift, a comprehension check, or context only you hold. Blocking gaps must be resolved before execution can start. See [Understanding gaps](/concepts/blueprints#understanding-gaps).

## Review

You review the plan in the **Plan & Review** section of the outcome, in the same order it was built: the task breakdown, then each task's journeys, then each journey with its acceptance criteria and blueprints.

```mermaid theme={null}
%%{init: {"theme":"base","themeVariables":{"fontFamily":"Inter, ui-sans-serif, system-ui, sans-serif","fontSize":"16px","primaryColor":"#FFF1E0","primaryBorderColor":"#A94604","primaryTextColor":"#3B1A02","secondaryColor":"#FFE4C2","tertiaryColor":"#FFF8F0","lineColor":"#A94604","clusterBkg":"#FFF8F0","clusterBorder":"#E8B98A","edgeLabelBackground":"#FFFFFF","git0":"#A94604","git1":"#FF9F0A","git2":"#D97706","git3":"#B45309","gitBranchLabel0":"#FFFFFF","gitBranchLabel1":"#3B1A02","gitBranchLabel2":"#FFFFFF","commitLabelColor":"#3B1A02","commitLabelBackground":"#FFF1E0"}}}%%
flowchart TD
  A[Task breakdown] -->|Approve Task Breakdown| B[Journey list]
  B -->|Approve Journey List| C[Each journey: criteria + blueprints]
  C --> G{Blocking gaps left?}
  G -- yes --> C
  G -- no --> Q[Kana's quiz]
  Q -->|every answer right| S[Start Outcome]
  Q -->|missed one| Q
```

**Start Outcome** stays locked until everything it depends on is in place:

* every task you want built is approved, with its requirements reviewed
* every blueprint is approved, with no open blocking annotations
* no blocking understanding gaps are left
* you've passed Kana's quiz

The **quiz** is how Kana checks that you understand what you're approving. In the review chat, she walks you through the plan, then asks three to five questions. You need every answer right. If you miss one, she explains again and asks a new set. When you choose **Start Outcome**, you confirm you passed, then choose **Confirm and start**.

## Pipelines

As each task becomes ready, a **task planning** session designs its **pipeline**, the exact steps that will build and check it. An independent reviewer checks the plan before any step runs.

A pipeline has three levels:

* **Phases**: always **Biz Logic**, **API**, **UI**, **QA**, and **Deploy**, in that order. A phase that doesn't apply is skipped with a recorded reason.
* **Layers** inside each phase, matching the parts of the codebase. Biz Logic has domain and use-case layers. API has controllers, adapters, and API clients. UI has components, pages, state management, and front-end use cases.
* **Steps** inside each layer, run one at a time.

```mermaid theme={null}
%%{init: {"theme":"base","themeVariables":{"fontFamily":"Inter, ui-sans-serif, system-ui, sans-serif","fontSize":"16px","primaryColor":"#FFF1E0","primaryBorderColor":"#A94604","primaryTextColor":"#3B1A02","secondaryColor":"#FFE4C2","tertiaryColor":"#FFF8F0","lineColor":"#A94604","clusterBkg":"#FFF8F0","clusterBorder":"#E8B98A","edgeLabelBackground":"#FFFFFF","git0":"#A94604","git1":"#FF9F0A","git2":"#D97706","git3":"#B45309","gitBranchLabel0":"#FFFFFF","gitBranchLabel1":"#3B1A02","gitBranchLabel2":"#FFFFFF","commitLabelColor":"#3B1A02","commitLabelBackground":"#FFF1E0"}}}%%
flowchart TD
  subgraph BL[Biz Logic]
    direction LR
    D[domain] --> U[use case]
  end
  subgraph API
    direction LR
    CT[controllers] --> AD[adapters] --> AC[API clients]
  end
  subgraph UI
    direction LR
    CO[components] --> PG[pages] --> SM[state]
  end
  subgraph QA
    direction LR
    E2E[end-to-end tests] --> SEC[security + quality]
  end
  subgraph Deploy
    direction LR
    CM[commit] --> FR[final review] --> PRQ[pull request]
  end
  BL --> API --> UI --> QA --> Deploy
```

Each layer runs two cycles:

1. **Build.** Most layers write the code first, then its tests. Use-case layers are test-first: the tests, and the interface they define, come before the implementation. Every piece of generated code is lint-fixed immediately.
2. **Review and fix.** A review step checks the code or the tests just written. If it rejects the work, the pipeline sends it back to the step that wrote it, then reviews it again. After a few rejections, an **escalation judge** decides whether to accept it, send it back again, or block it for you.

```mermaid theme={null}
%%{init: {"theme":"base","themeVariables":{"fontFamily":"Inter, ui-sans-serif, system-ui, sans-serif","fontSize":"16px","primaryColor":"#FFF1E0","primaryBorderColor":"#A94604","primaryTextColor":"#3B1A02","secondaryColor":"#FFE4C2","tertiaryColor":"#FFF8F0","lineColor":"#A94604","clusterBkg":"#FFF8F0","clusterBorder":"#E8B98A","edgeLabelBackground":"#FFFFFF","git0":"#A94604","git1":"#FF9F0A","git2":"#D97706","git3":"#B45309","gitBranchLabel0":"#FFFFFF","gitBranchLabel1":"#3B1A02","gitBranchLabel2":"#FFFFFF","commitLabelColor":"#3B1A02","commitLabelBackground":"#FFF1E0"}}}%%
flowchart TD
  G[Write code or tests] --> L[Lint fix]
  L --> R{Review}
  R -- approved --> N[Next step]
  R -- rejected --> G
  R -- rejected again --> J{Escalation judge}
  J -- accept --> N
  J -- retry --> G
  J -- block --> H[Waits for you]
```

Business-logic layers end with **mutation testing**, which checks that the tests actually catch bugs.

Not every step is an agent. Steps can be **agents**, built-in **skills** such as commit or create PR, or **manual** actions. Each also has a category, such as generation, test, lint, review, or quality.

**QA** proves the task works end to end. Every task gets end-to-end tests of its acceptance criteria, along with security, code-review, and quality gates. **Deploy** commits the work, runs a fresh review of the whole change, opens a pull request, and verifies the result. Every pipeline ends with a short task **retrospective** and a **context sync**, so the next task starts with what this one learned.

The agent then cares for the pull request, answering review comments and fixing CI until it merges. Each task works in its own Git worktree and branch, so parallel tasks never share a checkout. Up to three tasks per outcome run at once, and a task that depends on another can start while the other's pull request is still in review.

## Delivery and retrospective

Task pull requests merge into the outcome's own branch (`outcome/<id>`). When the last one has merged, Kanaeru opens one **delivery pull request** per repository, from the outcome branch into your default branch. Merging it ships the whole outcome at once. If you'd rather review another way, ask Kana. For example, she can stack task pull requests or merge each one straight into your base branch.

```mermaid theme={null}
%%{init: {"theme":"base","themeVariables":{"fontFamily":"Inter, ui-sans-serif, system-ui, sans-serif","fontSize":"16px","primaryColor":"#FFF1E0","primaryBorderColor":"#A94604","primaryTextColor":"#3B1A02","secondaryColor":"#FFE4C2","tertiaryColor":"#FFF8F0","lineColor":"#A94604","clusterBkg":"#FFF8F0","clusterBorder":"#E8B98A","edgeLabelBackground":"#FFFFFF","git0":"#A94604","git1":"#FF9F0A","git2":"#D97706","git3":"#B45309","gitBranchLabel0":"#FFFFFF","gitBranchLabel1":"#3B1A02","gitBranchLabel2":"#FFFFFF","commitLabelColor":"#3B1A02","commitLabelBackground":"#FFF1E0"}}}%%
gitGraph TB:
  commit id: "main"
  branch outcome
  checkout outcome
  branch task-1
  commit id: "task 1"
  checkout outcome
  merge task-1 id: "task 1 PR"
  branch task-2
  commit id: "task 2"
  checkout outcome
  merge task-2 id: "task 2 PR"
  checkout main
  merge outcome id: "delivery PR"
```

Once the delivery pull request is merged, choose **Start retrospective**. The **retrospective** covers what went well, what didn't, and what it cost. Once at least one piece of feedback is recorded (yours or Kana's) and you've checked the **evidence package** (test results, diffs, approvals, and gate results), choose **Accept delivery and complete outcome**. Findings from the retrospective are saved as learnings that later Kana sessions draw on, so the next outcome starts where this one left off. See [Learning loop](/concepts/learning-loop).

## Sessions

Every stage of this loop runs as a **Kana session** of a particular type: Vision & Roadmap, Refinement, Planning, Review, Task Planning, Task Execution, and Retrospective. Sessions run on an [agent machine](/machines/connect-a-machine) with the [runtime](/machines/runtimes) you choose. You talk to them in the web app, from the [CLI](/cli/overview), or from the [Kanaeru app inside Codex or Claude](/mcp/connect).

## Who does what

| Role | Description |
| - | - |
| **You** | Set the vision, answer questions, approve plans and blueprints, and accept deliveries |
| **Kana** | Your Kanaeru teammate. She plans, builds, reviews, and reports back, with the reasoning behind each decision |
| **Koa** | Kana's operator agent. Hand an outcome to him and he runs its whole lifecycle in Kana for you, one Koa per outcome. He decides from what you approved and the evidence, and contacts you through your human inbox, **Waiting on you**, only for calls that are yours. Take it back from him at any time |


## Related topics

- [Kanaeru overview](/index.md)
- [Quickstart](/quickstart.md)
- [Settings and profile](/guides/settings.md)


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