discuss prompt

docs/operations.md

@@ -219,7 +219,7 @@ For Claude, byre chooses the session ID (`vendor_session_id`) up front. Codex pi
 
 Every session gets byre's guidance (`guidance` in `internal/agents/guidance.go`): ask questions with `ask_human`, end each turn with a final message that summarizes it (including every departure from the plan), put everything the human needs in a question's context since that turn has no summary, don't commit (byre commits each turn), don't push, touch other branches or run git maintenance, and write `TODO.md` items the way byre parses them (see "TODO"): a top-level `- ` line holding only the title, with the description indented under it. A task agent's guidance also names its port range, tells it to do the setup AGENTS.md describes in a new worktree (see "Worktree setup and ports"), and quotes the task's title, which may be all the human typed when creating the task. A task started from a `TODO.md` item gets one more line naming the item and telling the agent to remove it from `TODO.md` in its worktree when the work is done (`taskGuidance`; see "TODO"). A subtask gets one naming its parent and saying that its final messages go to the parent's agent (`subtaskGuidance`; see "Subtasks"). For Claude it is passed as `--append-system-prompt`, which Claude Code records on a session's first request and reuses on resume, so a running session keeps the text it started with; a `UserPromptSubmit` hook also attaches it as `additionalContext` to every user turn, which reaches existing sessions too. For Codex it is the thread's `developerInstructions`, and every `turn/start` also carries it as `additionalContext` under the key `byre`. For Antigravity it is an always-on rule in the session's plugin (`rules/AGENTS.md`, with the notes in `rules/notes.md`), written when byre starts the session's process, and every message also starts with it in `<system-reminder>` tags. The guidance names byre's tools vendor-neutrally ("byre's ask_human tool"): Claude sees them as `mcp__byre__<name>`, Codex as `<name>` in the namespace `byre` (Codex reserves the `mcp__` prefix), Antigravity as `<name>` on the MCP server `byre_byre`, called through its `call_mcp_tool` (recorded as `mcp__byre__<name>`).
 
-A turn whose final message asks the human something in prose is bounced once (`takeBounce` in `internal/agents/guidance.go`): if `ask_human` wasn't called during the turn and the final message's last paragraph has a sentence ending in `?` outside code spans, code blocks, quotes, blockquotes, table rows and `<details>` sections, the agent is told to ask through `ask_human` and carries on. Questions earlier in the message (quoted, answered, or listed for someone else) don't count. A task started as a TODO discussion (its first `user.message` holds `discussPrompt` from `internal/agents/tasks.go`) is never bounced, since that prompt tells the agent not to use `ask_human`, and neither is a task with an open question already in the inbox, since the prose then points at that question. A bounce is recorded as a `byre` `user.message` with `mid_turn: true` and `bounce: true` carrying the nudge; the transcript draws neither it nor the agent message before it, so the rewritten message takes the blocked one's place. For Claude the bounce is a Stop hook (`bounceProseQuestion`) that blocks the stop; Claude Code reports the block as a "Stop hook error" notification, which is expected. For Codex, byre doesn't end its turn on `turn/completed`: it records the nudge and starts another Codex turn with it, and only that turn's end ends byre's turn. Antigravity works the same way on its `result`, since its `Stop` hook isn't given the final message. The per-turn flags reset when the next user message is sent. An agent told explicitly to ask in plain text will refuse the bounce.
+A turn whose final message asks the human something in prose is bounced once (`takeBounce` in `internal/agents/guidance.go`): if `ask_human` wasn't called during the turn and the final message's last paragraph has a sentence ending in `?` outside code spans, code blocks, quotes, blockquotes, table rows and `<details>` sections, the agent is told to ask through `ask_human` and carries on. Questions earlier in the message (quoted, answered, or listed for someone else) don't count. A task started as a TODO discussion (its first `user.message` holds `discussPrompt` from `internal/agents/tasks.go`) is never bounced, since that prompt lets the agent talk it over in chat as well as through `ask_human`, and neither is a task with an open question already in the inbox, since the prose then points at that question. A bounce is recorded as a `byre` `user.message` with `mid_turn: true` and `bounce: true` carrying the nudge; the transcript draws neither it nor the agent message before it, so the rewritten message takes the blocked one's place. For Claude the bounce is a Stop hook (`bounceProseQuestion`) that blocks the stop; Claude Code reports the block as a "Stop hook error" notification, which is expected. For Codex, byre doesn't end its turn on `turn/completed`: it records the nudge and starts another Codex turn with it, and only that turn's end ends byre's turn. Antigravity works the same way on its `result`, since its `Stop` hook isn't given the final message. The per-turn flags reset when the next user message is sent. An agent told explicitly to ask in plain text will refuse the bounce.
 
 A turn's final message is its summary, and it lives only in the transcript, so the human reads it once. When a task turn ends normally (not an error, not interrupted, not a handoff) with non-empty `result` text, didn't call `ask_human`, and isn't a Merge turn or discard turn (the task closes right after one, so its final message is never left to read), its `turn.ended` event carries `summary: true`. A Merge turn that called `stop_merge` keeps the task open and does carry it. That flag drives the lead's "finished a turn" signal and the "Turn summaries" notification (see "Lead agent" and "Notifications"). A turn that asked a question has no summary, since the final message comes after the question it explains; the guidance tells agents to put everything the human needs in the question's context. There is no report tool: models write a closing recap whatever they are told, so byre uses it rather than asking for a second one.
 
