Talk to kanman

When you open your workspace, you land in a conversation with kanman. kanman is the teammate that writes your stories, builds them, checks them and tells you how it went. The conversation is the one place where you see what happened, answer what needs you and hand over new work.

What you see when you open it

• What happened since your last visit. New messages sit below a line that says how many are new, for example “4 new”. The conversation opens right there.
• Which chat you are in. The top of the conversation names it: General or a team. Under the name, one line says what the chat is about, and on a phone what the team is doing right now, for example “Working · 1 running · 2 in review”.
• What needs you. When kanman waits for you in this chat, an amber bell appears at the top right. Point at it (or focus it) to read how many things need you, for example “1 thing needs you”. Click it to jump to that message; click again for the next one. It rings once when something new needs you and goes away when nothing does. It never covers a message.
• Cards. kanman writes one sentence and puts the details into a card. Every card first says what it is for, in a small line at its top: Decision, Run, Evidence for review, Weekly report, Incident, Drafted stories, Done on my own and so on, in General also which team it belongs to, with its status on the right. Below follows what it is about, for example the story or the question. A card that needs your answer has an amber edge and says so in that top line. Cards stay up to date while you read them, for example an incident card shows when the incident moves from “Open” to “Mitigating”.

General and your team chats

You have one conversation with kanman per place, like separate chats:

• General is the one conversation across all your teams. It opens when you open the workspace, centred on the screen, with nothing beside it. Ask what needs you, how things are going everywhere, or anything that is not about one team. The short summary of what happened since your last visit (“Since yesterday: …”, or “Since Friday: …” after a weekend) arrives here, once a day when something happened, and the conversation opens at it, with a row for each team that has news: what happened there and Open chat, which takes you to that team’s chat. The team with a decision waiting for you comes first, and its button says what you do there: Answer 2 decisions. When nothing happened since your last visit, a short line under the newest message says so, and how many items still need you. Ask “How are the teams doing?” for one sentence per team, the teams that need you first, or “Show me the weekly report” for the newest report of each team.
• Every team has its own chat. Everything about that team lands there: its runs, decisions, reports, incidents and setup. When you open a team’s chat, the conversation moves to the left and the team’s board opens beside it. On a phone the team’s chat fills the screen; the board and team settings buttons next to the chip in the message box open them from the bottom. The team’s status and what needs you are in the chip’s menu, and the amber bell in the message box takes you to what needs you.

To switch, use the chip under the message box. It lists General and your teams, each with how many new messages it has and how many need you. A dot on the chip tells you that something happened in another chat. The chip is the only place to switch: the conversation decides what you see. You can also press G then T to open it from the keyboard, use the arrow keys and press Enter.

Your conversation is private. Other people in the workspace see the shared results (the board, runs, decisions and the audit log), not what you asked kanman.

What kanman is working on

At the end of the conversation, under the newest message, a quiet line shows what kanman is working on right now: one small line in italics with a softly breathing dot, for example

Claude Code is running go test in flow_object_okta · INT-1079 · 2 more

When several things run, the line slowly changes between them. In a team’s chat it shows that team’s work; in General it shows the work of every team, with the team in front (“Integrations · …”).

• Select the sentence to open that run’s agent log.
• Select 2 more or the arrow for a short list of everything running right now: the story, the step and how long it has been running.

When nothing runs, the line fades away. If kanman waits for something, the notices by the message field say so.

Open a card

Click a card (a run, a story, a decision, a report or an incident) to open its page. The Evidence card of a story in review opens its run at the evidence: every criterion with its proof, the tests and CI. On a large screen it opens beside the conversation, on a phone as a sheet from the bottom. Close, Escape or swiping the sheet down brings you back to the same place in the conversation. In a team’s chat, closing a page brings you back to the team’s board, never out of the team’s chat. See Tour of the app.

Answer a decision where you read it

When kanman needs your OK, for example on the plan of a story, the message carries a decision card. Its title says in a few words what it is about (“PU-43: The acceptance spec fails before it measures anything.”); Why opens kanman’s full reasoning right in the card. The options are listed one below the other, each in full, however long it is. The one kanman recommends is highlighted and marked Recommended. Click an option, such as Approve plan; Add a note lets you tell kanman more with your answer. The card folds into one line (“You approved the plan”), the count on the decisions icon in the top bar goes down and the bell at the top of the chat goes away once nothing else in the chat needs you. You can still answer the same decision in the Decisions inbox or on the run page; whichever you use first counts everywhere.

One card per story

Everything about one story lives in one card in the team’s chat, from the moment kanman writes it to the merge. The top of the card says what it is and where the story is now (In Backlog, Implementing, In review, Merged …). Below it, a bar of five parts shows how far the run got (Planning, Implementing, Verifying, Review, Done) and names the current step; if kanman had to rework the change, the line next to it says so (“Attempt 2 · reworked once”). When the change goes out to further repositories, one bar with counts shows how many merge requests are merged, waiting for review or need attention, with links to the ones waiting for you.

