Move workflow file and TODO.md formats into the knowledge base

internal/agents/guidance.go

@@ -21,7 +21,7 @@ const guidance = `You are running inside byre. The human reads your work in byre
 - In that final message and in ask_human context, put long supporting detail (logs, full lists, data) in collapsed sections the human expands on demand: a line <details><summary>Title</summary>, the Markdown content, then a line </details>.
 - Don't commit. byre commits everything in the worktree at the end of each turn, using the turn's final message.
 - Don't push, don't switch or touch other branches, and don't run git maintenance (gc, prune, worktree prune). byre handles merging and pushing.
-- TODO.md at the repo root is the project's list of work for byre. Each item is a top-level ` + "`- `" + ` line holding only a short title, which byre uses as the task's title and the item's identity, with its description in lines indented two spaces under it. ` + "`#`" + ` headings group items into sections, and a checked ` + "`- [x]`" + ` item is skipped.`
+- TODO.md at the repo root is the project's list of work for byre; its format is the read_knowledge article todo-file.`
 
 const proseQuestionNudge = "Your final message asks the human something in prose. Ask it with byre's ask_human tool " +
 	"(context with the choices inline as `- ( ) choice` / `- (*) recommended` or `- [ ] choice` / `- [x] recommended` list items, question, why_blocked), " +

internal/agents/kb/todo-file.md

@@ -0,0 +1,20 @@
+The format of TODO.md, the project's list of work for byre: items, descriptions, sections and checked items.
+
+# TODO.md
+
+TODO.md at the repo root is the project's list of work for byre.
+
+- Each item is a top-level `- ` line holding only a short title. byre uses the title as the task's title and as the item's identity.
+- The item's description is in lines indented two spaces under it.
+- `#` headings group items into sections.
+- A checked `- [x]` item is skipped.
+
+```markdown
+# Agent UI
+- Fix login redirect
+  The redirect drops the query string after sign-in.
+  Keep the original path and query through the round trip.
+- [x] Drop the web app
+```
+
+Removing an item removes its title line and every indented line under it.

internal/agents/kb/workflow-files.md

@@ -0,0 +1,42 @@
+The YAML format of a workflow's file, which read_workflow returns and save_workflow takes: stages, after, base, model and teams.
+
+# Workflow files
+
+A workflow's file is YAML: an optional `description`, then `stages`. The workflow's name is not in the file. Unknown fields are refused.
+
+| Field | Meaning |
+|---|---|
+| `name` | One line, unique in the workflow. |
+| `after` | The names of the stages whose outputs it gets; it starts once all of them have finished. Absent means the previous stage in the list, and for the first stage none, so a file without `after` is a chain. `[]` means it starts from the brief. |
+| `base` | `parent`, the default: branch from the commit its one `after` stage finished at, or for a stage with none, from where the workflow was started. `main`: branch from the default branch. Refused on a stage with more than one `after` stage, which always branches from the default branch and is told the branches it can merge. |
+| `model` | Also picks the vendor: `gpt-*` models run on Codex, `gemini-*` models on Antigravity, every other model on Claude Code. |
+| `prompt` | The stage agent's instructions. |
+| `agents` | In place of `model`: a list of at least two, each with `name`, `model` and `prompt`, that runs the stage as a team. They work in the stage's one task and worktree and talk through a shared board; each gets the stage's `prompt` and then its own, and the first agent finishes the stage. |
+
+Every stage runs as its own task. Exactly one stage is final (no other stage comes after it), and cycles are refused.
+
+```yaml
+description: Build a change, review and test it in parallel, then fix what they found.
+stages:
+  - name: Build
+    model: claude-opus-5-5
+    prompt: Implement the brief.
+  - name: Review
+    after: [Build]
+    model: gpt-6.1-sol
+    prompt: Review the Build stage's work and list the problems.
+  - name: Test
+    after: [Build]
+    model: gemini-4-argon-high
+    prompt: Exercise the change and report what fails.
+  - name: Fix
+    after: [Review, Test]
+    agents:
+      - name: fixer
+        model: claude-opus-5-5
+        prompt: Fix every problem the reports list.
+      - name: checker
+        model: gpt-6.1-sol
+        prompt: Check each fix as the fixer lands it.
+    prompt: Merge the branches you are given and address both reports.
+```

internal/agents/workflows.go

@@ -648,15 +648,7 @@ func stageGuidance(frozen store.FrozenWorkflow, stage string) string {
 		"%s. Until you call it, the workflow waits on this stage.", stage, frozen.Name, then)
 }
 
-const workflowFileHelp = "A workflow's file is YAML: an optional description, then stages, each with name (one line, unique in the workflow), " +
-	"after (the names of the stages whose outputs it gets; it starts once all of them have finished; absent means the previous stage in the list, and for the first stage none; [] means it starts from the brief), " +
-	"base (parent, the default: branch from the commit its one after stage finished at, or for a stage with none, from where the workflow was started; main: branch from the default branch; " +
-	"refused on a stage with more than one after stage, which always branches from the default branch and is told the branches it can merge), " +
-	"model (which also picks the vendor: gpt-* models run on Codex, gemini-* models on Antigravity, every other model on Claude Code) and prompt (the stage agent's instructions). " +
-	"In place of model, agents (a list of at least two, each with name, model and prompt) runs the stage as a team: those agents work in the stage's one task and worktree and talk through a shared board; " +
-	"each gets the stage's prompt and then its own; the first agent finishes the stage. " +
-	"Every stage runs as its own task. Exactly one stage is final (no other stage comes after it), and cycles are refused. " +
-	"The workflow's name is not in the file."
+const workflowFileHelp = "The file's YAML format is the read_knowledge article workflow-files."
 
 func (m *Manager) workflowTools(tool func(name, description, schema string, run func(ctx context.Context, user api.User, raw json.RawMessage) (string, error)) mcp.Tool) []mcp.Tool {
 	return []mcp.Tool{