Writing a clonable task

A task in the Catalog runs in enterprises its author has never seen. A clone keeps the original's definition and cannot be edited, so whatever its author wrote into it, every clone runs as written. These rules are what a task needs to work there, whether a person or an agent writes it, and each one comes with an example of the mistake it prevents. The checklist at the end is the same rules as questions, for whoever reviews the task before it is published.

This page is for anyone who writes a task to publish to the Catalog, and for whoever reviews one. It builds on the reference pages and does not repeat them: Tasks for what a task is made of and how to make one, Handoffs for outcomes and successors, Memory, Gates and tool scopes, and Spend and models. The full list of operations the OS gives a task, with the exact name of each, is Built-in tools.

Rules

Nine rules, in the order a reviewer checks them.

Name no enterprise, person, domain, repository, path or date

A task names none of these: an enterprise, a person, a domain, a repository, a file path or a fixed date. Each is true in its author's enterprise and wrong in every clone. Write the part a thing plays instead: "the repository in the repo input", "the person who approves releases", "the day the run starts". Where the run needs the actual value, the next rule says where it comes from.

This holds in every part a clone takes: the goal, the success metric, the guardrails, the skill, the inputs' labels and defaults, the values a tool is narrowed to, and the successors.

Mistake: A release-notes task's skill says "Read the pull requests merged in acme/web, save the notes to /srv/acme/notes/, and send them to [email protected] before 1 March 2027." In a clone, every one of those is somebody else's repository, folder, colleague and deadline.

Read what varies from memory or an input

Whatever an enterprise must be able to change, the task reads when it runs. It is never written into the skill: who approves, which repository, the voice it writes in, a threshold, a sign-off. There are two places for it:

• An input, for what changes from run to run, or what whoever starts the run knows: the repository, the issue, the customer. Give it a label that says what to put in, and a default only when any enterprise could use it. See Inputs.
• Memory, for what the enterprise knows and keeps: its voice, its approvers, its working days. The skill asks for it, and says what to do when memory has no answer yet. The next rule covers both.

A clone cannot be edited, so a value written into the skill can only be changed by the task's author, in a new version every clone would have to take.

Mistake: A support-reply task's skill says "Sign every reply 'The Acme team' and offer 10% off a late order." Every enterprise that clones it signs as Acme and gives away a discount it never chose. The sign-off and the discount belong in each enterprise's own memory.

State what it reads from memory and what it writes

Each task says, in its skill, what it asks memory for and what it trains back, so a reviewer can see both without running it. A clone brings no memory with it, so the skill also says what a run does when memory.ask answers insufficient_evidence: every first run in a new enterprise does.

What the task writes follows three rules:

• Facts and outcomes only. Train what the run established, or how the work ended: "the customer accepted the refund on the second reply". Never its reasoning, a draft, or what memory just told it.
• One note per outcome. One claim, in a sentence that still means something to a run with none of this one's context. Two outcomes are two notes.
• A correction replaces the note it corrects. When a note is wrong, train a correction that names the note it supersedes, never a second note beside it.

The task lists memory.ask and memory.train among its tools. A run writes only its own task's notes, and a clone does too. See Memory.

Every run also consults memory before it starts and records what it learned when it finishes, without the task asking (see Before and after every run). The skill does not repeat those steps: what it states is the questions it asks with memory.ask and the notes it trains with memory.train.

Mistake: A task that chases unpaid invoices trains "Checked memory, found nothing, drafted a reminder, decided to wait, sent it Friday, customer paid Monday" after a run. One note carries five claims and the run's reasoning, so a later run asking when this customer pays reads a story, and the wrong half of it cannot be corrected alone.

Put a gate on every tool that acts outside the OS

Every tool that sends, publishes, spends or changes something outside the OS has a gate: a mail, a post, a payment, a comment, a merge, a record in another system. Reads need none. A gate on a workspace.* or memory.* tool is saved but never waits: a workspace pushes only to a branch that is not the default one, and the gate that counts is on the merge (see Workspaces). A clone keeps the gates of the task it was cloned from, and cannot change them, so a gate missing from the original is missing in every enterprise that takes it. See Gates and tool scopes.

Mistake: A task that answers customer mail holds os.mail_reply and was saved with gates: [], because its author had read every draft by hand for a month. In each clone, its first reply reaches a customer before anyone in that enterprise has read a draft.

Name its tools exactly