@@ -285,7 +285,7 @@ The UI is two panes filling the window, with no navbar. The left has five tabs:
 
 A project's `TODO.md` is read from the root of its default branch in the project's checkout (`git cat-file blob <default branch>:TODO.md`), so it shows what has been merged, not uncommitted edits in the checkout. `GET /api/projects/{id}/todo` returns `exists` and the parsed `items` (`internal/todo`): every top-level list item (`-`, `*`, `+`, `1.` or `1)` at the start of a line) is an item. Its first line, with any `[ ]` checkbox removed, is its `title`; the lines indented under it (and lines continuing it without a blank line between) are its `body`, with the common indentation removed; `section` is the nearest heading above it. Checked items (`[x]`) are skipped, list markers inside fenced code don't count, and paragraphs between items are ignored.
 
-The title is the item's identity. `POST /api/projects/{id}/todo/tasks` with a `title` re-reads `TODO.md`, refuses an unknown title (404) or one an active task already has (409), creates a task from the default branch with that title and `todo_item` (the `tasks.todo_item` column, empty for other tasks), and starts its session as the requesting user with `todoPrompt` (`internal/agents/tasks.go`): the item as written, and an instruction to remove it from `TODO.md` in the worktree when the work is done. With `discuss: true` the prompt adds that the human wants to discuss the item first: the agent reads what it needs, ends its turn with its thoughts on the item (its reading, approach, trade-offs and doubts) in its final message rather than `ask_human` questions, carries on the conversation in chat, and changes nothing until told to build it. The agent's guidance names the item too (`taskGuidance`, see "Agent sessions"), so the instruction survives compaction and resumes. The agent removes the item on its own branch, so the removal lands on the default branch in the same squash commit as the work.
+The title is the item's identity. `POST /api/projects/{id}/todo/tasks` with a `title` re-reads `TODO.md`, refuses an unknown title (404) or one an active task already has (409), creates a task from the default branch with that title and `todo_item` (the `tasks.todo_item` column, empty for other tasks), and starts its session as the requesting user with `todoPrompt` (`internal/agents/tasks.go`): the item as written, and an instruction to remove it from `TODO.md` in the worktree when the work is done. With `discuss: true` the prompt adds that the human wants to discuss the item first: the agent zooms out first, reads what it needs and gives its view on whether the item should be built at all and in what shape (the problem it solves, alternatives including a smaller change or nothing, its approach, trade-offs and doubts), talks it over in its final messages and in as many `ask_human` questions as help, each about those broad choices rather than build details and free to build on earlier answers, and changes nothing until told to build it. The agent's guidance names the item too (`taskGuidance`, see "Agent sessions"), so the instruction survives compaction and resumes. The agent removes the item on its own branch, so the removal lands on the default branch in the same squash commit as the work.
 
 The **Project** tab is the dashboard of the right pane's project (the focused task's, or the project focused with no task). Under **Tasks** it lists the project's active tasks in the server's order (newest first), each with its task state (see "Task state") and open inbox item count, as links that point the right pane at the task's transcript; the focused task is highlighted. Under **TODO** it lists the `TODO.md` items, grouped by section, with each body rendered as Markdown. An item with an active task whose `todo_item` equals its title shows that task's state as a link to the task instead of the **Start** and **Discuss** buttons. **Start** posts the item with the composer's default model; **Discuss** posts it the same way with `discuss: true`. Neither moves the right pane (see "Start hold"). The task list follows byre's live state; the tab fetches the project's `TODO.md` when it opens, when the right pane moves to another project, when the project list changes, when the SSE stream reconnects, and on `task.merged`; a change pushed to the default branch outside byre shows the next time one of those happens.
 

internal/agents/tasks.go

@@ -91,7 +91,7 @@ func todoPrompt(item api.TodoItem, discuss bool) string {
 	return p + "\n\n" + discussPrompt
 }
 
-const discussPrompt = "The human wants to discuss this item with you before any of it is built: a conversation, not a questionnaire. Read what you need to understand it, then end your turn with your thoughts on it in your final message: how you read it, how you would approach it, and what trade-offs or doubts you see. Don't use ask_human for this; the human replies in the chat. Keep the conversation going turn by turn, and change nothing until they tell you to build it."
+const discussPrompt = "The human wants to discuss this item with you before any of it is built, to judge whether it should be built at all and in what shape. Zoom out before going into detail. Read what you need to understand it, then give your view: what problem it solves and whether that is worth solving, whether we should do it, what the alternatives are (another approach, a smaller change, or nothing), and how you would approach it, with the trade-offs and doubts you see. Talk it over in your final messages, where the human replies in the chat, and use ask_human as often as it helps. Each question belongs to that zoomed-out discussion, such as whether to do it, which alternative, or what shape, rather than the narrow details of getting it built, and later questions can build on earlier answers. Keep the conversation going turn by turn, and change nothing until they tell you to build it."
 
 func (m *Manager) createTask(ctx context.Context, project api.Project, t api.Task, frozen *store.FrozenWorkflow, base, actor string) (api.Task, error) {
 	t.Id = store.NewID()