Details at the bottom of the card opens the rest: how long kanman worked on the story, the run’s ID with a copy button, and the history as a short timeline with the time of each step:

Started · Plan approved by you · Spec fixed as you asked · Attempt 2

The timeline shows the latest steps; Show all … steps opens the earlier ones.

The card stays where the story started in the chat and changes in place, so a busy team does not fill your chat with a line for every step. While the story waits in the Backlog, Start now on the card starts it.

• A question for you about the story (the plan, a failing check, the merge) appears as a card of its own, highlighted, until you answer it.
• Once answered, the question folds into the story’s card: it shows your answer for a moment, then becomes a step in the history, for example “Plan approved by you”. Click the step to open the decision with everything that was said. If you talked about a decision afterwards, it stays where the conversation about it is.
• The rest of the chat keeps its order: messages that came in between stay where they are.

kanman writes a new message only when something concerns you:

• a decision that needs your answer, for example the plan or the merge of a story;
• a story you wrote or moved to Ready failed, was parked or was merged (not when you pressed Merge yourself).

If you follow a team but did not start the run, you see the story’s card in the team’s chat without being notified. Decisions that someone else answered show who answered, on their card and in the story’s history (“Spec fixed as Paula asked”).

Tell kanman a message did not help

When kanman writes to you on its own (a run is ready for review, a report is in, a story was merged), the message has a … button at its top right: point at the message to see it, on a phone it is always there. Choose Not helpful when a message told you nothing you needed. A short line under the message confirms it, with Undo. Only the mark is counted, never the message, to measure how useful kanman’s own messages are; your conversation stays private.

Ask kanman

Type into the box at the bottom and press Enter (on a phone, tap the send button). Shift+Enter starts a new line. kanman shows that it is thinking the moment you send, also on a slow connection. While kanman answers, its reply appears word by word; Stop ends the answer early.

Without a connection (on a train, while your VPN reconnects) a line above the box says that you are offline. You can keep writing: your message waits in the conversation (“Sends when you’re back online”) and goes out by itself when the connection is back. The conversation then catches up on what happened in the meantime, including decisions you answered on another device.

The chip on the left of the box says which chat you are in: General or a team. On a phone, the button for the team’s board sits right next to it; the team’s settings are the Settings tab of the board. In a team’s chat, kanman answers about that team. In a chat without messages yet, suggestions above the box help you start; once the chat is under way, they make room for the messages. You can always ask the same in your own words:

A question in General that is not about one team (“What should we watch out for when we roll out the export?”) is answered right there. Work you describe in General still goes to a team: kanman asks which one when your message does not say it.

Press N anywhere in the app to jump to the box of the chat you are in.

Describe new work

Describe work in the team’s chat: paste a requirement, a bug report, an e-mail or a few sentences into the box and send it. A long paste stays one message and folds to its first lines (Show all opens it), so kanman’s drafts stay in view, also on a phone. kanman drafts stories and shows them as a card, one row per story:

1. To write every ready draft, click Write all 2 ready stories; Reject the ones you do not want first. To pick single drafts, Approve them: the button then says Write 2 stories (the number follows your choice).
2. kanman writes them to your tracker and the card says “2 stories written”.
3. To edit acceptance criteria first, click Open review. The review page shows each draft’s open questions at the top, then every criterion, the test plan and the Demonstrate steps; Back to the conversation brings you back to the card.

kanman drafts with what it knows about the team’s repository: the code host (GitHub or GitLab), the default branch, the package manager and lockfile, the frameworks and scripts in package.json, the CI system, the top-level folders and the start of the README, plus passages from the team’s documents if you added sources under Team settings > Knowledge. So drafts use your package manager’s commands and propose changes for your CI (a .gitlab-ci.yml on GitLab, never GitHub Actions) instead of asking about them. If your workspace runs everything on its own runners, the runner reads these facts itself; your code never passes through kanman’s cloud.

When a request is too vague to draft, kanman asks first (“Before I draft, I need to know: …”), usually with what it would choose. Just answer in the chat: kanman adds your answer to the same request and drafts the stories from both. Navigation and status questions you send in between keep their meaning.

Answer kanman’s questions

kanman settles design and code details on its own and writes them down as assumptions on the story. When a draft still needs something only you can decide, kanman says so right after drafting, for example “I need 2 answers from you before SBX-301 is ready.”, and the questions sit under their story in the card, numbered. Each one says whether it Blocks approval. For each question you can:

• click Answer, type a short answer and press Enter: kanman works it into the acceptance criteria and the test plan, and the question disappears,
• click Let kanman decide: kanman takes its own pick and notes it as an assumption,
• click Not relevant: the question is dropped.

Or just reply in the chat, by number: “1: only the section navigation, 2: you decide, 3: not relevant”. kanman maps your answers to the questions, updates the draft and tells you whether the story is ready now or how many questions still block it (“I worked your answers into SBX-301. It is ready to approve.”). A free-text reply without numbers works too; if kanman cannot tell which question it answers, it asks you to number your answers. A message that is not about the questions, such as new work, is handled as usual.

