Put the file in the project
Kisuke looks for these files in order under the selected project folder and uses the first file it finds:.kisuke/WORKFLOW.md.kisuke/workflow.mdWORKFLOW.md
package.json before dispatching its goal:
package.json in the task worktree. It does not install dependencies, run tests, or cap the number of goal turns.
Write task instructions
The Markdown body is added to the task’s repository context and proposed first prompt. Use it for conventions such as required checks, acceptance criteria, or whether committing and publishing are part of the workflow. For a manual start, read the complete proposed prompt before sending. Already prepared conversations and retained first prompts can contain an earlier version; editing the file does not replace an accepted goal. The supported substitutions are plain values:
Liquid filters, loops, and conditionals are not supported.
{{ attempt }} is recognized by the renderer, but current task prompt callers do not supply an attempt value, so it renders empty. Do not use it to control retries.
An unknown simple variable, such as {{ issue.repository }}, causes that optional workflow instruction block to be omitted from task prompt construction and a warning to be logged. It does not reliably prevent the task from starting. Inspect the proposed prompt to confirm your instructions appear.
Settings that affect execution
Use positive whole numbers for numeric settings.agent.max_concurrent_agentssets the Auto-run board’s effective capacity. The file default is 3. It is not a limit on manual starts, all boards combined, or ordinary conversations.agent.max_retry_backoff_mscaps the delay between task failure retries. The default is 300000 milliseconds, or five minutes. It does not cap the number of attempts, tokens, or total runtime.agent.assigneechanges the assignee sent with the Auto-run Linear refresh, for exampleme. It does not exclude other tasks already cached on the board from dispatch. When absent, the board’s assignee choice carries forward.hooks.timeout_mssets the time before Kisuke requests termination of a hook. The default is 60000 milliseconds. This is not a guaranteed deadline for every descendant process to stop.
A workflow file supplies defaults for omitted fields. Even a prose-only file replaces the board’s concurrency with 3 and clears its per-state caps. Include
agent.max_concurrent_agents explicitly when the board must keep a lower setting; the Auto-run menu can still display the stored board value rather than this effective override.agent.max_concurrent_agents_by_state accepts a mapping from workflow column names to counts. Names are compared in lowercase. The current runner checks the issue’s column before starting and then moves work toward In Progress. This is not a strict cap on the number of tasks in the destination column; use the global concurrency setting for the board-wide limit.
Fields that do not enforce their apparent limit
These fields can be parsed without providing the control their names suggest:polling.interval_ms: does not set the actual next-check schedule. Use Poll interval in the Auto-run menu.tracker.active_statesandtracker.terminal_states: do not replace dispatch and terminal-state classification. The runner uses the imported Linear workflow types.tracker.project_slug: does not choose the Linear team. The board’s linked team and organization do.agent.max_turns: does not cap task goal turns.agent.stall_timeout_ms: does not configure the task runner’s stall handling.
Choose the policy source when routing projects
Auto-run reads its board-level workflow policy from the default project. If no default is set, it uses the first routing-rule entry with a project path; that selection can include a disabled rule. It does not choose an independent scheduling policy for every matching issue. Each prepared task also reads its own selected project’s workflow for repository context and hooks. With multiple routed repositories, the Auto-run prompt can therefore include instructions from the board’s policy project alongside the task repository’s context. Keep the policy source explicit and its instructions suitable for every project the board can dispatch. Use individual starts when you need to inspect each repository’s exact proposed prompt.Add lifecycle hooks
Hooks run with the task worktree as their working directory, using the executing computer’s shell and environment. Keep commands appropriate to that computer. The names describe lifecycle points, not an exactly-once guarantee across retries or restarts.
These hooks do not necessarily run for every response in a continuing goal. For example, an active goal can continue or resume without a fresh task-first-prompt dispatch. Put checks that must happen before every particular action in that action’s own workflow too.
Kisuke supplies
KISUKE_HOOK, KISUKE_TASK_ID, and KISUKE_TASK_TITLE to task hooks. Linked issues also receive KISUKE_LINEAR_ID and KISUKE_LINEAR_ISSUE_ID. Hooks inherit the daemon’s other environment variables; the project-script environment variables are not automatically a separate task-hook contract.
Use before_run for a prerequisite whose failure must block that dispatch. Do not rely on after_create failure to stop the agent, or on before_remove failure to preserve files. Save work before clearing a task or completing its issue.
Ordinary project Setup/Archive scripts and task workflow hooks can both apply to a worktree. They have different timing and failure behavior. A task’s waiting for after_create does not establish that its ordinary Setup script finished.
Apply changes and recover
File watching invalidates the workflow cache for a watched project; otherwise cached definitions can remain for up to a minute. Changes apply when the relevant configuration or prompt is read again. They are not an acknowledgement from a running agent that its goal changed. For changes to automatic execution policy, stop Auto-run, inspect tasks already dispatched, edit the file, and verify the settings and intended scope before enabling it again. Stopping the loop does not cancel an in-flight check or existing task retries.My workflow instructions are missing
My workflow instructions are missing
Check the file on the executing computer, its location, and whether a higher-priority candidate exists. Inspect the manual Start task prompt and look for a template warning in the daemon logs.Remove unsupported variables and syntax. An optional template failure can fall back to ordinary task context, so the agent running is not proof that the workflow instructions were included.
A YAML mistake did not stop the task
A YAML mistake did not stop the task
Invalid YAML can fall back to defaults while retaining the Markdown body. An unclosed frontmatter block can be treated as prompt text. The loader is not a strict configuration validation gate.Correct the file and inspect effective behavior before using it for unattended work. Do not use malformed or omitted settings as a way to disable automation.
A hook fails or times out
A hook fails or times out
Check the command, executable availability, task checkout contents, and daemon hook log. Fix the prerequisite before deliberately retrying;
before_run failure does not itself queue the same automatic retry as an agent failure.A timeout requests termination of the hook process. If it launched another service, inspect that service separately. Keep hooks repeatable and avoid assuming interruption undoes their effects.I edited the file, but an existing task uses the old instructions
I edited the file, but an existing task uses the old instructions
Check the conversation’s accepted goal and retained prompt. Workflow reload does not rewrite them. Use an explicit follow-up or the goal’s edit controls when you intend to change work already underway.Do not clear the workspace just to refresh instructions; clearing can delete its uncommitted files.