Workflows

A workflow is a saved template of steps that Keyoku learned from your activity (or that you approved by hand). Suggest, approve, execute — with pause points wherever judgment is required.

From suggestion to template

workflow_suggest mines ~/.keyoku/activity.jsonl for sequences of 2–6 steps that occurred at least 3 times (configurable via min_count) and contain at least one action step — a file change, git mutation, non-inspection command, or connector call. Run-specific values like commit messages, quoted strings, hex hashes, and absolute paths are normalized away first, and sub-sequences collapse into the longest repeated chain. You rarely have to call it: the server tracks pattern ripeness in the background and nudges your agent when a sequence crosses threshold.

Don't want to wait for three repetitions? workflow_capture is "save what I just did" — the last N actions of the current session become a reviewable draft. Detection needs 3×; capture needs you vouching once.

workflow_approve saves the result as a template with a slug, name, description, and steps — and publishes it as an MCP prompt, a native slash command in Claude Code (alongside a static keyoku-catalog prompt listing everything saved). If an SLM is configured, the model parameterizes run-specific values with {{placeholders}} before you approve; with no key, your coding agent is instructed to do the same refinement. Later, workflow_update edits a template in place and its slash command refreshes.

Step types

Type	Fields	Behavior
`bash`	`command, cwd?`	Runs a shell command. cwd defaults to the server's working directory. 30-second timeout (SIGTERM, then SIGKILL). Output is captured and truncated to 2000 characters.
`mcp_call`	`connector, tool, args`	Calls a tool on a registered connector. Gated by the connector's autonomy level exactly like a direct connector_call — at the approve level, the step pauses the execution and queues an approval request; at observe, the step fails.
`agent_prompt`	`—`	Pauses and returns a prompt to the coding agent. The agent does the work, then resumes via execution_complete with { id, step_index, result }.
`human_review`	`—`	Pauses the execution for explicit human sign-off before anything else runs.

Example template

{
  "slug": "patch-release",
  "name": "Patch release",
  "description": "Test, bump, and gate a patch release on sign-off.",
  "steps": [
    { "type": "bash", "command": "npm test" },
    { "type": "bash", "command": "npm version {{bump}}" },
    { "type": "human_review" }
  ]
}

Executions

workflow_execute runs a template, with params filling {{placeholders}} — it refuses to run with missing params and lists them. Executions persist step-by-step to ~/.keyoku/executions.json, so a paused execution survives across sessions. When a step pauses — agent_prompt, human_review, or an approval-gated mcp_call — resume it with execution_complete, which enforces in-order step completion, or stop it with execution_cancel. execution_list shows history, and each template's timesRun increments per completed run. At 5, 10, and 25 runs, Keyoku hints that the workflow is worth baking.

Baking workflows

Once a workflow proves itself, bake it into the repo so it travels with the code:

# Bake as a Claude Code skill
keyoku export <slug>            # → .claude/skills/<slug>/SKILL.md
                                #   provenance header + run instructions

# Bake for Codex (and any AGENTS.md-aware agent)
keyoku export <slug> --agents-md [file]
# → managed block in AGENTS.md (<!-- keyoku:workflows -->),
#   slug-keyed — re-export updates it in place

Tool reference

Tool	Purpose
`workflow_suggest`	Mine the activity trace for repeated patterns and propose workflow drafts
`workflow_capture`	Save what you just did — the last N session actions become a reviewable draft, no repetition needed
`workflow_approve`	Save a draft as a template (slug, name, description, steps) — published as a native slash command
`workflow_update`	Edit an approved template in place; its slash command refreshes
`workflow_execute`	Run a template step by step, with params filling {{placeholders}}
`execution_complete`	Resume a paused step with its result — in-order completion is enforced
`execution_cancel`	Stop a running or paused execution
`execution_list`	Show execution history
`workflow_template_list`	List saved templates
`workflow_template_delete`	Delete a template

A note on trust

Approval is the trust boundary: approved templates execute shell commands with your user privileges. Review templates the way you would review a shell script. See Security for the full model.

How it works — the mining rules in detail
Connectors — what mcp_call steps can reach
MCP Tools — the full 36-tool surface