Clicking Approve on a draft that a question still blocks does not approve it: kanman says why and moves you to the first blocking question. Workspace owners and admins can choose Approve with open questions instead; the questions then stay on the story as notes. See Assumptions and open questions.

Long requirements are always treated as work to draft, even when they mention words like “status”, “overview” or “priority” (for example a UI label you quote). Short questions and commands keep their meaning.

You can attach text files (Markdown, plain text, CSV, JSON, YAML or logs), PDF files and Word documents (.docx) with the paperclip or by dropping them on the box; images work the same way (see Attaching and pasting images). Their text is sent with your message, and the conversation shows each file by its name; kanman drafts from the file like from a pasted requirement.

PDF and Word files. A requirements document, a specification or meeting notes can go in as they are. While kanman reads the file, it shows as “Reading spec.pdf…” in the message box, and Send waits until its text is there. A file can be up to 10 MB, and its text has to fit into one message (about 20,000 characters, together with what you type); for a longer document, attach the part that matters. The file stays on your message: click its name to open it again. A scanned PDF has no text kanman can read; paste a screenshot of the pages instead. Older Word files (.doc) are not supported: save them as .docx first. Reading the file works the same when your workspace runs on its own runners, because no model is involved; the file is stored privately with your conversation, like your images.

Refine an existing story or issue. A vague issue that is already on the board or in your tracker can go through the same drafting: type “refine PU-43” (or “refine #12” for a GitHub or GitLab issue), or open the story and click Refine with kanman, which puts that message into the team’s chat for you. kanman reads the issue, drafts from it like from a pasted requirement, and asks what is unclear. When you write the first draft, kanman updates the existing issue and its story in place, so the key, links and history stay; further drafts become new stories. Stories that are already being worked on, closed stories and drafts that are still waiting for review are not refined.

This is how it looks: a requirement for the Sandbox Team goes in in General, continues in the team’s chat, kanman drafts three stories there, and approving them writes them to the tracker.

Attaching and pasting images

Show kanman what you mean: a screenshot of a bug, a sketch of a screen or a photo of a whiteboard. There are three ways to add an image to your message:

• Paste it. Take a screenshot or copy an image, click into the message box and press Ctrl+V (on a Mac Cmd+V).
• Drop it. Drag one or more images onto the message box.
• Pick it. Click the paperclip next to the send button. On a phone it opens your photo library or the camera.

You can attach PNG, JPEG, WebP and GIF images, up to 6 per message and up to 10 MB each. Very large images are scaled down before they are sent, so they go out quickly and still show every detail kanman needs. Each image appears as a small preview in the message box with a button to remove it; you can send images with or without text. Text files (Markdown, plain text, CSV, JSON, YAML and logs) work as before.

Your sent images appear in your message. Click one to see it larger; Escape or Close brings you back.

kanman looks at your images when it answers. Describe a bug and paste the screenshot, and kanman uses what it shows as context when it drafts the stories, for example the screen, the visible error and the steps that lead to it. If your team’s model cannot read images, kanman says so in one sentence and answers from your text.

Privacy. Images are stored privately with your conversation, and only you can see them, like the rest of your conversation with kanman. They are shown to you through links that expire after a short time. If your workspace runs kanman’s work on its own runners, your runner fetches the image through a short-lived link and sends it to your own model, never to kanman’s cloud models.

Slack and Microsoft Teams. kanman looks at images in the app only. When you send kanman a direct message with images, the copy of that message in your app conversation notes that the images stayed in Slack or Microsoft Teams. A message with only an image gets a short reply that points you to the app.

When a General conversation turns to one team

Conversations often start in General and then become work for one team, for example when you write down what a team should build. kanman notices and asks first, it never moves a conversation on its own: a card says Continue in Sandbox Team and quotes your request.

• Continue in Sandbox Team opens the team’s chat. It starts with a short line “Started in General” and your request, and kanman carries on there, for example by drafting the stories. In General the card folds to “Moved” and a short line stays behind: “Continued in Sandbox Team”, with a link that takes you straight to the team’s chat. In the team’s chat, Back to General takes you to where it started.
• Stay here keeps the conversation in General.

You can also move a message yourself: point at one of your messages (on a phone it is always shown), open its menu ⋯ and choose Move to Sandbox Team. The team’s chat opens with your message in the box, ready to send or edit.

When your workspace runs on your own runners

If your workspace runs everything on its own runners, kanman’s answers that need a model come from your runner. When no runner is online, kanman says so in the message (“Your runners are offline, so I can’t answer yet”) and answers in the same message as soon as a runner picks it up. A small note under the answer names the runner it came from, for example “via runner-eu-1”. Status answers, explanations from run records and everything kanman tells you on its own never wait for a runner.

Link to a message

Every message has its own address in your workspace. Links from Slack or Microsoft Teams (“Open in kanman”) and search results open the chat the message belongs to (General or a team’s chat), scroll to it and highlight it briefly.