List each tool the task calls by its exact name, github.add_issue_comment rather than github, and nothing it does not call. In the portal's tool picker that is Choose actions, not Add toolset. Use the same names in the skill, so the model calls what the task holds: a run that calls a tool its task does not list fails. A whole vendor reaches every tool that vendor offers, the ones that write included, in every enterprise that connects it. Tool scopes says how to narrow a tool to some of its values.

Mistake: A triage task lists github so that its skill can "use GitHub as needed". That reaches github.merge_pull_request too, so the version is refused until it declares a merge gate, and once it does, every clone holds a merge the task never needed.

Name its outcomes and where each leads

List every outcome the skill can end on, by the exact word it ends with, and the successor each one leads to, or that it leads nowhere because the work is done. An outcome no rule routes is a dead end: the run stops there, and the work is listed on Blockers. A clone looks for each successor by its slug in its own enterprise, and Successors names it by that slug alone. So say which task each slug is in the skill, where it lists the outcomes it ends on: beside each outcome, the successor's slug and one line on what that task does, such as "needs_changes leads to fix-review-findings, a task that fixes what a review found". That is where a reviewer reads it, and where an enterprise that clones the task learns which task it needs under that slug. See Named outcomes.

Mistake: A review task's skill ends {"outcome":"needs_review"} when it is unsure, but its only successor rule is on needs_changes. Every unsure review stops as a dead end in every enterprise that cloned it, and nobody hears of it until someone reads Blockers.

State its finish

Say which outcomes finish the work, in Finishes the work on (finishesOn), and have the skill end on exactly those words when the work is done. A task that can also stop without finishing, waiting on someone, ends on a different outcome for that. See Finished work.

Mistake: A task that closes resolved support tickets leaves Finishes the work on empty. Every ticket it closes stays listed on Waiting in every clone, until someone there marks it finished by hand.

State its KPIs

Say how anyone would know the task works: its success metric, as a number any enterprise that clones it can count, such as the share of replies sent within a working day, or of issues labelled without a person correcting the label. A metric only its author's enterprise can read, or a target set for its author's business, tells a clone nothing. Where a run can count it, a KPI can name the task as its source, and once a person signs that KPI off, the task's runs record its readings with os.record_kpi_reading. See Teams and charters for how KPIs are kept.

Mistake: An onboarding task's success metric reads "new starters are happy". No run can count that and no person can record a reading of it, so nobody in a clone can tell a month it worked from a month it did not.

Choose a model tier, and say what the cheapest cannot do

Give the task a highest model tier, not an exact model. Each tier stands for a model on every provider, while an exact model may not be one the cloning enterprise's connection offers, and the run then uses the closest one it does. Start at economical, the cheapest. Choose mid or frontier only when you can say what the cheapest tier cannot do for this task, such as following a long skill without skipping a step, and write that reason at the top of the skill, where a reviewer reads it. Every clone runs up to the tier you choose, or lower where the cloning enterprise's caps set a lower tier, and pays for it. See Model tiers.

Mistake: A task that sorts receipts into expense categories is set to frontier because its first draft failed on economical. The draft failed because the skill never said what the categories were, which no tier can guess. Once it reads them from memory the cheapest tier sorts them, but every clone still runs a frontier model to do it.

Checklist

Run it against the task's current version before you publish it to the Catalog. Every answer should be yes; a no is a change to make first.

1. Are the goal, success metric, guardrails, skill, inputs, tools and successors free of any enterprise, person, domain or repository name?
2. Are they also free of file paths and fixed dates?
3. Is every value an enterprise would change read from an input or from memory, and never written into the skill?
4. Does each input have a label that says what to put in, and a default only where any enterprise could use it?
5. Does the skill say what it asks memory for, and what it does when memory has no answer?
6. Does the skill say what it trains to memory, as facts and outcomes only, one note per outcome?
7. Does the skill correct a wrong note with a correction that replaces it, never a second note beside it?
8. Does every tool that sends, publishes, spends or changes something outside the OS have a gate?
9. Is every tool listed by its exact name, with no whole vendor and nothing the skill does not call?
10. Does the skill call its tools by the names the task lists?
11. Does every outcome the skill can end on lead to a successor rule, or end the work on purpose?
12. Does the skill name each successor's slug beside the outcome that leads to it, with a line on what that task does?
13. Does Finishes the work on list every outcome that ends the work?
14. Is the success metric a number any enterprise that clones the task can count?
15. Does the task name a model tier rather than an exact model?
16. If that tier is above economical, does the skill say what the cheapest tier cannot do for it?