How Work Flows

How work flows

A piece of work in Nautelle starts as one sentence and ends as a merged pull request. This page follows it end to end: the intake interview, the candidates you accept, the optional design, the card worker, the pull request that ships itself, CI, and the merge. Each step links to a page with the details. The fleet path, where the Code Sentinel orchestrator works on ready GitHub issues, is a separate path, described at the end of this page.

The lifecycle at a glance

flowchart TD
  A["New work<br/>(Board, Telegram /new, assistant)"] --> B["Intake interview<br/>up to 4 question rounds"]
  B --> C{"Proposal"}
  C -->|one card| D["Candidates in Drafts"]
  C -->|split: 2–8 cards| D
  C -->|stack: staged cards| D
  D -->|Accept| E["To Do"]
  D -->|Reject| X["Nothing is made"]
  E --> F{"Design needed?"}
  F -->|yes| G["Generate → comment → Revise → Approve"]
  G --> H
  F -->|no| H["Run: card worker<br/>own worktree + Claude session"]
  H --> I["Draft PR opened by the runner"]
  I --> J["finish_card → PR ready for review"]
  J --> K{"CI on the head"}
  K -->|red or conflict| L["Automatic fix round<br/>at most 3 per PR"]
  L --> J
  K -->|green| M["Finished"]
  M -->|auto-merge on| N["Merged, stays in Finished"]
  M -->|auto-merge off| O["Accept: Merge pull request<br/>or Accept without merging"]
  N --> P["A person moves it to Completed<br/>worktree cleaned up"]
  O --> P

Loading

Step by step

1. Intake

Click Board › New work and describe what you want in any language. A read-only planner session on the project's runner reads the repository and asks questions in rounds, at most four, until the task is clear. You can stop it at any time with Enough — generate. The intake then proposes one of three results:

• One card: a clear, single task.
• A split: 2 to 8 independent cards, when the request is several tasks or too big for one agent.
• A stack: cards in ordered stages that share one design, when the work must happen in order or several UI changes share one look.

You can also start an intake from Telegram with /new, including photos and voice messages, or ask the assistant to draft a card. → New Work Intake

2. Candidates

What the intake writes are candidates, not cards. They wait in the Board's Drafts strip. You edit each one, then Accept or Reject it, or use Accept all to take a split as independent cards or a stack as proposed. Accepted cards land in To Do. Attachments from the intake go to the first accepted card.

3. Design (optional)

A card or a stack can need a design. Nautelle draws self-contained HTML mockups from the project's UI profile. You pin comments, ask for a revision, and Approve. The approved frames are committed into the card's branch, and the worker reads them from there. In a stack with a design, Run on any of its cards is held until the stack design is approved. → Design and Stacks

4. Run

Run opens a launch popover where you pick the Claude profile and the model. A small assessment recommends Opus, Sonnet or Haiku for the card. The runner gives the card:

• its own git worktree and branch;
• its own tmux session;
• its own interactive Claude Code session.

The worker prompt is Nautelle's fixed, versioned prompt. It carries the card, its spec, the project's coding rules and, for a stack card, the stack's approved design. Cards that depend on others can start by themselves with Auto-run when ready. → Card Workers and Shipping

5. Pull request

The worker commits but never pushes. While the round works, the runner pushes the committed head and opens a draft PR. When the worker calls finish_card, the PR leaves draft with a description the worker wrote: the spec link, what changed and the acceptance checklist.

6. CI

Nautelle reads the PR's checks through the runner:

• Red checks, or a merge conflict with the base, start an automatic fix round in the same session. There are at most three per PR; after that the card waits for a person.
• No checks at all, in a project whose PRs have had checks before, are treated as a lost event. The runner reopens the PR once to retrigger CI. If checks still do not report, the card waits for a person.

The card moves to Finished only when the worker is done and CI on the head is green, or the repository has no checks.

7. Accept and merge

• Auto-merge on: the card's PR is merged on the green head and its branch deleted. The card stays in Finished with a Merged badge. This is the default when the base is not the repository's default branch.
• Auto-merge off: the card waits for Accept, which offers Merge pull request (bound to the head you saw) or Accept without merging.

Feedback on a merged card starts a new round on a fresh branch with a new PR.

8. Completed

Only a person moves a card to Completed. That stops the worker's tmux session and removes the worktree and its local branches. Automation never completes a card.

Note

While all this runs, Token Saver trims what the agent reads, Steward watches the round for stuck states, and Context Handoff keeps a note so the next round starts in context.

Other ways work reaches the Board

Source	What appears	Where
A terminal Claude Code session calls track_card	a card In progress, marked Terminal	Board and Cards
Capture reads your own sessions (opt-in)	suggestions in Inbox	Board and Cards
The fleet dispatches a slot	a card marked Fleet that follows the slot	Board and Cards
Discuss	an answer, never a card; each proposal can open New work	New Work Intake

The fleet path

The fleet is the second way work gets done. It does not use cards as its queue:

flowchart LR
  I["GitHub issue<br/>with the ready label"] --> Q["Queue"]
  Q --> O["Code Sentinel orchestrator"]
  O --> S["Slot: worktree + tmux worker"]
  S --> PR["Pull request"]
  PR --> AP{"Merge approval on?"}
  AP -->|yes| A["Approvals: Approve / Request changes"]
  AP -->|no| M["Orchestrator merges"]
  A --> M

Loading

GitHub issues are the fleet's task queue. The orchestrator owns its slots, and Nautelle observes them, mirrors them on the Board, and lets you start, stop and message them. → Fleet and Orchestrator

Important

Orchestrator slots run Claude Code. Codex workers and Codex as the orchestrator are not built yet.

See also

• Board and Cards · New Work Intake · Design and Stacks · Card Workers and Shipping · Project Settings · Fleet and Orchestrator

Decisions: ADR-0024 · ADR-0035 · ADR-0037 · ADR-0043 · ADR-0058 · Spec: #359, #409