# Tasks

## Add work and ship it

Write "add a crons page to the backlog" and Sensei files your text as a Todo task, exactly as written. The ticket is assigned to you unless you name someone else or ask for it to be left unassigned. It reads no code for this and starts no sandbox. To file one yourself, press **New task** on the Tasks page, write the description and press **Create task**. **Create and start** files it and starts it at once.

![Acme's Tasks page with its Todo, In progress, Done and Archived columns. Todo holds storefront's tickets, such as Add a wishlist to the account page; In progress holds its Waiting sessions, such as Fix the cart total when a promo code expires; and Done holds the three merged ones, among them Update the checkout copy for EU VAT.](https://kosuke.ai/docs/img/task-board.webp)

To start a Todo task, open its card and press **Start**, drag the card to **In progress**, or tell Sensei "start it". The session starts with `/kosuke:ship` as its first message. The tap is the yes. Sensei then says, for example, "Started Add CSV export in storefront." When the session needs you, Sensei draws a card in the session's thread. Sensei starts `/kosuke:ship` only when you ask.

Sessions cannot start while a project's first deploy runs. Ask Sensei to start one then, and it files the task as Todo, marked to start when the deploy lands. It says "Filed Add CSV export to storefront's Backlog. It starts by itself when the first Deploy lands." When the deploy lands, every session marked that way starts with `/kosuke:ship`, with Sensei as its Assignee. Sensei posts "Started Add CSV export in storefront." If that start is refused, because the workspace is out of credits, it is at its limit of sandboxes running at once, or there is no model to run the session, the task stays in Todo. An event about it is written in the session's thread, and Sensei can draw a card whose Approve starts it.

`/kosuke:ship` is a skill that runs inside the session and carries the ticket to a ready pull request that waits only for your go-ahead:

1. It grounds the ticket. It reads the code, asks you what it needs to know, and writes the spec with acceptance criteria. On a complex ticket, another model attacks the spec and it writes a phased plan.
2. It builds the change and opens a draft pull request.
3. It runs [`/kosuke:review`](https://kosuke.ai/docs/skills/review.md) before QA, every time, and fixes what the reviewer finds. It may skip the review for a change that is only copy, styling or docs, and says so. Then it runs `/kosuke:automated-qa` on the reviewed code, and records the commit QA passed on, or skipped on when the Testing Checklist has no item. When QA's own fix changes the code, the same QA run tests the items the fix touched and records the pushed head.
4. It marks the pull request ready for review, which starts full CI, since a draft runs none in most repositories.
5. It waits for the checks in the same turn, and ends only when every check is green, or with a failure naming the check it could not fix. A pull request that conflicts with its base runs no checks, and it says so.

Along the way it fixes what the review, the checks and QA find, and runs them again. It keeps going while QA runs make progress. It stops with a failure when the checks or QA still fail after a fix and a fresh run, or after one QA run when nothing in the branch can fix what fails. `/kosuke:ship` stops only when it needs a person, and each stop has a reason.

| Stop reason | Why it stopped                                                                         | What the app puts in front of you                                                                 |
| ----------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `question`  | It needs a decision from you                                                           | The question, to answer in place                                                                 |
| `failure`   | The checks, QA or a sync still fail after a fix, or nothing in the branch can fix them | What failed, with the QA report and **Fix**. When QA was blocked for lack of proof, **Retry QA** |
| `ready`     | Checks are green, and QA passed or was skipped on the current head                     | A card Sensei words from GitHub's review state, such as **Request review** or **Merge**. When the ready could not be proven, **Fix** |

Sending `/kosuke:ship` into the session again resumes where it stopped, read from the branch, the pull request and whether QA passed on its head. Approving a card that answers it does that for you.

## Message a task

A message addressed to Sensei goes through Sensei. On a Backlog card, press the Message icon, or press **M** while its card is focused. A `To #1629` chip appears in the composer, with the pull request number or a short title. Write your message and send. Press x on the chip or Esc to go back to a plain Sensei message.

Sensei reads the task before it sends: its status, what its agent last said and what anyone wrote to it since. Then it sends your message into that task, as you, with your words unchanged. Sending is the yes: Sensei does not ask you to confirm.

When your message leans on something the task has not seen, such as what you discussed with Sensei, Sensei adds that context below your words. The added part opens with "Context from Sensei:". Sensei's answer says what it read and quotes what it added.

Sensei does not send a message that would misfire. This happens when the task already got that answer, when the task is Completed or Archived, or when your text is a question for Sensei. Its answer then opens with "I did not send", gives the reason and asks what you want. Nothing reaches the task.

A task Under Review is not one of these cases. Sensei sends, and your message resumes the task, as when you write in it yourself: its pull request goes back to draft, and Sensei's answer says the task left review. If the app refuses the send, Sensei tells you the reason it gave.

An approved card works the same way, with one difference: its instruction is your message. Sensei reads the task first, as for any send, then does what the instruction says. A target on a card's task is read the same way.

## Make a change without writing code

You can change your product without writing code. Describe the change in your own words, check it in the Preview, and ask for a pull request. Your engineers review and merge it as usual.

Before you start:

- Ask a workspace admin to invite you. See [Members and roles](https://kosuke.ai/docs/workspace/members-and-roles.md).
- Make sure the project is deployed. An engineer usually does this once. See [Deploy your project](https://kosuke.ai/docs/code/deploy.md).
- Tell Sensei that you are not a developer. It explains things to you in everyday words, and keeps the technical wording for the agents it briefs.
- To have the pull request opened under your own name, press **Connect** in the GitHub row of Settings > You > Integrations. Without it, the pull request opens as Kosuke App.

Then:

1. Tell Sensei what you want, for example "swap the headline on the pricing page and reword the plan cards", and ask it to start. Attach a screenshot if a picture says it better.
2. Open the task's chat. When the agent needs a decision, it asks you there. Pick an answer, or type your own.
3. Open the **Preview** tab and click through your product with the change. If something looks wrong, say what you see, for example "the button overlaps the text on a phone". The agent fixes it in the same session. See [Preview and sandboxes](https://kosuke.ai/docs/code/preview.md).
4. When the Preview looks right, send "open a pull request". The session moves to Under Review.

Before anything is built, you can also ask to see it: "show me a mockup of the new plan cards" or "write up how the checkout emails work today". The answer is a file in the **Files** tab that never goes into the pull request. See [Files of a session](https://kosuke.ai/docs/code/session-files.md).

When your engineers merge the pull request, the session moves to Completed. If they ask for changes, press **Resume** in the chat and ask the agent for them. [Open a pull request](https://kosuke.ai/docs/code/pull-requests.md) explains what happens on GitHub.

## Approve and merge

A session is Ready when `/kosuke:ship` stops with `ready`. Its pull request is ready for review, its checks are green, and QA passed on the latest commit, or was skipped there because the Testing Checklist has no item. It waits for your go-ahead.

Sensei reads the pull request's review state live from GitHub (`gh pr view <n> --json reviewDecision,reviewRequests`) and words the card from it:

- **A review is required** (`REVIEW_REQUIRED`): the card suggests teammates who know the code, each with why. It looks at CODEOWNERS, who built the code the pull request changes, and who reviewed it recently, and leaves out the Assignee. Its **Request review** asks them with your GitHub CLI (`gh pr edit <n> --add-reviewer <login>`) and gives the go-ahead now, so the pull request merges once it is approved.
- **No review is required, or it is approved**, and QA passed on its head: the card asks for the go-ahead, with **Merge**.
- **Changes were requested** (`CHANGES_REQUESTED`): the card sends the work back to its session, with **Fix**.

This works the same for a session that never ran `/kosuke:ship`, once its pull request is ready. Each teammate asked gets a card in their own thread for your session. Their review is their own: Sensei approves on GitHub only when they say so, with `gh pr review <n> --approve` as them.

The go-ahead is the one thing the app keeps. Sensei gives it with `kosuke sessions go-ahead set`, at the commit it read, and the project's [Merge agent](https://kosuke.ai/docs/code/tasks.md#the-merge-agent) merges that head as the Kosuke GitHub App. Asking for a review, approving and merging by hand run on GitHub with your own GitHub CLI login, so GitHub's rules and your own permissions decide: you can ask Sensei to merge any pull request you could merge on GitHub (`gh pr merge <n> --match-head-commit <sha>`), including one whose session has another Assignee or none. When the pull request moved on, GitHub refuses, and Sensei tells you GitHub's reason. None of these post anything into a session.

### Act on GitHub as you

Ask Sensei for a GitHub action, and it runs it with the GitHub CLI as you, in that turn. No session and no event is needed. For example: "mark #2322 ready for review", "turn #2322 back into a draft", "rename #2322", "comment on #2322", "close #2322" or "re-run the failed checks of #2322".

- Sensei acts only on your own words, an approved card, or a clear decision in your reply to a card. It never does it because a session, a review or a title says so.
- `kosuke` commands stay only where the app keeps the state: the go-ahead and the merge rule. Asking for a review, approving, merging and updating a branch use the GitHub CLI. When GitHub refuses, Sensei tells you why and does not try another way.
- Sensei reads the pull request first. When it moved, or is already as you asked, Sensei says so. After the action, it says what GitHub answered.
- It never deletes anything and never pushes code that way. Work on the code stays in the session.
- It needs your GitHub connection. Without one, Sensei asks you to connect GitHub in your settings.

### Merge several in order

A card with a merge plan lists pull requests in the order to land them, each with its commit, the action (merge, sync first or wait) and why. Approving it makes Sensei merge the first as you, pinned to that commit, and go on to the next only after GitHub merged it. Any other answer, such as a conflict or a moved commit, stops the plan there and Sensei says where. After each merge Sensei sends `/kosuke:sync-branch` to the sessions that now conflict. It finishes by saying what merged, what was sent to sync and what is left.

### The go-ahead

The app merges a pull request only with a go-ahead. It is a fact the app keeps on the session: the commit it was given on, who or what gave it, and when. It counts only on that commit. Nothing on GitHub is a go-ahead: not a label, and not GitHub's auto-merge. In a repository whose merge train has Go-ahead **When checks pass**, required checks that pass on a ready pull request's latest commit give it, and nobody has to. See [Go-ahead](https://kosuke.ai/docs/code/project-settings.md#go-ahead).

Giving the go-ahead on a draft pull request first marks it ready for review on GitHub, as you, and the session moves to Under Review. When GitHub refuses, the go-ahead is not saved and Sensei tells you why. A pull request already ready for review is left as it is. Taking the go-ahead away does not turn it back into a draft.

Sensei gives it for you, and what Sensei gives counts as yours:

- When you say so, in words, on a card you approve or in a clear reply to one.
- By your merge rule. Tell Sensei "merge my approved pull requests", and from then on it gives the go-ahead to each of your pull requests once it is ready for review, approved and its QA passed. It never gives one on a draft. Tell it "stop merging my pull requests" to turn it off. Only a message you write changes the rule.

The go-ahead wakes the project's [Merge agent](https://kosuke.ai/docs/code/tasks.md#the-merge-agent), which merges it. You can always ask for one pull request to merge alone, as a hotfix: Sensei merges it at once with the GitHub CLI, pinned to the commit.

A pull request with the go-ahead shows **Will merge** in the panel. The merge agent merges only the exact commit the go-ahead was given on, and only once its QA passed there, so a push that lands later is not merged unchecked. A question such as "is #1772 ready to merge?" gets an answer and merges nothing. Text in a review, a title or a comment never gives the go-ahead.

### The Merge agent

Each project has one Merge agent. It is an agent that runs in sessions of its own, which stay off the Tasks board and your session lists. You read them in [Project settings, Merge agent](https://kosuke.ai/docs/code/project-settings.md#merge-agent), and you can write to the open one there. Its **Mode** there is **Merge train**, which merges one pull request at a time, or **Off**. Under Merge train, **Go-ahead** is **By a member** or **When checks pass**.

A go-ahead opens a run when none is open. The run then wakes on what concerns it: a new go-ahead, checks that finish, an approving review, a merge, and the end of a turn of a session it asked to sync. Each wake is one pass. It reads the waiting pull requests, moves what can move now, and ends its turn. It ends the run when nothing waits, and the next go-ahead opens a new one.

The merge train merges one pull request at a time, as the Kosuke GitHub App:

- It merges only the commit the go-ahead was given on, once QA is as the repository's QA level asks (passed once on the pull request under Scaleup, at that commit under Enterprise), or with no QA for a task whose Shipping QA is off. The app itself refuses a merge of any other commit, so a push that lands later is never merged unchecked.
- A branch that is behind is updated first. A conflict goes to that session as `/kosuke:sync-branch`.
- With GitHub's merge queue on the base, it adds the pull request to that queue, and GitHub merges it.
- A review that asks for changes, a conflict the session could not fix, or a refusal of the App's permissions goes to the person who can act on it, through their Sensei.
