Instructions & categories

Standing guidance a step hands its agent, written once, and categories to group it in its libraries.

An instruction is standing guidance for a step's agent, written once: a name, an icon and colour, and above all a prompt that becomes part of the agent's system prompt. Attach one to a step and every workflow in the project gets the same review rules, the same test bar, the same hands-off list — and the transcript shows which ones a step carried.

Defining one

Instructions live in the Instructions library — the dashboard, the desktop app, the Mac app, or a phone — and, like workflows, take Manage workflows to change:

# instruction/security-reviewer.yaml
id: security-reviewer
name: Security Reviewer
icon: shield
color: red
description: Reviews changes for security implications.
prompt: |
  You are a security reviewer. Focus on authentication, authorization,
  injection, and secrets handling. Prefer the smallest safe change.

name and prompt are required; the icon defaults to a person and the colour to grey. The editor has an AI "improve prompt" helper, and the setup wizard offers a starter roster — Engineer, Spec Writer, QA Engineer, Security Reviewer, Technical Writer, and friends — that you can adopt and edit.

Using one

- type: prompt
  prompt: Review the diff for security issues and fix what you find.
  instructions: [security-reviewer]

The instruction's prompt becomes part of the step's system prompt. The full layering, outermost first: the shared memory the project receives, the project's memory, the workflow's base prompt, then the step's instructions. The transcript shows all of them, each openable on its own.

An instruction is deliberately not a model choice — pick models per step or per workflow in Agents & models.

More than one

A step can carry several instructions, and often should. A step regularly needs the frontend conventions and the house review rules, and writing a third instruction that repeats both is how a library stops being reusable.

- type: prompt
  prompt: Build the settings screen, then review your own diff.
  instructions: [frontend-engineer, security-reviewer]

They layer in the order you list them, and the run badges the step with each of them. A persona can carry instructions too: they ride on every prompt step it runs, after its own guidance.

Categories

Workflows, instructions, and triggers can each be grouped into categories. They are optional and invisible until you create one — no headers, no "Uncategorized" bucket, nothing to configure in a fresh project.

• Create, rename, delete from the library's header. Deleting a category leaves its members in place, just unfiled.
• Filing is drag and drop — drop a row on a group header to file it, drag past the last group to unfile. On a phone, use the row's "Move to category…" menu.
• Pickers follow along. Anywhere you choose a workflow or instruction, categories render as submenus, with unfiled items last.
• Searching flattens the list. A category's name matches all its members. An item belongs to at most one category.

Categories are per project: each project's workflows and instructions have their own, and a picked shared item shows under the category its shared project gave it.